@workerdeck/ui 0.15.0 → 0.17.0

package/src/components/agent/transcript-rows.ts

@@ -0,0 +1,173 @@
+/**
+ * The virtual row model: what one row of the transcript's virtual list *is*,
+ * and the two rules everything positional must go through — which item a row
+ * is spaced as, and how an item index maps onto a row index. Pure; shared by
+ * the transcript shell and its hooks.
+ */
+import type { TranscriptItem } from '@workerdeck/react'
+import { needsBlank, type TerminalBlock } from '../terminal/items.tsx'
+
+/** One row of the virtual list: a {@link TerminalBlock} (a transcript item,
+ * — under the terminal theme — a folded run of tool calls, or a task block
+ * standing for a `Task` call and everything its subagent produced), or the
+ * recap boundary line spliced in at `catchUp.from`. One flat array so the
+ * virtualizer sees stable indices, and each row carries the key the item was
+ * already React-keyed by — measurements are cached per key, so a row keeps its
+ * measured height when the recap splice shifts every index after it. */
+export type TranscriptRow = TerminalBlock | { key: 'recap'; line: string }
+
+/** The item a row is spaced *as*. A run stands for the calls it folded, and a
+ * task block for the `Task` call it absorbed into — all tool calls, so a run,
+ * a task and a lone tool call below them still read as one block. */
+export function rowItem(row: TranscriptRow | undefined): TranscriptItem | undefined {
+  if (!row) return undefined
+  if ('item' in row) return row.item
+  if ('run' in row) return row.run[0]
+  if ('task' in row) return row.task
+  return undefined
+}
+
+/**
+ * Does a blank line go above this row, in the terminal theme?
+ *
+ * The recap row always earns one — it is a boundary, and a boundary flush
+ * against the row above reads as part of it. Otherwise the pair decides
+ * (`needsBlank`): consecutive tool calls are one block in the CLI and get none.
+ */
+export function gapBefore(rows: TranscriptRow[], index: number): boolean {
+  const before = rowItem(rows[index - 1])
+  const after = rowItem(rows[index])
+  if (!before || !after) return true
+  return needsBlank(before, after)
+}
+
+/**
+ * Which items each task block absorbed, as itemIndex → rowIndex — the one
+ * lookup {@link rowIndexForItem} cannot answer from ordering (see its comment).
+ * Memoized per rows array identity: the shell builds `rows` in a `useMemo`, so
+ * within one row list this is built once, and a WeakMap means a discarded list
+ * takes its map with it. Memoization only — the answer is a pure function of
+ * the array.
+ */
+const absorbedCache = new WeakMap<readonly TranscriptRow[], Map<number, number>>()
+
+function absorbedRows(rows: readonly TranscriptRow[]): Map<number, number> {
+  const hit = absorbedCache.get(rows)
+  if (hit) return hit
+  const map = new Map<number, number>()
+  rows.forEach((row, rowIndex) => {
+    if ('task' in row) for (const itemIndex of row.childIndices) map.set(itemIndex, rowIndex)
+  })
+  absorbedCache.set(rows, map)
+  return map
+}
+
+/**
+ * Transcript-item index → virtual-row index — **the off-by-a-fold trap.**
+ *
+ * The virtualizer's rows are {@link TerminalBlock}s, not items: a folded tool
+ * run occupies ONE row for `run.length` consecutive items, a task block
+ * occupies ONE row for its `Task` call *plus every item its subagent produced*,
+ * and the recap boundary is a row with *no* item index at all, shifting every
+ * row after it by one. `virtualizer.scrollToIndex(itemIndex)` is therefore
+ * wrong by construction on any folded or spliced transcript — every jump that
+ * starts from an item (the scrubber's marks, a future bookmark) must come
+ * through here first.
+ *
+ * The contract, in two halves:
+ *
+ * - An index a task block **absorbed** maps to that block's row, wherever the
+ *   child fell in the stream. Subagents run in parallel, so absorbed indices
+ *   interleave arbitrarily with later rows' starts — no ordering argument can
+ *   find their row, which is why they are answered first, from a per-row-list
+ *   map ({@link absorbedRows}) built once per rows array. A row's coverage is
+ *   its `childIndices`, never `[index, index + N)` arithmetic.
+ * - Every other index maps to the **last non-recap row whose start (`index`)
+ *   is ≤ the target** — the original rule, still a binary search. Rows stay
+ *   ordered by `index`, and the ordering argument is now: between one row's
+ *   start and the next row's, every index is either absorbed (answered above)
+ *   or a member of the earlier row — note that is *weaker* than the old
+ *   contiguity claim, because a run can fold across an absorbed gap (two
+ *   top-level calls separated only by a subagent's step are adjacent on
+ *   screen), so `[index, index + run.length)` arithmetic no longer describes
+ *   a run's coverage; membership does. The recap row is skipped by giving it
+ *   its successor's start for navigation (both qualify at the boundary, and
+ *   "last wins" lands on the real row) while never letting it be the answer.
+ *
+ * Exhaustively checked against a linear reference — every fixture × every item
+ * index × several splice positions — by `__wdCheckMapping` in `dev/App.tsx`,
+ * and against constructed interleavings in `test/transcript-rows.test.ts`.
+ */
+export function rowIndexForItem(rows: readonly TranscriptRow[], itemIndex: number): number {
+  const absorbed = absorbedRows(rows).get(itemIndex)
+  if (absorbed !== undefined) return absorbed
+  let lo = 0
+  let hi = rows.length - 1
+  let best = 0
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1
+    const row = rows[mid]!
+    let start: number
+    if ('index' in row) start = row.index
+    else {
+      const next = rows[mid + 1]
+      start = next && 'index' in next ? next.index : Number.MAX_SAFE_INTEGER
+    }
+    if (start <= itemIndex) {
+      if ('index' in row) best = mid
+      lo = mid + 1
+    } else {
+      hi = mid - 1
+    }
+  }
+  return best
+}
+
+/** Where an item sits inside a row it shares with other items: its 0-based
+ * ordinal in stream order, out of `count` siblings. `0 ≤ ordinal < count`. */
+export type RowPosition = { ordinal: number; count: number }
+
+const positionCache = new WeakMap<readonly TranscriptRow[], Map<number, RowPosition>>()
+
+function rowPositions(rows: readonly TranscriptRow[]): Map<number, RowPosition> {
+  const hit = positionCache.get(rows)
+  if (hit) return hit
+  const map = new Map<number, RowPosition>()
+  for (const row of rows) {
+    if ('task' in row) {
+      const count = row.childIndices.length
+      row.childIndices.forEach((itemIndex, ordinal) => map.set(itemIndex, { ordinal, count }))
+    } else if ('run' in row && row.run.length > 1) {
+      const count = row.run.length
+      row.indices.forEach((itemIndex, ordinal) => map.set(itemIndex, { ordinal, count }))
+    }
+  }
+  positionCache.set(rows, map)
+  return map
+}
+
+/**
+ * Where an item sits inside a row that holds MORE than itself — a task block's
+ * absorbed child, or a member of a folded run of two or more. `undefined` for
+ * everything else, including a row's own head item (the `Task` call, a run's
+ * first member is *not* exempt) and a **singleton run**: there the row's extent
+ * IS the item's, and a mark spanning it is honest.
+ *
+ * That carve-out is load-bearing rather than tidy: `pushLeaf` makes *every*
+ * top-level tool call a `RunBlock`, usually of length 1, so without it every
+ * ordinary failed call's scrubber mark would shrink from its row's extent to a
+ * tick and the rail would stop reading as a map — a regression traded for a fix.
+ *
+ * The scrubber is the consumer: a mark for a shared-row item anchors at
+ * `ordinal / count` of the row's *measured* height instead of inheriting an
+ * extent that is mostly other items' work (one failed child of a hundred-call
+ * task painted the whole expanded block red). Memoized per rows array identity
+ * exactly like {@link absorbedRows}, and pure — the answer is a function of the
+ * array alone, and a discarded array takes its map with it.
+ */
+export function positionInRow(
+  rows: readonly TranscriptRow[],
+  itemIndex: number,
+): RowPosition | undefined {
+  return rowPositions(rows).get(itemIndex)
+}

