Speed up Reader first paint

server/test/trace-window.test.mjs

@@ -44,6 +44,19 @@ assert.equal(tail.firstTs, 0);
 assert.equal(tail.usage, null);
 assert.equal(tail.total, null);
 
+// The reader's FIRST paint asks for a strict, small floor. A sparse tail must
+// stop as soon as it has enough to render instead of growing to the ordinary
+// twelve-message page and putting megabytes in front of the first pixel.
+const sparse = path.join(TMP, 'sparse.jsonl');
+fs.writeFileSync(sparse, `${Array.from({ length: 20 }, (_, i) => claudeLine(i, 50_000)).join('\n')}\n`);
+const firstPaint = await readTraceByPath(sparse, { window: { at: 'tail', bytes: 32 * 1024, min: 2 } });
+const ordinary = await readTraceByPath(sparse, { window: { at: 'tail', bytes: 32 * 1024 } });
+assert.ok(firstPaint.turns.length >= 2, 'the strict tail still has enough messages to paint');
+assert.ok(firstPaint.turns.length < ordinary.turns.length,
+  `the first paint stops before an ordinary page (${firstPaint.turns.length} vs ${ordinary.turns.length})`);
+assert.ok(firstPaint.window.end - firstPaint.window.start < ordinary.window.end - ordinary.window.start,
+  'the strict tail reads a smaller byte range');
+
 // ---- paging back reproduces the conversation exactly ----
 let page = tail;
 let stitched = [];

web/package.json

@@ -13,7 +13,7 @@
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
     "typecheck": "tsc --noEmit",
