@weft-js/warp 0.0.0-stage → 0.1.0

package/src/admin/Settings.tsx

@@ -0,0 +1,76 @@
+import { untrack } from '@weft-js/core'
+import { uid } from '@weft-js/warp-core'
+import { Glyph } from '../parts'
+import '../styles'
+import '@weft-js/warp-core/styles/flows/tokens.css'
+import '@weft-js/warp-core/styles/flows/base.css'
+import '@weft-js/warp-core/styles/rich/helpers.css'
+import '@weft-js/warp-core/styles/layout/tokens.css'
+import '@weft-js/warp-core/styles/layout/row.css'
+import '@weft-js/warp-core/styles/layout/stack.css'
+import '@weft-js/warp-core/styles/flows/settings.css'
+import '@weft-js/warp-core/styles/flows/settings-section.css'
+import '@weft-js/warp-core/styles/flows/setting-row.css'
+
+/** One link of the settings nav. */
+export type SettingsNavItem = { id: string; label: string; glyph?: string; tone?: 'critical' | undefined }
+
+/**
+ * The settings frame (09 §4.1): a TabNav-like strip that becomes a sticky column at 760px of its own width, and a form
+ * holding the sections. A nav press scrolls to the section and moves focus to its heading.
+ */
+export function SettingsLayout({ label = 'Settings sections', sections, current, onNavigate, children }: { label?: string | undefined; sections: SettingsNavItem[]; current: string; onNavigate?: (id: string) => void; children: unknown }) {
+  const go = (e: MouseEvent, id: string) => {
+    e.preventDefault()
+    onNavigate?.(id)
+    const doc = (e.currentTarget as Element).ownerDocument
+    const sec = doc.getElementById(id)
+    const reduce = doc.defaultView?.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+    sec?.scrollIntoView?.({ behavior: reduce ? 'auto' : 'smooth', block: 'start' })
+    sec?.querySelector<HTMLElement>('header :is(h3, h4)')?.focus({ preventScroll: true })
+  }
+  return (
+    <div data-scope="settings">
+      <div data-part="layout">
+        <nav data-part="nav" aria-label={label}>
+          {sections.map(s => (
+            <a key={s.id} href={`#${s.id}`} data-tone={s.tone} aria-current={s.id === current ? 'true' : undefined} onClick={(e: MouseEvent) => go(e, s.id)}>
+              {s.glyph && <Glyph d={s.glyph} />}{s.label}
+            </a>
+          ))}
+        </nav>
+        <form data-part="content" novalidate>{children}</form>
+      </div>
+    </div>
+  )
+}
+
+/** A heading, one line, then one bordered group of rows (09 §4.1). `tone="critical"` is the danger zone's border. */
+export function SettingsSection({ id, title, description, tone, as: heading = 'h3', children }: { id: string; title: unknown; description?: unknown; tone?: 'critical' | undefined; as?: 'h3' | 'h4' | undefined; children: unknown }) {
+  return (
+    <section data-scope="settings-section" id={id} data-tone={tone} aria-labelledby={`${id}-h`}>
+      <header>
+        {heading === 'h4' ? <h4 id={`${id}-h`} tabindex="-1">{title}</h4> : <h3 id={`${id}-h`} tabindex="-1">{title}</h3>}
+        {description !== undefined && <p>{description}</p>}
+      </header>
+      <div data-part="group">{children}</div>
+    </section>
+  )
+}
+
+/**
+ * Label and help at the inline-start, the control at the inline-end, stacking under 520px (09 §4.1). `children` may be
+ * a function of the label's and help's ids, so a Switch can be labelled by them instead of repeating the words.
+ */
+export function SettingRow({ title, description, layout, children }: { title?: unknown; description?: unknown; layout?: 'stack'; children: unknown }) {
+  const id = uid('row')
+  const body = () => (typeof children === 'function' ? children({ label: `${id}-l`, description: `${id}-d` }) : children)
+  const stacked = untrack(() => title === undefined)
+  if (stacked) return <div data-scope="setting-row" data-layout={layout}>{body()}</div>
+  return (
+    <div data-scope="setting-row" data-layout={layout}>
+      <div><b id={`${id}-l`}>{title}</b><p id={`${id}-d`}>{description}</p></div>
+      <div data-part="control">{body()}</div>
+    </div>
+  )
+}

package/src/admin/StepBar.tsx

