@workerdeck/ui 0.13.0 → 0.16.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,91 @@
+/**
+ * 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 { 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}`
+}

package/src/components/ui/Badge.tsx

@@ -33,7 +33,12 @@ export interface BadgeProps
 export function Badge({ className, variant = 'neutral', mono, dot, children, ...props }: BadgeProps) {
   return (
     <span data-slot='badge' className={cn(badgeVariants({ variant, mono, className }))} {...props}>
-      {dot ? <span aria-hidden className='size-1.5 rounded-full bg-current' /> : null}
+      {/* `self-center` so the dot stays put if a caller baseline-aligns the
+          badge — a no-op under the default `items-center`, and what lets the
+          badge's *text* be the baseline it contributes to a row (a status bar
+          aligning readings on one line needs that, and the dot's own box would
+          otherwise answer for it). */}
+      {dot ? <span aria-hidden className='size-1.5 shrink-0 self-center rounded-full bg-current' /> : null}
       {children}
     </span>
   )

package/src/components/ui/Empty.tsx

@@ -0,0 +1,56 @@
+import type { ReactNode } from 'react'
+import { Button } from './Button.tsx'
+
+/**
+ * A view with nothing in it: icon, title, description, and at most one action.
+ *
+ * Centered and given room, because an empty view is the first thing a new
+ * install shows and a flush-left sentence in the top corner reads like a bug
+ * report. It lives here rather than in one client because every panel that can
+ * be empty should be empty the same way — the extension's views and the
+ * dashboard's four sidebars are the same shape of thing.
+ *
+ * **At most one action, and never one the view header already offers.** Creating
+ * a session and adding a gateway are the `+` in the native title bar, exclusively
+ * — so those empty states point at it in words rather than growing a second
+ * button that does the same thing two inches lower. A button here is for the way
+ * out of a state the header has no answer to: clearing a filter, widening a
+ * scope.
+ */
+export function Empty({
+  icon,
+  title,
+  description,
+  action,
+  onAction,
+}: {
+  icon: ReactNode
+  title: string
+  description?: ReactNode
+  action?: string
+  onAction?: () => void
+}) {
+  return (
+    <div className='flex flex-col items-center gap-2 px-5 py-8 text-center'>
+      <div className='text-fg-4 opacity-60 [&_svg]:size-7'>{icon}</div>
+      <p className='text-body-sm font-medium text-fg-2'>{title}</p>
+      {description ? (
+        <p className='max-w-[26ch] text-balance text-label leading-relaxed text-fg-4'>
+          {description}
+        </p>
+      ) : null}
+      {action && onAction ? (
+        <Button variant='outline' size='sm' className='mt-1' onClick={onAction}>
+          {action}
+        </Button>
+      ) : null}
+    </div>
+  )
+}
+
+/** A key or icon named inline in an empty state's description — "use the + above". */
+export function EmptyKey({ children }: { children: ReactNode }) {
+  return (
+    <span className='rounded border border-border px-1 font-mono text-fg-3'>{children}</span>
+  )
+}

package/src/components/ui/Splitter.tsx

@@ -20,6 +20,12 @@ export interface SplitterProps {
   max: number
   /** Keyboard step. */
   step?: number
+  /**
+   * Size to snap back to on a double-click — the convention every pane divider
+   * that can be dragged is expected to honour. Omit and a double-click does
+   * nothing, which is the honest behaviour when there is no default to mean.
+   */
+  defaultValue?: number
   /** Set when dragging the splitter *away* from the origin should shrink the
    * controlled pane — i.e. the pane is on the right or the bottom. */
   inverted?: boolean
@@ -52,6 +58,7 @@ export function Splitter({
   min,
   max,
   step = 16,
+  defaultValue,
   inverted,
   'aria-label': label,
   className,
@@ -84,6 +91,12 @@ export function Splitter({
     }
   }
 
+  // The second click of a double-click has already started a drag, so the reset
+  // has to land after `endDrag` — which it does: dblclick fires after pointerup.
+  const onDoubleClick = () => {
+    if (defaultValue !== undefined) onValueChange(clamp(defaultValue))
+  }
+
   const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
     // The arrows that move *along* this splitter's axis of travel; the other
     // pair is left to the page, which is what a separator should do with them.
@@ -112,6 +125,7 @@ export function Splitter({
       onPointerMove={onPointerMove}
       onPointerUp={endDrag}
       onPointerCancel={endDrag}
+      onDoubleClick={onDoubleClick}
       onKeyDown={onKeyDown}
       className={cn(
         // A 1px line that reads as a border, with a larger invisible grab area

package/src/index.ts

@@ -42,6 +42,7 @@ export { CopyButton, type CopyButtonProps } from './components/ui/CopyButton.tsx
 export { Spinner } from './components/ui/Spinner.tsx'
 export { CodeBlock, type CodeBlockProps } from './components/ui/CodeBlock.tsx'
 export { Splitter, type SplitterProps } from './components/ui/Splitter.tsx'
+export { Empty, EmptyKey } from './components/ui/Empty.tsx'
 export { ProgressRing, type ProgressRingProps } from './components/ui/ProgressRing.tsx'
 // Prompt input (vendored just-marketing/prompt-area, themed to these tokens)
 export {
@@ -70,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,
@@ -88,6 +122,7 @@ export {
   useTranscriptDensity,
   useTranscriptVariant,
   type TranscriptDensity,
+  type TranscriptFont,
   type TranscriptVariant,
 } from './components/agent/transcript-variant.tsx'
 export { Response, type ResponseProps } from './components/agent/Response.tsx'
@@ -123,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,

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?
  *