@workerdeck/ui 0.15.0 → 0.17.0

package/src/components/terminal/surface.tsx

@@ -0,0 +1,80 @@
+import type { CSSProperties, HTMLAttributes } from 'react'
+import { cn } from '../../lib/utils.ts'
+import {
+  AffordanceProvider,
+  resolveAffordances,
+  type TerminalAffordances,
+} from './affordances.tsx'
+
+/**
+ * The root of the terminal theme: the element that establishes the character
+ * cell every row inside it lands on.
+ *
+ * It exists as a component rather than a class because the cell has to be *set*
+ * somewhere — the font, the size and the line height together are what make
+ * `1ch` mean one column and `--term-line` mean one row — and because that is the
+ * one place a host is allowed to change the metrics. Everything below this
+ * element measures itself in those two units and never in pixels.
+ *
+ * The geometry and the palette live in `styles/terminal.css`; this only names
+ * the element and hands down the two numbers.
+ */
+export interface TerminalSurfaceProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Cell size in **whole pixels**. Fractional values put every other row on a
+   * half-pixel: text softens and the diff bands show a seam, which is exactly
+   * what a grid renderer must not do. Defaults (13/18) are the CLI's own.
+   */
+  fontSize?: number
+  lineHeight?: number
+  /**
+   * How far a full-bleed band reaches past the content edge — normally the
+   * scroller's own horizontal padding. A band cancels it with matched negative
+   * margin and padding, so a diff hunk's wash runs to the viewport edge the way
+   * a terminal's line does, instead of stopping at a gutter.
+   */
+  bleed?: string
+  /**
+   * The things a real terminal cannot do — the pointer hover fill, the
+   * hover-revealed copy actions. `false` turns them all off, an object picks.
+   * Default: all on. See {@link TerminalAffordances}; none of them costs layout,
+   * so switching them off changes no glyph's position.
+   */
+  affordances?: TerminalAffordances | boolean
+}
+
+export function TerminalSurface({
+  fontSize,
+  lineHeight,
+  bleed,
+  affordances,
+  className,
+  style,
+  children,
+  ...props
+}: TerminalSurfaceProps) {
+  const resolved = resolveAffordances(affordances)
+  return (
+    <div
+      data-terminal=''
+      // A space-separated list so CSS can ask for one with `~=` — the styling
+      // half of the switch, where the JS half (whether a button exists at all)
+      // rides the context.
+      data-affordances={
+        [resolved.hover && 'hover', resolved.actions && 'actions'].filter(Boolean).join(' ') ||
+        undefined
+      }
+      className={cn('min-w-0', className)}
+      style={
+        {
+          ...(fontSize !== undefined && { '--term-font-size': `${Math.round(fontSize)}px` }),
+          ...(lineHeight !== undefined && { '--term-line': `${Math.round(lineHeight)}px` }),
+          ...(bleed !== undefined && { '--term-bleed': bleed }),
+          ...style,
+        } as CSSProperties
+      }
+      {...props}>
+      <AffordanceProvider value={resolved}>{children}</AffordanceProvider>
+    </div>
+  )
+}

package/src/components/terminal/tool-run.ts