@@ -0,0 +1,35 @@
+import { CheckIcon } from '@weft-js/warp-icons'
+import { derived } from '@weft-js/core'
+import '../parts'
+import '@weft-js/warp-core/styles/rich/helpers.css'
+import '@weft-js/warp-core/styles/layout/tokens.css'
+import '@weft-js/warp-core/styles/layout/row.css'
+import '@weft-js/warp-core/styles/layout/stack.css'
+import '@weft-js/warp-core/styles/components/progress.css'
+
+/**
+ * Steps (05 §4) with the compact form 09 §6.2 asks for: steps.css hides the list under 520px and shows
+ * `[data-part="compact"]`, "Payment, step 4 of 5" over a bar, which parts' Steps doesn't render.
+ */
+export function StepBar({ label, steps, current, error }: { label: string; steps: { id: string; title: string }[]; current: number; error?: number }) {
+  const at = derived(() => Math.min(current, steps.length - 1))
+  return (
+    <nav data-scope="steps" aria-label={label}>
+      <ol>
+        {steps.map((s, i) => (
+          <li key={s.id} data-part="item" data-state={i === error ? 'error' : i < current ? 'complete' : i === current ? 'current' : undefined} aria-current={i === current ? 'step' : undefined}>
+            <span data-part="indicator"><CheckIcon /></span>
+            <span data-part="title">{s.title}</span>
+          </li>
+        ))}
+      </ol>
+      <div data-part="compact">
+        <div data-scope="row" data-justify="between">
+          <b data-part="compact-title">{steps[at.value]!.title}</b>
+          <span class="muted">Step {at.value + 1} of {steps.length}</span>
+        </div>
+        <div data-scope="progress" data-part="root" style={`--_v:${(at.value + 1) / steps.length}`}><div data-part="track"><div data-part="range"></div></div></div>
+      </div>
+    </nav>
+  )
+}

package/src/admin/TagsInput.tsx

@@ -0,0 +1,79 @@
+import { addTags, announce } from '@weft-js/warp-core'
+import { derived, state, type State } from '@weft-js/core'
+import { Field } from '../Field'
+import { Tag } from '../Tag'
+import { afterFlush } from './atoms'
+import '@weft-js/warp-core/styles/inputs/choice.css'
+
+/** Props for TagsInput. */
+export interface TagsInputProps {
+  label: string
+  hint?: unknown
+  error?: unknown
+  value: State<string[]>
+  /** A false tag stays, critical: the field's error says why, once for all of them. */
+  valid?: (tag: string) => boolean
+  /** Called when the tags change, to clear a stale error. */
+  onEdit?: (() => void) | undefined
+  /** Enter with nothing typed: the form's submit. */
+  onSubmit?: () => void
+  /** Focuses the field when it mounts. */
+  autofocus?: boolean
+  [attr: string]: unknown
+}
+
+/**
+ * TagsInput (09 §4.2): Enter, comma or a pasted list adds tags; an invalid one stays as a critical tag; Backspace
+ * highlights the last tag, then removes it. warp had none, so it lives here. Changes are announced politely.
+ */
+export function TagsInput({ label, hint, error, value, valid, onEdit, onSubmit, ...rest }: TagsInputProps) {
+  const draft = state('')
+  const armed = state(false)
+  let host: HTMLElement | undefined
+  const say = (text: string) => { if (host) announce(host.ownerDocument, text) }
+  const add = (raw: string) => {
+    const { list, added } = addTags(value.value, raw)
+    draft.value = ''
+    if (!added.length) return
+    value.value = list
+    armed.value = false
+    say(`Added ${added.join(', ')}. ${list.length} in total.`)
+    onEdit?.()
+  }
+  const drop = (tag: string) => {
+    value.value = value.value.filter(t => t !== tag)
+    armed.value = false
+    say(`Removed ${tag}.`)
+    onEdit?.()
+    afterFlush(() => host?.focus())
+  }
+  const key = (e: KeyboardEvent) => {
+    const text = draft.value.trim()
+    if ((e.key === 'Enter' || e.key === ',') && text) { e.preventDefault(); add(text) }
+    else if (e.key === 'Enter') { e.preventDefault(); onSubmit?.() }
+    else if (e.key === 'Backspace' && !draft.value && value.value.length) {
+      if (armed.value) drop(value.value[value.value.length - 1]!)
+      else armed.value = true
+    } else if (e.key !== 'Backspace') armed.value = false
+  }
+  const paste = (e: ClipboardEvent) => {
+    const t = e.clipboardData?.getData('text') ?? ''
+    if (/[\s,;]/.test(t.trim())) { e.preventDefault(); add(`${draft.value} ${t}`) }
+  }
+  const last = derived(() => value.value[value.value.length - 1])
+  return (
+    <Field
+      wrap
+      label={label}
+      hint={hint}
+      error={error ?? ''}
+      filled={value.value.length > 0 || !!draft.value}
+      control={p => (
+        <>
+          {value.value.map(t => <Tag key={t} label={t} tone={valid && !valid(t) ? 'critical' : undefined} data-highlighted={armed.value && t === last.value ? '' : undefined} onRemove={() => drop(t)}>{t}</Tag>)}
+          <input ref={n => (host = n)} data-part="input" id={p.id} placeholder=" " autocomplete="off" enterkeyhint="enter" aria-describedby={p.describedby} aria-invalid={p.invalid ? 'true' : undefined} value={draft.value} onInput={(e: Event) => { draft.value = (e.currentTarget as HTMLInputElement).value; armed.value = false }} onKeyDown={key} onPaste={paste} onBlur={() => { if (draft.value.trim()) add(draft.value) }} {...rest} />
+        </>
+      )}
+    />
+  )
+}

