@workerdeck/ui 0.23.0 → 1.0.0

package/src/components/terminal/TerminalTranscript.tsx

@@ -3,21 +3,8 @@ import type { TranscriptItem, TranscriptState } from '@workerdeck/react'
 import { cn } from '../../lib/utils.ts'
 import type { TerminalAffordances } from './affordances.tsx'
 import { OpenSubagentAction, WithActions } from './affordances.tsx'
-import {
-  AssistantRow,
-  FileRow,
-  NoticeRow,
-  ToolRunRow,
-  ThinkingRow,
-  ToolRow,
-  TurnResultRow,
-  UserRow,
-  WorkingRow,
-  blockNeedsBlank,
-  taskChildItems,
-  terminalBlocks,
-  type TaskBlock,
-} from './items.tsx'
+import { AssistantRow, FileRow, NoticeRow, ToolRunRow, ThinkingRow, ToolRow, TurnResultRow, UserRow, WorkingRow } from './items.tsx'
+import { blockNeedsBlank, taskChildItems, terminalBlocks, type TaskBlock } from './blocks.ts'
 import { usePulse } from '../agent/pulse.tsx'
 import { Pressable, useRevealOnOpen } from './press.tsx'
 import { taskBrief, taskBusy, taskFailed, taskSummary } from './tool-run.ts'
@@ -25,122 +12,61 @@ import { BRIEF_LINES } from './height.ts'
 import { Blank, Row } from './row.tsx'
 import { TerminalSurface } from './surface.tsx'
 
-/**
- * The transcript, drawn as a terminal.
- *
- * The whole of the layout is here and it is four lines long, which is the point:
- * items become row blocks, a blank line goes between blocks that do not belong
- * together, and the working line is one more row at the end. There is no gap
- * scale, no density knob and no variant branch — a terminal has one line height
- * and one type size, and everything the theme can express is expressed in which
- * rows exist and what marker each carries.
- *
- * Not virtualized yet: the row blocks are the part that has to be right first,
- * and the existing `Transcript` already owns a hard-won virtualizer plus the
- * scroll-regime rules it needs. This renders into that shell when the rows are
- * settled, rather than growing a second copy of that logic.
- */
 export interface TerminalTranscriptProps {
   state: TranscriptState
-  /** Builds the download URL for a delivered file. */
   fileUrl?: (path: string) => string
-  /** Cell metrics, in whole pixels. See {@link TerminalSurface}. */
   fontSize?: number
   lineHeight?: number
-  /** The pointer affordances a real terminal has no way to offer — hover fill,
-   * hover-revealed copy. `false` for none. See {@link TerminalAffordances}. */
   affordances?: TerminalAffordances | boolean
   className?: string
 }
 
