@workerdeck/ui 0.9.0 → 0.10.0

package/src/components/agent/ToolCallCard.tsx

@@ -1,18 +1,39 @@
-import { useState } from 'react'
+import { useEffect, useState } from 'react'
 import type { TranscriptItem } from '@workerdeck/react'
-import { ChevronDown, Clock, Wrench } from 'lucide-react'
+import { ChevronDown, Clock } from 'lucide-react'
 import { Badge } from '../ui/Badge.tsx'
 import { CodeBlock } from '../ui/CodeBlock.tsx'
 import { Spinner } from '../ui/Spinner.tsx'
 import { cn } from '../../lib/utils.ts'
 import { toolInputPreview } from '../../lib/format.ts'
+import { toolIcon } from '../../lib/tool-icon.ts'
 
 export type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
 
 const RESULT_PREVIEW_CHARS = 2000
 
+/** Codex's built-in image tools name a host path rather than sending bytes —
+ * an event log carries references, never base64. Rendering the picture means
+ * reading that path back through the gateway's host-file route. */
+const IMAGE_TOOLS = new Set(['CodexImageGeneration', 'CodexImageView'])
+
+const imagePathOf = (item: ToolCallItem): string | undefined => {
+  if (!IMAGE_TOOLS.has(item.name)) return undefined
+  const input = item.input as { savedPath?: unknown; path?: unknown } | null
+  const path = input?.savedPath ?? input?.path
+  return typeof path === 'string' ? path : undefined
+}
+
 export interface ToolCallCardProps {
   item: ToolCallItem
+  /**
+   * Reads a host file as a data URL, for tools whose output is a picture on the
+   * host. Resolves `undefined` when the gateway won't serve that path — a
+   * generated image saved outside the allowed roots (codex's default
+   * `$CODEX_HOME/generated_images/`) is one, and the card then names the path
+   * instead of showing it.
+   */
+  hostImage?: (path: string) => Promise<string | undefined>
   className?: string
 }
 
@@ -27,12 +48,14 @@ const STATE_BADGE = {
   failed: { label: 'Error', variant: 'danger', busy: false },
 } as const
 
