@workerdeck/ui 0.16.0 → 0.18.0

package/src/components/terminal/blocks.ts

@@ -0,0 +1,260 @@
+/**
+ * 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
+}
+
+/**
+ * **The frame membership rule**: the items a sub-agent produced, and nothing
+ * else — what the takeover renders instead of the whole conversation.
+ *
+ * One exported function rather than a `filter` at each call site, because this
+ * is a rule two renderers have to agree on: iOS mirrors the terminal model out
+ * of this module, and a phone that framed a sub-agent slightly differently would
+ * be a second answer to "what is this agent doing".
+ *
+ * It picks up the brief (a `user` item *with* a parent), the thinking, the
+ * streamed text (deltas are namespaced per sidechain, so `streaming:<parentId>`
+ * carries the parent like any other item), every tool call with its result, and
+ * the final report. It excludes the spawning `Task` call itself — that is the
+ * frame, not a row in it — and every other agent's work.
+ *
+ * The slice is safe to hand straight to {@link terminalBlocks} at offset 0:
+ * nothing in it is top-level, so nothing absorbs, and consecutive calls still
+ * fold into runs because {@link foldsTogether} keys on an *equal* parent rather
+ * than on absence of one. Row indices are internally consistent because the rows
+ * and the `items` they came from are the same array.
+ */
+export function subagentItems(
+  items: readonly TranscriptItem[],
+  parentToolUseId: string,
+): TranscriptItem[] {
+  return items.filter((item) => parentOf(item) === parentToolUseId)
+}
+
+/** 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)
@@ -105,6 +132,30 @@ export function estimateBlockPx(block: TerminalBlock, epoch: HeightEpoch): numbe
   return computed.px
 }
 
+/**
+ * How many lines of a sub-agent's brief the collapsed row shows.
+ *
+ * Four, and the number is a judgement rather than a measurement: a brief runs
+ * to thousands of characters, and an uncapped one buries the work it was asking
+ * for under its own instructions. Four is enough to recognise the task and
+ * short enough that the agent's first line stays on screen beside it.
+ */
+export const BRIEF_LINES = 4
+
+/**
+ * The collapsed brief row's height — the frame's first row, which is synthetic
+ * and so cannot go through {@link estimateBlockPx}.
+ *
+ * Clipped, so it is `min(wrapped, BRIEF_LINES)` lines plus the row the header
+ * occupies. Expanding is local state on a *mounted* row, which the virtualizer
+ * re-measures; what has to be right before it mounts is the collapsed height,
+ * exactly as a task row is always collapsed when unmounted for the same reason.
+ */
+export function briefPx(text: string, m: CellMetrics): number {
+  const cols = Math.max(1, Math.floor(m.width / m.ch + EPS))
+  return (Math.min(textLines(text, cols).lines, BRIEF_LINES) + 1) * m.line
+}
+
 /** Measure the advance of `0` on the live surface. A DOM read — call it from
  * the epoch's measurement pass (an effect / ResizeObserver callback), never
  * from render. The probe is absolutely positioned, so it contributes no layout
@@ -653,6 +704,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 +720,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 +776,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'