Let the transcript widen its painted window on scroll instead of always tailing

The long-log window called windowSlice with a fixed size and no feedback from
scrollTop, so once history passed the collapse threshold everything before
the last 200 rows was permanently replaced by a collapse marker and could
never be scrolled back to. Widen the window (never shrink) when the operator
scrolls near its top, and preserve their scroll position across the repaint.

Also stop rebuilding the whole window on every appended or replaced row once
windowed: append now adds one node and evicts the oldest only while following
the tail, and replace resolves streaming token updates to a single-node
retext when the row is still in the painted range, instead of tearing down
and repainting the entire window on every token.

Author: TheGreatAxios

src/tui-opentui/shell.ts

@@ -1734,6 +1734,30 @@ type ShellInternals = {
     task: string
     agents: string
   }
+  /**
+   * Live state of the painted transcript window, or null while every row in
+   * `streamLog` has its own node (`mustWindow` false). `size` only grows —
+   * scrolling near the collapsed-history marker widens it so history already
+   * in memory becomes reachable, rather than swapping in a different slice.
+   */
+  transcriptWindow: TranscriptWindowState | null
+  /**
+   * Set right after a scroll-triggered widen, consumed on the next frame once
+   * layout has measured the newly painted rows. Restores `scrollTop` so the
+   * rows the operator was already looking at do not jump.
+   */
+  transcriptScrollRestore: { distanceFromBottom: number } | null
+}
+
+type TranscriptWindowState = {
+  /** Index into `streamLog` of the first painted row. */
+  start: number
+  /** Target row count of the window; append eviction trims back to this. */
+  size: number
+  /** Whether a "N earlier lines collapsed" marker node is currently painted. */
+  hasMarker: boolean
+  /** The marker node itself, so eviction can retext it instead of rebuilding. */
+  markerNode: TextRenderable | null
 }
 
 const internals = new WeakMap<AppShell, ShellInternals>()
@@ -1927,21 +1951,78 @@ function paintAppendStreamRow(shell: AppShell, row: StreamRow): void {
   shell.streamLog.push(row)
   shell.lineCount = shell.streamLog.length
 
+  const index = shell.streamLog.length - 1
+
   // Under collapse threshold: append one paint node (cheap).
-  // Over threshold: rebuild the windowed paint tree only.
   if (!gainedVoice && !mustWindow(shell.streamLog.length)) {
-    const index = shell.streamLog.length - 1
     shell.transcript.add(
       createStreamRowRenderable(shell, row, gapBefore(shell, index), labelBefore(shell, index), index),
     )
     paintChrome(shell)
     return
   }
 
-  repaintTranscriptWindow(shell)
+  // Over threshold: a voice change relabels every already-painted row, so
+  // only that case needs the full rebuild. Otherwise append one node and
+  // trim the oldest — see `appendWindowedRow`.
+  if (gainedVoice) {
+    repaintTranscriptWindow(shell)
+    paintChrome(shell)
+    return
+  }
+
+  appendWindowedRow(shell, row, index)
   paintChrome(shell)
 }
 