package/src/components/agent/transcript-variant.tsx

@@ -1,22 +1,25 @@
 import { createContext, useContext, type ReactNode } from 'react'
-import { cn } from '../../lib/utils.ts'
 
 /**
  * How the transcript draws a turn.
  *
  * - `cards` — the chat convention: bubbles, bordered tool cards, generous gaps.
  *   Right for a wide dashboard where the transcript is the page.
- * - `lines` — one full-width line item per event, transparent, hover-highlit,
- *   with a glyph in a fixed left gutter. Right where vertical space is the
- *   scarce resource (a VS Code dock) and the terminal is the reference UX:
- *   nothing is boxed, the content and its marker carry the comprehension.
+ * - `terminal` — the CLI's own form: every row on a character cell, no boxes
+ *   anywhere, diffs as full-width bands. Right where the transcript sits beside
+ *   a terminal (a VS Code dock) and where vertical space is scarce.
  *
- * A context rather than a prop chain because every row component needs it and
- * only the transcript root knows it — and because `Message`/`ToolCallCard` are
- * exported on their own, so an embedder composing them by hand gets the right
- * treatment for free.
+ * `terminal` is **not** a second set of branches in the components under
+ * `components/agent/`: it is its own renderer (`components/terminal/`) that the
+ * shell mounts *instead* of them. So a row component here never asks which
+ * variant it is in — if it is drawing at all, it is drawing cards.
+ *
+ * A context rather than a prop chain because the pieces that DO need it sit
+ * outside the transcript (the composer, the pending prompts) and because
+ * `Message`/`ToolCallCard` are exported on their own, so an embedder composing
+ * them by hand gets the right treatment for free.
  */
