@workerdeck/ui 0.15.0 → 0.17.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/tool-result-fetch.tsx

@@ -0,0 +1,36 @@
+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)
+
+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)
+}

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

@@ -0,0 +1,209 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+import type { WorkerDeckClient } from '@workerdeck/client'
+
+/**
+ * How a row gets the picture the replay refused to send.
+ *
+ * The sibling of `tool-result-fetch.tsx` and the same shape of seam, because it
+ * answers the same shape of question: an opted-in socket delivers a base64
+ * `image` part as an `image_ref` — media type, decoded size, and its index in
+ * the stored block — and the bytes are fetched over REST by whoever is actually
+ * looking at the row. Across a measured corpus that payload was 91% of every
+ * tool result and nothing rendered a byte of it.
+ *
+ * A **context**, not a prop chain, for the variant's reason: the rows are drawn
+ * by `terminalBlocks` and by `ToolCallCard`, several layers under whoever holds
+ * the session. The default resolves `undefined`, which is exactly right for
+ * every surface that never asked (the playground, a fixture, a hand-composed
+ * row): `result.images` is only ever set by a replay a renderer opted into, so a
+ * row with no loader also has no reference to load. Only `SessionPanel` supplies
+ * a real one, because it owns the session's one attach and therefore the only
+ * `(seq, toolUseId)` addresses that mean anything.
+ */
+
+/** One image part, as the row addresses it: the reducer's entry plus the id of
+ * the call it came back from. `sourceSeq` is the entry's **own** — the
+ * result-level one is cleared by text hydration, and a reader who pressed "show
+ * everything" must still be able to load the screenshot afterwards. */
+export type ToolResultImageRef = {
+  toolUseId: string
+  sourceSeq: number
+  partIndex: number
+  mediaType: string
+  bytes: number
+}
+
+/** Resolves an object URL for the picture, or `undefined` when the gateway will
+ * not serve it — a stale address after a dormant wake, a gateway with no such
+ * route, a dropped connection. The row draws a box either way. */
+export type ToolResultImageLoader = (ref: ToolResultImageRef) => Promise<string | undefined>
+
+const noop: ToolResultImageLoader = async () => undefined
+
+const ImageContext = createContext<ToolResultImageLoader>(noop)
+
+export function ToolResultImageProvider({
+  value,
+  children,
+}: {
+  value: ToolResultImageLoader | undefined
+  children: ReactNode
+}) {
+  return <ImageContext.Provider value={value ?? noop}>{children}</ImageContext.Provider>
+}
+
+export function useToolResultImageLoader(): ToolResultImageLoader {
+  return useContext(ImageContext)
+}
+
+/**
+ * Long enough that a fast scrub through an image-heavy session fetches nothing
+ * it flew past, short enough to be invisible to a reader who stopped.
+ *
+ * There is no second visibility system here on purpose: the transcript is
+ * virtualized, so a *mounted* row is by definition within an overscan of the
+ * viewport — the virtualizer already is the IntersectionObserver, and a second
+ * answer to a question that has one is how the two disagree.
+ */
+const MOUNT_SETTLE_MS = 150
+
+export type ToolResultImageState = { src?: string; failed: boolean }
+
+/**
+ * One box's load, for either theme.
+ *
+ * Fires once the row has been mounted for {@link MOUNT_SETTLE_MS}, and then
+ * **runs to completion** — an aborted fetch re-pays the whole image on the
+ * return visit, and the gateway is HTTP/1.1, so the browser's per-origin
+ * connection cap is the concurrency throttle for free.
+ *
+ * The effect keys on the address's *primitives*, never on the ref object: the
+ * reducer replaces items on every streamed delta, so an object-identity dep
+ * would re-run this on every token of the turn after it.
+ */
+export function useToolResultImageSrc(ref: ToolResultImageRef): ToolResultImageState {
+  const load = useToolResultImageLoader()
+  const [state, setState] = useState<ToolResultImageState>({ failed: false })
+  const { toolUseId, sourceSeq, partIndex, mediaType, bytes } = ref
+  useEffect(() => {
+    let live = true
+    setState({ failed: false })
+    const timer = setTimeout(() => {
+      load({ toolUseId, sourceSeq, partIndex, mediaType, bytes })
+        .then((src) => {
+          if (live) setState({ src, failed: src === undefined })
+        })
+        .catch(() => {
+          if (live) setState({ failed: true })
+        })
+    }, MOUNT_SETTLE_MS)
+    return () => {
+      live = false
+      clearTimeout(timer)
+    }
+  }, [load, toolUseId, sourceSeq, partIndex, mediaType, bytes])
+  return state
+}
+
+/** ~64 MB of decoded pictures held at once. At the corpus's 335 KB median that
+ * is ~190 images, which no viewport holds; the budget exists so a session
+ * scrolled end to end does not pin every screenshot it passed. */
+const CACHE_BUDGET_BYTES = 64 * 1024 * 1024
+
+type Entry = { pending: Promise<string | undefined>; url?: string; bytes: number }
+
+/**
+ * `useHostImage`'s shape, generalized to the replay route — and **bounded**,
+ * which `useHostImage` is not.
+ *
+ * The promise-per-key cache is what makes this callable from a transcript row at
+ * all: rows re-render on every streamed delta, and an uncached resolver would
+ * re-fetch each time. The LRU is the part that is new. Object URLs pin their
+ * blob until revoked, so a fully-scrolled hundred-image session would otherwise
+ * hold ~50 MB until the panel unmounted — and evicting means revoking, or the
+ * eviction frees a `Map` entry and nothing else.
+ *
+ * Re-fetching on a return scroll is fine, and is the whole design: the bytes are
+ * one authenticated request away, which is precisely what makes it cheap not to
+ * have shipped them in the attach.
+ */
+export function useToolResultImages(
+  client: WorkerDeckClient,
+  sessionId: string | undefined,
+): ToolResultImageLoader {
+  const cache = useRef(new Map<string, Entry>())
+  useEffect(
+    () => () => {
+      for (const entry of cache.current.values()) if (entry.url) URL.revokeObjectURL(entry.url)
+      cache.current.clear()
+    },
+    [],
+  )
+  return useCallback(
+    (ref: ToolResultImageRef) => {
+      if (!sessionId) return Promise.resolve(undefined)
+      // The whole address, because every part of it can change under a row that
+      // is still on screen: a dormant wake restarts the seqs, and a cached
+      // address that outlived its log must miss rather than serve another
+      // call's pixels.
+      const key = `${sessionId}:${ref.sourceSeq}:${ref.toolUseId}:${ref.partIndex}`
+      const hit = cache.current.get(key)
+      if (hit) {
+        // Re-inserting is the "recently used" half of the LRU: `Map` iterates in
+        // insertion order, so eviction reads oldest-first for free.
+        cache.current.delete(key)
+        cache.current.set(key, hit)
+        return hit.pending
+      }
+      // Fetched rather than pointed at: a bare `<img src>` at the gateway
+      // carries a credential in exactly one of four clients (the dashboard's
+      // same-origin host), and a broken icon in the other three.
+      const pending = client
+        .toolResultImage(sessionId, ref.sourceSeq, ref.toolUseId, ref.partIndex)
+        .then((blob) => {
+          if (blob.size === 0) return undefined
+          const url = URL.createObjectURL(blob)
+          const entry = cache.current.get(key)
+          if (entry) {
+            entry.url = url
+            entry.bytes = blob.size
+            evict(cache.current, key)
+          } else {
+            // Evicted (or unmounted) while in flight — nothing will ever draw
+            // this, and an unrevoked URL is the leak the budget exists to stop.
+            URL.revokeObjectURL(url)
+          }
+          return url
+        })
+        .catch(() => undefined)
+      // The declared size is what the budget counts until the bytes land: a
+      // hundred fetches in flight must not all read as free.
+      cache.current.set(key, { pending, bytes: ref.bytes })
+      return pending
+    },
+    [client, sessionId],
+  )
+}
+
+/** Drop oldest-first until the held bytes fit the budget, revoking as it goes.
+ * `keep` is the entry just resolved — evicting the picture a row is about to
+ * draw would be a fetch spent on nothing. */
+function evict(cache: Map<string, Entry>, keep: string): void {
+  let held = 0
+  for (const entry of cache.values()) held += entry.bytes
+  for (const [key, entry] of cache) {
+    if (held <= CACHE_BUDGET_BYTES) return
+    if (key === keep) continue
+    if (entry.url) URL.revokeObjectURL(entry.url)
+    cache.delete(key)
+    held -= entry.bytes
+  }
+}