@weft-js/warp 0.0.0-stage → 0.1.0

package/src/agent/SpeechInput.tsx

@@ -0,0 +1,102 @@
+import { MicIcon } from '@weft-js/warp-icons'
+import { announce, dictation, formatClock, listMics, speechWave, type DictationEngine, type DictationEvents, type DictationState } from '@weft-js/warp-core'
+import { derived, onCleanup, onMount, state, untrack } from '@weft-js/core'
+import { Alert } from '../Alert'
+import { Button } from '../Button'
+import { Select } from '../Select'
+import { use } from '@weft-js/warp-core/weft'
+import { Sweep, useSweep } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/app/speech.css'
+
+const BARS = Array.from({ length: 40 }, (_, i) => i)
+const DEFAULT_MIC = [{ value: '', label: 'Default microphone' }]
+
+/** Props for SpeechInput. */
+export interface SpeechInputProps {
+  /** Writes the transcript somewhere: the Prompt's `control.insert`. Nothing is sent until then. */
+  onInsert?: (text: string) => void
+  mics?: { value: string; label: string }[]
+  /** Replaces the browser's speech recognition. */
+  engine?: (on: DictationEvents) => DictationEngine
+  /** The state and words to start from (a demo, a test). */
+  initial?: { state?: DictationState | undefined; final?: string; interim?: string; seconds?: number } | undefined
+}
+
+/**
+ * SpeechInput + MicSelector (07 §6.4): the mic Select and input level, then Record and Stop on one button. Listening
+ * holds the strip's sweep, moves the wave and counts; words arrive grey while they might change and ink once final. A
+ * blocked mic is a caution Alert with the fix, not a dead button. Uses the browser's speech recognition unless given an `engine`.
+ */
+export function SpeechInput({ onInsert, mics, engine, initial }: SpeechInputProps) {
+  const start = untrack(() => initial)
+  const mode = state<DictationState>(start?.state ?? 'idle')
+  const final = state(start?.final ?? '')
+  const interim = state(start?.interim ?? '')
+  const seconds = state(start?.seconds ?? 0)
+  const level = state(0)
+  const found = state<{ value: string; label: string }[]>(DEFAULT_MIC)
+  const mic = state('')
+  const options = derived(() => mics ?? found.value)
+  const on = derived(() => mode.value === 'listening')
+  const words = derived(() => (final.value + ' ' + interim.value).trim())
+  let root: HTMLElement | undefined
+  let wave: HTMLElement | undefined
+  let live: DictationEngine | undefined
+  let clock: ReturnType<typeof setInterval> | undefined
+  useSweep()
+  use(speechWave, () => wave, () => level.value)
+  const say = (text: string, urgent = false) => announce(root!.ownerDocument, text, urgent)
+  const tick = (run: boolean) => {
+    clearInterval(clock)
+    if (run) { seconds.value = 0; clock = setInterval(() => seconds.value++, 1000) }
+  }
+  const events: DictationEvents = {
+    onState(s) {
+      const was = mode.value
+      mode.value = s
+      tick(s === 'listening')
+      if (s === 'listening') say('Listening.')
+      if (s === 'blocked') say('Microphone blocked. Allow it from the site settings, then try again.', true)
+      if (s === 'unsupported') say('This browser has no dictation.', true)
+      if (s === 'idle' && was === 'listening') { final.value = words.value; interim.value = ''; if (final.value) say('Dictation stopped. Transcript ready.') }
+    },
+    onTranscript(f, i) { final.value = f; interim.value = i },
+    onLevel(v) { level.value = v },
+  }
+  onMount(() => {
+    if (!untrack(() => mics)) void listMics(window).then(list => { if (list.length) found.value = list })
+    onCleanup(() => { clearInterval(clock); live?.stop() })
+  })
+  const toggle = () => {
+    if (on.value) return live?.stop()
+    live ??= (untrack(() => engine) ?? (e => dictation(window, e)))(events)
+    final.value = interim.value = ''
+    live.start(mic.value || undefined)
+  }
+  const clear = () => { if (on.value) live?.stop(); final.value = interim.value = '' }
+  const insert = () => { onInsert?.(words.value); clear() }
+  return (
+    <div ref={n => (root = n)} data-scope="speech" data-state={mode.value}>
+      <Select label="Microphone" options={options.value} onChange={(e: Event) => { const s = e.currentTarget as HTMLSelectElement; mic.value = s.value; say(`Microphone: ${s.selectedOptions[0]!.textContent}`) }} />
+      <div data-part="mic">
+        <span data-part="level" aria-hidden="true" style={`--level:${level.value}`}><i></i><i></i><i></i></span>
+        <span>{mode.value === 'blocked' ? 'Blocked by the browser' : 'Input level'}</span>
+      </div>
+      <div data-part="strip" data-sweep="" data-pin={on.value ? '' : undefined}>
+        <Sweep />
+        <Button data-icon-only="" tone={on.value ? 'critical' : undefined} aria-pressed={on.value ? 'true' : 'false'} label={on.value ? 'Stop dictation' : 'Start dictation'} onClick={toggle}><MicIcon /></Button>
+        <span ref={n => (wave = n)} data-part="wave" data-loop="" aria-hidden="true">{BARS.map(b => <i key={b}></i>)}</span>
+        <span data-part="time" role="timer" aria-label="Recording time" data-numeric="">{formatClock(seconds.value)}</span>
+      </div>
+      <div data-part="transcript" role="log" aria-live="polite" aria-label="Transcript">
+        {words.value ? <>{final.value} <span data-part="interim">{interim.value}</span></> : <small>Press the mic and speak. Nothing is sent until you insert it.</small>}
+      </div>
+      <div>
+        <Button size="sm" disabled={!words.value || on.value} onClick={insert}>Insert into message</Button> <Button emphasis="ghost" tone="neutral" size="sm" onClick={clear}>Clear</Button>
+      </div>
+      {mode.value === 'blocked' && <Alert tone="caution" title="The browser is blocking the microphone">Click the lock in the address bar, allow Microphone, then press the mic again. Typing still works.</Alert>}
+      {mode.value === 'unsupported' && <Alert tone="info" title="This browser has no dictation">Typing still works.</Alert>}
+    </div>
+  )
+}

