@workerdeck/ui 0.13.0 → 0.16.0

package/src/components/terminal/QuestionPrompt.tsx

@@ -0,0 +1,322 @@
+import { useState } from 'react'
+import type { PermissionRequest, UserQuestion } from '@workerdeck/protocol'
+import { parseUserQuestions } from '../agent/QuestionPrompt.tsx'
+import { Box, Choices, Hint, PromptInput, Rule, TabStrip, type Choice } from './prompt.tsx'
+import { Blank, Ink, Row } from './row.tsx'
+
+/**
+ * The AskUserQuestion form, in the CLI's shape: **one question at a time**,
+ * behind a strip of chips, ending in a review step.
+ *
+ * The card version stacks every question on screen at once, which is right for a
+ * dialog and wrong here for a reason worth stating: a terminal form is answered
+ * with the keyboard, and a stacked form has no answer to "where does `Tab` go" —
+ * it has as many focus targets as there are options across every question. One
+ * question at a time makes the keys unambiguous (`↑↓` within, `Tab` between,
+ * `Enter` to take), and it is why the chips exist: something has to say that
+ * answering the first of three is not finishing.
+ *
+ * The review step is the other half of that. Answers given one screen at a time
+ * are answers you cannot see together, so the last chip shows all of them and
+ * asks once more before they go back to the model.
+ */
+
+type Selection = { labels: string[]; other: string; otherActive: boolean }
+
+const EMPTY: Selection = { labels: [], other: '', otherActive: false }
+
+/** A question's answer: chosen label(s), comma-joined, with any free-text
+ * "Other" appended — the shape the CLI's own UI puts in `updatedInput.answers`. */
+function answerFor(selection: Selection): string {
+  const parts = [...selection.labels]
+  if (selection.otherActive && selection.other.trim()) parts.push(selection.other.trim())
+  return parts.join(', ')
+}
+
+export interface TerminalQuestionPromptProps {
+  /** A pending permission whose toolName is 'AskUserQuestion'. */
+  request: PermissionRequest
+  /** Allow the tool with `updatedInput` (the original input plus `answers`). */
+  onAnswer: (requestId: string, updatedInput: Record<string, unknown>) => void
+  /** Deny the tool — the model proceeds without an answer. */
+  onDismiss: (requestId: string, message?: string) => void
+}
+
+export function TerminalQuestionPrompt({
+  request,
+  onAnswer,
+  onDismiss,
+}: TerminalQuestionPromptProps) {
+  const questions = parseUserQuestions(request.input)
+  const [selections, setSelections] = useState<Selection[]>(() => questions.map(() => EMPTY))
+  const [cursors, setCursors] = useState<number[]>(() => questions.map(() => 0))
+  // Tabs are the questions plus the review step, so `questions.length` is the
+  // review — one index space, which is what makes Tab a single `+1`.
+  const [tab, setTab] = useState(0)
+  const [reviewCursor, setReviewCursor] = useState(0)
+
+  const review = tab >= questions.length
+  const selection = selections[tab] ?? EMPTY
+  const answered = (index: number) => answerFor(selections[index] ?? EMPTY) !== ''
+  const complete = questions.every((_, index) => answered(index))
+
+  const update = (index: number, patch: Partial<Selection>) =>
+    setSelections((prev) => prev.map((s, i) => (i === index ? { ...s, ...patch } : s)))
+
+  // Functional, and it has to be: reading `selections` from the render closure
+  // means two toggles in one tick both compute from the same base and the second
+  // silently drops the first. A multi-select is exactly where that happens.
+  const toggle = (index: number, label: string, multiSelect: boolean) => {
+    setSelections((prev) =>
+      prev.map((current, i) => {
+        if (i !== index) return current
+        if (!multiSelect) return { ...current, labels: [label], otherActive: false }
+        return {
+          ...current,
+          labels: current.labels.includes(label)
+            ? current.labels.filter((l) => l !== label)
+            : [...current.labels, label],
+        }
+      }),
+    )
+  }
+
+  const submit = () => {
+    const answers: Record<string, string> = {}
+    questions.forEach((question, index) => {
+      answers[question.question] = answerFor(selections[index] ?? EMPTY)
+    })
+    onAnswer(request.id, { ...request.input, answers })
+  }
+
+  const dismiss = () => onDismiss(request.id, 'Question dismissed by user')
+
+  const move = (delta: number) =>
+    setTab((current) => Math.min(questions.length, Math.max(0, current + delta)))
+
+  return (
+    <div
+      data-slot='question-prompt'
+      onKeyDown={(event) => {
+        if (event.key === 'Escape') {
+          event.preventDefault()
+          dismiss()
+          return
+        }
+        if (event.key === 'Tab') {
+          event.preventDefault()
+          move(event.shiftKey ? -1 : 1)
+        }
+      }}>
+      <Rule />
+      <TabStrip
+        tabs={[
+          ...questions.map((question, index) => ({
+            key: `q${index}`,
+            label: question.header || `Question ${index + 1}`,
+            glyph: answered(index) ? '▣' : '▢',
+          })),
+          { key: 'submit', label: 'Submit', glyph: '✓' },
+        ]}
+        active={tab}
+        onSelect={setTab}
+      />
+      <Blank />
+      {review ? (
+        <ReviewStep
+          questions={questions}
+          answers={questions.map((_, index) => answerFor(selections[index] ?? EMPTY))}
+          complete={complete}
+          cursor={reviewCursor}
+          onCursor={setReviewCursor}
+          onSubmit={submit}
+          onCancel={dismiss}
+        />
+      ) : (
+        <QuestionStep
+          // Keyed by question, and load-bearing: without it React reuses the
+          // step across a Tab and the option list never re-arms its focus, so
+          // the keyboard lands on nothing and the next `3` or `Esc` goes
+          // nowhere. Remounting is also what re-runs the focus takeover.
+          key={tab}
+          question={questions[tab]!}
+          selection={selection}
+          cursor={cursors[tab] ?? 0}
+          onCursor={(next) => setCursors((prev) => prev.map((c, i) => (i === tab ? next : c)))}
+          onToggle={(label) => toggle(tab, label, questions[tab]!.multiSelect === true)}
+          onOther={(patch) => update(tab, patch)}
+          onAdvance={() => move(1)}
+          onDismiss={dismiss}
+        />
+      )}
+      <Blank />
+      <Hint>
+        Enter to select · ↑/↓ to navigate · Tab to switch questions · Esc to cancel
+      </Hint>
+    </div>
+  )
+}
+
+function QuestionStep({
+  question,
+  selection,
+  cursor,
+  onCursor,
+  onToggle,
+  onOther,
+  onAdvance,
+  onDismiss,
+}: {
+  question: UserQuestion
+  selection: Selection
+  cursor: number
+  onCursor: (index: number) => void
+  onToggle: (label: string) => void
+  onOther: (patch: Partial<Selection>) => void
+  onAdvance: () => void
+  onDismiss: () => void
+}) {
+  const multiSelect = question.multiSelect === true
+
+  const options: Choice[] = [
+    ...question.options.map((option, index): Choice => {
+      const selected = selection.labels.includes(option.label)
+      return {
+        key: option.label,
+        label: option.label,
+        description: option.description,
+        // Markers only where there is state to keep: a multi-select accumulates
+        // and has to show what is in the set, a one-of answers itself by being
+        // chosen and moves on — a column of empty radios in front of it would be
+        // three characters of nothing on every row. The CLI draws it the same way.
+        checked: multiSelect ? selected : undefined,
+        marker: 'check',
+        selected: !multiSelect && selected,
+        // A preview shows on **focus**, not only on selection: walking a list
+        // with the arrow keys, "what does this one look like" is the question
+        // the cursor is asking.
+        detail:
+          option.preview && cursor === index ? (
+            <Box>
+              {option.preview.split('\n').map((line, row) => (
+                <Row key={row} columns={0} tone='dim'>
+                  {line || ' '}
+                </Row>
+              ))}
+            </Box>
+          ) : undefined,
+      }
+    }),
+    {
+      key: '__other',
+      label: 'Other…',
+      // Always markered, in both kinds: this row is a *mode* (the field is open
+      // or it isn't), which the reader cannot see any other way.
+      checked: selection.otherActive,
+      marker: 'check' as const,
+      detail: selection.otherActive ? (
+        <PromptInput
+          value={selection.other}
+          onChange={(value) => onOther({ other: value })}
+          onSubmit={onAdvance}
+          onCancel={() => onOther({ otherActive: false, other: '' })}
+          placeholder='Type your own answer'
+        />
+      ) : undefined,
+    },
+    // Multi-select has no natural end — every toggle leaves the list where it
+    // was — so it needs a row that says "done with this one". A one-of answers
+    // itself by being chosen and advances on its own.
+    ...(multiSelect ? [{ key: '__next', label: 'Submit' }] : []),
+    { key: '__chat', label: 'Chat about this' },
+  ]
+
+  return (
+    <>
+      <Row bold tone='bright'>
+        {question.question}
+      </Row>
+      <Blank />
+      <Choices
+        label={question.question}
+        options={options}
+        focused={cursor}
+        active={!selection.otherActive}
+        onFocus={onCursor}
+        onChoose={(index) => {
+          if (index < question.options.length) {
+            onToggle(question.options[index]!.label)
+            // A one-of is finished the moment it is picked; making the reader
+            // press Tab as well would be a keystroke that answers nothing.
+            if (!multiSelect) onAdvance()
+            return
+          }
+          if (index === question.options.length) {
+            onOther({ otherActive: !selection.otherActive })
+            return
+          }
+          if (multiSelect && index === question.options.length + 1) {
+            onAdvance()
+            return
+          }
+          onDismiss()
+        }}
+      />
+    </>
+  )
+}
+
+/** The last chip: every answer together, and one more chance to change it. */
+function ReviewStep({
+  questions,
+  answers,
+  complete,
+  cursor,
+  onCursor,
+  onSubmit,
+  onCancel,
+}: {
+  questions: UserQuestion[]
+  answers: string[]
+  complete: boolean
+  cursor: number
+  onCursor: (index: number) => void
+  onSubmit: () => void
+  onCancel: () => void
+}) {
+  return (
+    <>
+      <Row bold tone='bright'>
+        Review your answers
+      </Row>
+      <Blank />
+      {questions.map((question, index) => (
+        <div key={index}>
+          <Row glyph='●' glyphTone='dim'>
+            {question.question}
+          </Row>
+          <Row indent={1} glyph='→' glyphTone='green'>
+            <Ink tone={answers[index] ? 'green' : 'faint'}>
+              {answers[index] || 'not answered'}
+            </Ink>
+          </Row>
+        </div>
+      ))}
+      <Blank />
+      <Row>{complete ? 'Ready to submit your answers?' : 'Some questions are unanswered.'}</Row>
+      <Choices
+        label='Submit answers'
+        options={[
+          // Offered even when incomplete: an unanswered question is a legitimate
+          // answer to give, and the model is told which ones were skipped. What
+          // it must not do is *look* finished, which is what the row above says.
+          { key: 'submit', label: complete ? 'Submit answers' : 'Submit anyway' },
+          { key: 'cancel', label: 'Cancel', danger: true },
+        ]}
+        focused={cursor}
+        onFocus={onCursor}
+        onChoose={(index) => (index === 0 ? onSubmit() : onCancel())}
+      />
+    </>
+  )
+}

