@workerdeck/ui 0.16.0 → 0.17.0

package/src/components/terminal/blocks.ts

@@ -0,0 +1,232 @@
+/**
+ * The terminal theme's block model — **which rows exist**.
+ *
+ * Pure and separate from `items.tsx` because which rows exist is part of what
+ * the theme *is*: the virtualizer counts these, `height.ts` sizes them, the
+ * scrubber addresses them, and both renderers — the virtualized shell in
+ * `agent/Transcript.tsx` and the plain `TerminalTranscript` — must fold
+ * identically or two clients would be showing different transcripts of the
+ * same session. `items.tsx` re-exports everything here, so its old imports
+ * keep working; the components stay there, the model lives here.
+ *
+ * Two folds happen in one pass:
+ *
+ * - **Runs.** Consecutive tool calls fold into one row (`tool-run.ts` owns the
+ *   membership rule and the summary line).
+ * - **Tasks.** A `Task` tool call *absorbs* every item whose
+ *   `parentToolUseId` names it — its subagent's brief, thinking, text and
+ *   tool calls — into ONE row, **wherever those items fall in the stream**.
+ *   Subagents run in parallel, so their items interleave with each other and
+ *   with top-level work; a consecutive-run rule cannot group them, which is
+ *   why absorption is by parent id and not by adjacency. The absorbed items
+ *   are folded again *within* the block (a subagent's consecutive calls
+ *   become runs — `foldsTogether` already keys on `parentToolUseId`), and the
+ *   block is always collapsed by default: that preserves the height
+ *   calculator's invariant that an unmounted row is collapsed by definition.
+ *
+ * The absorption rule, precisely: a task block forms for a **top-level** tool
+ * call (`parentToolUseId` empty) that has at least one child in the slice,
+ * and an item is absorbed iff its parent is such a call. Everything else
+ * renders as its own row, which settles the edges deliberately:
+ *
+ * - A **childless** `Task` call is a plain tool call and folds into runs —
+ *   right for a task still spawning, and for a resumed session whose
+ *   children were compacted away entirely.
+ * - An **orphan** child (its parent call absent from the slice) keeps today's
+ *   behaviour: its own row, stepped in behind a rule. The recap boundary is
+ *   the load-bearing case — the shell folds each side separately, so a task
+ *   split by the boundary shows its post-boundary children *below* the seam
+ *   rather than hiding new work inside a collapsed row above it, the same
+ *   claim the run fold makes about never counting across "what you already
+ *   read".
+ * - A **grandchild** (parent is itself a subagent's call — unreachable from
+ *   today's engines, which do not nest sidechains) is not absorbed and not
+ *   dropped: it renders top-level, stepped in. An unmapped item must be
+ *   visible, never gone.
+ * - Two top-level calls separated only by absorbed items **fold together**:
+ *   the interleaved step was another frame's work, and once it is absorbed
+ *   the two calls are adjacent on screen — the count matches what the reader
+ *   sees.
+ */
+import type { TranscriptItem } from '@workerdeck/react'
+import { foldsTogether } from './tool-run.ts'
+
+export type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
+
+/**
+ * The id of the tool call this item was produced inside, or `undefined` at the
+ * top level. One spelling for both shapes the reducer emits: `assistant_text`
+ * / `thinking` / `tool_call` carry `parentToolUseId: string | null` on every
+ * instance, while `user` carries it **optionally** (a human prompt has no
+ * parent at all — the key exists only on a subagent's brief). Callers must go
+ * through this rather than reading the field, or the absent-key case silently
+ * types as a compile error on one kind and a miss on another.
+ */
+export function parentOf(item: TranscriptItem): string | undefined {
+  const parent = 'parentToolUseId' in item ? item.parentToolUseId : undefined
+  return parent ?? undefined
+}
+
+/** Is this a row the transcript folds into a run? Any tool call is — see
+ * `tool-run.ts` for why this is no longer shell-only. */
+export function isRunCall(item: TranscriptItem): item is ToolCallItem {
+  return item.kind === 'tool_call'
+}
+
+/** One transcript item as its own row. */
+export type ItemBlock = { key: string; item: TranscriptItem; index: number }
+/** A folded run of consecutive tool calls — one row for `run.length` items.
+ * At the top level its coverage is contiguous (`[index, index + run.length)`);
+ * inside a task block the members' global indices may be scattered (the run is
+ * consecutive in the *subagent's* stream, not the transcript's). */
+export type RunBlock = {
+  key: string
+  run: ToolCallItem[]
+  /** Every member's global transcript index, in stream order — `childIndices`'
+   * sibling, and needed for the same reason: a run folded across an absorbed
+   * gap has no `[index, index + len)` coverage, so a member's ordinal within
+   * the run (what the scrubber anchors a failure by) is unrecoverable from
+   * `index` arithmetic. */
+  indices: number[]
+  index: number
+}
+/** What a task block's children fold into. Never a task block itself — the
+ * engines do not nest sidechains, and a hypothetical grandchild renders
+ * top-level rather than vanishing (see the module comment). */
+export type LeafBlock = ItemBlock | RunBlock
+
+/**
+ * A `Task` call and everything produced inside it, as ONE row — collapsed by
+ * default, pressable to expand, the same shape as the folded tool run.
+ *
+ * - `task` is the call itself; `index` its own transcript index, which is the
+ *   row's address (rows stay ordered by `index`).
+ * - `children` are the absorbed items in stream order, folded exactly as
+ *   top-level rows are; each leaf's `index` is its first member's *global*
+ *   transcript index.
+ * - `childIndices` is the flat list of every absorbed item's global index, in
+ *   stream order. It exists because absorption is the one exception to row
+ *   contiguity: a child run's members can straddle other rows' starts, so no
+ *   `[start, start + len)` arithmetic can say what this row covers —
+ *   `rowIndexForItem` answers from this list instead.
+ */
+export type TaskBlock = {
+  key: string
+  task: ToolCallItem
+  children: LeafBlock[]
+  childIndices: number[]
+  index: number
+}
+
+/**
+ * Fold consecutive tool calls into runs and absorb subagent items into task
+ * blocks, leaving everything else alone.
+ */
+export type TerminalBlock = ItemBlock | RunBlock | TaskBlock
+
+/** The absorbed items, flat and in stream order — what `taskSummary` counts
+ * and the collapsed row's one line is built from. */
+export function taskChildItems(block: TaskBlock): TranscriptItem[] {
+  return block.children.flatMap((child) => ('run' in child ? child.run : [child.item]))
+}
+
+/** Append one item to a leaf-block list, folding it into the previous run when
+ * the membership rule allows — the one fold implementation, used for the
+ * top-level stream and for each task's children alike. */
+function pushLeaf(out: LeafBlock[], item: TranscriptItem, index: number): void {
+  const previous = out.at(-1)
+  if (isRunCall(item)) {
+    if (previous && 'run' in previous && foldsTogether(previous.run[0]!, item)) {
+      previous.run.push(item)
+      previous.indices.push(index)
+    } else {
+      // Keyed by the run's *first* call, so the key is stable as the run grows.
+      out.push({ key: `run:${item.id}`, run: [item], indices: [index], index })
+    }
+    return
+  }
+  out.push({ key: `${item.kind}:${item.id}`, item, index })
+}
+
+/**
+ * @param offset  What `items[0]`'s index is in the whole transcript — the
+ *   virtualized shell folds each side of the recap boundary separately, and the
+ *   rows still have to say where they sit for the catch-up dimming.
+ * @param fold    Whether to group at all. `false` gives one block per item —
+ *   no runs *and no task absorption* — which is what the cards variant
+ *   renders: this is the terminal theme's rule and must not silently reshape
+ *   another renderer's row list.
+ */
+export function terminalBlocks(
+  items: readonly TranscriptItem[],
+  offset = 0,
+  fold = true,
+): TerminalBlock[] {
+  if (!fold) {
+    return items.map((item, position) => ({
+      key: `${item.kind}:${item.id}`,
+      item,
+      index: offset + position,
+    }))
+  }
+
+  // Which top-level tool calls have children in this slice, and what those
+  // children are. Collected over the whole slice before any block is built:
+  // membership is by parent id, not adjacency, so a call cannot know it is a
+  // task until every item has been seen.
+  const topLevelCalls = new Set<string>()
+  for (const item of items) {
+    if (item.kind === 'tool_call' && parentOf(item) === undefined) topLevelCalls.add(item.id)
+  }
+  const childrenOf = new Map<string, { item: TranscriptItem; index: number }[]>()
+  items.forEach((item, position) => {
+    const parent = parentOf(item)
+    if (parent !== undefined && topLevelCalls.has(parent)) {
+      const list = childrenOf.get(parent)
+      if (list) list.push({ item, index: offset + position })
+      else childrenOf.set(parent, [{ item, index: offset + position }])
+    }
+  })
+
+  const out: TerminalBlock[] = []
+  for (const [position, item] of items.entries()) {
+    const index = offset + position
+    const parent = parentOf(item)
+    // Absorbed into its task's row — it must not also appear as its own.
+    if (parent !== undefined && childrenOf.has(parent)) continue
+    if (item.kind === 'tool_call') {
+      const children = childrenOf.get(item.id)
+      if (children) {
+        const folded: LeafBlock[] = []
+        for (const child of children) pushLeaf(folded, child.item, child.index)
+        out.push({
+          key: `task:${item.id}`,
+          task: item,
+          children: folded,
+          childIndices: children.map((child) => child.index),
+          index,
+        })
+        continue
+      }
+    }
+    pushLeaf(out as LeafBlock[], item, index)
+  }
+  return out
+}
+
+/** Spacing between two items: a blank line, unless the pair belongs together.
+ * Tool output already sits under its call, and a run of tool calls reads as one
+ * block — the CLI leaves no blank line inside either. */
+export function needsBlank(previous: TranscriptItem, next: TranscriptItem): boolean {
+  if (previous.kind === 'tool_call' && next.kind === 'tool_call') return false
+  return true
+}
+
+/** The same rule over blocks: a run counts as the tool calls it folded, and a
+ * task block counts as the `Task` call it stands for — a collapsed task row
+ * sits flush with the tool rows of the same turn, exactly as the call itself
+ * did before it grew children. */
+export function blockNeedsBlank(previous: TerminalBlock, next: TerminalBlock): boolean {
+  const kind = (block: TerminalBlock) => ('item' in block ? block.item.kind : 'tool_call')
+  return !(kind(previous) === 'tool_call' && kind(next) === 'tool_call')
+}