package/src/admin/atoms.tsx

@@ -0,0 +1,33 @@
+// Small pieces the admin pack shares. Internal: not exported from the barrel.
+import { flush, type State, state, untrack, watch } from '@weft-js/core'
+import { CompactSelect } from '../Select'
+import '../fields'
+import '@weft-js/warp-core/styles/inputs/choice.css'
+import '@weft-js/warp-core/styles/inputs/text.css'
+
+/** A value given plainly or as a State box. */
+export const read = <T,>(v: T | State<T>): T => (v !== null && typeof v === 'object' && !Array.isArray(v) && 'value' in (v as object) ? (v as State<T>).value : v as T)
+
+/** The sweep's two spans, in every swept host. */
+export const Sweep = () => <><span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span></>
+
+/** Runs after the DOM has caught up: a focus move onto something this handler just rendered. */
+export const afterFlush = (fn: () => void) => queueMicrotask(() => { flush(); fn() })
+
+/** Goes true with `open` and stays: a closed overlay carries nothing until first opened, and keeps its close animation. */
+export function latch(open: State<boolean>) {
+  const on = state(untrack(() => open.value))
+  watch(() => open.value, v => { if (v) on.value = true })
+  return on
+}
+
+/** A close that can refuse, for dialogs that mustn't go yet. Modal only reads and writes `.value`. */
+export const guarded = (open: State<boolean>, may: () => boolean) => ({
+  get value() { return open.value },
+  set value(v: boolean) { if (v || may()) open.value = v },
+}) as State<boolean>
+
+/** The compact select in a table cell (specimen `roleSel`). */
+export const InlineSelect = ({ label, value, options, describedby, onValueChange }: { label: string; value: string; options: { value: string; label: string }[]; describedby?: string | undefined; onValueChange: (value: string) => void }) => (
+  <CompactSelect label={label} value={value} options={options} describedby={describedby} onValueChange={onValueChange} />
+)

package/src/admin/index.ts

@@ -0,0 +1,16 @@
+// The admin pack: see docs/design/warp. One file per component family; each imports only its own CSS.
+export { SettingsLayout, SettingsSection, SettingRow, type SettingsNavItem } from './Settings'
+export { SaveBar, type SaveBarProps, type FieldErrors } from './SaveBar'
+export { DangerZone, ConfirmDialog, TypeToConfirm, type ConfirmDialogProps, type TypeToConfirmProps } from './Danger'
+export { MembersTable, SeatsMeter, RolesMatrix, type Member, type Invite, type Role, type Permission, type MembersTableProps } from './Members'
+export { InviteDialog, type InviteDialogProps } from './InviteDialog'
+export { TagsInput, type TagsInputProps } from './TagsInput'
+export { ApiKeys, type ApiKey, type KeyDraft, type ApiKeysProps } from './ApiKeys'
+export { PlanPicker, UsageMeter, UsageMeters, type BillingPlan, type PlanPickerProps, type UsageMeterProps } from './Plans'
+export { Invoices, PaymentMethods, PayFrame, type Invoice, type InvoiceStatus, type PaymentMethod, type PayFrameProps } from './Billing'
+export { AuditLog, type AuditEvent, type AuditLogProps } from './Audit'
+export { IntegrationsGrid, Webhooks, type Integration, type IntegrationState, type IntegrationsGridProps, type Webhook, type WebhooksProps } from './Integrations'
+export { CsvImport, type CsvImportProps } from './CsvImport'
+export { CartDrawer, CartButton, LineItem, type CartDrawerProps } from './Cart'
+export { Checkout, type CheckoutProps, type CheckoutStep, type ShippingOption, type Coupon, type OrderDraft, type PlaceOrderResult } from './Checkout'
+export { OrderConfirmation, OrderTracker, type OrderConfirmationProps, type OrderStage } from './Order'