package/src/components/terminal/StatusLine.tsx

@@ -0,0 +1,159 @@
+import type { RateLimitInfo } from '@workerdeck/protocol'
+import type { ConnectionState, TranscriptState } from '@workerdeck/react'
+import { formatCost, formatTokens } from '../../lib/format.ts'
+import {
+  contextSeverity,
+  meterSeverity,
+  modelLabel,
+  statusPresentation,
+  tightestWindow,
+  windowLabel,
+  type StatusSeverity,
+} from '../../lib/status.ts'
+import { Ink, Row, type Tone } from './row.tsx'
+
+/**
+ * The session's readings, as one line.
+ *
+ * The styled bar puts each of these in its own affordance — a progress ring, a
+ * badge, a tooltip — which is right for a dashboard and wrong here for the usual
+ * reason: a terminal has one line height, and five widgets of five different
+ * heights is five different rhythms in a row that is supposed to be quiet. So
+ * they are words, `·`-separated, exactly as the CLI's own status line writes
+ * them.
+ *
+ * The readings themselves come from the same helpers the styled bar uses
+ * (`lib/status.ts`), and that matters more than it looks: `statusPresentation`
+ * is where the rule lives that **a dropped socket outranks the session status**,
+ * because a status held over a dead socket is a stale reading being presented as
+ * a live one. Re-deriving that here would be a second answer to a question that
+ * already has one.
+ */
+
+/** Severity → tone. The 80/95 thresholds are `lib/status.ts`'s, not new ones. */
+const SEVERITY_TONE: Record<StatusSeverity, Tone> = {
+  none: 'dim',
+  warning: 'yellow',
+  error: 'red',
+}
+
+export interface TerminalStatusLineProps {
+  state: TranscriptState
+  /** Plan windows to read from, when they should not be the session's own — the
+   * gateway's per-profile state merged over this transcript's. See
+   * {@link StatusBarProps.rateLimits}. Absent = `state.rateLimits`. */
+  rateLimits?: Record<string, RateLimitInfo>
+  /** How the client is doing at reaching the gateway. Wins the status slot when
+   * the socket is down — see above. */
+  connection?: ConnectionState
+  /** Opens the panel that answers each reading's own question. Omit and the
+   * reading is text rather than something to press. */
+  onOpenStatus?: () => void
+  onOpenContext?: () => void
+  onOpenUsage?: () => void
+}
+
+/** One reading. A button only when it leads somewhere — a segment that looks
+ * pressable and does nothing is worse than plain text. */
+function Reading({
+  tone,
+  onPress,
+  label,
+  children,
+}: {
+  tone?: Tone
+  onPress?: () => void
+  label?: string
+  children: React.ReactNode
+}) {
+  if (!onPress) return <Ink tone={tone}>{children}</Ink>
+  return (
+    <button type='button' className='term-reading' onClick={onPress} title={label}>
+      <Ink tone={tone}>{children}</Ink>
+    </button>
+  )
+}
+
+export function TerminalStatusLine({
+  state,
+  rateLimits,
+  connection,
+  onOpenStatus,
+  onOpenContext,
+  onOpenUsage,
+}: TerminalStatusLineProps) {
+  const presentation = statusPresentation({ status: state.status, connection })
+  const usage = state.contextUsage
+  const window = tightestWindow(rateLimits ?? state.rateLimits)
+  const model = modelLabel({ model: state.model, models: state.models ?? [] })
+
+  const parts: React.ReactNode[] = [
+    <Reading
+      key='status'
+      tone={SEVERITY_TONE[presentation.severity]}
+      onPress={onOpenStatus}
+      label='Session status'>
+      {presentation.label}
+    </Reading>,
+  ]
+
+  if (usage) {
+    parts.push(
+      <Reading
+        key='context'
+        tone={SEVERITY_TONE[contextSeverity(usage)]}
+        onPress={onOpenContext}
+        label='Context window'>
+        {Math.round(usage.percentage)}% ctx ({formatTokens(usage.totalTokens)})
+      </Reading>,
+    )
+  }
+
+  if (window) {
+    parts.push(
+      <Reading
+        key='usage'
+        tone={SEVERITY_TONE[meterSeverity(window.info.utilization)]}
+        onPress={onOpenUsage}
+        label='Plan usage'>
+        {Math.round(window.info.utilization ?? 0)}% {windowLabel(window.key)}
+      </Reading>,
+    )
+  }
+
+  // Cost last of the numbers: it is the reading you check, never the one you act
+  // on, and nothing about a turn changes because of it.
+  if (state.totalCostUsd > 0) {
+    parts.push(
+      <Ink key='cost' tone='faint'>
+        {formatCost(state.totalCostUsd)}
+      </Ink>,
+    )
+  }
+
+  if (model) {
+    parts.push(
+      <Ink key='model' tone='faint'>
+        {model}
+      </Ink>,
+    )
+  }
+  if (state.permissionMode && state.permissionMode !== 'default') {
+    parts.push(
+      <Ink key='mode' tone='yellow'>
+        {state.permissionMode}
+      </Ink>,
+    )
+  }
+
+  return (
+    <Row data-slot='status-line' tone='dim'>
+      {parts.map((part, index) => (
+        <span key={index}>
+          {index > 0 ? <Ink tone='faint'> · </Ink> : null}
+          {part}
+        </span>
+      ))}
+    </Row>
+  )
+}