-export type TranscriptVariant = 'cards' | 'lines'
+export type TranscriptVariant = 'cards' | 'terminal'
 
 const VariantContext = createContext<TranscriptVariant>('cards')
 
@@ -34,25 +37,21 @@ export function useTranscriptVariant(): TranscriptVariant {
   return useContext(VariantContext)
 }
 
-/** True in `lines`, for the many `cond ? a : b` reads in the row components. */
-export function useLines(): boolean {
-  return useTranscriptVariant() === 'lines'
-}
-
 /**
  * How much room the transcript gives each row.
  *
  * - `comfortable` — a blank line between messages, which is what the Claude Code
- *   CLI does and what the `lines` variant is trying to read like. The default:
- *   a transcript is prose before it is a table.
+ *   CLI does. The default: a transcript is prose before it is a table.
  * - `compact` — rows tight against each other, for a dock where every line of
  *   vertical space is contested.
  *
  * Separate from the variant, and deliberately: they answer different questions.
- * The variant decides *how a row is drawn* (boxed or not) and follows from the
- * surface; density decides *how much air is around it* and is a preference the
- * reader holds. Coupling them would mean a dock could not be roomy and a
- * dashboard could not be dense.
+ * The variant decides *how a row is drawn* and follows from the surface; density
+ * decides *how much air is around it* and is a preference the reader holds.
+ *
+ * Reaches `cards` only. The terminal theme's spacing is a blank *line*, decided
+ * per pair of blocks by `needsBlank` — a terminal has one line height, which is
+ * the whole premise — so there is nothing there for this to turn.
  */
 export type TranscriptDensity = 'comfortable' | 'compact'
 
@@ -95,43 +94,22 @@ export type TranscriptFont = 'sans' | 'mono'
  * `px` is fed to `estimateSize` alone, where being approximate is the contract:
  * it sets the scrollbar's length before rows mount and is replaced by a real
  * measurement the moment one does.
- *
- * `lines` + `compact` is the only combination with no gap at all: there the
- * row's own `py-0.5` is the entire separation, which is what makes it compact.
  */
 export const ROW_GAP: Record<
   TranscriptVariant,
   Record<TranscriptDensity, { className?: string; px: number }>
 > = {
+  // The terminal theme has no gap scale: the space between blocks is a **blank
+  // line**, decided per pair by `needsBlank` (a tool call and its output get
+  // none), so it is a class the shell applies conditionally rather than a
+  // constant it applies to every row. Density does not reach it — a terminal
+  // has one line height, which is the whole premise.
+  terminal: {
+    comfortable: { className: 'term-row-gap', px: 18 },
+    compact: { className: 'term-row-gap', px: 18 },
+  },
   cards: {
     comfortable: { className: 'pt-4', px: 16 },
     compact: { className: 'pt-2', px: 8 },
   },
-  lines: {
-    // 16px on top of the row's own 4px of `py-0.5` is one 20px line — the blank
-    // line the CLI leaves, arrived at from the line height rather than picked.
-    comfortable: { className: 'pt-4', px: 16 },
-    compact: { px: 0 },
-  },
-}
-
-/**
- * The left gutter of a line item: one glyph, fixed width, so every row's text
- * starts on the same column no matter which kind of event it is. Decorative —
- * the row's own text says what it is.
- */
-export function LineGlyph({ children, className }: { children: ReactNode; className?: string }) {
-  return (
-    <span
-      aria-hidden
-      className={cn(
-        'w-3.5 shrink-0 select-none text-center font-mono text-label leading-5 text-fg-4',
-        className,
-      )}>
-      {children}
-    </span>
-  )
 }
