sygnal 6.5.0 → 6.6.0

package/src/vike/onRenderClient.ts

@@ -13,12 +13,16 @@
  * - Wrappers are outermost (context providers, state management)
  * - Layouts are inside wrappers (visual structure, navigation chrome)
  * - Page is innermost (route-specific content, swapped on navigation)
+ * Cumulative Layouts / Wrappers nest the root's outermost (G-803, see shell.ts). Navigating to a
+ * page with another shell (pages/admin/+Layout) keeps the shell components both pages share
+ * mounted, from the outside in, and adds or removes the rest.
  */
 
 // Import from the package entry so rollup externalizes it
 // @ts-ignore — resolved at runtime via package exports
 import { run } from 'sygnal'
 import { owned } from '../extra/owned'
+import { shellOf, uidPart, type ShellPart } from './shell'
 
 declare global {
   interface Window {
@@ -47,6 +51,8 @@ interface PageContext {
 
 /** Track the running Sygnal app for disposal on navigation */
 let currentApp: { sources: any; sinks: any; dispose: () => void } | null = null
+/** G-803: the running shell, outermost first (read by the wrapper's view); null: an app without one */
+let currentShell: ShellPart[] | null = null
 
 /**
  * Mutable references read by the wrapper's view function.
@@ -59,16 +65,6 @@ let currentRouteParams: any = {}
 let currentUrlPathname: string = ''
 let pageNavCounter: number = 0
 
-/**
- * PLAN-4 G-207: the uid() path part of a shell component or the Page: wrapper_0 → 'w0',
- * layout_1 → 'l1', page → 'p'. Given as the nested vnode's `id` prop, so the Page's uid is
- * 'u-w0-l0-p' however the shell nests it; onRenderHtml renders each one with the same root
- * (renderToString's `uid`), so server and client ids match. (Same helper in onRenderHtml.ts.)
- */
-function uidPart(key: string): string {
-  return key == 'page' ? 'p' : key[0] + key.slice(key.indexOf('_') + 1)
-}
-
 /**
  * PLAN-4.6 R4 (04 §3.11): the core instantiates a component from the vnode's `data.c`, a
  * component function, and reads its statics there (no options object). A shell component or a
@@ -143,11 +139,11 @@ function pageChildVNode(pageState: any, stateField: any = 'page'): any {
  *
  * Nesting order: Wrapper(s) > Layout(s) > Page
  *
- * The wrapper's view reads `currentPage` from the mutable closure, so
- * on client-side navigation only the Page sub-component changes while
- * the Layout and Wrapper stay mounted with their state preserved.
+ * The wrapper's view reads `currentPage` and `currentShell` from the mutable closure, so
+ * on client-side navigation only the Page sub-component (and the shell components the new page
+ * doesn't share) change while the Layout and Wrapper stay mounted with their state preserved.
  */
-function createLayoutWrapper(wrappers: any[], layouts: any[], Page: any): any {
+function createLayoutWrapper(Page: any): any {
   currentPage = Page
   currentPageName = Page.componentName || Page.name || 'VikePageComponent'
 
@@ -158,9 +154,6 @@ function createLayoutWrapper(wrappers: any[], layouts: any[], Page: any): any {
   // one (and the Page) gets a { get, set } lens onto its own ROOT slice: an outer component's
   // reducer replacing its state can't wipe the inner slices (R2-2), and no view sees another
   // component's slice.
-  const keys = shellKeys(wrappers, layouts)
-  const shell = [...wrappers, ...layouts].map((comp: any, i: number) => ({ comp, key: keys[i] }))
-
   // The latest root state. Only the outermost lens gets the root itself; the nested lenses get
   // their parent shell component's state. In both directions the outermost lens runs first and
   // synchronously (state: root -> outer get -> inner get; a reducer: outer get, inner get, inner
@@ -180,10 +173,13 @@ function createLayoutWrapper(wrappers: any[], layouts: any[], Page: any): any {
       return outermost ? root : { ...state }
     },
   })
-  const lenses = keys.map((key, i) => rootLens(key, i === 0, true))
+  // one lens per key and place (outermost or not), the same object on every render
+  const lenses: Record<string, any> = {}
+  const lensOf = (key: string, outermost: boolean) => (lenses[key + outermost] ||= rootLens(key, outermost, true))
   const pageLens = rootLens('page', false, false)
 
   function LayoutWrapperView({ state }: any) {
+    const shell = currentShell || []
     if (shell.length === 0) {
       // No wrappers or layouts — render Page directly
       return pageChildVNode(state.page)
@@ -193,14 +189,14 @@ function createLayoutWrapper(wrappers: any[], layouts: any[], Page: any): any {
     let inner: any = componentVNode(
       shell[lastIdx].comp,
       shell[lastIdx].key,
-      lenses[lastIdx],
+      lensOf(shell[lastIdx].key, lastIdx === 0),
       [pageChildVNode(state.page, pageLens)],
       state[shell[lastIdx].key]
     )
 
     // Wrap with outer shell components
     for (let i = lastIdx - 1; i >= 0; i--) {
-      inner = componentVNode(shell[i].comp, shell[i].key, lenses[i], [inner], state[shell[i].key])
+      inner = componentVNode(shell[i].comp, shell[i].key, lensOf(shell[i].key, i === 0), [inner], state[shell[i].key])
     }
 
     // Wrap in a plain div so the view returns a regular DOM vnode.
@@ -223,6 +219,7 @@ function createLayoutWrapper(wrappers: any[], layouts: any[], Page: any): any {
   // The wrapper's initial state: a sibling slice for each shell component and the Page.
   // Must match onRenderHtml's serialized state.
   const initialState: any = {}
+  const shell = currentShell || []
   shell.forEach(({ comp, key }: any) => { initialState[key] = { ...(comp.initialState || {}) } })
   initialState.page = Page.initialState || {}
   // G-275: owned (built from the hydrated state and pageContext.data: never frozen in dev)
@@ -250,33 +247,18 @@ function createLayoutWrapper(wrappers: any[], layouts: any[], Page: any): any {
   return LayoutWrapperView
 }
 
-/** State keys of the shell components, outermost first: wrapper_0, ..., layout_0, ... */
-function shellKeys(wrappers: any[], layouts: any[]): string[] {
-  return [
-    ...wrappers.map((_: any, i: number) => 'wrapper_' + i),
-    ...layouts.map((_: any, i: number) => 'layout_' + i),
-  ]
-}
-
-/**
- * Normalize a cumulative config value into an array of functions.
- */
-function toComponentArray(val: any): any[] {
-  if (!val) return []
-  return (Array.isArray(val) ? val : [val]).filter((c: any) => typeof c === 'function')
-}
-
 export function onRenderClient(pageContext: PageContext) {
   const { Page, config } = pageContext
   const data = pageContext.data || {}
 
-  const wrappers = toComponentArray(config.Wrapper)
-  const layouts = toComponentArray(config.Layout)
-  const hasShell = wrappers.length > 0 || layouts.length > 0
+  // The shell, outermost first (G-803: Vike lists cumulative configs closest first); the state
+  // slices of its components and the Page's are siblings at the root (D50)
+  const parts = shellOf(config)
+  const hasShell = parts.length > 0
+  const shell = parts.map(p => p.key)
 
-  // The shell is wrappers (outermost) + layouts; their state slices and the Page's are
-  // siblings at the root (D50).
-  const shell = shellKeys(wrappers, layouts)
+  // a shell page after a page without one (or the reverse, below): a new app
+  if (hasShell && currentApp && !currentShell) { currentApp.dispose(); currentApp = null }
 
   // PLAN-3 5-5 (H-7): seed the caches of the fetch drivers (makeFetchDriver({ cache: queryCache() })
   // exposes it as driver.cache) before the page renders, so its resources start at 'success'
@@ -304,8 +286,22 @@ export function onRenderClient(pageContext: PageContext) {
       pageNavCounter++
 
       const newPageState = { ...(Page.initialState || {}), ...data }
-      // replace the page slice, keeping every shell slice (G-106, D50)
-      const swapPage = (state: any) => ({ ...state, page: newPageState })
+      // replace the page slice, keeping every shell slice (G-106, D50). G-803: a page with another
+      // shell keeps the slices of the components it shares at the same place (key) and starts the
+      // others from their initialState
+      const old = currentShell!
+      const same = parts.length === old.length && parts.every((p, i) => p.comp === old[i].comp)
+      let swapPage = (state: any) => ({ ...state, page: newPageState })
+      if (!same) {
+        currentShell = parts
+        swapPage = (state: any) => {
+          const next: any = { page: newPageState }
+          for (const { comp, key } of parts) {
+            next[key] = old.some(o => o.key === key && o.comp === comp) ? state[key] : { ...(comp.initialState || {}) }
+          }
+          return next
+        }
+      }
       // (PLAN-4.6 core: through the runtime API, 04 §3.11)
       const rt = (currentApp as any).__runtime
       rt?.setState('root', swapPage)
@@ -322,7 +318,7 @@ export function onRenderClient(pageContext: PageContext) {
       if (initialState && initialState[shell[shell.length - 1]] !== undefined) {
         // Hydrated shell state: sibling slices (D50), or the 5.4.0 shape with the Page state
         // under the innermost shell slice (R2-9) — distribute the slices to each component
-        const allShellComps = [...wrappers, ...layouts]
+        const allShellComps = parts.map(p => p.comp)
         let pageState = initialState.page
         shell.forEach((key: string, i: number) => {
           let slice = initialState[key]
@@ -348,7 +344,8 @@ export function onRenderClient(pageContext: PageContext) {
         urlPathname: () => currentUrlPathname,
       }
 
-      const Component = createLayoutWrapper(wrappers, layouts, Page)
+      currentShell = parts
+      const Component = createLayoutWrapper(Page)
 
       try {
         // 3-B2: `__vike` marks the shell's components (Page, Layouts, Wrappers: sub-components of
@@ -372,6 +369,7 @@ export function onRenderClient(pageContext: PageContext) {
       currentApp.dispose()
       currentApp = null
     }
+    currentShell = null
 
     let initialState: any
     // 3-B2: the server's state is here when the page hydrates its HTML

package/src/vike/onRenderHtml.ts

@@ -16,6 +16,7 @@
 
 // @ts-ignore — resolved at runtime via package exports
 import { renderToString, renderHead, queryCache } from 'sygnal'
+import { shellOf, uidPart } from './shell'
 
 interface PageContext {
   Page: any
@@ -54,16 +55,6 @@ function esc(str: string): string {
     .replace(/"/g, '"')
 }
 
-/**
- * PLAN-4 G-207: the uid() path part of a shell component or the Page (wrapper_0 → 'w0',
- * layout_1 → 'l1', page → 'p'), as onRenderClient gives each nested vnode in its `id` prop. Each
- * one renders here as its own root, so its root is 'u' plus the parts of the shell around it and
- * its own: the same uids as the client's nested instances.
- */
-function uidPart(key: string): string {
-  return key == 'page' ? 'p' : key[0] + key.slice(key.indexOf('_') + 1)
-}
-
 export function onRenderHtml(pageContext: PageContext) {
   const { Page, config } = pageContext
   const data = pageContext.data || {}
@@ -128,22 +119,10 @@ export function onRenderHtml(pageContext: PageContext) {
   // PLAN-3 5-5 (H-7): the seeded cache the components' resources render from
   const cache = pageContext.queryCache ? queryCache({ initial: pageContext.queryCache }) : undefined
 
-  // Determine if Wrapper(s) and/or Layout(s) are present — this affects hydration state shape
-  const wrapperArray = config.Wrapper
-    ? (Array.isArray(config.Wrapper) ? config.Wrapper : [config.Wrapper])
-        .filter((W: any) => typeof W === 'function')
-    : []
-  const layoutArray = config.Layout
-    ? (Array.isArray(config.Layout) ? config.Layout : [config.Layout])
-        .filter((L: any) => typeof L === 'function')
-    : []
-  const hasShell = wrapperArray.length > 0 || layoutArray.length > 0
-  // Combined shell: wrappers (outermost) + layouts (innermost around Page)
-  // Must match the order used in onRenderClient's createLayoutWrapper.
-  const shell = [
-    ...wrapperArray.map((w: any, i: number) => ({ comp: w, key: 'wrapper_' + i })),
-    ...layoutArray.map((l: any, i: number) => ({ comp: l, key: 'layout_' + i })),
-  ]
+  // Wrapper(s) and/or Layout(s), outermost first (G-803: Vike lists them closest first; shellOf
+  // reverses them, the same order as onRenderClient's): they decide the hydration state's shape
+  const shell = shellOf(config)
+  const hasShell = shell.length > 0
   // G-207: with a shell, the client nests each shell component and the Page in the one outside it
   // with an `id` prop (onRenderClient), so their uid roots are 'u-w0', 'u-w0-l0', 'u-w0-l0-p'
   const uidRoot = (i: number) => ['u', ...shell.slice(0, i + 1).map(s => uidPart(s.key))].join('-')

package/src/vike/shell.ts

@@ -0,0 +1,33 @@
+/**
+ * G-803: the shell components of a page (its Wrappers and Layouts), outermost first, with their
+ * state keys. Shared by onRenderHtml and onRenderClient so the server and the client nest them
+ * the same way.
+ *
+ * Vike's cumulative configs (`Layout` and `Wrapper` are, see +config.ts) list the values closest
+ * to the page first: pages/admin/+Layout before pages/+Layout (vike's resolveVikeConfigInternal:
+ * sortAfterInheritanceOrder puts the longer inheritance root first). So the root's come last, and
+ * the shell reverses each list: every Wrapper outside every Layout (as vike-react), and within each
+ * the root's outermost. Keys count from the outside in (wrapper_0, ..., layout_0, ...), so a root
+ * Layout keeps `layout_0` on every page, nested or not.
+ */
+export interface ShellPart { comp: any; key: string }
+
+const comps = (val: any): any[] =>
+  (val ? (Array.isArray(val) ? val : [val]) : []).filter((c: any) => typeof c === 'function')
+
+export function shellOf(config: { Wrapper?: any; Layout?: any }): ShellPart[] {
+  return [
+    ...comps(config.Wrapper).reverse().map((comp, i) => ({ comp, key: 'wrapper_' + i })),
+    ...comps(config.Layout).reverse().map((comp, i) => ({ comp, key: 'layout_' + i })),
+  ]
+}
+
+/**
+ * PLAN-4 G-207: the uid() path part of a shell component or the Page: wrapper_0 → 'w0',
+ * layout_1 → 'l1', page → 'p'. onRenderClient gives it as the nested vnode's `id` prop, so the
+ * Page's uid is 'u-w0-l0-p' however the shell nests it; onRenderHtml renders each one with the
+ * same root (renderToString's `uid`), so server and client ids match.
+ */
+export function uidPart(key: string): string {
+  return key == 'page' ? 'p' : key[0] + key.slice(key.indexOf('_') + 1)
+}

package/src/vite/graph.ts

@@ -0,0 +1,247 @@
+/**
+ * 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)
+  }
+}
+
+/** Adds the page's URL under Vite's own when the dev server prints them. */
+export function printGraphUrl(server: any) {
+  const print = server?.printUrls
+  if (typeof print !== 'function') return
+  server.printUrls = function (this: any, ...args: any[]) {
+    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
+  }
+}

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

@@ -136,6 +136,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 {