@workerdeck/ui 0.23.0 → 1.0.0

package/src/components/terminal/blocks.ts

@@ -1,143 +1,31 @@
-/**
- * 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.
- */
+// `user` items carry `parentToolUseId` only optionally (only a subagent's brief has the key); the other kinds carry it as `string | null`.
 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[] {
+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
@@ -146,21 +34,12 @@ export type TaskBlock = {
   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)) {
@@ -168,7 +47,6 @@ function pushLeaf(out: LeafBlock[], item: TranscriptItem, index: number): void {
       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
@@ -176,20 +54,7 @@ function pushLeaf(out: LeafBlock[], item: TranscriptItem, index: number): void {
   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[] {
+export function terminalBlocks(items: readonly TranscriptItem[], offset = 0, fold = true): TerminalBlock[] {
   if (!fold) {
     return items.map((item, position) => ({
       key: `${item.kind}:${item.id}`,
@@ -198,21 +63,22 @@ export function terminalBlocks(
     }))
   }
 
-  // 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)
+    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 }])
+      if (list) {
+        list.push({ item, index: offset + position })
+      } else {
+        childrenOf.set(parent, [{ item, index: offset + position }])
+      }
     }
   })
 
@@ -220,13 +86,16 @@ export function terminalBlocks(
   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 (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)
+        for (const child of children) {
+          pushLeaf(folded, child.item, child.index)
+        }
         out.push({
           key: `task:${item.id}`,
           task: item,
@@ -242,18 +111,13 @@ export function terminalBlocks(
   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
+  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/diff.tsx

@@ -1,49 +1,24 @@
 import type { FilePatch, PatchHunk } from '@workerdeck/protocol'
 import { Row } from './row.tsx'
 
-/**
- * A file edit, drawn the way the CLI draws it: a right-aligned line-number
- * column, a one-column `+`/`-` marker, and the line — with added and removed
- * rows carrying a full-bleed wash.
- *
- * The line numbers are the engine's own, off the wire (protocol's
- * {@link FilePatch}). Nothing here computes one: this component has never seen
- * the file, and a number it invented would be worse than no number at all —
- * it would look authoritative and send the reader to the wrong line.
- *
- * The whole row — number, marker and text — is one {@link Row}, with the number
- * and marker as its gutter. That is what keeps a wrapped line hanging under the
- * text rather than under the numbers, and it is why the gutter width is computed
- * rather than fixed: a four-digit file and a two-digit one both put their first
- * character of code on a whole column.
- */
-
-/** Which side of the edit a body line belongs to, from its unified-diff prefix. */
 type LineKind = 'context' | 'add' | 'remove'
 
-const kindOf = (line: string): LineKind =>
-  line.startsWith('+') ? 'add' : line.startsWith('-') ? 'remove' : 'context'
+function kindOf(line: string): LineKind {
+  return line.startsWith('+') ? 'add' : line.startsWith('-') ? 'remove' : 'context'
+}
 
-/**
- * The rows of one hunk, each with the line number it has *in the file*.
- *
- * Two counters, because a diff is two files interleaved: an added line has a
- * number only in the new file, a removed line only in the old one, and context
- * advances both. Showing the new number for adds and the old number for removes
- * is what makes the column mean "where do I find this line", which is the only
- * reason to print it.
- */
 function hunkRows(hunk: PatchHunk): { kind: LineKind; number: number; text: string }[] {
   let oldLine = hunk.oldStart
   let newLine = hunk.newStart
   const rows = []
   for (const line of hunk.lines) {
     const kind = kindOf(line)
-    // The prefix is diff syntax, not content — the marker column says it now.
     const text = line.slice(1)
-    if (kind === 'add') rows.push({ kind, number: newLine++, text })
-    else if (kind === 'remove') rows.push({ kind, number: oldLine++, text })
-    else {
+    if (kind === 'add') {
+      rows.push({ kind, number: newLine++, text })
+    } else if (kind === 'remove') {
+      rows.push({ kind, number: oldLine++, text })
+    } else {
       rows.push({ kind, number: newLine, text })
       oldLine++
       newLine++
@@ -54,25 +29,20 @@ function hunkRows(hunk: PatchHunk): { kind: LineKind; number: number; text: stri
 
 const MARKER = { context: ' ', add: '+', remove: '-' } as const
 
-/**
- * A patch for a change that has **not happened yet** — an approval prompt's
- * `Edit`, where the input names the old and new text but no line numbers exist
- * because the edit has not been applied and this client has never read the file.
- *
- * `newStart: 0` is how it says so, and {@link TerminalDiff} reads that back: a
- * diff whose hunks all start at zero renders without a number column rather than
- * printing a column of zeroes or inventing an offset.
- */
 export function previewPatch(input: unknown): FilePatch | undefined {
   const edit = input as { file_path?: unknown; old_string?: unknown; new_string?: unknown } | null
   const before = typeof edit?.old_string === 'string' ? edit.old_string : undefined
   const after = typeof edit?.new_string === 'string' ? edit.new_string : undefined
-  if (before === undefined && after === undefined) return undefined
+  if (before === undefined && after === undefined) {
+    return undefined
+  }
   const lines = [
     ...(before ? before.split('\n').map((line) => `-${line}`) : []),
     ...(after ? after.split('\n').map((line) => `+${line}`) : []),
   ]
-  if (lines.length === 0) return undefined
+  if (lines.length === 0) {
+    return undefined
+  }
   return {
     ...(typeof edit?.file_path === 'string' && { path: edit.file_path }),
     hunks: [{ oldStart: 0, oldLines: 0, newStart: 0, newLines: 0, lines }],
@@ -81,47 +51,29 @@ export function previewPatch(input: unknown): FilePatch | undefined {
 
 export function TerminalDiff({ patch }: { patch: FilePatch }) {
   const rows = patch.hunks.map(hunkRows)
-  // Numbers only when the engine gave any (see `previewPatch`): a column of
-  // zeroes would look like line 0 of the file, which is a lie about where to
-  // look — and a diff with no numbers is honest about having none.
   const numbered = patch.hunks.some((hunk) => hunk.newStart > 0)
-  // Wide enough for the largest number any row will print, so the marker and the
-  // code start on the same column throughout — including across a hunk boundary,
-  // where the numbers jump.
   const width = numbered ? String(Math.max(...rows.flat().map((row) => row.number), 1)).length : 0
-  // number + space + marker + space (or just the marker and a space)
   const columns = numbered ? width + 3 : 2
 
   return (
-    <div className='term-diff'>
+    <div className="term-diff">
       {rows.map((hunk, index) => (
         <div key={index}>
-          {/* Hunks are not adjacent in the file, and a blank line would say they
-              were merely a paragraph apart. The CLI's separator is the honest
-              one: a row that says lines were skipped. */}
-          {index > 0 ? (
-            <Row columns={columns} glyph={' '.repeat(width) + ' ⋮'} tone='faint' />
-          ) : null}
+          {index > 0 ? <Row columns={columns} glyph={' '.repeat(width) + ' ⋮'} tone="faint" /> : null}
           {hunk.map((row, line) => (
             <Row
               key={line}
               columns={columns}
               data-diff={row.kind}
-              glyph={
-                numbered
-                  ? `${String(row.number).padStart(width)} ${MARKER[row.kind]}`
-                  : MARKER[row.kind]
-              }
-              // `pre-wrap` on the body already keeps the code's own indentation;
-              // an empty line still has to occupy its row, hence the space.
-              >
+              glyph={numbered ? `${String(row.number).padStart(width)} ${MARKER[row.kind]}` : MARKER[row.kind]}
+            >
               {row.text || ' '}
             </Row>
           ))}
         </div>
       ))}
       {patch.truncated ? (
-        <Row columns={columns} tone='faint'>
+        <Row columns={columns} tone="faint">
           … diff truncated
         </Row>
       ) : null}