sygnal 6.6.0 → 7.0.0

package/CHANGELOG.md

@@ -2,6 +2,138 @@
 
 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.
 
+## 7.0.0 — 2026-10-19
+
+**Read [Migrating to 7.0](https://sygnal.js.org/guide/migrating-to-7/) before upgrading.** 7.0
+has one reducer timing contract and no option to switch back; apps that aren't ready stay on 6.x.
+
+**Measured impact.** Size: the kanban gate is (a) 42,844 B with `nativeGlobalThis: false` (6.6.0:
+42,495 B; budget raised from 42,700 B to 43,000 B for the binding lifetimes) and (b) 38,834 B by
+default. Most of the growth is the binding-lifetime bookkeeping; the single timing contract is
+smaller than the opt-in switch it replaced (−181 B against the 7.0 candidate). The timing audit is
+in the dev diagnostics entry (0 production bytes), and the upload, SSE, form and `tooltips()`
+features add nothing to an app that doesn't use them. The perf count gate is within its limits.
+
+**Companion packages.**
+- **`sygnal-check` 0.11.0:** checks reducer timing and binding changes against the Sygnal version
+  installed for each source package (7: every output gets the committed state, changed known
+  targets remount; 6: the 6.x contracts). New **SYG256** (an output guard that rejects the state
+  its own action writes, in a Sygnal 7 project); **SYG454** (an unkeyed dynamic `byId` selection)
+  only for an installed Sygnal 6. SYG731 accepts state announced through text, `aria-label`,
+  `aria-live` or `role="status"`; SYG609 also reports intent sources with no driver; `progress`
+  counts as a reply-action key (SYG102 / SYG112). Explanations for SYG257 and SYG636. Its caret
+  range doesn't reach 0.11.0 from `^0.10.0`, so update the dev dependency.
+- **`create-sygnal-app` 2.9.0:** every template depends on `sygnal` ^7.0.0 and `sygnal-check`
+  ^0.11.0 and has `npm run check` (TypeScript templates: sygnal-check and `tsc --noEmit`).
+  Scaffolding into a directory that holds only `.git` and/or `.DS_Store` keeps that metadata, and
+  `.` gets a valid package name from the directory.
+- **VS Code extension 0.8.0:** bundles `sygnal-check` 0.11.0 for Sygnal 7 and existing Sygnal 6
+  apps; workspace checkers need 0.11.0 or later (earlier ones fall back to the bundled checker).
+- **Claude Code plugin 0.2.0:** the `sygnal-dev` skill describes Sygnal 7; a project's
+  `sygnal-check` older than 0.11.0 is refused only when the project has Sygnal 7.
+
+### Breaking: STATE runs first, and output sinks see its result
+
+In every model entry STATE now runs first, whatever the key order, and every other sink (EFFECT,
+EVENTS, PARENT, ELEMENT, HTTP and other drivers) gets the committed state, calculated fields
+included, as `state` and `props.state`. The new `props.previousState` (fourth argument) is the
+state from before the action; a STATE reducer gets the old state in both. 6.x gave every reducer
+the state from before the action.
+
+- An output that computed the update itself now applies it twice: in
+  `INC: { STATE: s => ({ ...s, n: s.n + 1 }), PARENT: s => ({ n: s.n + 1 }) }`, PARENT becomes
+  `s => ({ n: s.n })`.
+- A value STATE clears or deletes (a submitted draft, a removed record) is read from
+  `previousState`.
+- A guard that admits the action (a loading or status flag STATE sets) tests `previousState`.
+  Keep the output guard: STATE returning `ABORT` doesn't cancel the other sinks.
+- When STATE returns `ABORT` or the same state, or throws, the other sinks still run, with
+  `state === previousState`.
+- When STATE removes the component's own state (`STATE: () => undefined` in a Collection item, or
+  a child bound with `state="x"` / `byId()` deleting its record), the other sinks get its last
+  state, so `REMOVE: { STATE: () => undefined, EVENTS: event('REMOVED', (s) => s.id) }` works as
+  before.
+- Behaviors: the first argument is the slice after STATE, `props.state` the host state after
+  STATE, `props.previousState` the host state before the action; the old slice is
+  `props.previousState[key]`. Every built-in behavior (form, chat, compose, commandBar, undo,
+  pager, selection, sortable, and the `sygnal/ui` dialog, popover, tooltip, tabs, accordion and
+  disclosure) is on this contract.
+- Libraries that support 6 and 7 read old values as `props.previousState ?? state`.
+
+### New: the timing audit (SYG257)
+
+An opt-in dev check for upgrading 6.x code: with `renderComponent(C, { timingAudit: true })`,
+`sygnal({ diagnostics: { timingAudit: true } })` in `vite.config`, `configureTimingAudit(true)`
+from `'sygnal/diagnostics'` or `globalThis.__SYGNAL_TIMING_AUDIT__ = true`, every output sink that
+reads a top-level state field its action's STATE changed reports **SYG257** (info, once per
+component, action, sink and field). Keep `state` where the new value is meant; read
+`previousState` where the old one was. It is off by default because in code written for 7.0
+reading the new value is the intent, and it adds nothing to production builds.
+
+sygnal-check's **SYG256** (warning) reports an output guard that contradicts the same action's
+literal STATE write, the loading/admission pitfall above. sygnal-check reads the installed
+Sygnal version per package; **SYG454** (a `byId()` selection without a key) applies only to
+Sygnal 6.
+
+### Breaking: a child follows the record its state binding points at
+
+When a child's `state` path, or its `byId()` field, id or idKey, changes, Sygnal disposes the old
+child and mounts a new one: `DISPOSE` runs with the last state, pending requests, delayed `next()`
+actions and subscriptions are cancelled, initialization reruns and local state starts from its
+defaults. The child's DOM is replaced, so focus, caret, scroll position and in-progress input
+inside it are lost. The same applies to Collection/VirtualCollection `from` and Switchable
+`state` (all items or pages, hidden ones included, even when ids overlap). Deleting the bound
+record disposes the child too, after the deleting action's outputs; re-adding the same id gets a
+new child, never the old pending work. A new `byId()` call with the same arguments, field edits
+and reordering keep the child. `key={selected.id}` is no longer needed for a selection.
+
+**A stable explicit key no longer keeps a child across a target change**: lift state that must
+survive the change into the parent. A child with a custom lens keeps its binding until its key
+changes.
+
+### New: uploads, SSE auth, form files and types, `tooltips()`
+
+- **Upload and download progress** on `makeFetchDriver` requests: `progress: 'UPLOADING'` (a reply
+  action) or `progress: true` (`HTTP.progress(category)`) sends `{ phase, loaded, total, fraction }`
+  steps, throttled to one every 50 ms per phase. Such a request goes over XMLHttpRequest, the only
+  way to see upload progress in every browser; fetch-only `init` options it can't honour are
+  SYG636. Tests: `t.progress('HTTP', { loaded, total }, 'UPLOADING')`.
+- **`multipart: { file, title }`** on a request: the multipart/form-data body as data, the way
+  `json` is; a model never builds a `FormData`.
+- **The `form` behavior** takes file inputs (a field's value is its `File`, `multiple` an array,
+  validated by the schema), keeps the submit's progress in `state.form.progress`
+  (`progress: 'form.PROGRESS'`) and counts start-overs in `state.form.resets` (key a file input
+  with it). `request: { url }` (or `(data, state) => request`) sends a valid submit itself, as
+  JSON or multipart, with `form.DONE` / `form.ERRORS` wired: the common save needs no model entry.
+  `form.RESET` from a click goes back to the start values (it used to take the event as values).
+- **Form types from the schema**: a typed Standard Schema (zod, valibot, arktype) types
+  `state.form.values` and `fields.x.value`; `FormOutput<typeof uses.form>` is the submit data.
+- **SSE connections take `headers`** (`{ authorization: 'Bearer ' + state.token }`): such a stream
+  is read with fetch (`Last-Event-ID`, `retry`), since EventSource can't send headers.
+- **`tooltips()`** in `sygnal/ui`: one behavior and one state slice for every tooltip of a
+  component (glossary terms, icon toolbars), one tip at a time.
+- `Component<State, any>` keeps `state` typed; SYG731 accepts state announced through text,
+  `aria-label`, `aria-live` or `role="status"`; sygnal-check's SYG609 also reports intent sources
+  with no driver; a test wait that times out on the fake clock names the pending timer; every
+  create-sygnal-app template has `npm run check` (TypeScript: sygnal-check and `tsc --noEmit`).
+
+### Also included
+
+- A child that fails to instantiate is no longer retried on every parent render.
+- State-wait timeout messages report queued simulated inputs; the testing guide separates
+  serialized simulated input from synchronous native bursts.
+- TypeScript tests can use `t.query<HTMLInputElement>(selector)` and `t.queryAll<…>(selector)`
+  (type assertions, not runtime checks); typed control tokens keep their inference.
+- The combined Rollup build exits normally (compiler watcher lifecycle fix).
+- The release workflow checks the CHANGELOG headings of the new versions before the gates and
+  any publish.
+
+### Changed
+
+- **The app graph's banner line says why it's missing.** When the dev server's graph route is on but the project has no `sygnal-check` 0.10.0 or later, `sygnal/vite` prints `➜  Sygnal graph: needs sygnal-check 0.10.0 or later in this project (npm i -D sygnal-check)` instead of nothing (the URL already answered 404 with the same hint).
+- **`astro dev` prints the graph page's address** under Astro's own banner (Astro never runs Vite's URL printing), and the Astro integration takes the `graph` option (`sygnal({ graph: false })`).
+- **The repository's examples link `sygnal-check`** (`file:../../sygnal-check`, as they link `sygnal`), so `npm run dev` in any of them serves the app graph; `examples/mcp-app` moves off `sygnal-check` ^0.7.0.
+
 ## 6.6.0 — 2026-10-16
 
 The app graph as an interactive page: `sygnal-check --graph=html`, live with `--watch` or at `/__sygnal/graph` in the Vite dev server, in a VS Code panel and in Sygnal DevTools. See [The App Graph](https://sygnal.js.org/guide/app-graph/).

package/README.md

@@ -9,6 +9,8 @@ A reactive component framework with pure functions, zero side effects, and autom
 
 ---
 
+> **Upgrading from 6.x?** Sygnal 7.0 changes reducer timing: output sinks (EFFECT, EVENTS, PARENT, HTTP, ...) now see the state after the action's STATE update. See [Migrating to 7.0](https://sygnal.js.org/guide/migrating-to-7/).
+
 ## Why Sygnal?
 
 - **Pure components** — Views are plain functions. All side effects are handled by drivers, outside your code.

package/dist/astro/index.cjs.js

@@ -867,17 +867,25 @@ function graphMiddleware(server, root, engine, ping = 25000) {
         res.end(req.method === 'HEAD' ? undefined : body);
     };
 }
-/** Adds the page's URL under Vite's own when the dev server prints them. */
-function printGraphUrl(server) {
+/** The banner line when the project has no sygnal-check with the graph page (it used to print nothing). */
+const GRAPH_MISSING_LINE = '  ➜  Sygnal graph: needs sygnal-check 0.10.0 or later in this project (npm i -D sygnal-check)';
+/**
+ * Adds the page's URL under Vite's own when the dev server prints them, or, when the project's
+ * sygnal-check is missing or too old for the page (`available` false), a line saying what to install.
+ */
+function printGraphUrl(server, available = true) {
     const print = server?.printUrls;
     if (typeof print !== 'function')
         return;
     server.printUrls = function (...args) {
         const out = print.apply(this, args);
         try {
+            const logger = server.config?.logger || console;
             const local = server.resolvedUrls?.local?.[0];
-            if (local)
-                (server.config?.logger || console).info(`  ➜  Sygnal graph: ${new URL(local).origin}${GRAPH_PATH}`);
+            if (!available)
+                logger.info(GRAPH_MISSING_LINE);
+            else if (local)
+                logger.info(`  ➜  Sygnal graph: ${new URL(local).origin}${GRAPH_PATH}`);
         }
         catch (_) { }
         return out;
@@ -1016,7 +1024,8 @@ function printGraphUrl(server) {
  *      skipped silently when missing; a sygnal-check without the page keeps the checker as in 5)
  *      builds it with createLiveProject on start and after each change: one build gives the page,
  *      the check overlay / console findings of 5, and the component stamps. Its URL is printed
- *      under Vite's ("➜  Sygnal graph: http://localhost:5173/__sygnal/graph"). The modules of the
+ *      under Vite's ("➜  Sygnal graph: http://localhost:5173/__sygnal/graph"; without a sygnal-check
+ *      0.10.0+ in the project, a line saying so instead). The modules of the
  *      scanned files get a tail setting a non-enumerable `__sygnalKey` (the static 'file#name'
  *      key, D521) on each top-level component function, which the runtime inspect() reports as
  *      `key`; with DevTools on, the dev entries also import 'virtual:sygnal/graph'
@@ -1084,7 +1093,7 @@ function sygnal(options = {}) {
     // Files whose `import ... from 'sygnal'` resolves to the run() wrapper
     const runtimeImporters = new Set();
     // Statements run before the app starts: dev flag (+ strict flag)
-    const flags = DEV_FLAG + (diagnostics.strict ? STRICT_FLAG : '');
+    const flags = DEV_FLAG + (diagnostics.strict ? STRICT_FLAG : '') + (diagnostics.timingAudit ? AUDIT_FLAG : '');
     const devImports = `import 'sygnal/diagnostics';import '${DEV_CLIENT}';`;
     // D77: the DevTools bridge, dev only. First, so the diagnostics entry finds it.
     // E-1: the MCP endpoint needs the bridge, so `mcp` turns it on
@@ -1282,8 +1291,7 @@ function sygnal(options = {}) {
             // W-2 (D543): the page and its stream, behind the MCP endpoint's guard; its URL in the banner
             if (graphOn && server?.middlewares) {
                 server.middlewares.use(graphMiddleware(server, root, engine));
-                if (graphAvailable(root))
-                    printGraphUrl(server);
+                printGraphUrl(server, graphAvailable(root));
             }
         },
         transform(code, id, opts) {
@@ -1568,7 +1576,7 @@ function normalizeDiagnostics(value) {
     if (!MODES.includes(mode)) {
         throw new Error(`[vite-plugin-sygnal] diagnostics mode must be one of ${MODES.map(m => `'${m}'`).join(', ')}; got ${JSON.stringify(mode)}`);
     }
-    return { mode, strict: !!o.strict, ignore: Array.isArray(o.ignore) ? o.ignore.map(String) : [] };
+    return { mode, strict: !!o.strict, timingAudit: !!o.timingAudit, ignore: Array.isArray(o.ignore) ? o.ignore.map(String) : [] };
 }
 /** Module id without a query or hash. */
 function cleanId(id) {
@@ -1946,6 +1954,8 @@ function startChecker(server, root, mod, setup, opts, engine) {
 }
 const DEV_FLAG = 'if (globalThis.__SYGNAL_DEV__ === undefined) globalThis.__SYGNAL_DEV__ = true;';
 const STRICT_FLAG = 'if (globalThis.__SYGNAL_STRICT__ === undefined) globalThis.__SYGNAL_STRICT__ = true;';
+// 7.0: the opt-in timing audit (SYG257, 'sygnal/diagnostics' checks/timingAudit.ts)
+const AUDIT_FLAG = 'if (globalThis.__SYGNAL_TIMING_AUDIT__ === undefined) globalThis.__SYGNAL_TIMING_AUDIT__ = true;';
 // A top-level (column 0) run(Component, ...) statement: bare, or declaring a
 // new binding. Assignments to existing variables, nested calls and indented
 // calls (e.g. inside a function or test callback) do not match (B-007). It is
@@ -2084,10 +2094,12 @@ const rootDir = (root) =>
 // @ts-ignore — Node's process
 !root ? process.cwd() : typeof root === 'string' ? root : node_url.fileURLToPath(root);
 function sygnalAstroIntegration(options = {}) {
+    let projectRoot;
     return {
         name: SYGNAL_RENDERER_NAME,
         hooks: {
             'astro:config:setup': ({ addRenderer, updateConfig, command, config }) => {
+                projectRoot = rootDir(config?.root);
                 addRenderer({
                     name: SYGNAL_RENDERER_NAME,
                     clientEntrypoint: 'sygnal/astro/client',
@@ -2117,6 +2129,7 @@ function sygnalAstroIntegration(options = {}) {
                             check: options.check,
                             nativeGlobalThis: options.nativeGlobalThis,
                             devtools: options.devtools,
+                            graph: options.graph,
                         })];
                 }
                 else if (options.nativeGlobalThis !== false) {
@@ -2129,6 +2142,16 @@ function sygnalAstroIntegration(options = {}) {
                 vite.plugins = [...(vite.plugins || []), onErrorPlugin(hook)];
                 updateConfig({ vite });
             },
+            // W-2: Astro prints its own banner (Vite's printUrls never runs), so the graph page's line goes here
+            'astro:server:start': ({ address, logger }) => {
+                if (options.graph === false || !projectRoot)
+                    return;
+                const print = (msg) => (logger ? logger.info(msg.replace(/^\s*➜\s*/, '')) : console.log(msg));
+                if (!graphAvailable(projectRoot))
+                    print(GRAPH_MISSING_LINE);
+                else if (address?.port)
+                    print(`  ➜  Sygnal graph: http://localhost:${address.port}${GRAPH_PATH}`);
+            },
         },
     };
 }