sygnal 6.3.0 → 6.5.0

package/dist/guide/mcp-apps.md

@@ -48,10 +48,19 @@ App.model = {
     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
+  // tell the model what the user picked: store it on the server, where the model reads it with a
+  // tool, then send it as model context too (see Model context below)
   PICK: {
     STATE: (state, date) => ({ ...state, selected: date }),
-    MCP: (state, date) => ({ updateModelContext: { city: state.city, selectedDay: state.days.find((d) => d.date === date) } }),
+    MCP: (state, date) => ({ callTool: 'select_day', args: { city: state.city, day: state.days.find((d) => d.date === date) }, ok: 'PICKED' }),
+  },
+  PICKED: {
+    MCP: (state) => ({
+      updateModelContext: {
+        content: `The user selected ${state.selected} in the ${state.city} forecast card.`,
+        structuredContent: { city: state.city, selectedDay: state.days.find((d) => d.date === state.selected) },
+      },
+    }),
   },
   // post a message to the conversation, as the user
   ASK: { MCP: (state) => ({ message: `What should I pack for ${state.city} on ${state.selected}?` }) },
@@ -92,7 +101,7 @@ The latest tool input, tool result, host context and `host` are replayed to a co
 | 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`) |
+| `{ updateModelContext: value }` | Tells the model something, for its next turn: a string (one text block), content blocks, an object (`structuredContent`), or `{ content, structuredContent }`. The host decides whether the model sees it: see [Model context](#model-context) |
 | `{ 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 |
@@ -155,6 +164,45 @@ Export.model = {
 
 **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.
 
+### Model context
+
+A view has three ways to tell the model something, and hosts handle them differently:
+
+- `{ message }` posts a message to the conversation as the user. The model sees it and answers it, in every host that supports `message`. Use it when the user's click is a question (the starter's **Ask about this day**).
+- `{ updateModelContext }` gives the host context for the model's **next** turn, and the host decides what to do with it. The spec says a host *should* pass it on, not how. Cursor adds it to the next user message; claude.ai keeps it and lets the model fetch it with a built-in tool ("Reading widget context"), and so does Claude Desktop's Code tab (`read_widget_context`, which the host points the model to); Claude Desktop's chat (tested October 2026) accepts it, but its model has no way to read it.
+- **A tool on your server.** The view saves what the user did with a tool only the view may call, and the model reads it with an ordinary tool. This reaches the model in every host, because every host offers the server's tools.
+
+The starter does the last two. When the user picks a day, the view calls `select_day`, then sends the same selection as model context:
+
+```js
+// server/server.js
+let selection = null   // one per process: the stdio server runs one per host connection
+
+// only the view can call it: visibility ['app'] keeps it out of the model's tool list
+server.registerTool('select_day', {
+  description: 'Records the day the user selected in the forecast card.',
+  inputSchema: { city: z.string(), day: z.object({ date: z.string(), sky: z.string(), high: z.number(), low: z.number() }) },
+  _meta: { ui: { resourceUri: VIEW_URI, visibility: ['app'] } },
+}, async ({ city, day }) => {
+  selection = { city, day }
+  return { content: [{ type: 'text', text: `Selected ${day.date} in ${city}` }], structuredContent: selection }
+})
+
+// the model's way to read it; get_forecast's description says to call it
+server.registerTool('get_selected_day', {
+  description: 'The day the user selected in the forecast card shown by get_forecast, if any.',
+  inputSchema: {},
+}, async () => ({
+  content: [{ type: 'text', text: selection ? `The user selected ${selection.day.date} in ${selection.city}.` : 'The user has not selected a day.' }],
+}))
+```
+
+The stdio server runs once per host connection, so one variable holds one user's selection. A server many users share (Streamable HTTP behind a public URL) has to keep it per user or session.
+
+Send `updateModelContext` with a text `content`: hosts list the content types they take (`MCP.select('host')` gives `hostCapabilities.updateModelContext`, Claude's is `{ text: {}, image: {} }`), and one that doesn't list `structuredContent` may drop an update that only has it.
+
+A host may also keep a tool's view (the `ui://` resource) and the tool list for as long as the server stays connected: Claude Desktop fetches them once per connection. After rebuilding the view or changing a tool, reconnect the server (restart the host, or turn the server off and on) before trying it again.
+
 ## 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.
@@ -263,7 +311,14 @@ it('shows the result, refreshes, and tells the model what the user picked', asyn
 
   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] } })