-/**
- * One transcript item as terminal rows. Exported because the virtualized shell
- * in `agent/Transcript.tsx` renders rows through it: the theme owns how a row
- * looks, that component owns which rows are mounted, and neither needs a copy
- * of the other.
- */
-export function TerminalItemView({
-  item,
-  fileUrl,
-}: {
-  item: TranscriptItem
-  fileUrl?: (path: string) => string
-}) {
+export function TerminalItemView({ item, fileUrl }: { item: TranscriptItem; fileUrl?: (path: string) => string }) {
   switch (item.kind) {
-    case 'user':
+    case 'user': {
       return <UserRow item={item} />
-    case 'assistant_text':
+    }
+    case 'assistant_text': {
       return <AssistantRow item={item} />
-    case 'thinking':
+    }
+    case 'thinking': {
       return <ThinkingRow item={item} />
-    case 'tool_call':
+    }
+    case 'tool_call': {
       return <ToolRow item={item} />
-    case 'turn_result':
+    }
+    case 'turn_result': {
       return <TurnResultRow item={item} />
-    case 'notice':
+    }
+    case 'notice': {
       return <NoticeRow item={item} />
-    case 'file_delivered':
+    }
+    case 'file_delivered': {
       return <FileRow item={item} href={fileUrl?.(item.path)} />
-    default:
+    }
+    default: {
       return null
+    }
   }
 }
 
-/**
- * A `Task` and everything the subagent it spawned produced, as one row.
- *
- * The same claim the tool-run fold makes, and a stronger one: a subagent is
- * *sixty* rows of somebody else's working — a brief, a dozen greps, its own
- * thinking — and none of it is what you came back to read. What you came back
- * to read is the report, and the report is the model's next sentence. So the
- * whole frame collapses to one line saying what was asked and how big the
- * answer was, and opens in full the moment it is the thing you want.
- *
- * **Always collapsed when unmounted**, and that is load-bearing rather than
- * tidy: `height.ts` predicts this row as exactly one wrapped `taskSummary`, and
- * expansion is component-local state that dies with the row. A row auto-opening
- * because its subagent happens to be running would make its own height
- * unpredictable — which is why the live signal is *in* the collapsed line (the
- * pulse, and a count that climbs) rather than in an open block.
- *
- * The children are the theme's ordinary rows, stepped in behind a rule, and
- * they fold among themselves: a subagent's consecutive tool calls are as much
- * an aside inside its frame as they are in the main thread.
- */
-/**
- * **What the agent was asked** — the sub-agent's brief, clipped to
- * {@link BRIEF_LINES} and pressable for the whole of it.
- *
- * It leads the takeover's frame and the inline task expansion alike, because
- * both are answering the same question and an answer without its question is
- * half a transcript. This is the one row here built from something other than
- * the stream, and it exists for the case the stream does not cover: a
- * **background** agent forwards no brief, where a foreground `Task` forwards a
- * real nested user item that renders as an ordinary prompt row. The callers
- * splice this in only when that row is absent. Codex draws nothing either way —
- * its spawn message is encrypted on the wire, so there is no brief to give.
- *
- * `>` and blue, the prompt's own marker and colour, because that is what this
- * is: somebody's instruction, one level in. The clip is `line-clamp`, which
- * cuts on the same wrapped lines `briefPx` counts — one rule, so the reserved
- * height and the drawn height cannot disagree.
- */
 export function BriefRow({ text, terminal }: { text: string; terminal?: boolean }) {
   const [open, setOpen] = useState(false)
   if (!terminal) {
     return (
-      <div data-slot='brief' className='px-4 py-2 text-body-sm whitespace-pre-wrap text-fg-2'>
+      <div data-slot="brief" className="px-4 py-2 text-body-sm whitespace-pre-wrap text-fg-2">
         {text}
       </div>
     )
   }
   return (
-    <div data-slot='brief'>
+    <div data-slot="brief">
       <Pressable onPress={() => setOpen((v) => !v)} expanded={open}>
-        <Row glyph='>' glyphTone='blue' tone='dim'>
+        <Row glyph=">" glyphTone="blue" tone="dim">
           <span
             className={cn('whitespace-pre-wrap', !open && 'term-brief-clip')}
-            style={open ? undefined : { WebkitLineClamp: BRIEF_LINES }}>
+            style={open ? undefined : { WebkitLineClamp: BRIEF_LINES }}
+          >
             {text}
           </span>
         </Row>
@@ -156,17 +82,11 @@ export function TaskRow({
 }: {
   block: TaskBlock
   fileUrl?: (path: string) => string
-  /** Take over the panel with this sub-agent's own frame. Absent draws no
-   * affordance at all — the plain renderer has no surface to take over, and an
-   * action that opens nothing is worse than no action. */
   onOpenSubagent?: (toolUseId: string) => void
 }) {
   const [open, setOpen] = useState(false)
   const reveal = useRevealOnOpen(open)
   const children = useMemo(() => taskChildItems(block), [block])
-  // Only when the sub-agent's own stream carries no brief — a foreground Task
-  // forwards one as a real user item, and two spellings of one instruction is
-  // worse than none. See `taskBrief`.
   const brief = children.some((item) => item.kind === 'user') ? undefined : taskBrief(block.task)
   const busy = taskBusy(block.task, children)
   const failed = taskFailed(block.task)
@@ -175,64 +95,30 @@ export function TaskRow({
   const row = (
     <div ref={reveal} className={open ? 'term-open' : undefined}>
       <Pressable onPress={() => setOpen((v) => !v)} expanded={open}>
-        {/* A marker, where a folded run of calls gets none: a run is an aside,
-            but delegating a piece of the work is something the model *did*, and
-            the row stands for the whole of it. The body is `taskSummary`
-            verbatim — it is the string `height.ts` wraps to size this row, and
-            a second spelling here would be a second height. */}
-        {/* Green means sub-agent, and it means it here for the same reason it
-            means it on the rail: every other colour is spoken for — blue is
-            you, white is the answer, red is an alarm, magenta is your bookmark,
-            yellow is the session waiting on you (see `terminal.css`). The
-            *body* is green and the marker is not: a green glyph already means
-            "wrote to the workspace" a few rows down, and one colour cannot mean
-            two things in the same gutter. Failure still outranks it — an alarm
-            is not a category. */}
-        <Row
-          glyph={busy ? pulse : '●'}
-          glyphTone={failed ? 'red' : busy ? 'mark' : 'dim'}
-          tone={failed ? 'red' : 'green'}>
+        <Row glyph={busy ? pulse : '●'} glyphTone={failed ? 'red' : busy ? 'mark' : 'dim'} tone={failed ? 'red' : 'green'}>
           {taskSummary(block.task, children)}
         </Row>
       </Pressable>
       {open ? (
-        // `term-nested` and not the shell's cards-era `border-l-2 pl-3`: this
-        // sits on the open block's wash, where that border token is invisible,
-        // and its 14px would take every nested marker off the cell grid.
-        <div className='term-nested'>
-          {/* The brief leads the children for the same reason it leads the
-              frame: the instruction, then the work. */}
+        <div className="term-nested">
           {brief ? <BriefRow text={brief} terminal /> : null}
           {block.children.map((leaf, index) => (
             <Fragment key={leaf.key}>
               {index > 0 && blockNeedsBlank(block.children[index - 1]!, leaf) ? <Blank /> : null}
-              {'run' in leaf ? (
-                <ToolRunRow items={leaf.run} />
-              ) : (
-                <TerminalItemView item={leaf.item} fileUrl={fileUrl} />
-              )}
+              {'run' in leaf ? <ToolRunRow items={leaf.run} /> : <TerminalItemView item={leaf.item} fileUrl={fileUrl} />}
             </Fragment>
           ))}
         </div>
       ) : null}
     </div>
   )
-  // Wrapped only when there is somewhere to go. `WithActions` is a no-op when
-  // affordances are off, but wrapping unconditionally would still put an
-  // "open" glyph on a renderer that cannot honour it.
   return onOpenSubagent === undefined ? (
     row
   ) : (
-    <WithActions actions={<OpenSubagentAction onOpen={() => onOpenSubagent(block.task.id)} />}>
-      {row}
-    </WithActions>
+    <WithActions actions={<OpenSubagentAction onOpen={() => onOpenSubagent(block.task.id)} />}>{row}</WithActions>
   )
 }
 
-/** When the current run began — the clock the working line counts from. Held
- * here, not in the row, because the row comes and goes within a single turn (it
- * hides the moment text streams) and a clock restarting at every tool call
- * would be measuring the wrong thing. */
 function useRunStart(status: TranscriptState['status']): number | undefined {
   const running = status === 'running' || status === 'starting'
   const [startedAt, setStartedAt] = useState<number | undefined>(undefined)
@@ -242,25 +128,24 @@ function useRunStart(status: TranscriptState['status']): number | undefined {
   return running ? startedAt : undefined
 }
 
-/** Is the model between outputs? Only then does the working line show — while
- * text is streaming, the text itself is the evidence. */
 function working(state: TranscriptState): boolean {
-  if (state.status !== 'running' && state.status !== 'starting') return false
+  if (state.status !== 'running' && state.status !== 'starting') {
+    return false
+  }
   const last = state.items.at(-1)
-  if (!last) return true
-  if (last.kind === 'assistant_text' && last.streaming) return false
-  if (last.kind === 'thinking' && last.id === 'streaming-thinking') return false
+  if (!last) {
+    return true
+  }
+  if (last.kind === 'assistant_text' && last.streaming) {
+    return false
+  }
+  if (last.kind === 'thinking' && last.id === 'streaming-thinking') {
+    return false
+  }
   return true
 }
 
-export function TerminalTranscript({
-  state,
-  fileUrl,
-  fontSize,
-  lineHeight,
-  affordances,
-  className,
-}: TerminalTranscriptProps) {
+export function TerminalTranscript({ state, fileUrl, fontSize, lineHeight, affordances, className }: TerminalTranscriptProps) {
   const runStartedAt = useRunStart(state.status)
   const blocks = useMemo(() => terminalBlocks(state.items), [state.items])
   return (
@@ -268,10 +153,9 @@ export function TerminalTranscript({
       fontSize={fontSize}
       lineHeight={lineHeight}
       affordances={affordances}
-      // One cell of breathing room at each edge, and the value a full-bleed
-      // band cancels so its wash reaches the scroller's edge.
-      bleed='1ch'
-      className={cn('term-transcript', className)}>
+      bleed="1ch"
+      className={cn('term-transcript', className)}
+    >
       {blocks.map((block, index) => (
         <Fragment key={block.key}>
           {index > 0 && blockNeedsBlank(blocks[index - 1]!, block) ? <Blank /> : null}

package/src/components/terminal/affordances.tsx

@@ -1,30 +1,9 @@
 import { createContext, useContext, useState, type ReactNode } from 'react'
+import { copyText } from '../../lib/clipboard.ts'
 import { cn } from '../../lib/utils.ts'
 
-/**
- * The things a terminal cannot do, and this can.
- *
- * The theme's whole discipline is that it renders like a CLI — but it is not a
- * CLI, and refusing every affordance a pointer makes possible would be cosplay
- * rather than design. A terminal cannot highlight the row under your cursor and
- * cannot put a copy button on a block of output; a web view can do both for free
- * and they are genuinely useful.
- *
- * The rule that keeps this honest is that **each one costs no layout**. A hover
- * fill is a background. An action button is an overlay at the row's right edge,
- * one line tall, absolutely positioned so it displaces nothing. Turn them all
- * off and every glyph is on exactly the same cell it was on — which is what
- * makes `off` a real option rather than a degraded mode, and why it is the mode
- * a host projecting to a real terminal would choose.
- *
- * Off by nothing in particular: both default **on**, because the surface these
- * render on is a browser and pretending otherwise helps nobody. A host that
- * wants the pure article passes `affordances={false}`.
- */
 export type TerminalAffordances = {
-  /** Fill the row under the pointer, on anything pressable. */
   hover?: boolean
-  /** Reveal a row's actions (copy, and whatever a row adds) on hover or focus. */
   actions?: boolean
 }
 
@@ -36,88 +15,83 @@ export function useAffordances(): Required<TerminalAffordances> {
   return useContext(AffordanceContext)
 }
 
-/** Resolve the surface's prop — `false` means none, `true`/absent means all. */
-export function resolveAffordances(
-  value: TerminalAffordances | boolean | undefined,
-): Required<TerminalAffordances> {
-  if (value === false) return { hover: false, actions: false }
-  if (value === true || value === undefined) return DEFAULTS
+export function resolveAffordances(value: TerminalAffordances | boolean | undefined): Required<TerminalAffordances> {
+  if (value === false) {
+    return { hover: false, actions: false }
+  }
+  if (value === true || value === undefined) {
+    return DEFAULTS
+  }
   return { ...DEFAULTS, ...value }
 }
 
-export function AffordanceProvider({
-  value,
-  children,
-}: {
-  value: Required<TerminalAffordances>
-  children: ReactNode
-}) {
+export function AffordanceProvider({ value, children }: { value: Required<TerminalAffordances>; children: ReactNode }) {
   return <AffordanceContext.Provider value={value}>{children}</AffordanceContext.Provider>
 }
 
-/**
- * A block that reveals its actions on hover.
- *
- * Wraps rather than decorates because the actions belong to the *block* — a
- * message is many rows and its copy button belongs at the top right of all of
- * them, not on whichever row the pointer happens to be over.
- */
-export function WithActions({
-  actions,
-  children,
-  className,
-}: {
-  actions: ReactNode
-  children: ReactNode
-  className?: string
-}) {
+export function WithActions({ actions, children, className }: { actions: ReactNode; children: ReactNode; className?: string }) {
   const { actions: enabled } = useAffordances()
-  if (!enabled) return <>{children}</>
+  if (!enabled) {
+    return <>{children}</>
+  }
   return (
     <div className={cn('term-hoverable', className)}>
       {children}
-      <div className='term-actions'>{actions}</div>
+      <div className="term-actions">{actions}</div>
     </div>
   )
 }
 
-/**
- * Copy, as a character.
- *
- * `⧉` and `✓` rather than an SVG for the same reason the rest of the theme uses
- * glyphs: an icon drawn at some other size sits between the cells everything
- * else is on, and reads as a button borrowed from another application. The tick
- * replaces the glyph in place, so the confirmation costs no width either.
- */
-/**
- * Open a sub-agent's own surface, as a character.
- *
- * A row **action** and not the row's press, because the press already means
- * expand/collapse and that is the cheaper, more common intent — a reader
- * glancing at what an agent did wants the four rows inline, not a new screen.
- * Taking over the panel is the deliberate move, so it gets the deliberate
- * target. Same zero-layout contract as `CopyAction`: it lives in the hover
- * actions overlay, so a collapsed Task row is exactly as tall with it as
- * without, which is what keeps the height book honest.
- */
-export function OpenSubagentAction({
-  onOpen,
-  label = 'Open sub-agent',
-}: {
-  onOpen: () => void
-  label?: string
-}) {
+// Bookmarks are a host concern (which items, where they persist); the transcript only needs
+// membership and a toggle. A missing provider renders no action at all, so embeddings that
+// never wire bookmarks pay nothing — the same contract AffordanceContext has.
+export type BookmarkHandle = {
+  has: (itemId: string) => boolean
+  toggle: (itemId: string) => void
+}
+
+const BookmarkContext = createContext<BookmarkHandle | undefined>(undefined)
+
+export function BookmarkProvider({ value, children }: { value: BookmarkHandle | undefined; children: ReactNode }) {
+  return <BookmarkContext.Provider value={value}>{children}</BookmarkContext.Provider>
+}
+
+export function BookmarkAction({ id }: { id: string }) {
+  const handle = useContext(BookmarkContext)
+  if (!handle) {
+    return null
+  }
+  const active = handle.has(id)
+  const label = active ? 'Remove bookmark' : 'Bookmark'
+  return (
+    <button
+      type="button"
+      className="term-action"
+      title={label}
+      aria-label={label}
+      aria-pressed={active}
+      onClick={(event) => {
+        event.stopPropagation()
+        handle.toggle(id)
+      }}
+    >
+      {active ? '★' : '☆'}
+    </button>
+  )
+}
+
+export function OpenSubagentAction({ onOpen, label = 'Open sub-agent' }: { onOpen: () => void; label?: string }) {
   return (
     <button
-      type='button'
-      className='term-action'
+      type="button"
+      className="term-action"
       title={label}
       aria-label={label}
       onClick={(event) => {
-        // The row underneath expands; opening is not expanding.
         event.stopPropagation()
         onOpen()
-      }}>
+      }}
+    >
       ⤢
     </button>
   )
@@ -127,25 +101,21 @@ export function CopyAction({ text, label = 'Copy' }: { text: string; label?: str
   const [copied, setCopied] = useState(false)
   return (
     <button
-      type='button'
-      className='term-action'
+      type="button"
+      className="term-action"
       title={label}
       aria-label={label}
       onClick={(event) => {
-        // The row underneath is usually pressable (a tool call expands); copying
-        // is not expanding.
         event.stopPropagation()
-        void navigator.clipboard
-          ?.writeText(text)
-          .then(() => {
-            setCopied(true)
-            setTimeout(() => setCopied(false), 1200)
-          })
-          // No toast, no error row: a refused clipboard (an insecure origin, a
-          // denied permission) is the host's business, and a failed copy that
-          // says nothing is better than a transcript that grows an error.
-          .catch(() => {})
-      }}>
+        void copyText(text).then((ok) => {
+          if (!ok) {
+            return
+          }
+          setCopied(true)
+          setTimeout(() => setCopied(false), 1200)
+        })
+      }}
+    >
       {copied ? '✓' : '⧉'}
     </button>
   )