@weft-js/warp 0.0.0-stage → 0.1.0

package/src/live/NotificationPreferences.tsx

@@ -0,0 +1,193 @@
+import { announce, applyPrefs, gridNav, prefCell, toggleChanges, triState, uid, type PrefChange, type PrefEvent, type PrefGroup, type PrefRules, type PrefValues } from '@weft-js/warp-core'
+import { derived, onMount, state, untrack, watch } from '@weft-js/core'
+import { Badge } from '../Badge'
+import { Button } from '../Button'
+import { Checkbox } from '../Choice'
+import { Select } from '../Select'
+import { use } from '@weft-js/warp-core/weft'
+import { G, val } from './shared'
+import '../fields'
+import '@weft-js/warp-core/styles/app/prefs-matrix.css'
+
+/** A column of the preferences grid: email, push and so on. */
+export interface PrefChannel { id: string; label: string }
+/** Props for NotificationPreferences. */
+export interface NotificationPreferencesProps {
+  /** The grid's name: the id of a heading, else this text is rendered in a visually hidden one. */
+  title?: string
+  groups: PrefGroup[]
+  channels: PrefChannel[]
+  value: PrefValues | { value: PrefValues } | (() => PrefValues)
+  /** Event id → the channels it can use. An event not listed can use all. */
+  offered?: Record<string, string[]> | undefined
+  /** Event id → the channels it must use. */
+  locked?: Record<string, string[]> | undefined
+  lockReason?: string
+  /** Every change saves on its own; a rejected promise flips the cells back and says why. */
+  onChange?: ((changes: PrefChange[]) => void | Promise<unknown>) | undefined
+  digest?: string
+  /** The channel the digest applies to. */
+  digestChannel?: string
+  /** The email delivery choices, such as instant, hourly or daily. */
+  digests?: { value: string; label: string }[]
+  /** Called with the delivery picked. A rejected promise puts the old one back. */
+  onDigest?: (digest: string) => void | Promise<unknown>
+  /** Enables Reset to defaults. */
+  defaults?: { value: PrefValues; digest?: string }
+}
+
+const DIGESTS = [{ value: 'instant', label: 'Instantly' }, { value: 'hourly', label: 'Hourly digest' }, { value: 'daily', label: 'Daily digest at 9:00' }, { value: 'weekly', label: 'Weekly digest, Mondays' }]
+const lower = (s: string) => (s === 'SMS' ? s : s.toLowerCase())
+type Save = 'idle' | 'saving' | 'saved' | 'error'
+const CELL = 'input[type="checkbox"], [data-part="na"]'
+
+/**
+ * NotificationPreferences (07 §4.6): event × channel, one APG grid with one tab stop. Group and channel toggles are
+ * tri-state; a required channel is locked and says why; a channel an event can't use is a plain "—" that still takes
+ * focus. Saves on every change, optimistically; a rejected save flips back. The same DOM restacks below 560px.
+ */
+export function NotificationPreferences({ title = 'Notification preferences', groups, channels, value, offered, locked, lockReason = 'Required: this alert always goes to your account.', onChange, digest = 'instant', digestChannel = 'email', digests = DIGESTS, onDigest, defaults }: NotificationPreferencesProps) {
+  const id = uid('prefs')
+  const model = state<PrefValues>(untrack(() => val<PrefValues>(value)))
+  const mail = state(untrack(() => digest))
+  const save = state<Save>('idle')
+  // what a cell is (a box, locked, not offered) never depends on the values: its node stays through every change
+  const fixed: PrefRules = untrack(() => ({ offered, locked }))
+  const events = derived(() => groups.flatMap(g => g.events))
+  const reset = untrack(() => defaults)
+  let grid: HTMLDivElement | undefined
+  let seq = 0
+  onMount(() => {
+    watch(() => val<PrefValues>(value), v => { if (save.value !== 'saving') model.value = v })
+    watch(() => digest, d => { if (save.value !== 'saving') mail.value = d })
+  })
+  use(gridNav, () => grid, () => ({ targets: CELL }))
+
+  const say = (text: string, assertive = false) => announce(grid!.ownerDocument, text, assertive)
+  /** Apply now, run the save, roll back on rejection. */
+  const commit = async (apply: () => void, run: () => void | Promise<unknown>, msg: string) => {
+    const snap = [model.value, mail.value] as const
+    const mine = ++seq
+    apply()
+    save.value = 'saving'
+    try {
+      await run()
+      if (mine !== seq) return
+      save.value = 'saved'
+      say(`${msg}. Saved.`)
+    } catch {
+      if (mine !== seq) return
+      model.value = snap[0]
+      mail.value = snap[1]
+      save.value = 'error'
+      say(`Couldn't save: ${msg}. Change undone.`, true)
+    }
+  }
+  const change = (changes: PrefChange[], msg: string) => commit(() => (model.value = applyPrefs(model.value, changes)), () => onChange?.(changes), msg)
+  const name = (c: string) => channels.find(x => x.id === c)!.label
+  const cell = (e: PrefEvent, c: string, on: boolean) => change([{ event: e.id, channel: c, on }], `${e.label}, ${name(c)} ${on ? 'on' : 'off'}`)
+  const parent = (evs: PrefEvent[], c: string, where?: string) => {
+    const ch = toggleChanges(model.value, evs, fixed, c)
+    if (ch.length) void change(ch, `${name(c)} ${ch[0]!.on ? 'on' : 'off'} for ${ch.length} event${ch.length > 1 ? 's' : ''}${where ? ` in ${where}` : ''}`)
+  }
+  const onLocked = (e: Event) => {
+    e.preventDefault()
+    grid!.querySelector<HTMLElement>(`#${(e.currentTarget as HTMLElement).id}`)?.focus()
+    say(lockReason)
+  }
+  const onNa = (e: KeyboardEvent) => { if (e.key === ' ') { e.preventDefault(); say('Not offered for this event') } }
+
+  const parentBox = (evs: PrefEvent[], c: string, nameText: string, visible: string, where: string | undefined, first: boolean) => {
+    const tri = derived(() => triState(model.value, evs, fixed, c))
+    return (
+      <Checkbox checked={tri.value === 'on'} indeterminate={tri.value === 'mixed'} tabindex={first ? '0' : '-1'} onChange={() => parent(evs, c, where)}>
+        <span data-part="sr-only">{nameText}</span><span data-part="ch-name" aria-hidden="true">{visible}</span>
+      </Checkbox>
+    )
+  }
+  const na = (text: string, chName?: string) => (
+    <span data-part="na" tabindex="-1" onKeyDown={onNa}>
+      <span aria-hidden="true">—</span><span data-part="sr-only">{text}</span>
+      {chName && <span data-part="ch-name" aria-hidden="true">{chName}</span>}
+    </span>
+  )
+  const emailOn = derived(() => events.value.some(e => prefCell(model.value, fixed, e.id, digestChannel) === 'on'))
+  const hint = derived(() => (!emailOn.value ? 'Turn on an email event to choose a digest' : mail.value === 'instant' ? 'Each email is sent as it happens' : 'Batches email; security alerts skip the digest'))
+  const statusText = derived(() => ({ idle: 'All changes saved', saving: 'Saving…', saved: 'Saved', error: "Couldn't save. Your last change was undone." })[save.value])
+  const doReset = () => commit(() => { model.value = reset!.value; mail.value = reset!.digest ?? 'instant' }, async () => {
+    await onChange?.(events.value.flatMap(e => channels.flatMap(c => (prefCell(reset!.value, fixed, e.id, c.id) === 'na' || prefCell(reset!.value, fixed, e.id, c.id) === 'locked' ? [] : [{ event: e.id, channel: c.id, on: !!reset!.value[e.id]?.[c.id] }]))))
+    await onDigest?.(reset!.digest ?? 'instant')
+  }, 'Notification settings reset to defaults')
+  const pickDigest = (e: Event) => {
+    const el = e.target as HTMLSelectElement
+    const next = el.value
+    void commit(() => (mail.value = next), () => onDigest?.(next), `Email delivery: ${el.selectedOptions[0]!.textContent}`)
+  }
+
+  return (
+    <div data-scope="prefs-matrix">
+      <span data-part="sr-only" id={`${id}-t`}>{title}</span>
+      <div ref={n => (grid = n)} role="grid" data-part="grid" aria-labelledby={`${id}-t`} aria-describedby={`${id}-k`}>
+        <div role="row" data-part="head">
+          <div role="columnheader" data-part="corner">Event</div>
+          {channels.map((c, i) => (
+            <div key={c.id} role="columnheader">
+              <span data-part="ch-head" aria-hidden="true">{c.label}</span>
+              {parentBox(events.value, c.id, `${c.label}, all events`, `All ${lower(c.label)}`, undefined, i === 0)}
+            </div>
+          ))}
+        </div>
+        {groups.map(g => (
+          <div key={g.id} role="rowgroup" data-part="rows">
+            <div role="row" data-part="group">
+              <div role="rowheader">{g.label}</div>
+              {channels.map(c => (
+                <div key={c.id} role="gridcell">
+                  {triState({}, g.events, fixed, c.id) === null
+                    ? na(`${g.label}, ${lower(c.label)}, not offered`)
+                    : parentBox(g.events, c.id, `${g.label}, all ${lower(c.label)}`, c.label, g.label, false)}
+                </div>
+              ))}
+            </div>
+            {g.events.map(e => (
+              <div key={e.id} role="row" data-row={e.id}>
+                <div role="rowheader">
+                  <b>{e.label}</b>
+                  {e.hint && <small>{e.hint}</small>}
+                  {e.instant && <Badge tone="info" hidden={mail.value === 'instant' || !emailOn.value}>Always instant</Badge>}
+                </div>
+                {channels.map(c => {
+                  const kind = prefCell({}, fixed, e.id, c.id)
+                  return (
+                    <div key={c.id} role="gridcell">
+                      {kind === 'na' ? na(`${e.label}, ${lower(c.label)}, not offered`, c.label)
+                        : kind === 'locked' ? <Checkbox checked aria-disabled="true" aria-describedby={`${id}-lock`} tabindex="-1" id={`${id}-${e.id}-${c.id}`} onClick={onLocked}>
+                            <span data-part="sr-only">{e.label}, {lower(c.label)}</span><span data-part="ch-name" aria-hidden="true">{c.label}</span><G name="lock" data-part="lock" />
+                          </Checkbox>
+                        : <EventCell on={prefCell(model.value, fixed, e.id, c.id) === 'on'} text={`${e.label}, ${lower(c.label)}`} ch={c.label} onToggle={(v: boolean) => cell(e, c.id, v)} />}
+                    </div>
+                  )
+                })}
+              </div>
+            ))}
+          </div>
+        ))}
+      </div>
+      <span data-part="sr-only" id={`${id}-k`}>Arrow keys move between cells, Home and End to the row's ends, Control Home and End to the grid's corners, Space toggles.</span>
+      <span data-part="sr-only" id={`${id}-lock`}>{lockReason}</span>
+      <div data-part="footer">
+        <Select label="Email delivery" options={digests} value={mail.value} disabled={!emailOn.value} hint={hint.value} onChange={pickDigest} />
+        <span data-part="status" role="status" data-state={save.value}>{statusText.value}</span>
+        {reset && <Button emphasis="ghost" tone="neutral" size="sm" onClick={doReset}>Reset to defaults</Button>}
+      </div>
+    </div>
+  )
+}
+
+function EventCell({ on, text, ch, onToggle }: { on: boolean; text: string; ch: string; onToggle: (v: boolean) => unknown }) {
+  return (
+    <Checkbox checked={on} tabindex="-1" onChange={(e: Event) => onToggle((e.target as HTMLInputElement).checked)}>
+      <span data-part="sr-only">{text}</span><span data-part="ch-name" aria-hidden="true">{ch}</span>
+    </Checkbox>
+  )
+}

