sygnal 6.3.0 → 6.4.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to Sygnal are listed here. Versions follow [semantic versioning](https://semver.org). Releases before 5.4.0 are described in the [GitHub releases](https://github.com/tpresley/sygnal/releases) and tags.
 
+## 6.4.0 — 2026-10-14
+
+Fixes for issues an agent hit while building a real app on 6.3.0, and a step-by-step chat tutorial in the AI showcase. Additive: an `event()` payload function may now return `ABORT`, `makeServiceWorkerDriver` takes `enabled`, and a new diagnostic code (SYG427) reports a `CHILD.select()` of something that isn't a component. Dev-time checks get fewer false positives (SYG103, SYG223).
+
+**Measured impact.** Size: the kanban gate is (a) 42,516 B with `nativeGlobalThis: false` (was 42,504 B; budget 42,700 B) and (b) 38,497 B by default (was 38,485 B): `event()`'s `ABORT` check adds 12 B. The SYG103 view words are dev-server only (never in `vite build`); SYG427's runtime check is in the dev diagnostics entry (0 production bytes).
+
+**Companion packages.**
+- **`sygnal-check` 0.8.0:** new SYG427 (error: a component imported from a module that doesn't export it), no false SYG223 for a `uses` slice in `persist({ pick })`, and SYG609's fix names `makeServiceWorkerDriver` for an `SW` sink. Its caret range doesn't reach 0.8.0 from `^0.7.0`, so update the dev dependency.
+- **`create-sygnal-app` 2.6.0:** every template depends on `sygnal` ^6.4.0 and `sygnal-check` ^0.8.0.
+- **VS Code extension 0.5.0:** bundles `sygnal-check` 0.8.0. The extension itself doesn't change.
+- **Claude Code plugin 0.1.3:** the `sygnal-dev` skill says that an `event()` payload function returns `ABORT` to send nothing.
+
+### Added
+
+- **`event()` can send nothing.** A payload function that returns `ABORT` sends no event, as `ABORT` does from any other sink: `EVENTS: event('SAVED', (state) => (state.dirty ? { id: state.id } : ABORT))`. Before, the event went out with `ABORT` as its data, and strict mode (which rules out the raw `EVENTS: (state) => …` form) left no way to skip one; apps split actions or sent placeholder events instead. Typed: the payload function may return `ABORT`. `emit()` gets it too.
+- **`makeServiceWorkerDriver(url, { enabled })`.** `enabled: false` registers no service worker, ignores commands and emits nothing, so an app keeps its `SW` wiring on a dev server, where a worker must not run: `makeServiceWorkerDriver('/sw.js', { enabled: import.meta.env.PROD })`. Before, leaving the driver out in development logged SYG609 on every load, and the fix was a hand-written no-op driver.
+- **SYG427 (error): `CHILD.select()` of something that is not a component.** A component imported by a name its module doesn't export is `undefined` under Vitest (the browser refuses to load the module), so `CHILD.select(Child)` never emitted and a test that never rendered `<Child />` passed with no diagnostic. The dev diagnostics now report it when the parent is created, so `expectNoDiagnostics()` fails in every test of the parent; `sygnal-check` reports a component imported from a relative module that doesn't export it, used as a JSX tag, in `CHILD.select()` or as a Collection's `of`.
+- **`examples/ai-showcase`: a Building Chat tab.** The page is now two tabs: Features (the ten sections) and Building Chat, one chat built up in eight steps on one model (Kimi K3 on Kindo): streaming; stop, retry and clear; the model's reasoning and a token tally; follow-up suggestions from a structured-output request; `persist()`; an `agent` declaration the model reads (an answer style) and acts on (a shopping list, with approval before clearing it); and a client tool answered with a click. Each step is a complete component, and Show code marks the lines new since the step before. Example chips fill in the prompt without sending it.
+
+### Fixed
+
+- **SYG103 no longer warns about markup drawn by a view helper.** The dev check that takes a not-yet-rendered selector as conditionally rendered read only the view function's source, so a button drawn by `panel()` (called from the view, in the same file or imported) counted as missing and warned after a few renders; the only way out was a component per branch. In dev, `sygnal/vite` now registers the words of a component module's string literals and of its relative imports, and the check reads them too. Strings that are selectors or paths are left out, so a typo in the intent's own selector is still reported. Without the plugin the check works as before.
+- **SYG223 no longer flags a behavior's slice.** `persist({ pick: ['chat'] })` on a component with `uses = { chat: chat() }` warned that `chat` isn't a key of `initialState` (dev diagnostics and `sygnal-check`), but a `uses` slice is state and is saved; both checkers now count `uses` keys.
+- **SYG609's fix names the right driver.** An `SW` sink now gets `makeServiceWorkerDriver('/sw.js', { enabled: import.meta.env.PROD })` instead of `makeFetchDriver()`, and a `WS` sink `makeSocketDriver()`, without the URL argument the fix text gave it (the socket driver takes none; connections come from the `connections` static). Runtime and `sygnal-check`.
+
+## create-sygnal-app 2.5.0 — 2026-10-13
+
+The `mcp-app` starter, new projects on sygnal-check 0.7.0, docs and examples; `sygnal` itself is unchanged (6.3.0). Testing the starter in Claude Desktop showed that a view's `updateModelContext` never reaches the model in its chat, so the starter now tells the model what the user picked through a server tool.
+
+### Changed
+
+- **`create-sygnal-app`: the `mcp-app` template (JS and TS) tells the model what the user picked through the server.** Hosts differ in what they do with `ui/update-model-context`: Cursor adds it to the next turn, claude.ai and Claude Desktop's Code tab let the model fetch it with a built-in tool, and Claude Desktop's chat accepts it (it lists `{ text, image }`) but its model never sees it (tested 2026-10-12). When the user picks a day, the view now calls `select_day`, a tool only the view can call (`_meta.ui.visibility: ['app']`), and the model reads the selection with `get_selected_day`, which `get_forecast`'s description names; the view still sends the selection as model context, now as text plus `structuredContent` (a host that doesn't list `structuredContent` may drop an update with only that). The README and `AGENTS.md` explain the pattern, and the README says to reconnect the server after a rebuild (Claude Desktop keeps the view and the tool list per connection).
+- **`create-sygnal-app`: new projects get `sygnal-check` ^0.7.0** (was ^0.6.0; a caret range on 0.x doesn't cross minors), so the editor highlights of sygnal-check 0.7.0 (below) work in them from the start. `sygnal` stays ^6.3.0.
+
+### Added
+
+- **Docs: Native AI Support**, a section above the Guide with seven narrative pages (overview, streaming chat, decision models, UI composed by a model, agents in your app, the agentic web, built for coding agents) that link to the guides, recipes and API reference. The home page lists the AI card right after Pure Components.
+- **Docs: Model context** in [MCP Apps](https://sygnal.js.org/guide/mcp-apps/#model-context): `message` vs `updateModelContext` vs a server tool, how hosts handle each, and the selection tools' server code.
+- **`examples/ai-showcase`**: one page with ten sections, each a small Sygnal app showing a part of `sygnal/ai` against real models (Ollama, Kindo through its Open Responses, Chat Completions and Messages endpoints, TypeSafe Jev, Chrome's built-in model): any model with the same component, structured output, tools, decision models, the command bar, an assistant that operates the app, composed UI, cards in a chat, WebMCP, and an MCP App. Each section has its source behind Show code. Provider keys stay on the dev server (a Keys dialog or key files outside the repository; `apply: 'serve'` routes that refuse cross-site requests).
+- **`examples/mcp-kindo-agents`**: an MCP App that runs Kindo agents from a conversation: the model fills in the inputs, the card starts the run, follows it through a server-side long poll (step evaluations, a live elapsed time) and hands the result back to the model (`get_agent_run`).
+- **`examples/mcp-app`**: the `mcp-app` starter linked to this checkout (part of `npm run test:examples`), with `scripts/add-to-claude-desktop.sh`, which adds the server to Claude Desktop while it is quit (Claude Desktop rewrites `claude_desktop_config.json` while it runs, dropping edits made then).
+
+## sygnal-check 0.7.0, VS Code extension 0.4.0 — 2026-10-13
+
+Highlights of Sygnal's wiring in the editor; `sygnal` itself is unchanged (6.3.0).
+
+### Added
+
+- **`sygnal-check lsp` highlights the wiring** as semantic tokens (`textDocument/semanticTokens/full`, custom types `sygnalAction`, `sygnalEvent`, `sygnalSelector`, `sygnalTarget`, `sygnalChild`): action names wherever they're wired (`unhandled` when no model entry handles an intent action), EVENTS types, intent selectors (`untargeted` when nothing the component or a child renders can match, `unverified` when only a dynamic class name in the view might), the view classes / ids / controls an intent of their scope selects, and child components selected with `CHILD.select` (the call, `<Child>` and `<Collection of={Child}>` in the parent's view, the child's name). Only names the checker resolved get a token. `workspace/semanticTokens/refresh` after a check that changed them; the setting `sygnal.highlights` turns them off. A client that keeps one semantic-token provider per file can opt out of the provider (`initializationOptions.semanticTokens: false`) and draw the decoded tokens of `sygnal/highlights` itself. Neovim layers them over its TypeScript server's ([highlight groups](https://sygnal.js.org/integration/editors/#neovim)).
+- **VS Code extension: highlights**, drawn as decorations over the theme's colors (VS Code asks only one semantic-token provider per file, so TypeScript's semantic highlighting stays): bold tinted action names, italic EVENTS types, underlined selectors (amber dashed when unverified, red struck through when nothing renders them), tinted targets, underlined selected children. Theme colors `sygnal.highlight.*`, setting `sygnal.highlights` (unset: on).
+
 ## 6.3.0 — 2026-10-11
 
 Composing UI with a model (PLAN-9). An app declares its parts once in a catalog, the user describes a page or an edit in words, and a model builds it from those parts: a decision model answering multiple-choice questions (TypeSafe Jev, Ollama's `nimble`) or an LLM with structured output, with the same catalog, app code and tests for both. The composition is plain JSON in state, each part is an ordinary child component, and follow-up requests edit the page while keeping the state of the parts they don't touch. The same catalog lets a chat assistant ask the user with a card instead of in text (`chat({ ask })`), on top of client tools for the `chat` behavior. Around it: `decide()` splits large question sets, `byId()` lenses, and a component's `key` is now its identity.

package/dist/astro/index.cjs.js

@@ -742,6 +742,12 @@ if (import.meta.hot) installMcpBridge(import.meta.hot, { agentTools, confirm: ${
  *      /__sygnal/mcp (./mcp.ts: streamable HTTP, loopback / local Host / local Origin only)
  *      and the dev entries also import 'virtual:sygnal/mcp', which connects the page over the
  *      HMR channel (installMcpBridge from 'sygnal/devtools'). Never in `vite build` or Vitest.
+ *  11. SYG103 view words (dev server with diagnostics on; never `vite build`, SSR or Vitest): a
+ *      module that sets `X.intent` or `X.uses` gets a tail registering, for each such X, the
+ *      words of its string literals and of the relative modules it imports, in
+ *      `globalThis.__SYGNAL_VIEW_TOKENS__`. The runtime SYG103 check then takes a selector drawn
+ *      by a view helper (`{state.open && panel()}`) as conditionally rendered, as it does for
+ *      markup in the view function itself (see viewTokensTail).
  *
  * Why not Vite's `define`? Vite's dependency optimizer does not apply user
  * `define` replacements to pre-bundled dependencies (only process.env.NODE_ENV),
@@ -979,9 +985,20 @@ function sygnal(options = {}) {
         transform(code, id, opts) {
             // SYG666 (PLAN-5 W-2): an adapter entry imported without its optional peers; every mode
             const adapters = adapterImports(this, code, id);
-            if (adapters)
-                return checkPeers(this, adapters, id).then(() => devTransform.call(this, code, id, opts));
-            return devTransform.call(this, code, id, opts);
+            const result = adapters
+                ? checkPeers(this, adapters, id).then(() => devTransform.call(this, code, id, opts))
+                : devTransform.call(this, code, id, opts);
+            // 11. the words SYG103 may take as conditionally rendered markup (dev server, diagnostics on)
+            const tokens = isServe && !isVitest && devOn && !opts?.ssr ? viewTokensTail(this, code, id) : null;
+            if (!tokens)
+                return result;
+            return Promise.all([result, tokens]).then(([r, tail]) => {
+                if (!tail)
+                    return r;
+                if (r == null)
+                    return withSourcemap(code, [], tail, id);
+                return typeof r == 'string' ? r + tail : { ...r, code: r.code + tail };
+            });
         },
     };
     function devTransform(code, id, opts) {
@@ -1064,6 +1081,55 @@ function sygnal(options = {}) {
         return done();
     }
 }
+// 11. SYG103 (the dev runtime check of an intent selector that never matched) lets a selector
+// through as conditionally rendered when its words appear in the component's view; the runtime
+// can read only the view function's own source. A component module (one that sets `X.intent` or
+// `X.uses`) gets, in dev, a tail registering for each such component the words of its string
+// literals and those of the relative modules it imports, where view helpers live
+// (globalThis.__SYGNAL_VIEW_TOKENS__, a WeakMap read by checks/dom.ts).
+const COMPONENT_WITH_SELECTORS_RE = /(?:^|[^\w$.])([A-Z][\w$]*)\.(?:intent|uses)\s*=(?!=)/g;
+const STRING_RE = /(['"])((?:\\.|(?!\1)[^\\\n])*)\1|`((?:\\[\s\S]|[^\\`])*)`/g;
+const RELATIVE_IMPORT_RE = /(?:\bfrom|\bimport)\s*\(?\s*(['"])(\.{1,2}\/[^'"]+)\1/g;
+// A string that is itself a selector ('.save', '#id', 'form.ask', '[data-x]') or a path / URL: its
+// words aren't markup (the intent's own DOM.click('.svae') would otherwise vouch for its typo)
+const NOT_MARKUP_RE = /(?:^|[\s>+~,(])[\w-]*[.#[][\w-]|^\s*(?:\/|[\w+-]+:\/\/)/;
+/** the class / id / tag-like words in a module's string and template literals (comments skipped) */
+function stringWords(code, into) {
+    for (const m of blankOut(code, false).matchAll(STRING_RE)) {
+        const text = m[2] ?? m[3] ?? '';
+        if (NOT_MARKUP_RE.test(text))
+            continue;
+        for (const w of text.match(/[A-Za-z_][\w-]*/g) || [])
+            into.add(w);
+    }
+}
+function viewTokensTail(ctx, code, id) {
+    const file = cleanId(id);
+    if (!/\.[jt]sx?$/.test(file) || id.includes('node_modules') || id.startsWith('\0'))
+        return null;
+    const names = new Set();
+    for (const m of blankOut(code, true).matchAll(COMPONENT_WITH_SELECTORS_RE))
+        names.add(m[1]);
+    if (!names.size)
+        return null;
+    const words = new Set();
+    stringWords(code, words);
+    const specs = new Set(Array.from(blankOut(code, false).matchAll(RELATIVE_IMPORT_RE), m => m[2]));
+    return Promise.all([...specs].map(async (spec) => {
+        try {
+            const r = await ctx.resolve(spec, id);
+            const dep = r && !r.external && cleanId(r.id);
+            if (!dep || !/\.[cm]?[jt]sx?$/.test(dep) || dep.includes('node_modules'))
+                return;
+            ctx.addWatchFile?.(dep);
+            stringWords(await fs.promises.readFile(dep, 'utf8'), words);
+        }
+        catch (_) { /* unreadable: its words are just not added */ }
+    })).then(() => {
+        const comps = [...names].map(n => `typeof ${n} == 'function' && ${n}`).join(', ');
+        return `\n;(() => { try { const m = globalThis.__SYGNAL_VIEW_TOKENS__ ||= new WeakMap(), t = ${JSON.stringify([...words].join(' '))}; for (const c of [${comps}]) if (c) m.set(c, t) } catch (_) {} })();\n`;
+    });
+}
 // PLAN-5 W-2 (D209): the adapter entries and the optional peer dependencies each one imports
 // (the Zag packages pinned together: they depend on each other's exact versions)
 const ZAG = '~1.45.0';