sygnal 6.5.0 → 7.0.0

package/dist/vite/plugin.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,275 @@ 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);
+    };
+}
+/** 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 (!available)
+                logger.info(GRAPH_MISSING_LINE);
+            else if (local)
+                logger.info(`  ➜  Sygnal graph: ${new URL(local).origin}${GRAPH_PATH}`);
+        }
+        catch (_) { }
+        return out;
+    };
+}
+
 /**
  * Sygnal Vite Plugin
  *
@@ -748,6 +1017,22 @@ 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"; 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'
+ *      (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 +1076,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';
@@ -806,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
@@ -814,11 +1101,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 +1120,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 +1228,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 +1252,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 +1273,26 @@ 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));
+                printGraphUrl(server, graphAvailable(root));
+            }
         },
         transform(code, id, opts) {
             // SYG666 (PLAN-5 W-2): an adapter entry imported without its optional peers; every mode
@@ -989,7 +1301,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 +1396,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
@@ -1242,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) {
@@ -1415,16 +1749,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 +1817,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 +1855,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 +1907,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 +1930,8 @@ async function startChecker(server, root, opts, defaults, explicit) {
         });
     }
     catch (_) { }
+    if (engine)
+        return;
     let timer;
     const onChange = (file) => {
         if (file.split(/[\\/]/).includes('node_modules'))
@@ -1573,6 +1954,8 @@ async function startChecker(server, root, opts, defaults, explicit) {
 }
 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