-
-/** Body text metrics for a line item — tighter than the card variant's. */
-export const LINE_TEXT = 'text-body-sm leading-5'

package/src/components/agent/use-height-epoch.ts

@@ -0,0 +1,60 @@
+/**
+ * The height epoch: one cache generation of computed row heights (terminal
+ * theme only — cards have no calculator and keep the flat estimate). Owned by
+ * the transcript shell because it owns the virtualizer the heights feed; the
+ * WeakMap inside self-invalidates through the reducer's replace-on-mutation,
+ * and the epoch itself is replaced wholesale when the wrap width or the cell
+ * changes. Measured off the rows container: it *is* the width rows wrap in
+ * (the scroller can resize without it moving — `ConversationContent` caps at
+ * 48rem — and the window never hears about a splitter drag), and it inherits
+ * the surface's font, which is what makes the `ch` probe honest. All DOM
+ * reads happen in the effect, debounced; render never touches layout.
+ */
+import { useEffect, useState, type RefObject } from 'react'
+import { createHeightEpoch, measureCh, type HeightEpoch } from '../terminal/height.ts'
+
+export function useHeightEpoch(options: {
+  terminal: boolean
+  /** The terminal cell, when the host set one — only read as a signal that the
+   * epoch must re-measure; the epoch's numbers come from the DOM. */
+  fontSize?: number
+  lineHeight?: number
+  rowsRef: RefObject<HTMLDivElement | null>
+}): HeightEpoch | null {
+  const { terminal, fontSize, lineHeight, rowsRef } = options
+  const [epoch, setEpoch] = useState<HeightEpoch | null>(null)
+  useEffect(() => {
+    if (!terminal) return
+    const element = rowsRef.current
+    if (!element) return
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const measure = () => {
+      const line = Number.parseFloat(
+        getComputedStyle(element).getPropertyValue('--term-line'),
+      )
+      const width = element.clientWidth
+      const ch = measureCh(element)
+      if (!line || !width || !ch) return
+      setEpoch((previous) =>
+        previous && previous.width === width && previous.ch === ch && previous.line === line
+          ? previous
+          : createHeightEpoch(width, ch, line),
+      )
+    }
+    const observer = new ResizeObserver(() => {
+      clearTimeout(timer)
+      timer = setTimeout(measure, 150)
+    })
+    observer.observe(element)
+    measure()
+    return () => {
+      observer.disconnect()
+      clearTimeout(timer)
+    }
+    // fontSize/lineHeight: a cell change re-renders every row, which usually
+    // moves the container's size and fires the observer — but a transcript
+    // whose height happens to survive the change would keep a stale `ch`, so
+    // the props re-arm the measurement directly.
+  }, [terminal, fontSize, lineHeight, rowsRef])
+  return epoch
+}

package/src/components/agent/use-path-links.ts