@@ -0,0 +1,224 @@
+/**
+ * What a folded run of tool calls is, and the one line that stands for it.
+ *
+ * The fold was shell-only, and the screenshot that started this made the cost
+ * obvious: a run of six calls that happened to alternate `Bash` with an MCP tool
+ * folded into *four* rows reading "Ran 1 shell command", "Ran 2 shell commands",
+ * "Ran 1 shell command" — a count for every gap between the calls it could not
+ * group. The grouping rule was right and the *membership* rule was too narrow.
+ *
+ * So any consecutive tool calls fold. The CLI's own line is the target
+ * (`called roam-code, ran 1 shell command`), and the claim is unchanged from the
+ * shell version: a tool call is almost never what you came back to read, and six
+ * of them bury the sentence that is.
+ *
+ * Pure and separate because `items.tsx` draws this line and `height.ts` wraps it
+ * to predict the row's pixel height without a DOM — the same reason
+ * `result-preview.ts` exists. Two spellings would be two different heights.
+ */
+import type { TranscriptItem } from '@workerdeck/react'
+import { toolInputPreview } from '../../lib/format.ts'
+import { isShellTool } from '../../lib/tool-icon.ts'
+
+type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
+
+/**
+ * What breaks a run.
+ *
+ * *Consecutive* is still the whole rule, and it is the reason the fold is honest:
+ * anything the model said between two calls breaks the run, because that
+ * sentence is the reason the second one happened and a count spanning it would
+ * claim the two were one act. The recap boundary breaks it too — the virtualized
+ * shell folds each side separately — so a count never spans "what you already
+ * read".
+ *
+ * `parentToolUseId` is the one addition the wider membership rule needs: a
+ * subagent's calls are drawn stepped in behind a rule, and folding one together
+ * with a top-level call would put rows from two different frames of reference
+ * under a single count.
+ */
+export function foldsTogether(a: ToolCallItem, b: ToolCallItem): boolean {
+  return a.parentToolUseId === b.parentToolUseId
+}
+
+/**
+ * The family a tool counts as in a run's breakdown.
+ *
+ * An MCP tool is `mcp__<server>__<tool>`, and the *server* is the useful unit:
+ * "3 roam-code" is a thing that happened, where three separate tool names are a
+ * list to read. Shell tools from both engines collapse to "shell" for the same
+ * reason. Everything else is its own name, lowercased so the breakdown reads as
+ * prose rather than as identifiers.
+ */
+export function toolFamily(name: string): string {
+  if (isShellTool(name)) return 'shell'
+  const mcp = /^mcp__([^_]+(?:_[^_]+)*?)__/.exec(name)
+  if (mcp?.[1]) return mcp[1].replace(/_/g, '-')
+  return name.toLowerCase()
+}
+
+/**
+ * The run's one line.
+ *
+ * A shell-only run keeps its old wording exactly — "Ran 3 shell commands" — both
+ * because it is the commonest run by far and because it is already the sentence
+ * people read here; widening the fold should not have re-worded the case that
+ * was working. Anything mixed gets the count plus a breakdown, loudest family
+ * first.
+ */
+export function runSummary(items: readonly ToolCallItem[], busy: boolean): string {
+  const verb = busy ? 'Running ' : 'Ran '
+  const tail = busy ? '…' : ''
+  const n = items.length
+
+  const counts = new Map<string, number>()
+  for (const item of items) {
+    const family = toolFamily(item.name)
+    counts.set(family, (counts.get(family) ?? 0) + 1)
+  }
+  if (counts.size === 1 && counts.has('shell')) {
+    return `${verb}${n} shell command${n === 1 ? '' : 's'}${tail}`
+  }
+  // Descending by count, then alphabetical — a stable order matters more than it
+  // looks: this string is the row's measured height, so a run whose breakdown
+  // reordered between renders would remeasure for no reason.
+  const breakdown = [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([family, count]) => `${count} ${family}`)
+    .join(', ')
+  // The ellipsis trails the whole line, not the count — "Running 2 tools… · 1
+  // read, 1 shell" reads as though the sentence ended and then carried on.
+  return `${verb}${n} tool${n === 1 ? '' : 's'} · ${breakdown}${tail}`
+}
+
+/* ── The task block's one line ─────────────────────────────────────────────
+ *
+ * A `Task` call and everything its subagent produced collapse to one row (see
+ * `blocks.ts`), and these are that row's words. Same contract as `runSummary`:
+ * `height.ts` wraps these exact strings to predict the row's pixel height with
+ * no DOM, so the component must render them verbatim — two spellings would be
+ * two different heights.
+ */
+
+const clip = (text: string, max = 80): string =>
+  text.length > max ? text.slice(0, max - 1) + '…' : text
+
+const trimmed = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+
+/**
+ * The row's identity half: which task this is.
+ *
+ * The Claude SDK's `Task` input carries `subagent_type` (e.g. "Explore") and a
+ * 3–5 word `description`, and both are worth the line: parallel tasks are the
+ * whole reason the block exists, and two rows both reading `Task(…)` answer
+ * nothing. `Task(Explore · find the auth check)` — falling back to the
+ * ordinary input preview when an engine sends neither, so the header is never
+ * emptier than a plain tool row's.
+ */
+export function taskLabel(task: ToolCallItem): string {
+  const input = task.input as { description?: unknown; subagent_type?: unknown } | null
+  const description = trimmed(input?.description)
+  const agent = trimmed(input?.subagent_type)
+  const inner =
+    agent && description
+      ? `${agent} · ${clip(description)}`
+      : (agent ?? (description ? clip(description) : toolInputPreview(task.input)))
+  return `${task.name}(${inner})`
+}
+
+const callBusy = (call: ToolCallItem): boolean =>
+  call.status === 'running' || call.status === 'pending'
+
+/** Did this one call fail? Both spellings are needed: an out-of-loop execution
+ * failure sets `status` with no `is_error` block to read, and an engine can flag
+ * `is_error` on a call the reducer has not settled yet. */
+export const callFailed = (call: ToolCallItem): boolean =>
+  call.status === 'failed' || call.result?.isError === true
+
+/**
+ * Does a folded run colour red? **Only when its last call failed.**
+ *
+ * It used to be `some`, on the argument that a failure should colour the block
+ * rather than fragment it. The argument was right about not fragmenting and
+ * wrong about `some`: a run is a sequence the model worked through, and a
+ * failure it recovered from two calls later is how work goes — a grep that
+ * matched nothing, a build fixed on the second go. Reddening the whole run for
+ * it means a normal working session is painted red, which spends the colour
+ * that should have been left for the one thing still broken.
+ *
+ * The last call is the run's *outcome*, and an outcome is what a collapsed row
+ * can honestly claim. The failures inside it are not hidden — they are one
+ * press away, each red on its own row, and the recap counts every one. The
+ * **scrubber agrees with this rule** rather than overriding it: it marks a
+ * failed call only when the call is its row's outcome, which for a run is
+ * exactly this one. It used to mark every member on the argument that the
+ * rail asks a different question; against a real session that was nine alarms
+ * on the rail for a transcript reddening one row.
+ */
+export function runFailed(items: readonly ToolCallItem[]): boolean {
+  const last = items[items.length - 1]
+  return last !== undefined && callFailed(last)
+}
+
+/** Is anything inside still going? The call itself, normally — the Task
+ * settles only when its subagent finishes — but a bridged or deferred child
+ * can outlive it, and a pulse that stopped while a child still worked would
+ * read as a hang. */
+export function taskBusy(task: ToolCallItem, children: readonly TranscriptItem[]): boolean {
+  return callBusy(task) || children.some((child) => child.kind === 'tool_call' && callBusy(child))
+}
+
+/**
+ * Does the row colour red? **The task's own outcome, and nothing else.**
+ *
+ * It used to be "or any child call's", which does not survive contact with a
+ * real subagent: an agent that ran a hundred calls, one of them a grep that
+ * matched nothing, came back with a red line saying it had failed. It had not —
+ * it had done exactly what it was asked, and the transcript said otherwise in
+ * the one colour reserved for things that need a human.
+ *
+ * This is the call `SubagentInfo.status` already makes, and it made it for this
+ * reason (see `packages/protocol`): the sub-agent's **own** `tool_result`
+ * `is_error`, deliberately not `taskFailed`. The argument there was that a
+ * nothing-matched grep must not read as a failed run *beside a session name*;
+ * what a hundred-call agent shows is that it must not read that way beside the
+ * `Task` row either. Two surfaces, one rule, one spelling.
+ *
+ * Nothing is concealed by this. A failed child is red on its own row, one press
+ * away, and the recap counts it. The **scrubber follows this rule too** and no
+ * longer marks such a child: a red tick on the rail says precisely what this
+ * row is forbidden from saying. The sub-agent band still says an agent ran
+ * here, and the task's own red tick still says it came back broken — which is
+ * what the two channels are for.
+ */
+export function taskFailed(task: ToolCallItem): boolean {
+  return callFailed(task)
+}
+
+/**
+ * The collapsed task row's one line: identity, then scale.
+ *
+ * `Task(Explore · find the auth check) · 7 tools…` while the subagent works —
+ * the count grows as it does, which is the row's progress reading, and the
+ * trailing ellipsis is the same in-flight signal `runSummary` uses (the pulse
+ * in the gutter carries the beat). Settled, the ellipsis drops:
+ * `… · 7 tools`. "Tools" and not "tool calls" because `runSummary` already
+ * chose that word for the same count one row over.
+ *
+ * The counts are counted from the absorbed children, never read from the
+ * engine's structured Task output — WorkerDeck does not plumb structured tool
+ * results to clients, so a transcript replayed tomorrow must spell the same
+ * line from the same items it holds today.
+ *
+ * With no tool calls yet — the subagent thinking, or only its brief arrived —
+ * the line says `working…`, because `0 tools…` reads as a stall; settled with
+ * none it says `done`.
+ */
+export function taskSummary(task: ToolCallItem, children: readonly TranscriptItem[]): string {
+  const busy = taskBusy(task, children)
+  const calls = children.reduce((n, child) => n + (child.kind === 'tool_call' ? 1 : 0), 0)
+  const label = taskLabel(task)
+  if (calls === 0) return busy ? `${label} · working…` : `${label} · done`
+  return `${label} · ${calls} tool${calls === 1 ? '' : 's'}${busy ? '…' : ''}`
+}

