sygnal 5.4.0 → 6.1.0

package/src/extra/copyAsTest.ts

@@ -0,0 +1,286 @@
+/**
+ * PLAN-4 3-E (GS-10): "Copy as test". Turns a recorded session (./devtoolsActions getSession())
+ * into a Vitest + renderComponent test that replays it:
+ *
+ *   renderComponent(C, { initialState?, drivers? })   the session's initial state (left out when
+ *                                                      it is the component's own initialState)
+ *   await t.ready()
+ *   t.simulateAction(type, data)     each action caused by 'intent' | 'simulateAction' | 'behavior' | 'agent'
+ *   await t.respond(sink, body, OK)  a reply action from a makeFetchDriver source (renderComponent's
+ *   await t.fail(sink, status, ...)  HTTP fake answers the request the replayed actions send again)
+ *   await t.settle()
+ *   expect(t.state).toEqual(final)
+ *
+ * 'next' and 'built-in' actions are consequences (the replay produces them again), never replayed;
+ * nor is an intent action whose data is the component's own state (an intent over STATE.stream).
+ * A t.respond / t.fail that follows simulateAction calls waits for the request they send (G-218).
+ * Data is written as JS literals: JSON values, Date, Map, Set, NaN / Infinity / -0, bigint. A DOM
+ * event or element becomes a stub ({ type, key, target: { dataset, value, checked, id } }), with a
+ * comment. Anything else (functions, class instances, cycles) is left out with a comment.
+ *
+ * The final-state assertion is written only when the replay is complete: every state-changing
+ * action could be replayed with its data, no descendant instance changed the state on its own
+ * (a child's intent: copy the test from that instance instead), the session wasn't truncated,
+ * and the final state is JSON-safe. Otherwise a comment says why. A test written with the
+ * assertion passes unchanged (for drivers the session's app had, pass `drivers`).
+ */
+import type {SessionRecording, SessionAction} from './devtoolsActions'
+import {isElement, isEvent, deepEqual} from './devtoolsActions'
+
+export interface CopyAsTestOptions {
+  /** the import line(s) for the component, e.g. "import App from './App.jsx'" (default: `import <Name> from './<Name>.js'`) */
+  componentImport?: string
+  /** the identifier the component has in the test (default: the recorded component name) */
+  componentName?: string
+  /** more import lines (drivers, helpers) */
+  imports?: string[]
+  /** drivers for renderComponent, as source code by sink name: { DND: 'mockDragDriver().driver' } */
+  drivers?: Record<string, string>
+  /** more renderComponent options, as source code: "strict: true" */
+  renderOptions?: string
+  /** the test's name (default: '<Component> session (copied from sygnal/devtools)') */
+  testName?: string
+  /** adds a `// @vitest-environment <env>` first line (e.g. 'jsdom') */
+  environment?: string
+}
+
+export interface CopyAsTestResult {
+  /** the test file */
+  code: string
+  /** true when the test asserts the final state */
+  complete: boolean
+  /** what was left out, and why (also comments in the code) */
+  warnings: string[]
+  /** actions written as simulateAction / respond / fail */
+  replayed: number
+}
+
+const REPLAY = new Set(['intent', 'simulateAction', 'behavior', 'agent'])
+const IDENT = /^[A-Za-z_$][\w$]*$/
+
+class Unserializable extends Error {}
+
+/** a single-quoted JS string literal */
+const str = (s: string) => `'${JSON.stringify(s).slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'")}'`
+
+interface Lit { code: string; stubbed: boolean }
+
+/** `v` as a JS literal. mode 'data' turns DOM events / elements into stubs; 'state' refuses them. */
+export function literal(v: any, mode: 'data' | 'state' = 'data', indent = ''): Lit {
+  const flag = {stubbed: false}
+  const code = lit(v, mode, indent, new Set(), flag)
+  return {code, stubbed: flag.stubbed}
+}
+
+function elementStub(el: any): any {
+  const out: any = {}
+  const ds = el.dataset && typeof el.dataset == 'object' ? {...el.dataset} : {}
+  if (Object.keys(ds).length) out.dataset = ds
+  if (el.id) out.id = el.id
+  const tag = String(el.tagName).toUpperCase()
+  if (/^(INPUT|SELECT|TEXTAREA)$/.test(tag) && typeof el.value == 'string') out.value = el.value
+  if (tag == 'INPUT' && /^(checkbox|radio)$/i.test(el.type || '')) out.checked = !!el.checked
+  return out
+}
+
+function eventStub(e: any): any {
+  const out: any = {type: e.type}
+  if (typeof e.key == 'string') out.key = e.key
+  if (isElement(e.target)) {
+    const t = elementStub(e.target)
+    if (Object.keys(t).length) out.target = t
+  }
+  return out
+}
+
+function lit(v: any, mode: 'data' | 'state', ind: string, seen: Set<any>, flag: {stubbed: boolean}): string {
+  if (v === null) return 'null'
+  switch (typeof v) {
+    case 'undefined': return 'undefined'
+    case 'boolean': return String(v)
+    case 'string': return str(v)
+    case 'number': return Object.is(v, -0) ? '-0' : String(v)
+    case 'bigint': return `${v}n`
+    case 'function': throw new Unserializable(`a function (${v.name || 'anonymous'})`)
+    case 'symbol': throw new Unserializable(`a symbol (${String(v)})`)
+  }
+  if (seen.has(v)) throw new Unserializable('a circular reference')
+  if (isEvent(v) || isElement(v)) {
+    if (mode == 'state') throw new Unserializable(isEvent(v) ? `a DOM ${v.type} event` : 'a DOM element')
+    flag.stubbed = true
+    return lit(isEvent(v) ? eventStub(v) : elementStub(v), mode, ind, seen, flag)
+  }
+  seen.add(v)
+  try {
+    const inner = ind + '  '
+    const list = (items: string[], open: string, close: string) => {
+      if (!items.length) return open + close
+      const one = open + (open == '{' ? ' ' : '') + items.join(', ') + (open == '{' ? ' ' : '') + close
+      if (one.length + ind.length <= 100 && !one.includes('\n')) return one
+      return open + '\n' + items.map(s => inner + s).join(',\n') + ',\n' + ind + close
+    }
+    if (Array.isArray(v)) return list(Array.from(v, x => lit(x, mode, inner, seen, flag)), '[', ']')
+    if (v instanceof Date) return `new Date(${str(isNaN(+v) ? 'Invalid Date' : v.toISOString())})`
+    if (v instanceof Map) return `new Map(${list([...v].map(([k, x]) => list([lit(k, mode, inner + '  ', seen, flag), lit(x, mode, inner + '  ', seen, flag)], '[', ']')), '[', ']')})`
+    if (v instanceof Set) return `new Set(${list([...v].map(x => lit(x, mode, inner, seen, flag)), '[', ']')})`
+    const proto = Object.getPrototypeOf(v)
+    // G-265: a vnode of the JSX pragma (its own constructor, flagged $p) is a plain object
+    if (proto !== Object.prototype && proto !== null && !v.$p) throw new Unserializable(`a ${(v.constructor && v.constructor.name) || 'class instance'}`)
+    const items: string[] = []
+    for (const k of Object.keys(v)) {
+      if (v[k] === undefined) continue
+      items.push(`${IDENT.test(k) ? k : str(k)}: ${lit(v[k], mode, inner, seen, flag)}`)
+    }
+    return list(items, '{', '}')
+  } finally {
+    seen.delete(v)
+  }
+}
+
+const q = str
+const tryLit = (v: any, mode: 'data' | 'state', ind: string): Lit | {error: string} => {
+  try { return literal(v, mode, ind) } catch (e: any) {
+    if (e instanceof Unserializable) return {error: e.message}
+    throw e
+  }
+}
+
+/** an error reply from makeFetchDriver: { error, request, status?, body? } for the request's `error` action */
+const isErrorReply = (a: SessionAction) =>
+  a.data && typeof a.data == 'object' && 'error' in a.data && a.data.request && typeof a.data.request == 'object' && a.data.request.error === a.type
+
+/** The test for a recorded session (see the module comment), with what it left out. */
+export function sessionToTest(rec: SessionRecording, options: CopyAsTestOptions = {}): CopyAsTestResult {
+  const name = options.componentName || (IDENT.test(rec.component) ? rec.component : 'Component')
+  const warnings: string[] = []
+  const incomplete: string[] = []
+  const body: string[] = []
+  const I = '    '
+  const drivers = options.drivers || {}
+  let replayed = 0
+
+  if (rec.truncated) incomplete.push('the session lost its oldest actions (clear the log, then record a shorter session)')
+
+  // render options
+  const opts: string[] = []
+  if (rec.initialState !== undefined && !deepEqual(rec.initialState, rec.definitionInitialState)) {
+    const l = tryLit(rec.initialState, 'state', I)
+    if ('error' in l) {
+      warnings.push(`the initial state holds ${l.error}: rendering with the component's own initialState`)
+      incomplete.push('the initial state could not be written')
+    } else opts.push(`initialState: ${l.code}`)
+  }
+  const fakeable = new Set(rec.fakeable)
+  const driverNames = [...new Set([...rec.drivers.filter(n => !fakeable.has(n)), ...Object.keys(drivers)])]
+  const given = driverNames.filter(n => drivers[n] !== undefined)
+  const missing = driverNames.filter(n => drivers[n] === undefined)
+  if (given.length) opts.push(`drivers: { ${given.map(n => `${IDENT.test(n) ? n : q(n)}: ${drivers[n]}`).join(', ')} }`)
+  if (missing.length) warnings.push(`the app had ${missing.length == 1 ? 'a driver' : 'drivers'} for ${missing.join(', ')}: pass ${missing.length == 1 ? 'it' : 'them'} with copyAsTest(..., { drivers: { ${missing[0]}: '...' } }) if the component reads ${missing.length == 1 ? 'it' : 'them'}`)
+  if (options.renderOptions) opts.push(options.renderOptions)
+
+  const names = rec.actionNames && new Set(rec.actionNames)
+  // (G-218: t.respond / t.fail right after queued simulateAction calls wait for the request
+  // those calls send, so no settle() is needed before them)
+  const answer = (line: string) => body.push(line)
+  for (const a of rec.actions) {
+    const changes = a.sinks.includes('STATE') || a.sinks.includes('state')
+    if (REPLAY.has(a.cause)) {
+      // an intent over the component's own STATE stream: the replay produces it again
+      if (a.echo) continue
+      // an intent action with no model entry does nothing (renderComponent can't send it)
+      if (names && !names.has(a.type) && a.cause != 'behavior') continue
+      replayed++
+      if (a.data === undefined) { body.push(`${I}t.simulateAction(${q(a.type)})`); continue }
+      const l = tryLit(a.data, 'data', I)
+      if ('error' in l) {
+        body.push(`${I}t.simulateAction(${q(a.type)}) // data left out: it held ${l.error}`)
+        if (changes) incomplete.push(`${a.type}'s data could not be written (${l.error})`)
+        continue
+      }
+      if (l.stubbed) body.push(`${I}// ${a.type}: DOM event/element data as a stub (type, key, target dataset/value/checked/id)`)
+      body.push(`${I}t.simulateAction(${q(a.type)}, ${l.code})`)
+    } else if (a.cause == 'reply') {
+      const sink = a.replySink
+      if (!sink || a.replyKind != 'fetch' || drivers[sink] !== undefined) {
+        body.push(`${I}// reply ${a.type}${sink ? ` from ${sink}` : ''}: not replayed (renderComponent fakes makeFetchDriver sources only)`)
+        if (changes) incomplete.push(`the ${a.type} reply could not be replayed`)
+        continue
+      }
+      if (isErrorReply(a)) {
+        const err = a.data.error, status = a.data.status ?? (err && err.status), errBody = a.data.body ?? (err && err.body)
+        if (typeof status == 'number') {
+          if (errBody === undefined) answer(`${I}await t.fail(${q(sink)}, ${status}, ${q(a.type)})`)
+          else {
+            const l = tryLit(errBody, 'state', I)
+            if ('error' in l) { answer(`${I}await t.fail(${q(sink)}, ${status}, ${q(a.type)}) // body left out: it held ${l.error}`); if (changes) incomplete.push(`the ${a.type} error body could not be written`) }
+            else answer(`${I}await t.fail(${q(sink)}, ${status}, { request: (r) => r.error === ${q(a.type)}, body: ${l.code} })`)
+          }
+        } else if (a.data.issues) {
+          body.push(`${I}// reply ${a.type}: a validation failure, not replayed`)
+          if (changes) incomplete.push(`the ${a.type} validation failure could not be replayed`)
+          continue
+        } else {
+          answer(`${I}await t.fail(${q(sink)}, new Error(${str(String(err && err.message || err))}), ${q(a.type)})`)
+        }
+        replayed++
+        continue
+      }
+      const l = tryLit(a.data, 'state', I)
+      if ('error' in l) {
+        body.push(`${I}// reply ${a.type} from ${sink}: its data held ${l.error}, not replayed`)
+        if (changes) incomplete.push(`the ${a.type} reply's data could not be written`)
+        continue
+      }
+      answer(`${I}await t.respond(${q(sink)}, ${l.code}, ${q(a.type)})`)
+      replayed++
+    } else if (a.type == 'RESOURCE' && a.data && (a.data.status == 'success' || a.data.status == 'error')) {
+      body.push(`${I}// RESOURCE ${a.data.name}: ${a.data.status}, not replayed (answer it with t.respond / t.fail)`)
+      if (changes) incomplete.push(`resource '${a.data.name}' was answered`)
+    }
+    // 'next' and 'built-in': consequences, produced again by the replay
+  }
+
+  if (rec.foreign.length) {
+    const list = rec.foreign.slice(0, 5).map(f => `${f.component}#${f.instance} ${f.type}`).join(', ') + (rec.foreign.length > 5 ? ', ...' : '')
+    incomplete.push(`child components changed the state through their own actions (${list}): copy the test from that component instance instead`)
+  }
+
+  let assertion: string[]
+  if (!incomplete.length) {
+    const l = tryLit(rec.finalState, 'state', I)
+    if ('error' in l) incomplete.push(`the final state holds ${l.error}`)
+    else assertion = [`${I}expect(t.state).toEqual(${l.code})`]
+  }
+  if (incomplete.length) {
+    warnings.push(...incomplete.map(s => 'no final-state assertion: ' + s))
+    assertion = [`${I}// No final-state assertion: ${incomplete.join('; ')}`]
+  }
+
+  const head: string[] = []
+  if (options.environment) head.push(`// @vitest-environment ${options.environment}`)
+  head.push(`// Copied from a sygnal/devtools session of ${rec.component} (${rec.actions.length} recorded actions, ${replayed} replayed)`)
+  for (const w of warnings) head.push(`// NOTE: ${w}`)
+  head.push(`import { it, expect } from 'vitest'`, `import { renderComponent } from 'sygnal'`)
+  head.push(...(options.imports || []))
+  head.push(options.componentImport || `import ${name} from './${name}.js'`)
+
+  const testName = options.testName || `${rec.component} session (copied from sygnal/devtools)`
+  const render = opts.length ? `renderComponent(${name}, {\n${opts.map(o => `${I}${o},`).join('\n')}\n  })` : `renderComponent(${name})`
+  const code = [
+    ...head,
+    '',
+    `it(${q(testName)}, async () => {`,
+    `  const t = ${render}`,
+    '  try {',
+    `${I}await t.ready()`,
+    ...body,
+    `${I}await t.settle()`,
+    ...assertion!,
+    '  } finally {',
+    `${I}t.dispose()`,
+    '  }',
+    '})',
+    '',
+  ].join('\n')
+  return {code, complete: !incomplete.length, warnings, replayed}
+}