package/src/agent/Actions.tsx

@@ -0,0 +1,85 @@
+import { BranchIcon, CopyIcon, LeftIcon, RefreshIcon, RightIcon, ThumbsDownIcon, ThumbsUpIcon } from '@weft-js/warp-icons'
+import { announce, popover } from '@weft-js/warp-core'
+import { derived, state } from '@weft-js/core'
+import { Badge } from '../Badge'
+import { Button } from '../Button'
+import { use } from '@weft-js/warp-core/weft'
+import { IconButton } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/components/popover.css'
+import '@weft-js/warp-core/styles/app/branch.css'
+
+const say = (e: Event, text: string) => announce((e.currentTarget as Element).ownerDocument, text)
+
+/** BranchSwitcher (07 §1.3): `‹ 2/2 ›`, shown once a turn has more than one version. `index` counts from 0. */
+export function BranchSwitcher({ index, count, onChange }: { index: number; count: number; onChange: (index: number) => void }) {
+  const go = (e: Event, to: number) => { onChange(to); say(e, `Version ${to + 1} of ${count}`) }
+  return (
+    <>
+      {count > 1 && (
+        <span data-scope="branch" role="group" aria-label="Versions">
+          <button type="button" aria-label="Previous version" disabled={index <= 0} onClick={e => go(e, index - 1)}><LeftIcon /></button>
+          <span data-numeric="">{index + 1}/{count}</span>
+          <button type="button" aria-label="Next version" disabled={index >= count - 1} onClick={e => go(e, index + 1)}><RightIcon /></button>
+        </span>
+      )}
+    </>
+  )
+}
+
+/** A reader's verdict on an answer; null until they give one. */
+export type Feedback = 'up' | 'down' | null
+
+/** Props for MessageActions. */
+export interface MessageActionsProps {
+  /** Adds Copy, and is called with the pressed button. Copy the message text here. */
+  onCopy?: ((el: HTMLElement) => void) | undefined
+  /** Called with `up`, `down` or null when thumbs change, and the reason picked for a thumbs down. */
+  onFeedback?: ((value: Feedback, reason?: string) => void) | undefined
+  reasons?: string[] | undefined
+  /** Adds Regenerate: ask for a new answer. */
+  onRegenerate?: (() => void) | undefined
+  /** Adds Branch: start a new conversation from this message. */
+  onBranch?: (() => void) | undefined
+  stopped?: boolean | undefined
+  /** Which of several answers is shown, with arrows between them. */
+  branch?: ({ index: number; count: number; onChange: (index: number) => void }) | undefined
+}
+
+/**
+ * Message actions (07 §1.3): copy, good and bad answer (toggles; bad opens a short reason popover), regenerate, branch
+ * and the switcher. Regenerate, branch and thumbs render only when they have a handler.
+ */
+export function MessageActions({ onCopy, onFeedback, reasons = ['Wrong', 'Too long', 'Missed the point'], onRegenerate, onBranch, stopped, branch }: MessageActionsProps) {
+  const value = state<Feedback>(null)
+  const asking = state(false)
+  const has = derived(() => branch)
+  let bad: HTMLElement | undefined
+  let panel: HTMLElement | undefined
+  use(popover, () => panel, () => ({ open: asking.value, trigger: bad!, side: 'top' as const, onClose: () => (asking.value = false) }))
+  const rate = (e: Event, to: 'up' | 'down') => {
+    const next = value.value === to ? null : to
+    value.value = next
+    onFeedback?.(next)
+    if (next === 'down') asking.value = true
+    else if (next) say(e, 'Thanks for the feedback.')
+  }
+  const because = (e: Event, reason: string) => { onFeedback?.('down', reason); say(e, 'Thanks for the feedback.') }
+  return (
+    <div data-part="actions">
+      {stopped && <Badge tone="neutral">Stopped · kept what arrived</Badge>}
+      {onCopy && <IconButton icon={CopyIcon} label="Copy" onClick={(e: Event) => onCopy(e.currentTarget as HTMLElement)} />}
+      {onFeedback && <IconButton icon={ThumbsUpIcon} label="Good answer" aria-pressed={value.value === 'up' ? 'true' : 'false'} onClick={(e: Event) => rate(e, 'up')} />}
+      {onFeedback && <IconButton icon={ThumbsDownIcon} label="Bad answer" aria-pressed={value.value === 'down' ? 'true' : 'false'} aria-haspopup="dialog" ref={(n: HTMLElement) => (bad = n)} onClick={(e: Event) => rate(e, 'down')} />}
+      {onFeedback && (
+        <div ref={n => (panel = n)} data-scope="popover" data-part="content" role="dialog" popover="manual" aria-label="What went wrong?">
+          <p data-part="title">What went wrong?</p>
+          <div>{reasons.map(r => <Button key={r} emphasis="ghost" tone="neutral" size="sm" data-close-popover="" onClick={(e: Event) => because(e, r)}>{r}</Button>)}</div>
+        </div>
+      )}
+      {onRegenerate && <IconButton icon={RefreshIcon} label="Regenerate" onClick={onRegenerate} />}
+      {onBranch && <IconButton icon={BranchIcon} label="Branch from here" onClick={onBranch} />}
+      {has.value && <BranchSwitcher index={has.value.index} count={has.value.count} onChange={has.value.onChange} />}
+    </div>
+  )
+}

