sygnal 6.4.0 → 6.6.0

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 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.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.
+
+**Measured impact.** Size: the kanban gate goes down, (a) 42,496 B with `nativeGlobalThis: false` (was 42,527 B; budget 42,700 B): the path cell adds about 107 B, and moving the string-`from` SYG401 checks out of the core saves more than that.
+
+**Companion packages.**
+- **`sygnal-check` 0.9.0:** SYG401 follows a `from` path through the literal `initialState`; rename, definition and references treat a path's first segment as a use of that state key. Its caret range doesn't reach 0.9.0 from `^0.8.0`, so update the dev dependency.
+- **`create-sygnal-app` 2.7.0:** every template depends on `sygnal` ^6.5.0 and `sygnal-check` ^0.9.0.
+- **VS Code extension 0.6.0:** bundles `sygnal-check` 0.9.0. The extension itself doesn't change.
+- **Claude Code plugin 0.1.4:** the `sygnal-dev` skill describes state paths.
+
+### Added
+
+- **State paths.** A child's `state`, a Switchable's `state` and a Collection's (and VirtualCollection's) `from` take a path into nested state: `<RulesPanel state="settings.rules" />`, `<BoardTitle state="boards[0].title" />`, `<Collection of={Card} from="board.cards" />`. Reads follow the path; a write copies only the objects and arrays on it, so untouched branches keep their identity, as a hand-written lens would (a missing level is created as an object when an `isolatedState` child first writes). A calculated first segment is read-only (SYG409), as a calculated key is. For list items, `byId('boards', id)` stays the way to follow an item rather than a position. Typed Collections accept dotted paths to nested arrays (`ArrayPathsOf<STATE>`, three levels). There is no array form (`state={['a', 'b']}`): an array `state` / `from` is still the data passed by mistake (SYG410 / SYG412).
+- **New SYG428** (warn, dev diagnostics): a `state="a.b"` or `from="a.b"` whose owner's state has a key named `"a.b"` (see Changed).
+
+### Changed
+
+- **A `state` / `from` string with a `.` or `[` is now a path.** Before, `state="a.b"` meant the key named `"a.b"`; now it means `state.a.b`. A state that still has a key with a dot in its name is reported as SYG428 in development; keep it with a lens (`state={{ get: (s) => s['a.b'], set: (s, v) => ({ ...s, 'a.b': v }) }}`) or rename the key.
+- **SYG401 for a string `from` is reported by the development diagnostics only** (`sygnal/diagnostics`, which `sygnal/vite` loads in dev and `renderComponent` in tests): a `from` key or path that isn't in state, or isn't an array. Production builds no longer carry or print it (D22 had the core report it in every mode); the core still reports a lens getter that returns a non-array (SYG401) and an invalid `from` (SYG412). The kanban gate goes down 31 B (42,527 → 42,496 B) with state paths included.
+- **`sygnal-check`: SYG401 follows a `from` path** through the literal `initialState` (a missing key along the way names the keys of that level; it stops where a value isn't a literal), and the editor features (rename, go to definition, references) treat a path's first segment as a use of that state key, so renaming `board` edits `from="board.cards"` to `from="deck.cards"`.
+
+### Fixed
+
+- **State guide:** a child bound to a property that is `undefined` renders nothing until the property exists (only an `isolatedState` child renders and creates it); the guide said the property "gets added when the child first updates".
+
+## VS Code extension 0.5.1 — 2026-10-14
+
+Bundles `sygnal-check` 0.8.1 (the SYG427 fixes above); the extension's own code doesn't change. The first extension release published by the keyless release workflow: the VS Code Marketplace through Microsoft Entra ID, Open VSX through trusted publishing.
+
+## sygnal-check 0.8.1 — 2026-10-14
+
+A patch for SYG427 (new in 0.8.0), reported from a real project; `sygnal` itself is unchanged (6.4.0). Projects on `sygnal-check` ^0.8.0 get it on their next install. The first release published by the keyless release workflow (npm trusted publishing, with provenance).
+
+### Fixed
+
+- **SYG427 is filed under the component that has the mistake.** It was labelled with the imported component (`RuleForm: RuleForm is imported from …`), which may not exist at all (the import is `undefined`), while every other finding in the file, and the runtime SYG427 for the same mistake, names the component whose view or intent uses it. It now names that component (`RulesPanel: …`), or the file outside any component; the imported name stays in the message and `data.name`.
+- **SYG427's fix says how the module does export the component.** A named import of a module that only has a default export (`import { RuleForm } from './RuleForm.jsx'` for `export default RuleForm`) now gets `'./RuleForm.jsx' exports a default: import RuleForm from './RuleForm.jsx'`, and a default import of a named export the reverse, instead of "export it from …". The remaining case reads `export it from '…' with export function X, or fix the name`, without the parenthetical that nested inside the formatter's parentheses.
+
 ## 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).

package/dist/astro/index.cjs.js

@@ -357,11 +357,11 @@ function inAllowed(h, allowed) {
         return e.startsWith('.') ? h === e.slice(1) || h.endsWith(e) : h === e;
     });
 }