package/src/components/terminal/height.ts

@@ -6,9 +6,10 @@ import {
   formatDuration,
   toolInputPreview,
 } from '../../lib/format.ts'
-import type { TerminalBlock, ToolCallItem } from './items.tsx'
+import { taskChildItems, type TerminalBlock, type ToolCallItem } from './blocks.ts'
+import { IMAGE_BOX_LINES } from './image-box.ts'
 import { collapsedResult } from './result-preview.ts'
-import { runSummary } from './tool-run.ts'
+import { runSummary, taskSummary } from './tool-run.ts'
 
 /**
  * The terminal theme's row-height calculator.
@@ -37,6 +38,26 @@ import { runSummary } from './tool-run.ts'
  *   row is always collapsed — and an expanded row is by definition mounted,
  *   which means the virtualizer has its real measurement. There is no
  *   open/expanded branch here on purpose.
+ *
+ *   **This is a decided, permanent divergence from iOS**, not a gap anyone
+ *   should close. There (`apps/ios/WorkerDeckKit/.../TerminalExpansion.swift`)
+ *   nothing self-measures — a `UICollectionViewLayout` takes every frame from
+ *   the height book — so expansion has to be an *input to the planner*, and a
+ *   height the book does not know about is a frame the layout gets wrong. That
+ *   inversion is what lets the iOS scrubber be expansion-aware (a band over the
+ *   region you opened; a failed member of an *open* run marking on its own
+ *   line) and it is the one thing this client's rail cannot do. Lifting
+ *   expansion to shared state here to match would buy one rail feature and cost
+ *   this invariant — the central simplification of the whole calculator — so
+ *   the two clients share the *rule* and differ in how much of it each can see.
+ *
+ *   And the gap is entailed by **where the state can live**, not by how it is
+ *   plumbed: a paint-only registry would preserve this invariant, but web
+ *   expansion exists only while a row is *mounted*, so the rail it fed could
+ *   only ever band the rows currently on screen — the one place an overview
+ *   rail is useless, because the yellow wash is already visible there.
+ *   Said here as well as in the Swift, because this is the file where someone
+ *   would go looking to "fix" it.
  * - **Mutation is object replacement.** The transcript reducer never mutates an
  *   item in place — streaming text, a result arriving, a patch attaching each
  *   produce a new object — which is what lets {@link HeightEpoch}'s cache key on
@@ -97,7 +118,13 @@ export function createHeightEpoch(width: number, ch: number, line: number): Heig
  * The inter-row gap is the *pair's* business (`gapBefore`), not the row's, so
  * it is added by the caller. */
 export function estimateBlockPx(block: TerminalBlock, epoch: HeightEpoch): number {
-  if ('run' in block) return blockHeight(block, epoch).px
+  // Only item blocks cache. A run's array is rebuilt every render, so its
+  // identity is worthless as a key — and a task block must not key on its
+  // `task` item either: children arrive without the call object changing (the
+  // reducer replaces the *child*), so a height cached against the task would
+  // survive exactly the mutation that changes the summary line. Both are one
+  // `wrapOne` over a short string (~2µs), so neither needs the cache.
+  if (!('item' in block)) return blockHeight(block, epoch).px
   const hit = epoch.cache.get(block.item)
   if (hit) return hit.px
   const computed = itemHeight(block.item, epoch)
@@ -653,6 +680,15 @@ function toolRowHeight(item: ToolCallItem, m: CellMetrics, extraPx: number): Acc
   const backend = item.backend && item.backend !== 'server' ? ` · ${item.backend}` : ''
   let acc = rowH(`${item.name}(${preview})${backend}`, m, { gutterCells: 2, extraPx })
 
+  // Each replayed image part draws a box of whole lines, and it draws it in
+  // every state — placeholder, picture, failure — so the height is settled
+  // before the first byte is asked for and the load can never reflow the list.
+  // No wrap and no `exact: false`: the box is the constant, not the image (see
+  // `image-box.ts`).
+  const images = item.result?.images
+  if (images?.length)
+    acc = add(acc, { px: images.length * IMAGE_BOX_LINES * m.line, exact: true })
+
   if (item.patch) return add(acc, diffHeight(item.patch, m, extraPx))
   const text = item.result?.text ?? ''
   if (!text) return acc
@@ -660,7 +696,7 @@ function toolRowHeight(item: ToolCallItem, m: CellMetrics, extraPx: number): Acc
   // the lines and the exact trailing label, so this cannot drift from what
   // `items.tsx` draws — which it previously could, and which its own comment
   // said only the dev audit was catching.
-  const { shown, more } = collapsedResult(text.trimEnd().split('\n'))
+  const { shown, more } = collapsedResult(text.trimEnd().split('\n'), item.result?.totalChars)
   for (const line of shown) {
     // indent=1 with columns=3 resolves the indent against the row's own
     // --term-cell: 3ch of padding + 3ch of gutter.
@@ -716,9 +752,16 @@ export function itemHeight(item: TranscriptItem, m: CellMetrics): ComputedHeight
   }
 }
 
