sygnal 6.1.1 → 6.2.0

package/dist/guide/adapters.md

@@ -24,7 +24,8 @@ npm install react react-dom
 The React component here is a small one of our own, written with React's `createElement` (the JSX on these pages is Sygnal's); a component from npm is wrapped the same way:
 
 ```js live-file=./Rating.js
-// Rating.js: a React component
+// Rating.js
+// a React component
 import { createElement as h } from 'react'
 
 export function Rating({ value, max, onChange }) {

package/dist/guide/agent.md

@@ -69,6 +69,7 @@ TodoApp.agent = {
 | `label(state)` | A [Collection item](#collection-items)'s label for the model |
 | `untrusted` | `read` returns text users typed (see [Security](#security)). Unset, Sygnal infers it from the strings in the projection |
 | `actions` | The only actions agents may run, by action name |
+| `queries` | Read-only tools that take an input: data too large for `read`, or answers computed from the state ([Queries](#queries)) |
 
 Each entry of `actions`:
 
@@ -79,6 +80,8 @@ Each entry of `actions`:
 | `consequential` | Ask the user before running it |
 | `when(state)` | The tool is offered only while this is true |
 | `idempotent` | A call that changes nothing is a success (`{ ok: true, unchanged: true }`), not an error |
+| `until` | The call answers once the action's result is in state: a resource name, or a function of the state ([Waiting for a result](#waiting-for-a-result-until)) |
+| `timeout` | With `until`: how long to wait, in ms (default 10,000) |
 
 ### Input schemas
 
@@ -109,7 +112,7 @@ In TypeScript, on a component typed with its actions ([TypeScript](https://sygna
 
 ## What agents see
 
-**Tools.** One per listed action, plus `<name>_read` when the declaration has a `read`. The todo app above offers:
+**Tools.** One per listed action and [query](#queries), plus `<name>_read` when the declaration has a `read`. The todo app above offers:
 
 | Tool | Input | Hints |
 |---|---|---|
@@ -131,7 +134,7 @@ Every call, from any kind of agent, goes through the same steps:
 2. **Availability.** A tool whose `when` is false now gets `{ ok: false, error: 'todos_clear_done is not available now' }`.
 3. **Confirmation.** A `consequential` action waits for the user (each consumer asks in its own way). A declined call is `{ ok: false, error: 'the user declined' }`. The target and `when` are checked again after the answer.
 4. **Dispatch.** The action runs with `cause: 'agent'`, through the same queue, reducers and render as a click. It shows in `t.actions`, the DevTools action log and the dev MCP endpoint's `recent_actions` with that cause.
-5. **The result**, after the render: `{ ok: true, state }`, where `state` is the nearest `read` projection (the component's, or for an item, its own or its list's).
+5. **The result**, after the render: `{ ok: true, state }`, where `state` is the nearest `read` projection (the component's, or for an item, its own or its list's). An action with [`until`](#waiting-for-a-result-until) answers later, once its result is in state.
 
 **No-op detection.** A call succeeds when one of the action's handlers had an effect: a reducer changed the state, a driver sink got a value, or an `EFFECT` ran. A call that changed nothing is reported as a failure, not a false success. Here, `SET_FILTER` to the filter already set, on an action without `idempotent`:
 
@@ -158,6 +161,107 @@ A refusal is reported even on an `idempotent` action.
 
 **One at a time.** Calls run serially, in the order the model made them, so each one sees the previous one's result. A model that sends three calls at once gets three results computed in sequence.
 
+## Waiting for a result: `until`
+
+Some actions only start something: a search sets the query, and a [`resources`](./resources.md) entry fetches the results. Right after the action, the results aren't there yet, so the call would answer with `status: 'loading'`, and the model would have to guess or ask again. With `until`, the call answers once the result is in state:
+
+```jsx
+// Shop.jsx
+import { z } from 'zod'
+
+export default function Shop({ state }) {
+  const { status, data } = state.search
+  return (
+    <section>
+      {status === 'loading' && <p>Searching…</p>}
+      <ul className="results">{(data ?? []).map((p) => <li key={p.id}>{p.name}</li>)}</ul>
+    </section>
+  )
+}
+
+Shop.initialState = { query: '' }
+
+Shop.resources = { search: (state) => state.query && { url: '/api/search', query: { q: state.query } } }
+
+Shop.model = { SEARCH: (state, query) => ({ ...state, query }) }
+
+Shop.agent = {
+  name: 'shop',
+  description: 'The product search the user sees',
+  read: (state) => ({ query: state.query, status: state.search.status, results: (state.search.data ?? []).map(({ id, name }) => ({ id, name })) }),
+  actions: {
+    SEARCH: { description: 'Search the catalog; the results show on the page', input: z.string().min(1), until: 'search' },
+  },
+}
+```
+
+`shop_search({ value: 'red shoes' })` now answers with the results the user sees, `{ ok: true, state: { query: 'red shoes', status: 'success', results: [...] } }`, or with `status: 'error'` when the request failed.
+
+- **`until: 'search'`** names one of the component's resources. The call answers once that resource is neither loading nor refreshing, so a [`keepPrevious`](./resources.md) request or a refetch, which keep the status and set `refreshing`, are waited for too. A name the component's `resources` doesn't have is [SYG248](https://sygnal.js.org/reference/errors/#syg248): the call answers at once.
+- **`until: (state) => boolean`** is for a result a reply action writes (a driver request with an `ok` action). The action's own reducer must mark it pending, `status: 'loading'`, so the test is false right after the action: `until: (state) => state.status !== 'loading'`. A throwing `until` ends the wait ([SYG241](https://sygnal.js.org/reference/errors/#syg241)).
+- **The test runs after the action's render and after every render that changed something.** A result already in state answers at once.
+- **No result within `timeout`** (default 10 s): `{ ok: true, pending: true, note, state }`. The note tells the model the result will be in the app state later, where the `chat` behavior's next request shows it.
+- **Calls run one at a time**, so a waiting call delays the model's next one. The [`chat` behavior](#an-in-app-assistant-chat) ends the wait when the user presses Stop or sends a new message (the call answers `pending`), and `agentTools()` has `cancel()` for other consumers.
+- An item that removes itself while its call waits answers `{ ok: true, removed: true, state }`.
+
+The side effect stays where it was: the request goes through `resources` or a driver, and a test answers it with the fetch fake, `await t.respond('HTTP', [...])`. `t.callTool()` waits for it like any agent.
+
+## Queries
+
+`read` goes to the model whole, with every request. That suits a summary, not a table of 5,000 invoices: sending them all costs tokens on every turn, and a model reads a long list badly anyway. A query is a read-only tool that takes an input and answers from the state: the model asks for the overdue invoices of one customer and gets those.
+
+```jsx
+// Invoices.jsx
+import { z } from 'zod'
+
+export default function Invoices({ state }) {
+  return <p className="count">{state.invoices.length} invoices</p>
+}
+
+Invoices.initialState = { invoices: [] }
+
+const Filter = z.object({
+  customer: z.string().optional().describe('The customer name'),
+  overdue: z.boolean().optional(),
+})
+
+Invoices.agent = {
+  name: 'invoices',
+  description: 'The invoices',
+  untrusted: true,
+  read: (state) => ({ count: state.invoices.length }),   // the summary, on every request
+  queries: {
+    // invoices_find({ customer?, overdue? })
+    find: {
+      description: 'The invoices matching a filter, at most 50',
+      input: Filter,
+      run: (state, { customer, overdue }) => state.invoices
+        .filter((i) => (customer === undefined || i.customer === customer) && (overdue === undefined || i.overdue === overdue))
+        .slice(0, 50),
+    },
+    // invoices_total()
+    total: { description: 'The sum of all invoices', run: (state) => state.invoices.reduce((sum, i) => sum + i.total, 0) },
+  },
+}
+```
+
+| Key | What it does |
+|---|---|
+| `description` | What the query returns, for the model |
+| `input` | The schema of its input, as for an action ([Input schemas](#input-schemas)). Without one the query takes no arguments |
+| `when(state)` | The tool is offered only while this is true |
+| `run(state, input)` | The result: a pure, synchronous function of the component's state now and the validated input |
+
+- **A query is a tool named `<name>_<query>`**, marked read-only. It is offered next to the actions, to every kind of agent (the command bar, which picks one action, leaves read-only tools out).
+- **A call validates the input and checks `when`**, as for an action, then returns `{ ok: true, result }` with what `run` returned. Nothing is dispatched, nothing is confirmed, and nothing renders: a query can't change the app.
+- **It must be synchronous.** A `run` that returns a promise (an `async` function, a `fetch`) fails the call and is [SYG246](https://sygnal.js.org/reference/errors/#syg246), as is a query without `run`. Data that has to be loaded belongs to an action: its model entry asks for it (a [`resources`](./resources.md) entry or a driver request), and [`until`](#waiting-for-a-result-until) makes the call answer with the result.
+- **A throw** fails the call with its message and is [SYG241](https://sygnal.js.org/reference/errors/#syg241).
+- **Actions and queries share the tool names.** A query whose snake-case name is an action's (`find` next to `FIND`) is [SYG247](https://sygnal.js.org/reference/errors/#syg247), and only the action is offered.
+- **On a Collection item component**, a query gets the same key parameter as the item's actions (`contact_notes({ id, word })`), and answers from that item's state.
+- **Results are data.** When they hold text users typed, set `untrusted: true` on the declaration: WebMCP then marks the queries with `untrustedContentHint` too ([Security](#security)). Keep results small (filter, then cut): WebMCP cuts a result over 1,500 characters of JSON ([SYG242](https://sygnal.js.org/reference/errors/#syg242)).
+
+In TypeScript, `run`'s `state` is typed from the component; type the input yourself, `run: (state, input: z.infer<typeof Filter>) => …`, since it isn't inferred from `input`.
+
 ## Collection items
 
 An item component's actions don't become one tool per item. They become one tool per action, with a parameter that names the item: an enum of the live keys (the items' `id`s), routed to the item with that key.
@@ -259,7 +363,7 @@ export default {
 }
 ```
 