+  expect(t.requests('MCP').at(-1)).toEqual({ callTool: 'select_day', args: { city: 'Oslo', day: days[1] }, ok: 'PICKED' })
+  await t.respond('MCP', { content: [], structuredContent: { city: 'Oslo', day: days[1] } }, 'PICKED')
+  expect(t.requests('MCP').at(-1)).toEqual({
+    updateModelContext: {
+      content: 'The user selected Tue in the Oslo forecast card.',
+      structuredContent: { city: 'Oslo', selectedDay: days[1] },
+    },
+  })
 })
 ```
 

package/dist/index.cjs.js

@@ -785,6 +785,10 @@ const DEV_CODE_SEVERITY = {
     SYG425: 'warn',
     // PLAN-9 (checks/next.ts): D471 a lowercase <collection> / <switchable> tag (deprecated in 6.3.0)
     SYG426: 'warn',
+    // checks/next.ts: CHILD.select(undefined), usually a missing export
+    SYG427: 'error',
+    // checks/next.ts: a path designator that 6.4 read as one key with a dot
+    SYG428: 'warn',
     // PLAN-9 (checks/next.ts): D470 key identity, two children with one identity
     SYG453: 'warn',
     SYG612: 'error',
@@ -1411,18 +1415,45 @@ function localCell(app, parent) {
     return { local: true, get: () => (own ? v : parent.get()), set: (n) => { v = n; own = true; app.commit(); } };
 }
 /**
- * state="key". `owner`: the parent's name when `k` is one of its calculated fields (SYG409:
- * writes ignored; `what` names the writer in the message). `dflt`: an isolated child's
- * initialState, read while the slice is undefined. `has()`: the slice itself is defined (D174).
+ * SPIKE (state paths): a state designator as segments. A plain key is one segment; 'a.b.0' and
+ * 'a[0].b' are paths into nested objects and arrays. No array form: an array `from` / `state` is
+ * the data passed by mistake (SYG410 / SYG412), and ['x', 'y'] would be ambiguous.
+ */
+const pathOf$1 = (p) => p.replace(/\[(\d+)\]/g, '.$1').split('.');
+const getIn$1 = (o, ks) => { for (const k of ks) {
+    if (o == null)
+        return undefined;
+    o = o[k];
+} return o; };
+/** `o` with the value at `ks` replaced; only the levels on the path are copied (a missing level becomes {}) */
+function setIn$1(o, ks, i, v) {
+    if (i == ks.length)
+        return v;
+    const k = ks[i], cur = o?.[k], n = setIn$1(cur, ks, i + 1, v);
+    if (n === cur && o != null)
+        return o;
+    if (Array.isArray(o)) {
+        const c = o.slice();
+        c[k] = n;
+        return c;
+    }
+    return { ...o, [k]: n };
+}
+/**
+ * state="key" (SPIKE: or a path, 'a.b' / 'a[0].b'). `owner`: the parent's name when the first
+ * segment is one of its calculated fields (SYG409: writes ignored; `what` names the writer in
+ * the message). `dflt`: an isolated child's initialState, read while the slice is undefined.
+ * `has()`: the slice itself is defined (D174).
  */
 function keyCell(parent, k, owner, dflt, what = 'Sub-component') {
+    const ks = pathOf$1(k);
     let lp = {}, lv;
     return {
         get() {
             const p = parent.get();
             if (p !== lp) {
                 lp = p;
-                lv = p == null ? undefined : p[k];
+                lv = getIn$1(p, ks);
                 if (lv === undefined)
                     lv = dflt;
             }
@@ -1430,12 +1461,12 @@ function keyCell(parent, k, owner, dflt, what = 'Sub-component') {
         },
         set(v) {
             if (owner)
-                return warn('SYG409', owner, `${what} tried to update calculated field '${k}'; ignored`, 'Bind it to a non-calculated field');
+                return warn('SYG409', owner, `${what} tried to update calculated field '${ks[0]}'; ignored`, 'Bind it to a non-calculated field');
             const p = parent.get();
-            if (p?.[k] !== v)
-                parent.set({ ...p, [k]: v });
+            if (getIn$1(p, ks) !== v)
+                parent.set(setIn$1(p, ks, 0, v));
         },
-        has: () => parent.get()?.[k] !== undefined,
+        has: () => getIn$1(parent.get(), ks) !== undefined,
     };
 }
 /**
@@ -2781,7 +2812,7 @@ class Inst {
                 fail$2('SYG405', def.name, 'Sub-component initialState replaces the state its parent passes in', 'Remove initialState, or set isolatedState = true');
             }
             const dflt = def.isolated ? def.initialState : undefined;
-            const cell = typeof st == 'string' ? keyCell(this.cell, st, calcOf?.has(st) && this.def.name, dflt)
+            const cell = typeof st == 'string' ? keyCell(this.cell, st, calcOf?.has(pathOf$1(st)[0]) && this.def.name, dflt)
                 : st !== undefined ? lensCell(this.cell, st, this.def.name, (e) => app.appError(this, e, 'view'), dflt)
                     : def.isolated ? localCell(app, this.cell) : this.cell;
             const scope = app.scope();
@@ -2863,8 +2894,9 @@ class Inst {
  *
  * It stands where the `<Collection>` marker was in its owner's template and renders the items
  * inside the owner's render: no stream of its own, no pickCombine.
- * - `of`: a component function (D163: no names). `from`: a state key (SYG409 on a calculated
- *   one), a `{ get, set }` lens (SYG412 without get(); SYG401 for a non-array) or none (the
+ * - `of`: a component function (D163: no names). `from`: a state key or path ('board.cards';
+ *   SYG409 on a calculated first segment; SYG401 when it isn't an array: the dev entry's), a
+ *   `{ get, set }` lens (SYG412 without get(); SYG401 for a non-array) or none (the
  *   owner's state is the array).
  * - Items are keyed by `id`, an id-less item by its raw index (D169); one key -> index map per
  *   array identity serves every item (cell.ts indexer). A duplicate key renders its first element
@@ -2946,16 +2978,9 @@ function arrayCell(owner, from) {
             set: (v) => oc.set(v),
         };
     }
-    if (typeof from == 'string') {
-        const cs = oc.get(), calc = owner.def.calcNames?.has(from);
-        if (isObj$2(cs) && !(from in cs) && !calc) {
-            const arrays = Object.keys(cs).filter(k => Array.isArray(cs[k]));
-            warn('SYG401', name, `Collection from="${from}" is not in state${arrays.length ? ` (array fields: '${arrays.join("', '")}')` : ''}; it renders nothing until it exists`, 'Set it to an array in initialState');
-        }
-        else if (isObj$2(cs) && !Array.isArray(cs[from]))
-            warn('SYG401', name, `Collection 'from' field '${from}' is not an array; it renders nothing`, 'Set it to an array in initialState');
-        return keyCell(oc, from, calc && name, undefined, 'Collection');
-    }
+    // a key or a path ('board.cards'); SYG401 for one that isn't an array is the dev entry's (checks/collections.ts)
+    if (typeof from == 'string')
+        return keyCell(oc, from, owner.def.calcNames?.has(pathOf$1(from)[0]) && name, undefined, 'Collection');
     if (isObj$2(from) && typeof from.get == 'function') {
         let lp = {}, lv;
         return {
@@ -4164,7 +4189,7 @@ class SwitchableHost {
         this.lr = true;
         this.kids = [];
         check$3(owner, props);
-        const st = props.state, calc = typeof st == 'string' && owner.def.calcNames?.has(st);
+        const st = props.state, calc = typeof st == 'string' && owner.def.calcNames?.has(pathOf$1(st)[0]);
         this.cell = typeof st == 'string' ? keyCell(owner.cell, st, calc && owner.def.name, undefined, 'Switchable sub-component')
             : st !== undefined ? lensCell(owner.cell, st, owner.def.name, (e) => owner.app.appError(owner, e, 'view'))
                 : owner.cell;
@@ -17460,10 +17485,14 @@ function toggle(field) {
     return (state) => ({ ...state, [field]: !state[field] });
 }
 // event(type, payload?) → EVENTS sink fn for the object form:
-// `ACTION: { EVENTS: event('TYPE', (state, data) => payload) }` (static payloads allowed)
+// `ACTION: { EVENTS: event('TYPE', (state, data) => payload) }` (static payloads allowed).
+// A payload function that returns ABORT sends nothing, as ABORT does from any other sink.
 function event(type, payload) {
     return typeof payload === 'function'
-        ? (state, data, next, props) => ({ type, data: payload(state, data, next, props) })
+        ? (state, data, next, props) => {
+            const d = payload(state, data, next, props);
+            return isAbort(d) ? ABORT : { type, data: d };
+        }
         : () => ({ type, data: payload });
 }
 // ── emit() ─────────────────────────────────────────────────────────
@@ -17501,7 +17530,7 @@ function trackWorker(worker, events) {
 function makeServiceWorkerDriver(scriptUrl, options = {}) {
     return function serviceWorkerDriver(sink$) {
         const events = new EventTarget();
-        if (typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
+        if (options.enabled !== false && typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
             navigator.serviceWorker
                 .register(scriptUrl, { scope: options.scope })
                 .then((reg) => {