package/src/index.ts

@@ -71,11 +71,44 @@ export {
   type SessionPanelProps,
   type SessionSurfacePanel,
   type SessionVitals,
+  type TerminalMetrics,
 } from './components/agent/SessionPanel.tsx'
 // The workspace layout and its Monaco editor live at `@workerdeck/ui/workspace`
 // — deliberately unreachable from here, so importing this entry never drags
 // Monaco into the bundle. See `src/workspace.ts`.
 export { Transcript, type TranscriptProps } from './components/agent/Transcript.tsx'
+// The terminal theme. `SessionPanel`/`Transcript` reach it through
+// `variant: 'terminal'` and most embedders need nothing else — these are for a
+// host composing the surface by hand (a prompt outside the panel, a status line
+// in its own chrome) and for the primitives, so a host's own row lands on the
+// same character cell as ours.
+export {
+  TerminalSurface,
+  type TerminalSurfaceProps,
+} from './components/terminal/surface.tsx'
+export {
+  TerminalTranscript,
+  TerminalItemView,
+  type TerminalTranscriptProps,
+} from './components/terminal/TerminalTranscript.tsx'
+export { TerminalStatusLine, type TerminalStatusLineProps } from './components/terminal/StatusLine.tsx'
+export {
+  TerminalPermissionPrompt,
+  type TerminalPermissionPromptProps,
+} from './components/terminal/PermissionPrompt.tsx'
+export {
+  TerminalQuestionPrompt,
+  type TerminalQuestionPromptProps,
+} from './components/terminal/QuestionPrompt.tsx'
+export { TerminalDiff, previewPatch } from './components/terminal/diff.tsx'
+export { TerminalMarkdown, type TerminalMarkdownProps } from './components/terminal/markdown.tsx'
+export { Band, Blank, Ink, Row, type RowProps, type Tone } from './components/terminal/row.tsx'
+export {
+  CopyAction,
+  WithActions,
+  useAffordances,
+  type TerminalAffordances,
+} from './components/terminal/affordances.tsx'
 export {
   Conversation,
   ConversationContent,
@@ -125,6 +158,7 @@ export {
 export { StatusBar, type StatusBarProps } from './components/agent/StatusBar.tsx'
 export { ContextDialog, type ContextDialogProps } from './components/agent/ContextDialog.tsx'
 export { UsageDialog, type UsageDialogProps } from './components/agent/UsageDialog.tsx'
+export { UsageMeters, useMinuteClock } from './components/agent/UsageMeters.tsx'
 export {
   SessionInfoDialog,
   type SessionInfoDialogProps,
@@ -146,7 +180,8 @@ export {
 export { SessionStatusIcon } from './components/agent/SessionBrowser.tsx'
 // Lifted out of the VS Code sidebar once the dashboard grew a collapsed rail
 // that needs the same glyph — two copies of a trademark set is one too many.
-export { EngineIcon } from './components/agent/EngineIcon.tsx'
+export { EngineIcon, engineMark } from './components/agent/EngineIcon.tsx'
+export { ProjectIcon } from './components/agent/ProjectIcon.tsx'
 export {
   SessionEmptyState,
   type SessionEmptyStateProps,

package/src/lib/status.ts

@@ -63,8 +63,59 @@ export function meterSeverity(pct: number | undefined): StatusSeverity {
   return 'none'
 }
 
+/**
+ * The three *lanes* a plan-usage reading can occupy, and the whole reason this
+ * is a rule rather than a per-client `if`.
+ *
+ * The CLI reports one window per limit (`five_hour`, `seven_day`, and a
+ * `seven_day_<model>` bucket per model-scoped limit — `seven_day_opus`,
+ * `seven_day_sonnet`, and whatever `model_scoped` names next). A surface with
+ * one slot shows the fullest of them, which is why `tightestWindow` exists —
+ * but that answers "what is closest to blocking me", not "how much of *this
+ * session's* budget have I spent", and those are different questions a reader
+ * asks at different times. A weekly window at 71% will win the single slot over
+ * a five-hour window at 60% every time, so the reading you actually watch while
+ * working is the one you can never see.
+ *
+ * Hence three lanes, each independently showable:
+ *
+ * - `'session'` — the five-hour window. The one that resets while you work.
+ * - `'weekly'` — the plain seven-day window, the account-wide ceiling.
+ * - `'model'` — the fullest of the *model-scoped* weekly buckets. Deliberately
+ *   not a named model: which models have their own bucket is the plan's
+ *   business and changes without notice, so a client that hardcoded
+ *   `seven_day_opus` would show nothing the month it becomes something else.
+ *   The label comes from the key, so this lane names whatever it found.
+ */
+export type UsageLane = 'session' | 'weekly' | 'model'
+
+/** The window a lane points at, or `undefined` when this account has none. */
+export function usageWindow(
+  rateLimits: Record<string, RateLimitInfo> | undefined,
+  lane: UsageLane,
+): { key: string; info: RateLimitInfo } | undefined {
+  if (!rateLimits) return undefined
+  if (lane === 'session') {
+    const info = rateLimits.five_hour
+    return info ? { key: 'five_hour', info } : undefined
+  }
+  if (lane === 'weekly') {
+    const info = rateLimits.seven_day
+    return info ? { key: 'seven_day', info } : undefined
+  }
+  // Model-scoped: same "fullest wins" rule as the single slot, over the subset.
+  const scoped = Object.fromEntries(
+    Object.entries(rateLimits).filter(
+      ([key]) => key.startsWith('seven_day_') && key !== 'seven_day_oauth_apps',
+    ),
+  )
+  return tightestWindow(scoped)
+}
+
 /** The rate-limit window that gets the one visible slot: whichever is fullest,
- * since the binding constraint is the one worth glancing at. */
+ * since the binding constraint is the one worth glancing at. Still the right
+ * rule for a surface with exactly one slot; {@link usageWindow} is for one with
+ * three. */
 export function tightestWindow(
   rateLimits: Record<string, RateLimitInfo> | undefined,
 ): { key: string; info: RateLimitInfo } | undefined {
@@ -85,11 +136,16 @@ export function tightestWindow(
   return best
 }
 
-/** A rate-limit window's key, named for a human. */
+/** A rate-limit window's key, named for a human. A model-scoped bucket is named
+ * for its model alone (`seven_day_fable` → "Fable"): the lane it sits in
+ * already says weekly, and "Seven day fable" in a status bar is three words to
+ * say one. */
 export function windowLabel(key: string): string {
   if (key === 'five_hour') return 'Session'
   if (key === 'seven_day') return 'Weekly'
-  return key.replaceAll('_', ' ')
+  const scoped = key.startsWith('seven_day_') ? key.slice('seven_day_'.length) : key
+  const words = scoped.replaceAll('_', ' ')
+  return words.charAt(0).toUpperCase() + words.slice(1)
 }
 
 export type ModelReadings = { model?: string; models: readonly ModelOption[] }

package/src/lib/tool-icon.ts

@@ -73,6 +73,20 @@ export function toolIcon(toolName: string): LucideIcon {
   }
 }
 
+/**
+ * Is this tool a shell command?
+ *
+ * Its own question because a run of them is *one* thing the reader skims past:
+ * the terminal theme collapses consecutive shell calls into a single "Ran N
+ * shell commands" line, the way the CLI does. Names from both first-party
+ * engines. `BashOutput`/`KillShell` are excluded on purpose — they manage a
+ * background shell rather than run something, and folding them into the count
+ * would inflate it.
+ */
+export function isShellTool(toolName: string): boolean {
+  return toolName === 'Bash' || toolName === 'CodexCommand'
+}
+
 /**
  * Does this tool *change* the workspace?
  *