-    "test": "node test/exchanges.test.mjs && node test/sessionTitle.test.mjs && node test/overviewSort.test.mjs && node test/drafts.test.mjs",
+    "test": "node test/exchanges.test.mjs && node test/sessionTitle.test.mjs && node test/overviewSort.test.mjs && node test/drafts.test.mjs && node test/traceWindows.test.mjs",
     "preview": "vite preview"
   },
   "dependencies": {

web/src/App.tsx

@@ -120,8 +120,20 @@ export default function App() {
   // How every pane is read — the terminal itself, or reader mode over the same
   // session. App-wide, like zoom, and remembered the same way.
   const [paneMode, setPaneMode] = useState(readPaneMode);
-  useEffect(() => onPaneMode(setPaneMode), []);
-  const showPaneMode = (m: 'terminal' | 'reader') => { setPaneMode(m); writePaneMode(m); };
+  // Which visible batch has let its focused reader paint. Reset before entering
+  // reader mode; a batch key below also prevents readiness leaking across pages.
+  const [readerReadyFor, setReaderReadyFor] = useState('');
+  const paneModeRef = useRef(paneMode);
+  paneModeRef.current = paneMode;
+  useEffect(() => onPaneMode((m) => {
+    if (m === 'reader' && paneModeRef.current !== 'reader') setReaderReadyFor('');
+    paneModeRef.current = m;
+    setPaneMode(m);
+  }), []);
+  const showPaneMode = (m: 'terminal' | 'reader') => {
+    if (m === 'reader' && paneMode !== 'reader') setReaderReadyFor('');
+    setPaneMode(m); writePaneMode(m);
+  };
   const [zoom, setZoom] = useState<number>(() => {
     const z = parseInt(localStorage.getItem('am-zoom') || '100', 10);
     return Number.isFinite(z) ? z : 100;
@@ -515,6 +527,13 @@ export default function App() {
     .filter((s) => !isPassive(s.cli) && !isRemote(s.cli))
     .map((s) => s.id);
   const visibleTerminalKey = visibleTerminalIds.join(',');
+  const readerLeadId = focusedId && visibleTerminalIds.includes(focusedId)
+    ? focusedId : visibleTerminalIds[0] || null;
+  // Focus can move after the batch is ready; that must not tear down and
+  // re-fetch every sibling reader. A different visible page/group is a new
+  // batch, while focus only chooses which member gets its critical path.
+  const readerBatch = visibleTerminalKey;
+  const readerFollowersReady = readerReadyFor === readerBatch;
   const sessionIdsKey = tree.sessions.map((s) => s.id).join(',');
   const [warmTerminalIds, setWarmTerminalIds] = useState<string[]>([]);
   useEffect(() => {
@@ -807,6 +826,9 @@ export default function App() {
                 theme={theme}
                 zoom={zoom}
                 mode={paneMode}
+                readerEnabled={shown && deckVisible && (id === readerLeadId || readerFollowersReady)}
+                onReaderReady={id === readerLeadId ? () => setReaderReadyFor(readerBatch) : undefined}
+                readerReadyKey={readerBatch}
                 groupName={groupNameOf[s.id]}
                 focused={shown && sessions.length > 1 && s.id === focusedId}
                 visible={shown && deckVisible}

web/src/api.ts

@@ -451,14 +451,17 @@ const traceFetch = async <T>(url: string): Promise<T> => {
   return r.json();
 };
 
-export const getTraceWindow = (id: string, req: TraceReq, bytes?: number): Promise<TraceWindow> =>
-  traceFetch(`/api/trace/${id}?${traceRange(req)}${bytes ? `&bytes=${bytes}` : ''}`);
+const windowSize = (bytes?: number, min?: number) =>
+  `${bytes ? `&bytes=${bytes}` : ''}${min ? `&min=${min}` : ''}`;
+
+export const getTraceWindow = (id: string, req: TraceReq, bytes?: number, min?: number): Promise<TraceWindow> =>
+  traceFetch(`/api/trace/${id}?${traceRange(req)}${windowSize(bytes, min)}`);
 
 export const getTraceSummary = (id: string): Promise<TraceSummary> =>
   traceFetch(`/api/trace/${id}?summary=1`);
 
-export const getFileTraceWindow = (id: string, p: string, req: TraceReq, bytes?: number): Promise<TraceWindow> =>
-  traceFetch(`/api/files/${id}/trace?path=${encodeURIComponent(p)}&${traceRange(req)}${bytes ? `&bytes=${bytes}` : ''}`);
+export const getFileTraceWindow = (id: string, p: string, req: TraceReq, bytes?: number, min?: number): Promise<TraceWindow> =>
+  traceFetch(`/api/files/${id}/trace?path=${encodeURIComponent(p)}&${traceRange(req)}${windowSize(bytes, min)}`);
 
 export const getFileTraceSummary = (id: string, p: string): Promise<TraceSummary> =>
   traceFetch(`/api/files/${id}/trace?path=${encodeURIComponent(p)}&summary=1`);

web/src/components/FilesPane.tsx

@@ -766,7 +766,7 @@ function FileView({ sessionId, path, zoom, raw, scripts, onInfo, onSaved }: {
   // The reader opens on the tail of the transcript and pages backwards from
   // there; the summary is the one call that reads all of it.
   const traceSrc = useMemo<TraceSource>(() => ({
-    window: (req, bytes) => api.getFileTraceWindow(sessionId, path, req, bytes),
+    window: (req, bytes, min) => api.getFileTraceWindow(sessionId, path, req, bytes, min),
     summary: () => api.getFileTraceSummary(sessionId, path),
   }), [sessionId, path]);
 

web/src/components/TerminalPane.tsx

@@ -181,7 +181,8 @@ if (typeof window !== 'undefined') {
 }
 
 export default function TerminalPane({
-  session, cli, theme, focused, visible, active, zoom = 100, mode = 'terminal', dragId, isMobile, groupName, onDragActive, onFocus, onRename, onClose,
+  session, cli, theme, focused, visible, active, zoom = 100, mode = 'terminal', readerEnabled,
+  readerReadyKey, onReaderReady, dragId, isMobile, groupName, onDragActive, onFocus, onRename, onClose,
 }: {
   session: Session;
   cli?: Cli;
@@ -192,6 +193,9 @@ export default function TerminalPane({
   active?: boolean;
   zoom?: number;
   mode?: PaneMode;          // app-wide reading mode, from the bottom bar
+  readerEnabled?: boolean;  // focused reader paints before visible followers
+  readerReadyKey?: string;  // visible batch whose first paint is being awaited
+  onReaderReady?: () => void;
   dragId?: string;          // set when the pane can be rearranged (group view)
   isMobile?: boolean;       // show the on-screen control-key bar
   onDragActive?: (dragging: boolean) => void;
@@ -892,9 +896,11 @@ export default function TerminalPane({
         {/* Reader mode draws OVER the terminal rather than replacing it: xterm needs
             layout to fit, and detaching tmux costs a repaint and can trip the
             handoff path. The terminal stays mounted and connected underneath. */}
-        {reading && (
+        {reading && visible !== false && (
           <div className="pane-reader" onMouseDown={(e) => e.stopPropagation()}>
-            <ConversationView session={session} paused={visible === false} isMobile={isMobile} />
+            {readerEnabled === false
+              ? <div className="cxv-empty mono">reading the trace…</div>
+              : <ConversationView session={session} isMobile={isMobile} onReady={onReaderReady} readyKey={readerReadyKey} />}
           </div>
         )}
       </div>

web/src/components/TracePane.tsx

@@ -586,7 +586,7 @@ export default function TracePane({
   const nav = useRef<((dir: -1 | 1) => void) | null>(null);
   const onNav = useCallback((go: (dir: -1 | 1) => void) => { nav.current = go; }, []);
   const src = useMemo<TraceSource>(() => ({
-    window: (req, bytes) => api.getTraceWindow(session.id, req, bytes),
+    window: (req, bytes, min) => api.getTraceWindow(session.id, req, bytes, min),
     summary: () => api.getTraceSummary(session.id),
   }), [session.id]);
 

web/src/components/conversation/ConversationView.tsx

@@ -30,7 +30,7 @@ const fmtNum = (n: number) => n.toLocaleString();
 const fmtUsage = (u?: { in: number; out: number } | null) =>
   (u ? `${fmtTok(u.in)}↓ ${fmtTok(u.out)}↑` : '');
 
-export default function ConversationView({ session, paused, isMobile, readOnly, onHandover }: {
+export default function ConversationView({ session, paused, isMobile, readOnly, onHandover, onReady, readyKey }: {
   session: Session;
   /** The pane is off-screen: stop asking the server for a trace nobody sees. */
   paused?: boolean;
@@ -38,6 +38,10 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
   /** A trace with no agent behind it — a shared file, an import. Read-only. */
   readOnly?: boolean;
   onHandover?: () => void;
+  /** Called after the first tail page (or its terminal error) has painted. */
+  onReady?: () => void;
+  /** The visible batch this paint should release. */
+  readyKey?: string;
 }) {
   const [query, setQuery] = useState('');
   const [hits, setHits] = useState(0);
@@ -62,7 +66,7 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
   const live = session.state === 'working' && !paused;
 
   const src = useMemo<TraceSource>(() => ({
-    window: (req, bytes) => api.getTraceWindow(session.id, req, bytes),
+    window: (req, bytes, min) => api.getTraceWindow(session.id, req, bytes, min),
     summary: () => api.getTraceSummary(session.id),
   }), [session.id]);
 
@@ -96,6 +100,20 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
   const exchanges = useMemo(() => splitExchanges(turns), [version, turns]); // eslint-disable-line react-hooks/exhaustive-deps
   const last = exchanges[exchanges.length - 1];
 
+  // Group reader mode gives the focused pane the critical path. Its siblings
+  // wait for this signal before mounting their own readers, so one click cannot
+  // turn twelve retained panes into twelve competing tail reads. useEffect runs
+  // after the head/error render commits: this is a paint barrier, not a timer.
+  const readySentFor = useRef('');
+  const ready = useRef(onReady);
+  ready.current = onReady;
+  useEffect(() => {
+    const key = `${session.id}:${readyKey || ''}`;
+    if (readySentFor.current === key || (!head && !error)) return;
+    readySentFor.current = key;
+    ready.current?.();
+  }, [head, error, readyKey, session.id]);
+
   // The optimistic echo stands until the transcript catches up: a CLI writes it,
   // the reader picks it up, the poll lands — seconds, during which a card that
   // showed nothing would read as "did that get lost?".
@@ -200,12 +218,12 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
   const fills = useRef(0);
   useEffect(() => {
     const el = scroller.current;
-    if (!el || !head || atStart || blocked) return;
+    if (paused || !el || !head || atStart || blocked) return;
     if (el.scrollHeight > el.clientHeight) { fills.current = 0; return; }
     if (fills.current >= 2) return;
     fills.current += 1;
     loadOlder();
-  }, [version, head, atStart, blocked, loadOlder]);
+  }, [version, head, atStart, blocked, loadOlder, paused]);
 
   useLayoutEffect(() => {
     const el = scroller.current;

web/src/lib/traceWindows.ts

@@ -21,10 +21,13 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import * as api from '../api';
 import type { TraceCursor, TraceSummary, TraceTurn, TraceWindow } from '../api';
 
-/** How much transcript the first request asks for. Measured on the longest trace
- *  on this box (19 MB / 1,420 turns): 384 KB is ~60 turns, ~84 KB of JSON and
- *  ~6 ms of server time, and renders in a frame — the smallest window that still
- *  opens on a complete-looking conversation rather than a stub. */
+/** The first paint is deliberately smaller than an ordinary page. A turn floor
+ *  made a nominal 384 KB tail grow to 1.5 MB / 737 KB of JSON on a real Codex
+ *  trace before the reader could show anything. Two messages are enough to paint
+ *  the latest exchange; the host can fill above it after that first paint. */
+export const INITIAL_WINDOW_BYTES = 128 * 1024;
+export const INITIAL_WINDOW_TURNS = 2;
+/** Once something is on screen, larger pages make scrolling back efficient. */
 export const WINDOW_BYTES = 384 * 1024;
 // Following a trace that is still being written. Nothing in here knows whether
 // an agent is running — but a transcript whose newest turn is seconds old is one
@@ -36,7 +39,7 @@ const FRESH_MS = 120_000;
 const SUMMARY_DELAY_MS = 400; // let the first paint happen before the whole-file read
 
 export interface TraceSource {
-  window: (req: api.TraceReq, bytes?: number) => Promise<TraceWindow>;
+  window: (req: api.TraceReq, bytes?: number, min?: number) => Promise<TraceWindow>;
   summary: () => Promise<TraceSummary>;
 }
 
@@ -112,10 +115,13 @@ export function useTraceWindows(src: TraceSource, srcKey: string, opts: {
   cb.current = opts;
 
   const loadTail = useCallback(async () => {
+    if (cb.current.paused) return;
     loading.current = true;
     const mine = gen.current;
     try {
-      const { turns: got, window: win, ...m } = await src.window({ at: 'tail' }, WINDOW_BYTES);
+      const { turns: got, window: win, ...m } = await src.window(
+        { at: 'tail' }, INITIAL_WINDOW_BYTES, INITIAL_WINDOW_TURNS,
+      );
       if (mine !== gen.current) return;
       turns.current = got;
       cursor.current = win;
@@ -142,7 +148,7 @@ export function useTraceWindows(src: TraceSource, srcKey: string, opts: {
   /** Fetch the window before the oldest turn held. Returns how many arrived. */
   const loadOlder = useCallback(async () => {
     const cur = cursor.current;
-    if (loading.current || !cur || cur.atStart || cur.blocked) return 0;
+    if (cb.current.paused || loading.current || !cur || cur.atStart || cur.blocked) return 0;
     loading.current = true;
     const mine = gen.current;
     try {
@@ -184,7 +190,7 @@ export function useTraceWindows(src: TraceSource, srcKey: string, opts: {
   /** Whatever the agent has written since we last looked. */
   const loadNewer = useCallback(async () => {
     const cur = cursor.current;
-    if (loading.current || !cur) return 0;
+    if (cb.current.paused || loading.current || !cur) return 0;
     loading.current = true;
     const mine = gen.current;
     try {
@@ -215,6 +221,8 @@ export function useTraceWindows(src: TraceSource, srcKey: string, opts: {
     }
   }, [src, bump]);
 
+  const paused = !!opts.paused;
+
   useEffect(() => {
     gen.current += 1;
     loading.current = false;
@@ -224,8 +232,8 @@ export function useTraceWindows(src: TraceSource, srcKey: string, opts: {
     setMeta(null);
     setSummary(null);
     setError(null);
-    loadTail();
-  }, [srcKey, loadTail]);
+    if (!paused) loadTail();
+  }, [srcKey, loadTail, paused]);
 
   // The one read that touches the whole file, fired AFTER the first paint: it
   // buys the header a real turn count, the session's token total, the date the
@@ -233,12 +241,17 @@ export function useTraceWindows(src: TraceSource, srcKey: string, opts: {
   // a window can know. If it fails or is slow, the header simply says how much
   // is loaded.
   useEffect(() => {
+    // `meta` is set by the tail response and this effect runs after that render
+    // commits. Starting the clock on mount let a slow tail lose a race to every
+    // pane's full-file summary — exactly the work the delay meant to keep away
+    // from first paint. A paused/hidden reader does no summary work at all.
+    if (paused || !meta || summary) return undefined;
     let dead = false;
     const h = window.setTimeout(() => {
       src.summary().then((s) => { if (!dead) setSummary(s); }).catch(() => {});
     }, SUMMARY_DELAY_MS);
     return () => { dead = true; window.clearTimeout(h); };
-  }, [src, srcKey]);
+  }, [src, srcKey, paused, meta, summary]);
 
   // The transcript may still be being written — see LIVE_MS above. Except when
   // "a window" costs a whole-file read: the SQLite harnesses have no byte
@@ -246,7 +259,6 @@ export function useTraceWindows(src: TraceSource, srcKey: string, opts: {
   // evict the Overview's memo doing it). They are not polled at all.
   const lastTs = meta ? meta.lastTs : 0;
   const seekable = cursor.current ? cursor.current.mode === 'bytes' : true;
-  const paused = !!opts.paused;
   const live = opts.live;
   const [hidden, setHidden] = useState(() => (typeof document === 'undefined' ? false : document.hidden));
   useEffect(() => {

web/test/traceWindows.test.mjs

@@ -0,0 +1,124 @@
+// Critical-path scheduling for the windowed reader, in a real React/browser
+// lifecycle: hidden readers stay silent, the first request is deliberately
+// small, and the whole-file summary clock starts only after the tail paints.
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import { chromium } from 'playwright';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trace-windows-web-'));
+const bundle = path.join(tmp, 'harness.js');
+
+await build({
+  stdin: {
+    resolveDir: path.join(HERE, '..'),
+    loader: 'tsx',
+    contents: `
+      import React, { useEffect } from 'react';
+      import { createRoot } from 'react-dom/client';
+      import { useTraceWindows } from './src/lib/traceWindows.ts';
+
+      const calls = [];
+      const tails = [];
+      const source = {
+        window(req, bytes, min) {
+          calls.push({ kind: 'window', req, bytes, min, at: performance.now() });
+          return new Promise((resolve) => tails.push(resolve));
+        },
+        async summary() {
+          calls.push({ kind: 'summary', at: performance.now() });
+          return { total: 2, userTurns: [0] };
+        },
+      };
+
+      function Probe({ paused }) {
+        const { head } = useTraceWindows(source, 'session-a', { paused, live: false });
+        useEffect(() => { window.__traceHead = head; }, [head]);
+        return <div id="head">{head ? String(head.loaded) : ''}</div>;
+      }
+
+      const root = createRoot(document.getElementById('root'));
+      let paused = true;
+      const render = () => root.render(<Probe paused={paused} />);
+      window.__traceHarness = {
+        calls,
+        setPaused(next) { paused = next; render(); },
+        resolveTail() {
+          tails.shift()?.({
+            harness: 'claude', harnessLabel: 'Claude Code', sessionId: 's',
+            title: '', model: null, cwd: null, firstTs: 0, lastTs: Date.now(),
+            usage: null, source: null, sharedBy: null, note: null, truncated: false,
+            total: null, userTurns: null,
+            turns: [
+              { role: 'user', ts: 1, blocks: [{ type: 'text', text: 'ask' }] },
+              { role: 'assistant', ts: 2, blocks: [{ type: 'text', text: 'answer' }] },
+            ],
+            window: { mode: 'bytes', start: 10, end: 20, atStart: false, atEnd: true },
+          });
+        },
+      };
+      render();
+    `,
+  },
+  outfile: bundle,
+  bundle: true,
+  format: 'iife',
+  platform: 'browser',
+  logLevel: 'error',
+});
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// CI normally uses Playwright's matching download. The development Space keeps
+// a shared Chromium revision instead, so allow that executable to be supplied
+// without baking an environment-specific path into the test.
+const browser = await chromium.launch({
+  headless: true,
+  executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
+});
+try {
+  const page = await browser.newPage();
+  await page.setContent('<div id="root"></div>');
+  await page.addScriptTag({ path: bundle });
+  await page.waitForFunction(() => !!window.__traceHarness);
+
+  await sleep(100);
+  assert.deepEqual(await page.evaluate(() => window.__traceHarness.calls), [],
+    'a paused reader performs no initial or summary request');
+
+  await page.evaluate(() => window.__traceHarness.setPaused(false));
+  await page.waitForFunction(() => window.__traceHarness.calls.length === 1);
+  const first = await page.evaluate(() => window.__traceHarness.calls[0]);
+  assert.deepEqual(first.req, { at: 'tail' });
+  assert.equal(first.bytes, 128 * 1024, 'the first byte window is strict and small');
+  assert.equal(first.min, 2, 'the first window stops after one displayable exchange');
+
+  // The old mount-based timer would have fired by now even though no tail page
+  // exists. The summary must not compete with the request that removes loading.
+  await sleep(500);
+  assert.equal(await page.evaluate(() => window.__traceHarness.calls.filter((c) => c.kind === 'summary').length), 0,
+    'the summary clock has not started while the tail is pending');
+
+  const resolvedAt = Date.now();
+  await page.evaluate(() => window.__traceHarness.resolveTail());
+  await page.waitForFunction(() => document.getElementById('head').textContent === '2');
+  await sleep(250);
+  assert.equal(await page.evaluate(() => window.__traceHarness.calls.filter((c) => c.kind === 'summary').length), 0,
+    'the summary remains deferred after the first page paints');
+  await page.waitForFunction(() => window.__traceHarness.calls.some((c) => c.kind === 'summary'), { timeout: 1500 });
+  assert.ok(Date.now() - resolvedAt >= 350, 'the delay is measured from the painted tail, not mount');
+
+  const beforePause = await page.evaluate(() => window.__traceHarness.calls.length);
+  await page.evaluate(() => window.__traceHarness.setPaused(true));
+  await sleep(500);
+  assert.equal(await page.evaluate(() => window.__traceHarness.calls.length), beforePause,
+    'pausing an already-mounted reader starts no further work');
+} finally {
+  await browser.close();
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log('trace-windows: ok');