@workerdeck/ui 0.15.0 → 0.17.0

package/src/components/terminal/affordances.tsx

@@ -0,0 +1,118 @@
+import { createContext, useContext, useState, type ReactNode } from 'react'
+import { cn } from '../../lib/utils.ts'
+
+/**
+ * The things a terminal cannot do, and this can.
+ *
+ * The theme's whole discipline is that it renders like a CLI — but it is not a
+ * CLI, and refusing every affordance a pointer makes possible would be cosplay
+ * rather than design. A terminal cannot highlight the row under your cursor and
+ * cannot put a copy button on a block of output; a web view can do both for free
+ * and they are genuinely useful.
+ *
+ * The rule that keeps this honest is that **each one costs no layout**. A hover
+ * fill is a background. An action button is an overlay at the row's right edge,
+ * one line tall, absolutely positioned so it displaces nothing. Turn them all
+ * off and every glyph is on exactly the same cell it was on — which is what
+ * makes `off` a real option rather than a degraded mode, and why it is the mode
+ * a host projecting to a real terminal would choose.
+ *
+ * Off by nothing in particular: both default **on**, because the surface these
+ * render on is a browser and pretending otherwise helps nobody. A host that
+ * wants the pure article passes `affordances={false}`.
+ */
+export type TerminalAffordances = {
+  /** Fill the row under the pointer, on anything pressable. */
+  hover?: boolean
+  /** Reveal a row's actions (copy, and whatever a row adds) on hover or focus. */
+  actions?: boolean
+}
+
+const DEFAULTS: Required<TerminalAffordances> = { hover: true, actions: true }
+
+const AffordanceContext = createContext<Required<TerminalAffordances>>(DEFAULTS)
+
+export function useAffordances(): Required<TerminalAffordances> {
+  return useContext(AffordanceContext)
+}
+
+/** Resolve the surface's prop — `false` means none, `true`/absent means all. */
+export function resolveAffordances(
+  value: TerminalAffordances | boolean | undefined,
+): Required<TerminalAffordances> {
+  if (value === false) return { hover: false, actions: false }
+  if (value === true || value === undefined) return DEFAULTS
+  return { ...DEFAULTS, ...value }
+}
+
+export function AffordanceProvider({
+  value,
+  children,
+}: {
+  value: Required<TerminalAffordances>
+  children: ReactNode
+}) {
+  return <AffordanceContext.Provider value={value}>{children}</AffordanceContext.Provider>
+}
+
+/**
+ * A block that reveals its actions on hover.
+ *
+ * Wraps rather than decorates because the actions belong to the *block* — a
+ * message is many rows and its copy button belongs at the top right of all of
+ * them, not on whichever row the pointer happens to be over.
+ */
+export function WithActions({
+  actions,
+  children,
+  className,
+}: {
+  actions: ReactNode
+  children: ReactNode
+  className?: string
+}) {
+  const { actions: enabled } = useAffordances()
+  if (!enabled) return <>{children}</>
+  return (
+    <div className={cn('term-hoverable', className)}>
+      {children}
+      <div className='term-actions'>{actions}</div>
+    </div>
+  )
+}
+
+/**
+ * Copy, as a character.
+ *
+ * `⧉` and `✓` rather than an SVG for the same reason the rest of the theme uses
+ * glyphs: an icon drawn at some other size sits between the cells everything
+ * else is on, and reads as a button borrowed from another application. The tick
+ * replaces the glyph in place, so the confirmation costs no width either.
+ */
+export function CopyAction({ text, label = 'Copy' }: { text: string; label?: string }) {
+  const [copied, setCopied] = useState(false)
+  return (
+    <button
+      type='button'
+      className='term-action'
+      title={label}
+      aria-label={label}
+      onClick={(event) => {
+        // The row underneath is usually pressable (a tool call expands); copying
+        // is not expanding.
+        event.stopPropagation()
+        void navigator.clipboard
+          ?.writeText(text)
+          .then(() => {
+            setCopied(true)
+            setTimeout(() => setCopied(false), 1200)
+          })
+          // No toast, no error row: a refused clipboard (an insecure origin, a
+          // denied permission) is the host's business, and a failed copy that
+          // says nothing is better than a transcript that grows an error.
+          .catch(() => {})
+      }}>
+      {copied ? '✓' : '⧉'}
+    </button>
+  )
+}

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/diff.tsx

@@ -0,0 +1,130 @@
+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'
+
+/**
+ * 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 {
+      rows.push({ kind, number: newLine, text })
+      oldLine++
+      newLine++
+    }
+  }
+  return rows
+}
+
+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
+  const lines = [
+    ...(before ? before.split('\n').map((line) => `-${line}`) : []),
+    ...(after ? after.split('\n').map((line) => `+${line}`) : []),
+  ]
+  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 }],
+  }
+}
+
+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'>
+      {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}
+          {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.
+              >
+              {row.text || ' '}
+            </Row>
+          ))}
+        </div>
+      ))}
+      {patch.truncated ? (
+        <Row columns={columns} tone='faint'>
+          … diff truncated
+        </Row>
+      ) : null}
+    </div>
+  )
+}