-export function ToolCallCard({ item, className }: ToolCallCardProps) {
+export function ToolCallCard({ item, hostImage, className }: ToolCallCardProps) {
   const [open, setOpen] = useState(false)
   const [fullResult, setFullResult] = useState(false)
+  const imagePath = imagePathOf(item)
   const status = item.status ?? (item.result === undefined ? 'running' : 'settled')
   const badge = STATE_BADGE[status]
   const isError = status === 'failed' || item.result?.isError === true
+  const Icon = toolIcon(item.name)
 
   const resultText = item.result?.text ?? ''
   const truncated = !fullResult && resultText.length > RESULT_PREVIEW_CHARS
@@ -50,8 +73,13 @@ export function ToolCallCard({ item, className }: ToolCallCardProps) {
           'flex w-full items-center gap-2 px-3 py-2 text-left transition-colors outline-none',
           'hover:bg-surface-hover focus-visible:bg-surface-hover',
         )}>
-        <Wrench className='size-3.5 shrink-0 text-fg-3' />
+        <Icon className='size-3.5 shrink-0 text-fg-3' />
         <span className='shrink-0 font-mono text-body-sm font-medium text-fg-1'>{item.name}</span>
+        {item.backend && item.backend !== 'server' ? (
+          <Badge variant='neutral' className='shrink-0'>
+            {item.backend}
+          </Badge>
+        ) : null}
         <span className='min-w-0 flex-1 truncate font-mono text-label text-fg-4'>
           {toolInputPreview(item.input)}
         </span>
@@ -64,6 +92,11 @@ export function ToolCallCard({ item, className }: ToolCallCardProps) {
           className={cn('size-3.5 shrink-0 text-fg-4 transition-transform', open && 'rotate-180')}
         />
       </button>
+      {/* The picture is the point of the call — shown without expanding, the
+          way the tool's own output would be if the engine had sent bytes. */}
+      {imagePath && hostImage ? (
+        <HostImage path={imagePath} load={hostImage} />
+      ) : null}
       {open ? (
         <div className='flex flex-col gap-2 border-t border-border p-2.5'>
           <CodeBlock code={JSON.stringify(item.input, null, 2)} label='Parameters' />
@@ -92,3 +125,46 @@ export function ToolCallCard({ item, className }: ToolCallCardProps) {
     </div>
   )
 }
+
+/**
+ * A picture that lives on the host, fetched through the gateway's host-file
+ * route and shown inline.
+ *
+ * Silent on failure by design: a path outside the server's allowed roots is the
+ * *expected* case for codex's default save location, and the card's result text
+ * already names where the file went. An error banner over that would be noise
+ * about a thing the operator can fix in one line of config.
+ */
+function HostImage({
+  path,
+  load,
+}: {
+  path: string
+  load: (path: string) => Promise<string | undefined>
+}) {
+  const [src, setSrc] = useState<string | undefined>()
+  useEffect(() => {
+    let cancelled = false
+    setSrc(undefined)
+    load(path)
+      .then((url) => {
+        if (!cancelled) setSrc(url)
+      })
+      .catch(() => {
+        // Not readable from here — the path in the result is the answer.
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [path, load])
+  if (!src) return null
+  return (
+    <div className='border-t border-border p-2.5'>
+      <img
+        src={src}
+        alt={path.split('/').pop() ?? 'Generated image'}
+        className='max-h-96 w-auto max-w-full rounded-md border border-border'
+      />
+    </div>
+  )
+}

package/src/components/agent/Transcript.tsx

@@ -6,19 +6,34 @@ import { Conversation, ConversationContent, ConversationScrollButton } from './C
 import { FileCard } from './FileCard.tsx'
 import { Loader } from './Loader.tsx'
 import { Message, MessageContent } from './Message.tsx'
+import { PromptTokenText } from './PromptTokenText.tsx'
 import { Reasoning } from './Reasoning.tsx'
 import { Response } from './Response.tsx'
+import { SessionEmptyState } from './SessionEmptyState.tsx'
 import { ToolCallCard } from './ToolCallCard.tsx'
 
 function TurnResultRow({ item }: { item: Extract<TranscriptItem, { kind: 'turn_result' }> }) {
   return (
-    <div data-slot='turn-result' className='flex items-center gap-2 py-1'>
-      <div className='h-px flex-1 bg-border' />
-      <span className={cn('font-mono text-label', item.isError ? 'text-danger' : 'text-fg-4')}>
-        {item.isError ? item.subtype : 'turn done'} · {formatDuration(item.durationMs)} ·{' '}
-        {formatCost(item.totalCostUsd)}
-      </span>
-      <div className='h-px flex-1 bg-border' />
+    <div data-slot='turn-result' className='py-1'>
+      <div className='flex items-center gap-2'>
+        <div className='h-px flex-1 bg-border' />
+        <span className={cn('font-mono text-label', item.isError ? 'text-danger' : 'text-fg-4')}>
+          {item.isError ? item.subtype : 'turn done'} · {formatDuration(item.durationMs)} ·{' '}
+          {formatCost(item.totalCostUsd)}
+        </span>
+        <div className='h-px flex-1 bg-border' />
+      </div>
+      {/* A failed turn's reasons are the whole point of the row — dropping them
+          leaves "error_during_execution" and nothing to act on. */}
+      {item.errors?.length ? (
+        <ul className='mt-1 flex flex-col gap-0.5 text-center'>
+          {item.errors.map((message, index) => (
+            <li key={index} className='text-label break-words text-danger'>
+              {message}
+            </li>
+          ))}
+        </ul>
+      ) : null}
     </div>
   )
 }
@@ -42,10 +57,12 @@ function TranscriptItemView({
   item,
   fileUrl,
   attachmentUrl,
+  hostImage,
 }: {
   item: TranscriptItem
   fileUrl?: (path: string) => string
   attachmentUrl?: (attachmentId: string) => string
+  hostImage?: (path: string) => Promise<string | undefined>
 }) {
   switch (item.kind) {
     case 'user':
@@ -55,7 +72,11 @@ function TranscriptItemView({
             <SentAttachments attachments={item.attachments} attachmentUrl={attachmentUrl} />
           ) : null}
           {/* A photo can be the whole message — an empty bubble under it says nothing. */}
-          {item.text ? <MessageContent>{item.text}</MessageContent> : null}
+          {item.text ? (
+            <MessageContent>
+              <PromptTokenText text={item.text} />
+            </MessageContent>
+          ) : null}
         </Message>
       )
     case 'assistant_text':
@@ -69,7 +90,7 @@ function TranscriptItemView({
     case 'thinking':
       return <Reasoning isStreaming={item.id === 'streaming-thinking'}>{item.text}</Reasoning>
     case 'tool_call':
-      return <ToolCallCard item={item} />
+      return <ToolCallCard item={item} hostImage={hostImage} />
     case 'turn_result':
       return <TurnResultRow item={item} />
     case 'notice':
@@ -124,6 +145,14 @@ function SentAttachments({
   )
 }
 
+/** Rows produced inside a subagent (`parentToolUseId != null`) are stepped in
+ * behind a rule, so a Task's own output reads as belonging to the tool call
+ * above it rather than as the main thread carrying on. */
+function nestedClass(item: TranscriptItem): string | undefined {
+  const nested = 'parentToolUseId' in item && item.parentToolUseId != null
+  return nested ? 'border-l-2 border-border pl-3' : undefined
+}
+
 export interface TranscriptProps {
   state: TranscriptState
   /** Builds the download URL for a delivered file (see FileCard). Typically
@@ -133,23 +162,43 @@ export interface TranscriptProps {
    * `(id) => client.attachmentUrl(sessionId, id)`. Same-origin and
    * cookie-authenticated, which is what lets an `<img src>` render one. */
   attachmentUrl?: (attachmentId: string) => string
+  /** Whether this gateway serves `@file` search here — the empty state must not
+   * advertise an affordance the composer doesn't have. */
+  canBrowseFiles?: boolean
+  /** Reads a host file as a data URL, for tool calls whose output is a picture
+   * on the host (codex's `image_gen`). Omit and those cards name the path. */
+  hostImage?: (path: string) => Promise<string | undefined>
   className?: string
 }
 
-export function Transcript({ state, fileUrl, attachmentUrl, className }: TranscriptProps) {
+export function Transcript({
+  state,
+  fileUrl,
+  attachmentUrl,
+  canBrowseFiles,
+  hostImage,
+  className,
+}: TranscriptProps) {
   return (
     <Conversation className={className}>
       <ConversationContent>
         {state.items.length === 0 && state.status !== 'starting' ? (
-          <div className='py-12 text-center text-body-sm text-fg-4'>No messages yet.</div>
+          <SessionEmptyState
+            cwd={state.cwd}
+            hasCommands={!!state.commands?.length}
+            hasSkills={!!state.skills?.some((s) => s.enabled)}
+            canBrowseFiles={canBrowseFiles}
+          />
         ) : (
           state.items.map((item) => (
-            <TranscriptItemView
-              key={`${item.kind}:${item.id}`}
-              item={item}
-              fileUrl={fileUrl}
-              attachmentUrl={attachmentUrl}
-            />
+            <div key={`${item.kind}:${item.id}`} className={nestedClass(item)}>
+              <TranscriptItemView
+                item={item}
+                fileUrl={fileUrl}
+                attachmentUrl={attachmentUrl}
+                hostImage={hostImage}
+              />
+            </div>
           ))
         )}
         {showLoader(state) ? (

package/src/components/agent/UsageDialog.tsx

@@ -0,0 +1,168 @@
+import { useEffect, useState } from 'react'
+import type { ProfileEngine, RateLimitInfo } from '@workerdeck/protocol'
+import { RotateCcw } from 'lucide-react'
+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'
+
+export interface UsageDialogProps {
+  /** Windows in reading order — session, weekly, then per-model weeklies. */
+  rateLimits: Array<{ key: string; info: RateLimitInfo }>
+  /** 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. */
+  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.
+ */
+export function UsageDialog({
+  rateLimits,
+  subscriptionType,
+  engine,
+  totalCostUsd,
+  updatedAt,
+  open,
+  onOpenChange,
+}: UsageDialogProps) {
+  const now = useMinuteClock(open)
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader
+          title='Usage'
+          description={engine === 'claude' ? 'Claude Code' : engine}
+          actions={
+            // The CLI reports a tier ('max'), never the multiplier a
+            // subscription page shows — so this says "Max" and stops there.
+            subscriptionType ? (
+              <Badge variant='accent' className='mt-0.5 shrink-0 capitalize'>
+                {subscriptionType}
+              </Badge>
+            ) : null
+          }
+        />
+        <DialogBody>
+          {rateLimits.length === 0 ? (
+            <p className='py-6 text-center text-body-sm text-fg-4'>
+              {engine === 'claude'
+                ? 'This session reports no plan windows — API-key sessions have none, and a subscription session reports them once a turn has run.'
+                : `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>
+          )}
+          <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>
+            <span className='font-mono text-body-sm text-fg-1'>{formatCost(totalCostUsd)}</span>
+          </div>
+          {updatedAt ? (
+            <p className='mt-2 text-label text-fg-4'>Updated {formatAgoPrecise(updatedAt, now)}</p>
+          ) : null}
+        </DialogBody>
+      </DialogContent>
+    </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/prompt-area/prompt-area-engine.ts

@@ -288,6 +288,59 @@ export function resolveChip(
   return { segments: merged, cursorOffset }
 }
 
+/**
+ * Replaces the active trigger's range with **plain text** instead of a chip.
+ *
+ * The sibling of {@link resolveChip}, for suggestions that are a typing aid
+ * rather than a token: what lands in the document is ordinary editable text the
+ * user is expected to finish and change, and it must not look or behave like a
+ * resolved chip — no immutability, no trigger character, nothing for a consumer
+ * to parse back out. The caret is left at the end of the inserted text so typing
+ * continues from there.
+ */
+export function resolveText(
+  segments: Segment[],
+  activeTrigger: ActiveTrigger,
+  text: string,
+): { segments: Segment[]; cursorOffset: number } {
+  const triggerStart = activeTrigger.startOffset
+  const triggerEnd = triggerStart + 1 + activeTrigger.query.length // +1 for trigger char
+
+  const newSegments: Segment[] = []
+  let offset = 0
+  let cursorOffset = triggerStart + text.length
+
+  for (const seg of segments) {
+    if (seg.type === 'chip') {
+      const chipEnd = offset + `${seg.trigger}${seg.displayText}`.length
+      // A trigger range can never overlap a chip — chips are atomic — so a chip
+      // is either wholly before or wholly after, and is kept either way.
+      if (chipEnd <= triggerStart || offset >= triggerEnd) newSegments.push(seg)
+      offset = chipEnd
+      continue
+    }
+    const textStart = offset
+    const textEnd = offset + seg.text.length
+    if (textEnd <= triggerStart || textStart >= triggerEnd) {
+      newSegments.push(seg)
+    } else {
+      const before = seg.text.slice(0, Math.max(0, triggerStart - textStart))
+      const after = seg.text.slice(Math.min(seg.text.length, triggerEnd - textStart))
+      if (before) newSegments.push({ type: 'text', text: before })
+      newSegments.push({ type: 'text', text })
+      if (after) newSegments.push({ type: 'text', text: after })
+    }
+    offset = textEnd
+  }
+
+  const merged = mergeAdjacentTextSegments(newSegments)
+  // Clamp: a trigger detected against a stale document could otherwise leave the
+  // caret past the end, which renders as no caret at all.
+  const total = segmentsToPlainText(merged).length
+  if (cursorOffset > total) cursorOffset = total
+  return { segments: merged, cursorOffset }
+}
+
 // ---------------------------------------------------------------------------
 // Chip removal
 // ---------------------------------------------------------------------------

package/src/components/prompt-area/types.ts

@@ -103,6 +103,21 @@ export type TriggerConfig = {
    * Return the display text for the chip, or void to use `suggestion.label`.
    */
   onSelect?: (suggestion: TriggerSuggestion) => string | void
+  /**
+   * For 'dropdown' mode: opt a suggestion out of becoming a chip.
+   *
+   * Return a string and the trigger's range is replaced with that **plain,
+   * editable text** — the trigger character included — with the caret left at
+   * its end. Return undefined and the suggestion resolves to a chip as usual,
+   * so one dropdown can mix both kinds.
+   *
+   * For suggestions that are a typing aid rather than a token: something the
+   * user is meant to finish and edit, where a chip would falsely promise the
+   * host parses it back out. Takes precedence over `onSelect`, which is not
+   * called for a text-resolved suggestion (there is no chip to label), and
+   * `onChipAdd` does not fire either.
+   */
+  insertAsText?: (suggestion: TriggerSuggestion) => string | undefined
   /**
    * For 'callback' and 'launch' modes: called when the trigger is activated.
    * Receives the full input text and cursor position. For 'launch' it fires on

package/src/components/prompt-area/use-prompt-area.ts

@@ -17,6 +17,7 @@ import {
   plainTextToSegments,
   segmentsEqual,
   resolveChip,
+  resolveText,
   removeChipAtIndex,
   revertChipAtIndex,
   replaceTextRange,
@@ -929,6 +930,25 @@ export function usePromptArea({
       if (!activeTrigger) return
 
       const segments = readSegmentsFromDOM()
+
+      // Text-resolved suggestions leave before any chip machinery runs: there
+      // is no chip, so there is nothing for the chip-click editing path or the
+      // onChipAdd callback below to be about.
+      const asText = activeTrigger.config.insertAsText?.(suggestion)
+      if (asText !== undefined) {
+        const inserted = resolveText(segments, activeTrigger, asText)
+        events.pushUndo(segments)
+        onChange(inserted.segments)
+        renderSegmentsToDOM(inserted.segments)
+        const editor = editorRef.current
+        if (editor) setCursorAtOffset(editor, inserted.cursorOffset)
+        dismissTrigger()
+        setTimeout(() => {
+          editorRef.current?.focus()
+        }, 0)
+        return
+      }
+
       const displayText = activeTrigger.config.onSelect?.(suggestion) ?? suggestion.label
 
       const chipData = {

package/src/components/ui/CopyButton.tsx

@@ -1,6 +1,7 @@
 import { useState } from 'react'
 import { Check, Copy } from 'lucide-react'
 import { Button, type ButtonProps } from './Button.tsx'
+import { copyText } from '../../lib/clipboard.ts'
 import { cn } from '../../lib/utils.ts'
 
 export interface CopyButtonProps extends Omit<ButtonProps, 'onClick' | 'children'> {
@@ -16,7 +17,13 @@ export function CopyButton({ value, className, variant = 'ghost', size = 'icon-s
       aria-label='Copy'
       className={cn('text-fg-3', className)}
       onClick={() => {
-        void navigator.clipboard.writeText(value).then(() => {
+        // Through `copyText`, which falls back for insecure origins — the
+        // dashboard on a LAN address has no `navigator.clipboard` at all, and
+        // reaching straight for `.writeText` there throws.
+        void copyText(value).then((ok) => {
+          // Only tick when it really copied: a check mark over an empty
+          // clipboard is worse than no feedback.
+          if (!ok) return
           setCopied(true)
           setTimeout(() => setCopied(false), 1500)
         })

package/src/components/ui/Dialog.tsx

@@ -0,0 +1,92 @@
+import { type FunctionComponent } from 'react'
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog'
+import { X } from 'lucide-react'
+import { cn } from '../../lib/utils.ts'
+
+export const Dialog = DialogPrimitive.Root
+export const DialogTrigger = DialogPrimitive.Trigger
+export const DialogClose = DialogPrimitive.Close
+
+/**
+ * A dismissible panel, sized for reading rather than confirming — the web
+ * counterpart of the iOS app's detail sheets (context, usage, session info, MCP).
+ *
+ * Taller than {@link AlertDialogContent} and scrollable inside, because these
+ * carry lists whose length is the engine's business, not the layout's.
+ */
+export const DialogContent: FunctionComponent<
+  DialogPrimitive.Popup.Props & { size?: 'sm' | 'md' | 'lg' }
+> = ({ className, children, size = 'md', ...props }) => (
+  <DialogPrimitive.Portal>
+    <DialogPrimitive.Backdrop
+      className={cn(
+        'fixed inset-0 z-70 bg-black/40 backdrop-blur-[1px]',
+        'transition-opacity duration-(--motion-base)',
+        'data-starting-style:opacity-0 data-ending-style:opacity-0',
+      )}
+    />
+    <DialogPrimitive.Popup
+      data-slot='dialog-content'
+      className={cn(
+        'fixed top-1/2 left-1/2 z-70 flex max-h-[min(42rem,calc(100dvh-3rem))] -translate-x-1/2 -translate-y-1/2 flex-col',
+        size === 'sm' && 'w-[min(24rem,calc(100vw-2rem))]',
+        size === 'md' && 'w-[min(32rem,calc(100vw-2rem))]',
+        size === 'lg' && 'w-[min(46rem,calc(100vw-2rem))]',
+        'rounded-lg border border-border bg-surface shadow-(--shadow-lg) outline-none',
+        'transition-[opacity,transform] duration-(--motion-base)',
+        'data-starting-style:scale-95 data-starting-style:opacity-0',
+        'data-ending-style:scale-95 data-ending-style:opacity-0',
+        className,
+      )}
+      {...props}>
+      {children}
+    </DialogPrimitive.Popup>
+  </DialogPrimitive.Portal>
+)
+
+/** Title row with the close button, pinned above the scrolling body. */
+export const DialogHeader: FunctionComponent<{
+  title: string
+  description?: string
+  /** Rendered between the title and the close button. */
+  actions?: React.ReactNode
+}> = ({ title, description, actions }) => (
+  <div className='flex items-start gap-2 border-b border-border px-4 py-3'>
+    <div className='min-w-0 flex-1'>
+      <DialogPrimitive.Title className='truncate text-body-sm font-semibold text-text'>
+        {title}
+      </DialogPrimitive.Title>
+      {description ? (
+        <DialogPrimitive.Description className='mt-0.5 text-label text-fg-4'>
+          {description}
+        </DialogPrimitive.Description>
+      ) : null}
+    </div>
+    {actions}
+    <DialogPrimitive.Close
+      aria-label='Close'
+      className='-mr-1 flex size-6 shrink-0 items-center justify-center rounded-md text-fg-3 transition-colors outline-none hover:bg-surface-hover hover:text-fg-1'>
+      <X className='size-3.5' />
+    </DialogPrimitive.Close>
+  </div>
+)
+
+/** The scrolling region under the header. */
+export const DialogBody: FunctionComponent<React.HTMLAttributes<HTMLDivElement>> = ({
+  className,
+  ...props
+}) => <div className={cn('min-h-0 flex-1 overflow-y-auto p-4', className)} {...props} />
+
+/** A label/value row — the shape every one of these panels is mostly made of. */
+export const DialogRow: FunctionComponent<{
+  label: string
+  children: React.ReactNode
+  mono?: boolean
+}> = ({ label, children, mono }) => (
+  <div className='flex items-baseline justify-between gap-4 py-1.5'>
+    <span className='shrink-0 text-label text-fg-3'>{label}</span>
+    <span className={cn('min-w-0 truncate text-right text-body-sm text-fg-1', mono && 'font-mono text-label')}>
+      {children}
+    </span>
+  </div>
+)