sygnal 5.4.0 → 6.1.0

package/dist/guide/persistence.md

@@ -0,0 +1,245 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Persistence
+
+`persist()` saves part of the app's state in the browser's storage and puts it back when the app starts again. You declare it once, on the root component: which keys to keep, under which storage key, and in which version of their shape.
+
+```jsx live
+// TodoApp.jsx
+import { ABORT, persist } from 'sygnal'
+
+export function TodoApp({ state }) {
+  const shown = state.filter === 'open' ? state.todos.filter((todo) => !todo.done) : state.todos
+  return (
+    <main>
+      <label>New todo <input className="draft" value={state.draft} /></label>
+      <button className="add">Add</button>
+      <button className="show-all">All</button>
+      <button className="show-open">Open</button>
+      <button className="start-over">Start over</button>
+      <ul>{shown.map((todo) => <li>{todo.title}</li>)}</ul>
+    </main>
+  )
+}
+
+TodoApp.initialState = { todos: [], filter: 'all', draft: '' }
+
+TodoApp.intent = ({ DOM }) => ({
+  DRAFT: DOM.input('.draft').value(),
+  ADD: DOM.click('.add'),
+  SHOW_ALL: DOM.click('.show-all'),
+  SHOW_OPEN: DOM.click('.show-open'),
+  START_OVER: DOM.click('.start-over'),
+})
+
+TodoApp.model = {
+  DRAFT: (state, draft) => ({ ...state, draft }),
+  ADD: (state) => state.draft
+    ? { ...state, todos: [...state.todos, { title: state.draft, done: false }], draft: '' }
+    : ABORT,
+  SHOW_ALL: (state) => ({ ...state, filter: 'all' }),
+  SHOW_OPEN: (state) => ({ ...state, filter: 'open' }),
+  START_OVER: {
+    STATE: (state) => ({ ...state, todos: [], filter: 'all' }),
+    PERSIST: { clear: true },
+  },
+}
+
+// Version 1 saved { items: ['milk', ...] }; version 2 saves { todos: [{ title, done }], filter }
+TodoApp.persist = persist({
+  key: 'todo-app',
+  pick: ['todos', 'filter'],
+  version: 2,
+  migrate: (old, fromVersion) => fromVersion === 1
+    ? { todos: old.items.map((title) => ({ title, done: false })), filter: 'all' }
+    : undefined,
+})
+```
+
+Reload the page and the todos and the filter are still there; the half-typed `draft` is not, because it isn't picked. **Start over** empties the list and removes the saved copy.
+
+## What is saved
+
+The stored value is JSON, `{ version, state }`, under `key`:
+
+```json
+{"version":2,"state":{"todos":[{"title":"milk","done":false}],"filter":"all"}}
+```
+
+`state` has the top-level keys listed in `pick`, or, with `omit` instead, every key except those. [Calculated fields](https://sygnal.js.org/guide/calculated-fields/) are never saved: they are computed again from the restored state. Pick what has to survive a reload (the user's data, a chosen view) and leave out what doesn't (drafts, loading flags, server data you fetch again, an undo history). A [behavior](./behaviors.md#persisted-state-and-undo-steps) of the root component whose slice is UI state (`persist: false`, as [`sortable`](./drag-and-drop.md)'s drag state) is never saved or restored, even when `pick` names it. A sub-component's or Collection item's behavior slice is part of the data it lives in and is saved with it.
+
+Values must survive `JSON.stringify`: plain objects, arrays, strings, numbers, booleans and `null`. A `Date` comes back as a string, and a `Map` or `Set` as `{}`.
+
+### A plain format
+
+When something else reads or writes the same entry (an older version of the app, another script, a spec that fixes the format), `format: 'plain'` stores the picked keys themselves, with no envelope:
+
+```jsx
+Note.persist = persist({ key: 'note-draft', pick: ['title', 'body'], format: 'plain' })
+```
+
+```json
+{"title":"Groceries","body":"milk, eggs"}
+```
+
+A plain entry has no version, so `version` and `migrate` don't apply: TypeScript rejects them with `format: 'plain'`, and they are ignored at runtime. A stored value that isn't an object (an array, a string, a number) is ignored, and the app starts from `initialState`. Everything else (`pick`/`omit`, `sync`, `storage`, clearing, the restore and the debounced writes) works as with the default `format: 'versioned'`.
+
+## When it is restored
+
+When the app starts, the root component reads the stored entry synchronously, before its first state, and merges the saved keys into `initialState`. The first render already shows the saved todos, and the `INITIALIZE` action carries them: there is no separate "load" step and no flash of the empty list.
+
+`persist` works on the **root component** only, the one passed to `run()`. It saves and restores the app's whole state tree, and a sub-component's state is a slice of it: to save a child's state, pick the key the root keeps it under. On any other component the static is ignored, which is [SYG224](https://sygnal.js.org/reference/errors/#syg224) in development and in `sygnal-check`.
+
+:::note[Where persist works]
+On any component that is its app's root:
+
+- the component you pass to `run()`
+- the component you pass to [`renderComponent`](#testing) in tests
+- an [Astro](https://sygnal.js.org/integration/astro/) island (each island is its own app)
+- a [Vike](https://sygnal.js.org/integration/vike/) page with no Layout or Wrapper
+
+Not (yet) on a Vike page, Layout or Wrapper rendered in a Layout/Wrapper shell: the shell is the root there, so `persist` is ignored and SYG224 says so. Save that state yourself: write it with [`STATE.watch`](https://sygnal.js.org/guide/intent/#reacting-to-state-changes-statewatch) and read it back in `BOOTSTRAP`.
+:::
+
+## When it is saved
+
+A write happens after the state stops changing for `debounceMs` (100 ms by default), so typing or a burst of actions makes one write. A pending write is also made at once when the page is hidden for good (the `pagehide` event: closing the tab, navigating away) and when the app is disposed. Nothing is written while the picked keys are unchanged, and the initial state is not written back.
+
+## Versions and migrate
+
+`version` (default 1) is saved with the state (not with `format: 'plain'`). When the stored entry has another version, `migrate(old, fromVersion)` turns the old `state` into this version's keys; the result is merged into `initialState` like any restore and saved under the new version on the next write. When `migrate` returns nothing (`undefined` or `null`), or there is no `migrate`, the stored entry is ignored and the app starts from `initialState`.
+
+Bump `version` whenever the shape of a picked key changes, and keep the `migrate` branches for the versions your users may still have.
+
+## Clearing
+
+`PERSIST: { clear: true }` in a model entry removes the stored copy. Like other sinks it can be a function of `(state, data)` that returns the command, or `ABORT` to do nothing:
+
+```jsx
+Account.model = {
+  LOG_OUT: {
+    STATE: (state) => ({ ...state, user: null, cart: [] }),
+    PERSIST: { clear: true },
+  },
+}
+```
+
+The state the same action produces isn't saved; the next change is. `PERSIST` needs no driver.
+
+## Several tabs: sync
+
+With `sync: true`, a write made in another tab (or window) of the same site is applied in this one, as a built-in `RESTORE` action whose data is the saved keys. The default `RESTORE` merges them into the state; a `RESTORE` entry in your model replaces it:
+
+```jsx
+TodoApp.persist = persist({ key: 'todo-app', pick: ['todos', 'filter'], version: 2, migrate, sync: true })
+```
+
+Clearing in another tab doesn't reset this one: it keeps its state and saves it again on its next change.
+
+## Storage
+
+`storage` is `'local'` (`localStorage`, the default), `'session'` (`sessionStorage`: one tab, until it closes) or an object with synchronous `getItem`, `setItem` and `removeItem`. With `sync`, an object can also have `subscribe(fn)`: call `fn(key, newValue)` when another writer changes a key, and return a function that unsubscribes.
+
+```jsx
+const memory = new Map()
+
+export const memoryStorage = {
+  getItem: (key) => memory.get(key) ?? null,
+  setItem: (key, value) => { memory.set(key, value) },
+  removeItem: (key) => { memory.delete(key) },
+}
+```
+
+Asynchronous storages (IndexedDB, a server) don't fit the synchronous restore. Load from those with a request in `BOOTSTRAP` and save with [`STATE.watch`](https://sygnal.js.org/guide/intent/#reacting-to-state-changes-statewatch) instead.
+
+During server rendering nothing is read or written: `renderToString` runs views only.
+
+## Server rendering: hydrate
+
+When the client starts from server-rendered HTML (the [`hydrateState`](./ssr.md) state), restoring before the first render would make that render differ from the server's markup. So when the app hydrates, the first render uses the server's state, and the saved keys follow in a `RESTORE` action once it is on the page. The app hydrates when:
+
+- `run()`'s mount point starts with markup from [`renderToString()`](./ssr.md): its root element carries a `data-sygnal-ssr` attribute, which the first client render removes. Other markup in the mount point, such as a client-only app's loading placeholder, isn't server markup: the saved keys are part of the first render
+- an [Astro](https://sygnal.js.org/integration/astro/) island was rendered on the server (not `client:only`)
+- a [Vike](https://sygnal.js.org/integration/vike/) page hydrates its server HTML (not a client-side navigation)
+
+```jsx
+App.persist = persist({ key: 'app', pick: ['theme'] })
+App.initialState = window.__SYGNAL_STATE__ || App.initialState
+
+run(App, {}, { mountPoint: '#app' })
+```
+
+The `hydrate` option overrides the detection: `hydrate: true` always restores after the first render, `hydrate: false` always before it. Use `hydrate: true` when the server's HTML doesn't come from `renderToString()` (another renderer, or markup you post-process without the attribute).
+
+## With undo
+
+Keep an [undo history](./undo.md) out of the saved state: pick the document, not `history`. After a reload the document is back and the history starts empty.
+
+## Diagnostics
+
+| Code | When |
+|---|---|
+| [SYG642](https://sygnal.js.org/reference/errors/#syg642) (warning) | The stored entry isn't JSON, `migrate` threw, or a write failed (the storage is full or blocked). The app continues: from `initialState` after a failed restore, unsaved after a failed write (retried at the next state change). Printed in production too, once per kind (restore, save, clear): a storage that refuses every write warns once, and again only after a save has worked |
+| [SYG223](https://sygnal.js.org/reference/errors/#syg223) (warning) | A `pick` or `omit` key that isn't a key of `initialState` (a typo) |
+| [SYG224](https://sygnal.js.org/reference/errors/#syg224) (error) | `persist` on a component that isn't the root |
+
+## Testing
+
+`renderComponent` gives a persisting root a fake storage. The `storage` option fills it (key to stored entry, or a raw string), `t.storage(key)` reads an entry, and `t.settle()` makes the pending writes:
+
+```jsx
+// TodoApp.test.jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { TodoApp } from './TodoApp.jsx'
+
+it('restores version 1 todos and saves version 2', async () => {
+  const t = renderComponent(TodoApp, {
+    storage: { 'todo-app': { version: 1, state: { items: ['milk'] } } },
+  })
+  await t.ready()
+  expect(t.state.todos).toEqual([{ title: 'milk', done: false }])
+
+  t.simulateAction('DRAFT', 'eggs')
+  t.simulateAction('ADD')
+  await t.settle()
+  expect(t.storage('todo-app')).toEqual({
+    version: 2,
+    state: { todos: [{ title: 'milk', done: false }, { title: 'eggs', done: false }], filter: 'all' },
+  })
+  t.dispose()
+})
+```
+
+The object you pass is used as the storage, not copied: writes land in it, and two `renderComponent` calls given the same object share it, so `sync: true` can be tested with two instances. The fake serves `'local'` and `'session'` alike; a component whose `storage` is an object uses that object.
+
+With `format: 'plain'` the entries are the stored keys themselves, both in the `storage` option and from `t.storage(key)`:
+
+```jsx
+it('saves the draft as { title, body }', async () => {
+  const t = renderComponent(Note, { storage: { 'note-draft': { title: 'Groceries', body: '' } } })
+  await t.ready()
+  expect(t.state.title).toBe('Groceries')
+
+  t.simulateAction('BODY', 'milk')
+  await t.settle()
+  expect(t.storage('note-draft')).toEqual({ title: 'Groceries', body: 'milk' })
+  t.dispose()
+})
+```
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `key` | (required) | The storage key |
+| `pick` | all keys | The top-level state keys to save |
+| `omit` | `[]` | The top-level state keys not to save (instead of `pick`) |
+| `version` | `1` | Saved with the state; another stored version goes through `migrate` |
+| `migrate` | none | `(old, fromVersion) => keys` for a stored entry of another version; nothing discards it |
+| `format` | `'versioned'` | `'versioned'` stores `{ version, state }`; `'plain'` stores the picked keys themselves (no `version` / `migrate`) |
+| `storage` | `'local'` | `'local'`, `'session'` or a synchronous `{ getItem, setItem, removeItem, subscribe? }` |
+| `sync` | `false` | Apply other tabs' writes (a `RESTORE` action) |
+| `hydrate` | detected | Restore after the first render (in `RESTORE`): `true` / `false` override the detection of server-rendered HTML |
+| `debounceMs` | `100` | Wait this long without a state change before writing |
+
+In TypeScript, `pick` and `omit` are checked against the root component's state keys.

package/dist/guide/recipes/ai-form-fill.md

@@ -0,0 +1,163 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Structured Output into a Form
+
+A contact form with a shortcut: paste an email signature, and a [chat model](../ai-chat.md) fills in the fields. The model answers with [structured output](../ai-chat.md#structured-output), validated against a schema, and each field it found goes into the [`form` behavior](../forms.md) as if the user had typed it. Nothing is saved until the user checks the fields and submits, with the form's own validation.
+
+The pieces:
+
+- **Two schemas.** The extraction schema says what the model may answer: every field can be `null` (not in the text). The form's schema says what the user may submit.
+- **The `ok` action fills the form** with one `form.SET` holding the fields the model found, so those fields are validated and marked as changed like typed ones.
+- **The model never submits.** The user does.
+
+## The form
+
+In this demo, the signature is read as soon as the demo shows. Paste another one and fill again; or edit a field and submit.
+
+```js live-server
+import { encodeOpenResponses } from 'sygnal/ai'
+
+let nextId = 1
+
+export default {
+  // the chat model: reads a signature (a real model reads anything)
+  'POST /v1/responses': ({ json }) => {
+    const text = String(json.input.at(-1).content)
+    const contact = {
+      name: text.split('\n')[0].trim() || null,
+      email: text.match(/[\w.+-]+@[\w-]+\.[\w.]+/)?.[0] ?? null,
+      company: text.split('\n')[1]?.split('|')[1]?.trim() || null,
+      phone: text.match(/\+?[\d ()-]{7,}\d/)?.[0].trim() ?? null,
+    }
+    return { sse: encodeOpenResponses(JSON.stringify(contact).match(/.{1,20}/g)), delayMs: 300, chunkMs: 40 }
+  },
+  'POST /api/contacts': ({ json }) => ({ status: 201, json: { id: nextId++, ...json } }),
+}
+```
+
+```jsx live live-height=420
+import { z } from 'zod'
+import { ABORT, form } from 'sygnal'
+
+// what the model may answer: null for "not in the text"
+const Extracted = z.object({
+  name: z.string().nullable(),
+  email: z.string().nullable(),
+  company: z.string().nullable(),
+  phone: z.string().nullable(),
+})
+
+// what the user may submit
+const contactSchema = z.object({
+  name: z.string().trim().min(1, 'Enter a name'),
+  email: z.string().trim().email('Enter a valid email address'),
+  company: z.string().trim(),
+  phone: z.string().trim(),
+})
+
+const SIGNATURE = 'Dana Whitfield\nHead of Operations | Northwind Traders\ndana.whitfield@northwind.example\n+1 (555) 014-2290'
+
+const read = (text) => ({
+  instructions: 'Extract the contact details from the text. Use null for anything that is not there.',
+  messages: [{ role: 'user', content: text }],
+  output: Extracted,
+  ok: 'EXTRACTED',
+  error: 'NOT_EXTRACTED',
+})
+
+function Field({ field, label, id }) {
+  return (
+    <p>
+      <label for={id}>{label}</label>{' '}
+      <input id={id} name={field.name} value={field.value} aria-invalid={field.invalid} aria-describedby={`${id}-error`} />
+      <span id={`${id}-error`}> {field.error}</span>
+    </p>
+  )
+}
+
+function NewContact({ state, uid }) {
+  const f = state.form.fields
+  return (
+    <section className="new-contact">
+      <form className="paste">
+        <label for={uid('paste')}>Paste a signature</label>
+        <textarea id={uid('paste')} className="pasted" rows="4" value={state.pasted} />
+        <button type="submit" disabled={state.reading}>{state.reading ? 'Reading…' : 'Fill in the form'}</button>
+        <span role="status"> {state.note}</span>
+      </form>
+      <form className="contact" noValidate>
+        <Field field={f.name} label="Name" id={uid('name')} />
+        <Field field={f.email} label="Email" id={uid('email')} />
+        <Field field={f.company} label="Company" id={uid('company')} />
+        <Field field={f.phone} label="Phone" id={uid('phone')} />
+        <button type="submit" disabled={state.form.submitting}>Save contact</button>
+        <span className="saved"> {state.savedId ? `Saved as contact ${state.savedId}.` : ''}</span>
+      </form>
+    </section>
+  )
+}
+
+NewContact.initialState = { pasted: SIGNATURE, reading: false, note: '', savedId: null }
+
+NewContact.uses = {
+  form: form(contactSchema, { form: '.contact', values: { name: '', email: '', company: '', phone: '' }, submit: 'SAVE' }),
+}
+
+NewContact.intent = ({ DOM }) => ({
+  PASTE: DOM.input('.pasted').value(),
+  FILL: DOM.select('.paste').events('submit', { preventDefault: true }),
+})
+
+NewContact.model = {
+  BOOTSTRAP: {
+    STATE: (state) => ({ ...state, reading: true }),
+    LLM: (state) => read(state.pasted),
+  },
+  PASTE: (state, pasted) => ({ ...state, pasted }),
+  FILL: {
+    STATE: (state) => (state.pasted.trim() ? { ...state, reading: true, note: '' } : ABORT),
+    LLM: (state) => (state.pasted.trim() ? read(state.pasted) : ABORT),
+  },
+  EXTRACTED: {
+    STATE: (state, { value }) => ({ ...state, reading: false, note: value.name === null ? 'No name found: add it, then save.' : 'Check the fields, then save.' }),
+    // the fields the model found, as if the user had typed them
+    EFFECT: (state, { value }, next) => {
+      next('form.SET', { values: Object.fromEntries(Object.entries(value).filter(([, text]) => text !== null)) })
+    },
+  },
+  NOT_EXTRACTED: (state) => ({ ...state, reading: false, note: 'Could not read that. Fill in the form by hand.' }),
+  SAVE: { HTTP: (state, values) => ({ url: '/api/contacts', method: 'POST', json: values, ok: 'form.DONE', error: 'form.ERRORS' }) },
+  'form.DONE': (state, contact) => ({ ...state, savedId: contact.id }),
+}
+```
+
+```css live
+.new-contact textarea { width: 100%; }
+.new-contact form { margin-bottom: 1rem; }
+```
+
+- **The extraction schema is loose, the form's is strict.** The model may find no email; the form still requires one. A wrong value from the model (an email without `@`) shows the form's error once the user leaves the field or submits, as for anything typed.
+- **`form.SET`, not `form.RESET`**: a reset makes the values the form's starting point, so they would count as unchanged, and it would clear what the user had already typed in the fields the model didn't find. `form.SET` changes only the fields it names, in one validation.
+- **`null`, not optional.** Providers' strict modes require every key, so "not found" is a `null` value. `.nullable()` also tells the model plainly that it may say so.
+- **Keep the user in the loop.** The model's answer is a suggestion: the form shows it, the user saves it.
+
+## Testing
+
+`t.respond('LLM', object)` sends the object as the reply's JSON, so `EXTRACTED` gets it as `value`:
+
+```js
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import NewContact from './NewContact.jsx'
+
+it('fills the fields the model found, and saves only on submit', async () => {
+  const t = renderComponent(NewContact)
+  await t.respond('LLM', { name: 'Dana Whitfield', email: 'dana@northwind.example', company: null, phone: null })
+  expect(t.state.form.values).toEqual({ name: 'Dana Whitfield', email: 'dana@northwind.example', company: '', phone: '' })
+  expect(t.requests('HTTP')).toEqual([])
+
+  t.simulateEvent('.contact', 'submit')
+  await t.respond('HTTP', { id: 7 })
+  expect(t.state.savedId).toBe(7)
+  t.dispose()
+})
+```

package/dist/guide/recipes/ai-summarize.md

@@ -0,0 +1,155 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# On-device Summaries
+
+Chrome can run a small language model on the user's device, through the [Prompt API](https://developer.chrome.com/docs/ai/prompt-api) (`LanguageModel`). The `chromePrompt()` transport from `sygnal/ai` puts it behind the [chat driver](../ai-chat.md), so a component asks it for a summary exactly as it would ask a hosted model. Nothing leaves the device: no server, no key, no cost per request.
+
+Not every visitor has it: other browsers don't, and Chrome needs a capable device and a one-time model download. So the feature must **degrade**: where the model is unavailable, the component shows a plain excerpt instead.
+
+## main.js
+
+```js
+import { run } from 'sygnal'
+import { makeChatDriver, chromePrompt } from 'sygnal/ai'
+import Article from './Article.jsx'
+
+run(Article, { LLM: makeChatDriver({ transport: chromePrompt() }) })
+```
+
+Where the browser has no `LanguageModel`, or the device can't run it, every request fails at once with an Error whose `status` is `'unavailable'`. The component's `error` action handles that like any failure, so `main.js` needs no check.
+
+To use a hosted model where the on-device one is missing, choose the transport before `run()` with `status()`:
+
+```js
+import { run } from 'sygnal'
+import { makeChatDriver, chromePrompt, uiMessageStream } from 'sygnal/ai'
+import Article from './Article.jsx'
+
+const onDevice = chromePrompt()
+const transport = (await onDevice.status()) === 'unavailable' ? uiMessageStream('/api/summarize') : onDevice
+
+run(Article, { LLM: makeChatDriver({ transport }) })
+```
+
+`status()` resolves with `'available'`, `'downloadable'`, `'downloading'` or `'unavailable'`. A `'downloadable'` model is downloaded by its first request, which must come from a user action (a click), so summarise on a click rather than on load. `chromePrompt({ monitor })` gets the download's progress events.
+
+A component can show the status too, for example to say "Summaries need a one-time download" before the first click. A promise can't be read in a view, so give `status` to [`driverFromAsync`](https://sygnal.js.org/guide/custom-drivers/) and ask for it like any request:
+
+```js
+import { run, driverFromAsync } from 'sygnal'
+import { makeChatDriver, chromePrompt } from 'sygnal/ai'
+import Article from './Article.jsx'
+
+const onDevice = chromePrompt()
+run(Article, { LLM: makeChatDriver({ transport: onDevice }), MODEL: driverFromAsync(onDevice.status) })
+```
+
+```js
+Article.model = {
+  BOOTSTRAP: { MODEL: () => ({ ok: 'MODEL_STATUS' }) },
+  MODEL_STATUS: (state, status) => ({ ...state, model: status }),
+}
+```
+
+In a test, `await t.respond('MODEL', 'downloadable')` answers it.
+
+## The component
+
+The component is the same whatever the transport. In this demo it runs on the page's demo model (as every demo here does), and asks for a summary as soon as it shows. In your app, the same code runs on the device.
+
+```js live-server
+import { encodeOpenResponses } from 'sygnal/ai'
+
+export default {
+  'POST /v1/responses': () => ({
+    sse: encodeOpenResponses(['Octopuses ', 'have three hearts ', 'and blue blood, ', 'and each arm ', 'can act ', 'on its own.']),
+    delayMs: 300,
+    chunkMs: 80,
+  }),
+}
+```
+
+```jsx live live-height=260
+import { ABORT } from 'sygnal'
+
+const TEXT = 'The octopus has three hearts: two pump blood through the gills, and one through the rest of the body. Its blood is blue, because it carries oxygen with copper instead of iron. Two thirds of its neurons are in its arms, so each arm can taste, touch and react without waiting for the brain. Most octopuses live only a year or two.'
+
+// the fallback: the first two sentences
+const excerpt = (text) => text.match(/[^.!?]+[.!?]+/g)?.slice(0, 2).join(' ') ?? text
+
+const summarize = (text) => ({
+  instructions: 'Summarise the text in one sentence of at most 25 words.',
+  messages: [{ role: 'user', content: text }],
+  key: 'summary',
+  delta: 'SUMMARY',
+  ok: 'SUMMARIZED',
+  error: 'NO_SUMMARY',
+})
+
+function Article({ state }) {
+  return (
+    <article className="article">
+      <p>{state.text}</p>
+      <button type="button" className="summarize" disabled={state.status === 'busy'}>Summarise</button>
+      <p aria-live="polite">
+        {state.status === 'busy' && !state.summary && 'Summarising…'}
+        {state.summary && <><b>Summary:</b> {state.summary}</>}
+        {state.status === 'fallback' && <><b>Excerpt:</b> {excerpt(state.text)} <i>(summaries need Chrome's built-in model)</i></>}
+      </p>
+    </article>
+  )
+}
+
+Article.initialState = { text: TEXT, summary: '', status: 'ready' }
+
+Article.intent = ({ DOM }) => ({
+  SUMMARIZE: DOM.click('.summarize'),
+})
+
+Article.model = {
+  BOOTSTRAP: {
+    STATE: (state) => ({ ...state, status: 'busy' }),
+    LLM: (state) => summarize(state.text),
+  },
+  SUMMARIZE: {
+    STATE: (state) => (state.status === 'busy' ? ABORT : { ...state, summary: '', status: 'busy' }),
+    LLM: (state) => (state.status === 'busy' ? ABORT : summarize(state.text)),
+  },
+  SUMMARY: (state, { text }) => ({ ...state, summary: text }),
+  SUMMARIZED: (state, { text }) => ({ ...state, summary: text, status: 'ready' }),
+  // no model on this device: show the excerpt; any other failure: let the user try again
+  NO_SUMMARY: (state, { error }) => ({ ...state, summary: '', status: error.status === 'unavailable' ? 'fallback' : 'ready' }),
+}
+```
+
+- **The summary streams in** through `SUMMARY`, and `SUMMARIZED` ends the busy state.
+- **Degrade, don't hide.** The excerpt is computed in the view from the text, so it needs no model. Where a summary isn't essential, an excerpt is an honest fallback.
+- **Keep prompts short and in `instructions`.** The on-device model is small and has a small context window. Long articles need splitting, or a hosted model.
+
+## What the on-device model can't do
+
+- **No tools.** The Prompt API has no tool calling yet, so `chromePrompt()` doesn't send `tools`. An assistant that operates the app needs a hosted model.
+- **One system prompt.** The Prompt API takes system text only at the start of a session, so `instructions` and every `system` message (wherever it is in the conversation) are joined into that one prompt.
+- **Structured output works.** `output` becomes the Prompt API's `responseConstraint`, and `ok` gets the validated `value`, as with any transport.
+
+## Testing
+
+The LLM fake doesn't care which transport `main.js` uses. Fail a request with the transport's error to test the fallback:
+
+```js
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import Article from './Article.jsx'
+
+it('summarises, and falls back to an excerpt without the model', async () => {
+  const t = renderComponent(Article)
+  await t.respond('LLM', 'Octopuses have three hearts.')
+  expect(t.html()).toContain('Summary:')
+
+  t.simulateEvent('.summarize', 'click')
+  await t.fail('LLM', Object.assign(new Error('the on-device model is unavailable'), { status: 'unavailable' }))
+  expect(t.html()).toContain('Excerpt:')
+  t.dispose()
+})
+```
+
+To test the transport itself, `chromePrompt({ LanguageModel })` takes a stub of the Prompt API instead of the browser's.