sygnal 6.5.0 → 7.0.0

package/src/vite/graph.ts

@@ -0,0 +1,255 @@
+/**
+ * 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
+import fs from 'node:fs'
+// @ts-ignore
+import path from 'node:path'
+// @ts-ignore
+import { createRequire } from 'node:module'
+import { refusal } from './mcp'
+
+export const GRAPH_PATH = '/__sygnal/graph'
+export const GRAPH_EVENTS = GRAPH_PATH + '/events'
+export const GRAPH_CLIENT = 'virtual:sygnal/graph'
+export const GRAPH_CHANNEL = 'sygnal:graph'
+/** The property the dev transform sets on component functions (read by inspect()) */
+export const STAMP_PROP = '__sygnalKey'
+
+const SOURCE_RE = /\.[cm]?[jt]sx?$/
+const CONFIG_FILES = ['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: Record<string, string> = { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer', 'X-Frame-Options': 'DENY' }
+
+const posix = (p: string) => p.split(path.sep).join('/')
+
+/** Whether the project's sygnal-check has the live graph page with "Live data" (checked without loading it). */
+export function graphAvailable(root: string): boolean {
+  try {
+    const main = createRequire(path.join(root, 'package.json')).resolve('sygnal-check')
+    return fs.existsSync(path.join(path.dirname(main), 'graphView', 'liveData.js'))
+  } catch (_) {
+    return false
+  }
+}
+
+export interface LiveBuild { graph: any; json: string; version: number; changed: boolean; diagnostics: any[]; stamps: Map<string, Array<{ binding: string; key: string }>> | null; files: string[] }
+
+export interface LiveEngine {
+  /** build now; listeners hear about it */
+  build(): LiveBuild | null
+  readonly last: LiveBuild | null
+  onBuild(fn: (b: LiveBuild) => void): void
+  /** the stamps of a module (absolute path), after building again when its text changed */
+  stampsFor(file: string): Array<{ binding: string; key: string }> | null
+  /** follow Vite's watcher (100 ms debounce) */
+  watch(server: any): void
+  readonly mod: any
+}
+
+/**
+ * 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).
+ */
+export function createEngine(mod: any, root: string, settings: any, logger: any, stamps: boolean): LiveEngine {
+  const live = mod.createLiveProject({ root })
+  const listeners: Array<(b: LiveBuild) => void> = []
+  let last: LiveBuild | null = 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<string, Array<{ binding: string; key: string }>>()
+  let known = new Map<string, string>()
+  let failed = ''
+  const real = (f: string) => { try { return posix(fs.realpathSync(f)) } catch (_) { return posix(f) } }
+
+  const build = (): LiveBuild | null => {
+    let b: any
+    try {
+      b = live.build({ settings, stamps })
+    } catch (err: any) {
+      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: string) => {
+    if (!last) return null
+    const own = known.get(posix(file)) ?? known.get(real(file))
+    if (!own) return null
+    let text: string | null = 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: any
+  const watch = (server: any) => {
+    const onChange = (file: string) => {
+      if (String(file).split(/[\\/]/).includes('node_modules')) return
+      if (!SOURCE_RE.test(file) && !CONFIG_FILES.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. */
+export function stampTail(list: Array<{ binding: string; key: string }>): string {
+  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) */
+export function graphClientModule(): string {
+  return `import { installGraphBridge } from 'sygnal/devtools';\ninstallGraphBridge({ channel: ${JSON.stringify(GRAPH_CHANNEL)} });\n`
+}
+
+function deny(res: any, status: number, text: string, headers: Record<string, string> = {}) {
+  res.statusCode = status
+  for (const k in { ...SECURITY, ...headers }) res.setHeader(k, ({ ...SECURITY, ...headers } as any)[k])
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+  res.end(text + '\n')
+}
+
+function projectTitle(root: string): string {
+  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.
+ */
+export function graphMiddleware(server: any, root: string, engine: Promise<LiveEngine | null>, ping = 25000) {
+  const streams = new Set<any>()
+  let subscribed = false
+  let pinger: any = null
+  const event = (b: LiveBuild) => `event: graph\nid: ${b.version}\ndata: ${b.json}\n\n`
+  const subscribe = (e: LiveEngine) => {
+    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: any, res: any, next: any) => {
+    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: string
+    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: any) {
+      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 as any).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). */
+export 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.
+ */
+export function printGraphUrl(server: any, available = true) {
+  const print = server?.printUrls
+  if (typeof print !== 'function') return
+  server.printUrls = function (this: any, ...args: any[]) {
+    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
+  }
+}

package/src/vite/mcp.ts

@@ -337,10 +337,10 @@ function inAllowed(h: string, allowed: any): boolean {
   })
 }
 
-/** Why the request is refused (403), or null */
-export function refusal(req: any, allowedHosts?: any): string | null {
+/** Why the request is refused (403), or null. PLAN-10 W-2: the graph route (./graph.ts) uses the same guard */
+export function refusal(req: any, allowedHosts?: any, what = 'the Sygnal MCP endpoint'): string | null {
   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'})`
+  if (!LOOPBACK_IP.test(remote)) 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'
   const h = hostname(host)

package/src/vite/plugin.d.ts

@@ -12,6 +12,13 @@ export interface DiagnosticsPluginOptions {
    * @default false
    */
   strict?: boolean
+  /**
+   * 7.0 timing audit (SYG257, info): the dev snippet sets `globalThis.__SYGNAL_TIMING_AUDIT__ =
+   * true`, and each output sink that reads a top-level state field its action's STATE changed is
+   * reported (since 7.0 it gets the new value; 6.x gave it the old one). For migrating 6.x code.
+   * @default false
+   */
+  timingAudit?: boolean
   /** Diagnostic codes to drop, e.g. ['SYG105'] (runtime and static) */
   ignore?: string[]
 }
@@ -136,6 +143,18 @@ export interface SygnalPluginOptions {
    * @default false
    */
   mcp?: boolean | McpPluginOptions
+
+  /**
+   * Serve the live app graph page at `/__sygnal/graph` on the dev server (requests from this
+   * machine with a local Host / Origin only, as `/__sygnal/mcp`), built by sygnal-check and updated
+   * on every save; its URL is printed under Vite's. Skipped silently when sygnal-check isn't
+   * installed. In dev the component functions also get their static key (non-enumerable, read by
+   * inspect() as `key`), and with DevTools on the open app tabs answer the page's "Live data"
+   * (mounted components, instance counts, action flashes, state). Dev server only: production
+   * builds contain none of it.
+   * @default true
+   */
+  graph?: boolean
 }
 
 export interface McpPluginOptions {

package/src/vite/plugin.ts

@@ -123,6 +123,22 @@
  *      `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),
@@ -162,6 +178,8 @@ import { pathToFileURL } from 'node:url'
 import { globalThisAlias } from './globalthis'
 import { attachMcp, mcpClientModule } from './mcp'
 import type { McpPluginOptions } from './mcp'
+import { GRAPH_CLIENT, createEngine, graphAvailable, graphClientModule, graphMiddleware, printGraphUrl, stampTail } from './graph'
+import type { LiveEngine } from './graph'
 
 export type { McpPluginOptions } from './mcp'
 
@@ -174,6 +192,8 @@ export interface DiagnosticsPluginOptions {
   mode?: DiagnosticsMode
   /** Strict (canonical-form, SYG5xx) runtime checks: sets globalThis.__SYGNAL_STRICT__. @default false */
   strict?: boolean
+  /** 7.0 timing audit (SYG257, info): sets globalThis.__SYGNAL_TIMING_AUDIT__. @default false */
+  timingAudit?: boolean
   /** Diagnostic codes to drop, e.g. ['SYG105'] */
   ignore?: string[]
 }
@@ -282,6 +302,17 @@ export interface SygnalPluginOptions {
    * @default false
    */
   mcp?: boolean | McpPluginOptions
+
+  /**
+   * PLAN-10 W-2 (D543): serve the live app graph page at `/__sygnal/graph` on the dev server (local
+   * requests only, as `/__sygnal/mcp`), built by sygnal-check (skipped silently when it isn't
+   * installed) and updated on every save; its URL is printed under Vite's. P-2 (D544): in dev the
+   * component functions get their static key (a non-enumerable `__sygnalKey`), and the app tabs
+   * answer the page's "Live data" (mounted components, instance counts, action flashes, state).
+   * Dev server only: never `vite build`, `vite preview` or Vitest. false: no route, no stamps.
+   * @default true
+   */
+  graph?: boolean
 }
 
 // Virtual modules (dev server only)
@@ -297,6 +328,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'
@@ -313,7 +346,7 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
   // Files whose `import ... from 'sygnal'` resolves to the run() wrapper
   const runtimeImporters = new Set<string>()
   // 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
@@ -321,11 +354,17 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
   const mcpOptions: McpPluginOptions = 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: Promise<LiveEngine | null> | null = 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: Set<string> | undefined
 
@@ -336,6 +375,10 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
       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: any = {
         // Ensure sygnal is bundled for SSR rather than externalized.
@@ -440,6 +483,7 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
         if (!isServe || isVitest) return null
         if (source === DEV_CLIENT) 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
         }
@@ -459,6 +503,7 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
     load(id: string) {
       if (id === DEV_CLIENT_ID) 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
       // pre-bundled copy of it can carry its own copy of the Sygnal core
@@ -476,14 +521,25 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
       if (mcpOn && server?.middlewares) {
         attachMcp(server, root, mcpOptions, sygnalVersion(root))
       }
-      if (options.check === false) return
+      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<LiveEngine | null>((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(this: any, code: string, id: string, opts?: { ssr?: boolean }) {
@@ -493,7 +549,10 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
         ? 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]: [any, string]) => {
         if (!tail) return r
@@ -587,6 +646,19 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
   }
 }
 
+// 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: Promise<LiveEngine | null>, id: string): Promise<string> | null {
+  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
@@ -721,7 +793,7 @@ function viteMajor(ctx: any, root: string): number {
   return Infinity
 }
 
-interface NormalizedDiagnostics { mode: DiagnosticsMode, strict: boolean, ignore: string[] }
+interface NormalizedDiagnostics { mode: DiagnosticsMode, strict: boolean, timingAudit: boolean, ignore: string[] }
 
 const MODES: DiagnosticsMode[] = ['off', 'collect', 'warn', 'error']
 
@@ -731,7 +803,7 @@ function normalizeDiagnostics(value: SygnalPluginOptions['diagnostics']): Normal
   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. */
@@ -899,16 +971,41 @@ function checkInclude(root: string, include: string[] | undefined, notice: (m: s
   return ['.']
 }
 
-/** Run sygnal-check now and after source changes; report to the terminal and the browser. */
-async function startChecker(server: any, root: string, opts: CheckPluginOptions,
-  defaults: { strict: boolean, ignore: string[] }, explicit: boolean) {
+/**
+ * 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: any, root: string, opts: CheckPluginOptions,
+  defaults: { strict: boolean, ignore: string[] }, explicit: boolean, checkOn: boolean, graphOn: boolean): Promise<LiveEngine | null> {
   const mod = await loadSygnalCheck(root)
   const logger = server?.config?.logger || console
   if (!mod || typeof mod.check !== 'function') {
-    if (explicit) logger.info('[sygnal] sygnal-check is not installed, so static checks are off (npm i -D sygnal-check)')
-    return
+    if (explicit && checkOn) logger.info('[sygnal] sygnal-check is not installed, so static checks are off (npm i -D sygnal-check)')
+    return null
   }
-  const notice = (m: string) => logger.info(m)
+  const setup = checkSetup(mod, root, opts, defaults, (m: string) => 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)
+  }
+  return engine
+}
+
+interface CheckSetup { include: string[]; checkOptions: any; configAware: boolean }
+
+/** What sygnal-check checks, with which options (see the `check` option). */
+function checkSetup(mod: any, root: string, opts: CheckPluginOptions,
+  defaults: { strict: boolean, ignore: string[] }, notice: (m: string) => void): CheckSetup {
   // 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.
@@ -940,6 +1037,17 @@ async function startChecker(server: any, root: string, opts: CheckPluginOptions,
       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: any, root: string, mod: any, setup: CheckSetup, opts: CheckPluginOptions, engine: LiveEngine | null) {
+  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
@@ -966,13 +1074,16 @@ async function startChecker(server: any, root: string, opts: CheckPluginOptions,
     } catch (_) {}
   }
 
-  const run = (initial = false) => {
+  const run = (initial = false, built?: any[]) => {
     let diags: any[]
-    try {
-      diags = mod.check(include, checkOptions)
-    } catch (err: any) {
-      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: any) {
+        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)
@@ -1011,7 +1122,12 @@ async function startChecker(server: any, root: string, opts: CheckPluginOptions,
     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 {
@@ -1023,6 +1139,7 @@ async function startChecker(server: any, root: string, opts: CheckPluginOptions,
     })
   } catch (_) {}
 
+  if (engine) return
   let timer: any
   const onChange = (file: string) => {
     if (file.split(/[\\/]/).includes('node_modules')) return
@@ -1041,6 +1158,8 @@ async function startChecker(server: any, root: string, opts: CheckPluginOptions,
 
 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