@weft-js/warp 0.0.0-stage → 0.1.0

package/src/agent/ContextMeter.tsx

@@ -0,0 +1,31 @@
+import { contextLevel, formatTokens } from '@weft-js/warp-core'
+import { derived } from '@weft-js/core'
+import { Button } from '../Button'
+import { Tooltip } from '../Tooltip'
+import '../styles'
+import '@weft-js/warp-core/styles/app/context-meter.css'
+
+/** How full the context window is, and optionally what with. */
+export type ContextUse = { used: number; limit: number; parts?: { label: string; tokens: number }[] | undefined }
+
+/**
+ * ContextMeter (07 §1.2): a ring and a number, caution at 80%, critical at 95%, where `onCompact` offers /compact. The
+ * tooltip lists what fills it. `showTokens` adds the count beside the percent.
+ */
+export function ContextMeter({ used, limit, parts, showTokens, onCompact }: ContextUse & { showTokens?: boolean; onCompact?: (() => void) | undefined }) {
+  const ratio = derived(() => Math.min(1, limit > 0 ? used / limit : 0))
+  const level = derived(() => contextLevel(ratio.value))
+  const pct = derived(() => Math.round(ratio.value * 100))
+  const tip = derived(() => [`${formatTokens(used)} of ${formatTokens(limit)} tokens`, ...(parts ?? []).map(p => `${p.label} ${formatTokens(p.tokens)}`)].join(' · '))
+  return (
+    <>
+      <Tooltip content={tip.value}>
+        <span data-scope="context-meter" data-level={level.value} role="meter" tabindex="0" aria-label="Context used" aria-valuemin="0" aria-valuemax="100" aria-valuenow={pct.value} aria-valuetext={`${pct.value}%, ${formatTokens(used)} of ${formatTokens(limit)} tokens`} style={`--_v:${ratio.value}`}>
+          <svg viewBox="0 0 36 36" aria-hidden="true"><circle cx="18" cy="18" r="15.9" stroke="var(--warp-color-surface-active)" pathLength="100" /><circle cx="18" cy="18" r="15.9" pathLength="100" /></svg>
+          <span>{showTokens ? `${pct.value}% · ${formatTokens(used)}` : `${pct.value}%`}</span>
+        </span>
+      </Tooltip>
+      {level.value && onCompact && <Button emphasis="link" tone="neutral" size="sm" onClick={onCompact}>/compact</Button>}
+    </>
+  )
+}

package/src/agent/Conversation.tsx

@@ -0,0 +1,34 @@
+import { DownIcon } from '@weft-js/warp-icons'
+import { stick } from '@weft-js/warp-core'
+import { derived, state } from '@weft-js/core'
+import { Button } from '../Button'
+import { use } from '@weft-js/warp-core/weft'
+import '../styles'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/base.css'
+import '@weft-js/warp-core/styles/app/thread.css'
+
+/**
+ * Conversation (07 §1.1, §1.3, §1.6): role=log with aria-live off (a turn announces its own end), keyed turns as
+ * `children`, an optional app bar and the Prompt below. It sticks to the bottom only within 48px of it; otherwise Jump
+ * to latest appears, and pressing it goes back to the end and focuses the log.
+ */
+export function Conversation({ label = 'Assistant conversation', title, bar, prompt, children }: { label?: string | undefined; title?: unknown; bar?: unknown; prompt?: unknown; children?: unknown }) {
+  const away = state(false)
+  const head = derived(() => title !== undefined || bar !== undefined)
+  let log: HTMLElement | undefined
+  use(stick, () => log, () => ({ onAway: (a: boolean) => (away.value = a) }))
+  const jump = () => {
+    log!.scrollTop = log!.scrollHeight
+    log!.focus({ preventScroll: true })
+    away.value = false
+  }
+  return (
+    <section data-scope="thread" data-part="root" aria-label={label}>
+      {head.value && <div data-part="app-bar"><h2 data-part="app-title">{title}</h2><span data-part="spacer"></span>{bar}</div>}
+      <div ref={n => (log = n)} data-part="log" role="log" aria-live="off" aria-label="Messages" tabindex="0">{children}</div>
+      {away.value && <Button emphasis="soft" tone="neutral" size="sm" data-part="jump" onClick={jump}><DownIcon />Jump to latest</Button>}
+      <div style="grid-row:3">{prompt}</div>
+    </section>
+  )
+}