-```jsx live live-height=380
+```jsx live live-height=380 title="TodoApp.jsx"
 import { z } from 'zod'
 import { Collection } from 'sygnal'
 import { chat, messageText } from 'sygnal/ai'
@@ -361,7 +465,7 @@ In production the provider key belongs on your server: `makeChatDriver({ transpo
 | `prompt` | | The prompt field (its input sets `prompt`) |
 | `stop`, `approve`, `deny`, `regenerate` | | Buttons: their clicks dispatch `STOP`, `APPROVE`, `DENY`, `REGENERATE` |
 | `instructions` | | System instructions: your app's own text |
-| `agent` | the host's and its shown descendants' | Whose declarations become tools: `false` for none, `[Comp, ...]` for only these (inside the host) |
+| `agent` | the host's and its shown descendants' | Whose declarations become tools: `false` for none (a plain chat, [AI Chat](./ai-chat.md#the-same-chat-with-the-chat-behavior)), `[Comp, ...]` for only these (inside the host) |
 | `maxSteps` | `8` | The most requests per turn; tool calls in a reply past it are not run |
 | `sink` | `'LLM'` | The chat driver's name |
 | `model`, `transportOptions` | | A model id, and extra request keys for the transport |
@@ -377,7 +481,7 @@ The slice, `state.assistant` for `uses = { assistant: chat(...) }`:
 | `pending` | A consequential call waiting for `APPROVE` / `DENY`: `{ tool, component, action, description, input, key?, label? }`, else `null` |
 | `error` | The last failure's message, else `null` |
 
-Actions, as `'assistant.X'`: `SEND` (the form's submit; or dispatch it with the text as data), `STOP` (aborts the reply, keeps the text so far, declines a waiting call), `REGENERATE` (sends the last user message again), `APPROVE`, `DENY`, and `DONE` (the turn is over: `{ message, text, finishReason, usage, steps }`; a host entry `'assistant.DONE'` runs after the behavior's).
+Actions, as `'assistant.X'`: `SEND` (the form's submit; or dispatch it with the text as data), `STOP` (aborts the reply, keeps the text so far, declines a waiting call, and answers a call waiting on [`until`](#waiting-for-a-result-until) as pending), `REGENERATE` (sends the last user message again), `APPROVE`, `DENY`, and `DONE` (the turn is over: `{ message, text, finishReason, usage, steps }`; a host entry `'assistant.DONE'` runs after the behavior's).
 
 **The markup belongs to the host's view.** A behavior listens to selectors in its host's own view, like every intent ([SYG104](https://sygnal.js.org/reference/errors/#syg104)): elements rendered inside a child component are out of its reach. So the panel is a plain function the host's view calls, `{assistantPanel(state.assistant)}`, not a `<AssistantPanel />` component. A function can still live in its own file and be shared.
 
@@ -414,7 +518,7 @@ export default {
 }
 ```
 