package/src/components/terminal/TerminalTranscript.tsx

@@ -0,0 +1,147 @@
+import { Fragment, useEffect, useMemo, useState } from 'react'
+import type { TranscriptItem, TranscriptState } from '@workerdeck/react'
+import { cn } from '../../lib/utils.ts'
+import type { TerminalAffordances } from './affordances.tsx'
+import {
+  AssistantRow,
+  FileRow,
+  NoticeRow,
+  ToolRunRow,
+  ThinkingRow,
+  ToolRow,
+  TurnResultRow,
+  UserRow,
+  WorkingRow,
+  blockNeedsBlank,
+  terminalBlocks,
+} from './items.tsx'
+import { Blank } 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
+}) {
+  switch (item.kind) {
+    case 'user':
+      return <UserRow item={item} />
+    case 'assistant_text':
+      return <AssistantRow item={item} />
+    case 'thinking':
+      return <ThinkingRow item={item} />
+    case 'tool_call':
+      return <ToolRow item={item} />
+    case 'turn_result':
+      return <TurnResultRow item={item} />
+    case 'notice':
+      return <NoticeRow item={item} />
+    case 'file_delivered':
+      return <FileRow item={item} href={fileUrl?.(item.path)} />
+    default:
+      return null
+  }
+}
+
+/** 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)
+  useEffect(() => {
+    setStartedAt((previous) => (running ? (previous ?? Date.now()) : undefined))
+  }, [running])
+  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
+  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
+  return true
+}
+
+export function TerminalTranscript({
+  state,
+  fileUrl,
+  fontSize,
+  lineHeight,
+  affordances,
+  className,
+}: TerminalTranscriptProps) {
+  const runStartedAt = useRunStart(state.status)
+  const blocks = useMemo(() => terminalBlocks(state.items), [state.items])
+  return (
+    <TerminalSurface
+      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)}>
+      {blocks.map((block, index) => (
+        <Fragment key={block.key}>
+          {index > 0 && blockNeedsBlank(blocks[index - 1]!, block) ? <Blank /> : null}
+          {'run' in block ? (
+            <ToolRunRow items={block.run} />
+          ) : (
+            <TerminalItemView item={block.item} fileUrl={fileUrl} />
+          )}
+        </Fragment>
+      ))}
+      {working(state) ? (
+        <>
+          {state.items.length > 0 ? <Blank /> : null}
+          <WorkingRow
+            label={state.status === 'starting' ? 'Starting…' : 'Working…'}
+            startedAt={runStartedAt}
+            tokens={state.contextUsage?.totalTokens}
+          />
+        </>
+      ) : null}
+    </TerminalSurface>
+  )
+}