-/** A virtual row's height: an item, or a folded tool run (collapsed = its one
- * summary line, built by the same function the row draws). */
+/** A virtual row's height: an item, a folded tool run, or a task block —
+ * either fold collapsed is its one summary line, built by the same function
+ * the row draws (`runSummary` / `taskSummary`), rendered as one standard
+ * 2-cell-gutter `Row`. No expanded branch for the task block either: it is
+ * always collapsed by default, which is the invariant that keeps every
+ * unmounted row's estimate exact. */
 export function blockHeight(block: TerminalBlock, m: CellMetrics): ComputedHeight {
+  if ('task' in block) {
+    return rowH(taskSummary(block.task, taskChildItems(block)), m)
+  }
   if ('run' in block) {
     const busy = block.run.some((item) => item.status === 'running' || item.status === 'pending')
     return rowH(runSummary(block.run, busy), m)

package/src/components/terminal/image-box.ts

@@ -0,0 +1,53 @@
+import { formatBytes } from '../../lib/format.ts'
+
+/**
+ * The box a tool result's image is drawn in, and the words drawn in it before
+ * the bytes arrive.
+ *
+ * Its own module, and pure, for `result-preview.ts`'s reason with a constant
+ * standing where a string stood: `items.tsx` draws these boxes and `height.ts`
+ * predicts their pixel height for the virtualizer's `estimateSize` without a
+ * DOM. Two spellings of the box would be two different heights, and the row
+ * would grow or shrink the moment it mounted.
+ *
+ * **A fixed box, sized in whole lines, reserved from plan time.** An image's
+ * intrinsic dimensions are not knowable before its bytes are, and the
+ * alternative — an `exact: false` row corrected on mount — would demote *most*
+ * rows of an image-bearing session to estimates and bring back the growing
+ * scrollbar the calculator exists to kill. A box that does not depend on what is
+ * inside it is exact by definition, at the cost of some letterboxing.
+ */
+
+/**
+ * Whole lines per image. 12 ≈ 240px at an 18px line — big enough that a
+ * screenshot is legible as *what it is* (which is the whole reason images became
+ * visible at all), small enough that a call returning four of them does not
+ * become a screenful.
+ */
+export const IMAGE_BOX_LINES = 12
+
+/**
+ * What the box says before the fetch lands.
+ *
+ * `bytes` is the decoded size the gateway stamped on the reference — the client
+ * holds no bytes at all until it asks for them, so this is a number it cannot
+ * compute, the same reason `total_chars` rides beside a truncated head.
+ * `formatBytes` rather than a spelling of its own: the panel says "336.0 KB"
+ * everywhere else, and a second byte formatter is a second thing to keep in
+ * step.
+ */
+export function imagePlaceholder(image: { bytes: number }): string {
+  return `image · ${formatBytes(image.bytes)}`
+}
+
+/**
+ * What it says when the fetch failed — a stale address after a dormant wake
+ * (the route 404s rather than serving another call's pixels), a gateway too old
+ * to know the route, a dropped connection.
+ *
+ * It occupies the same box, because the alternative is the row changing height
+ * on a network failure. Silence is not an option here the way it is for
+ * `HostImage`: that card names the host path in its result text, so a reader can
+ * still find the picture; a replayed image part has no path to name.
+ */
+export const IMAGE_UNAVAILABLE = 'image unavailable'

package/src/components/terminal/items.tsx

@@ -7,10 +7,32 @@ import { CopyAction, WithActions } from './affordances.tsx'
 import { TerminalDiff } from './diff.tsx'
 import { TerminalMarkdown } from './markdown.tsx'
 import { Pressable, useRevealOnOpen } from './press.tsx'
+import { IMAGE_BOX_LINES, IMAGE_UNAVAILABLE, imagePlaceholder } from './image-box.ts'
 import { collapsedResult } from './result-preview.ts'
-import { foldsTogether, runSummary } from './tool-run.ts'
+import { useToolResultFetcher } from '../agent/tool-result-fetch.tsx'
+import { useToolResultImageSrc } from '../agent/tool-result-image.tsx'
+import { runFailed, runSummary } from './tool-run.ts'
+import { type ToolCallItem } from './blocks.ts'
 import { Band, Blank, Ink, Row, type Tone } from './row.tsx'
 
+// The pure block model — which rows exist — lives in `blocks.ts` now that a
+// task block made it non-trivial; re-exported here because this file is where
+// consumers have always found it.
+export {
+  blockNeedsBlank,
+  isRunCall,
+  needsBlank,
+  parentOf,
+  taskChildItems,
+  terminalBlocks,
+  type ItemBlock,
+  type LeafBlock,
+  type RunBlock,
+  type TaskBlock,
+  type TerminalBlock,
+  type ToolCallItem,
+} from './blocks.ts'
+
 /**
  * One transcript item, drawn as terminal rows.
  *
@@ -44,8 +66,13 @@ import { Band, Blank, Ink, Row, type Tone } from './row.tsx'
 export const PROMPT_GLYPH = '❯'
 
 /** How much the expanded row shows before offering the rest. The collapsed
- * budget is `collapsedResult`'s, shared with the height calculator. */
-const RESULT_PREVIEW_CHARS = 2000
+ * budget is `collapsedResult`'s, shared with the height calculator.
+ *
+ * Exported for one test and not from the package: protocol's
+ * `TOOL_RESULT_HEAD_CHARS` is chosen to exceed it, so that a truncated result's
+ * open state is byte-identical to an untruncated one and only the uncapped
+ * `full` press ever fetches. That relationship is asserted, not assumed. */
+export const RESULT_PREVIEW_CHARS = 2000
 
 /** Whole lines up to a character budget — never zero, because a single line
  * longer than the budget still has to be shown or the row would open onto
@@ -122,11 +149,14 @@ const TOOL_TONE: Record<string, Tone> = {
   failed: 'red',
 }
 
-export type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
-
 export function ToolRow({ item }: { item: ToolCallItem }) {
   const [open, setOpen] = useState(false)
   const [full, setFull] = useState(false)
+  // Set while the rest of a truncated result is in flight. Row-local, unlike the
+  // text itself, which lands in transcript state — this is a spinner, not a
+  // fact about the session.
+  const [fetching, setFetching] = useState(false)
+  const fetchResult = useToolResultFetcher()
   const reveal = useRevealOnOpen(open)
   const status = item.status ?? (item.result === undefined ? 'running' : 'settled')
   const busy = status === 'running' || status === 'pending'
@@ -144,7 +174,9 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
   // the virtualizer mounts rows, so it cannot help with what is inside a single
   // one. Without the clip, expanding one row commits thousands of DOM nodes and
   // the transcript stops being smooth for the rest of the session.
-  const collapsed = collapsedResult(lines)
+  // The true total when the replay delivered only a head — the row must count
+  // what is missing, not what it happens to hold.
+  const collapsed = collapsedResult(lines, item.result?.totalChars)
   const preview = open
     ? full
       ? lines
@@ -152,6 +184,11 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
     : collapsed.shown
   const hidden = lines.length - preview.length
   const clipped = open && !full && hidden > 0
+  // The replay sent a head. `full` then means "fetch the rest", not "lift the
+  // clip" — and the marker outlives the clip, because a head short enough to fit
+  // the open budget still is not the result.
+  const truncated = item.result?.truncated === true
+  const missing = truncated ? (item.result?.totalChars ?? 0) - text.length : 0
 
   const tone: Tone = isError
     ? 'red'
@@ -184,6 +221,13 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
           ) : null}
         </Row>
       </Pressable>
+      {/* Above the output, because when a call returned a picture the picture is
+          what the call was: a screenshot's result text is "took a screenshot".
+          Drawn collapsed as well as open — this is not detail behind a press,
+          it is the answer. */}
+      {item.result?.images?.map((image) => (
+        <TerminalImage key={image.partIndex} toolUseId={item.id} image={image} />
+      ))}
       {/* A file edit shows its diff, not its result prose: "The file has been
           updated" is what the *model* needed to hear, and the change is what the
           reader did. The text stays reachable by expanding. */}
@@ -214,15 +258,30 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
                 {collapsed.more}
               </Row>
             ) : null