-```jsx live live-height=300
+```jsx live live-height=300 title="Commands.jsx"
 import { z } from 'zod'
 import { Collection } from 'sygnal'
 import { commandBar } from 'sygnal/ai'
@@ -581,6 +685,8 @@ it('is operable by agents', async () => {
 ```
 
 - `t.tools()` lists the offered tools, plus any declared tool that can't be offered (SYG240) with its `error`.
+- A [query](#queries) is called the same way: `await t.callTool('invoices_find', { customer: 'Acme' })` resolves with `{ ok: true, result }`.
+- A call to an action with [`until`](#waiting-for-a-result-until) resolves once its result is in state: start it, answer the request (`await t.respond('HTTP', data)`), then await it. Under `vi.useFakeTimers()`, advancing past `timeout` gives `{ ok: true, pending: true }`.
 - `t.callTool(name, args, { confirm })` resolves with the [call result](#the-call-rules) after the render. A consequential tool without `confirm` throws, so a test can't approve one by accident.
 - `t.agentContext()` returns what the model sees: one entry per declaration with a `read`, keyed by the declaration's `name`, holding what its `read` returned. That is why the example above reads `todos.todos`: the declaration is named `todos`, and its `read` returns `{ todos, filter }`. An item declaration's entry is an array with one projection per live item, each with its `id` (`{ todo: [{ id: 1, done: false }] }` for `read: (s) => ({ done: s.done })`).
 

package/dist/guide/ai-chat.md

@@ -49,7 +49,7 @@ export default {
 }
 ```
 
-```jsx live live-height=260
+```jsx live live-height=260 title="Chat.jsx"
 import { ABORT } from 'sygnal'
 import { messageText } from 'sygnal/ai'
 
@@ -71,7 +71,6 @@ function Chat({ state }) {
   )
 }
 
-const userSays = (text) => ({ role: 'user', parts: [{ type: 'text', text }] })
 const ask = (messages) => ({ messages, key: 'reply', delta: 'DELTA', ok: 'DONE', error: 'FAILED' })
 
 Chat.initialState = { messages: [], prompt: '', draft: '', status: 'ready', error: null }
@@ -85,16 +84,16 @@ Chat.intent = ({ DOM }) => ({
 Chat.model = {
   // the first question, as soon as the demo shows
   BOOTSTRAP: {
-    STATE: (state) => ({ ...state, messages: [userSays('How does a reply stream?')], status: 'streaming' }),
-    LLM: () => ask([userSays('How does a reply stream?')]),
+    STATE: (state) => ({ ...state, messages: [{ role: 'user', content: 'How does a reply stream?' }], status: 'streaming' }),
+    LLM: () => ask([{ role: 'user', content: 'How does a reply stream?' }]),
   },
   TYPE: (state, prompt) => ({ ...state, prompt }),
   SEND: {
     STATE: (state) => (state.prompt.trim()
-      ? { ...state, messages: [...state.messages, userSays(state.prompt)], prompt: '', status: 'streaming', error: null }
+      ? { ...state, messages: [...state.messages, { role: 'user', content: state.prompt }], prompt: '', status: 'streaming', error: null }
       : ABORT),
     // sinks see the state before the action: the conversation plus the prompt being sent
-    LLM: (state) => (state.prompt.trim() ? ask([...state.messages, userSays(state.prompt)]) : ABORT),
+    LLM: (state) => (state.prompt.trim() ? ask([...state.messages, { role: 'user', content: state.prompt }]) : ABORT),
   },
   STOP: {
     // keep the text that arrived; nothing arrives after the abort
@@ -114,12 +113,57 @@ Chat.model = {
 
 What the component does:
 
-- **The conversation is state.** `messages` holds the user's messages and the model's replies. Every request sends the whole conversation: models are stateless, so the history goes with each turn.
+- **The conversation is state.** `messages` holds the user's messages and the model's replies. Every request sends the whole conversation: models are stateless, so the history goes with each turn. A message you write yourself can be `{ role: 'user', content: text }`: the driver, `messageText()` and every transport accept that short form.
 - **`SEND` has two sinks.** `STATE` adds the user's message, `LLM` sends the request. Both see the state from before the action ([Model](https://sygnal.js.org/guide/model/#sinks-see-the-state-before-the-action)), so the `LLM` sink builds the message list with the prompt itself.
 - **`DELTA` shows the reply so far.** Its `text` is all the text received, not just the new piece, so the reducer only replaces `draft`.
 - **`DONE` gets the finished message** and appends it to the conversation as is.
 - **`STOP` aborts the request** by its key. Nothing arrives after an abort, not even `FAILED`.
 
+### The same chat with the `chat` behavior
+
+The component above shows how the driver works. For a conversation in your app, use the `chat` behavior from `sygnal/ai` instead: it holds the conversation, sends the requests, and handles streaming, Stop, failures and Retry. With `agent: false` it sends no tools, so it is a plain chat. Its markup stays in your view, and its options name the elements to listen to.
+
+This demo asks the same first question. Press **Stop** while it streams to keep the partial reply.
+
+```jsx live live-height=260
+import { chat, messageText } from 'sygnal/ai'
+
+function Chat({ state }) {
+  const c = state.chat
+  const busy = c.status === 'submitted' || c.status === 'streaming'
+  return (
+    <section className="chat">
+      <ol className="messages" aria-live="polite">
+        {c.messages.map((m) => <li key={m.id} className={m.role}><b>{m.role}:</b> {messageText(m)}</li>)}
+        {c.draft && <li className="assistant streaming"><b>assistant:</b> {c.draft}</li>}
+      </ol>
+      {c.error && <p role="alert">{c.error} <button type="button" className="retry">Retry</button></p>}
+      <form className="ask">
+        <label>Message <input className="prompt" value={c.prompt} /></label>
+        <button type="submit" disabled={busy}>Send</button>
+        <button type="button" className="stop" hidden={!busy}>Stop</button>
+      </form>
+    </section>
+  )
+}
+
+Chat.uses = {
+  chat: chat({ agent: false, form: '.ask', prompt: '.prompt', stop: '.stop', regenerate: '.retry' }),
+}
+
+Chat.model = {
+  // the first question, as soon as the demo shows
+  BOOTSTRAP: { EFFECT: (state, data, next) => next('chat.SEND', 'How does a reply stream?') },
+}
+```
+
+- **`state.chat` is the behavior's slice**: `messages`, `prompt`, `draft`, `status` (`'ready'`, `'submitted'`, `'streaming'` or `'error'`) and `error`.
+- **Retry doesn't repeat the question.** `regenerate` sends the conversation again up to the last user message, without a second copy of it, and drops the failed partial reply.
+- **Every message has an `id`**, the user's too, so `key={m.id}` works and a server can store the conversation by message id.
+- **The host can drive it.** `next('chat.SEND', text)` sends a message, and a `'chat.DONE'` entry in the host's model runs when a reply is finished.
+
+Use the driver directly for one-off requests, like a summary or [structured output](#structured-output), or when you need your own state shape. The [`chat` behavior](./agent.md#options-and-state) documents its options, state and actions. Without `agent: false` it also runs your components' [agent tools](./agent.md).
+
 ## Requests
 
 A request is an object sent to the `LLM` sink. The driver passes it to the transport as is, so a transport's own options can go in it too.
@@ -197,7 +241,7 @@ export default {
 }
 ```
 
-```jsx live live-height=200
+```jsx live live-height=200 title="QuickAdd.jsx"
 import { z } from 'zod'
 import { ABORT } from 'sygnal'
 
@@ -296,7 +340,7 @@ export default {
 }
 ```
 
-```jsx live live-height=260
+```jsx live live-height=260 title="Shopping.jsx"
 import { ABORT } from 'sygnal'
 import { messageText, withToolResults } from 'sygnal/ai'
 
@@ -308,7 +352,6 @@ const tools = {
 }
 
 const said = (m) => messageText(m) || m.parts.filter((p) => p.type.startsWith('tool-')).map((p) => `(called ${p.type.slice(5)})`).join(' ')
-const userSays = (text) => ({ role: 'user', parts: [{ type: 'text', text }] })
 const ask = (messages) => ({ messages, tools, key: 'reply', delta: 'DELTA', tool: 'TOOL', ok: 'DONE', error: 'FAILED' })
 
 // the reply with each add_item call answered: the output goes into the call's tool-add_item part
@@ -343,9 +386,9 @@ Shopping.model = {
   TYPE: (state, prompt) => ({ ...state, prompt }),
   SEND: {
     STATE: (state) => (state.prompt.trim()
-      ? { ...state, messages: [...state.messages, userSays(state.prompt)], prompt: '', status: 'streaming', error: null }
+      ? { ...state, messages: [...state.messages, { role: 'user', content: state.prompt }], prompt: '', status: 'streaming', error: null }
       : ABORT),
-    LLM: (state) => (state.prompt.trim() ? ask([...state.messages, userSays(state.prompt)]) : ABORT),
+    LLM: (state) => (state.prompt.trim() ? ask([...state.messages, { role: 'user', content: state.prompt }]) : ABORT),
   },
   DELTA: (state, { text }) => ({ ...state, draft: text }),
   // runs the call as it arrives; the model's input is unchecked, so check it
@@ -464,8 +507,8 @@ The transports refuse the other mistake for you. In a browser, a request with an
 
 The component never changes. Only the transport in `main.js` does: Ollama while you develop, your AI SDK route in production.
 
-```js
-// main.js: development, a local model
+```js title="main.js (development)"
+// a local model, through Ollama
 import { run } from 'sygnal'
 import { makeChatDriver, openResponses } from 'sygnal/ai'
 import Chat from './Chat.jsx'
@@ -475,8 +518,8 @@ run(Chat, {
 })
 ```
 
-```js
-// main.js: production, the AI SDK route above
+```js title="main.js (production)"
+// the AI SDK route above
 import { run } from 'sygnal'
 import { makeChatDriver, uiMessageStream } from 'sygnal/ai'
 import Chat from './Chat.jsx'
@@ -489,6 +532,7 @@ run(Chat, {
 Or pick one at build time, so the development transport isn't in the production bundle:
 
 ```js
+// main.js
 import { run } from 'sygnal'
 import { makeChatDriver, openResponses, uiMessageStream } from 'sygnal/ai'
 import Chat from './Chat.jsx'

package/dist/guide/ai-decisions.md

@@ -157,7 +157,7 @@ export default {
 }
 ```
 
-```jsx live live-height=220
+```jsx live live-height=220 title="Ticket.jsx"
 import { ABORT } from 'sygnal'
 import { decide, choice, noul } from 'sygnal/ai'
 

package/dist/guide/behaviors.md

@@ -35,7 +35,7 @@ export default {
 }
 ```
 
-```jsx live
+```jsx live title="TaskList.jsx"
 import { pager } from 'sygnal'
 
 export function TaskList({ state }) {

package/dist/guide/error-boundaries.md

@@ -123,7 +123,8 @@ Compared with React, which unmounts the whole tree when an error isn't caught by
 In a [Vike](https://sygnal.js.org/integration/vike/) app, the hook is the `sygnalOnError` config: define it in `+sygnalOnError.js` (or in `+config.js`). It is passed to `renderToString` on the server and to `run()` in the browser. (Vike's own `onError` is a different hook: server-only, called with `(error, pageContext)` for any error during rendering.)
 
 ```js
-// pages/+sygnalOnError.js: used by renderToString on the server and by run() in the browser
+// pages/+sygnalOnError.js
+// used by renderToString on the server and by run() in the browser
 export default function sygnalOnError(error, { componentName, action, phase }) {
   console.error('[' + phase + ']', componentName, action, error)
 }

package/dist/guide/forms.md

@@ -21,7 +21,7 @@ export default {
 
 Validation, a list of rows the user adds and removes, the submit to the server, the pending button, and the server's errors:
 
-```jsx live
+```jsx live title="Signup.jsx"
 import { form } from 'sygnal'
 import { z } from 'zod'
 

package/dist/guide/http.md

@@ -24,7 +24,7 @@ export default {
 }
 ```
 
-```jsx live
+```jsx live title="Quote.jsx"
 import { ABORT } from 'sygnal'
 
 function Quote({ state }) {
@@ -84,7 +84,7 @@ export default {
 }
 ```
 
-```jsx live
+```jsx live title="Search.jsx"
 import { ABORT, debounce } from 'sygnal'
 
 function Search({ state }) {
@@ -219,7 +219,7 @@ export default {
 }
 ```
 
-```jsx live
+```jsx live title="Todos.jsx"
 function Todos({ state }) {
   return (
     <div>
@@ -261,7 +261,7 @@ export default {
 }
 ```
 
-```jsx live
+```jsx live title="Profile.jsx"
 import { ABORT } from 'sygnal'
 
 function Profile({ state }) {

package/dist/guide/mcp-apps.md

@@ -8,7 +8,8 @@ In Sygnal that bridge is a driver. The view is an ordinary component.
 ## The view
 
 ```jsx
-// App.jsx: the view of the get_forecast tool
+// App.jsx
+// the view of the get_forecast tool
 function App({ state }) {
   return (
     <main>
@@ -168,7 +169,8 @@ run(App, { MCP: makeMcpAppDriver({ tools: agentTools }) })
 ```
 
 ```jsx
-// App.jsx: what the model may do in the view
+// App.jsx
+// what the model may do in the view
 import { z } from 'zod'
 
 App.model = {

package/dist/guide/persistence.md

@@ -214,7 +214,7 @@ The object you pass is used as the storage, not copied: writes land in it, and t
 
 With `format: 'plain'` the entries are the stored keys themselves, both in the `storage` option and from `t.storage(key)`:
 
-```jsx
+```jsx title="Note.test.jsx"
 it('saves the draft as { title, body }', async () => {
   const t = renderComponent(Note, { storage: { 'note-draft': { title: 'Groceries', body: '' } } })
   await t.ready()

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

@@ -34,7 +34,7 @@ export default {
 }
 ```
 
-```jsx live live-height=420
+```jsx live live-height=420 title="NewContact.jsx"
 import { z } from 'zod'
 import { ABORT, form } from 'sygnal'
 

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

@@ -68,7 +68,7 @@ export default {
 }
 ```
 
-```jsx live live-height=260
+```jsx live live-height=260 title="Article.jsx"
 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.'

package/dist/guide/recipes/ai-support-inbox.md

@@ -66,7 +66,7 @@ export default {
 }
 ```
 
-```jsx live live-height=280
+```jsx live live-height=280 title="Inbox.jsx"
 import { z } from 'zod'
 import { ABORT, Collection } from 'sygnal'
 import { decide, choice, noul } from 'sygnal/ai'

package/dist/guide/resources.md

@@ -17,7 +17,7 @@ export default {
 }
 ```
 
-```jsx live
+```jsx live title="Quote.jsx"
 function Quote({ state }) {
   const { status, data, refreshing } = state.quote
   return (
@@ -126,7 +126,8 @@ export const router = makeRouter({
 ```
 
 ```jsx
-// TaskPage.jsx: the page reads the same request
+// TaskPage.jsx
+// the page reads the same request
 TaskPage.resources = { task: (state) => routeData.task(state.route)[0] }
 
 // App.jsx: { prefetch } on the ROUTER sink, e.g. on hover, warms the route's data
@@ -151,8 +152,7 @@ A seeded entry keeps its `updatedAt`, so it stays fresh for `staleTime` after th
 
 A `+data` hook seeds a cache and puts its snapshot on `pageContext.queryCache`. The Sygnal Vike extension renders the page's resources from it, passes it to the client, and hydrates the cache of every fetch driver in the `drivers` config before the page runs. On client-side navigation it does the same with the next page's snapshot.
 
-```javascript
-// pages/quote/@id/+data.js
+```javascript title="pages/quote/@id/+data.js"
 import { queryCache } from 'sygnal'
 
 export async function data(pageContext) {
@@ -166,14 +166,14 @@ export async function data(pageContext) {
 ```
 
 ```javascript
-// pages/+drivers.js: client-only; one cache for the session
+// pages/+drivers.js
+// client-only; one cache for the session
 import { makeFetchDriver, queryCache } from 'sygnal'
 
 export default { HTTP: makeFetchDriver({ cache: queryCache({ staleTime: 30000 }) }) }
 ```
 
-```jsx
-// pages/quote/@id/+Page.jsx
+```jsx title="pages/quote/@id/+Page.jsx"
 function Page({ state }) {
   const { status, data } = state.quote
   return <p className="quote">{status === 'success' ? data.text : 'Loading…'}</p>
@@ -294,7 +294,7 @@ export default {
 .rows.stale { opacity: 0.5; }
 ```
 
-```jsx live
+```jsx live title="Pages.jsx"
 function Pages({ state }) {
   const { data, refreshing } = state.list
   return (
@@ -373,7 +373,7 @@ export default {
 }
 ```
 
-```jsx live
+```jsx live title="App.jsx"
 const statusOf = (r) => (r?.status === 'loading' ? 'Loading…' : r?.refreshing ? 'Updating…' : '')
 
 function App({ state }) {
@@ -426,7 +426,8 @@ App.model = {
 ```
 
 ```javascript
-// main.js; the tests use renderComponent(App, { http: { cache: queryCache() } })
+// main.js
+// the tests use renderComponent(App, { http: { cache: queryCache() } })
 run(App, { HTTP: makeFetchDriver({ cache: queryCache() }) })
 ```
 

package/dist/guide/ui/combobox.md

@@ -49,7 +49,7 @@ export default {
 }
 ```
 
-```jsx live live-height=240
+```jsx live live-height=240 title="Search.jsx"
 import { Combobox } from 'sygnal/ui/combobox'
 
 function Search({ state }) {

package/dist/guide/undo.md

@@ -112,7 +112,7 @@ export default {
 }
 ```
 
-```jsx live
+```jsx live title="Editor.jsx"
 import { undoable } from 'sygnal'
 
 export function Editor({ state }) {

package/dist/guide/web-components.md

@@ -152,6 +152,7 @@ defineElement('score-card', ScoreCard, {
 ```
 
 ```html
+<!-- index.html -->
 <score-card title="Pasta" score="3"></score-card>
 <script>
   document.querySelector('score-card').addEventListener('score-change', (e) => console.log(e.detail.score))

package/dist/guide/webmcp.md

@@ -43,8 +43,7 @@ Chrome 153 has WebMCP behind a flag: enable **WebMCP for testing** at `chrome://
 
 **Other browsers: the polyfill.** [`@mcp-b/webmcp-polyfill`](https://www.npmjs.com/package/@mcp-b/webmcp-polyfill) installs a `document.modelContext` in any browser, so an agent extension that speaks it can call your tools. Load it before `experimentalExposeWebMcp`, in development only:
 
-```js
-// main.js (development)
+```js title="main.js (development)"
 import { run } from 'sygnal'
 import { experimentalExposeWebMcp } from 'sygnal/ai'
 import TodoApp from './TodoApp.jsx'