@workerdeck/ui 0.15.0 → 0.16.0

package/src/components/agent/Transcript.tsx

@@ -1,7 +1,17 @@
-import { useEffect, useMemo, useRef, useState, type RefObject } from 'react'
-import { useVirtualizer } from '@tanstack/react-virtual'
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { defaultRangeExtractor, useVirtualizer, type Range } from '@tanstack/react-virtual'
 import { useStickToBottomContext } from 'use-stick-to-bottom'
-import type { MessageAttachment } from '@workerdeck/protocol'
+import type { MessageAttachment, PermissionRequest } from '@workerdeck/protocol'
 import { recapLine, summarizeSince, type TranscriptItem, type TranscriptState } from '@workerdeck/react'
 import { cn } from '../../lib/utils.ts'
 import { formatCost, formatDuration, formatRelativeTime } from '../../lib/format.ts'
@@ -14,41 +24,24 @@ import { Reasoning } from './Reasoning.tsx'
 import { Response } from './Response.tsx'
 import { SessionEmptyState } from './SessionEmptyState.tsx'
 import { ToolCallCard } from './ToolCallCard.tsx'
+import { resolveAffordances, type TerminalAffordances } from '../terminal/affordances.tsx'
+import { ToolRunRow, WorkingRow, terminalBlocks } from '../terminal/items.tsx'
+import { estimateBlockPx } from '../terminal/height.ts'
+import { TerminalScrubber } from '../terminal/scrubber.tsx'
+import { gapBefore, rowIndexForItem, type TranscriptRow } from './transcript-rows.ts'
+import { useHeightEpoch } from './use-height-epoch.ts'
+import { useTranscriptJumps } from './use-transcript-jumps.ts'
+import { Row } from '../terminal/row.tsx'
+import { TerminalSurface } from '../terminal/surface.tsx'
+import { TerminalItemView } from '../terminal/TerminalTranscript.tsx'
 import {
-  LineGlyph,
   ROW_GAP,
   TranscriptVariantProvider,
-  useLines,
   type TranscriptDensity,
   type TranscriptVariant,
 } from './transcript-variant.tsx'
 
 function TurnResultRow({ item }: { item: Extract<TranscriptItem, { kind: 'turn_result' }> }) {
-  const lines = useLines()
-  if (lines) {
-    // One dim line, no rules: the turn's end is a footnote, not a divider that
-    // costs three rows of vertical space.
-    return (
-      <div data-slot='turn-result' className='flex items-baseline gap-2'>
-        <LineGlyph className='text-fg-4'>·</LineGlyph>
-        <div className='min-w-0 flex-1'>
-          <span className={cn('text-label leading-5', item.isError ? 'text-danger' : 'text-fg-4')}>
-            {item.isError ? item.subtype : 'turn done'} · {formatDuration(item.durationMs)} ·{' '}
-            {formatCost(item.totalCostUsd)}
-          </span>
-          {item.errors?.length ? (
-            <ul className='flex flex-col'>
-              {item.errors.map((message, index) => (
-                <li key={index} className='text-label leading-5 break-words text-danger'>
-                  {message}
-                </li>
-              ))}
-            </ul>
-          ) : null}
-        </div>
-      </div>
-    )
-  }
   return (
     <div data-slot='turn-result' className='py-1'>
       <div className='flex items-center gap-2'>
@@ -75,21 +68,6 @@ function TurnResultRow({ item }: { item: Extract<TranscriptItem, { kind: 'turn_r
 }
 
 function NoticeRow({ item }: { item: Extract<TranscriptItem, { kind: 'notice' }> }) {
-  const lines = useLines()
-  if (lines) {
-    return (
-      <div data-slot='notice' className='flex items-baseline gap-2'>
-        <LineGlyph className={item.level === 'error' ? 'text-danger' : 'text-fg-4'}>!</LineGlyph>
-        <span
-          className={cn(
-            'min-w-0 flex-1 text-body-sm leading-5',
-            item.level === 'error' ? 'text-danger' : 'text-fg-3',
-          )}>
-          {item.text}
-        </span>
-      </div>
-    )
-  }
   return (
     <div
       data-slot='notice'
@@ -109,12 +87,17 @@ function TranscriptItemView({
   fileUrl,
   attachmentUrl,
   hostImage,
+  terminal,
 }: {
   item: TranscriptItem
   fileUrl?: (path: string) => string
   attachmentUrl?: (attachmentId: string) => string
   hostImage?: (path: string) => Promise<string | undefined>
+  terminal?: boolean
 }) {
+  // The terminal theme is a renderer, not a branch: it draws every kind itself,
+  // so the switch below is never reached under it.
+  if (terminal) return <TerminalItemView item={item} fileUrl={fileUrl} />
   switch (item.kind) {
     case 'user':
       return (
@@ -163,21 +146,27 @@ function TranscriptItemView({
  * the virtual list, and a boundary with nothing to say must contribute no row
  * at all rather than an empty slot that still costs its gap.
  */
-function RecapRow({ line, since }: { line: string; since?: number }) {
-  const lines = useLines()
+function RecapRow({ line, since, terminal }: { line: string; since?: number; terminal?: boolean }) {
   const away = since === undefined ? undefined : formatRelativeTime(since)
   const text = away ? `${line} · last here ${away}` : line
 
-  if (lines) {
+  // Under the terminal theme it is a Row like everything else, and that is not
+  // cosmetic: the cards markup measures 42px against an 18px line, so it was the
+  // one row in the transcript sitting off the grid — and it shifted *every row
+  // below it* by the remainder, which is precisely the failure the whole-multiple
+  // rule exists to prevent. It was invisible until a fixture carried a recap
+  // splice. Being a real row also makes it exactly computable, so the height
+  // calculator loses its last estimated constant.
+  if (terminal) {
     return (
-      <div data-slot='recap' className='flex items-baseline gap-2 py-0.5'>
-        <LineGlyph className='text-fg-3'>※</LineGlyph>
-        <span className='min-w-0 flex-1 text-label leading-5 text-fg-3'>
-          <span className='text-fg-2'>recap:</span> {text}
-        </span>
+      <div data-slot='recap'>
+        <Row glyph='※' glyphTone='faint' tone='faint'>
+          recap: {text}
+        </Row>
       </div>
     )
   }
+
   return (
     <div data-slot='recap' className='flex items-center gap-2 py-1'>
       <div className='h-px flex-1 bg-border' />
@@ -188,39 +177,24 @@ function RecapRow({ line, since }: { line: string; since?: number }) {
 }
 
 /**
- * Has the transcript stopped *filling* and started *streaming*?
+ * **Nothing on this surface animates its scroll position.** VS Code does not —
+ * click its editor scrollbar and it jumps — and neither does a terminal, which
+ * is the article this transcript is drawing. Every travel a reader ever
+ * complained about here was an animation we asked for.
  *
- * Attaching replays the whole session as a burst of events, so the content grows
- * by hundreds of rows over a few hundred milliseconds. Animating that — which is
- * the right behaviour for a live turn — turns opening a session into a
- * several-second scroll from its first row to its last, which is precisely wrong
- * when you are skimming sessions to see where each agent got to.
+ * What used to be here was `useSettled`: a latch deciding smooth-vs-instant for
+ * the follow spring, with a quiet window, a "silence before the first row does
+ * not count" guard and a live-status gate — all of it apparatus for a
+ * smooth-scroll bug (the attach replays hundreds of rows, and animating that
+ * turned opening a session into a several-second journey). With no smooth mode
+ * left there is nothing for it to decide, so the whole thing is gone rather
+ * than pinned to `false`.
  *
- * So: instant until the arrivals stop for a beat, smooth from then on. Latched,
- * because a live turn is bursty too and nobody wants the follow behaviour to
- * flicker between modes mid-answer.
- *
- * Two guards, both load-bearing, both learned from this going wrong:
- *
- * - **Silence before the first row is not quiet, it is waiting.** The attach
- *   that fills this transcript is a round trip — and in a VS Code webview it is
- *   webview → extension host → gateway and back — so the first replayed row can
- *   land well after the quiet window. A timer started at mount then latches
- *   *before the transcript exists*, and the whole replay animates: exactly the
- *   symptom the latch was added to prevent.
- * - **Only a live turn earns smooth.** An idle session has nothing to animate.
- *   Skimming finished sessions is therefore instant no matter what the timing
- *   did, which is the case that has to be right.
+ * The two remaining writers of `scrollTop` — the follow spring and the
+ * virtualizer's size-change correction — are unchanged and still split by
+ * regime; `Conversation` itself is now hardwired to `instant` on both `initial`
+ * and `resize`.
  */
-function useSettled(count: number, status: TranscriptState['status'], quietMs = 400): boolean {
-  const [settled, setSettled] = useState(false)
-  useEffect(() => {
-    if (settled || count === 0) return
-    const timer = setTimeout(() => setSettled(true), quietMs)
-    return () => clearTimeout(timer)
-  }, [count, settled, quietMs])
-  return settled && (status === 'running' || status === 'starting')
-}
 
 /**
  * When the current run began — the clock the working line counts from.
@@ -283,23 +257,137 @@ function SentAttachments({
   )
 }
 
+/**
+ * The terminal theme's root, when that is the variant, and a passthrough when it
+ * is not.
+ *
+ * It has to live *inside* the scroller's content element rather than around the
+ * whole `Conversation`: `--term-line` and `1ch` are inherited, and the rows are
+ * rendered by the virtualizer several levels down. Wrapping the scroller instead
+ * would work identically for the cells and break the full-bleed bands, whose
+ * negative margins are measured against this element's padding.
+ */
+function TerminalShell({
+  active,
+  fontSize,
+  lineHeight,
+  affordances,
+  children,
+}: {
+  active: boolean
+  fontSize?: number
+  lineHeight?: number
+  affordances?: TerminalAffordances | boolean
+  children: ReactNode
+}) {
+  if (!active) return <>{children}</>
+  return (
+    <TerminalSurface
+      fontSize={fontSize}
+      lineHeight={lineHeight}
+      affordances={affordances}
+      bleed='1ch'
+      className='term-transcript'>
+      {children}
+    </TerminalSurface>
+  )
+}
+
+/** Already read: present, legible, and visibly behind you. */
+function read(boundary: number | undefined, index: number): boolean {
+  return boundary !== undefined && index < boundary
+}
+
 /** Rows produced inside a subagent (`parentToolUseId != null`) are stepped in
  * behind a rule, so a Task's own output reads as belonging to the tool call
  * above it rather than as the main thread carrying on. */
-function nestedClass(item: TranscriptItem, lines: boolean): string | undefined {
+function nestedClass(item: TranscriptItem): string | undefined {
   const nested = 'parentToolUseId' in item && item.parentToolUseId != null
-  if (!nested) return undefined
-  return lines ? 'ml-3.5 border-l border-border pl-2' : 'border-l-2 border-border pl-3'
+  return nested ? 'border-l-2 border-border pl-3' : undefined
 }
 
-/** One row of the virtual list: a transcript item, or the recap boundary line
- * spliced in at `catchUp.from`. One flat array so the virtualizer sees stable
- * indices, and each row carries the key the item was already React-keyed by —
- * measurements are cached per key, so a row keeps its measured height when the
- * recap splice shifts every index after it. */
-type TranscriptRow =
-  | { key: string; item: TranscriptItem; index: number }
-  | { key: 'recap'; line: string }
+// The virtual row model — what a row *is*, the spacing rule, and the
+// item-index → row-index mapping — lives in `transcript-rows.ts`; re-exported
+// here because this file is where consumers have always found them.
+export { rowIndexForItem, type TranscriptRow } from './transcript-rows.ts'
+
+/**
+ * A prompt row's sticky lane — the strip spanning its turn, leading with the
+ * one-line pinned **head** (see the pinned-prompt comment in
+ * {@link TranscriptRows}).
+ *
+ * The head starts `visibility: hidden` and shows only while actually stuck —
+ * an overlay that is visible in flow would sit on the real row's first line
+ * and swallow its selection highlight, which reads as "the first line cannot
+ * be selected". CSS cannot ask "am I stuck?", so a 1px sentinel at the head's
+ * engage threshold (the line's own y) feeds an IntersectionObserver: sentinel
+ * above the scrollport top → stuck. Transition-only callbacks — this adds no
+ * per-scroll work, and the pin itself is still the compositor's.
+ */
+function StickyPromptLane({
+  top,
+  height,
+  gapClass,
+  scrollRoot,
+  index,
+  measureRef,
+  content,
+}: {
+  top: number
+  height: number
+  gapClass?: string | false
+  scrollRoot: HTMLElement | null
+  index: number
+  measureRef: (element: HTMLDivElement | null) => void
+  content: ReactNode
+}) {
+  const headRef = useRef<HTMLDivElement | null>(null)
+  const sentinelRef = useRef<HTMLDivElement | null>(null)
+  useEffect(() => {
+    const head = headRef.current
+    const sentinel = sentinelRef.current
+    if (!head || !sentinel || !scrollRoot) return
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry) return
+        // Above the scrollport, not merely out of it — a lane still below the
+        // viewport has its sentinel non-intersecting too.
+        const stuck =
+          !entry.isIntersecting &&
+          entry.boundingClientRect.top < (entry.rootBounds?.top ?? 0)
+        head.toggleAttribute('data-stuck', stuck)
+      },
+      { root: scrollRoot },
+    )
+    observer.observe(sentinel)
+    return () => observer.disconnect()
+  }, [scrollRoot])
+  return (
+    <div data-sticky-lane='' className='absolute inset-x-0' style={{ top, height }}>
+      {/* The head rides in its own absolutely positioned sub-lane rather than
+          in flow with a cancelled footprint: sticky confinement clamps the
+          *margin* box, and a negative bottom margin shrinks that box to zero
+          height — the head then overshoots the lane's end by its own height,
+          which put two pinned prompts on screen at once during the handoff.
+          Out of flow, the border box is what gets clamped, and the push-off
+          lands exactly at the lane's bottom edge. */}
+      <div data-sticky-headlane='' aria-hidden>
+        <div ref={headRef} data-sticky-head='' className={gapClass || undefined}>
+          {content}
+        </div>
+      </div>
+      <div
+        ref={sentinelRef}
+        aria-hidden
+        className='absolute left-0 w-px'
+        style={{ top: gapClass ? 'var(--term-line)' : 0, height: 1 }}
+      />
+      <div ref={measureRef} data-index={index} className={gapClass || undefined}>
+        {content}
+      </div>
+    </div>
+  )
+}
 
 /**
  * The virtualized row window. Only rows near the viewport are mounted, so
@@ -339,23 +427,52 @@ function TranscriptRows({
   rows,
   boundary,
   since,
-  lines,
+  terminal,
+  replaying,
+  stickyPrompt,
   gap,
+  fontSize,
+  lineHeight,
+  items,
+  pendingApprovals,
+  scrubber,
+  scrubberMarks,
+  affordances,
   fileUrl,
   attachmentUrl,
   hostImage,
   jumpToRecapRef,
+  repinRef,
 }: {
   rows: TranscriptRow[]
   boundary: number | undefined
   since: number | undefined
-  lines: boolean
+  /** The terminal theme draws its own rows; see {@link TranscriptItemView}. */
+  terminal: boolean
+  /** The replay hold (see {@link TranscriptProps.replaying}) — read here only
+   * for its falling edge, which needs a pre-paint pin. */
+  replaying: boolean
+  /** Pin the prompt of the turn being read to the top of the scroller. */
+  stickyPrompt: boolean
   /** The inter-row gap for this variant and density (`ROW_GAP`). */
   gap: { className?: string; px: number }
+  /** The terminal cell, when the host set one — only read as a signal that the
+   * height epoch below must re-measure; the epoch's numbers come from the DOM. */
+  fontSize?: number
+  lineHeight?: number
+  /** The transcript items — the scrubber's marks and peeks render from these,
+   * never from the DOM (the row a mark points at is usually unmounted). */
+  items: readonly TranscriptItem[]
+  pendingApprovals: readonly PermissionRequest[]
+  /** Mount the overview-ruler rail (terminal theme only). */
+  scrubber?: boolean
+  scrubberMarks?: readonly number[]
+  affordances?: TerminalAffordances | boolean
   fileUrl?: (path: string) => string
   attachmentUrl?: (attachmentId: string) => string
   hostImage?: (path: string) => Promise<string | undefined>
   jumpToRecapRef?: RefObject<(() => void) | null>
+  repinRef?: RefObject<(() => void) | null>
 }) {
   const stick = useStickToBottomContext()
   // The scroll element belongs to an ancestor — `StickToBottom.Content`
@@ -366,9 +483,90 @@ function TranscriptRows({
   // virtualizer adopt it promptly: without one, a transcript short enough to
   // never fire a scroll event could sit renderless indefinitely.
   const [scrollElement, setScrollElement] = useState<HTMLElement | null>(null)
+  // Which rows *could* be the pinned prompt. Recomputed only when the row list
+  // changes, so the per-scroll work below is a walk over prompts rather than
+  // over the transcript.
+  const promptRows = useMemo(
+    () => rows.flatMap((row, index) => ('item' in row && row.item.kind === 'user' ? [index] : [])),
+    [rows],
+  )
+  // The pinned row must stay mounted even when it is far above the window, so
+  // it is forced into the virtual range — see `rangeExtractor` below, which
+  // reads these refs rather than closing over render values: it is called from
+  // inside the virtualizer's own range pass, where a closure would be a stale
+  // render's.
+  const pinRef = useRef<{ enabled: boolean; promptRows: readonly number[] }>({
+    enabled: false,
+    promptRows: [],
+  })
+  pinRef.current = { enabled: terminal && stickyPrompt, promptRows }
   useEffect(() => {
     setScrollElement(stick.scrollRef.current)
   }, [stick.scrollRef])
+
+  // A composer that grows steals a line from the transcript.
+  //
+  // The composer and the transcript are siblings in the panel's flex column, so
+  // typing a newline shrinks this scroller by one line. "At the bottom" is a
+  // `scrollTop`, and that number stops meaning the bottom the moment the
+  // viewport changes height — so the last row, the one you were reading, slides
+  // under the fold as you type.
+  //
+  // `use-stick-to-bottom` cannot catch this: its ResizeObserver observes the
+  // **content** element (`.observe(content)` in its `useStickToBottom`), and
+  // here the content is unchanged and the *scroller* moved. Nor does the browser
+  // help — scrollTop is untouched, so no scroll event fires and nothing
+  // recomputes. Hence an observer of our own, on the scroller's own box.
+  //
+  // The guard is the whole feature: re-pin **only when already pinned**, or
+  // every newline yanks a reader who had deliberately scrolled up. That state
+  // lives in here, which is why this is in `Transcript` and not `SessionPanel`.
+  // Reading `stick.state.isAtBottom` (the library's live object, not the
+  // rendered boolean) is safe precisely because of the paragraph above: no
+  // scroll event fired, so the flag still holds the pre-resize answer.
+  //
+  // This is not a third writer of `scrollTop` — it presses the follow spring's
+  // own button, instantly, which is what the spring would have done had it
+  // noticed. The pinned-suppresses-corrections regime below is untouched.
+  useEffect(() => {
+    if (!scrollElement) return
+    let last = scrollElement.clientHeight
+    const observer = new ResizeObserver(() => {
+      const height = scrollElement.clientHeight
+      if (height === last) return
+      last = height
+      if (stick.state.isAtBottom) void stick.scrollToBottom('instant')
+    })
+    observer.observe(scrollElement)
+    return () => observer.disconnect()
+  }, [scrollElement, stick])
+
+  // The replay hold's reveal must paint already at the bottom, and the follow
+  // spring cannot make that true: even `scrollToBottom('instant')` defers its
+  // write behind a `requestAnimationFrame`, one frame after the reveal's paint
+  // — so the first visible frame showed the tail a burst shy of the bottom and
+  // then hopped (measured: revealTop 33037 against final 34459 on the 600-row
+  // fixture). A layout effect runs after the commit that removed the hold's
+  // visibility and before its paint, so this write lands in the very frame the
+  // transcript appears. It presses the library's own `state.scrollTop` setter
+  // — which records the write in `ignoreScrollToTop`, so the scroll handler
+  // knows it for its own — not a raw `scrollTop`, and only on the hold's
+  // falling edge, only while pinned; it is the pin's own move made a frame
+  // early, not a third writer.
+  const wasReplaying = useRef(replaying)
+  useLayoutEffect(() => {
+    const was = wasReplaying.current
+    wasReplaying.current = replaying
+    if (!was || replaying) return
+    if (!stick.state.isAtBottom) return
+    stick.state.scrollTop = stick.state.calculatedTargetScrollTop
+  }, [replaying, stick])
+
+  // The height epoch — see `use-height-epoch.ts`. Owned here because this
+  // component owns the virtualizer the heights feed.
+  const rowsRef = useRef<HTMLDivElement | null>(null)
+  const epoch = useHeightEpoch({ terminal, fontSize, lineHeight, rowsRef })
+
   const virtualizer = useVirtualizer<HTMLElement, HTMLDivElement>({
     count: rows.length,
     // On adopting a scroll element the virtualizer *replays* its remembered
@@ -387,16 +585,56 @@ function TranscriptRows({
       }
       return scrollElement
     },
-    // Estimates only shape the scrollbar and the span of never-mounted rows;
-    // a measurement replaces them the moment a row mounts. A lines row is one
-    // text line more often than not; cards vary too much for any constant to
-    // be right, so that one is merely the order of magnitude.
-    // Plus the gap, which is real height on the same measured element — an
-    // estimate that ignored it would make the scrollbar visibly too short on a
-    // long transcript before the rows mount.
-    estimateSize: () => (lines ? 32 : 100) + gap.px,
+    // Estimates only shape the scrollbar and the span of never-mounted rows; a
+    // measurement replaces them the moment a row mounts. Under the terminal
+    // theme they are *computed* (`terminal/height.ts`): the theme's one line
+    // height and one cell make a row's height derivable from its item, so the
+    // scrollbar is honest before rows mount and `scrollToIndex` sums real
+    // sizes instead of accumulating error over unmeasured spans. The gap rides
+    // the same estimate because it is real height on the same measured element
+    // — one line, decided per pair by `gapBefore`, exactly as the renderer
+    // applies the class. The recap row is a Row here too, so it is one line and
+    // exact — it used to be the cards markup, which measured 42px against an
+    // 18px line and pushed every row below it off the grid.
+    // Cards keep the flat constant: they vary too much for any constant to be
+    // right, so it is merely the order of magnitude — and the calculator has
+    // no claim there (padding scales, borders, a proportional face).
+    estimateSize: (index) => {
+      if (terminal && epoch) {
+        const row = rows[index]
+        const gapPx = index > 0 && gapBefore(rows, index) ? epoch.line : 0
+        if (row && ('item' in row || 'run' in row))
+          return estimateBlockPx(row, epoch) + gapPx
+        return epoch.line + gapPx // recap: one Row, one line
+      }
+      return (terminal ? 36 : 100) + gap.px
+    },
     overscan: 8,
     getItemKey: (index) => rows[index].key,
+    // The sticky row, forced into the range. This is the virtualizer's own
+    // sticky-header seam: without it the pinned prompt's lane unmounts the
+    // moment it leaves the window, which is exactly when it is doing its job.
+    // The active prompt — the last one starting at or above the fold — is
+    // computed *here*, from the instance's own offset, rather than in the
+    // render body: the range pass runs before the render that would refresh a
+    // ref, so a value computed outside this callback is one scroll event
+    // stale, and a long programmatic jump would leave the pinned row unmounted
+    // until the next scroll. (`virtualizer` is safe to close over: the hook
+    // returns one stable instance for the component's lifetime.)
+    rangeExtractor: useCallback((range: Range) => {
+      const indexes = new Set(defaultRangeExtractor(range))
+      const { enabled, promptRows: prompts } = pinRef.current
+      if (enabled) {
+        const offset = virtualizer.scrollOffset ?? 0
+        let pinned = -1
+        for (const index of prompts) {
+          if ((virtualizer.measurementsCache[index]?.start ?? Infinity) <= offset) pinned = index
+          else break
+        }
+        if (pinned >= 0) indexes.add(pinned)
+      }
+      return [...indexes].sort((a, b) => a - b)
+    }, []),
     // Explicit, and left at the default, because the obvious cleanup here is
     // wrong. A correction fires from `measureElement`'s ref callback — inside
     // React's commit — so the core's synchronous flush draws a "flushSync was
@@ -426,104 +664,228 @@ function TranscriptRows({
       : item.start < fold
   }
 
-  // The catch-up strip's "jump" lives outside this scroll container, and the
-  // recap row it targets is usually unmounted — only the virtualizer knows
-  // where it would be, so the strip is handed this closure instead of a DOM
-  // query. Smooth on purpose: the jump IS a journey, and watching it travel
-  // is what tells you how far back the boundary was. `stopScroll()` first,
-  // because the pin spring is the other `scrollTop` writer and this is the
-  // library's own switch for "the user is leaving the bottom".
+  // A new epoch means every remembered size is against the wrong metrics —
+  // the *measurements* included, which were taken at the old width. Dropping
+  // both together is the whole point: better estimates layered under
+  // stale-width measurements would be worse than either alone.
   //
-  // And it has to *re-aim*. Every row between here and the boundary is
-  // unmeasured, so the offset the virtualizer scrolls to is the sum of a few
-  // hundred estimates; the real one only exists once those rows mount. A
-  // single smooth scroll therefore lands a screen or two short — measured at
-  // ~3300px off over 600 rows — and it cannot self-correct, because the core
-  // suppresses size-change adjustments outright while a smooth scroll is in
-  // flight. So: aim, let the rows it crossed measure, aim again from the
-  // better estimate. Each pass overshoots by less, and the moment the row is
-  // actually mounted the DOM can finish the job exactly.
-  //
-  // The pending re-aim lives in a ref, and this is the whole reason: the effect
-  // that publishes the closure has to re-run every render to keep `rows` fresh,
-  // so anything held in its scope is torn down every render too — and a jump in
-  // flight re-renders constantly, because that is what rows mounting *is*. A
-  // timer in the closure would be cancelled by the very work it is waiting for.
-  const aimTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
-  useEffect(() => () => clearTimeout(aimTimer.current), [])
+  // The second half is not optional: `measure()` clears the size cache and a
+  // row re-enters it only when its ResizeObserver fires — which needs a *size
+  // change*. A mounted row whose height happens to survive the width change
+  // (short lines that never rewrap) would keep its estimate forever, and
+  // wherever the estimate is off the transcript grows a phantom tail — 2,052px
+  // of scrollable nothing after one sidebar toggle, on a real session. So the
+  // mounted rows are fed straight back in.
   useEffect(() => {
-    if (!jumpToRecapRef) return
-    jumpToRecapRef.current = () => {
-      const index = rows.findIndex((row) => row.key === 'recap')
-      if (index < 0) return
-      stick.stopScroll()
-      clearTimeout(aimTimer.current)
-      const aim = (attempt: number) => {
-        const row = scrollElement?.querySelector('[data-slot="recap"]')
-        if (row) {
-          row.scrollIntoView({ behavior: 'smooth', block: 'center' })
-          return
-        }
-        if (attempt >= 6) return
-        virtualizer.scrollToIndex(index, { align: 'center', behavior: 'smooth' })
-        // Longer than one frame: the aim is only better once the rows crossed
-        // have mounted *and* been measured, and that is a layout pass away.
-        aimTimer.current = setTimeout(() => aim(attempt + 1), 300)
-      }
-      aim(0)
-    }
-    return () => {
-      jumpToRecapRef.current = null
+    if (!terminal || !epoch) return
+    virtualizer.measure()
+    const container = rowsRef.current
+    if (!container) return
+    // Two sharp edges in the re-feed, both learned the hard way. Order:
+    // `resizeItem` diffs a measure against `measurementsCache`, and straight
+    // after `measure()` that array is still the pre-wipe one — an unchanged
+    // row diffs to zero against its own old measurement and the write is
+    // skipped; recomputing first (any measurement read does it) rebuilds the
+    // array from estimates, so the diff is real again. And `resizeItem`
+    // directly, not `measureElement(element)`: the latter is gated on the
+    // scroll state and silently drops a measure that lands while a scroll is
+    // still hot — which a resize's own scroll anchoring makes routine.
+    virtualizer.getTotalSize()
+    for (const element of container.querySelectorAll<HTMLElement>('[data-index]')) {
+      const index = Number(element.getAttribute('data-index'))
+      if (Number.isInteger(index) && index >= 0)
+        virtualizer.resizeItem(index, element.getBoundingClientRect().height)
     }
+  }, [terminal, epoch, virtualizer])
+
+  // The jump machinery — the aim loop, the catch-up strip's jump, the re-pin
+  // — lives in `use-transcript-jumps.ts`; every jump on this surface comes
+  // through the one function it returns.
+  const jumpToRow = useTranscriptJumps({
+    rows,
+    terminal,
+    stickyPrompt,
+    epoch,
+    promptRows,
+    scrollElement,
+    rowsRef,
+    virtualizer,
+    stick,
+    jumpToRecapRef,
+    repinRef,
   })
 
+  // The scrubber. Interactivity follows the hover affordance — with
+  // `affordances={false}` the rail is passive paint (pointer-events off) and
+  // the native scrollbar stays; interactive, the rail IS the scrollbar, so the
+  // native one is hidden via an attribute on the scroll element.
+  const scrubInteractive = resolveAffordances(affordances).hover
+  const recapIndex = rows.findIndex((row) => row.key === 'recap')
+  const recapRow =
+    recapIndex >= 0
+      ? { rowIndex: recapIndex, label: (rows[recapIndex] as { line: string }).line }
+      : undefined
+  useEffect(() => {
+    if (!terminal || !scrubber || !scrubInteractive || !scrollElement) return
+    scrollElement.setAttribute('data-term-scrubber-host', '')
+    return () => scrollElement.removeAttribute('data-term-scrubber-host')
+  }, [terminal, scrubber, scrubInteractive, scrollElement])
+
+  /**
+   * The pinned prompt: the prompt's **first line**, held at the top of the
+   * scroller.
+   *
+   * One line, not the row: a pasted twenty-line prompt pinned whole covers the
+   * viewport and buries the very answer being read under it. So what pins is a
+   * **head** — one line tall, `overflow: hidden` — whose content is the same
+   * row rendered again, laid exactly over the real row's first line. It is a
+   * duplicate, which an earlier design here rejected — but that rejection was
+   * of a *separate header* with its own padding and its own idea of the
+   * gutter. This copy is the same component in the same column at the same
+   * width, so it aligns with the row beneath by construction, and while the
+   * row is in flow the overlay is pixel-identical and invisible. It takes no
+   * pointer events and is `aria-hidden`: the real row owns interaction and
+   * the accessibility tree; the head is paint.
+   *
+   * The pin itself is the browser's, not ours. Each prompt row renders inside a
+   * **lane**: an absolutely positioned strip spanning from the prompt's start to
+   * the next prompt's (its turn), with the head `position: sticky` inside it
+   * (its flow footprint cancelled by a negative bottom margin, so the real row
+   * sits at the lane's top as if the head were not there). The compositor does
+   * the pinning and the lane's bottom edge does the push-off — `sticky` is
+   * inert on an absolutely positioned element, but works unchanged on a child
+   * *of* one, confined to the lane's box. An earlier version clamped the row's
+   * transform from render instead, and paid for it every frame: any JS-written
+   * pin — React render or a raw scroll handler — runs behind the compositor
+   * thread, so the row wobbled under momentum scroll. With the lane there is
+   * no per-scroll JS and no lag.
+   *
+   * Which row — the last prompt at or above the fold, the question the answer
+   * on screen belongs to — falls out of the geometry: only the lane spanning
+   * the viewport top has its child stuck; every earlier lane has pushed its row
+   * off its bottom edge, every later one hasn't reached the top.
+   *
+   * The one job left to JS is keeping that row *mounted* once it scrolls far
+   * above the virtual window — which is exactly when it is working. That lives
+   * in the `rangeExtractor` above.
+   */
+  const measurements = virtualizer.measurementsCache
+
   return (
     <div
+      ref={rowsRef}
       data-slot='transcript-rows'
       className='relative w-full'
       style={{ height: virtualizer.getTotalSize() }}>
       {virtualizer.getVirtualItems().map((virtualRow) => {
         const row = rows[virtualRow.index]
+        // The inter-row gap, folded into each row so the measured height
+        // carries it: flex `gap` cannot reach absolutely positioned rows,
+        // and a pixel constant for the virtualizer's `gap` option would
+        // drift from the rem the layout is set in. On the measured wrapper,
+        // not the row div, so a nested row's left border still breaks
+        // across the gap as it did under flex. Skipped for the first row —
+        // a gap above it would be padding, not spacing.
+        // Every variant but terminal spaces every row alike. Terminal
+        // asks whether the pair belongs together — a tool call and its
+        // output get no blank line, exactly as the CLI leaves none.
+        const gapClass =
+          virtualRow.index > 0 && (!terminal || gapBefore(rows, virtualRow.index))
+            ? gap.className
+            : undefined
+        const content =
+          'run' in row ? (
+            <div className={cn(read(boundary, row.index) && 'opacity-45')}>
+              <ToolRunRow items={row.run} />
+            </div>
+          ) : 'item' in row ? (
+            <div className={cn(read(boundary, row.index) && 'opacity-45', nestedClass(row.item))}>
+              <TranscriptItemView
+                item={row.item}
+                fileUrl={fileUrl}
+                attachmentUrl={attachmentUrl}
+                hostImage={hostImage}
+                terminal={terminal}
+              />
+            </div>
+          ) : (
+            <RecapRow line={row.line} since={since} terminal={terminal} />
+          )
+        // A prompt row's sticky lane — see the pinned-prompt comment above.
+        // The lane is sized to the turn; the sticky **head** (one clipped
+        // line, the same content again) comes first with its flow footprint
+        // cancelled, and the *measured* element is the real row after it, so
+        // the virtualizer's heights are untouched by either. Both carry the
+        // gap class: the row because the gap is part of its measured height,
+        // the head so its one visible line sits on the same y while in flow —
+        // the pin parks that padding above the viewport edge when stuck.
+        // Positioned with `top`, NOT the translate every other row gets:
+        // `position: sticky` is resolved at layout time and a transform is
+        // paint-only, so under a translate the head would stick against the
+        // lane's un-translated box at the top of the list — observed as the
+        // row clamped to its lane's bottom edge, never pinning at all.
+        if (terminal && stickyPrompt && 'item' in row && row.item.kind === 'user') {
+          const next = promptRows.find((index) => index > virtualRow.index)
+          const laneEnd =
+            next === undefined
+              ? virtualizer.getTotalSize()
+              : (measurements[next]?.start ?? virtualRow.start)
+          return (
+            <StickyPromptLane
+              key={row.key}
+              top={virtualRow.start}
+              height={Math.max(laneEnd - virtualRow.start, 0)}
+              gapClass={gapClass}
+              scrollRoot={scrollElement}
+              index={virtualRow.index}
+              measureRef={virtualizer.measureElement}
+              content={content}
+            />
+          )
+        }
         return (
           <div
             key={row.key}
             ref={virtualizer.measureElement}
             data-index={virtualRow.index}
-            className={cn(
-              'absolute inset-x-0 top-0',
-              // The inter-row gap, folded into each row so the measured height
-              // carries it: flex `gap` cannot reach absolutely positioned rows,
-              // and a pixel constant for the virtualizer's `gap` option would
-              // drift from the rem the layout is set in. On this outer wrapper,
-              // not the row div, so a nested row's left border still breaks
-              // across the gap as it did under flex. Skipped for the first row —
-              // a gap above it would be padding, not spacing.
-              virtualRow.index > 0 && gap.className,
-            )}
+            className={cn('absolute inset-x-0 top-0', gapClass)}
             style={{ transform: `translateY(${virtualRow.start}px)` }}>
-            {'item' in row ? (
-              <div
-                className={cn(
-                  // Full-bleed hover: the row IS the affordance, so the
-                  // highlight has to reach past the content gutter.
-                  lines && '-mx-1 rounded-sm px-1 py-0.5 transition-colors hover:bg-surface-hover',
-                  // Already read: present, legible, and visibly behind you.
-                  boundary !== undefined && row.index < boundary && 'opacity-45',
-                  nestedClass(row.item, lines),
-                )}>
-                <TranscriptItemView
-                  item={row.item}
-                  fileUrl={fileUrl}
-                  attachmentUrl={attachmentUrl}
-                  hostImage={hostImage}
-                />
-              </div>
-            ) : (
-              <RecapRow line={row.line} since={since} />
-            )}
+            {content}
           </div>
         )
       })}
+      {/* The overview ruler, portalled beside the scroll element rather than
+          rendered as content: it must not scroll with the rows it maps. It
+          lives here, not in the shell above, because everything it draws from
+          — the virtualizer's offsets, the epoch, the row list, the jump — is
+          this component's. The portal target is the Conversation root
+          (`relative`), the same containing block the scroll button uses. */}
+      {terminal && scrubber && scrollElement?.parentElement
+        ? createPortal(
+            <TerminalScrubber
+              items={items}
+              pendingApprovals={pendingApprovals}
+              recapRow={recapRow}
+              bookmarks={scrubberMarks ?? []}
+              rowIndexFor={(itemIndex) => rowIndexForItem(rows, itemIndex)}
+              // The public memoized measurements array — `getTotalSize()` just
+              // above refreshed it, and with the calculator feeding
+              // `estimateSize` these starts are honest for unmounted rows too.
+              offsetOfRow={(rowIndex) => virtualizer.measurementsCache[rowIndex]?.start ?? 0}
+              sizeOfRow={(rowIndex) => virtualizer.measurementsCache[rowIndex]?.size ?? 0}
+              totalSize={virtualizer.getTotalSize()}
+              scrollOffset={virtualizer.scrollOffset ?? 0}
+              viewportH={virtualizer.scrollRect?.height ?? 0}
+              // To the top: a mark is where you start reading, not the middle of
+              // what you want to see.
+              onJumpToRow={(rowIndex) => jumpToRow(rowIndex, 'start')}
+              interactive={scrubInteractive}
+              fontSize={fontSize}
+              lineHeight={lineHeight}
+            />,
+            scrollElement.parentElement,
+          )
+        : null}
     </div>
   )
 }
@@ -544,9 +906,9 @@ export interface TranscriptProps {
    * on the host (codex's `image_gen`). Omit and those cards name the path. */
   hostImage?: (path: string) => Promise<string | undefined>
   /**
-   * How a turn is drawn: `cards` (default, the chat convention) or `lines` —
-   * full-width transparent line items with a gutter glyph, for hosts where
-   * vertical space is scarce. See {@link TranscriptVariant}.
+   * How a turn is drawn: `cards` (default, the chat convention) or `terminal`,
+   * which is not a set of branches in these components but its own renderer.
+   * See {@link TranscriptVariant}.
    */
   variant?: TranscriptVariant
   /**
@@ -555,6 +917,42 @@ export interface TranscriptProps {
    * {@link TranscriptVariant}. See {@link TranscriptDensity}.
    */
   density?: TranscriptDensity
+  /** Terminal theme only: the character cell, in whole pixels. See
+   * {@link TerminalSurface}. */
+  fontSize?: number
+  lineHeight?: number
+  /** Terminal theme only: the pointer affordances a real terminal cannot offer.
+   * `false` for none. See {@link TerminalAffordances}. */
+  affordances?: TerminalAffordances | boolean
+  /** Terminal theme only: hold the prompt of the turn being read at the top of
+   * the scroller. The *real* row is pinned, not a copy — see `TranscriptRows`. */
+  stickyPrompt?: boolean
+  /**
+   * Terminal theme only: mount the overview-ruler scrubber — a 2ch rail of
+   * marks (your prompts, each turn's response and result as one mark, errors,
+   * the pending approval, the catch-up boundary) that replaces the native
+   * scrollbar. Ignored under `cards`: the rail's positions ride the height
+   * calculator, which has no claim there. With `affordances={false}` the rail
+   * degrades to passive paint — no drag, peek or click — and the native
+   * scrollbar stays. See {@link TerminalScrubber}.
+   */
+  scrubber?: boolean
+  /**
+   * Bookmarked item indices, painted as full-width marks on the rail. Paint
+   * only, deliberately: the store — and the affordance that writes it — is
+   * the client's, the way the unread watermarks are, not the panel's.
+   */
+  scrubberMarks?: readonly number[]
+  /**
+   * The attach replay is still landing (`useClaudeSession().replaying`): rows
+   * render, measure and pin exactly as normal but nothing paints, and a loading
+   * line shows in their place; when it flips false the settled tail appears in
+   * one frame. Hiding is by *visibility*, never by not mounting — see the
+   * comment at the render site. Optional: an embedder that never passes it
+   * gets today's behaviour, and a short or empty session holds for no visible
+   * time at all (the frame between attach and replay-complete).
+   */
+  replaying?: boolean
   /**
    * Catch-up: `from` is how many items had been seen last time, `since` when
    * that was. A recap row is drawn at that boundary and everything above it is
@@ -570,6 +968,14 @@ export interface TranscriptProps {
    * catch-up strip never touch it. `null` while no transcript is mounted.
    */
   jumpToRecapRef?: RefObject<(() => void) | null>
+  /**
+   * Filled with a closure that re-pins the transcript to the bottom, so a host
+   * can resume following after the reader has scrolled away. The panel presses
+   * it on send: choosing to say something is choosing to watch what happens
+   * next, and a transcript left parked where you were reading makes a sent
+   * message look like it did nothing at all.
+   */
+  repinRef?: RefObject<(() => void) | null>
   className?: string
 }
 
@@ -581,33 +987,71 @@ export function Transcript({
   hostImage,
   variant = 'cards',
   density = 'comfortable',
+  fontSize,
+  lineHeight,
+  affordances,
+  stickyPrompt = false,
+  scrubber,
+  scrubberMarks,
+  replaying = false,
   catchUp,
   jumpToRecapRef,
+  repinRef,
   className,
 }: TranscriptProps) {
-  const lines = variant === 'lines'
+  const terminal = variant === 'terminal'
   const gap = ROW_GAP[variant][density]
   const runStartedAt = useRunStart(state.status)
-  const following = useSettled(state.items.length, state.status)
   // A boundary at (or past) the end means nothing is new — no row, no dimming.
+  //
+  // That "past the end" arm now also covers a `/clear`. The mark a client
+  // stored is an item index, and `conversation_reset` empties `items` while
+  // `activityCount` stays monotonic (it is an unread cursor, not an item count
+  // — a count that went backwards would silence the badge for good against a
+  // monotonic watermark store). So a session returned to after a clear has a
+  // boundary well past its few fresh rows and gets **no recap row**, which is
+  // the honest answer: an index into a conversation that no longer exists
+  // cannot say what you missed. Clamping it would land on `items.length` and
+  // read as "nothing is new" — the same outcome, told less truthfully.
   const boundary =
     catchUp && catchUp.from > 0 && catchUp.from < state.items.length ? catchUp.from : undefined
   const recap = useMemo(
     () => (boundary === undefined ? undefined : recapLine(summarizeSince(state, boundary))),
     [state, boundary],
   )
-  const rows = useMemo(() => {
-    const out: TranscriptRow[] = []
-    for (const [index, item] of state.items.entries()) {
-      if (index === boundary && recap) out.push({ key: 'recap', line: recap })
-      out.push({ key: `${item.kind}:${item.id}`, item, index })
-    }
-    return out
-  }, [state.items, boundary, recap])
+  const rows = useMemo<TranscriptRow[]>(() => {
+    const fold = (from: number, to: number) =>
+      terminalBlocks(state.items.slice(from, to), from, terminal)
+    if (boundary === undefined || !recap) return fold(0, state.items.length)
+    // Each side of the boundary folds separately, so a shell run never spans it:
+    // "what happened while you were away" must not hide inside a count that also
+    // covers what you have already read.
+    return [
+      ...fold(0, boundary),
+      { key: 'recap' as const, line: recap },
+      ...fold(boundary, state.items.length),
+    ]
+  }, [state.items, boundary, recap, terminal])
   return (
     <TranscriptVariantProvider value={variant}>
-      <Conversation className={className} resize={following ? 'smooth' : 'instant'}>
-        <ConversationContent className={cn(lines && 'gap-0 px-2 py-1.5')}>
+      {/* The replay hold hides by VISIBILITY, never by not mounting. The rows
+          must exist and lay out while hidden: the virtualizer measures them,
+          the height epoch builds, and the follow pin settles on the real
+          bottom — so the reveal is the removal of one style, a single paint of
+          an already-settled tail, and the catch-up jump always fires against a
+          measured list. (Unmounting instead would replay the entire
+          mount-measure-correct churn, visibly, at reveal time.) `visibility`
+          is the one hiding property a descendant can turn back ON, which is
+          how the loading line below stays visible inside a hidden root — and
+          the root is the right scope because the scrubber and the scroll
+          button portal/position into it, not into the scroller. */}
+      <Conversation className={cn(replaying && 'invisible', className)}>
+        <ConversationContent className={cn(terminal && 'gap-0 p-0')}>
+          <TerminalShell
+            active={terminal}
+            fontSize={fontSize}
+            lineHeight={lineHeight}
+            affordances={affordances}>
           {state.items.length === 0 && state.status !== 'starting' ? (
             <SessionEmptyState
               cwd={state.cwd}
@@ -620,24 +1064,87 @@ export function Transcript({
               rows={rows}
               boundary={boundary}
               since={catchUp?.since}
-              lines={lines}
+              terminal={terminal}
+              replaying={replaying}
+              stickyPrompt={stickyPrompt}
               gap={gap}
+              fontSize={fontSize}
+              lineHeight={lineHeight}
+              items={state.items}
+              pendingApprovals={state.pendingApprovals}
+              scrubber={scrubber}
+              scrubberMarks={scrubberMarks}
+              affordances={affordances}
               fileUrl={fileUrl}
               attachmentUrl={attachmentUrl}
               hostImage={hostImage}
               jumpToRecapRef={jumpToRecapRef}
+              repinRef={repinRef}
             />
           )}
           {showLoader(state) ? (
-            <Loader
-              label={state.status === 'starting' ? 'Starting session…' : undefined}
-              startedAt={runStartedAt}
-              tokens={state.contextUsage?.totalTokens}
-              className={cn(lines && 'py-0.5')}
-            />
+            terminal ? (
+              // The CLI's own working line, and it is a *row of the transcript*
+              // rather than a spinner floating over it — one blank line down,
+              // like every other block.
+              <>
+                {state.items.length > 0 ? <div className='term-blank' aria-hidden /> : null}
+                <WorkingRow
+                  label={state.status === 'starting' ? 'Starting…' : 'Working…'}
+                  startedAt={runStartedAt}
+                  tokens={state.contextUsage?.totalTokens}
+                />
+              </>
+            ) : (
+              <Loader
+                label={state.status === 'starting' ? 'Starting session…' : undefined}
+                startedAt={runStartedAt}
+                tokens={state.contextUsage?.totalTokens}
+              />
+            )
           ) : null}
+          </TerminalShell>
         </ConversationContent>
         <ConversationScrollButton />
+        {/* What shows while the hold is on — and for a normal attach that is
+            *nothing*. `wd-hold-appear` (theme.css) keeps it at `opacity: 0`
+            and fades it in only after 600ms, so a healthy ~0.5s hold unmounts
+            it before it ever paints. An unconditional line here was worse than
+            no hold at all: it appeared and vanished inside half a second, which
+            is the flicker the hold exists to remove, relocated to the top of
+            the panel. Only a genuinely slow attach earns a placeholder, which
+            is the case where a reader would otherwise think the panel is dead.
+            An overlay rather than a flow row
+            because the hidden content is at full height and pinned to its
+            bottom; a row in flow would sit at the bottom edge. It mirrors
+            `ConversationContent`'s wrapper (not the component itself — a
+            second `StickToBottom.Content` would steal the library's content
+            ref) so the paddings line up with the real rows'. */}
+        {replaying ? (
+          <div
+            data-slot='transcript-hold'
+            aria-hidden
+            className='wd-hold-appear visible pointer-events-none absolute inset-0 overflow-hidden'>
+            <div
+              className={cn(
+                'mx-auto w-full max-w-[var(--wd-content-max-w,48rem)]',
+                !terminal && 'px-4 py-4',
+              )}>
+              {terminal ? (
+                <TerminalSurface
+                  fontSize={fontSize}
+                  lineHeight={lineHeight}
+                  affordances={false}
+                  bleed='1ch'
+                  className='term-transcript'>
+                  <WorkingRow label='Loading…' />
+                </TerminalSurface>
+              ) : (
+                <Loader label='Loading session…' />
+              )}
+            </div>
+          </div>
+        ) : null}
       </Conversation>
     </TranscriptVariantProvider>
   )