@workerdeck/ui 0.22.0 → 1.0.0

package/src/components/agent/UsageMeters.tsx

@@ -2,24 +2,15 @@ import { useEffect, useState } from 'react'
 import type { UsageWindowRow } from '@workerdeck/protocol'
 import { RotateCcw } from 'lucide-react'
 import { cn } from '../../lib/utils.ts'
-import {
-  formatAgoPrecise,
-  formatCountdown,
-  formatRateLimitWindowLong,
-  rateLimitWindowSeconds,
-} from '../../lib/format.ts'
+import { formatAgoPrecise, formatCountdown, formatRateLimitWindowLong, rateLimitWindowSeconds } from '../../lib/format.ts'
+import { meterTintClass } from '../../lib/status.ts'
 
-/**
- * Ticking clock — the countdowns and the pace markers both move with it, and a
- * minute is the finest resolution either of them prints.
- *
- * `active` is what a dialog passes its `open`: a closed panel's clock is a timer
- * re-rendering something nobody can see.
- */
 export function useMinuteClock(active = true): number {
   const [now, setNow] = useState(() => Date.now())
   useEffect(() => {
-    if (!active) return
+    if (!active) {
+      return
+    }
     setNow(Date.now())
     const timer = setInterval(() => setNow(Date.now()), 60_000)
     return () => clearInterval(timer)
@@ -27,37 +18,7 @@ export function useMinuteClock(active = true): number {
   return now
 }
 
-const usageTint = (pct: number) => (pct >= 90 ? 'bg-danger' : pct >= 70 ? 'bg-warning' : 'bg-accent')
-
-/**
- * The plan's rate-limit windows, spelled out: how much of each is used, how that
- * compares to the pace that would spend the window exactly, and when it resets.
- *
- * The pace marker is the point. A bar alone says "17% used", which is only
- * alarming or reassuring once you know how far into the week you are — so every
- * window draws a tick at the elapsed share of its duration. Left of the tick is
- * under budget, right of it is ahead of it. The duration comes from the window
- * key (5h, 7d) because the engine reports a reset time and a percentage and
- * never a duration; a window whose key doesn't say gets no marker rather than a
- * guessed one.
- *
- * Its own component rather than the Usage dialog's private helper because two
- * surfaces draw these now — the session panel's Usage panel, from the session's
- * readings merged with the gateway's, and the dashboard's profile page, straight
- * off `ProfileInfo.usage` with no session in sight. Same account, same bars.
- */
-export function UsageMeters({
-  windows,
-  now,
-  className,
-}: {
-  /** In reading order — protocol's `orderUsageWindows`. */
-  windows: UsageWindowRow[]
-  /** A shared clock, when the caller already ticks one. Omitted, this ticks its
-   * own for as long as it is mounted. */
-  now?: number
-  className?: string
-}) {
+export function UsageMeters({ windows, now, className }: { windows: UsageWindowRow[]; now?: number; className?: string }) {
   const ownClock = useMinuteClock(now === undefined)
   const clock = now ?? ownClock
   return (
@@ -73,8 +34,6 @@ function UsageMeter({ window, now }: { window: UsageWindowRow; now: number }) {
   const { key: windowKey, info, updatedAt, inferredReset } = window
   const utilization = info.utilization ?? 0
   const resetsAtMs = info.resetsAt !== undefined ? info.resetsAt * 1000 : undefined
-  // Share of the window already elapsed — where usage *would* be if it were
-  // spent evenly. Needs both a duration (from the key) and a reset time.
   const duration = rateLimitWindowSeconds(windowKey)
   const remaining = resetsAtMs !== undefined ? (resetsAtMs - now) / 1000 : undefined
   const pace =
@@ -83,49 +42,35 @@ function UsageMeter({ window, now }: { window: UsageWindowRow; now: number }) {
       : undefined
   return (
     <div>
-      <div className='flex items-baseline justify-between gap-3'>
-        <span className='truncate text-body-sm text-fg-1'>
-          {formatRateLimitWindowLong(windowKey)}
-        </span>
-        <span
-          className={cn(
-            'shrink-0 font-mono text-body-sm font-medium',
-            info.status === 'rejected' ? 'text-danger' : 'text-fg-1',
-          )}>
+      <div className="flex items-baseline justify-between gap-3">
+        <span className="truncate text-body-sm text-fg-1">{formatRateLimitWindowLong(windowKey)}</span>
+        <span className={cn('shrink-0 font-mono text-body-sm font-medium', info.status === 'rejected' ? 'text-danger' : 'text-fg-1')}>
           {utilization.toFixed(0)}% used
         </span>
       </div>
-      <div className='relative mt-2 h-2 rounded-full bg-border'>
+      <div className="relative mt-2 h-2 rounded-full bg-border">
         <div
-          className={cn('h-full rounded-full', usageTint(utilization))}
-          // A floor, so a barely-touched window still shows a mark instead of
-          // reading as missing data.
+          className={cn('h-full rounded-full', meterTintClass(utilization))}
           style={{ width: `${Math.min(100, Math.max(2, utilization))}%` }}
         />
         {pace !== undefined ? (
           <span
             aria-hidden
-            title='Spent evenly, usage would be here by now'
-            className='absolute -top-1 h-4 w-0.5 -translate-x-1/2 rounded-full bg-fg-1'
+            title="Spent evenly, usage would be here by now"
+            className="absolute -top-1 h-4 w-0.5 -translate-x-1/2 rounded-full bg-fg-1"
             style={{ left: `${Math.min(100, Math.max(0, pace * 100))}%` }}
           />
         ) : null}
       </div>
-      <div className='mt-1.5 flex items-center gap-3 text-label text-fg-4'>
+      <div className="mt-1.5 flex items-center gap-3 text-label text-fg-4">
         {resetsAtMs !== undefined ? (
-          <span className='inline-flex items-center gap-1'>
-            <RotateCcw className='size-3' /> Resets in {formatCountdown(resetsAtMs, now)}
+          <span className="inline-flex items-center gap-1">
+            <RotateCcw className="size-3" /> Resets in {formatCountdown(resetsAtMs, now)}
           </span>
         ) : null}
-        {info.isUsingOverage ? <span className='text-warning'>overage</span> : null}
-        {info.status === 'rejected' ? <span className='text-danger'>limit reached</span> : null}
-        {/* Said plainly rather than drawn as a fact: the gateway zeroed this
-            because the reading's own reset time passed with nothing newer, so 0
-            is a floor — the account may have been spent elsewhere since. */}
+        {info.isUsingOverage ? <span className="text-warning">overage</span> : null}
+        {info.status === 'rejected' ? <span className="text-danger">limit reached</span> : null}
         {inferredReset ? <span>window reset · nothing reported since</span> : null}
-        {/* Per window, because they no longer share one clock: a reading learned
-            from a sibling session minutes ago can sit beside one this session
-            last heard about yesterday. */}
         {updatedAt && !inferredReset ? <span>{formatAgoPrecise(updatedAt, now)}</span> : null}
       </div>
     </div>

package/src/components/agent/pulse.tsx

@@ -1,39 +1,17 @@
 import { useEffect, useState } from 'react'
 
-/**
- * The brand mark's pulse, as characters — the working marker every surface in the
- * transcript animates.
- *
- * These are the mark's own four states (`docs/assets/BRAND.md`, "The loading
- * state"): a dot, an outline, a semi and a full diamond, built in the SVG from
- * two shapes rather than four drawings. 150ms each, so one cycle is the 0.6s
- * clock the marker pulses on in `icon-loading.svg` — the same rhythm, in the
- * medium a transcript row actually has.
- *
- * BRAND.md's caveat applies and is satisfied here: `U+25C6/7/8` are East-Asian
- * *ambiguous width*, so they can render double-width in a terminal under an
- * East-Asian locale and shift every line with them. They are safe wherever the
- * glyph is centred in a fixed-width box, which is what the terminal theme's
- * gutter cell (`.term-gutter`, one `--term-cell` wide) is. Anything writing to a
- * real terminal must use the ASCII set instead.
- */
 export const PULSE_FRAMES = ['⋄', '◇', '◈', '◆'] as const
 export const PULSE_MS = 150
 
-/**
- * The resting state. Stopping the animation lands on the complete mark rather
- * than on a half-drawn frame — the same property that makes the SVG's
- * `prefers-reduced-motion` free (see BRAND.md: `translateY(0)` *is* the mark).
- */
 export const PULSE_REST = PULSE_FRAMES[PULSE_FRAMES.length - 1]
 
-/** The OS-level "stop moving things" setting. A spinner is decoration — the word
- * beside it carries the meaning — so honouring this costs nothing. */
 export function usePrefersReducedMotion(): boolean {
   const [reduced, setReduced] = useState(false)
   useEffect(() => {
     const query = window.matchMedia?.('(prefers-reduced-motion: reduce)')
-    if (!query) return
+    if (!query) {
+      return
+    }
     setReduced(query.matches)
     const onChange = () => setReduced(query.matches)
     query.addEventListener('change', onChange)
@@ -42,20 +20,19 @@ export function usePrefersReducedMotion(): boolean {
   return reduced
 }
 
-/**
- * The current pulse frame, ticking while `animated`. Callers mount this only
- * while something is actually in flight, so nothing here runs on an idle
- * session; with reduced motion, or when not animating, it holds at rest.
- */
 export function usePulse(animated: boolean): string {
   const reduced = usePrefersReducedMotion()
   const running = animated && !reduced
   const [frame, setFrame] = useState(0)
   useEffect(() => {
-    if (!running) return
+    if (!running) {
+      return
+    }
     const timer = setInterval(() => setFrame((f) => f + 1), PULSE_MS)
     return () => clearInterval(timer)
   }, [running])
-  if (!running) return PULSE_REST
+  if (!running) {
+    return PULSE_REST
+  }
   return PULSE_FRAMES[frame % PULSE_FRAMES.length]!
 }

package/src/components/agent/scrubber-marks.ts

@@ -2,53 +2,15 @@ import type { TranscriptItem } from '@workerdeck/react'
 import { formatCost, formatDuration, toolInputPreview } from '../../lib/format.ts'
 import { parentOf } from '../terminal/blocks.ts'
 
-/**
- * The scrubber's mark model, shared between the two rails.
- *
- * The terminal scrubber (`terminal/scrubber.tsx`) positions marks in **pixel
- * space** — the virtualizer's row offsets, honest because the height calculator
- * feeds `estimateSize`. The cards variant has no such claim (proportional text,
- * variable row heights), so its rail (`agent/Scrubber.tsx`) positions marks in
- * **index space**: `itemIndex / items.length` of the rail. Less precise, but it
- * still answers the reader's questions — where did I type, where did it fail,
- * where is the approval waiting.
- *
- * What is shared here is the *classification*: which items earn a mark, which
- * lane a mark lives in, and who wins the colour when marks merge. The walk in
- * {@link buildMarks} mirrors `buildClusters`'s first half (the segment
- * machinery, sub-agent detection, bookmark/recap injection) minus everything
- * that needs a row model. One deliberate divergence: the terminal marks a
- * failed tool call only when it is its row's *outcome* (a fold's last member),
- * because that is what its transcript reddens; cards folds nothing
- * (`terminalBlocks` with `fold=false`), every failed top-level call reddens its
- * own card, so every one marks — the same "the rail marks what the transcript
- * reddens" rule, read against a surface with no folds.
- */
-
 export type Lane = 'l' | 'r' | 'f'
-export type MarkKind =
-  | 'user'
-  | 'subagent'
-  | 'turn'
-  | 'turnFailed'
-  | 'toolFailed'
-  | 'error'
-  | 'approval'
-  | 'recap'
-  | 'bookmark'
+export type MarkKind = 'user' | 'subagent' | 'turn' | 'turnFailed' | 'toolFailed' | 'error' | 'approval' | 'recap' | 'bookmark'
 
 export type Mark = {
   kind: MarkKind
-  /** The jump anchor (for a turn mark: the paired response). */
   itemIndex: number
-  /** The `turn_result` behind a right-lane mark — the peek shows its done-line. */
   turnIndex?: number
 }
 
-/** Members keep their own y: a dense transcript chain-merges a lane into one
- * tall bar, and the bar answers the pointer by its *nearest member* — a press
- * or peek at the middle of the bar must not act on the mark that happened to
- * found the cluster. */
 export type Cluster = {
   lane: Lane
   kind: MarkKind
@@ -57,20 +19,16 @@ export type Cluster = {
   marks: { mark: Mark; y: number }[]
 }
 
-/** The member closest to a rail-space y — what a press or peek on a merged
- * cluster resolves to. */
 export function nearestMember(cluster: Cluster, y: number): Mark | undefined {
   let best: { mark: Mark; y: number } | undefined
-  for (const member of cluster.marks)
-    if (!best || Math.abs(member.y - y) < Math.abs(best.y - y)) best = member
+  for (const member of cluster.marks) {
+    if (!best || Math.abs(member.y - y) < Math.abs(best.y - y)) {
+      best = member
+    }
+  }
   return best?.mark
 }
 
-/** The two lanes are channels, not classes: left is what went *in* (your
- * prompts, the sub-agents you dispatched), right is what came *out* (each
- * turn's answer, and everything that went wrong producing one). Full width is
- * for what is not a channel at all: the waiting approval, a bookmark, the
- * catch-up seam. See the terminal scrubber for the full argument. */
 export const LANE: Record<MarkKind, Lane> = {
   user: 'l',
   subagent: 'l',
@@ -83,7 +41,6 @@ export const LANE: Record<MarkKind, Lane> = {
   bookmark: 'f',
 }
 
-/** Who wins the colour when marks merge. */
 export const LOUDNESS: Record<MarkKind, number> = {
   approval: 7,
   error: 6,
@@ -108,48 +65,40 @@ export const KIND_NAME: Record<MarkKind, string> = {
   bookmark: 'bookmark',
 }
 
-/** The floor: an index-proportional mark has no extent to draw, so this is
- * usually the height too — 2px keeps a tick findable. */
 export const MIN_MARK = 2
 
-export const doneLine = (turn: Extract<TranscriptItem, { kind: 'turn_result' }>): string =>
-  `${turn.isError ? turn.subtype : 'done'} · ${formatDuration(turn.durationMs)} · ${formatCost(turn.totalCostUsd)}`
+export function doneLine(turn: Extract<TranscriptItem, { kind: 'turn_result' }>): string {
+  return `${turn.isError ? turn.subtype : 'done'} · ${formatDuration(turn.durationMs)} · ${formatCost(turn.totalCostUsd)}`
+}
 
 export function excerpt(item: TranscriptItem): string {
   switch (item.kind) {
     case 'user':
     case 'assistant_text':
     case 'thinking':
-    case 'notice':
+    case 'notice': {
       return item.text
-    case 'tool_call':
+    }
+    case 'tool_call': {
       return `${item.name}(${toolInputPreview(item.input)})`
-    case 'turn_result':
+    }
+    case 'turn_result': {
       return doneLine(item)
-    case 'file_delivered':
+    }
+    case 'file_delivered': {
       return item.path
-    default:
+    }
+    default: {
       return ''
+    }
   }
 }
 
-/** One right-lane mark per segment, emitted when the segment closes — by the
- * next prompt, by its own turn end, or by running out of items (which is what
- * a replayed history is made of, since `#backfillHistory` carries no turn
- * rows). A `turn_result` *decorates* the answer rather than conjuring the
- * mark, so a live answer with no turn end yet is still on the rail. */
 type Segment = { response?: number; turn?: number; failed?: boolean }
 
 export interface BuildMarksOptions {
-  /** The sub-agent takeover's parent id, when the rail belongs to a frame — it
-   * is what "top level" means here (`undefined` at the conversation's own
-   * level). Inside a frame every narration step is its own mark: the stream
-   * carries no prompts and no `turn_result` for the segment machinery to work
-   * with, and a fifty-step agent run is exactly where a rail earns its keep. */
   frameParentId?: string
-  /** Bookmarked item indices. Paint only — the store is the client's. */
   bookmarks?: readonly number[]
-  /** The catch-up boundary's item index, when the recap is spliced in. */
   recapItemIndex?: number
 }
 
@@ -158,14 +107,12 @@ export function buildMarks(
   { frameParentId, bookmarks = [], recapItemIndex }: BuildMarksOptions = {},
 ): Mark[] {
   const marks: Mark[] = []
-  // Which top-level calls a sub-agent ran inside — by `parentToolUseId`, never
-  // by the spawning call's *name*: `Task` is the SDK's convention (a background
-  // agent arrives as `Agent`), and an id other items demonstrably nest under IS
-  // a sub-agent whatever spawned it.
   const subagentParents = new Set<string>()
   for (const item of items) {
     const parent = parentOf(item)
-    if (parent !== undefined) subagentParents.add(parent)
+    if (parent !== undefined) {
+      subagentParents.add(parent)
+    }
   }
   let segment: Segment = {}
   const closeSegment = () => {
@@ -180,16 +127,9 @@ export function buildMarks(
     segment = {}
   }
   items.forEach((item, index) => {
-    // The dispatch itself. Deliberately not part of the chain below: a `Task`
-    // whose own result errored earns a red tick in the response lane *and*
-    // this mark in the input lane — one says a sub-agent ran here, the other
-    // says it came back broken.
     if (item.kind === 'tool_call' && subagentParents.has(item.id)) {
       marks.push({ kind: 'subagent', itemIndex: index })
     }
-    // Top-level prompts only, like the answer check below: a sub-agent's brief
-    // is a `user` item too, and it would both paint a "you" mark for something
-    // nobody typed and close the segment mid-turn.
     if (item.kind === 'user' && parentOf(item) === frameParentId) {
       closeSegment()
       marks.push({ kind: 'user', itemIndex: index })
@@ -200,11 +140,6 @@ export function buildMarks(
     } else if (item.kind === 'notice' && item.level === 'error') {
       marks.push({ kind: 'error', itemIndex: index })
     } else if (
-      // 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 this reducer has not settled yet. Top level only
-      // — a sub-agent's failed child is represented by the sub-agent mark and
-      // the Task's own red tick, exactly as the terminal rail does.
       item.kind === 'tool_call' &&
       parentOf(item) === frameParentId &&
       (item.status === 'failed' || item.result?.isError === true)
@@ -218,20 +153,18 @@ export function buildMarks(
       segment.response = index
     }
   })
-  // A history that ends mid-segment still has an answer in it.
   closeSegment()
-  for (const index of bookmarks)
-    if (index >= 0 && index < items.length) marks.push({ kind: 'bookmark', itemIndex: index })
-  if (recapItemIndex !== undefined) marks.push({ kind: 'recap', itemIndex: recapItemIndex })
+  for (const index of bookmarks) {
+    if (index >= 0 && index < items.length) {
+      marks.push({ kind: 'bookmark', itemIndex: index })
+    }
+  }
+  if (recapItemIndex !== undefined) {
+    marks.push({ kind: 'recap', itemIndex: recapItemIndex })
+  }
   return marks
 }
 
-/**
- * Place marks proportionally — y = `itemIndex / itemCount` of the rail, every
- * mark one item's share tall (floored at {@link MIN_MARK}) — then merge
- * adjacent ones per lane, the loudest colour winning. The same merge rule as
- * the terminal rail; only the position source differs.
- */
 export function clusterMarks(marks: readonly Mark[], railH: number, itemCount: number): Cluster[] {
   const count = Math.max(1, itemCount)
   const h = Math.max(MIN_MARK, Math.round(railH / count))
@@ -248,11 +181,11 @@ export function clusterMarks(marks: readonly Mark[], railH: number, itemCount: n
     list.sort((a, b) => a.y - b.y)
     let current: Cluster | null = null
     for (const { mark, y } of list) {
-      // Merge when the gap is under a pixel; the merged mark grows and takes
-      // the loudest member's colour.
       if (current && y <= current.y + current.h + 1) {
         current.h = Math.max(current.h, y + h - current.y)
-        if (LOUDNESS[mark.kind] > LOUDNESS[current.kind]) current.kind = mark.kind
+        if (LOUDNESS[mark.kind] > LOUDNESS[current.kind]) {
+          current.kind = mark.kind
+        }
         current.marks.push({ mark, y })
       } else {
         current = { lane, kind: mark.kind, y, h, marks: [{ mark, y }] }
@@ -263,9 +196,6 @@ export function clusterMarks(marks: readonly Mark[], railH: number, itemCount: n
   return clusters
 }
 
-/** The approval is not an item — the prompt renders below the transcript — so
- * its mark pins at the rail's foot, where the prompt is. Built by hand (no
- * item to derive a position from), hence `marks: []`. */
 export function approvalCluster(railH: number): Cluster {
   return {
     lane: LANE.approval,

package/src/components/agent/status.ts

@@ -1,15 +1,11 @@
 import type { SessionStatus } from '@workerdeck/protocol'
 import type { BadgeProps } from '../ui/Badge.tsx'
 
-export const STATUS_META: Record<
-  SessionStatus,
-  { label: string; variant: NonNullable<BadgeProps['variant']>; busy: boolean }
-> = {
+export const STATUS_META: Record<SessionStatus, { label: string; variant: NonNullable<BadgeProps['variant']>; busy: boolean }> = {
   starting: { label: 'Starting', variant: 'info', busy: true },
   running: { label: 'Running', variant: 'info', busy: true },
   awaiting_approval: { label: 'Needs approval', variant: 'warning', busy: true },
   idle: { label: 'Idle', variant: 'success', busy: false },
-  // Waiting on a deferred execution: the run is alive but nothing is burning.
   parked: { label: 'Parked', variant: 'accent', busy: false },
   failed: { label: 'Failed', variant: 'danger', busy: false },
   closed: { label: 'Closed', variant: 'neutral', busy: false },

package/src/components/agent/tool-result-fetch.tsx

@@ -1,36 +1,14 @@
 import { createContext, useContext, type ReactNode } from 'react'
 
-/**
- * How a row gets back the part of a tool result the replay did not send.
- *
- * A **context**, not a prop chain, for the same reason the variant is one: the
- * rows that need it are drawn by `terminalBlocks` and by the cards theme's
- * `ToolCallCard`, several layers below whoever holds the session, and a row
- * composed by hand should get the same behaviour without threading a callback
- * through everything in between.
- *
- * The default is a no-op resolving `false`, which is exactly right for every
- * surface that never asked for truncation (the playground, a fixture, an
- * embedder rendering rows by hand): `result.truncated` is only ever set by a
- * replay a renderer opted into, so a row that has no fetcher also has no head to
- * complete. A press still opens the row; it simply has everything already.
- */
 export type ToolResultFetcher = (toolUseId: string) => Promise<boolean>
 
-const FetchContext = createContext<ToolResultFetcher>(async () => false)
+const noop: ToolResultFetcher = async () => false
+const FetchContext = createContext<ToolResultFetcher>(noop)
 
-export function ToolResultFetchProvider({
-  value,
-  children,
-}: {
-  value: ToolResultFetcher | undefined
-  children: ReactNode
-}) {
+export function ToolResultFetchProvider({ value, children }: { value: ToolResultFetcher | undefined; children: ReactNode }) {
   return <FetchContext.Provider value={value ?? noop}>{children}</FetchContext.Provider>
 }
 
-const noop: ToolResultFetcher = async () => false
-
 export function useToolResultFetcher(): ToolResultFetcher {
   return useContext(FetchContext)
 }