@workerdeck/ui 0.11.0 → 0.12.0

package/src/components/agent/Transcript.tsx

@@ -16,8 +16,10 @@ import { SessionEmptyState } from './SessionEmptyState.tsx'
 import { ToolCallCard } from './ToolCallCard.tsx'
 import {
   LineGlyph,
+  ROW_GAP,
   TranscriptVariantProvider,
   useLines,
+  type TranscriptDensity,
   type TranscriptVariant,
 } from './transcript-variant.tsx'
 
@@ -339,6 +341,7 @@ function TranscriptRows({
   boundary,
   since,
   lines,
+  gap,
   fileUrl,
   attachmentUrl,
   hostImage,
@@ -348,6 +351,8 @@ function TranscriptRows({
   boundary: number | undefined
   since: number | undefined
   lines: boolean
+  /** The inter-row gap for this variant and density (`ROW_GAP`). */
+  gap: { className?: string; px: number }
   fileUrl?: (path: string) => string
   attachmentUrl?: (attachmentId: string) => string
   hostImage?: (path: string) => Promise<string | undefined>
@@ -387,7 +392,10 @@ function TranscriptRows({
     // a measurement replaces them the moment a row mounts. A lines row is one
     // text line more often than not; cards vary too much for any constant to
     // be right, so that one is merely the order of magnitude.
-    estimateSize: () => (lines ? 32 : 100),
+    // Plus the gap, which is real height on the same measured element — an
+    // estimate that ignored it would make the scrollbar visibly too short on a
+    // long transcript before the rows mount.
+    estimateSize: () => (lines ? 32 : 100) + gap.px,
     overscan: 8,
     getItemKey: (index) => rows[index].key,
     // Explicit, and left at the default, because the obvious cleanup here is
@@ -484,13 +492,14 @@ function TranscriptRows({
             data-index={virtualRow.index}
             className={cn(
               'absolute inset-x-0 top-0',
-              // The card layout's inter-row gap, folded into each row so the
-              // measured height carries it: flex `gap` cannot reach absolutely
-              // positioned rows, and a pixel constant for the virtualizer's
-              // `gap` option would drift from the rem the layout is set in.
-              // On this outer wrapper, not the row div, so a nested row's left
-              // border still breaks across the gap as it did under flex.
-              !lines && virtualRow.index > 0 && 'pt-4',
+              // The inter-row gap, folded into each row so the measured height
+              // carries it: flex `gap` cannot reach absolutely positioned rows,
+              // and a pixel constant for the virtualizer's `gap` option would
+              // drift from the rem the layout is set in. On this outer wrapper,
+              // not the row div, so a nested row's left border still breaks
+              // across the gap as it did under flex. Skipped for the first row —
+              // a gap above it would be padding, not spacing.
+              virtualRow.index > 0 && gap.className,
             )}
             style={{ transform: `translateY(${virtualRow.start}px)` }}>
             {'item' in row ? (
@@ -541,6 +550,12 @@ export interface TranscriptProps {
    * vertical space is scarce. See {@link TranscriptVariant}.
    */
   variant?: TranscriptVariant
+  /**
+   * How much air each row gets: `comfortable` (default — a blank line between
+   * messages, as the Claude Code CLI does) or `compact`. Independent of
+   * {@link TranscriptVariant}. See {@link TranscriptDensity}.
+   */
+  density?: TranscriptDensity
   /**
    * Catch-up: `from` is how many items had been seen last time, `since` when
    * that was. A recap row is drawn at that boundary and everything above it is
@@ -566,11 +581,13 @@ export function Transcript({
   canBrowseFiles,
   hostImage,
   variant = 'cards',
+  density = 'comfortable',
   catchUp,
   jumpToRecapRef,
   className,
 }: TranscriptProps) {
   const lines = variant === 'lines'
+  const gap = ROW_GAP[variant][density]
   const runStartedAt = useRunStart(state.status)
   const following = useSettled(state.items.length, state.status)
   // A boundary at (or past) the end means nothing is new — no row, no dimming.
@@ -605,6 +622,7 @@ export function Transcript({
               boundary={boundary}
               since={catchUp?.since}
               lines={lines}
+              gap={gap}
               fileUrl={fileUrl}
               attachmentUrl={attachmentUrl}
               hostImage={hostImage}

package/src/components/agent/pulse.tsx

@@ -0,0 +1,60 @@
+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 `LineGlyph` 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
+    setReduced(query.matches)
+    const onChange = () => setReduced(query.matches)
+    query.addEventListener('change', onChange)
+    return () => query.removeEventListener('change', onChange)
+  }, [])
+  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
+    const timer = setInterval(() => setFrame((f) => f + 1), PULSE_MS)
+    return () => clearInterval(timer)
+  }, [running])
+  if (!running) return PULSE_REST
+  return PULSE_FRAMES[frame % PULSE_FRAMES.length]!
+}

package/src/components/agent/transcript-variant.tsx

@@ -39,6 +39,68 @@ 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.
+ * - `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.
+ */
+export type TranscriptDensity = 'comfortable' | 'compact'
+
+const DensityContext = createContext<TranscriptDensity>('comfortable')
+
+export function TranscriptDensityProvider({
+  value,
+  children,
+}: {
+  value: TranscriptDensity
+  children: ReactNode
+}) {
+  return <DensityContext.Provider value={value}>{children}</DensityContext.Provider>
+}
+
+export function useTranscriptDensity(): TranscriptDensity {
+  return useContext(DensityContext)
+}
+
+/**
+ * The gap between two rows, per variant and density — the whole of the density
+ * feature, since it is the only vertical spacing between rows that exists.
+ *
+ * `className` goes on the **measured** wrapper (see `Transcript`), so the gap is
+ * part of each row's measured height and no pixel constant is load-bearing.
+ * `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 }>
+> = {
+  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 —

package/src/format.ts

@@ -8,3 +8,4 @@
  * costs nothing and keeps one truth for what "45.2k" and "2h 10m" mean.
  */
 export * from './lib/format.ts'
+export * from './lib/status.ts'

package/src/index.ts

@@ -83,8 +83,11 @@ export {
 } from './components/agent/Conversation.tsx'
 export { Message, MessageContent, type MessageProps } from './components/agent/Message.tsx'
 export {
+  TranscriptDensityProvider,
   TranscriptVariantProvider,
+  useTranscriptDensity,
   useTranscriptVariant,
+  type TranscriptDensity,
   type TranscriptVariant,
 } from './components/agent/transcript-variant.tsx'
 export { Response, type ResponseProps } from './components/agent/Response.tsx'
@@ -133,6 +136,7 @@ export {
   type SessionListItemProps,
   type SessionListProps,
 } from './components/agent/SessionList.tsx'
+export { SessionBrowser, type SessionBrowserProps } from './components/agent/SessionBrowser.tsx'
 export {
   SessionEmptyState,
   type SessionEmptyStateProps,

package/src/lib/status.ts

@@ -0,0 +1,124 @@
+import type { ContextUsage, ModelOption, RateLimitInfo, SessionStatus } from '@workerdeck/protocol'
+
+/**
+ * How a session's live readings become a status line — the pure half, so every
+ * host spells "Needs approval", "80% is a warning" and "which window is the
+ * binding one" the same way.
+ *
+ * Structurally typed against `SessionVitals` rather than importing it: this file
+ * ships from the React-free `@workerdeck/ui/format` entry, and a host drawing
+ * the readings outside React (the VS Code extension host in the window status
+ * bar) must not pull a component graph in to do it. A real `SessionVitals`
+ * satisfies every shape here.
+ */
+export type StatusSeverity = 'none' | 'warning' | 'error'
+
+/** What a status slot shows, before any host's icon vocabulary gets involved.
+ * `icon` is a VS Code codicon name — the one host-shaped thing left, because the
+ * alternative is a second mapping table in the only consumer. */
+export type StatusPresentation = {
+  icon: string
+  label: string
+  severity: StatusSeverity
+}
+
+export type StatusReadings = {
+  status: SessionStatus
+  /** `@workerdeck/react`'s `ConnectionState`, structurally — the link state wins
+   * the slot, so it has to be part of the reading. */
+  connection?: 'live' | 'reconnecting' | 'offline'
+}
+
+const STATUS_META: Record<SessionStatus, StatusPresentation> = {
+  starting: { icon: 'loading~spin', label: 'Starting', severity: 'none' },
+  running: { icon: 'loading~spin', label: 'Running', severity: 'none' },
+  awaiting_approval: { icon: 'warning', label: 'Needs approval', severity: 'warning' },
+  idle: { icon: 'check', label: 'Idle', severity: 'none' },
+  parked: { icon: 'debug-pause', label: 'Parked', severity: 'none' },
+  failed: { icon: 'error', label: 'Failed', severity: 'error' },
+  closed: { icon: 'circle-slash', label: 'Closed', severity: 'none' },
+}
+
+/**
+ * The status slot, connection first. A session status held over a dead socket is
+ * the last thing we heard, not the current state — so a lost link takes the slot
+ * rather than letting "Running" imply a turn is still streaming.
+ */
+export function statusPresentation(vitals: StatusReadings | undefined): StatusPresentation {
+  if (!vitals) return { icon: 'hubot', label: 'Connecting…', severity: 'none' }
+  if (vitals.connection === 'offline') {
+    return { icon: 'debug-disconnect', label: 'Offline', severity: 'error' }
+  }
+  if (vitals.connection === 'reconnecting') {
+    return { icon: 'sync~spin', label: 'Reconnecting…', severity: 'warning' }
+  }
+  return STATUS_META[vitals.status] ?? { icon: 'hubot', label: vitals.status, severity: 'none' }
+}
+
+/** 0–100 → the colour a meter wears. One pair of thresholds for every surface. */
+export function meterSeverity(pct: number | undefined): StatusSeverity {
+  if (pct === undefined) return 'none'
+  if (pct >= 95) return 'error'
+  if (pct >= 80) return 'warning'
+  return 'none'
+}
+
+/** The rate-limit window that gets the one visible slot: whichever is fullest,
+ * since the binding constraint is the one worth glancing at. */
+export function tightestWindow(
+  rateLimits: Record<string, RateLimitInfo> | undefined,
+): { key: string; info: RateLimitInfo } | undefined {
+  const entries = Object.entries(rateLimits ?? {})
+  if (entries.length === 0) return undefined
+  let best: { key: string; info: RateLimitInfo } | undefined
+  for (const [key, info] of entries) {
+    // A rejected window outranks any utilization: it is the one actually blocking.
+    const rank = info.status === 'rejected' ? Number.POSITIVE_INFINITY : (info.utilization ?? -1)
+    const bestRank =
+      best === undefined
+        ? Number.NEGATIVE_INFINITY
+        : best.info.status === 'rejected'
+          ? Number.POSITIVE_INFINITY
+          : (best.info.utilization ?? -1)
+    if (rank > bestRank) best = { key, info }
+  }
+  return best
+}
+
+/** A rate-limit window's key, named for a human. */
+export function windowLabel(key: string): string {
+  if (key === 'five_hour') return 'Session'
+  if (key === 'seven_day') return 'Weekly'
+  return key.replaceAll('_', ' ')
+}
+
+export type ModelReadings = { model?: string; models: readonly ModelOption[] }
+
+/**
+ * The catalog row a session is actually running, or `undefined` for a model the
+ * list doesn't name. Matched leniently: a session reports the *resolved* id
+ * (`claude-sonnet-5`) where the row may be keyed on the alias (`sonnet`), and
+ * either can carry a `[1m]` context-window suffix.
+ */
+export function currentModel(vitals: ModelReadings | undefined): ModelOption | undefined {
+  const id = vitals?.model
+  if (!id) return undefined
+  const bare = (value: string) => value.replace(/\[.*\]$/, '')
+  const wanted = bare(id)
+  return vitals.models.find(
+    (m) => bare(m.value) === wanted || (m.resolvedModel && bare(m.resolvedModel) === wanted),
+  )
+}
+
+/** A session's model, named the way the picker names it. Falls back to the raw
+ * id, and to "Default" while the session is on the CLI's own pick. */
+export function modelLabel(vitals: ModelReadings | undefined): string {
+  if (!vitals?.model) return 'Default'
+  return currentModel(vitals)?.displayName ?? vitals.model
+}
+
+/** Context percentage as its meter severity — the reading and the colour come
+ * from one place so a panel and a status bar never disagree. */
+export function contextSeverity(usage: ContextUsage | undefined): StatusSeverity {
+  return meterSeverity(usage?.percentage)
+}