sygnal 5.4.0 → 6.1.0

package/dist/guide/inputs.md

@@ -0,0 +1,173 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Inputs, Labels and Focus
+
+How Sygnal treats the value of a field, how to give labels and descriptions ids that stay unique, and how to focus a field when it appears. For forms with validation, see [Forms](./forms.md).
+
+## Controlled Inputs
+
+An `<input>`, `<textarea>` or `<select>` with a `value` prop (or a checkbox/radio with `checked`) is **controlled**: on every render, Sygnal writes the value from your view into the element, like React does. That keeps the field in sync with state (clearing a field after "Add" works even when both happen in the same tick), but it means the field must update state as the user types. Otherwise any re-render resets what they typed.
+
+A form-associated custom element (one whose class has `static formAssociated = true`, such as Web Awesome's `<wa-input>` or `<wa-rating>`) with a `value` or `checked` prop is controlled the same way.
+
+To refuse what the user entered, return `ABORT` (or the state unchanged): the state stays as it was, and because the action came from an `input` or `change` event, the component still renders, so the field shows the state's value again. A digits-only field:
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+function Pin({ state }) {
+  return <input className="pin" aria-label="PIN" inputMode="numeric" value={state.pin} />
+}
+
+Pin.initialState = { pin: '' }
+Pin.intent = ({ DOM }) => ({ PIN: DOM.input('.pin').value() })
+Pin.model = {
+  PIN: (state, pin) => /^\d{0,6}$/.test(pin) ? { ...state, pin } : ABORT,
+}
+```
+
+This applies only while the `input` or `change` event is being handled (an intent that delays the action, with `debounce` for example, gets no extra render). `ABORT` from any other action (a click, a timer, a reply) still renders nothing.
+
+Pick one of two patterns:
+
+**Controlled**: bind `value` to state and update state on `input`:
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+function NewTodo({ state }) {
+  return (
+    <div>
+      <input className="new-todo" aria-label="New todo" value={state.draft} />
+      <button className="add">Add</button>
+      <ul>{state.items.map((item) => <li>{item}</li>)}</ul>
+    </div>
+  )
+}
+
+NewTodo.initialState = { draft: '', items: [] }
+
+NewTodo.intent = ({ DOM }) => ({
+  DRAFT: DOM.input('.new-todo').value(),
+  ADD:   DOM.click('.add'),
+})
+
+NewTodo.model = {
+  DRAFT: (state, draft) => ({ ...state, draft }),
+  ADD:   (state) => state.draft.trim()
+    ? { ...state, items: [...state.items, state.draft.trim()], draft: '' }
+    : ABORT,
+}
+```
+
+**Uncontrolled**: leave out `value`, and read the element's value from the event when you need it (on blur, Enter or submit), or with [`processForm()`](./forms-reference.md#processform):
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+function Rename({ state }) {
+  return <input className="rename" aria-label="Title" placeholder={state.title} />
+}
+
+Rename.initialState = { title: 'Untitled' }
+
+Rename.intent = ({ DOM }) => ({
+  RENAME: DOM.keydown('.rename').filter(e => e.key === 'Enter').map(e => e.target.value),
+})
+
+Rename.model = {
+  RENAME: (state, title) => title ? { ...state, title } : ABORT,
+}
+```
+
+What doesn't work is a bound `value` with no `input`/`change` listener, for example a "save on blur" field that only listens to `blur`: the first re-render while the user types puts the old value back. `sygnal-check` reports that as [SYG111](https://sygnal.js.org/reference/errors/#syg111). Literal values (`value=""`) are controlled too, so they reset the field on every render as well.
+
+`value={null}` (or `checked={null}`) clears the field and keeps it controlled; leaving the prop out makes the field uncontrolled, so whatever the user typed stays.
+
+## Labels and ids: uid()
+
+Every field needs a label ([SYG702](./accessibility.md#syg702-form-field-without-a-label)). Wrapping the field in a `<label>` needs no id. When the label sits elsewhere, or a hint is attached with `aria-describedby`, the elements need ids, and a literal `id="email"` is repeated as soon as the component renders twice. Use the `uid` view prop instead:
+
+```jsx
+function Signup({ state, uid }) {
+  return (
+    <form className="signup">
+      <label for={uid('email')}>Email</label>
+      <input id={uid('email')} type="email" className="email" value={state.email} aria-describedby={uid('email-help')} />
+      <p id={uid('email-help')}>We only use it to sign you in.</p>
+    </form>
+  )
+}
+
+Signup.initialState = { email: '' }
+Signup.intent = ({ DOM }) => ({ EMAIL: DOM.input('.email').value() })
+Signup.model = { EMAIL: (state, email) => ({ ...state, email }) }
+```
+
+`uid()` returns an id for this component instance, and `uid('email')` one derived from it (for example `u-email` at the root, longer further down the tree). Ids come from the instance's position in the tree and its Collection item key, never from a counter, so they:
+
+- differ between two instances of the component, and between Collection items;
+- stay the same across renders, and move with their item when a Collection is reordered;
+- are the same on the server and after hydration ([SSR](./ssr.md#stable-ids-uid)).
+
+`uid` is also on the reducers' `props` argument. It is a reserved prop: a parent can't pass its own `uid` to a child ([SYG106](https://sygnal.js.org/reference/errors/#syg106)). `sygnal-check` matches `for={uid('email')}` with `id={uid('email')}` ([SYG708](./accessibility.md#syg708-label-or-aria-reference-to-an-id-that-isnt-rendered)).
+
+## Focus Management
+
+Sygnal components are pure functions — they never touch real DOM elements. But web apps frequently need to focus an element programmatically, for example when an input appears for inline editing.
+
+The `autoFocus` and `autoSelect` JSX props handle this declaratively. No imperative code in your view, no drivers, no hooks.
+
+### autoFocus
+
+Add `autoFocus={true}` to any element. When that element enters the DOM, it receives focus automatically:
+
+```jsx
+function SearchBar({ state }) {
+  return (
+    <div>
+      {state.isOpen &&
+        <input autoFocus={true} className="search-input" placeholder="Search..." />
+      }
+    </div>
+  )
+}
+```
+
+### autoSelect
+
+Add `autoSelect={true}` alongside `autoFocus` to select all text in the element after focusing. This is ideal for edit-in-place patterns where the user typically wants to replace the existing value:
+
+```jsx live
+function EditableTitle({ state }) {
+  return (
+    <div>
+      {state.isEditing
+        ? <input autoFocus={true} autoSelect={true} value={state.draft} className="title-input" aria-label="Title" />
+        : <h2 className="title">{state.title}</h2>
+      }
+    </div>
+  )
+}
+
+EditableTitle.initialState = { title: 'Double-click to rename', isEditing: false, draft: '' }
+
+EditableTitle.intent = ({ DOM }) => ({
+  EDIT:  DOM.dblclick('.title'),
+  DRAFT: DOM.input('.title-input').value(),
+  SAVE:  DOM.blur('.title-input'),
+})
+
+EditableTitle.model = {
+  EDIT:  (state) => ({ ...state, isEditing: true, draft: state.title }),
+  DRAFT: (state, draft) => ({ ...state, draft }),
+  SAVE:  (state) => ({ ...state, isEditing: false, title: state.draft }),
+}
+```
+
+When the user double-clicks to edit, the input appears focused with all text selected — ready to type a replacement.
+
+### How It Works
+
+These props are intercepted by the JSX pragma before they reach the DOM. Under the hood, a snabbdom `insert` hook calls `.focus()` (and optionally `.select()`) when the element is first inserted. The props are never passed to the actual DOM element.
+
+If you also set a manual `hook={{ insert: fn }}` on the same element, both hooks run — yours first, then the focus behavior.

package/dist/guide/mcp-apps.md

@@ -0,0 +1,272 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# MCP Apps
+
+An [MCP App](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp) is an MCP server tool that comes with an interactive view. When the model calls the tool, a host that supports MCP Apps (Claude, ChatGPT, VS Code, Goose, MCPJam, ...) shows the view in the conversation, in a sandboxed iframe. The view and the host talk JSON-RPC over `postMessage`: the host sends the tool's input and result, and the view can call the server's tools, tell the model what the user did, or post a message.
+
+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
+function App({ state }) {
+  return (
+    <main>
+      <h1>{state.city ? `Forecast for ${state.city}` : 'Forecast'}</h1>
+      <p role="status">{state.status === 'loading' ? 'Loading…' : ''}</p>
+      <ul className="days">
+        {state.days.map((day) => (
+          <li key={day.date}>
+            <button type="button" className="day" data={{ date: day.date }} aria-pressed={day.date === state.selected}>
+              {day.date}: {day.sky}, {day.high}° / {day.low}°
+            </button>
+          </li>
+        ))}
+      </ul>
+      <button type="button" className="refresh" disabled={!state.city}>Refresh</button>
+      <button type="button" className="ask" disabled={!state.selected}>Ask about this day</button>
+    </main>
+  )
+}
+
+App.initialState = { city: '', days: [], selected: null, status: 'waiting' }
+
+App.intent = ({ DOM, MCP }) => ({
+  INPUT: MCP.select('tool-input'),     // the arguments the model called the tool with
+  RESULT: MCP.select('tool-result'),   // the server tool's result
+  REFRESH: DOM.click('.refresh'),
+  PICK: DOM.click('.day').data('date'),
+  ASK: DOM.click('.ask'),
+})
+
+App.model = {
+  INPUT: (state, args) => ({ ...state, city: args.city ?? state.city, status: 'loading' }),
+  RESULT: (state, result) => ({ ...state, status: 'ready', days: result.structuredContent?.days ?? [], selected: null }),
+  // call the server's tool again from the view; the result comes back as RESULT
+  REFRESH: {
+    STATE: (state) => ({ ...state, status: 'loading' }),
+    MCP: (state) => ({ callTool: 'get_forecast', args: { city: state.city }, ok: 'RESULT' }),
+  },
+  // tell the model what the user picked: it reads it on its next turn
+  PICK: {
+    STATE: (state, date) => ({ ...state, selected: date }),
+    MCP: (state, date) => ({ updateModelContext: { city: state.city, selectedDay: state.days.find((d) => d.date === date) } }),
+  },
+  // post a message to the conversation, as the user
+  ASK: { MCP: (state) => ({ message: `What should I pack for ${state.city} on ${state.selected}?` }) },
+}
+
+export default App
+```
+
+```js
+// main.js
+import { run } from 'sygnal'
+import { makeMcpAppDriver } from 'sygnal/ai'
+import App from './App.jsx'
+
+run(App, { MCP: makeMcpAppDriver({ appInfo: { name: 'forecast', version: '1.0.0' } }) })
+```
+
+The driver does the `ui/initialize` handshake with the host when the app starts. Requests made before it completes wait for it; with no host (the page opened directly, or server rendering) every request gets its `error` action.
+
+## The driver
+
+**Sources**, in the intent:
+
+| `MCP.select(...)` | Delivers |
+|---|---|
+| `'tool-input'` | The arguments the model called the tool with |
+| `'tool-input-partial'` | The same, while the model is still writing them (to show something early) |
+| `'tool-result'` | The tool's result, an MCP `CallToolResult`: `{ content, structuredContent?, isError? }` |
+| `'tool-cancelled'` | The call was cancelled: `{ reason? }` |
+| `'host-context-changed'` | The host context: `theme`, `displayMode`, `availableDisplayModes`, `locale`, `timeZone`, `containerDimensions`, `styles`, ... First the handshake's, then after every change (merged) |
+| `'teardown'` | The host is about to remove the view; it waits for the actions this causes |
+| `'host'` | The handshake's answer: `{ hostInfo, hostCapabilities, protocolVersion }`. `hostCapabilities` says what the host supports (`downloadFile`, `serverResources`, `logging`, `sampling`, `openLinks`, ...) |
+
+The latest tool input, tool result, host context and `host` are replayed to a component that subscribes later, so a component that appears after they arrived still gets them.
+
+**Sinks**, in the model. Reply actions (`ok`, `error`) go back to the component that sent the request, as with the [fetch driver](./http.md):
+
+| Value | Does |
+|---|---|
+| `{ callTool: 'name', args, ok, error }` | Calls a tool on the MCP server through the host. `ok` gets the `CallToolResult`; `error` gets `{ error, code?, result?, request }` (a JSON-RPC error, or a result with `isError: true`) |
+| `{ updateModelContext: value }` | Tells the model something, for its next turn: a string (one text block), content blocks, or an object (`structuredContent`) |
+| `{ message: 'text' }` | Posts a message to the conversation as the user (a string or content blocks) |
+| `{ openLink: 'https://…' }` | Asks the host to open a link |
+| `{ displayMode: 'fullscreen' }` | Asks for `'inline'`, `'fullscreen'` or `'pip'`; `ok` gets `{ mode }`, the mode the host chose |
+| `{ downloadFile: contents }` | Asks the host to save a file (the iframe can't download itself; the host asks the user). `contents`: `{ uri, mimeType, text }` (or `blob`, base64), or MCP `resource` / `resource_link` blocks, one or an array. `error` runs when the host refused or the user cancelled |
+| `{ readResource: 'uri' }` | Reads a resource of the MCP server through the host; `ok` gets `{ contents }` |
+| `{ listResources: true }` | Lists the server's resources (`{ cursor }` for the next page); `ok` gets `{ resources, nextCursor? }` |
+| `{ createMessage: 'prompt' }` | Asks the host's model for a completion (MCP sampling): a string is one user message, or pass the MCP params (`messages`, `maxTokens`, `systemPrompt`, ...); `maxTokens` defaults to 1024. `ok` gets `{ role, content, model }`. The host may ask the user first or refuse |
+| `{ log: data, level?, logger? }` | A log line for the host's logs (`notifications/message`; not shown to the model). `level`: `'debug'` … `'emergency'`, default `'info'` |
+| `{ requestTeardown: true }` | Asks the host to close the view. If it agrees, it sends `teardown` as usual |
+
+`log` and `requestTeardown` are notifications: there is no answer, and `ok` runs once they are sent.
+
+`makeMcpAppDriver(options)`:
+
+| Option | Default | |
+|---|---|---|
+| `appInfo` | `{ name: document.title, version: '0.0.0' }` | The view's name and version in the handshake |
+| `availableDisplayModes` | | The display modes the view supports |
+| `autoResize` | `true` | Reports the document's size to the host when it changes, so the iframe fits the content |
+| `tools` | | `agentTools`: offer the view's `agent` tools to the host ([below](#the-views-own-tools)) |
+| `confirm` | declined | With `tools`: consequential calls run when this resolves `true` |
+| `protocolVersion` | `'2026-01-26'` | The MCP Apps protocol version offered |
+
+**Files, resources and the host's model.** Check `hostCapabilities` from `MCP.select('host')` before offering what a host may not support:
+
+```jsx
+function Export({ state }) {
+  return (
+    <div>
+      {state.canDownload ? <button className="csv">Download CSV</button> : null}
+      {state.canSample ? <button className="summary">Summarize</button> : null}
+      <p className="summary-text">{state.summary}</p>
+    </div>
+  )
+}
+
+Export.initialState = { days: [], canDownload: false, canSample: false, summary: '' }
+
+Export.intent = ({ DOM, MCP }) => ({
+  HOST: MCP.select('host'),
+  CSV: DOM.click('.csv'),
+  SUMMARIZE: DOM.click('.summary'),
+})
+
+Export.model = {
+  HOST: (state, { hostCapabilities }) => ({ ...state, canDownload: !!hostCapabilities.downloadFile, canSample: !!hostCapabilities.sampling }),
+  CSV: {
+    MCP: (state) => ({
+      downloadFile: { uri: 'file:///forecast.csv', mimeType: 'text/csv', text: state.days.map((d) => `${d.date},${d.high}`).join('\n') },
+      error: 'FAILED',
+    }),
+  },
+  SUMMARIZE: {
+    MCP: (state) => ({ createMessage: `Summarize this forecast in one sentence: ${JSON.stringify(state.days)}`, ok: 'SUMMARY', error: 'FAILED' }),
+  },
+  SUMMARY: (state, result) => ({ ...state, summary: result.content.text }),
+  FAILED: (state, { error }) => ({ ...state, summary: error }),
+}
+```
+
+**Theme and size.** Follow `host-context-changed` for the host's `theme` (and its `styles.variables`, CSS custom properties the host suggests), so the view matches the conversation around it. Keep the view compact for `inline` mode; offer full screen with `{ displayMode: 'fullscreen' }` when `availableDisplayModes` includes it.
+
+## The view's own tools
+
+The model sees the server's tools. With `tools: agentTools`, the view also offers its components' [`agent` declarations](./agent.md) to the host as tools of its own, so the model can operate the view while it is shown: select a day, change units, open a detail. Calls go through the same [call rules](./agent.md#the-call-rules) as any agent's.
+
+```js
+// main.js
+import { run } from 'sygnal'
+import { makeMcpAppDriver, agentTools } from 'sygnal/ai'
+import App from './App.jsx'
+
+run(App, { MCP: makeMcpAppDriver({ tools: agentTools }) })
+```
+
+```jsx
+// App.jsx: what the model may do in the view
+import { z } from 'zod'
+
+App.model = {
+  // ...the entries above, plus:
+  SELECT_DAY: (state, date) => ({ ...state, selected: date }),
+}
+
+App.agent = {
+  name: 'forecast',
+  description: 'The forecast card on screen',
+  read: (state) => ({ city: state.city, days: state.days, selected: state.selected }),
+  actions: {
+    SELECT_DAY: { description: 'Highlight one day of the forecast', input: z.enum(['Mon', 'Tue', 'Wed', 'Thu', 'Fri']) },
+  },
+}
+```
+
+The driver answers the host's `tools/list` and `tools/call` with them and tells the host when the list changes (a `when`, a new Collection key). As everywhere, a Collection item's `label` text is user text: the item parameter lists the ids, and the model reads the labels' contents through a `read` tool ([Agents: Collection items](./agent.md#collection-items)). `agentTools` is passed in rather than switched on, so a view without tools doesn't carry the agent layer.
+
+A consequential tool is declined unless you pass `confirm`, a function that asks the user in the view and resolves `true` to run the call. The host's own approval UI covers the server's tools, not the view's.
+
+## The starter: `create-sygnal-app --template mcp-app`
+
+```bash
+npm create sygnal-app@latest my-tool -- --template mcp-app
+```
+
+(`--ts` for TypeScript.) The starter needs Sygnal 6.1 or later (`makeMcpAppDriver` is in `sygnal/ai` since 6.1.0). To try it against an unreleased Sygnal change, point it at a local build: `npm run build` in a Sygnal checkout, then `npm install /path/to/sygnal` in the project (its README has the steps).
+
+```text
+src/App.jsx          the view (the forecast card above, with theme and full screen)
+src/main.js          run(App, { MCP: makeMcpAppDriver() })
+server/server.js     the MCP server: the get_forecast tool and the ui:// resource that serves the view
+server/forecast.js   made-up weather (replace it with a real API)
+```
+
+The host loads the view into a sandboxed iframe with no other files and no network access, so the view is built as **one HTML file** (`vite-plugin-singlefile`) and gets its data only through the tool's result and `callTool`. The server registers the tool with `_meta: { ui: { resourceUri: 'ui://forecast/view.html' } }` and serves that file as a resource of type `text/html;profile=mcp-app`.
+
+| Command | |
+|---|---|
+| `npm start` | Build `dist/index.html`, then serve MCP on `http://localhost:3001/mcp` (Streamable HTTP) |
+| `node server/server.js --stdio` | The same server over stdio |
+| `npm test` | The view (with `renderComponent`) and the server, no host needed |
+
+## Trying it in a host
+
+Connect the server, then ask the model for a forecast ("What's the weather in Lisbon this week?"):
+
+- **MCPJam Inspector**, no account needed: `npx @mcpjam/inspector@latest`, add the server as Streamable HTTP at `http://localhost:3001/mcp`, then call `get_forecast` from the Tools tab or the chat.
+- **The ext-apps basic host**, the reference host in [modelcontextprotocol/ext-apps](https://github.com/modelcontextprotocol/ext-apps) (`examples/basic-host`).
+- **Claude Desktop**: add the server over stdio to `claude_desktop_config.json` (`npm run build` first):
+
+  ```json
+  { "mcpServers": { "forecast": { "command": "node", "args": ["/absolute/path/to/my-tool/server/server.js", "--stdio"] } } }
+  ```
+
+  On claude.ai, add it as a custom connector; that needs the HTTP server at a public HTTPS URL (a tunnel to port 3001).
+- **VS Code** (Copilot agent mode), in `.vscode/mcp.json`:
+
+  ```json
+  { "servers": { "forecast": { "type": "http", "url": "http://localhost:3001/mcp" } } }
+  ```
+
+Rebuild (`npm run build`) after changing the view; the server reads `dist/index.html` on each request.
+
+## Testing
+
+`renderComponent` runs the view with no host. The `MCP` source's events are actions you simulate, and the `MCP` sink is a fake: `t.requests('MCP')` lists what the view sent, and `t.respond('MCP', result, 'RESULT')` answers a `callTool`.
+
+```js
+import { it, expect, afterEach } from 'vitest'
+import { renderComponent } from 'sygnal'
+import App from './App.jsx'
+
+let t
+afterEach(() => t?.dispose())
+
+const days = [{ date: 'Mon', sky: 'Sunny', high: 21, low: 14 }, { date: 'Tue', sky: 'Showers', high: 17, low: 12 }]
+
+it('shows the result, refreshes, and tells the model what the user picked', async () => {
+  t = renderComponent(App)
+  t.simulateAction('INPUT', { city: 'Oslo' })
+  t.simulateAction('RESULT', { content: [], structuredContent: { city: 'Oslo', days } })
+  await t.waitForState((s) => s.status === 'ready')
+
+  t.simulateEvent('.refresh', 'click')
+  expect(t.requests('MCP').at(-1)).toMatchObject({ callTool: 'get_forecast', args: { city: 'Oslo' }, ok: 'RESULT' })
+  await t.respond('MCP', { content: [], structuredContent: { city: 'Oslo', days: days.slice(1) } }, 'RESULT')
+  expect(t.state.days).toEqual(days.slice(1))
+
+  t.simulateEvent('.day', 'click', { data: { date: 'Tue' } })
+  await t.waitForState((s) => s.selected === 'Tue')
+  expect(t.requests('MCP').at(-1)).toEqual({ updateModelContext: { city: 'Oslo', selectedDay: days[1] } })
+})
+```
+
+The starter's tests also run the server with the MCP SDK's in-memory client.
+
+## Not covered yet
+
+The driver wraps the view-side requests and notifications of protocol 2026-01-26, except two listings a host may proxy to the server: `resources/templates/list` and `prompts/list`.