@workerdeck/ui 0.15.0 → 0.16.0

package/src/components/agent/UsageDialog.tsx

@@ -1,56 +1,36 @@
-import { useEffect, useState } from 'react'
-import type { ProfileEngine, RateLimitInfo } from '@workerdeck/protocol'
-import { RotateCcw } from 'lucide-react'
+import type { ProfileEngine, UsageWindowRow } from '@workerdeck/protocol'
 import { Badge } from '../ui/Badge.tsx'
 import { Dialog, DialogBody, DialogContent, DialogHeader } from '../ui/Dialog.tsx'
-import { cn } from '../../lib/utils.ts'
-import {
-  formatAgoPrecise,
-  formatCost,
-  formatCountdown,
-  formatRateLimitWindowLong,
-  rateLimitWindowSeconds,
-} from '../../lib/format.ts'
+import { formatAgoPrecise, formatCost } from '../../lib/format.ts'
+import { UsageMeters, useMinuteClock } from './UsageMeters.tsx'
 
 export interface UsageDialogProps {
-  /** Windows in reading order — session, weekly, then per-model weeklies. */
-  rateLimits: Array<{ key: string; info: RateLimitInfo }>
+  /**
+   * Windows in reading order — session, weekly, then per-model weeklies.
+   *
+   * `updatedAt`/`inferredReset` ride each window because the readings no longer
+   * share one clock: the panel merges the gateway's per-profile state over this
+   * session's, so a `five_hour` learned from a sibling session two minutes ago
+   * can sit beside a `seven_day` this session last heard about yesterday.
+   * `inferredReset` marks the ones the *gateway* zeroed because their own reset
+   * time passed with nothing newer — a floor, not a report.
+   */
+  rateLimits: UsageWindowRow[]
   /** claude.ai plan behind the windows ('max', 'pro', …), when there is one. */
   subscriptionType?: string
   engine: ProfileEngine
   totalCostUsd: number
-  /** Local receipt time of the last window update. `rate_limit` events are one
-   * per turn at best, so a stale reading is normal and worth saying out loud. */
+  /** When the *freshest* of the windows was read, for the footer line. Readings
+   * arrive one per turn at best (and for an idle session, not at all), so a
+   * stale one is normal and worth saying out loud. */
   updatedAt?: number
   open: boolean
   onOpenChange: (open: boolean) => void
 }
 
-/** Ticking clock — the countdowns and the pace markers both move with it, and a
- * minute is the finest resolution either of them prints. */
-function useMinuteClock(open: boolean): number {
-  const [now, setNow] = useState(() => Date.now())
-  useEffect(() => {
-    if (!open) return
-    setNow(Date.now())
-    const timer = setInterval(() => setNow(Date.now()), 60_000)
-    return () => clearInterval(timer)
-  }, [open])
-  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 CLI 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.
+ * The session's view of the plan: every window as a meter (see
+ * {@link UsageMeters}), the plan tier, and what this session itself has cost.
  */
 export function UsageDialog({
   rateLimits,
@@ -86,11 +66,7 @@ export function UsageDialog({
                 : `Plan windows are a claude.ai subscription thing; this session runs on the ${engine} engine.`}
             </p>
           ) : (
-            <div className='flex flex-col gap-5'>
-              {rateLimits.map(({ key, info }) => (
-                <UsageWindow key={key} windowKey={key} info={info} now={now} />
-              ))}
-            </div>
+            <UsageMeters windows={rateLimits} now={now} />
           )}
           <div className='mt-5 flex items-baseline justify-between gap-4 border-t border-border pt-3'>
             <span className='text-label text-fg-3'>This session has cost</span>
@@ -104,65 +80,3 @@ export function UsageDialog({
     </Dialog>
   )
 }
-
-function UsageWindow({
-  windowKey,
-  info,
-  now,
-}: {
-  windowKey: string
-  info: RateLimitInfo
-  now: number
-}) {
-  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 =
-    duration !== undefined && remaining !== undefined && remaining > 0 && remaining < duration
-      ? (duration - remaining) / duration
-      : 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',
-          )}>
-          {utilization.toFixed(0)}% used
-        </span>
-      </div>
-      <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.
-          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'
-            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'>
-        {resetsAtMs !== undefined ? (
-          <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}
-      </div>
-    </div>
-  )
-}

package/src/components/agent/UsageMeters.tsx

@@ -0,0 +1,133 @@
+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'
+
+/**
+ * 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
+    setNow(Date.now())
+    const timer = setInterval(() => setNow(Date.now()), 60_000)
+    return () => clearInterval(timer)
+  }, [active])
+  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
+}) {
+  const ownClock = useMinuteClock(now === undefined)
+  const clock = now ?? ownClock
+  return (
+    <div className={cn('flex flex-col gap-5', className)}>
+      {windows.map((window) => (
+        <UsageMeter key={window.key} window={window} now={clock} />
+      ))}
+    </div>
+  )
+}
+
+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 =
+    duration !== undefined && remaining !== undefined && remaining > 0 && remaining < duration
+      ? (duration - remaining) / duration
+      : 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',
+          )}>
+          {utilization.toFixed(0)}% used
+        </span>
+      </div>
+      <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.
+          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'
+            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'>
+        {resetsAtMs !== undefined ? (
+          <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. */}
+        {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

@@ -13,8 +13,9 @@ import { useEffect, useState } from 'react'
  * 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 `LineGlyph` is. Anything
- * writing to a real terminal must use the ASCII set instead.
+ * 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

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

@@ -0,0 +1,82 @@
+/**
+ * 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, or
+ * — under the terminal theme — a folded run of tool calls), 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, so a
+ * run and a lone tool call below it 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]
+  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)
+}
+
+/**
+ * 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, 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 rule: the **last non-recap row whose first item index is ≤ the target**.
+ * Rows are ordered by `index` (a run's row covers
+ * `[index, index + run.length)`), so this is a binary search; 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`.
+ */
+export function rowIndexForItem(rows: readonly TranscriptRow[], itemIndex: number): number {
+  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
+}

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
+}