-          ) : hidden > 0 ? (
+          ) : clipped || truncated ? (
             <Row indent={1} columns={3} tone='faint'>
-              {clipped ? (
+              {fetching ? (
+                // Never a row that does nothing when pressed: it says what it is
+                // doing instead. See `planToolCall`'s comment on the same rule.
+                <>… fetching {(item.result?.totalChars ?? 0).toLocaleString()} chars</>
+              ) : clipped || truncated ? (
                 <button
                   type='button'
                   className='term-press term-link'
-                  onClick={() => setFull(true)}>
-                  … +{hidden} line{hidden === 1 ? '' : 's'} — show all{' '}
-                  {text.length.toLocaleString()} chars
+                  onClick={() => {
+                    // One press, two acts, in the order that keeps the row
+                    // honest: lift the clip immediately (that part is local and
+                    // instant), and fetch the rest when there is a rest. The
+                    // fetched text lands in transcript state, so the row
+                    // re-renders with the marker gone.
+                    setFull(true)
+                    if (!truncated) return
+                    setFetching(true)
+                    void fetchResult(item.id).finally(() => setFetching(false))
+                  }}>
+                  {truncated
+                    ? `… +${missing.toLocaleString()} chars — fetch the rest`
+                    : `… +${hidden} line${hidden === 1 ? '' : 's'} — show all ${text.length.toLocaleString()} chars`}
                 </button>
               ) : (
                 <>
@@ -230,6 +289,10 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
                 </>
               )}
             </Row>
+          ) : hidden > 0 ? (
+            <Row indent={1} columns={3} tone='faint'>
+              … +{hidden} line{hidden === 1 ? '' : 's'}
+            </Row>
           ) : null}
         </>
       ) : null}