-/** Why the request is refused (403), or null */
-function refusal(req, allowedHosts) {
+/** Why the request is refused (403), or null. PLAN-10 W-2: the graph route (./graph.ts) uses the same guard */
+function refusal(req, allowedHosts, what = 'the Sygnal MCP endpoint') {
     const remote = String(req?.socket?.remoteAddress || '');
     if (!LOOPBACK_IP.test(remote))
-        return `the Sygnal MCP endpoint only answers requests from this machine (not ${remote || 'an unknown address'})`;
+        return `${what} only answers requests from this machine (not ${remote || 'an unknown address'})`;
     const host = req?.headers?.host;
     if (typeof host !== 'string' || !host)
         return 'missing Host header';
@@ -623,6 +623,267 @@ if (import.meta.hot) installMcpBridge(import.meta.hot, { agentTools, confirm: ${
 `;
 }
 
+/**
+ * PLAN-10 W-2 / P-2: the live app graph page of sygnal/vite's dev server (D543, D544).
+ *
+ * `/__sygnal/graph` serves sygnal-check's graph page (`graphHtml`, the same file `sygnal-check
+ * --graph=html --watch` serves) in live mode, and `/__sygnal/graph/events` its SSE stream: the
+ * whole graph (`event: graph`, `id: <version>`) on connect (unless `Last-Event-ID` already has it)
+ * and after each build whose graph changed, a `: ping` comment every 25 s. Dev server only.
+ *
+ * One live project (sygnal-check's createLiveProject, W-1) feeds the page, the check overlay and
+ * the console (the plugin's `check`): each build gives the graph and the diagnostics, so they agree.
+ * It builds on start and 100 ms after the last source or config file change Vite's watcher reports.
+ *
+ * P-2: each build also gives the top-level binding and static key (D521: 'file#name', '#2' for a
+ * second of the same name in a file) of every component in a scanned file (sygnal-check's
+ * componentStamps); the dev transform appends to those modules a tail that sets a non-enumerable
+ * `__sygnalKey` on each component function, and the runtime inspect() reports it as `key`. A
+ * module whose text changed since the last build is built again first, so a stamp is never stale.
+ *
+ * The page is served on the app's origin: its "Live data" (graphView/liveData.js) joins the open
+ * app tabs over a BroadcastChannel (src/extra/devGraph.ts), with no server in between.
+ *
+ * Security: the same guard as `/__sygnal/mcp` (./mcp.ts refusal(): a loopback peer, a local Host
+ * (or one in `server.allowedHosts`), a local Origin when there is one); GET and HEAD only; the page
+ * gets `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`,
+ * `X-Frame-Options: DENY` and a CSP (inline style and script, `connect-src 'self'`, no framing).
+ * Read only: it serves the page and the stream, nothing else.
+ */
+// @ts-ignore
+const GRAPH_PATH = '/__sygnal/graph';
+const GRAPH_EVENTS = GRAPH_PATH + '/events';
+const GRAPH_CLIENT = 'virtual:sygnal/graph';
+const GRAPH_CHANNEL = 'sygnal:graph';
+/** The property the dev transform sets on component functions (read by inspect()) */
+const STAMP_PROP = '__sygnalKey';
+const SOURCE_RE$1 = /\.[cm]?[jt]sx?$/;
+const CONFIG_FILES$1 = ['sygnal-check.config.json', 'package.json'];
+const EMPTY = { version: 1, source: 'static', components: [], events: {}, diagnostics: [] };
+const PAGE_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; img-src data: blob:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+const SECURITY = { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer', 'X-Frame-Options': 'DENY' };
+const posix = (p) => p.split(path.sep).join('/');
+/** Whether the project's sygnal-check has the live graph page with "Live data" (checked without loading it). */
+function graphAvailable(root) {
+    try {
+        const main = node_module.createRequire(path.join(root, 'package.json')).resolve('sygnal-check');
+        return fs.existsSync(path.join(path.dirname(main), 'graphView', 'liveData.js'));
+    }
+    catch (_) {
+        return false;
+    }
+}
+/**
+ * The live project behind the page and the checker. `settings` are live.js's (paths = the check's
+ * include, strict / a11y / ignore / defaults as the checker resolves them).
+ */
+function createEngine(mod, root, settings, logger, stamps) {
+    const live = mod.createLiveProject({ root });
+    const listeners = [];
+    let last = null;
+    // the stamps by the live project's path of each file; `known` maps a module path as Vite gives it
+    // (posix, possibly through a symlink) to that path
+    let stampsByFile = new Map();
+    let known = new Map();
+    let failed = '';
+    const real = (f) => { try {
+        return posix(fs.realpathSync(f));
+    }
+    catch (_) {
+        return posix(f);
+    } };
+    const build = () => {
+        let b;
+        try {
+            b = live.build({ settings, stamps });
+        }
+        catch (err) {
+            const msg = String(err?.message || err);
+            if (msg !== failed)
+                logger.warn(`[sygnal] sygnal-check failed: ${msg}`, { timestamp: true });
+            failed = msg;
+            return null;
+        }
+        failed = '';
+        if (!b.graph)
+            b = { ...b, json: JSON.stringify(EMPTY) };
+        last = b;
+        stampsByFile = b.stamps || new Map();
+        known = new Map();
+        for (const f of b.files || []) {
+            known.set(posix(f), f);
+            known.set(real(f), f);
+        }
+        for (const fn of listeners) {
+            try {
+                fn(b);
+            }
+            catch (_) { /* a listener never stops the others */ }
+        }
+        return b;
+    };
+    const stampsFor = (file) => {
+        if (!last)
+            return null;
+        const own = known.get(posix(file)) ?? known.get(real(file));
+        if (!own)
+            return null;
+        let text = null;
+        try {
+            text = fs.readFileSync(own, 'utf8');
+        }
+        catch (_) { }
+        const entry = live.cache?.get?.(own);
+        // changed since the last build (Vite transforms it before the watcher's debounced build)
+        if (text !== null && (!entry || entry.text !== text))
+            build();
+        return stampsByFile.get(own) || null;
+    };
+    let timer;
+    const watch = (server) => {
+        const onChange = (file) => {
+            if (String(file).split(/[\\/]/).includes('node_modules'))
+                return;
+            if (!SOURCE_RE$1.test(file) && !CONFIG_FILES$1.includes(path.basename(file)))
+                return;
+            clearTimeout(timer);
+            timer = setTimeout(build, 100);
+        };
+        const watcher = server?.watcher;
+        if (watcher && typeof watcher.on === 'function') {
+            watcher.on('change', onChange);
+            watcher.on('add', onChange);
+            watcher.on('unlink', onChange);
+        }
+        try {
+            server.httpServer?.once?.('close', () => clearTimeout(timer));
+        }
+        catch (_) { }
+    };
+    return {
+        build, stampsFor, watch, mod,
+        get last() { return last; },
+        onBuild(fn) { listeners.push(fn); },
+    };
+}
+/** The tail the dev transform appends to a module: a non-enumerable key on each component function. */
+function stampTail(list) {
+    const ok = list.filter(s => /^[A-Za-z_$][\w$]*$/.test(s.binding));
+    if (!ok.length)
+        return '';
+    const pairs = ok.map(s => `[typeof ${s.binding} == 'function' ? ${s.binding} : null, ${JSON.stringify(s.key)}]`).join(', ');
+    return `\n;(() => { try { for (const [f, k] of [${pairs}]) if (f) Object.defineProperty(f, '${STAMP_PROP}', { value: k, configurable: true }) } catch (_) {} })();\n`;
+}
+/** 'virtual:sygnal/graph': the app side of the page's "Live data" (dev only) */
+function graphClientModule() {
+    return `import { installGraphBridge } from 'sygnal/devtools';\ninstallGraphBridge({ channel: ${JSON.stringify(GRAPH_CHANNEL)} });\n`;
+}
+function deny(res, status, text, headers = {}) {
+    res.statusCode = status;
+    for (const k in { ...SECURITY, ...headers })
+        res.setHeader(k, { ...SECURITY, ...headers }[k]);
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+    res.end(text + '\n');
+}
+function projectTitle(root) {
+    try {
+        const name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name;
+        if (typeof name === 'string' && name)
+            return name;
+    }
+    catch (_) { }
+    return path.basename(root);
+}
+/**
+ * The middleware for `/__sygnal/graph` and its stream. `engine` resolves to null when sygnal-check
+ * isn't installed (or too old): the route then answers 404 with the install hint.
+ */
+function graphMiddleware(server, root, engine, ping = 25000) {
+    const streams = new Set();
+    let subscribed = false;
+    let pinger = null;
+    const event = (b) => `event: graph\nid: ${b.version}\ndata: ${b.json}\n\n`;
+    const subscribe = (e) => {
+        if (subscribed)
+            return;
+        subscribed = true;
+        e.onBuild((b) => { if (b.changed)
+            for (const res of streams)
+                res.write(event(b)); });
+        pinger = setInterval(() => { for (const res of streams)
+            res.write(': ping\n\n'); }, ping);
+        pinger.unref?.();
+        try {
+            server.httpServer?.once?.('close', () => {
+                clearInterval(pinger);
+                for (const res of streams)
+                    res.end();
+                streams.clear();
+            });
+        }
+        catch (_) { }
+    };
+    return async (req, res, next) => {
+        const url = String(req.url || '').replace(/[?#].*$/, '');
+        if (url !== GRAPH_PATH && url !== GRAPH_PATH + '/' && url !== GRAPH_EVENTS)
+            return next();
+        const why = refusal(req, server?.config?.server?.allowedHosts, 'the Sygnal graph page');
+        if (why)
+            return deny(res, 403, `Forbidden: ${why}`);
+        if (req.method !== 'GET' && req.method !== 'HEAD')
+            return deny(res, 405, 'Method not allowed', { Allow: 'GET, HEAD' });
+        const e = await engine;
+        if (!e)
+            return deny(res, 404, 'The Sygnal graph page needs a sygnal-check with the live graph page in the project: npm i -D sygnal-check@latest');
+        subscribe(e);
+        const b = e.last || e.build();
+        if (!b)
+            return deny(res, 500, 'sygnal-check failed: see the dev server output');
+        if (url === GRAPH_EVENTS) {
+            res.writeHead(200, { ...SECURITY, 'Content-Type': 'text/event-stream; charset=utf-8', Connection: 'keep-alive', 'Content-Security-Policy': "default-src 'none'" });
+            if (req.method === 'HEAD')
+                return res.end();
+            res.write('retry: 1000\n\n');
+            if (req.headers['last-event-id'] !== String(b.version))
+                res.write(event(b));
+            streams.add(res);
+            req.on('close', () => streams.delete(res));
+            return;
+        }
+        let body;
+        try {
+            body = e.mod.graphHtml(b.graph || EMPTY, {
+                title: projectTitle(root),
+                subtitle: 'dev server',
+                root,
+                live: { events: GRAPH_EVENTS, version: b.version },
+                appData: { channel: GRAPH_CHANNEL },
+            });
+        }
+        catch (err) {
+            return deny(res, 500, `The graph page failed: ${err?.message || err}`);
+        }
+        res.writeHead(200, { ...SECURITY, 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': PAGE_CSP, 'Content-Length': globalThis.Buffer.byteLength(body) });
+        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) {
+    const print = server?.printUrls;
+    if (typeof print !== 'function')
+        return;
+    server.printUrls = function (...args) {
+        const out = print.apply(this, args);
+        try {
+            const local = server.resolvedUrls?.local?.[0];
+            if (local)
+                (server.config?.logger || console).info(`  ➜  Sygnal graph: ${new URL(local).origin}${GRAPH_PATH}`);
+        }
+        catch (_) { }
+        return out;
+    };
+}
+
 /**
  * Sygnal Vite Plugin
  *
@@ -748,6 +1009,21 @@ if (import.meta.hot) installMcpBridge(import.meta.hot, { agentTools, confirm: ${
  *      `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).
+ *  12. `graph` option (PLAN-10 W-2 / P-2, D543 / D544, default true; dev server only, never
+ *      `vite build`, `vite preview` or Vitest): the live app graph page at /__sygnal/graph, with
+ *      its SSE stream at /__sygnal/graph/events (./graph.ts; the /__sygnal/mcp guard: loopback
+ *      peer, local Host or server.allowedHosts, local Origin). sygnal-check (from the project,
+ *      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
+ *      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'
+ *      (installGraphBridge from 'sygnal/devtools'), which answers the page's "Live data" over a
+ *      same-origin BroadcastChannel: the page fades components with no instance, shows instance
+ *      counts, flashes a card when its action runs and shows an instance's state. `graph: false`:
+ *      no route, stamps or bridge (the checker of 5 runs check() as before).
  *
  * Why not Vite's `define`? Vite's dependency optimizer does not apply user
  * `define` replacements to pre-bundled dependencies (only process.env.NODE_ENV),
@@ -791,6 +1067,8 @@ const OVERLAY_PLUGIN = 'sygnal-check';
 // PLAN-6 E-1: the page side of the dev MCP endpoint
 const MCP_CLIENT = 'virtual:sygnal/mcp';
 const MCP_CLIENT_ID = '\0' + MCP_CLIENT;
+// PLAN-10 P-2: the page side of the graph page's "Live data"
+const GRAPH_CLIENT_ID = '\0' + GRAPH_CLIENT;
 // Register the runtime checks with the core that loaded last (see the Vike wrapper)
 const REINSTALL_IMPORT = `import { installChecks as __sygnalInstallChecks } from 'sygnal/diagnostics';`;
 const REINSTALL_CALL = 'try { __sygnalInstallChecks() } catch (e) { console.warn(e) }\n';
@@ -814,11 +1092,17 @@ function sygnal(options = {}) {
     const mcpOptions = typeof options.mcp === 'object' && options.mcp ? options.mcp : {};
     const devtoolsOn = options.devtools !== false || mcpOn;
     const redux = typeof options.devtools == 'object' && !!options.devtools?.redux;
-    const devtoolsImport = (!devtoolsOn ? ''
+    // PLAN-10 W-2 / P-2 (D543, D544): the graph page, the component stamps and (with DevTools and a
+    // sygnal-check that has the page, decided in config()) the app side of its "Live data"
+    const graphOn = options.graph !== false;
+    let graphClient = false;
+    let engine = null;
+    const devtoolsBase = (!devtoolsOn ? ''
         : redux ? `import { connectReduxDevtools as __sygnalReduxDevtools } from 'sygnal/devtools';__sygnalReduxDevtools();`
             : `import 'sygnal/devtools';`) + (mcpOn ? `import '${MCP_CLIENT}';` : '');
+    let devtoolsImport = devtoolsBase;
     // What a dev entry gets: DevTools, then (unless diagnostics are 'off') flags + checks
-    const devSnippet = devtoolsImport + (devOn ? flags + devImports : '');
+    let devSnippet = devtoolsImport + (devOn ? flags + devImports : '');
     const devInject = devOn || devtoolsOn;
     let astroClient;
     return {
@@ -827,6 +1111,10 @@ function sygnal(options = {}) {
             isServe = env.command === 'serve';
             isVitest = !!nodeProcess?.env?.VITEST;
             root = config?.root ? path.resolve(config.root) : nodeProcess.cwd();
+            // P-2: the graph page's app side, in the dev server only, when the page can exist
+            graphClient = isServe && !isVitest && graphOn && devtoolsOn && graphAvailable(root);
+            devtoolsImport = devtoolsBase + (graphClient ? `import '${GRAPH_CLIENT}';` : '');
+            devSnippet = devtoolsImport + (devOn ? flags + devImports : '');
             const result = {
                 // Ensure sygnal is bundled for SSR rather than externalized.
                 // Without this, Node fails to resolve sygnal's exports from
@@ -931,6 +1219,8 @@ function sygnal(options = {}) {
                     return DEV_CLIENT_ID;
                 if (source === MCP_CLIENT && mcpOn)
                     return MCP_CLIENT_ID;
+                if (source === GRAPH_CLIENT && graphClient)
+                    return GRAPH_CLIENT_ID;
                 if (source === 'sygnal' && importer && wrapRun && runtimeImporters.has(cleanId(importer))) {
                     return RUNTIME_ID;
                 }
@@ -953,6 +1243,8 @@ function sygnal(options = {}) {
                 return devClientModule();
             if (id === MCP_CLIENT_ID && mcpOn)
                 return mcpClientModule(mcpOptions);
+            if (id === GRAPH_CLIENT_ID && graphClient)
+                return graphClientModule();
             if (id === RUNTIME_ID)
                 return runtimeModule(diagnostics);
             // The checks register again once the real entry has loaded: a
@@ -972,15 +1264,27 @@ function sygnal(options = {}) {
             if (mcpOn && server?.middlewares) {
                 attachMcp(server, root, mcpOptions, sygnalVersion(root));
             }
-            if (options.check === false)
+            const checkOn = options.check !== false;
+            if (!checkOn && !graphOn)
                 return;
             const checkOptions = typeof options.check === 'object' && options.check ? options.check : {};
-            // Deferred: the dev server doesn't wait for the first check
             const checkDefaults = { strict: diagnostics.strict, ignore: diagnostics.ignore };
-            setTimeout(() => {
-                startChecker(server, root, checkOptions, checkDefaults, options.check !== undefined)
-                    .catch(err => server?.config?.logger?.warn?.(`[sygnal] sygnal-check could not start: ${err?.message || err}`));
-            }, 0);
+            // Deferred: the dev server doesn't wait for the first check. `engine`: the live graph
+            // project (W-2), null without a sygnal-check that has it
+            engine = new Promise((resolve) => {
+                setTimeout(() => {
+                    startDev(server, root, checkOptions, checkDefaults, options.check !== undefined, checkOn, graphOn).then(resolve, (err) => {
+                        server?.config?.logger?.warn?.(`[sygnal] sygnal-check could not start: ${err?.message || err}`);
+                        resolve(null);
+                    });
+                }, 0);
+            });
+            // 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);
+            }
         },
         transform(code, id, opts) {
             // SYG666 (PLAN-5 W-2): an adapter entry imported without its optional peers; every mode
@@ -989,7 +1293,10 @@ function sygnal(options = {}) {
                 ? 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;
+            const words = isServe && !isVitest && devOn && !opts?.ssr ? viewTokensTail(this, code, id) : null;
+            // 12. P-2 (D544): the static keys of the module's components (dev server, graph on)
+            const stamps = engine && isServe && !isVitest && !opts?.ssr ? componentStampTail(engine, id) : null;
+            const tokens = words && stamps ? Promise.all([words, stamps]).then(([a, b]) => a + b) : words || stamps;
             if (!tokens)
                 return result;
             return Promise.all([result, tokens]).then(([r, tail]) => {
@@ -1081,6 +1388,25 @@ function sygnal(options = {}) {
         return done();
     }
 }
+// 12. PLAN-10 P-2 (D544): a module of the scanned files gets, in dev, a tail that sets each of its
+// components' static key (sygnal-check's D521 'file#name', from the live graph engine's last build,
+// built again first when the module's text changed) as a non-enumerable `__sygnalKey` on the
+// function; the runtime inspect() reports it as `key`, and the graph page joins instances to cards.
+function componentStampTail(engine, id) {
+    const file = cleanId(id);
+    if (!/\.[cm]?[jt]sx?$/.test(file) || id.includes('node_modules') || id.startsWith('\0'))
+        return null;
+    return engine.then((e) => {
+        if (!e)
+            return '';
+        try {
+            return stampTail(e.stampsFor(file) || []);
+        }
+        catch (_) {
+            return '';
+        }
+    });
+}
 // 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
@@ -1415,16 +1741,39 @@ function checkInclude(root, include, notice, label = 'check.include') {
     notice(`[sygnal] sygnal-check: no ${DEFAULT_INCLUDE.join('/, ')}/ directory under ${root}; checking the project root (set check.include to choose)`);
     return ['.'];
 }
-/** Run sygnal-check now and after source changes; report to the terminal and the browser. */
-async function startChecker(server, root, opts, defaults, explicit) {
+/**
+ * Load sygnal-check and start what dev uses it for: the checker (`check`, reported to the terminal
+ * and the browser) and the live graph engine (`graph`, PLAN-10 W-2: the page, its stream and the
+ * component stamps). With an engine, both come from one build. Resolves to the engine, or null.
+ */
+async function startDev(server, root, opts, defaults, explicit, checkOn, graphOn) {
     const mod = await loadSygnalCheck(root);
     const logger = server?.config?.logger || console;
     if (!mod || typeof mod.check !== 'function') {
-        if (explicit)
+        if (explicit && checkOn)
             logger.info('[sygnal] sygnal-check is not installed, so static checks are off (npm i -D sygnal-check)');
-        return;
+        return null;
+    }
+    const setup = checkSetup(mod, root, opts, defaults, (m) => logger.info(m));
+    // PLAN-10 W-2: a sygnal-check with the live project and the page (feature-detected, so an older
+    // one keeps the checker as it was)
+    const engine = graphOn && setup.configAware && typeof mod.createLiveProject === 'function' && typeof mod.graphHtml === 'function'
+        ? createEngine(mod, root, {
+            paths: setup.include, strict: setup.checkOptions.strict, a11y: setup.checkOptions.a11y,
+            ignore: setup.checkOptions.ignore, defaults: setup.checkOptions.defaults,
+        }, logger, true)
+        : null;
+    if (checkOn)
+        startChecker(server, root, mod, setup, opts, engine);
+    if (engine) {
+        if (!engine.last)
+            engine.build();
+        engine.watch(server);
     }
-    const notice = (m) => logger.info(m);
+    return engine;
+}
+/** What sygnal-check checks, with which options (see the `check` option). */
+function checkSetup(mod, root, opts, defaults, notice) {
     // PLAN-7 C-5 (D299): a sygnal-check with config support resolves the settings itself:
     // explicit check.* options > its config file > the `diagnostics` defaults passed as `defaults`.
     // An older one gets exactly what it got before.
@@ -1460,6 +1809,16 @@ async function startChecker(server, root, opts, defaults, explicit) {
             a11y: opts.a11y === 'error' ? 'error' : 'warn',
         };
     }
+    return { include, checkOptions, configAware };
+}
+/**
+ * Run sygnal-check now and after source changes; report to the terminal and the browser. With the
+ * live graph engine (W-2) the findings come from its builds (one build for the page and the
+ * checker); else from check() on each change.
+ */
+function startChecker(server, root, mod, setup, opts, engine) {
+    const logger = server?.config?.logger || console;
+    const { include, checkOptions, configAware } = setup;
     const a11y = checkOptions.a11y;
     // Only error-severity findings open Vite's overlay: while an overlay is open
     // Vite's client reloads the page on the first HMR update, so warnings stay
@@ -1488,14 +1847,18 @@ async function startChecker(server, root, opts, defaults, explicit) {
         }
         catch (_) { }
     };
-    const run = (initial = false) => {
+    const run = (initial = false, built) => {
         let diags;
-        try {
-            diags = mod.check(include, checkOptions);
-        }
-        catch (err) {
-            logger.warn(`[sygnal] sygnal-check failed: ${err?.message || err}`, { timestamp: true });
-            return;
+        if (built)
+            diags = built;
+        else {
+            try {
+                diags = mod.check(include, checkOptions);
+            }
+            catch (err) {
+                logger.warn(`[sygnal] sygnal-check failed: ${err?.message || err}`, { timestamp: true });
+                return;
+            }
         }
         // A sygnal-check from before D144 reports SYG7xx as errors under strict: keep them warnings
         // (one with config support postdates D144 and resolves a11y itself)
@@ -1536,7 +1899,15 @@ async function startChecker(server, root, opts, defaults, explicit) {
         if (!initial)
             broadcast(changed);
     };
-    run(true);
+    if (engine) {
+        // every build of the engine: the first on start, then after changes (its own watcher)
+        let first = !engine.last;
+        engine.onBuild((b) => { const initial = first; first = false; run(initial, b.diagnostics || []); });
+        if (engine.last)
+            run(true, engine.last.diagnostics || []);
+    }
+    else
+        run(true);
     // A page that loads (or reloads) asks for the current findings: answer
     // that client only, never every client.
     try {
@@ -1551,6 +1922,8 @@ async function startChecker(server, root, opts, defaults, explicit) {
         });
     }
     catch (_) { }
+    if (engine)
+        return;
     let timer;
     const onChange = (file) => {
         if (file.split(/[\\/]/).includes('node_modules'))