Render without attribution until build resolves

Yield before the first chunk so cold start doesn't block the initial
paint, and clear stale source on file switch so prior attribution
doesn't flash against the new file's AST on re-navigation.

Author: shikokuchuo

claude-notes/plans/2026-04-15-node-attribution.md

@@ -118,7 +118,7 @@ Minor tweaks to fix build issues under hub-client's stricter TypeScript config:
 
 8. **Run-length encoding as the default producer** (`3265de11`) — Automerge history is replayed into a sorted `AttributionRun[]` rather than a per-char `CharAttribution[]`. Realistic batched workloads see 4× faster updates, 5× faster queries, 20× smaller storage, and arbitrary-size bulk inserts don't need the splice-chunking workaround. Numbers below.
 
-9. **Cold-start latency tuning** (`d880d643`) — Two small, unambiguous changes to `buildRunListAttribution` / `waitForIdle`: (a) skip the `await waitForIdle()` before the *first* chunk so attribution work begins immediately, and (b) pass `{ timeout: 100 }` to `requestIdleCallback` so the build isn't starved when React is still mounting. A progressive-rendering variant was tried and reverted — partial runs describe an intermediate text state whose byte positions don't align with the current AST, so intermediate paints could briefly show attribution against the wrong bytes.
+9. **Cold-start latency tuning** — The hook returns `null` until the build resolves, so the document renders with no attribution visible and re-renders once the map is ready. Given that, `buildRunListAttribution` now yields via `waitForIdle()` before *every* chunk including the first, letting the initial paint settle before attribution CPU work begins. `waitForIdle` still passes `{ timeout: 100 }` so subsequent chunks aren't starved during sustained activity. An earlier iteration (`d880d643`) skipped the first yield to reduce time-to-attribution, but that made the first chunk block the post-mount paint — reverted in favour of prioritizing initial load over fast attribution. A progressive-rendering variant was tried and reverted — partial runs describe an intermediate text state whose byte positions don't align with the current AST, so intermediate paints could briefly show attribution against the wrong bytes.
 
 ## Performance results
 

hub-client/src/hooks/useAttribution.test.ts

@@ -225,6 +225,42 @@ describe('useAttribution', () => {
     expect(result.current!.source).toBeDefined();
   });
 
+  it('clears stale source when filePath changes, before new build resolves', async () => {
+    const firstMap = createMockMap();
+    const handle = { __mock: true };
+    mockGetFileHandle.mockReturnValue(handle as any);
+
+    let resolveSecond: (map: RunListAttribution | null) => void;
+    mockBuildRunListAttribution
+      .mockResolvedValueOnce(firstMap)
+      .mockReturnValueOnce(
+        new Promise(resolve => { resolveSecond = resolve as any; })
+      );
+
+    const { result, rerender } = renderHook(
+      ({ path }) => useAttribution(path, 'hello'),
+      { initialProps: { path: 'file1.qmd' } },
+    );
+
+    // Let the first build complete
+    await act(async () => {});
+    expect(result.current).not.toBeNull();
+
+    // Switch to a different file — the second build is still pending
+    rerender({ path: 'file2.qmd' });
+
+    // The stale source from file1 must NOT be visible while file2 is building.
+    // Otherwise the AST of file2 would render briefly attributed against
+    // file1's runs/byteToChar map — visibly jarring on re-navigation.
+    expect(result.current).toBeNull();
+
+    // Complete the second build — attribution reappears.
+    await act(async () => {
+      resolveSecond!(createMockMap({ processedHistoryIndex: 2 }));
+    });
+    expect(result.current).not.toBeNull();
+  });
+
   it('aborts in-flight build on unmount', async () => {
     const handle = { __mock: true };
     mockGetFileHandle.mockReturnValue(handle as any);

hub-client/src/hooks/useAttribution.ts

@@ -74,12 +74,15 @@ export function useAttribution(
     const controller = new AbortController();
     abortRef.current = controller;
 
+    // Clear any stale attribution up-front. Without this, a previous file's
+    // `source` (with its own byteToChar map baked in) briefly renders
+    // against the new file's AST on re-navigation, which flashes colors on
+    // the first block before the new build lands.
+    setResult(null);
+    mapRef.current = null;
+
     const handle = getFileHandle(path);
-    if (!handle) {
-      setResult(null);
-      mapRef.current = null;
-      return;
-    }
+    if (!handle) return;
 
     buildRunListAttribution(handle, 'text', controller.signal).then(map => {
       if (controller.signal.aborted) return;

hub-client/src/services/attribution-runs.test.ts

@@ -242,6 +242,38 @@ describe('buildRunListAttribution', () => {
     expect(result!.runs).toHaveLength(1);
     expect(result!.runs[0]).toEqual({ start: 0, end: N, actor: 'a1', time: 1000 });
   });
+
+  it('yields to the event loop before touching history', async () => {
+    // The hook renders the document without attribution during the build;
+    // the build must yield first so the initial paint isn't blocked by
+    // the first chunk's CPU work.
+    const entries: MockHistoryEntry[] = [{
+      heads: ['h1'], actor: 'a1', time: 1000,
+      patches: [{ action: 'splice', path: ['text', 0], value: 'x' }],
+    }];
+    const handle = createMockHandle(entries);
+    mockDiff.mockImplementation(createMockDiff(entries));
+
+    let idleCalls = 0;
+    let metadataCalledBeforeIdle = false;
+    const originalMetadata = handle.metadata;
+    handle.metadata = vi.fn((hash: string) => {
+      if (idleCalls === 0) metadataCalledBeforeIdle = true;
+      return originalMetadata(hash);
+    });
+
+    // @ts-expect-error -- mock global
+    globalThis.requestIdleCallback = (cb: IdleRequestCallback) => {
+      idleCalls++;
+      cb({ didTimeout: false, timeRemaining: () => 50 } as IdleDeadline);
+      return idleCalls;
+    };
+
+    await buildRunListAttribution(handle as never, 'text');
+
+    expect(idleCalls).toBeGreaterThan(0);
+    expect(metadataCalledBeforeIdle).toBe(false);
+  });
 });
 
 describe('updateRunListAttribution', () => {

hub-client/src/services/attribution-runs.ts

@@ -201,13 +201,12 @@ export async function buildRunListAttribution(
   let lastHeads: unknown[] = [];
 
   for (let chunkStart = 0; chunkStart < history.length; chunkStart += CHUNK_SIZE) {
-    // Skip the yield before the first chunk — the main thread is usually
-    // already busy at cold-start and yielding immediately only adds latency
-    // to time-to-first-paint.
-    if (chunkStart > 0) {
-      await waitForIdle();
-      if (signal?.aborted) return null;
-    }
+    // Yield before every chunk, including the first. The hook returns null
+    // until the build resolves, so nothing about attribution is visible to
+    // the user yet — we can afford to let the document's initial paint
+    // complete on an idle tick before starting CPU work.
+    await waitForIdle();
+    if (signal?.aborted) return null;
 
     const chunkEnd = Math.min(chunkStart + CHUNK_SIZE, history.length);
     for (let i = chunkStart; i < chunkEnd; i++) {