package/src/agent/Message.tsx

@@ -0,0 +1,53 @@
+import { CopyIcon, EditIcon } from '@weft-js/warp-icons'
+import { copyConfirm, installSweep } from '@weft-js/warp-core'
+import { onMount, state, untrack } from '@weft-js/core'
+import { Button } from '../Button'
+import { Textarea } from '../Field'
+import { IconButton, Sweep } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/app/message.css'
+
+/**
+ * The user's turn (07 §1.1): a prompt bubble with edit and copy. `arrive` is a message just sent: it enters and
+ * confirms one sweep. Edit opens the bubble as a Textarea in place; saving is `onEdit` (a new branch).
+ */
+export function Message({ text, arrive, onEdit }: { text: string; arrive?: boolean; onEdit?: ((text: string) => void) | undefined }) {
+  const editing = state(false)
+  const draft = state('')
+  let bubble: HTMLElement | undefined
+  let root: HTMLElement | undefined
+  onMount(() => { const s = installSweep(); if (untrack(() => arrive)) requestAnimationFrame(() => s.confirm(bubble)) })
+  const open = () => {
+    draft.value = text
+    editing.value = true
+    queueMicrotask(() => root?.querySelector('textarea')?.focus())
+  }
+  const close = () => {
+    editing.value = false
+    queueMicrotask(() => root?.querySelector<HTMLElement>('[aria-label="Edit message"]')?.focus())
+  }
+  const save = () => { const t = draft.value.trim(); close(); if (t && t !== text) onEdit?.(t) }
+  return (
+    <div ref={n => (root = n)} data-scope="message" data-mine="" data-arrive={arrive ? '' : undefined}>
+      <div data-part="body">
+        {editing.value ? (
+          <>
+            <Textarea label="Edit message" value={draft.value} onInput={e => (draft.value = e.currentTarget.value)} onKeyDown={(e: KeyboardEvent) => { if (e.key === 'Escape') { e.preventDefault(); close() } }} />
+            <div data-part="status">
+              <Button size="sm" onClick={save}>Save</Button>
+              <Button emphasis="ghost" tone="neutral" size="sm" onClick={close}>Cancel</Button>
+            </div>
+          </>
+        ) : (
+          <>
+            <div ref={n => (bubble = n)} data-part="bubble" data-variant="prompt" data-sweep=""><Sweep />{text}</div>
+            <div data-part="status" style="gap:2px">
+              {onEdit && <IconButton icon={EditIcon} label="Edit message" onClick={open} />}
+              <IconButton icon={CopyIcon} label="Copy" onClick={(e: Event) => copyConfirm(e.currentTarget as Element, text, bubble)} />
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/agent/ModelPicker.tsx

@@ -0,0 +1,65 @@
+import { DownIcon } from '@weft-js/warp-icons'
+import { announce, nextIndex, popover, uid } from '@weft-js/warp-core'
+import { derived, state, type State } from '@weft-js/core'
+import { Badge } from '../Badge'
+import { use } from '@weft-js/warp-core/weft'
+import { held } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/components/popover.css'
+import '@weft-js/warp-core/styles/app/prompt.css'
+import '@weft-js/warp-core/styles/app/suggest.css'
+import '@weft-js/warp-core/styles/app/model-menu.css'
+
+/** A model on offer. */
+export type ModelOption = { id: string; name: string; short?: string; provider?: string | undefined; description?: string | undefined; capabilities?: string[]; context?: string; cost?: string }
+
+/**
+ * ModelPicker (07 §1.3): the model chip opens a Popover holding a listbox grouped by provider. Each option shows its
+ * capabilities, context size and relative cost; the current one is checked. ↑/↓, Home/End move, Enter picks, Escape
+ * closes; focus goes back to the chip. `compact` shows the short name.
+ */
+export function ModelPicker({ models, value, onChange, compact }: { models: ModelOption[]; value?: string | State<string | undefined> | undefined; onChange?: ((id: string) => void) | undefined; compact?: boolean | undefined }) {
+  const id = uid('model')
+  const open = state(false)
+  const picked = held<string | undefined>(() => value, undefined, () => (v: string | undefined) => onChange?.(v!))
+  const current = derived(() => models.find(m => m.id === picked.value) ?? models[0])
+  const groups = derived(() => [...new Set(models.map(m => m.provider ?? ''))].map(name => ({ name, models: models.filter(m => (m.provider ?? '') === name) })))
+  let chip: HTMLButtonElement | undefined
+  let panel: HTMLElement | undefined
+  use(popover, () => panel, () => ({ open: open.value, trigger: chip!, side: 'top' as const, align: 'end' as const, onClose: () => (open.value = false) }))
+  const choose = (m: ModelOption) => {
+    picked.set(m.id)
+    open.value = false
+    announce(panel!.ownerDocument, `Model: ${m.name}`)
+  }
+  const onKey = (e: KeyboardEvent) => {
+    const list = [...panel!.querySelectorAll<HTMLElement>('[role="option"]')]
+    const at = list.indexOf(e.target as HTMLElement)
+    const to = nextIndex(e.key, at, list.length, { orientation: 'vertical' })
+    if (to >= 0) { e.preventDefault(); list[to]!.focus() }
+    else if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); list[at]?.click() }
+  }
+  return (
+    <span data-scope="prompt" style="display:contents">
+      <button ref={n => (chip = n)} type="button" data-part="model" aria-haspopup="listbox" aria-expanded={open.value ? 'true' : 'false'} aria-controls={id} onClick={() => (open.value = !open.value)}>
+        <i></i><span data-part="sr-only">Model: </span><span>{compact ? (current.value?.short ?? current.value?.name) : current.value?.name}</span><DownIcon />
+      </button>
+      <div ref={n => (panel = n)} id={id} data-scope="popover" data-part="content" popover="manual" style="padding:4px;min-inline-size:280px">
+        <div data-scope="model-menu" role="listbox" aria-label="Model" onKeyDown={onKey}>
+          {groups.value.map(g => (
+            <div key={g.name} role="group" aria-label={g.name || 'Models'}>
+              <div data-scope="suggest" style="all:unset"><div data-part="group" aria-hidden="true">{g.name || 'Models'}</div></div>
+              {g.models.map(m => (
+                <div key={m.id} role="option" tabindex="-1" aria-selected={m.id === current.value?.id ? 'true' : 'false'} data-initial={m.id === current.value?.id ? '' : undefined} onClick={() => choose(m)}>
+                  <b>{m.name}</b>
+                  <small>{m.description} {(m.capabilities ?? []).map(c => <Badge key={c} tone="neutral">{c}</Badge>)}</small>
+                  <code>{[m.context, m.cost].filter(Boolean).join(' · ')}</code>
+                </div>
+              ))}
+            </div>
+          ))}
+        </div>
+      </div>
+    </span>
+  )
+}

package/src/agent/Prompt.tsx

@@ -0,0 +1,197 @@
+import { CommandIcon, FileIcon, GlobeIcon, MicIcon, PaperclipIcon, SendIcon, StopIcon, XIcon } from '@weft-js/warp-icons'
+import { announce, applySuggest, autosize, installSweep, suggestQuery, uid } from '@weft-js/warp-core'
+import { derived, onMount, state, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import { use } from '@weft-js/warp-core/weft'
+import { Bar, held, IconButton, Sweep } from './bits'
+import { ContextMeter, type ContextUse } from './ContextMeter'
+import { ModelPicker, type ModelOption } from './ModelPicker'
+import '../styles'
+import '@weft-js/warp-core/styles/app/prompt.css'
+import '@weft-js/warp-core/styles/app/composer.css'
+import '@weft-js/warp-core/styles/app/suggest.css'
+
+/** A tool the composer's row can offer. */
+export type PromptTool = 'attach' | 'slash' | 'mic' | 'web'
+/** A file attached to the prompt. */
+export type PromptFile = { id: string; name: string; progress?: number }
+/** A completion shown under the prompt. */
+export type PromptSuggestion = { value: string; description?: string | undefined }
+/** What the prompt hands out through `control`. */
+export interface PromptControl { insert(text: string): void; focus(): void }
+
+/** Props for Prompt. */
+export interface PromptProps {
+  value?: State<string> | string
+  /** Called with the draft on every keystroke. */
+  onValueChange?: (v: string) => void
+  onSubmit?: (text: string) => void
+  /** Pressing Stop or Escape while busy. Stop keeps what arrived. */
+  onStop?: () => void
+  /** A message sent while busy goes to the queue. */
+  onQueue?: (text: string) => void
+  busy?: boolean | undefined
+  /** Why Send is off ("You're offline"): the button stays focusable and says why. */
+  blocked?: string
+  label?: string | undefined
+  placeholder?: string
+  tools?: PromptTool[]
+  /** The picked model's id: a state, or a plain value with `onModelChange`. */
+  model?: State<string> | string
+  models?: ModelOption[]
+  /** Called with the id of the model picked. */
+  onModelChange?: (id: string) => void
+  context?: ContextUse
+  /** Called from the context meter's Compact: summarise the conversation to free room. */
+  onCompact?: () => void
+  /** Attached files shown as chips above the input, with upload progress. */
+  files?: PromptFile[]
+  /** Your own attachment row, in place of `files`. */
+  attachments?: unknown
+  /** Called with the files picked or dropped. */
+  onAttach?: (files: File[]) => void
+  /** Called with a file's id when its chip is removed. */
+  onRemoveFile?: (id: string) => void
+  /** What `/` offers: one suggestion each, with a description. */
+  commands?: PromptSuggestion[]
+  /** What `@` offers: one suggestion each, with a description. */
+  mentions?: PromptSuggestion[]
+  /** Whether the Web toggle is on. */
+  web?: boolean
+  /** Called with the Web toggle's new state. */
+  onWebChange?: (on: boolean) => void
+  /** Whether dictation is on: the mic button turns critical. */
+  mic?: boolean
+  /** Called when the mic button is pressed. */
+  onMic?: () => void
+  /** Phone: fewer tools, the model's short name. */
+  compact?: boolean | undefined
+  /** Hands over insert() and focus(), for SpeechInput's Insert. */
+  control?: ((c: PromptControl) => void) | undefined
+  /** Above the composer: Suggestions. */
+  children?: unknown
+}
+
+/**
+ * Prompt (07 §1.1, §1.6): one composer in the field's sweep. It grows to 8 lines; Enter sends, Shift+Enter adds a line,
+ * Escape stops. Send and Stop are one button, so focus never drops. `/` and `@` open a suggest listbox on the textarea
+ * (aria-activedescendant); files come by button or drop, the drag holding the sweep. Busy sends go to `onQueue`.
+ */
+export function Prompt(p: PromptProps) {
+  const id = uid('prompt')
+  const draft = held<string>(() => p.value, '', () => p.onValueChange)
+  const toolset = derived(() => p.tools ?? ['attach', 'slash', 'mic', 'web'])
+  const shown = (t: PromptTool) => toolset.value.includes(t)
+  const open = state<ReturnType<typeof suggestQuery>>(null)
+  const active = state(0)
+  const drag = state(false)
+  const options = derived(() => {
+    const q = open.value
+    if (!q) return []
+    const list = (q.trigger === '/' ? p.commands : p.mentions) ?? []
+    return list.filter(o => o.value.slice(1).toLowerCase().startsWith(q.query))
+  })
+  const listed = derived(() => options.value.length > 0)
+  const oid = (o: PromptSuggestion) => `${id}-o-${o.value.slice(1)}`
+  const current = derived(() => options.value[Math.min(active.value, options.value.length - 1)])
+  const activeId = derived(() => (current.value ? oid(current.value) : undefined))
+  const hasFiles = derived(() => p.attachments !== undefined || !!p.files?.length)
+  let box: HTMLTextAreaElement | undefined
+  let host: HTMLElement | undefined
+  let picker: HTMLInputElement | undefined
+  use(autosize, () => box, () => draft.value)
+  onMount(() => {
+    p.control?.({
+      insert(text) {
+        draft.set(draft.value ? `${draft.value} ${text}` : text)
+        box!.focus({ preventScroll: true })
+        installSweep().confirm(host)
+        announce(box!.ownerDocument, 'Inserted into the message box.')
+      },
+      focus: () => box!.focus(),
+    })
+  })
+  const look = () => {
+    open.value = suggestQuery(box!.value, box!.selectionStart)
+    active.value = 0
+  }
+  const pick = (value: string) => {
+    const q = open.value!
+    const next = applySuggest(box!.value, q.start, box!.selectionStart, value)
+    draft.set(next.text)
+    open.value = null
+    box!.value = next.text
+    box!.focus()
+    box!.setSelectionRange(next.caret, next.caret)
+  }
+  const send = () => {
+    const text = draft.value.trim()
+    if (!text) return
+    if (p.busy) {
+      if (!p.onQueue) return
+      p.onQueue(text)
+      announce(box!.ownerDocument, 'Queued. It will run after the current step.')
+    } else if (p.blocked) return
+    else p.onSubmit?.(text)
+    draft.set('')
+    open.value = null
+  }
+  const press = () => (p.busy ? p.onStop?.() : send())
+  const onKey = (e: KeyboardEvent) => {
+    if (listed.value) {
+      const n = options.value.length
+      if (e.key === 'Escape') { e.preventDefault(); open.value = null; return }
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') { e.preventDefault(); active.value = (active.value + (e.key === 'ArrowDown' ? 1 : n - 1)) % n; return }
+      if (e.key === 'Enter' || e.key === 'Tab') { e.preventDefault(); pick(current.value!.value); return }
+    }
+    if (e.key === 'Enter' && !e.shiftKey && !e.isComposing) { e.preventDefault(); send() }
+    else if (e.key === 'Escape' && p.busy) { e.preventDefault(); p.onStop?.() }
+  }
+  const add = (list: FileList | null | undefined) => { const f = [...(list ?? [])]; if (f.length) p.onAttach?.(f) }
+  const onDrop = (e: DragEvent) => { e.preventDefault(); drag.value = false; add(e.dataTransfer?.files) }
+  const over = (e: DragEvent) => { e.preventDefault(); drag.value = true }
+  return (
+    <div data-scope="prompt" style="position:relative;padding:0 var(--warp-space-group) var(--warp-space-group)">
+      {p.children}
+      <div ref={n => (host = n)} data-scope="composer" data-sweep="" data-pin={drag.value ? '' : undefined} style="margin:0" onDragOver={over} onDragLeave={() => (drag.value = false)} onDrop={onDrop}>
+        <Sweep />
+        {hasFiles.value && (
+          <div data-part="files">
+            {p.attachments ?? (p.files ?? []).map(f => (
+              <span key={f.id} data-part="file">
+                <FileIcon /><span>{f.name}</span>
+                <IconButton icon={XIcon} label={`Remove ${f.name}`} onClick={() => p.onRemoveFile?.(f.id)} />
+                {f.progress !== undefined && f.progress < 1 && <Bar label={`Uploading ${f.name}`} value={f.progress} />}
+              </span>
+            ))}
+          </div>
+        )}
+        <label data-part="sr-only" for={`${id}-in`}>{p.label ?? 'Message the assistant'}</label>
+        <textarea ref={n => (box = n)} id={`${id}-in`} rows="1" enterkeyhint="send" placeholder={p.placeholder ?? 'Ask, or type / for commands'} aria-describedby={p.blocked ? `${id}-hint ${id}-why` : `${id}-hint`} aria-controls={listed.value ? `${id}-list` : undefined} aria-activedescendant={activeId.value} value={draft.value} onInput={e => { draft.set((e.currentTarget).value); look() }} onKeyDown={onKey} onClick={look} onBlur={() => (open.value = null)}></textarea>
+        {p.blocked && <span data-part="hint" data-state="error" id={`${id}-why`}>{p.blocked}</span>}
+        <div data-part="row">
+          {shown('attach') && <IconButton icon={PaperclipIcon} label="Attach file" onClick={() => picker?.click()} />}
+          {shown('attach') && <input ref={n => (picker = n)} type="file" multiple hidden onChange={e => { add((e.currentTarget).files); (e.currentTarget).value = '' }} />}
+          {shown('slash') && !!p.commands?.length && <IconButton icon={CommandIcon} label="Commands" onClick={() => { draft.set('/'); box!.value = '/'; box!.focus(); box!.setSelectionRange(1, 1); look() }} />}
+          {shown('mic') && <IconButton icon={MicIcon} label="Dictate" tone={p.mic ? 'critical' : 'neutral'} aria-pressed={p.mic ? 'true' : 'false'} onClick={p.onMic} />}
+          {shown('web') && !p.compact && <Button emphasis="ghost" tone="neutral" size="sm" aria-pressed={p.web ? 'true' : 'false'} onClick={() => p.onWebChange?.(!p.web)}><GlobeIcon /><span data-part="label">Web</span></Button>}
+          <span data-part="spacer"></span>
+          {p.context && <ContextMeter used={p.context.used} limit={p.context.limit} parts={p.context.parts} onCompact={p.onCompact} />}
+          {p.models && <ModelPicker models={p.models} value={p.model} onChange={p.onModelChange} compact={p.compact} />}
+          <Button data-part="send" data-icon-only="" tone={p.busy ? 'neutral' : undefined} label={p.busy ? 'Stop' : 'Send'} aria-disabled={p.blocked && !p.busy ? 'true' : undefined} onClick={press}>{p.busy ? <StopIcon /> : <SendIcon />}</Button>
+        </div>
+        <span data-part="sr-only" id={`${id}-hint`}>Enter sends, Shift+Enter adds a line, Escape stops a running answer.</span>
+        {listed.value && (
+          <div data-scope="suggest" role="listbox" id={`${id}-list`} aria-label={open.value?.trigger === '/' ? 'Commands' : 'Mentions'}>
+            <div data-part="group" aria-hidden="true">{open.value?.trigger === '/' ? 'Commands' : 'Mentions'}</div>
+            {options.value.map(o => (
+              <div key={o.value} id={oid(o)} role="option" aria-selected={o === current.value ? 'true' : 'false'} onMouseDown={e => { e.preventDefault(); pick(o.value) }}>
+                <span data-part="cmd">{o.value}</span><small>{o.description}</small><kbd>{o === current.value ? '↵' : ''}</kbd>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/agent/Prose.tsx

@@ -0,0 +1,54 @@
+import { parseInline, parseText, type AgentSource, type Inline, type TextBlock } from '@weft-js/warp-core'
+import { derived, untrack } from '@weft-js/core'
+import { Cite } from './Cite'
+import '../styles'
+import '@weft-js/warp-core/styles/app/assistant.css'
+
+function Cited({ n, sources, base }: { n: number; sources: AgentSource[]; base: string }) {
+  const source = derived(() => sources[n - 1])
+  return <Cite n={n} source={source.value} href={`#${base}-s${n}`} />
+}
+
+type Mark = Extract<Inline, { kind: 'cite' }>
+type Run = Exclude<Inline, Mark>
+type Para = Extract<TextBlock, { kind: 'p' }>
+type List = Extract<TextBlock, { kind: 'ul' }>
+type Fence = Extract<TextBlock, { kind: 'code' }>
+
+function Span({ part, sources, base }: { part: Inline; sources: AgentSource[]; base: string }) {
+  const kind = derived(() => part.kind)
+  const view = derived(() => {
+    const k = kind.value
+    return untrack(() => (k === 'cite' ? <Cited n={(part as Mark).n} sources={sources} base={base} /> : k === 'code' ? <code>{(part as Run).text}</code> : <span>{(part as Run).text}</span>))
+  })
+  return <>{view.value}</>
+}
+
+function Spans({ text, sources, base }: { text: string; sources: AgentSource[]; base: string }) {
+  const parts = derived<Inline[]>(() => parseInline(text))
+  return <>{parts.value.map(p => <Span key={p.at} part={p} sources={sources} base={base} />)}</>
+}
+
+function Block({ block, sources, base }: { block: TextBlock; sources: AgentSource[]; base: string }) {
+  const kind = derived(() => block.kind)
+  // a block that changes kind (a paragraph becoming a list) rebuilds; one that only grows is patched
+  const view = derived(() => {
+    const k = kind.value
+    return untrack(() => {
+      if (k === 'p') return <p><Spans text={(block as Para).text} sources={sources} base={base} /></p>
+      if (k === 'ul') return <ul>{(block as List).items.map(i => <li key={i.at}><Spans text={i.text} sources={sources} base={base} /></li>)}</ul>
+      return <pre role="group" tabindex="0" aria-label={(block as Fence).lang ? `Code, ${(block as Fence).lang}` : 'Code'}><code>{(block as Fence).text}</code></pre>
+    })
+  })
+  return <>{view.value}</>
+}
+
+/**
+ * Answer text, the safe default until warp has Markdown: paragraphs, `- ` lists, code fences (open ones already render
+ * as code), inline code and `[n]` cites. Text only: nothing in the model's output becomes markup. Blocks are keyed by
+ * where they start, so streaming patches the last one in place.
+ */
+export function Prose({ text, sources = [], base = 'src' }: { text: string; sources?: AgentSource[]; base?: string }) {
+  const blocks = derived(() => parseText(text))
+  return <>{blocks.value.map(b => <Block key={b.at} block={b} sources={sources} base={base} />)}</>
+}

package/src/agent/Question.tsx

@@ -0,0 +1,52 @@
+import { CheckIcon } from '@weft-js/warp-icons'
+import { announce, uid, type AgentQuestion } from '@weft-js/warp-core'
+import { derived, onMount, state, untrack } from '@weft-js/core'
+import { Button } from '../Button'
+import { Checkbox, Radio } from '../Choice'
+import { Input } from '../Field'
+import '../styles'
+import '@weft-js/warp-core/styles/app/question.css'
+
+/**
+ * Question (07 §1.3): the run pauses and asks. A fieldset with the question as legend, radios or checkboxes, optional
+ * free text; Continue is the solid. Once answered it reads back the choice.
+ */
+export function Question({ question, onAnswer, quiet }: { question: AgentQuestion; onAnswer?: (answer: string | string[]) => void; quiet?: boolean | undefined }) {
+  const name = uid('q')
+  const type = derived(() => (question.multiple ? 'checkbox' : 'radio'))
+  const picks = state<string[]>(untrack(() => (question.multiple ? [] : question.options.slice(0, 1))))
+  const free = state('')
+  const other = '__other'
+  const options = derived(() => [...question.options.map(o => ({ value: o, label: o })), ...(question.free ? [{ value: other, label: 'Something else…' }] : [])])
+  const answered = derived(() => question.answer)
+  const said = derived(() => { const a = answered.value; return Array.isArray(a) ? a.join(', ') : a })
+  let form: HTMLFormElement | undefined
+  onMount(() => { if (!untrack(() => quiet) && form) announce(form.ownerDocument, 'The assistant has a question.', true) })
+  const toggle = (v: string, on: boolean) => (picks.value = question.multiple ? (on ? [...picks.value, v] : picks.value.filter(x => x !== v)) : [v])
+  const submit = (e: Event) => {
+    e.preventDefault()
+    const chosen = picks.value.map(p => (p === other ? free.value.trim() : p)).filter(Boolean)
+    if (chosen.length) onAnswer?.(question.multiple ? chosen : chosen[0]!)
+  }
+  // one build per phase: a list around this reads its nodes again as siblings arrive, and picks must survive that
+  const done = derived(() => answered.value !== undefined)
+  const view = derived(() => (done.value ? (
+    <p><CheckIcon /> You chose: {said.value}</p>
+  ) : untrack(() => (
+        <form ref={n => (form = n)} data-scope="question" onSubmit={submit}>
+          <fieldset disabled={question.closed}>
+            <legend>{question.prompt}</legend>
+            {options.value.map(o => (
+              type.value === 'radio'
+                ? <Radio key={o.value} name={name} checked={picks.value.includes(o.value)} onChange={(e: Event & { currentTarget: HTMLInputElement }) => toggle(o.value, e.currentTarget.checked)}>{o.label}</Radio>
+                : <Checkbox key={o.value} name={name} checked={picks.value.includes(o.value)} onChange={(e: Event & { currentTarget: HTMLInputElement }) => toggle(o.value, e.currentTarget.checked)}>{o.label}</Checkbox>
+            ))}
+            {picks.value.includes(other) && <Input label="Your answer" value={free.value} onInput={e => (free.value = e.currentTarget.value)} />}
+          </fieldset>
+          <div>
+            <Button size="sm" type="submit" disabled={question.closed}>Continue</Button> <small>{question.closed ? 'The run stopped before this was answered.' : 'Waiting for you'}</small>
+          </div>
+        </form>
+  ))))
+  return <>{view.value}</>
+}

package/src/agent/Reasoning.tsx

@@ -0,0 +1,19 @@
+import { RightIcon } from '@weft-js/warp-icons'
+import { derived } from '@weft-js/core'
+import { Shimmer } from './Shimmer'
+import '../styles'
+import '@weft-js/warp-core/styles/app/reasoning.css'
+
+/** Reasoning (07 §1.2): a native details. "Thinking…" while it streams, open; it folds itself and keeps the duration. */
+export function Reasoning({ text, streaming, seconds }: { text: string; streaming?: boolean | undefined; seconds?: number | undefined }) {
+  const label = derived(() => (seconds !== undefined ? `Thought for ${seconds} s` : 'Thought'))
+  return (
+    <details data-scope="reasoning" data-state={streaming ? 'streaming' : 'done'} open={!!streaming}>
+      <summary>
+        <RightIcon data-part="chev" />
+        {streaming ? <Shimmer>Thinking…</Shimmer> : <span>{label.value}</span>}
+      </summary>
+      <div data-part="body">{text}</div>
+    </details>
+  )
+}

package/src/agent/Shimmer.tsx

@@ -0,0 +1,7 @@
+import '../styles'
+import '@weft-js/warp-core/styles/app/shimmer.css'
+
+/** Placeholder text with a light passing over it (07 §1.3); static under reduced motion. */
+export function Shimmer({ children, ...rest }: { children?: unknown; [attr: string]: unknown }) {
+  return <span data-scope="shimmer" {...rest}>{children}</span>
+}

package/src/agent/Sources.tsx

@@ -0,0 +1,23 @@
+import type { AgentSource } from '@weft-js/warp-core'
+import { derived } from '@weft-js/core'
+import { Sweep, useSweep } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/app/sources.css'
+
+/** Sources (07 §1.1): numbered cards, the same numbers as the cites. `base` ties them to their Cite hrefs. */
+export function Sources({ items, base }: { items: AgentSource[]; base: string }) {
+  useSweep()
+  const rows = derived(() => items.map((s, i) => ({ s, n: i + 1, id: `${base}-s${i + 1}` })))
+  return (
+    <div data-scope="sources" role="group" aria-label="Sources">
+      {rows.value.map(r => (
+        <a key={r.n} id={r.id} href={r.s.url ?? `#${r.id}`} data-sweep="">
+          <Sweep />
+          <i>{r.n}</i>
+          <b>{r.s.title}</b>
+          {r.s.path !== undefined && <small>{r.s.path}</small>}
+        </a>
+      ))}
+    </div>
+  )
+}