@@ -0,0 +1,147 @@
+import { useEffect, type RefObject } from 'react'
+
+/**
+ * Cmd/Ctrl+click a file path in the transcript to open it.
+ *
+ * The agent names files constantly — in prose, in tables, in tool arguments —
+ * and every one of them is a place the reader wants to go. They already *look*
+ * like links (inline code renders in the accent), so the affordance is half
+ * promised before anything is wired: this makes it true.
+ *
+ * **Detection is deliberately conservative**, because the cost is asymmetric. A
+ * missed path is a path you select and open yourself; a false positive is a
+ * word that lights up under the modifier and then does nothing, which teaches
+ * the reader not to trust any of them. So:
+ *
+ * - A trailing `/` means a directory. Directories are not openable in a text
+ *   editor, and offering it is worse than staying quiet.
+ * - Outside a `<code>` element the match must be *most* of what the element
+ *   says, or a paragraph mentioning `src/index.ts` in passing would underline
+ *   whole sentences.
+ * - A bare filename (`worker.mjs`) is only a path **inside code**, and only
+ *   with an extension. `18 B` and `Type` are table cells, not files.
+ *
+ * The modifier is the editor's own: hold it and what would open lights up
+ * (`wd-path-link`), which is the only honest way to show which of the blue
+ * things on screen are actually reachable.
+ */
+export type PathHit = { path: string; line?: number }
+
+/** Marks the element under the pointer while the modifier is held. */
+const LINKISH = 'wd-path-link'
+
+/** Absolute, or relative with at least one separator. `:12` is a line number. */
+const PATH_RE = /^(\/[^\s:'"`()[\]{}]+|[\w.@~-]+(?:\/[\w.@~-]+)+)(?::(\d+))?$/
+/** A bare filename — only trusted inside a code element. */
+const FILE_RE = /^([\w.@-]+\.[A-Za-z0-9]{1,10})(?::(\d+))?$/
+
+/** How much of an element's text the match must cover, outside code. */
+const COVERAGE = 0.6
+
+export function matchPath(text: string, inCode: boolean): PathHit | undefined {
+  const trimmed = text.trim()
+  if (!trimmed || trimmed.endsWith('/')) return undefined
+  const hit = PATH_RE.exec(trimmed) ?? (inCode ? FILE_RE.exec(trimmed) : null)
+  if (!hit) return undefined
+  return { path: hit[1]!, line: hit[2] ? Number(hit[2]) : undefined }
+}
+
+/** The path a click on this element means, if any. */
+function hitFor(element: HTMLElement | undefined): PathHit | undefined {
+  if (!element) return undefined
+  const inCode = element.closest('code') !== null
+  const text = element.textContent ?? ''
+  const hit = matchPath(text, inCode)
+  if (!hit) return undefined
+  if (!inCode && hit.path.length < text.trim().length * COVERAGE) return undefined
+  return hit
+}
+
+export function usePathLinks({
+  container,
+  onOpen,
+  enabled = true,
+  ignore,
+}: {
+  /** The subtree to listen in — normally the panel. */
+  container: RefObject<HTMLElement | null>
+  onOpen: (hit: PathHit) => void
+  /** Off when there is no host filesystem to open from: a link that cannot
+   * resolve is worse than plain text. */
+  enabled?: boolean
+  /**
+   * A selector for subtrees to leave alone. Anything with its own meaning for
+   * the modifier needs this — a code editor's Cmd+click is go-to-definition,
+   * and every identifier in it would otherwise match as a filename.
+   */
+  ignore?: string
+}) {
+  useEffect(() => {
+    const root = container.current
+    if (!root || !enabled) return
+    const excluded = (element: HTMLElement | undefined) =>
+      ignore !== undefined && element?.closest(ignore) !== null && element !== undefined
+
+    let marked: HTMLElement | undefined
+    const unmark = () => {
+      marked?.classList.remove(LINKISH)
+      marked = undefined
+    }
+
+    const onClick = (event: MouseEvent) => {
+      if (!event.metaKey && !event.ctrlKey) return
+      const target = event.target instanceof HTMLElement ? event.target : undefined
+      if (excluded(target)) return
+      const hit = hitFor(target)
+      if (!hit) return
+      // Capture phase and stopped here: the row underneath is usually pressable
+      // (a tool call expands), and opening a file is not expanding it.
+      event.preventDefault()
+      event.stopPropagation()
+      unmark()
+      onOpen(hit)
+    }
+
+    const onMove = (event: MouseEvent) => {
+      if (!event.metaKey && !event.ctrlKey) return unmark()
+      const element = event.target instanceof HTMLElement ? event.target : undefined
+      if (element === marked) return
+      unmark()
+      if (!element || excluded(element) || !hitFor(element)) return
+      marked = element
+      element.classList.add(LINKISH)
+    }
+
+    // Releasing the modifier has to clear it: an underline that outlives the key
+    // promises a click that will not work.
+    const onKey = (event: KeyboardEvent) => {
+      if (!event.metaKey && !event.ctrlKey) unmark()
+    }
+
+    root.addEventListener('click', onClick, true)
+    root.addEventListener('mousemove', onMove)
+    document.addEventListener('keydown', onKey)
+    document.addEventListener('keyup', onKey)
+    window.addEventListener('blur', unmark)
+    return () => {
+      unmark()
+      root.removeEventListener('click', onClick, true)
+      root.removeEventListener('mousemove', onMove)
+      document.removeEventListener('keydown', onKey)
+      document.removeEventListener('keyup', onKey)
+      window.removeEventListener('blur', unmark)
+    }
+  }, [container, onOpen, enabled, ignore])
+}
+
+/**
+ * A transcript path against the session's cwd.
+ *
+ * Absolute wins outright. Everything else is relative to where the agent is
+ * working, which is the only root that makes `worker.mjs` mean anything.
+ */
+export function resolveAgainstCwd(path: string, cwd: string | undefined): string {
+  if (path.startsWith('/')) return path
+  if (!cwd) return path
+  return `${cwd.replace(/\/$/, '')}/${path.replace(/^\.\//, '')}`
+}