package/src/agent/AgentPlan.tsx

@@ -0,0 +1,49 @@
+import { CheckIcon, ClockIcon, HandIcon, XIcon } from '@weft-js/warp-icons'
+import type { PlanStep } from '@weft-js/warp-core'
+import { derived } from '@weft-js/core'
+import { Bar, IconButton } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/components/spinner.css'
+import '@weft-js/warp-core/styles/app/plan.css'
+
+/** A message waiting for the agent to finish. */
+export type QueuedMessage = { id: string; text: string }
+
+/**
+ * Plan: the task list and the Queue (07 §1.1, §1.2). Steps are pending, running, done or blocked; messages sent during
+ * a run wait in order under them and can be removed. Named AgentPlan so it can't be mistaken for a billing plan.
+ */
+export function AgentPlan({ steps, queue, title = 'Plan', onRemoveQueued }: { steps: PlanStep[]; queue?: QueuedMessage[]; title?: unknown; onRemoveQueued?: (id: string) => void }) {
+  const done = derived(() => steps.filter(s => s.state === 'done').length)
+  const waiting = derived(() => queue ?? [])
+  const note = (s: PlanStep) => s.note ?? (s.state === 'blocked' ? 'Waiting for your approval' : s.state === 'running' ? 'In progress' : undefined)
+  return (
+    <div data-scope="plan">
+      <div data-part="header"><h4>{title}</h4><small data-numeric="">{done.value}/{steps.length}</small></div>
+      <Bar label="Plan progress" value={steps.length ? done.value / steps.length : 0} />
+      <ol aria-label="Plan steps">
+        {steps.map(s => (
+          <li key={s.id} data-state={s.state}>
+            <span data-part="box">
+              {s.state === 'done' && <CheckIcon style="inline-size:12px;block-size:12px;stroke-width:2.2" />}
+              {s.state === 'running' && <span data-scope="spinner" style="--_size:10px;color:var(--warp-color-accent-text)"></span>}
+              {s.state === 'blocked' && <HandIcon style="inline-size:11px;block-size:11px" />}
+            </span>
+            <span>{s.title}{note(s) !== undefined && <small>{note(s)}</small>}</span>
+          </li>
+        ))}
+      </ol>
+      <div data-part="queue" role="group" aria-label="Queued messages">
+        <span data-part="eyebrow">Queue · {waiting.value.length}</span>
+        {waiting.value.length === 0 && <small>Messages you send while a run is busy wait here, in order.</small>}
+        {waiting.value.map(q => (
+          <div key={q.id}>
+            <ClockIcon style="inline-size:14px;block-size:14px;color:var(--warp-color-text-subtle)" />
+            <span>{q.text}</span>
+            <IconButton icon={XIcon} label={`Remove from queue: ${q.text}`} onClick={() => onRemoveQueued?.(q.id)} />
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/agent/ArtifactPanel.tsx

@@ -0,0 +1,80 @@
+import { CopyIcon, ExternalIcon } from '@weft-js/warp-icons'
+import { announce, copyConfirm, indicator, nextIndex, uid } from '@weft-js/warp-core'
+import { derived, state, untrack, type State } from '@weft-js/core'
+import { Badge } from '../Badge'
+import { use } from '@weft-js/warp-core/weft'
+import { IconButton, held, Sweep, useSweep } from './bits'
+import '../styles'
+import '@weft-js/warp-core/styles/components/tabs.css'
+import '@weft-js/warp-core/styles/app/artifact.css'
+import '@weft-js/warp-core/styles/app/versions.css'
+
+/** One saved version of an artifact. */
+export type ArtifactVersion = { id: string; label: string; meta?: string | undefined; code?: string; named?: boolean }
+const VIEWS = ['Preview', 'Code', 'Versions'] as const
+
+/**
+ * ArtifactPanel (07 §6.4): title, version badge, Copy; APG tabs Preview, Code, Versions. Versions is a listbox with a
+ * roving tab stop, selection following focus; picking one is `onVersion`, and Code shows that version's code. Copy
+ * confirms the panel's sweep. It fills its container, so a rail, a Sheet or a full route all hold it.
+ */
+export function ArtifactPanel({ title, versions, version, onVersion, code, onOpen, children }: { title: unknown; versions: ArtifactVersion[]; version?: string | State<string | undefined> | undefined; onVersion?: (id: string) => void; code?: string; onOpen?: () => void; children?: unknown }) {
+  const id = uid('art')
+  const view = state<(typeof VIEWS)[number]>('Preview')
+  const picked = held<string | undefined>(() => version, untrack(() => versions[0]?.id), () => (v: string | undefined) => onVersion?.(v!))
+  const current = derived(() => versions.find(v => v.id === picked.value) ?? versions[0])
+  const source = derived(() => current.value?.code ?? code ?? '')
+  const badge = derived(() => current.value?.label.split(' ·')[0])
+  let root: HTMLElement | undefined
+  let list: HTMLElement | undefined
+  useSweep()
+  use(indicator, () => list, () => ({ selected: '[aria-selected="true"]', x: '--_ix', w: '--_iw', at: view.value }))
+  const go = (v: (typeof VIEWS)[number]) => (view.value = v)
+  const onTab = (e: KeyboardEvent) => {
+    const to = nextIndex(e.key, VIEWS.indexOf(view.value), VIEWS.length, { rtl: getComputedStyle(e.currentTarget as Element).direction === 'rtl' })
+    if (to < 0) return
+    e.preventDefault()
+    go(VIEWS[to]!)
+    list!.querySelectorAll<HTMLElement>('[role="tab"]')[to]?.focus()
+  }
+  const choose = (v: ArtifactVersion) => {
+    picked.set(v.id)
+    announce(root!.ownerDocument, `Previewing ${v.label}`)
+    queueMicrotask(() => root!.querySelectorAll<HTMLElement>('[role="option"]')[versions.findIndex(x => x.id === v.id)]?.focus())
+  }
+  const onList = (e: KeyboardEvent) => {
+    const at = versions.findIndex(v => v.id === current.value?.id)
+    const to = nextIndex(e.key, at, versions.length, { orientation: 'vertical' })
+    if (to < 0) return
+    e.preventDefault()
+    choose(versions[to]!)
+  }
+  return (
+    <section ref={n => (root = n)} data-scope="artifact" data-sweep="" aria-labelledby={`${id}-n`}>
+      <Sweep />
+      <div data-part="head">
+        <b id={`${id}-n`}>{title}</b>
+        {badge.value !== undefined && <Badge tone="neutral">{badge.value}</Badge>}
+        <IconButton icon={CopyIcon} label="Copy" onClick={(e: Event) => copyConfirm(e.currentTarget as Element, source.value, root)} />
+        {onOpen && <IconButton icon={ExternalIcon} label="Open in editor" onClick={onOpen} />}
+      </div>
+      <div data-scope="tabs" data-part="root" style="padding:8px 12px 0;gap:0">
+        <div ref={n => (list = n)} data-part="list" role="tablist" aria-label="Artifact views" onKeyDown={onTab}>
+          {VIEWS.map((v, i) => <button key={v} data-part="trigger" role="tab" type="button" id={`${id}-t${i}`} aria-controls={`${id}-p${i}`} aria-selected={v === view.value ? 'true' : 'false'} tabindex={v === view.value ? undefined : '-1'} onClick={() => go(v)}>{v}</button>)}
+          <span data-part="indicator" aria-hidden="true" data-instant=""></span>
+        </div>
+      </div>
+      <div data-part="panel" role="tabpanel" id={`${id}-p0`} aria-labelledby={`${id}-t0`} tabindex="0" hidden={view.value !== 'Preview'}><div data-part="preview">{children}</div></div>
+      <div data-part="panel" role="tabpanel" id={`${id}-p1`} aria-labelledby={`${id}-t1`} tabindex="0" hidden={view.value !== 'Code'}><pre>{source.value}</pre></div>
+      <div data-part="panel" role="tabpanel" id={`${id}-p2`} aria-labelledby={`${id}-t2`} hidden={view.value !== 'Versions'}>
+        <ol data-scope="versions" role="listbox" aria-label="Versions" onKeyDown={onList}>
+          {versions.map(v => (
+            <li key={v.id} id={`${id}-v-${v.id}`} role="option" aria-selected={v.id === current.value?.id ? 'true' : 'false'} aria-current={v.id === current.value?.id ? 'true' : undefined} tabindex={v.id === current.value?.id ? '0' : '-1'} data-named={v.named ?? v.id === current.value?.id ? '' : undefined} onClick={() => choose(v)}>
+              <i></i><span>{v.label}{v.meta !== undefined && <small>{v.meta}</small>}</span>
+            </li>
+          ))}
+        </ol>
+      </div>
+    </section>
+  )
+}

package/src/agent/Assistant.tsx

@@ -0,0 +1,96 @@
+import { SparkleIcon } from '@weft-js/warp-icons'
+import { announce, answerText, copyConfirm, uid, type AgentTool, type Answer, type AnswerBlock } from '@weft-js/warp-core'
+import { derived, onMount, untrack, watch } from '@weft-js/core'
+import { Alert } from '../Alert'
+import { Button } from '../Button'
+import { MessageActions, type Feedback } from './Actions'
+import { Prose } from './Prose'
+import { Question } from './Question'
+import { Reasoning } from './Reasoning'
+import { Sources } from './Sources'
+import { ToolCall } from './ToolCall'
+import '../styles'
+import '@weft-js/warp-core/styles/app/assistant.css'
+
+/** Props for Assistant. */
+export interface AssistantProps {
+  /** The folded value: `foldAnswer(events)`, or what a stream folds to. */
+  answer: Answer
+  /** The turn number, for its name: "Assistant answer 2". */
+  n?: number
+  arrive?: boolean
+  /** Was there on load: approvals and questions take no focus and announce nothing. */
+  quiet?: boolean | undefined
+  /** Render a block of answer text yourself (Markdown, say); the default is `Prose`. */
+  render?: (text: string, answer: Answer) => unknown
+  /** Called when a tool call is approved, with its arguments as edited and whether to always allow it. */
+  onApprove?: (tool: AgentTool, args: string, always: boolean) => void
+  /** Called when a tool call is denied. */
+  onDeny?: (tool: AgentTool) => void
+  alwaysAllow?: (tool: AgentTool) => string | undefined
+  /** Called with a question's id and the answer picked or typed. */
+  onAnswer?: (id: string, answer: string | string[]) => void
+  /** Called with `up`, `down` or null when thumbs change, and the reason picked for a thumbs down. */
+  onFeedback?: (value: Feedback, reason?: string) => void
+  /** Adds Regenerate: ask for a new answer. */
+  onRegenerate?: () => void
+  /** Adds Branch: start a new conversation from this answer. */
+  onBranch?: () => void
+  /** Which of several answers is shown, with arrows between them. */
+  branch?: { index: number; count: number; onChange: (index: number) => void }
+}
+
+type Thought = Extract<AnswerBlock, { kind: 'reasoning' }>
+type Said = Extract<AnswerBlock, { kind: 'text' }>
+type Asked = Extract<AnswerBlock, { kind: 'question' }>
+
+function Block({ block, base, p }: { block: AnswerBlock; base: string; p: AssistantProps }) {
+  const tool = derived(() => p.answer.tools.find(t => t.id === block.id))
+  const kind = derived(() => block.kind)
+  // once per kind: a row's nodes are read again whenever the list changes
+  const view = derived(() => {
+    const k = kind.value
+    return untrack(() => {
+      if (k === 'reasoning') return <Reasoning text={(block as Thought).text} streaming={(block as Thought).streaming} seconds={(block as Thought).seconds} />
+      if (k === 'text') return p.render ? <>{p.render((block as Said).text, p.answer)}</> : <Prose text={(block as Said).text} sources={p.answer.sources} base={base} />
+      if (k === 'question') return <Question question={(block as Asked).question} quiet={p.quiet} onAnswer={a => p.onAnswer?.(block.id, a)} />
+      return <ToolCall call={tool.value!} quiet={p.quiet} alwaysAllow={p.alwaysAllow?.(tool.value!)} onApprove={(a, al) => p.onApprove?.(tool.value!, a, al)} onDeny={() => p.onDeny?.(tool.value!)} />
+    })
+  })
+  return <>{view.value}</>
+}
+
+/**
+ * The assistant's turn (07 §1.1, §1.2): renders the folded Answer only, so replay and hydration take the same path.
+ * Caret while streaming, aria-busy until done; the end of a turn is announced once, never each token.
+ */
+export function Assistant(p: AssistantProps) {
+  const base = uid('ans')
+  const st = derived(() => p.answer.state)
+  const busy = derived(() => st.value === 'waiting' || st.value === 'streaming' || st.value === 'approval')
+  const empty = derived(() => p.answer.blocks.length === 0 && st.value !== 'error')
+  const blocks = derived(() => p.answer.blocks)
+  const many = derived(() => p.answer.sources.length > 0)
+  let root: HTMLElement | undefined
+  onMount(() => {
+    watch(() => st.value, (s, prev) => {
+      if (prev === undefined || !root) return
+      const doc = root.ownerDocument
+      if (s === 'done') announce(doc, 'Answer ready')
+      if (s === 'stopped') announce(doc, 'Stopped')
+      if (s === 'error') announce(doc, 'The answer failed', true)
+    })
+  })
+  return (
+    <article ref={n => (root = n)} data-scope="assistant" data-state={st.value} aria-label={p.n !== undefined ? `Assistant answer ${p.n}` : 'Assistant answer'} aria-busy={busy.value ? 'true' : undefined} data-arrive={p.arrive ? '' : undefined}>
+      <span data-part="mark"><SparkleIcon /></span>
+      <div data-part="content">
+        {empty.value && <p></p>}
+        {blocks.value.map(b => <Block key={b.id} block={b} base={base} p={p} />)}
+        {st.value === 'error' && <Alert tone="critical" title="The answer failed">{p.answer.error}{p.onRegenerate && <> <Button emphasis="link" tone="neutral" onClick={p.onRegenerate}>Retry</Button></>}</Alert>}
+        {many.value && <Sources items={p.answer.sources} base={base} />}
+      </div>
+      {!busy.value && <MessageActions stopped={st.value === 'stopped'} onCopy={el => void copyConfirm(el, answerText(untrack(() => p.answer)))} onFeedback={p.onFeedback} onRegenerate={p.onRegenerate} onBranch={p.onBranch} branch={p.branch} />}
+    </article>
+  )
+}

package/src/agent/Checkpoint.tsx

@@ -0,0 +1,14 @@
+import { UndoIcon } from '@weft-js/warp-icons'
+import { Button } from '../Button'
+import '../styles'
+import '@weft-js/warp-core/styles/app/checkpoint.css'
+
+/** Checkpoint (07 §1.3): a hairline with a label and Restore. Restoring forks a branch; `onRestore` decides how. */
+export function Checkpoint({ label, onRestore }: { label: unknown; onRestore?: () => void }) {
+  return (
+    <div data-scope="checkpoint">
+      <span>{label}</span>
+      {onRestore && <Button emphasis="ghost" tone="neutral" size="sm" onClick={onRestore}><UndoIcon />Restore</Button>}
+    </div>
+  )
+}

package/src/agent/Cite.tsx

@@ -0,0 +1,39 @@
+import { citePreview, installSweep, type AgentSource } from '@weft-js/warp-core'
+import { state } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import '../styles'
+import '@weft-js/warp-core/styles/components/popover.css'
+import '@weft-js/warp-core/styles/app/cite.css'
+
+/**
+ * A citation (07 §1.3, §1.6): a link to source n named "Source n", with a preview on hover and focus. The preview sits
+ * next in the DOM, so Tab reaches its link. Pressing moves focus to the source card and confirms it.
+ */
+export function Cite({ n, source, href }: { n: number; source?: AgentSource | undefined; href: string }) {
+  const open = state(false)
+  let link: HTMLAnchorElement | undefined
+  let panel: HTMLElement | undefined
+  use(citePreview, () => (source ? link : undefined), () => ({ panel: panel!, onOpen: (o: boolean) => (open.value = o) }))
+  const jump = (e: MouseEvent) => {
+    const a = e.currentTarget as Element
+    const doc = a.ownerDocument
+    const card = doc.getElementById(a.getAttribute('href')!.slice(1)) // the page's id: a hydrated server id isn't this side's
+    if (!card) return
+    e.preventDefault()
+    card.focus()
+    installSweep(doc).confirm(card)
+  }
+  return (
+    <span style="display:contents">
+      <a ref={el => (link = el)} href={href} data-scope="cite" aria-label={`Source ${n}`} aria-expanded={source ? (open.value ? 'true' : 'false') : undefined} onClick={jump}>{n}</a>
+      {source && (
+        <span ref={el => (panel = el)} data-scope="popover" data-part="content" popover="manual">
+          <span data-part="title" style="display:block">{source.title}</span>
+          {source.path !== undefined && <span data-part="description" style="display:block">{source.path}</span>}
+          {source.snippet !== undefined && <span>{source.snippet}</span>}
+          {source.url !== undefined && <a href={source.url} data-part="open">Open source</a>}
+        </span>
+      )}
+    </span>
+  )
+}