sygnal 6.5.0 → 7.0.0

package/CHANGELOG.md

@@ -2,6 +2,162 @@
 
 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/).
+
+**Measured impact.** Size: the kanban gate stays flat, (a) 42,495 B with `nativeGlobalThis: false` (6.5.0: 42,496 B; budget 42,700 B): the runtime `contextConsumes` getter costs 9 B in the core, and nothing else in this release reaches an app bundle (the graph page, the Vite route, the dev stamps and the DevTools bridge are dev-only; a `vite build` contains none of them). The perf count gate is within its limits.
+
+**Companion packages.**
+- **`sygnal-check` 0.10.0:** `--graph=html` writes the graph as one self-contained page (no network, runs no app code) and opens it: cards for every component, render / Collection / Switchable / Vike layout edges, EVENTS, context and `PARENT` overlays, a health list, a detail panel with line links into the editor (`--editor`), traces of events, context fields, actions and state keys, search, filters, an EVENTS table, SVG / JSON / Mermaid export, and directory groups folded above 150 components. `--graph=html --watch` serves it on 127.0.0.1 behind a token and updates it on every save (`--poll`, `--port`). `--graph=mermaid` prints a flowchart (`--events=false`). `--out`, `--open` / `--no-open`. `--graph[=<format>] --base <ref>` compares the graph with a git ref without a checkout (`--graph --json --base` prints the diff for CI). The graph gains `key`, `entry`, `viewOnly`, Vike `route`s and layout edges, child `id` / `external` / `widget` / `state`, `childSelects`, `emitterIds` / `selectorIds`, `writes` / `removes` on actions, `stateReads`, and source lines on actions, selectors, children, context entries and EVENTS sites, in `--graph --json`, the MCP `graph` tool and the language server's new `sygnal/graph` request. New rules **SYG170** (a context field no provider above gives) and **SYG171** (`PARENT` that no parent selects). Its caret range doesn't reach 0.10.0 from `^0.9.0`, so update the dev dependency; `sygnal/vite`'s graph route needs 0.10.0 or later.
+- **`create-sygnal-app` 2.8.0:** every template depends on `sygnal` ^6.6.0 and `sygnal-check` ^0.10.0.
+- **VS Code extension 0.7.0:** **Sygnal: Show App Graph**, the page in a panel that updates as you type; bundles `sygnal-check` 0.10.0.
+- **Claude Code plugin 0.1.5:** the `sygnal-dev` skill mentions the graph page and `--graph --json`.
+
+### Added
+
+- **The app graph in the Vite dev server.** `sygnal/vite` serves the live graph page at `/__sygnal/graph` (local requests only) when `sygnal-check` 0.10.0 or later is installed, and prints its address. In dev it also stamps each component function with its static key (a non-enumerable `__sygnalKey`, reported by `inspect()` as `key`), so the page's **Live data** shows which components are mounted, their instance counts, a flash when an action runs and each instance's state, from the app tabs of the same origin. New option `graph` (default `true`); `graph: false` turns off the route, the stamps and the bridge. `vite build`, `vite preview` and Vitest get none of it.
+- **`installGraphBridge()`** in `sygnal/devtools`: connects the page's apps to the graph page's live data over a same-origin `BroadcastChannel` (`sygnal:graph`). The Vite plugin calls it in dev.
+- **App graph in the DevTools panel.** An **App graph** button draws the running app's `inspect()` graph with the same page: a card per component under each parent (`×N` for several instances), each app as its own group, action flashes and instance state.
+- **More in the runtime `inspect()`** (the `sygnal/diagnostics` dev entry): `key`, `entry`, `viewOnly`, `app`, `shown`, `children[].ids`, `events[type].emitterIds` / `selectorIds`, the time of each diagnostic (`timestamp`), and `contextConsumes`: the context fields the component's latest render read (a read-only getter in the core, 9 B gzip). The `InspectGraph` type gains these and the static graph's new fields, all optional.
+
+### Fixed
+
+- **A Transition's leave, or a Portal mounted late, under jsdom.** The DOM "poke" that re-emits the app's DOM source after such a change created its event with the global `Event`. jsdom refuses an event from another realm, so a jsdom test whose environment was torn down while a leave transition's timer was pending failed with "parameter 1 is not of type 'Event'" (the 6.5.0 release's CI run did once). It now creates the event from the element's own window. Browsers were not affected.
+- **Nested Vike Layouts and Wrappers (`sygnal/vike`).** Vike lists a cumulative config's values closest to the page first, so a page under `pages/admin/` gets `[adminLayout, rootLayout]`. `sygnal/vike` treated the first as the outermost, so the admin Layout rendered outside the root Layout, on the server and on hydration. Client-side navigation also kept the first page's Layouts and Wrappers, so going from `/` to `/admin` never added the admin Layout (nor did going back remove it), and navigating from a page with no Layout to one with a Layout swapped the Page into the old app. Now the root's Layout is outermost and every Wrapper is outside every Layout, as in `vike-react`. Navigation keeps mounted, with their state, the Layouts and Wrappers that two pages share (from the outside in), adds the new page's others and removes the ones it lacks. A page with one Layout and one Wrapper renders and hydrates as before. The Vike example has an `/admin` page with a nested Layout.
+
 ## 6.5.0 — 2026-10-14
 
 State paths: a child's `state`, a Switchable's `state` and a Collection's `from` reach nested state (`state="settings.rules"`, `from="board.cards"`) without a hand-written lens. Additive, except that a `state` / `from` string with a `.` or `[` now means a path (SYG428 reports a state that still has a key with a dot in its name). The first full release published by the keyless release workflow.

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.