package/src/agent/Suggestions.tsx

@@ -0,0 +1,22 @@
+import { Sweep, useSweep } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/app/suggestions.css'
+
+/** A prompt offered as a starting point. */
+export type Suggestion = { id?: string; title: string; description?: string | undefined }
+
+/** Starter prompts (sweep cards) on an empty conversation, chips after a turn (07 §1.3). Picking one sends it. */
+export function Suggestions({ items, variant, onPick, ...rest }: { items: Suggestion[]; variant?: 'cards' | 'chips' | undefined; onPick?: (s: Suggestion) => void; [attr: string]: unknown }) {
+  useSweep()
+  return (
+    <div data-scope="suggestions" data-variant={variant === 'chips' ? 'chips' : undefined} {...rest}>
+      {items.map(s => (
+        <button key={s.id ?? s.title} type="button" data-sweep="" onClick={() => onPick?.(s)}>
+          <Sweep />
+          <span>{s.title}</span>
+          {s.description !== undefined && <small>{s.description}</small>}
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/agent/ToolCall.tsx

@@ -0,0 +1,91 @@
+import { AlertIcon, CheckIcon, RightIcon, XIcon } from '@weft-js/warp-icons'
+import { announce, argsDiff, installSweep, toolStatus, uid, type AgentTool } from '@weft-js/warp-core'
+import { derived, onMount, state, untrack, watch } from '@weft-js/core'
+import { Button } from '../Button'
+import { Checkbox } from '../Choice'
+import { Sweep } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/components/spinner.css'
+import '@weft-js/warp-core/styles/app/tool-call.css'
+
+/** Props for ToolCall. */
+export interface ToolCallProps {
+  call: AgentTool
+  /** Called with the arguments as edited, and whether "always allow" is ticked. Approval never auto-runs. */
+  onApprove?: (args: string, always: boolean) => void
+  /** Called when the call is denied. */
+  onDeny?: () => void
+  /** The "always allow" line, scoped to tool and resource: "Always allow edits in src/calendar". */
+  alwaysAllow?: string | undefined
+  /** Was there on load: takes no focus and announces nothing. */
+  quiet?: boolean | undefined
+}
+
+/**
+ * ToolCall (07 §1.2, §1.6): running carries a light on its bottom edge, and every other state is an icon plus words.
+ * Approval opens the card with editable arguments and a diff of the edit, takes focus and announces assertively. The
+ * summary reads with its state ("run_tests, failed, exit 1"); settling confirms one sweep.
+ */
+export function ToolCall({ call, onApprove, onDeny, alwaysAllow, quiet }: ToolCallProps) {
+  const id = uid('tool')
+  const meta = derived(() => toolStatus(call))
+  const st = derived(() => call.state)
+  const args = state(untrack(() => call.args))
+  const always = state(false)
+  const diff = derived(() => argsDiff(call.args, args.value).join('\n'))
+  let frame: HTMLElement | undefined
+  let head: HTMLElement | undefined
+  let ok: HTMLElement | undefined
+  onMount(() => {
+    const asked = () => queueMicrotask(() => {
+      ok?.focus({ preventScroll: true })
+      if (frame) announce(frame.ownerDocument, `The assistant wants to run ${untrack(() => call.name)}. Approve or deny.`, true)
+    })
+    watch(() => st.value, (s, prev) => {
+      if (s === 'approval') { args.value = untrack(() => call.args); if (prev !== undefined || !untrack(() => quiet)) asked() }
+      if (prev !== undefined && s === 'done') {
+        installSweep().confirm(frame)
+        announce(frame!.ownerDocument, `${untrack(() => call.name)} finished.`)
+      }
+    })
+  })
+  const leave = (then: () => void) => { head?.focus({ preventScroll: true }); then() }
+  return (
+    <div ref={n => (frame = n)} data-part="tool-frame" data-sweep="">
+      <Sweep />
+      <details data-scope="tool-call" data-state={st.value} open={st.value === 'approval'}>
+        <summary ref={n => (head = n)}>
+          <span>
+            {st.value === 'running' && <span data-scope="spinner" style="--_size:13px;color:var(--warp-color-accent-text)"></span>}
+            {st.value === 'done' && <CheckIcon style="color:var(--warp-color-positive-text)" />}
+            {st.value === 'approval' && <AlertIcon style="color:var(--warp-color-caution-text)" />}
+            {(st.value === 'failed' || st.value === 'denied') && <XIcon style="color:var(--warp-color-critical-text)" />}
+          </span>
+          <span data-part="name">{call.name}</span>
+          <span data-part="sr-only">{meta.value.word}</span>
+          <span data-part="arg" aria-hidden="true">{call.args}</span>
+          <span data-part="dur" data-numeric="">{meta.value.status}</span>
+          <RightIcon data-part="chev" />
+        </summary>
+        <div data-part="io">
+          <span>Input</span>
+          <pre>{call.args}</pre>
+          <span>Output</span>
+          <pre>{call.output ?? (st.value === 'approval' ? 'Waiting for approval' : st.value === 'denied' ? 'Denied. Nothing was changed.' : '…')}</pre>
+        </div>
+        {st.value === 'approval' && (
+          <div data-part="approve" role="group" aria-label={`Approve ${call.name}`}>
+            <span data-part="eyebrow" id={`${id}-a`}>Arguments · editable</span>
+            <textarea aria-labelledby={`${id}-a`} spellcheck="false" value={args.value} onInput={e => (args.value = (e.currentTarget).value)}></textarea>
+            {diff.value && <section data-part="io"><span>Your edit</span><pre>{diff.value}</pre></section>}
+            <div>
+              <Button size="sm" ref={n => (ok = n)} onClick={() => leave(() => onApprove?.(args.value, always.value))}><CheckIcon />Approve</Button>
+              <Button emphasis="outline" tone="neutral" size="sm" onClick={() => leave(() => onDeny?.())}>Deny</Button>
+              {alwaysAllow !== undefined && <Checkbox checked={always.value} onChange={(e: Event & { currentTarget: HTMLInputElement }) => (always.value = e.currentTarget.checked)}>{alwaysAllow}</Checkbox>}
+            </div>
+          </div>
+        )}
+      </details>
+    </div>
+  )
+}

package/src/agent/TraceViewer.tsx

@@ -0,0 +1,55 @@
+import { formatSeconds, traceKey, traceRows, traceSummary, type TraceSpan } from '@weft-js/warp-core'
+import { derived, state, untrack } from '@weft-js/core'
+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/trace.css'
+
+/**
+ * TraceViewer (07 §1.3): nested spans on a shared time axis, an APG treegrid. One tab stop; ↑/↓, Home/End move, →/←
+ * expand, collapse and step in and out, Enter toggles. The line above follows the focused span's time, tokens and cost.
+ * Live: pass new `spans`, and rows patch by id.
+ */
+export function TraceViewer({ spans, label = 'Spans' }: { spans: TraceSpan[]; label?: string | undefined }) {
+  const shut = state<ReadonlySet<string>>(new Set())
+  const rows = derived(() => traceRows(spans, shut.value))
+  const at = state<string | undefined>(undefined)
+  const stop = derived(() => rows.value.find(r => r.id === at.value) ?? rows.value[0])
+  let grid: HTMLElement | undefined
+  const toggle = (id: string) => {
+    const next = new Set(shut.value)
+    if (!next.delete(id)) next.add(id)
+    shut.value = next
+  }
+  const onKey = (e: KeyboardEvent) => {
+    const list = rows.value
+    const i = list.findIndex(r => r.id === stop.value?.id)
+    if (i < 0) return
+    const rtl = getComputedStyle(e.currentTarget as Element).direction === 'rtl'
+    const go = traceKey(e.key, list, i, rtl)
+    if (!go) return
+    e.preventDefault()
+    if (go.toggle) toggle(go.toggle)
+    if (go.focus) {
+      at.value = go.focus
+      queueMicrotask(() => grid?.querySelector<HTMLElement>(`[data-id="${untrack(() => at.value)}"]`)?.focus())
+    }
+  }
+  return (
+    <div style="display:grid;gap:14px">
+      <div style="display:flex;justify-content:space-between;gap:8px">
+        <span data-part="eyebrow">{label}</span>
+        <small data-numeric="">{stop.value ? traceSummary(stop.value) : ''}</small>
+      </div>
+      <div ref={n => (grid = n)} data-scope="trace" role="treegrid" aria-label={label} aria-readonly="true" onKeyDown={onKey}>
+        {rows.value.map(r => (
+          <div key={r.id} data-id={r.id} role="row" aria-level={r.level} aria-posinset={r.pos} aria-setsize={r.size} aria-expanded={r.branch ? (r.open ? 'true' : 'false') : undefined} aria-label={`${r.name}, ${traceSummary(r)}`} tabindex={r.id === stop.value?.id ? '0' : '-1'} onFocus={() => (at.value = r.id)} onClick={() => r.branch && toggle(r.id)}>
+            <span role="gridcell" style={`--_d:${r.level - 1}`}>{r.branch ? (r.open ? '▾ ' : '▸ ') : ''}{r.name}</span>
+            <i role="gridcell" style={`--_x:${r.x};--_w:${r.w};--_c:var(--warp-color-data-${r.color})`}></i>
+            <em role="gridcell" data-numeric="">{formatSeconds(r.ms)}</em>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/agent/bits.tsx

@@ -0,0 +1,40 @@
+// What the agent pack's components share: glyphs from the app specimen, the sweep's two parts, an icon button, a value
+// held in a State or a plain prop, and the thin progress bar.
+import { type IconComponent } from '@weft-js/warp-icons'
+import { installSweep } from '@weft-js/warp-core'
+import { Box, onMount, state, untrack, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/base.css'
+import '@weft-js/warp-core/styles/components/progress.css'
+
+/** The two sweep parts a [data-sweep] host carries. */
+export const Sweep = () => <><span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span></>
+
+/** Follow the sweep machine; for hosts this pack draws by hand. */
+export const useSweep = () => onMount(() => { installSweep() })
+
+/** A small ghost icon button, named by `label`. */
+export function IconButton({ icon, label, ...rest }: { icon: IconComponent; label: string; [attr: string]: unknown }) {
+  return <Button emphasis="ghost" tone="neutral" size="sm" label={label} data-icon-only="" {...rest}>{icon({})}</Button>
+}
+
+/** A thin determinate bar; `value` is 0 to 1. */
+export function Bar({ label, value }: { label: string; value: number }) {
+  return <div data-scope="progress" data-part="root" role="progressbar" aria-label={label} aria-valuemin="0" aria-valuemax="100" aria-valuenow={Math.round(value * 100)} style={`--_v:${value}`}><div data-part="track"><div data-part="range"></div></div></div>
+}
+
+/** One read and write over a State to bind or a plain value with its change callback. */
+export function held<T>(value: () => State<T> | T | undefined, fallback: T, onChange?: () => ((v: T) => void) | undefined) {
+  const box = (v: unknown): v is State<T> => v instanceof Box
+  const own = state<T>(untrack(() => { const v = value(); return box(v) || v === undefined ? fallback : v }))
+  return {
+    get value(): T { const v = value(); return box(v) ? v.value : v !== undefined ? v : own.value },
+    set(next: T) {
+      const v = untrack(value)
+      if (box(v)) v.value = next
+      else own.value = next
+      untrack(onChange ?? (() => undefined))?.(next)
+    },
+  }
+}

package/src/agent/index.ts

@@ -0,0 +1,22 @@
+// The agent pack: see docs/design/warp. One file per component family; each imports only its own CSS.
+export { Conversation } from './Conversation'
+export { Message as UserMessage } from './Message'
+export { Assistant, type AssistantProps } from './Assistant'
+export { Reasoning } from './Reasoning'
+export { ToolCall, type ToolCallProps } from './ToolCall'
+export { Cite } from './Cite'
+export { Sources } from './Sources'
+export { Prose } from './Prose'
+export { AgentPlan, type QueuedMessage } from './AgentPlan'
+export { Prompt, type PromptProps, type PromptTool, type PromptFile, type PromptSuggestion, type PromptControl } from './Prompt'
+export { ModelPicker, type ModelOption } from './ModelPicker'
+export { MessageActions, BranchSwitcher, type MessageActionsProps, type Feedback } from './Actions'
+export { Suggestions, type Suggestion } from './Suggestions'
+export { Question } from './Question'
+export { Checkpoint } from './Checkpoint'
+export { Shimmer } from './Shimmer'
+export { ContextMeter, type ContextUse } from './ContextMeter'
+export { TraceViewer } from './TraceViewer'
+export { ArtifactPanel, type ArtifactVersion } from './ArtifactPanel'
+export { SpeechInput, type SpeechInputProps } from './SpeechInput'
+export { foldAnswer, type Answer, type AgentEvent, type AgentTool, type AgentSource, type AgentQuestion, type PlanStep, type TraceSpan } from '@weft-js/warp-core'

package/src/bind.ts

@@ -0,0 +1,42 @@
+import type { ChangeReason } from '@weft-js/warp-core'
+import { Box, state, untrack, type State } from '@weft-js/core'
+
+/** 04 §1.1: a State to bind, or a plain value (controlled) or defaultValue; `onValueChange` hears every change. */
+export interface Bindable<T> {
+  value?: State<T> | T
+  defaultValue?: T
+  /** Called with each new value, and whether a pointer, a key or code made the change. */
+  onValueChange?: (v: T, reason: ChangeReason) => void
+}
+/** An overlay's open state, held by the caller or by the component. */
+export interface Openable {
+  open?: State<boolean> | boolean
+  /** Starts open, when the component keeps its own open state. */
+  defaultOpen?: boolean
+  /** Called with `true` when it opens and `false` when it closes. */
+  onOpenChange?: (o: boolean) => void
+}
+
+const isState = (v: unknown): v is State<unknown> => v instanceof Box
+
+/** One read/write over the three ways a value can be held. */
+export function bindable<T>(value: () => State<T> | T | undefined, initial: () => T | undefined, fallback: T, onChange?: () => ((v: T, r: ChangeReason) => void) | undefined) {
+  const own = state<T>(untrack(() => { const v = value(); return (isState(v) ? undefined : (v)) ?? initial() ?? fallback }))
+  const read = (): T => {
+    const v = value()
+    return isState(v) ? v.value : v !== undefined ? (v) : own.value
+  }
+  const first = untrack(read)
+  const set = (next: T, reason: ChangeReason = 'programmatic') => {
+    const v = untrack(value)
+    if (isState(v)) v.value = next
+    else own.value = next
+    untrack(onChange ?? (() => undefined))?.(next, reason)
+  }
+  return {
+    get value(): T { return read() },
+    set,
+    /** Back to the value it started with: a form's reset. */
+    reset: () => { set(first) },
+  }
+}

package/src/collab/AutoTrack.tsx

@@ -0,0 +1,42 @@
+import { announce, autoTrack, firstName, type Peer } from '@weft-js/warp-core'
+import { derived, state } from '@weft-js/core'
+import { Button } from '../Button'
+import { Switch } from '../Choice'
+import { use } from '@weft-js/warp-core/weft'
+import { PeerAvatar } from './peer'
+import '../styles'
+import '@weft-js/warp-core/styles/app/tokens.css'
+import '@weft-js/warp-core/styles/app/auto-track.css'
+
+type Track = 'following' | 'paused' | 'off'
+
+/**
+ * MultiplayerAutoTrack (07 §6.4): a Switch, a status line, and a scroll region that follows the presenter's section
+ * (`[data-section]` children). A manual scroll pauses it with Resume; presenter changes are shown, not announced.
+ */
+export function AutoTrack({ presenter, section, label, height = 180, children }: { presenter: Peer | null; section?: string | undefined; label: string; height?: number; children?: unknown }) {
+  const mode = state<Track>('following')
+  const name = derived(() => (presenter ? firstName(presenter.name) : ''))
+  let region: HTMLDivElement | undefined
+  use(autoTrack, () => region, () => ({
+    following: mode.value === 'following',
+    section,
+    onPause() {
+      mode.value = 'paused'
+      announce(region!.ownerDocument, 'Auto-track paused. Resume to follow the presenter again.')
+    },
+  }))
+  return (
+    <div>
+      <Switch checked={mode.value !== 'off'} onChange={(e: Event) => (mode.value = (e.currentTarget as HTMLInputElement).checked ? 'following' : 'off')}>Follow whoever presents</Switch>
+      <div>
+        <span data-scope="auto-track" data-state={mode.value} role="status">
+          {mode.value === 'following' && presenter && <PeerAvatar peer={presenter} size="sm" />}
+          {mode.value === 'following' ? (presenter ? `Following ${name.value} · presenting` : 'Nobody is presenting') : mode.value === 'paused' ? 'Paused: you scrolled' : 'Off'}
+        </span>
+        {mode.value === 'paused' && <Button emphasis="outline" tone="neutral" size="sm" onClick={() => { mode.value = 'following'; announce(region!.ownerDocument, `Following ${presenter?.name ?? 'the presenter'}`) }}>Resume</Button>}
+      </div>
+      <div ref={n => (region = n)} tabindex="0" role="region" aria-label={label} style={`block-size:${height}px;overflow:auto`}>{children}</div>
+    </div>
+  )
+}

package/src/collab/Comments.tsx

@@ -0,0 +1,94 @@
+import { CheckIcon } from '@weft-js/warp-icons'
+import { announce, arrivalTracker, isSheet, uid, type Peer } from '@weft-js/warp-core'
+import { derived, onMount, state, untrack, watch, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import { Drawer } from '../Drawer'
+import { PeerAvatar, read, SWEEP, type Live } from './peer'
+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/comment-thread.css'
+import '@weft-js/warp-core/styles/app/comment-anchor.css'
+
+/** One comment in a thread. */
+export interface Comment { id: string; author: Peer; time: string; text: string }
+/** A comment thread and whether it's resolved. */
+export interface CommentThreadData { id: string; comments: Comment[]; resolved?: boolean }
+
+/**
+ * A comment thread (07 §6.2): an article of comments, a reply field and Resolve; resolved collapses to one line with
+ * Reopen. A new comment arrives with `data-arrive`; `active` raises it and holds its sweep.
+ */
+export function CommentThread({ thread, active, onReply, onResolve }: { thread: Live<CommentThreadData>; active?: boolean; onReply?: (text: string) => void; onResolve?: (resolved: boolean) => void }) {
+  const id = uid('reply')
+  const data = derived(() => read(thread))
+  const own = state(untrack(() => !!data.value.resolved))
+  const resolved = derived(() => own.value)
+  const mark = arrivalTracker()
+  const fresh = derived(() => mark(data.value.comments.map(c => c.id)))
+  const first = derived(() => data.value.comments[0])
+  let root: HTMLElement | undefined
+  const flip = (on: boolean) => {
+    own.value = on
+    onResolve?.(on)
+    if (root) announce(root.ownerDocument, on ? 'Comment resolved' : 'Comment reopened')
+  }
+  const reply = (e: KeyboardEvent) => {
+    const el = e.currentTarget as HTMLInputElement
+    if (e.key !== 'Enter' || !el.value.trim()) return
+    e.preventDefault()
+    onReply?.(el.value.trim())
+    el.value = ''
+  }
+  return (
+    <article ref={n => (root = n)} data-scope="comment-thread" data-c={data.value.id} data-sweep="surface" data-active={active ? '' : undefined} data-pin={active ? '' : undefined} data-resolved={resolved.value ? '' : undefined} aria-label={`Comment from ${first.value?.author.name}`}>
+      <SWEEP />
+      {resolved.value
+        ? <div data-part="reply"><span>{first.value?.author.name}: {first.value?.text}</span><Button emphasis="ghost" tone="neutral" size="sm" onClick={() => flip(false)}>Reopen</Button></div>
+        : <>
+            {data.value.comments.map(c => (
+              <div key={c.id} data-part="comment" data-arrive={fresh.value.includes(c.id) ? '' : undefined}>
+                <PeerAvatar peer={c.author} size="sm" /><b>{c.author.name}</b><time>{c.time}</time><p>{c.text}</p>
+              </div>
+            ))}
+            <div data-part="reply">
+              <label data-part="sr-only" for={id}>Reply to {first.value?.author.name}</label>
+              <input id={id} placeholder="Reply…" onKeyDown={reply} />
+              <Button emphasis="ghost" tone="neutral" size="sm" onClick={() => flip(true)}><CheckIcon /> Resolve</Button>
+            </div>
+          </>}
+    </article>
+  )
+}
+
+/** The highlighted range a thread hangs from (07 §6.2): activates its thread on press and on focus. */
+export function CommentAnchor({ thread, active, children }: { thread: string; active: State<string | null>; children?: unknown }) {
+  const on = () => (active.value = thread)
+  return <span data-scope="comment-anchor" data-c={thread} data-active={active.value === thread ? '' : undefined} role="button" tabindex="0" aria-pressed={active.value === thread ? 'true' : 'false'} onClick={on} onFocus={on} onKeyDown={(e: KeyboardEvent) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); on() } }}>{children}</span>
+}
+
+/**
+ * The margin rail of anchored threads (07 §6.2): a complementary landmark of articles. On a phone the rail gives way
+ * to a bottom Sheet holding the active thread.
+ */
+export function CommentRail({ threads, active, onReply, onResolve, label = 'Comments' }: { threads: Live<CommentThreadData[]>; active: State<string | null>; onReply?: (thread: string, text: string) => void; onResolve?: (thread: string, resolved: boolean) => void; label?: string | undefined }) {
+  const list = derived(() => read(threads))
+  const phone = state(false)
+  let rail: HTMLElement | undefined
+  const sheet = state(false)
+  onMount(() => {
+    queueMicrotask(() => { if (rail && isSheet(rail)) phone.value = true })
+    watch(() => active.value, a => { if (phone.value) sheet.value = a !== null })
+    watch(() => sheet.value, on => { if (!on) active.value = null })
+  })
+  const open = derived(() => list.value.find(t => t.id === active.value))
+  const body = (t: CommentThreadData) => <CommentThread thread={t} active={active.value === t.id} onReply={x => onReply?.(t.id, x)} onResolve={r => onResolve?.(t.id, r)} />
+  return (
+    <>
+      <aside ref={n => (rail = n)} aria-label={label} hidden={phone.value}>
+        {!phone.value && list.value.map(t => <div key={t.id}>{body(t)}</div>)}
+      </aside>
+      {phone.value && <Drawer open={sheet} title={label} side="bottom">{open.value ? body(open.value) : null}</Drawer>}
+    </>
+  )
+}