@@ -238,10 +301,41 @@ export function ToolRow({ item }: { item: ToolCallItem }) {
   )
 }
 
-/** Is this a row the transcript folds into a run? Any tool call is — see
- * `tool-run.ts` for why this is no longer shell-only. */
-export function isRunCall(item: TranscriptItem): item is ToolCallItem {
-  return item.kind === 'tool_call'
+/** One image part of a tool result, as the reducer holds it. */
+type ToolResultImage = NonNullable<NonNullable<ToolCallItem['result']>['images']>[number]
+
+/**
+ * A picture a tool returned, in a box of {@link IMAGE_BOX_LINES} whole lines.
+ *
+ * **Three states, one height.** Before the fetch lands the box is a wash and the
+ * size the gateway declared; after it, the picture, letterboxed inside the same
+ * box; on a refusal, `image unavailable` in it. Nothing here may ever collapse
+ * to nothing — that is `HostImage`'s return-null-then-pop, which in a
+ * *virtualized* list is not a flicker but a reflow of every row below it, and
+ * the height calculator would have been lying about the row from plan time.
+ *
+ * The box is why the calculator can stay exact: it is a constant, not a function
+ * of pixels nobody has downloaded yet.
+ */
+function TerminalImage({ toolUseId, image }: { toolUseId: string; image: ToolResultImage }) {
+  const { src, failed } = useToolResultImageSrc({ toolUseId, ...image })
+  return (
+    <Row indent={1} columns={3}>
+      <div
+        className='term-image'
+        data-state={src ? 'loaded' : failed ? 'failed' : 'pending'}
+        // The one measurement in this file, and it is the shared constant
+        // spelled once — `height.ts` adds exactly this many lines for exactly
+        // this box.
+        style={{ height: `calc(var(--term-line) * ${IMAGE_BOX_LINES})` }}>
+        {src ? (
+          <img src={src} alt={imagePlaceholder(image)} />
+        ) : (
+          <Ink tone='faint'>{failed ? IMAGE_UNAVAILABLE : imagePlaceholder(image)}</Ink>
+        )}
+      </div>
+    </Row>
+  )
 }
 
 /**
@@ -254,10 +348,11 @@ export function isRunCall(item: TranscriptItem): item is ToolCallItem {
  * collapses to its count and gets out of the way — and opens, in full, the
  * moment it is the thing you actually want.
  *
- * The membership and wording rules live in `tool-run.ts`, shared with the height
- * calculator. A failed member does not break the run — it *colours* it, which is
- * the same call the scrubber makes: a failure is worth seeing, and fragmenting
- * the run around it would hide it in a longer list rather than surface it.
+ * The membership, wording and failure rules live in `tool-run.ts`, shared with
+ * the height calculator. A failure never breaks the run — fragmenting it around
+ * one would hide the failure in a longer list rather than surface it — but only
+ * the run's **last** call colours it, because that is the run's outcome and an
+ * outcome is what a collapsed row can honestly claim (see `runFailed`).
  */
 export function ToolRunRow({ items }: { items: ToolCallItem[] }) {
   const [open, setOpen] = useState(false)
@@ -266,7 +361,7 @@ export function ToolRunRow({ items }: { items: ToolCallItem[] }) {
     const status = item.status ?? (item.result === undefined ? 'running' : 'settled')
     return status === 'running' || status === 'pending'
   })
-  const failed = items.some((item) => item.status === 'failed' || item.result?.isError === true)
+  const failed = runFailed(items)
   const pulse = usePulse(busy)
 
   return (
@@ -293,49 +388,6 @@ export function ToolRunRow({ items }: { items: ToolCallItem[] }) {
   )
 }
 
-/**
- * Fold consecutive tool calls into runs, leaving everything else alone.
- *
- * Shared by both renderers — the virtualized shell in `agent/Transcript.tsx` and
- * the plain {@link TerminalTranscript} — because which rows exist is part of what
- * the theme *is*, and a client that grouped differently would be showing a
- * different transcript of the same session.
- */
-export type TerminalBlock =
-  | { key: string; item: TranscriptItem; index: number }
-  | { key: string; run: ToolCallItem[]; index: number }
-
-/**
- * @param offset  What `items[0]`'s index is in the whole transcript — the
- *   virtualized shell folds each side of the recap boundary separately, and the
- *   rows still have to say where they sit for the catch-up dimming.
- * @param fold    Whether to group at all. `false` gives one block per item,
- *   which is what the cards variant renders: this is the terminal theme's rule
- *   and must not silently reshape another renderer's row list.
- */
-export function terminalBlocks(
-  items: readonly TranscriptItem[],
-  offset = 0,
-  fold = true,
-): TerminalBlock[] {
-  const out: TerminalBlock[] = []
-  for (const [position, item] of items.entries()) {
-    const index = offset + position
-    const previous = out.at(-1)
-    if (fold && isRunCall(item)) {
-      if (previous && 'run' in previous && foldsTogether(previous.run[0]!, item)) {
-        previous.run.push(item)
-      } else {
-        // Keyed by the run's *first* call, so the key is stable as the run grows.
-        out.push({ key: `run:${item.id}`, run: [item], index })
-      }
-      continue
-    }
-    out.push({ key: `${item.kind}:${item.id}`, item, index })
-  }
-  return out
-}
-
 export function TurnResultRow({
   item,
 }: {
@@ -431,19 +483,4 @@ export function WorkingRow({
   )
 }
 
-/** Spacing between two items: a blank line, unless the pair belongs together.
- * Tool output already sits under its call, and a run of tool calls reads as one
- * block — the CLI leaves no blank line inside either. */
-export function needsBlank(previous: TranscriptItem, next: TranscriptItem): boolean {
-  if (previous.kind === 'tool_call' && next.kind === 'tool_call') return false
-  return true
-}
-
-/** The same rule over blocks: a shell run counts as the tool calls it folded. */
-export function blockNeedsBlank(previous: TerminalBlock, next: TerminalBlock): boolean {
-  const before = 'run' in previous ? 'tool_call' : previous.item.kind
-  const after = 'run' in next ? 'tool_call' : next.item.kind
-  return !(before === 'tool_call' && after === 'tool_call')
-}
-
 export { Band, Blank }