package/src/live/Prejoin.tsx

@@ -0,0 +1,140 @@
+import { announce, countdownLabel, countdownParts, levelMeter, uid } from '@weft-js/warp-core'
+import { derived, onCleanup, onMount, state, untrack } from '@weft-js/core'
+import { Avatar } from '../parts'
+import { Button } from '../Button'
+import { Card } from '../Card'
+import { Input } from '../Field'
+import { Select, type Option } from '../Select'
+import { Spinner } from '../Spinner'
+import { use } from '@weft-js/warp-core/weft'
+import { avatarTint, G, held } from './shared'
+import '../fields'
+import '@weft-js/warp-core/styles/app/base.css'
+import '@weft-js/warp-core/styles/app/tile.css'
+import '@weft-js/warp-core/styles/app/prejoin.css'
+
+const BARS = Array.from({ length: 16 }, (_, i) => i)
+/** The devices to choose from before joining. */
+export interface PrejoinDevices { mics?: Option[]; cameras?: Option[]; speakers?: Option[] }
+
+/** Props for Prejoin. */
+export interface PrejoinProps {
+  name?: string | undefined
+  /** The preview: your own <video>. Media is the caller's; warp never touches getUserMedia. */
+  preview?: () => unknown
+  /** 0 to 1. For a 10 Hz level, set `--level` on [data-part="meter"] yourself: nothing re-renders either way. */
+  level?: number
+  /** Whether your mic starts on. */
+  mic?: boolean
+  /** Whether your camera starts on. */
+  camera?: boolean
+  /** Called with the mic toggle's new state. */
+  onMic?: (on: boolean) => void
+  /** Called with the camera toggle's new state. */
+  onCamera?: (on: boolean) => void
+  devices?: PrejoinDevices
+  onDevice?: (kind: 'mic' | 'camera' | 'speaker', id: string) => void
+  onTestSound?: (() => void) | undefined
+  joining?: boolean
+  /** The join button's words. Default "Join now". */
+  joinLabel?: string
+  onJoin?: ((name: string) => void) | undefined
+}
+
+/** Prejoin (07 §3.2): preview, 16-bar mic meter, device Selects, Join with its loading state. */
+export function Prejoin({ name = '', preview, level, mic, camera, onMic, onCamera, devices, onDevice, onTestSound, joining, joinLabel = 'Join now', onJoin }: PrejoinProps) {
+  const who = state(untrack(() => name))
+  const micOn = held<boolean>(() => mic, true, () => onMic)
+  const camOn = held<boolean>(() => camera, true, () => onCamera)
+  const list = untrack(() => devices) ?? {}
+  let meter: HTMLDivElement | undefined
+  use(levelMeter, () => meter, () => level)
+  const pick = (kind: 'mic' | 'camera' | 'speaker', e: Event) => onDevice?.(kind, (e.target as HTMLSelectElement).value)
+  return (
+    <div data-scope="prejoin">
+      <div data-part="layout">
+        <div data-part="stack">
+          <div data-part="preview">
+            <div data-scope="tile" data-cam={camOn.value ? undefined : 'off'}>
+              {camOn.value && preview ? <div data-part="video">{preview()}</div> : <Avatar name={who.value || 'You'} size="xl" style={avatarTint(who.value)} />}
+              <span data-part="name">You</span>
+            </div>
+            <div data-part="preview-controls">
+              <Button emphasis="soft" tone="neutral" data-icon-only="" aria-pressed={micOn.value ? 'true' : 'false'} aria-label="Microphone" onClick={() => micOn.set(!micOn.value)}><G name={micOn.value ? 'mic' : 'micoff'} /></Button>
+              <Button emphasis="soft" tone="neutral" data-icon-only="" aria-pressed={camOn.value ? 'true' : 'false'} aria-label="Camera" onClick={() => camOn.set(!camOn.value)}><G name={camOn.value ? 'cam' : 'camoff'} /></Button>
+            </div>
+          </div>
+          <div ref={n => (meter = n)} data-part="meter" role="meter" aria-label="Microphone level" aria-valuemin="0" aria-valuemax="16" aria-valuenow="0" style={level === undefined ? undefined : `--level:${level}`}>
+            {BARS.map(i => <i key={i}></i>)}
+          </div>
+        </div>
+        <div data-part="stack">
+          <Input label="Your name" value={who.value} autocomplete="name" onInput={e => (who.value = e.currentTarget.value)} />
+          {list.mics && <Select label="Microphone" options={list.mics} onChange={e => pick('mic', e)} />}
+          {list.cameras && <Select label="Camera" options={list.cameras} onChange={e => pick('camera', e)} />}
+          {list.speakers && <Select label="Speakers" options={list.speakers} onChange={e => pick('speaker', e)} />}
+          {onTestSound && <Button emphasis="link" size="sm" onClick={onTestSound}>Play test sound</Button>}
+          <Button size="lg" full loading={!!joining} onClick={() => onJoin?.(who.value)}>{joinLabel}</Button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/** Lobby (07 §3.2): waiting to be let in. A Spinner and "Asking to join…" as a status. */
+export function Lobby({ title = 'Waiting for the host', children = "We'll chime when it's your turn.", onCancel }: { title?: unknown; children?: unknown; onCancel?: () => void }) {
+  return (
+    <Card eyebrow="Lobby" title={title} sweep={false}>
+      <p>{children}</p>
+      <p><Spinner size="sm" /> <span role="status">Asking to join…</span></p>
+      <Button emphasis="outline" tone="neutral" size="sm" onClick={() => onCancel?.()}>Cancel request</Button>
+    </Card>
+  )
+}
+
+/**
+ * Countdown (07 §3.2): role=timer, aria-live off, announced once at one minute. `to` and `now` are epoch ms: pass
+ * `now` to render on the server; without it the digits fill in after mount.
+ */
+export function Countdown({ to, now, label = 'Starts in', onDone }: { to: number; now?: number | undefined; label?: string | undefined; onDone?: () => void }) {
+  const left = state<number | null>(untrack(() => (now === undefined ? null : to - now)))
+  const parts = derived(() => countdownParts(left.value ?? 0))
+  const name = derived(() => (left.value === null ? label : countdownLabel(left.value)))
+  let root: HTMLDivElement | undefined
+  onMount(() => {
+    let warned = untrack(() => left.value !== null && left.value <= 60000)
+    let done = false
+    const beat = () => {
+      const ms = untrack(() => to) - Date.now()
+      left.value = ms
+      if (!warned && ms <= 60000) { warned = true; if (root) announce(root.ownerDocument, 'Starts in 1 minute') }
+      if (!done && ms <= 0) { done = true; clearInterval(t); onDone?.() }
+    }
+    const t = setInterval(beat, 1000)
+    onCleanup(() => clearInterval(t))
+    queueMicrotask(beat)
+  })
+  return (
+    <div ref={n => (root = n)} data-part="countdown" role="timer" aria-live="off" aria-label={name.value}>
+      {parts.value.map(p => <span key={p.unit}><b>{p.value}</b><small>{p.unit}</small></span>)}
+    </div>
+  )
+}
+
+/** ScheduledLobby (07 §3.1): Countdown, with Join disabled until `joinable` or the countdown ends. */
+export function ScheduledLobby({ title, children, to, now, joinable, opensAt, onJoin, onAddToCalendar }: { title: unknown; children?: unknown; to: number; now?: number | undefined; joinable?: boolean; opensAt?: string; onJoin?: (() => void) | undefined; onAddToCalendar?: (() => void) | undefined }) {
+  const ended = state(false)
+  const can = derived(() => !!joinable || ended.value)
+  const id = uid('sched')
+  return (
+    <Card eyebrow="Scheduled lobby" title={title} sweep={false} aria-labelledby={undefined}>
+      {children !== undefined && <p>{children}</p>}
+      <Countdown to={to} now={now} onDone={() => (ended.value = true)} />
+      <p>
+        <Button size="sm" disabled={!can.value} aria-describedby={!can.value && opensAt ? id : undefined} onClick={() => onJoin?.()}>Join</Button>
+        {onAddToCalendar && <Button emphasis="outline" tone="neutral" size="sm" onClick={onAddToCalendar}><G name="cal" />Add to calendar</Button>}
+      </p>
+      {opensAt && !can.value && <small id={id}>Opens at {opensAt}</small>}
+    </Card>
+  )
+}

package/src/live/PushSoftAsk.tsx

@@ -0,0 +1,37 @@
+import { announce, uid } from '@weft-js/warp-core'
+import { state } from '@weft-js/core'
+import { Button } from '../Button'
+import { G } from './shared'
+import '../styles'
+import '@weft-js/warp-core/styles/app/push-ask.css'
+
+/**
+ * Push soft-ask (07 §4.2, P2): an in-app card before the browser's prompt. `onAccept` is where the caller calls
+ * Notification.requestPermission(), only after this yes; the caller also decides when to show it (never first visit).
+ */
+export function PushSoftAsk({ title = 'Get a ping when someone mentions you?', children = 'Only mentions and approvals, on this device. You can change it any time.', onAccept, onDismiss, declined = "Okay. We won't ask again for 30 days." }: { title?: unknown; children?: unknown; onAccept: () => void; onDismiss?: () => void; declined?: string }) {
+  const id = uid('push')
+  const shown = state(true)
+  let root: HTMLElement | undefined
+  const no = () => {
+    announce(root!.ownerDocument, declined)
+    shown.value = false
+    onDismiss?.()
+  }
+  const yes = () => { shown.value = false; onAccept() }
+  return (
+    <>
+      {shown.value && (
+        <div ref={n => (root = n)} data-scope="push-ask" role="region" aria-labelledby={`${id}-t`}>
+          <span data-part="mark"><G name="bell" /></span>
+          <b id={`${id}-t`}>{title}</b>
+          <span>{children}</span>
+          <div data-part="actions">
+            <Button size="sm" onClick={yes}>Turn on</Button>
+            <Button emphasis="ghost" tone="neutral" size="sm" onClick={no}>Not now</Button>
+          </div>
+        </div>
+      )}
+    </>
+  )
+}

package/src/live/TransportPicker.tsx

@@ -0,0 +1,163 @@
+import { announce, formatMs, latencyTone, liveState, percentile, transportError, transportSim, uid, whileSeen, worstLive, type LaneId, type LiveState, type TransportBus, type TransportConfig, type TransportNetwork, type TransportPreset, type TransportWire } from '@weft-js/warp-core'
+import { derived, onCleanup, onMount, state, untrack } from '@weft-js/core'
+import { LiveStatus } from '../parts'
+import { Button } from '../Button'
+import { Select } from '../Select'
+import { use } from '@weft-js/warp-core/weft'
+import { G, val } from './shared'
+import '../fields'
+import '@weft-js/warp-core/styles/inputs/choice.css'
+import '@weft-js/warp-core/styles/components/alert.css'
+import '@weft-js/warp-core/styles/app/transport.css'
+
+const WIRES: [TransportWire, string, string, string][] = [['default', 'weft default', 'SSE + WebSocket', 'One SSE (.live, stream) and one WebSocket (channel) per tab'], ['tabs', 'Tabs only', 'BroadcastChannel', "tabs.channel: this browser's tabs, no server"], ['fake', 'Fake', '@weft-js/core/test', 'In-memory pair with a network model']]
+const BUSES: [TransportBus, string, string][] = [['memory', '+0 ms', 'One process. The default'], ['postgres', '+4 ms', 'LISTEN / NOTIFY'], ['redis', '+2 ms', 'Pub/sub'], ['nats', '+1 ms', 'Subjects'], ['durable-object', '+8 ms', 'Cloudflare preset only']]
+const PRESETS = [{ value: 'single', label: 'Single instance' }, { value: 'multi', label: 'Multi-instance' }, { value: 'cf', label: 'Cloudflare' }]
+const NETS = [{ value: 'good', label: 'Good' }, { value: 'slow', label: 'Slow (×6)' }, { value: 'lossy', label: 'Lossy (spikes, drops)' }, { value: 'wsblock', label: 'WebSocket blocked' }, { value: 'offline', label: 'Offline' }]
+const LANES: [LaneId, string][] = [['live', '.live'], ['stream', 'stream'], ['channel', 'channel']]
+const BARS = Array.from({ length: 20 }, (_, i) => i)
+
+type Status = string | { value: string } | (() => string)
+/** Props for TransportPicker. */
+export interface TransportPickerProps {
+  /** The real statuses to show (`.live`, `stream().status`, `channel.status`); the lanes' figures stay the sandbox's. */
+  lanes?: Partial<Record<LaneId, Status>>
+  bus?: TransportBus
+  wire?: TransportWire
+  preset?: TransportPreset
+  network?: TransportNetwork
+  onConfigChange?: (c: TransportConfig) => void
+  title?: string
+}
+
+/**
+ * TransportPicker (07 §4.7): the realtime sandbox, a dev surface, never end-user UI. It picks the wire under test and
+ * the server bus (validated like the build), runs the documented behaviour under a chosen network in `transportSim`,
+ * and reads lanes as the four states of §4.4, with p50 and p95 over the last 20 pings, cursors and an event log.
+ */
+export function TransportPicker({ lanes, bus = 'postgres', wire = 'default', preset = 'multi', network = 'good', onConfigChange, title = 'Realtime sandbox' }: TransportPickerProps) {
+  const id = uid('transport')
+  const start = untrack(() => ({ wire, bus, preset, network }))
+  const sim = transportSim(start)
+  const rev = state(0)
+  const view = <T,>(fn: () => T) => derived(() => { void rev.value; return fn() })
+  const cfg = view(() => sim.config)
+  const data = view(() => sim.lanes())
+  const log = view(() => sim.log)
+  const fallback = derived(() => untrack(() => lanes))
+  const stateOf = (k: LaneId): LiveState => {
+    const given = fallback.value?.[k]
+    return given !== undefined ? liveState(val<string>(given)) : data.value[k].state
+  }
+  const worst = derived(() => worstLive(LANES.map(([k]) => stateOf(k))))
+  const error = derived(() => transportError(cfg.value))
+  const noServer = derived(() => cfg.value.wire !== 'default')
+  const busNote = derived(() => (cfg.value.wire === 'tabs' ? 'No server: tabs only stays in this browser.' : cfg.value.wire === 'fake' ? 'No server: the fake pair runs in memory.' : ''))
+  let root: HTMLDivElement | undefined
+
+  onMount(() => {
+    const off = sim.subscribe(() => { rev.value++ })
+    sim.start()
+    onCleanup(() => { off(); sim.destroy() })
+  })
+  use(whileSeen, () => root, () => ({ ms: 2000, tick: () => sim.tick() }))
+  // one sentence per settled change (a lane's change is polite and once, offline assertive)
+  onMount(() => {
+    let said: LiveState | undefined
+    let t: ReturnType<typeof setTimeout> | undefined
+    const off = sim.subscribe(() => {
+      const w = untrack(() => worst.value)
+      if (w === said) return
+      said = w
+      clearTimeout(t)
+      t = setTimeout(() => {
+        if (!root) return
+        const text = w === 'live' ? 'all lanes live' : LANES.filter(([k]) => stateOf(k) !== 'live').map(([k, n]) => `${n} ${stateOf(k)}`).join(', ')
+        announce(root.ownerDocument, `Realtime sandbox: ${text}`, w === 'offline')
+      }, 600)
+    })
+    onCleanup(() => { off(); clearTimeout(t) })
+  })
+  const set = (next: Partial<TransportConfig>) => { sim.configure(next); onConfigChange?.(sim.config) }
+  const reset = () => { sim.reset(start); onConfigChange?.(sim.config); announce(root!.ownerDocument, 'Realtime sandbox reset') }
+  const drop = () => { if (!sim.drop()) announce(root!.ownerDocument, 'Tabs only has no server connection to drop') }
+
+  return (
+    <div ref={n => (root = n)} data-scope="transport">
+      <div data-part="head">
+        <h4>{title}</h4>
+        <LiveStatus state={worst.value} label="Realtime sandbox">{worst.value === 'live' ? 'All lanes live' : undefined}</LiveStatus>
+        <Button emphasis="ghost" tone="neutral" size="sm" onClick={reset}><G name="refresh" />Reset</Button>
+      </div>
+      <div data-part="config">
+        <fieldset data-scope="group">
+          <legend>Wire under test</legend>
+          <div data-part="choices" role="radiogroup" aria-label="Wire under test">
+            {WIRES.map(w => (
+              <label key={w[0]} data-scope="choice-card" data-sweep="">
+                <span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span>
+                <input type="radio" name={`${id}-wire`} value={w[0]} checked={cfg.value.wire === w[0]} onChange={() => set({ wire: w[0] })} />
+                <span data-part="label">{w[1]}</span><span data-part="meta">{w[2]}</span><span data-part="hint">{w[3]}</span>
+              </label>
+            ))}
+          </div>
+        </fieldset>
+        <fieldset data-scope="group" disabled={noServer.value}>
+          <legend>Server bus <code>realtime.bus</code></legend>
+          <div data-part="choices" role="radiogroup" aria-label="Server bus">
+            {BUSES.map(b => (
+              <label key={b[0]} data-scope="choice-card" data-sweep="">
+                <span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span>
+                <input type="radio" name={`${id}-bus`} value={b[0]} checked={cfg.value.bus === b[0]} disabled={b[0] === 'durable-object' && cfg.value.preset !== 'cf'} aria-describedby={`${id}-h-${b[0]}`} onChange={() => set({ bus: b[0] })} />
+                <span data-part="label"><code>{b[0]}</code></span><span data-part="meta">{b[1]}</span>
+                <span data-part="hint" id={`${id}-h-${b[0]}`}>{b[0] === 'durable-object' && cfg.value.preset === 'cf' ? 'One object per channel' : b[2]}</span>
+              </label>
+            ))}
+          </div>
+          <div data-part="row"><Select label="Deploy preset" options={PRESETS} value={cfg.value.preset} onChange={(e: Event) => set({ preset: (e.target as HTMLSelectElement).value as TransportPreset })} /></div>
+          <span data-part="message">{busNote.value}</span>
+        </fieldset>
+      </div>
+      {error.value && (
+        <div data-scope="alert" data-tone="critical" data-part="build-error" role="alert">
+          <span data-part="title">{error.value.title}</span>
+          <span data-part="description">{error.value.description}</span>
+        </div>
+      )}
+      <div data-part="row">
+        <Select label="Network" options={NETS} value={cfg.value.network} onChange={(e: Event) => set({ network: (e.target as HTMLSelectElement).value as TransportNetwork })} />
+        <Button emphasis="outline" tone="neutral" size="sm" onClick={() => sim.ping()}><G name="bolt" />Ping</Button>
+        <Button emphasis="outline" tone="neutral" size="sm" onClick={drop}>Drop connection</Button>
+        <Button emphasis="outline" tone="neutral" size="sm" onClick={() => sim.fallBehind()}>Fall behind</Button>
+      </div>
+      <ul data-part="lanes" aria-label="Lanes">
+        {LANES.map(l => <Lane key={l[0]} name={l[1]} lane={data.value[l[0]]} status={stateOf(l[0])} />)}
+      </ul>
+      <div data-part="log" role="log" aria-live="off" aria-label="Event log" tabindex="0">
+        <ol>{log.value.map(e => <li key={`${e.at}-${e.text}`}><span>+{e.at.toFixed(1)}s</span><b>{e.who}</b><span>{e.text}</span></li>)}</ol>
+      </div>
+    </div>
+  )
+}
+
+function Lane({ name, lane, status }: { name: string; lane: { samples: number[]; cursor: string; wire: string; note: string }; status: LiveState }) {
+  const p50 = derived(() => percentile(lane.samples, 0.5))
+  const p95 = derived(() => percentile(lane.samples, 0.95))
+  const bars = derived(() => BARS.map(i => {
+    const x = lane.samples.slice(-20)[i - (20 - Math.min(20, lane.samples.length))]
+    return { i, h: x === undefined ? 0 : Math.min(1, Math.sqrt(x / 1000)), tone: x === undefined ? undefined : latencyTone(x) }
+  }))
+  return (
+    <li data-part="lane" data-state={status}>
+      <div data-part="lane-name"><b>{name}</b><small>{lane.wire}</small></div>
+      <LiveStatus state={status} />
+      <dl data-part="figures">
+        <div><dt>p50</dt><dd data-numeric="" data-tone={latencyTone(p50.value!)}>{formatMs(p50.value!)}</dd></div>
+        <div><dt>p95</dt><dd data-numeric="" data-tone={latencyTone(p95.value!)}>{formatMs(p95.value!)}</dd></div>
+        <div><dt>cursor</dt><dd data-numeric="">{lane.cursor}</dd></div>
+      </dl>
+      <div data-part="bars" aria-hidden="true">{bars.value.map(b => <i key={b.i} data-tone={b.tone} style={`--h:${b.h.toFixed(3)}`}></i>)}</div>
+      <span data-part="note">{lane.note}</span>
+    </li>
+  )
+}

package/src/live/index.ts

@@ -0,0 +1,12 @@
+// The live pack: see docs/design/warp. One file per component family; each imports only its own CSS.
+export { Bell, type BellProps } from './Bell'
+export { Inbox, type InboxProps, type Note, type NoteAction, type NoteKind } from './Inbox'
+export { ActivityFeed, type ActivityItem } from './ActivityFeed'
+export { PushSoftAsk } from './PushSoftAsk'
+export { notify } from './notify'
+export { ConnectionPill, ConnectionBanner } from './Connection'
+export { LiveStatus, type LiveState } from '../parts'
+export { NotificationPreferences, type NotificationPreferencesProps, type PrefChannel } from './NotificationPreferences'
+export { TransportPicker, type TransportPickerProps } from './TransportPicker'
+export { MeetingRoom, ControlBar, Tile, type MeetingRoomProps, type ControlBarProps, type MeetingLayout, type Participant } from './MeetingRoom'
+export { Prejoin, Lobby, ScheduledLobby, Countdown, type PrejoinProps, type PrejoinDevices } from './Prejoin'

package/src/live/notify.tsx

@@ -0,0 +1,16 @@
+import { announce, notifyPolicy, type NotifyItem } from '@weft-js/warp-core'
+import { toast } from '../Toast'
+
+/**
+ * The inbox's toast policy (07 §4.2) on warp's toaster: `const n = notify({ open: () => inboxOpen.value })`, then
+ * `n.push({ title, description, tone, urgent, action })` per arrival. Inbox open: no toast, one announcement after a
+ * second of quiet. Closed: a toast each, three at most; a burst collapses to "3 new notifications".
+ */
+export function notify(opts: { open: () => boolean; burst?: number; quiet?: number | undefined; max?: number | undefined; summary?: (n: number) => string }) {
+  return notifyPolicy({
+    ...opts,
+    show: (t: NotifyItem) => toast.show(t),
+    dismiss: id => toast.dismiss(id),
+    announce: (text, assertive) => announce(document, text, assertive),
+  })
+}

package/src/live/shared.tsx

@@ -0,0 +1,39 @@
+// What the live pack's components share: glyphs from the specimen's 24 grid, and reading a prop that may be a plain
+// value, a weft State or Signal, or a getter (07 §4.5: `count={() => …}`, `items={inbox}`).
+import { AlertIcon, AtIcon, BellIcon, BoardIcon, BoltIcon, CalendarIcon, CamIcon, CamOffIcon, ChatIcon, CheckIcon, CommentIcon, FlagIcon, GridIcon, HandIcon, LeaveIcon, LockIcon, MicIcon, MicOffIcon, MoreIcon, PlusIcon, PresentIcon, RefreshIcon, ScreenIcon, SignalIcon, SmileIcon, SpeakerIcon, UsersIcon, XIcon, iconSet } from '@weft-js/warp-icons'
+import { hueOf } from '@weft-js/warp-core'
+import { Box, state, untrack, type State } from '@weft-js/core'
+
+const GLYPHS = { bell: BellIcon, at: AtIcon, comment: CommentIcon, flag: FlagIcon, check: CheckIcon, alert: AlertIcon, cal: CalendarIcon, more: MoreIcon, x: XIcon, plus: PlusIcon, lock: LockIcon, refresh: RefreshIcon, bolt: BoltIcon, mic: MicIcon, micoff: MicOffIcon, cam: CamIcon, camoff: CamOffIcon, screen: ScreenIcon, hand: HandIcon, smile: SmileIcon, chat: ChatIcon, users: UsersIcon, leave: LeaveIcon, signal: SignalIcon, grid: GridIcon, speaker: SpeakerIcon, present: PresentIcon, board: BoardIcon }
+
+export type GlyphName = keyof typeof GLYPHS
+export const G = iconSet(GLYPHS)
+
+/** A prop that may be a value, a box with `.value` (State, Signal, Resource) or a getter. */
+export function val<T>(v: T | { value: T } | (() => T)): T {
+  if (typeof v === 'function') return (v as () => T)()
+  if (v !== null && typeof v === 'object' && !Array.isArray(v) && 'value' in (v as object)) return (v as { value: T }).value
+  return v as T
+}
+
+const isState = (v: unknown): v is State<unknown> => v instanceof Box
+
+/** One read and write over a bound State, a controlled value and a default (the Picker `bindable`, without its CSS). */
+export function held<T>(value: () => State<T> | T | undefined, fallback: T, on?: () => ((v: T) => void) | undefined) {
+  const own = state<T>(untrack(() => { const v = value(); return isState(v) ? fallback : (v) ?? fallback }))
+  return {
+    get value(): T {
+      const v = value()
+      return isState(v) ? v.value : v !== undefined ? (v) : own.value
+    },
+    set(next: T) {
+      const v = untrack(value)
+      if (isState(v)) v.value = next
+      else own.value = next
+      untrack(() => on?.())?.(next)
+    },
+  }
+}
+
+/** The avatar and tile tint for a person: the data palette, never a status colour (07 §0). */
+export const avatarTint = (id: string) => `--_bg:color-mix(in oklab,var(--warp-color-data-${hueOf(id)}) 26%,var(--warp-color-surface-raised))`