package/src/extra/devMcp.ts

@@ -0,0 +1,386 @@
+/**
+ * PLAN-6 E-1: the page side of the dev MCP endpoint (`sygnal({ mcp: true })` in sygnal/vite).
+ * Dev only: it is part of the 'sygnal/devtools' entry, and sygnal/vite's 'virtual:sygnal/mcp'
+ * module (served by the dev server, never in a build) calls installMcpBridge(import.meta.hot).
+ *
+ * The protocol, over Vite's HMR channel (custom events):
+ *   page → server  'sygnal:mcp:hello'     { url, title, focused, apps, update? }   on load, focus,
+ *                                         when shown, and (update: true) when the apps change
+ *   server → page  'sygnal:mcp:request'   { id, tool, args }
+ *   page → server  'sygnal:mcp:response'  { id, ok: true, result } | { id, ok: false, error }
+ *                                         | { id, waiting: true }   (a confirm dialog is open:
+ *                                           the server waits longer)
+ *
+ * The tools read the page's apps through their runtime APIs, the DevTools bridge (diagnostics,
+ * action log, copy as test), the diagnostics core's inspect(), and the A-1 agent layer
+ * (agentTools, passed in by the virtual module from the app's own 'sygnal', so there is one core).
+ *
+ * G-638: every run() of the page is served. The bridge registers a dev hook layer
+ * (`__SYGNAL_DIAGNOSTICS__.layers`, read by each app at its start: no core bytes), so it sees each
+ * app's runtime API in start order; an HMR successor (disposed and started in the same tick)
+ * keeps its predecessor's place. `app` (an index, or the root component's name) picks one; the
+ * default is the first. An app started before the bridge was installed is still found through
+ * window.__SYGNAL_DEVTOOLS_APP__. The hello carries the apps ({ index, component }) and is sent
+ * again (`update: true`, not a focus) when they change.
+ */
+import {getDevTools} from './devtools'
+import {getActions, getSession, preview} from './devtoolsActions'
+import {sessionToTest} from './copyAsTest'
+import {addLayer} from './devtoolsNext'
+
+export const MCP_HELLO = 'sygnal:mcp:hello'
+export const MCP_REQUEST = 'sygnal:mcp:request'
+export const MCP_RESPONSE = 'sygnal:mcp:response'
+
+export interface McpBridgeOptions {
+  /** agentTools from 'sygnal' (the app's core) */
+  agentTools?: (target: any, options?: any) => any
+  /**
+   * Consequential agent tools (A-1 `consequential: true`): 'page' asks in the page with
+   * window.confirm() (default), true runs them, false declines them.
+   */
+  confirm?: boolean | 'page'
+  /** the app to serve, alone (default: every run() of the page) */
+  app?: () => any
+}
+
+interface Hot {
+  on(event: string, cb: (data: any) => void): void
+  send(event: string, data?: any): void
+}
+
+class ToolError extends Error {}
+
+const g: any = globalThis
+
+/** JSON-safe copy (functions, DOM nodes, cycles, Maps, Sets described) */
+const plain = (v: any) => (v === undefined ? null : preview(v))
+
+// ---------------------------------------------------------------- the page's apps (G-638)
+
+/** runtime APIs of the apps started since the bridge was installed, in start order */
+const started: any[] = []
+let gone = -1
+let tracking = false
+const listeners = new Set<() => void>()
+const changed = () => listeners.forEach(f => { try { f() } catch (_) {} })
+const alive = (api: any) => {
+  try { const r = api?.root; return !!r && !r.disposed } catch (_) { return false }
+}
+
+/** the dev hook layer: each app's runtime API at its start; its root's dispose ends it */
+function appLayer(api: any) {
+  // an HMR swap (or any app started in the tick its predecessor ended) takes the same place
+  if (gone >= 0 && gone < started.length && !alive(started[gone])) started[gone] = api
+  else started.push(api)
+  gone = -1
+  changed()
+  return {
+    onDispose(iv: any) {
+      if (!iv?.isRoot) return
+      const i = started.indexOf(api)
+      if (i < 0) return
+      gone = i
+      queueMicrotask(() => {
+        if (gone === i) gone = -1
+        const j = started.indexOf(api)
+        if (j >= 0) started.splice(j, 1)
+        changed()
+      })
+    },
+  }
+}
+
+function trackApps() {
+  if (tracking) return
+  tracking = true
+  addLayer(appLayer)
+}
+
+interface AppRef { api: any; target: any }
+
+/** the live apps of the page, the first app first */
+export function pageApps(o: McpBridgeOptions = {}): AppRef[] {
+  if (o.app) {
+    const app = o.app()
+    return app?.__runtime && alive(app.__runtime) ? [{api: app.__runtime, target: app}] : []
+  }
+  // each runtime.api() is a new object: an app is known by its root instance (ids are page-unique)
+  const first = g.window?.__SYGNAL_DEVTOOLS_APP__
+  const firstRoot = first?.__runtime && alive(first.__runtime) ? first.__runtime.root.id : undefined
+  const ref = (api: any): AppRef => ({api, target: firstRoot !== undefined && api.root.id === firstRoot ? first : api})
+  const out = started.filter(alive).map(ref)
+  if (firstRoot !== undefined && !out.some(a => a.api.root.id === firstRoot)) out.unshift({api: first.__runtime, target: first})
+  return out
+}
+
+const appSummary = (a: AppRef, index: number) => {
+  let component = '?'
+  try { component = a.api.root.name } catch (_) {}
+  return {index, component}
+}
+
+const appsLine = (apps: AppRef[]) => apps.map((a, i) => `${i} ${appSummary(a, i).component}`).join(', ')
+
+/** the app `want` names (an index, or the root component's name); the first when omitted */
+function pickApp(o: McpBridgeOptions, want: any): AppRef {
+  const apps = pageApps(o)
+  if (!apps.length) throw new ToolError('no Sygnal app is running on this page (run() has not been called, or the app was disposed)')
+  if (want === undefined || want === null || want === '') return apps[0]
+  if (typeof want == 'number' || /^\d+$/.test(String(want))) {
+    const a = apps[Number(want)]
+    if (!a) throw new ToolError(`no app ${want}; apps: ${appsLine(apps)}`)
+    return a
+  }
+  const named = apps.filter(a => { try { return a.api.root.name === want } catch (_) { return false } })
+  if (!named.length) throw new ToolError(`no app ${JSON.stringify(want)}; apps: ${appsLine(apps)}`)
+  if (named.length > 1) throw new ToolError(`${named.length} apps have the root ${want}; pass an index (apps: ${appsLine(apps)})`)
+  return named[0]
+}
+
+/**
+ * The runtime API to use: `app`'s; without `app`, the first app, unless `component` (a name or
+ * an instance id; ids are unique on the page) is only in another one
+ */
+function runtimeFor(o: McpBridgeOptions, args: any): any {
+  const c = args.component
+  const first = pickApp(o, args.app).api
+  if ((args.app !== undefined && args.app !== null) || c === undefined || c === null || c === '' || find(first, c).length) return first
+  const owners = pageApps(o).filter(a => { try { return find(a.api, c).length > 0 } catch (_) { return false } })
+  return owners.length == 1 ? owners[0].api : first
+}
+
+/** every instance of the app, root first (depth-first) */
+function allInstances(rt: any): any[] {
+  const out: any[] = []
+  const walk = (iv: any) => {
+    if (!iv) return
+    out.push(iv)
+    for (const c of iv.children?.() || []) walk(c)
+  }
+  walk(rt.root)
+  return out
+}
+
+/** The instances `component` names: a component name, or an instance id (number or digits); root when omitted */
+function find(rt: any, component: any): any[] {
+  if (component === undefined || component === null || component === '') return rt.root ? [rt.root] : []
+  const all = allInstances(rt)
+  if (typeof component == 'number' || /^\d+$/.test(String(component))) {
+    const iv = all.find(i => String(i.id) === String(component))
+    return iv ? [iv] : []
+  }
+  return all.filter(i => i.name === component)
+}
+
+function names(rt: any): string {
+  return [...new Set(allInstances(rt).map(i => i.name))].join(', ')
+}
+
+function one(rt: any, component: any, verb: string): any {
+  const found = find(rt, component)
+  if (!found.length) throw new ToolError(`no component ${JSON.stringify(component)} is shown now; components: ${names(rt) || 'none'}`)
+  if (found.length > 1) {
+    throw new ToolError(`${found.length} instances of ${component} are shown (ids ${found.map(i => i.id).join(', ')}); pass one id as component to ${verb} one`)
+  }
+  return found[0]
+}
+
+function at(value: any, path: any): any {
+  if (path === undefined || path === null || path === '') return value
+  const parts = Array.isArray(path) ? path.map(String) : String(path).split('.').filter(Boolean)
+  let v = value
+  for (const p of parts) {
+    if (v === null || v === undefined || typeof v != 'object') throw new ToolError(`state has no ${parts.join('.')} (stopped at ${p})`)
+    v = v instanceof Map ? v.get(p) : v[p]
+  }
+  return v
+}
+
+const stateOf = (iv: any) => ({component: iv.name, id: iv.id, ...(iv.kind == 'item' ? {item: true} : {}), state: plain(iv.state)})
+
+function actionNames(iv: any): string[] {
+  const def = iv.def || {}
+  const out = def.handlers instanceof Map ? [...def.handlers.keys()] : []
+  const b = def.behaviorActions
+  if (b && typeof b == 'object') out.push(...(b instanceof Map ? [...b.keys()] : Object.keys(b)))
+  return [...new Set(out.map(String))]
+}
+
+const serializeAction = (a: any) => ({
+  seq: a.seq, type: a.type, data: preview(a.data), component: a.component, instance: a.instance, parent: a.parent,
+  sinks: [...a.sinks], cause: a.cause, at: a.at,
+  ...('after' in a ? {before: plain(a.before), after: plain(a.after)} : {}),
+})
+
+/** The tool implementations; `id` is the request id (for the confirm notice). Exported for tests. */
+export function pageTools(o: McpBridgeOptions, notifyWaiting: (id: any) => void = () => {}) {
+  const agents = new WeakMap<object, any>()
+  const agentsOf = (target: any) => {
+    if (typeof o.agentTools != 'function') throw new ToolError('the agent layer is not available (agentTools from sygnal/ai)')
+    let t = agents.get(target)
+    if (!t) agents.set(target, t = o.agentTools(target))
+    return t
+  }
+  const confirmFor = (id: any) => {
+    const c = o.confirm === undefined ? 'page' : o.confirm
+    if (c !== 'page') return !!c
+    return async (info: any) => {
+      if (typeof g.window?.confirm != 'function') return false
+      notifyWaiting(id)
+      // let the notice leave before the dialog blocks the page
+      await new Promise(r => setTimeout(r, 30))
+      const input = info.input === undefined ? '' : `\n\nInput: ${JSON.stringify(info.input)}`
+      return !!g.window.confirm(`An agent (MCP, sygnal dev server) wants to run "${info.tool}" on ${info.component}${info.label ? ` (${info.label})` : ''}: ${info.description}${input}\n\nAllow it?`)
+    }
+  }
+
+  const tools: Record<string, (args: any, id: any) => any> = {
+    apps() {
+      return {apps: pageApps(o).map((a, i) => {
+        let id, instances = 0
+        try { id = a.api.root.id; instances = allInstances(a.api).length } catch (_) {}
+        return {...appSummary(a, i), id, instances, ...(i === 0 ? {default: true} : {})}
+      })}
+    },
+
+    get_state(args) {
+      const rt = runtimeFor(o, args)
+      const found = find(rt, args.component)
+      if (!found.length) throw new ToolError(`no component ${JSON.stringify(args.component)} is shown now; components: ${names(rt) || 'none'}`)
+      const withPath = (iv: any) => {
+        const s = stateOf(iv)
+        if (args.path === undefined) return s
+        return {...s, path: args.path, state: plain(at(iv.state, args.path))}
+      }
+      if (found.length == 1) return withPath(found[0])
+      return {component: args.component, instances: found.map(withPath)}
+    },
+
+    async dispatch(args) {
+      if (typeof args.action != 'string' || !args.action) throw new ToolError('dispatch needs action: the action name, e.g. "ADD"')
+      const rt = runtimeFor(o, args)
+      const iv = one(rt, args.component, 'dispatch to')
+      const known = actionNames(iv)
+      if (!known.includes(args.action) && !args.action.includes('.')) {
+        throw new ToolError(`${iv.name} has no action ${args.action}; its actions: ${known.join(', ') || 'none'}`)
+      }
+      const before = iv.state
+      rt.dispatch(iv.id, args.action, args.data, 'agent')
+      await rt.flushed()
+      const after = iv.disposed ? undefined : iv.state
+      return {ok: true, component: iv.name, id: iv.id, action: args.action, changed: after !== before, ...(iv.disposed ? {disposed: true} : {state: plain(after)})}
+    },
+
+    component_tree(args) {
+      // every app's instances, unless `app` names one
+      const app = pickApp(o, args.app)
+      const inspect = g.__SYGNAL_DIAGNOSTICS__?.inspect || (getDevTools() as any).inspect
+      if (typeof inspect != 'function') {
+        throw new ToolError("component_tree needs the runtime diagnostics ('sygnal/diagnostics'), which sygnal({ diagnostics: 'off' }) leaves out")
+      }
+      const graph = inspect()
+      if (!graph || !Array.isArray(graph.components)) return graph
+      let keep = graph.components
+      if (args.app !== undefined && args.app !== null) {
+        const ids = new Set(allInstances(app.api).map((i: any) => String(i.id)))
+        keep = keep.filter((c: any) => ids.has(String(c.id)))
+      }
+      if (args.component) keep = keep.filter((c: any) => c.name === args.component || String(c.id) === String(args.component))
+      return keep === graph.components ? graph : {...graph, components: keep}
+    },
+
+    recent_actions(args) {
+      const limit = Math.max(1, Math.min(500, Number(args.limit) || 20))
+      const filter: any = {}
+      if (args.component) filter.component = String(args.component)
+      if (args.type) filter.type = String(args.type)
+      if (args.cause) filter.cause = args.cause
+      const all = getActions(Object.keys(filter).length ? filter : undefined)
+      return {total: all.length, actions: all.slice(-limit).map(serializeAction)}
+    },
+
+    get_diagnostics(args) {
+      let list: any[] = getDevTools().getDiagnostics() || []
+      if (args.code) list = list.filter(d => d.code === String(args.code).toUpperCase())
+      if (args.severity) list = list.filter(d => d.severity === args.severity)
+      const count = (s: string) => list.filter(d => d.severity === s).length
+      const limit = Math.max(1, Math.min(500, Number(args.limit) || 100))
+      return {
+        summary: {error: count('error'), warn: count('warn'), info: count('info')},
+        diagnostics: list.slice(-limit).map(d => ({
+          code: d.code, severity: d.severity, component: d.component, message: d.message,
+          ...(d.fix ? {fix: d.fix} : {}), docsUrl: d.docsUrl, ...(d.data !== undefined ? {data: plain(d.data)} : {}),
+        })),
+      }
+    },
+
+    copy_as_test(args) {
+      // the default app's root by default (the DevTools default would be the newest root)
+      const target = String(one(runtimeFor(o, args), args.component, 'copy').id)
+      try {
+        const rec = getSession(target)
+        // a module path ('./App.jsx') or a whole import line
+        const ci = args.componentImport === undefined ? '' : String(args.componentImport)
+        const componentImport = !ci ? undefined : /^\s*import\s/.test(ci) ? ci : `import ${rec.component} from '${ci.replace(/'/g, "\\'")}'`
+        return sessionToTest(rec, componentImport ? {componentImport} : {})
+      } catch (e: any) {
+        throw new ToolError(String(e?.message || e))
+      }
+    },
+
+    async agent_tools(args, id) {
+      const t = agentsOf(pickApp(o, args.app).target)
+      if (args.call === undefined) return {tools: t.list(args.all ? {all: true} : undefined), context: plain(t.context())}
+      if (typeof args.call != 'string') throw new ToolError('call must be a tool name (see agent_tools without call)')
+      const result = await t.call(args.call, args.input, {confirm: confirmFor(id)})
+      return plain(result)
+    },
+  }
+  return tools
+}
+
+let installed: Hot | null = null
+
+/**
+ * Connect this page to the dev server's MCP endpoint (sygnal/vite with `mcp: true` calls it from
+ * 'virtual:sygnal/mcp'). Once per page; no-op without a hot channel.
+ */
+export function installMcpBridge(hot: Hot | undefined, options: McpBridgeOptions = {}): void {
+  if (!hot || installed === hot) return
+  installed = hot
+  if (!options.app) trackApps()
+  const tools = pageTools(options, (id) => hot.send(MCP_RESPONSE, {id, waiting: true}))
+  const hello = (update?: boolean) => {
+    const d = g.document
+    let apps: any[] = []
+    try { apps = pageApps(options).map(appSummary) } catch (_) {}
+    hot.send(MCP_HELLO, {url: String(g.location?.href || ''), title: String(d?.title || ''), focused: !!d?.hasFocus?.(), apps, ...(update ? {update: true} : {})})
+  }
+  // the apps changed: tell the server after the tick (when the new roots exist)
+  let queued = false
+  listeners.add(() => {
+    if (queued) return
+    queued = true
+    setTimeout(() => { queued = false; hello(true) }, 0)
+  })
+  hot.on(MCP_REQUEST, async (msg: any) => {
+    if (!msg || msg.id === undefined) return
+    const fn = Object.prototype.hasOwnProperty.call(tools, msg.tool) ? tools[msg.tool] : undefined
+    try {
+      if (!fn) throw new ToolError(`unknown page tool ${msg.tool}`)
+      const args = msg.args && typeof msg.args == 'object' && !Array.isArray(msg.args) ? msg.args : {}
+      const result = await fn(args, msg.id)
+      hot.send(MCP_RESPONSE, {id: msg.id, ok: true, result: result === undefined ? null : result})
+    } catch (e: any) {
+      hot.send(MCP_RESPONSE, {id: msg.id, ok: false, error: e instanceof ToolError ? e.message : `${msg.tool} failed: ${e?.message || e}`})
+    }
+  })
+  // the server answers this after a reconnect too (a restarted dev server)
+  hot.on('vite:ws:connect', () => hello())
+  hello()
+  if (typeof g.addEventListener == 'function') {
+    g.addEventListener('focus', () => hello())
+    g.document?.addEventListener?.('visibilitychange', () => { if (g.document.visibilityState == 'visible') hello() })
+  }
+}