@workerdeck/ui 0.11.0 → 0.13.0

package/src/components/agent/SessionPanel.tsx

@@ -49,7 +49,12 @@ import { QuestionPrompt, parseUserQuestions } from './QuestionPrompt.tsx'
 import { SessionInfoDialog } from './SessionInfoDialog.tsx'
 import { StatusBar } from './StatusBar.tsx'
 import { Transcript } from './Transcript.tsx'
-import { TranscriptVariantProvider, type TranscriptVariant } from './transcript-variant.tsx'
+import {
+  TranscriptDensityProvider,
+  TranscriptVariantProvider,
+  type TranscriptDensity,
+  type TranscriptVariant,
+} from './transcript-variant.tsx'
 import { UsageDialog } from './UsageDialog.tsx'
 
 export interface SessionPanelProps {
@@ -93,6 +98,17 @@ export interface SessionPanelProps {
    * take the menu, or it has nowhere left to go.
    */
   statusSurface?: 'internal' | 'external'
+  /**
+   * Which end of the panel the status bar sits at. Default `top`.
+   *
+   * `bottom` is the editor convention — VS Code's status bar runs along the
+   * foot of the window — and suits a host where the panel *is* the editor area
+   * and the chrome above it already belongs to the app. Placement only; the bar
+   * is the same bar, with the same `⋯` menu in its trailing slot, so this
+   * composes with {@link statusSurface} rather than competing with it (external
+   * still means "there isn't one").
+   */
+  statusPlacement?: 'top' | 'bottom'
   /** Where `panelSurface: 'external'` routes opens. Absent = the affordances
    * (status-bar clicks, `/mcp`) become inert rather than half-working. */
   onOpenPanel?: (panel: SessionSurfacePanel) => void
@@ -107,6 +123,14 @@ export interface SessionPanelProps {
    * (the VS Code panel) wants `'lines'`; a full-width dashboard usually doesn't.
    */
   transcriptVariant?: TranscriptVariant
+  /**
+   * How much air the transcript gives each row — `'comfortable'` (default: a
+   * blank line between messages, as the Claude Code CLI leaves) or `'compact'`
+   * (rows tight against one another). Independent of `transcriptVariant`: the
+   * variant follows from the surface, density is the reader's preference, and a
+   * dock is allowed to be roomy.
+   */
+  transcriptDensity?: TranscriptDensity
   /**
    * Where the session's own controls — model and permission mode — live.
    * `'internal'` (default) draws them in the composer's toolbar row.
@@ -148,6 +172,22 @@ export interface SessionPanelProps {
    * the number to remember through `SessionVitals.itemCount`.
    */
   unseen?: { itemCount: number; since?: number }
+  /**
+   * A viewer, not a seat at the session: transcript, status bar and panels as
+   * usual, but no composer and no approval prompts.
+   *
+   * For a surface that is *about* a run rather than in it — the dashboard's job
+   * detail, where the session belongs to the queue and typing into it would be a
+   * second operator arriving mid-run. Deliberately not "disabled controls": a
+   * greyed-out composer says the session is busy, an absent one says this screen
+   * does not drive it. The attach is still live and read paths are untouched,
+   * so the transcript streams and the file tree browses.
+   *
+   * It does **not** claim to be an authorization boundary. Anything holding this
+   * client can still send; what it removes is the affordance, and the honest
+   * enforcement lives on the gateway.
+   */
+  readOnly?: boolean
   className?: string
 }
 
@@ -156,6 +196,15 @@ export type SessionControls = {
   setModel: (model?: string) => void
   setPermissionMode: (mode: PermissionMode) => void
   interrupt: () => void
+  /**
+   * Put the caret in the composer.
+   *
+   * For an embedder whose own chrome is how you arrive at a session — clicking a
+   * row in VS Code's sidebar — where revealing the panel and being able to type
+   * are the same intention. The panel cannot infer it: from in here, a session
+   * appearing looks identical whether someone asked for it or it was restored.
+   */
+  focusComposer: () => void
 }
 
 /** Everything a click can mean other than "put the caret in the composer".
@@ -229,13 +278,16 @@ export function SessionPanel({
   header,
   panelSurface = 'internal',
   statusSurface = 'internal',
+  statusPlacement = 'top',
   onOpenPanel,
   onVitals,
   transcriptVariant = 'cards',
+  transcriptDensity = 'comfortable',
   controlsSurface = 'internal',
   onControls,
   focusComposerOnClick = false,
   unseen,
+  readOnly = false,
   className,
 }: SessionPanelProps) {
   const external = panelSurface === 'external'
@@ -358,6 +410,7 @@ export function SessionPanel({
     setModel: (model) => setters.current.setModel(model),
     setPermissionMode: (mode) => setters.current.setPermissionMode(mode),
     interrupt: () => setters.current.interrupt(),
+    focusComposer: () => composerRef.current?.focus(),
   })
   useEffect(() => {
     const handler = onControlsRef.current
@@ -479,11 +532,26 @@ export function SessionPanel({
   const menu = external ? null : actionsMenu
   const headerTakesActions = typeof header === 'function'
 
+  // Built once and placed at one end or the other — the bar has a `⋯` menu and
+  // three open handlers, and two copies of that in the tree would be two things
+  // to keep in step.
+  const statusBar = statusExternal ? null : (
+    <StatusBar
+      state={state}
+      connection={connection}
+      placement={statusPlacement}
+      onOpenStatus={external && !onOpenPanel ? undefined : () => openPanel('info')}
+      onOpenContext={external && !onOpenPanel ? undefined : () => openPanel('context')}
+      onOpenUsage={external && !onOpenPanel ? undefined : () => openPanel('usage')}
+      actions={headerTakesActions ? undefined : menu}
+    />
+  )
+
   // Dead-space clicks land in the composer. Anything the user actually aimed at
   // — a control, a link, the end of a drag-selection — keeps its own meaning;
   // this only claims what was left over.
   const handleClick = (event: ReactMouseEvent<HTMLDivElement>) => {
-    if (!focusComposerOnClick) return
+    if (!focusComposerOnClick || readOnly) return
     const target = event.target as HTMLElement | null
     if (target?.closest(INTERACTIVE)) return
     if (window.getSelection()?.isCollapsed === false) return
@@ -495,21 +563,13 @@ export function SessionPanel({
     // and question prompts live outside the scroller but are line items in the
     // same run, and they read `useLines()` like every other row.
     <TranscriptVariantProvider value={transcriptVariant}>
+      <TranscriptDensityProvider value={transcriptDensity}>
       <div
         data-slot='session-panel'
         onClick={handleClick}
         className={cn('flex h-full min-h-0 flex-col overflow-hidden bg-bg', className)}>
         {headerTakesActions ? header({ actions: menu }) : header}
-        {statusExternal ? null : (
-          <StatusBar
-            state={state}
-            connection={connection}
-            onOpenStatus={external && !onOpenPanel ? undefined : () => openPanel('info')}
-            onOpenContext={external && !onOpenPanel ? undefined : () => openPanel('context')}
-            onOpenUsage={external && !onOpenPanel ? undefined : () => openPanel('usage')}
-            actions={headerTakesActions ? undefined : menu}
-          />
-        )}
+        {statusPlacement === 'top' ? statusBar : null}
         {protocolMismatch !== undefined ? (
           <Notice level='warning'>
             Server speaks protocol v{protocolMismatch}, this build renders v{PROTOCOL_VERSION}. Some
@@ -528,6 +588,7 @@ export function SessionPanel({
           canBrowseFiles={hostFiles.available}
           hostImage={hostImage}
           variant={transcriptVariant}
+          density={transcriptDensity}
           catchUp={
             catchUp && newCount > 0
               ? { from: catchUp.itemCount, since: catchUp.since }
@@ -543,7 +604,12 @@ export function SessionPanel({
             <div
               data-slot='catch-up'
               className='mx-auto flex w-full max-w-[var(--wd-content-max-w,48rem)] items-center gap-2 text-label text-fg-3'>
-              <span aria-hidden className='select-none text-accent'>
+              <span
+                aria-hidden
+                className={cn(
+                  'select-none',
+                  transcriptVariant === 'lines' ? 'text-fg-3' : 'text-accent',
+                )}>
                 ※
               </span>
               <span className='min-w-0 flex-1 truncate'>
@@ -568,7 +634,10 @@ export function SessionPanel({
         {/* An engine with no approval channel never raises these, but a stale
             pending request from a replayed log would still render — the record is
             the authority on whether an approval UI means anything here. */}
-        {capabilities.interactiveApprovals && state.pendingApprovals.length > 0 ? (
+        {/* A read-only surface has no answer to give: the status bar still says
+            `awaiting approval`, and the place that can act on it is wherever the
+            session is actually driven. */}
+        {!readOnly && capabilities.interactiveApprovals && state.pendingApprovals.length > 0 ? (
           <div className='px-3 pb-2'>
             <div className='mx-auto flex w-full max-w-[var(--wd-content-max-w,48rem)] flex-col gap-2'>
               {state.pendingApprovals.map((request) =>
@@ -592,6 +661,7 @@ export function SessionPanel({
             </div>
           </div>
         ) : null}
+        {readOnly ? null : (
         <Composer
           ref={composerRef}
           onSend={handleSend}
@@ -636,6 +706,10 @@ export function SessionPanel({
             )
           }
         />
+        )}
+        {/* Below the composer, along the foot of the panel — the editor
+            convention. Last in the flex column, so it is the bottom edge. */}
+        {statusPlacement === 'bottom' ? statusBar : null}
 
         {/* The internal dialog surface. The external one renders none of these —
             the embedder hosts equivalent surfaces and is handed the intents. */}
@@ -686,6 +760,7 @@ export function SessionPanel({
           </>
         ) : null}
       </div>
+      </TranscriptDensityProvider>
     </TranscriptVariantProvider>
   )
 }

package/src/components/agent/SessionWorkspace.tsx

@@ -24,10 +24,35 @@ export interface SessionWorkspaceProps {
   /** Passed straight through to {@link SessionPanel} — including the render-prop
    * form that claims the session-actions menu. */
   header?: SessionPanelProps['header']
+  /**
+   * Panel seams the workspace does not interpret, forwarded verbatim.
+   *
+   * They are listed rather than spread so the workspace stays explicit about
+   * what it passes on: the panel owns the session's one attach, and a seam that
+   * silently arrived here would be a second place to look for why a session
+   * renders the way it does.
+   */
+  transcriptVariant?: SessionPanelProps['transcriptVariant']
+  transcriptDensity?: SessionPanelProps['transcriptDensity']
+  /** Which end of the panel the status bar sits at — see `SessionPanel`. */
+  statusPlacement?: SessionPanelProps['statusPlacement']
+  unseen?: SessionPanelProps['unseen']
+  /** Viewer mode — no composer, no approval prompts. Forwarded verbatim to
+   * {@link SessionPanel}; the file tree and editor are unaffected, since reading
+   * a run's files is the point of a read-only view. */
+  readOnly?: SessionPanelProps['readOnly']
+  onVitals?: SessionPanelProps['onVitals']
   /** Rail width in pixels on first render. */
   defaultRailWidth?: number
   /** Start with the file rail collapsed even on a wide viewport. */
   defaultRailCollapsed?: boolean
+  /**
+   * The rail moved. Paired with the two defaults so an embedder can persist the
+   * layout — the workspace deliberately does not, because *where* to keep it (a
+   * Memento, localStorage, a workspace file) is the embedder's call, and a
+   * component that picked one would be wrong in the other hosts.
+   */
+  onRailChange?: (rail: { width: number; collapsed: boolean }) => void
   className?: string
 }
 
@@ -64,8 +89,15 @@ export function SessionWorkspace({
   client,
   sessionId,
   header,
+  transcriptVariant,
+  transcriptDensity,
+  statusPlacement,
+  unseen,
+  readOnly,
+  onVitals,
   defaultRailWidth = 260,
   defaultRailCollapsed,
+  onRailChange,
   className,
 }: SessionWorkspaceProps) {
   // The cwd is the tree's root, and it comes from the registry rather than from
@@ -95,6 +127,13 @@ export function SessionWorkspace({
   const wide = useIsWide()
   const [railCollapsed, setRailCollapsed] = useState(defaultRailCollapsed ?? false)
   const [railWidth, setRailWidth] = useState(defaultRailWidth)
+  // Reported rather than stored. Kept in a ref so the effect below fires on a
+  // real change instead of on every render an inline callback would cause.
+  const onRailChangeRef = useRef(onRailChange)
+  onRailChangeRef.current = onRailChange
+  useEffect(() => {
+    onRailChangeRef.current?.({ width: railWidth, collapsed: railCollapsed })
+  }, [railWidth, railCollapsed])
   const [editorHeight, setEditorHeight] = useState(360)
 
   // Closing every tab returns the agent to the full column; opening one again
@@ -231,6 +270,12 @@ export function SessionWorkspace({
           client={client}
           sessionId={sessionId}
           header={hoisted}
+          transcriptVariant={transcriptVariant}
+          transcriptDensity={transcriptDensity}
+          statusPlacement={statusPlacement}
+          unseen={unseen}
+          readOnly={readOnly}
+          onVitals={onVitals}
           className='min-h-0 flex-1'
         />
       </div>

package/src/components/agent/StatusBar.tsx

@@ -28,8 +28,11 @@ export interface StatusBarProps {
   onOpenStatus?: () => void
   onOpenContext?: () => void
   onOpenUsage?: () => void
-  /** Trailing slot — the session-actions menu, in the panel's top-right. */
+  /** Trailing slot — the session-actions menu, at the bar's trailing edge. */
   actions?: ReactNode
+  /** Which edge the bar sits on, so its separating rule goes on the other side.
+   * Placement is the panel's decision; this only styles it. */
+  placement?: 'top' | 'bottom'
   className?: string
 }
 
@@ -149,6 +152,7 @@ export function StatusBar({
   onOpenContext,
   onOpenUsage,
   actions,
+  placement = 'top',
   className,
 }: StatusBarProps) {
   const meta = STATUS_META[state.status]
@@ -160,7 +164,10 @@ export function StatusBar({
     <div
       data-slot='status-bar'
       className={cn(
-        'flex items-center gap-2 border-b border-border bg-surface px-3 py-1.5',
+        'flex items-center gap-2 border-border bg-surface px-3 py-1.5',
+        // The rule goes between the bar and the content, so which edge it sits
+        // on follows the placement.
+        placement === 'bottom' ? 'border-t' : 'border-b',
         className,
       )}>
       {/* One slot, two meanings: connection trouble wins it, because a session

package/src/components/agent/ToolCallCard.tsx

@@ -8,6 +8,7 @@ import { cn } from '../../lib/utils.ts'
 import { toolInputPreview } from '../../lib/format.ts'
 import { isMutatingTool, toolIcon } from '../../lib/tool-icon.ts'
 import { LINE_INDENT, LinePayload } from './line-prompt.tsx'
+import { usePulse } from './pulse.tsx'
 import { LineGlyph, useLines } from './transcript-variant.tsx'
 
 export type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
@@ -97,6 +98,10 @@ export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps)
   const status: Status = item.status ?? (item.result === undefined ? 'running' : 'settled')
   const badge = STATE_BADGE[status]
   const isError = status === 'failed' || item.result?.isError === true
+  // Ticks only while this row is actually running, and only in the variant with a
+  // gutter to pulse in — an idle transcript of a hundred settled tools starts no
+  // timers at all.
+  const pulse = usePulse(lines && badge.busy)
   const Icon = toolIcon(item.name)
 
   const resultText = item.result?.text ?? ''
@@ -162,7 +167,10 @@ export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps)
                 ? 'text-success'
                 : STATE_GLYPH[status]
             }>
-            {badge.busy ? '◐' : '●'}
+            {/* Running: the mark's own pulse, so a working tool row and the
+                transcript's working line beat together. Settled: a plain dot,
+                which reads as "done" precisely by not moving. */}
+            {badge.busy ? pulse : '●'}
           </LineGlyph>
           <span className='min-w-0 flex-1 truncate text-body-sm leading-5 text-fg-3'>
             <span className='font-medium text-fg-1'>{item.name}</span>
@@ -171,7 +179,8 @@ export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps)
           {item.backend && item.backend !== 'server' ? (
             <span className='shrink-0 text-label text-fg-4'>{item.backend}</span>
           ) : null}
-          {badge.busy ? <Spinner className='size-3 shrink-0 self-center text-fg-4' /> : null}
+          {/* No Spinner here: the gutter glyph animates now, and two spinners on
+              one row is one too many. `cards` keeps its own — it has no gutter. */}
           {status === 'deferred' ? <Clock className='size-3 shrink-0 self-center text-fg-4' /> : null}
           {isError && !badge.busy ? (
             <span className='shrink-0 text-label text-danger'>error</span>

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'
 
@@ -169,7 +171,7 @@ function RecapRow({ line, since }: { line: string; since?: number }) {
   if (lines) {
     return (
       <div data-slot='recap' className='flex items-baseline gap-2 py-0.5'>
-        <LineGlyph className='text-accent'>※</LineGlyph>
+        <LineGlyph className='text-fg-3'>※</LineGlyph>
         <span className='min-w-0 flex-1 text-label leading-5 text-fg-3'>
           <span className='text-fg-2'>recap:</span> {text}
         </span>
@@ -258,9 +260,8 @@ function SentAttachments({
   attachments: MessageAttachment[]
   attachmentUrl?: (attachmentId: string) => string
 }) {
-  const lines = useLines()
   return (
-    <div className={cn('mb-1 flex flex-wrap gap-1.5', lines ? 'justify-start' : 'justify-end')}>
+    <div className='mb-1 flex flex-wrap justify-start gap-1.5'>
       {attachments.map((attachment) => {
         const href = attachmentUrl?.(attachment.id)
         return attachment.mediaType.startsWith('image/') && href ? (
@@ -339,6 +340,7 @@ function TranscriptRows({
   boundary,
   since,
   lines,
+  gap,
   fileUrl,
   attachmentUrl,
   hostImage,
@@ -348,6 +350,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 +391,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 +491,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 +549,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 +580,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 +621,7 @@ export function Transcript({
               boundary={boundary}
               since={catchUp?.since}
               lines={lines}
+              gap={gap}
               fileUrl={fileUrl}
               attachmentUrl={attachmentUrl}
               hostImage={hostImage}

package/src/components/agent/line-prompt.tsx

@@ -128,7 +128,7 @@ export function LineOptionList({
                 'flex w-full items-baseline gap-2 text-left outline-none',
                 isFocused ? 'bg-surface-hover' : 'hover:bg-surface-hover/60',
               )}>
-              <LineGlyph className={isFocused ? 'text-accent' : undefined}>
+              <LineGlyph className={isFocused ? 'text-fg-1' : undefined}>
                 {isFocused ? '❯' : ' '}
               </LineGlyph>
               <span className='shrink-0 font-mono text-label leading-5 text-fg-4'>{index + 1}</span>
@@ -184,7 +184,7 @@ export function LineInput({
 }) {
   return (
     <div className='flex items-baseline gap-2'>
-      <LineGlyph className='text-accent'>›</LineGlyph>
+      <LineGlyph className='text-fg-3'>›</LineGlyph>
       <input
         autoFocus
         value={value}

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/components/ui/Menu.tsx

@@ -14,7 +14,7 @@ export const MenuContent: FunctionComponent<
       align={align}
       side={side}
       sideOffset={sideOffset}
-      className='isolate z-60 outline-none'>
+      className='isolate z-80 outline-none'>
       <MenuPrimitive.Popup
         data-slot='menu-content'
         className={cn(

package/src/components/ui/Select.tsx

@@ -45,7 +45,7 @@ export const SelectContent: FunctionComponent<
       alignItemWithTrigger={alignItemWithTrigger}
       side={side}
       sideOffset={sideOffset}
-      className='isolate z-60 outline-none'>
+      className='isolate z-80 outline-none'>
       <SelectPrimitive.Popup
         data-slot='select-content'
         className={cn(

package/src/components/ui/Tooltip.tsx

@@ -8,7 +8,7 @@ export const TooltipContent: FunctionComponent<
   TooltipPrimitive.Popup.Props & Pick<TooltipPrimitive.Positioner.Props, 'side' | 'sideOffset'>
 > = ({ className, side = 'top', sideOffset = 6, ...props }) => (
   <TooltipPrimitive.Portal>
-    <TooltipPrimitive.Positioner side={side} sideOffset={sideOffset} className='isolate z-60'>
+    <TooltipPrimitive.Positioner side={side} sideOffset={sideOffset} className='isolate z-90'>
       <TooltipPrimitive.Popup
         data-slot='tooltip-content'
         className={cn(