+/**
+ * Append one row node to an already-windowed transcript without rebuilding
+ * the rest of the paint tree. Called on every streamed row once history
+ * passes `LONG_LOG_COLLAPSE_THRESHOLD`, so this is the hot path CL-5553
+ * exists to keep cheap: O(1) node churn per row, not O(window).
+ *
+ * Eviction of the oldest painted row only runs while the transcript is
+ * following the tail — an operator scrolled up into history keeps the rows
+ * they are looking at instead of having them trimmed out from under them.
+ */
+function appendWindowedRow(shell: AppShell, row: StreamRow, index: number): void {
+  const bag = internals.get(shell)
+  const win = bag?.transcriptWindow
+  if (bag === undefined || win === undefined || win === null) {
+    // First row to cross the threshold: no window tracked yet, one full build.
+    repaintTranscriptWindow(shell)
+    return
+  }
+
+  shell.transcript.add(
+    createStreamRowRenderable(shell, row, gapBefore(shell, index), labelBefore(shell, index), index),
+  )
+
+  if (!isTranscriptFollowing(shell)) return
+
+  const paintedCount = index + 1 - win.start
+  if (paintedCount <= win.size) return
+
+  const children = transcriptRowChildren(shell)
+  const oldest = children[win.hasMarker ? 1 : 0]
+  if (oldest) {
+    shell.transcript.remove(oldest)
+    destroySubtree(oldest)
+  }
+  win.start += 1
+
+  if (win.hasMarker && win.markerNode) {
+    win.markerNode.content = ` ${collapseMarker(win.start)}`
+  } else {
+    win.hasMarker = true
+    win.markerNode = new TextRenderable(shell.renderer as CliRenderer, {
+      content: ` ${collapseMarker(win.start)}`,
+      fg: UI.textDim,
+    })
+    shell.transcript.add(win.markerNode, 1)
+  }
+}
+
 /** Row count of the log `appendStreamRow` currently targets (parent or observe). */
 export function streamRowCount(shell: AppShell): number {
   return shell.observe !== null && shell.parentStreamLog !== null
@@ -2013,16 +2094,25 @@ export function replaceStreamRowAt(
   if (index < 0 || index >= shell.streamLog.length) return
   shell.streamLog[index] = row
 
+  const win = internals.get(shell)?.transcriptWindow ?? null
+  // Streaming rewrites the same row repeatedly (token by token), so a windowed
+  // transcript still resolves this to a single-node retext when the row is
+  // in the painted range — the case CL-5553 needs cheap, since it is the hot
+  // path. Anything else (row outside the window, or the 1:1 mapping broken by
+  // a raw appendTranscript line) falls back to the full windowed rebuild.
+  const paintedIndex = win !== null ? index - win.start + (win.hasMarker ? 1 : 0) : index
   const children = transcriptRowChildren(shell)
-  // A raw appendTranscript line breaks the 1:1 node↔row mapping; fall back to
-  // the windowed rebuild, which derives every node from the log.
-  if (mustWindow(shell.streamLog.length) || children.length !== shell.streamLog.length) {
+  const outsideWindow = win !== null && (index < win.start || paintedIndex >= children.length)
+  const brokenMapping = win === null && children.length !== shell.streamLog.length
+
+  if (outsideWindow) return
+  if (brokenMapping) {
     repaintTranscriptWindow(shell)
     paintChrome(shell)
     return
   }
 
-  const stale = children[index]
+  const stale = children[paintedIndex]
   if (stale && retextStreamRow(shell, stale, row, labelBefore(shell, index))) {
     paintChrome(shell)
     return
@@ -2035,7 +2125,7 @@ export function replaceStreamRowAt(
   // spacer, not a row (see `transcriptRowChildren`).
   shell.transcript.add(
     createStreamRowRenderable(shell, row, gapBefore(shell, index), labelBefore(shell, index), index),
-    index + 1,
+    paintedIndex + 1,
   )
   paintChrome(shell)
 }
@@ -2117,23 +2207,68 @@ export function repaintTranscriptWindow(shell: AppShell): void {
     destroySubtree(child)
   }
 
-  const win = windowSlice(shell.streamLog, { windowSize: LONG_LOG_WINDOW })
+  const bag = internals.get(shell)
+  // Window size only grows (see `maybeWidenTranscriptWindow`): once an
+  // operator has scrolled back to reach older rows, re-collapsing them would
+  // make the history they just reached unreachable again.
+  const size = bag?.transcriptWindow?.size ?? LONG_LOG_WINDOW
+  const win = windowSlice(shell.streamLog, { windowSize: size })
+
+  let markerNode: TextRenderable | null = null
   if (win.truncatedAbove) {
-    shell.transcript.add(
-      new TextRenderable(shell.renderer as CliRenderer, {
-        content: ` ${collapseMarker(win.start)}`,
-        fg: UI.textDim,
-      }),
-    )
+    markerNode = new TextRenderable(shell.renderer as CliRenderer, {
+      content: ` ${collapseMarker(win.start)}`,
+      fg: UI.textDim,
+    })
+    shell.transcript.add(markerNode)
   }
   win.rows.forEach((row, offset) => {
     const index = win.start + offset
     shell.transcript.add(
       createStreamRowRenderable(shell, row, gapBefore(shell, index), labelBefore(shell, index), index),
     )
   })
+
+  if (bag !== undefined) {
+    bag.transcriptWindow = mustWindow(shell.streamLog.length)
+      ? { start: win.start, size, hasMarker: win.truncatedAbove, markerNode }
+      : null
+  }
+}
+
+/**
+ * Widen the painted window when the operator scrolls near the top of it and
+ * older rows are still collapsed above. Growing from the tail rather than
+ * pinning a historical slice keeps this a plain `windowSlice` call — the
+ * scrollbox's own `scrollTop` already tells us where the operator is.
+ */
+function maybeWidenTranscriptWindow(shell: AppShell): void {
+  const bag = internals.get(shell)
+  const win = bag?.transcriptWindow
+  if (bag === undefined || win === null || win === undefined || !win.hasMarker) return
+  if (shell.transcript.scrollTop > TRANSCRIPT_WIDEN_MARGIN) return
+
+  const distanceFromBottom = shell.transcript.scrollHeight - shell.transcript.scrollTop
+  win.size = Math.min(shell.streamLog.length, win.size + LONG_LOG_WINDOW)
+  repaintTranscriptWindow(shell)
+  bag.transcriptScrollRestore = { distanceFromBottom }
 }
 
+/**
+ * Apply a scroll restore queued by `maybeWidenTranscriptWindow` once layout
+ * has measured the newly painted rows — `scrollHeight` is stale until then.
+ */
+function applyTranscriptScrollRestore(shell: AppShell): void {
+  const bag = internals.get(shell)
+  const pending = bag?.transcriptScrollRestore
+  if (bag === undefined || pending === null || pending === undefined) return
+  bag.transcriptScrollRestore = null
+  shell.transcript.scrollTop = Math.max(0, shell.transcript.scrollHeight - pending.distanceFromBottom)
+}
+
+/** Rows of headroom left before the widen kicks in — 0 waits for the exact top. */
+const TRANSCRIPT_WIDEN_MARGIN = 1
+
 /**
  * Tear the landing down on the first transcript row.
  *
@@ -4829,6 +4964,10 @@ export function createAppShell(
     // starves that pass of room to lay the row out in.
     syncTranscriptSpacer(shell)
     syncNoticeAfterLayout(shell)
+    // Restore first: a widen queued last frame needs this frame's layout to
+    // have measured the rows it added before scrollHeight is trustworthy.
+    applyTranscriptScrollRestore(shell)
+    maybeWidenTranscriptWindow(shell)
   }
 
   const onResize = (width: number, height: number): void => {
@@ -4951,6 +5090,8 @@ export function createAppShell(
     landingAnimating: false,
     landingNowMs: 0,
     chrome: { goal: "", task: "", agents: "" },
+    transcriptWindow: null,
+    transcriptScrollRestore: null,
   })
   transcriptSpacers.set(shell, transcriptSpacer)
   if (onCommandOpt) setPaletteOnCommand(shell, onCommandOpt)

src/tui-opentui/transcript-long-log-scroll.test.ts

@@ -0,0 +1,117 @@
+/**
+ * CL-5553: past the long-log collapse threshold, history above the painted
+ * window has to stay reachable by scrolling, and appending a new row must
+ * not rebuild the whole window to do it.
+ */
+import { describe, expect, test } from "bun:test"
+import { withTestRenderer } from "./harness"
+import { appendStreamRow, createAppShell, isTranscriptFollowing } from "./shell"
+import { LONG_LOG_COLLAPSE_THRESHOLD } from "./long-log"
+
+async function settle(h: { renderOnce: () => Promise<void> }): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 10))
+  await h.renderOnce()
+}
+
+describe("long-log transcript scrolling", () => {
+  test("scrolling to the top reaches a row far above the collapse threshold", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+        })
+        try {
+          const total = LONG_LOG_COLLAPSE_THRESHOLD + 50
+          for (let i = 0; i < total; i++) {
+            appendStreamRow(shell, { role: "assistant", text: `row-${i}` })
+          }
+          await settle(h)
+
+          // Repeatedly scroll to the current top and let the window widen —
+          // each widen only reaches back one more chunk, same as a real
+          // operator holding PageUp/scroll-up.
+          for (let i = 0; i < 10; i++) {
+            shell.transcript.scrollTop = 0
+            await settle(h)
+            if (h.captureCharFrame().includes("row-0")) break
+          }
+
+          expect(h.captureCharFrame()).toContain("row-0")
+        } finally {
+          shell.dispose()
+        }
+      },
+      { width: 80, height: 24 },
+    )
+  })
+
+  test("appending a row in a long session does not rebuild the painted window", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+        })
+        try {
+          for (let i = 0; i < LONG_LOG_COLLAPSE_THRESHOLD + 1; i++) {
+            appendStreamRow(shell, { role: "assistant", text: `row-${i}` })
+          }
+          await settle(h)
+          expect(isTranscriptFollowing(shell)).toBe(true)
+
+          // Node well inside the window, far from the eviction edge at the top.
+          const children = shell.transcript.getChildren()
+          const probe = children[children.length - 20]
+          expect(probe).toBeDefined()
+
+          appendStreamRow(shell, { role: "assistant", text: "one-more" })
+          await settle(h)
+
+          const childrenAfter = shell.transcript.getChildren()
+          // Same node instance survives: a full window rebuild would have torn
+          // every row down and painted fresh ones instead.
+          expect(childrenAfter).toContain(probe!)
+        } finally {
+          shell.dispose()
+        }
+      },
+      { width: 80, height: 24 },
+    )
+  })
+
+  test("append churn is O(1), not O(window)", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+        })
+        try {
+          for (let i = 0; i < LONG_LOG_COLLAPSE_THRESHOLD + 1; i++) {
+            appendStreamRow(shell, { role: "assistant", text: `row-${i}` })
+          }
+          await settle(h)
+
+          let removed = 0
+          const originalRemove = shell.transcript.remove.bind(shell.transcript)
+          shell.transcript.remove = (child) => {
+            removed += 1
+            return originalRemove(child)
+          }
+
+          appendStreamRow(shell, { role: "assistant", text: "one-more" })
+          await settle(h)
+
+          // Old behavior: mustWindow tripped repaintTranscriptWindow on every
+          // append, tearing down and rebuilding ~LONG_LOG_WINDOW (200) nodes.
+          // Fixed behavior: one row evicted at the top to hold the window size.
+          expect(removed).toBeLessThanOrEqual(1)
+        } finally {
+          shell.dispose()
+        }
+      },
+      { width: 80, height: 24 },
+    )
+  })
+})