sygnal 5.3.7 → 6.0.0

package/src/extra/diagnostics/checks/index.ts

@@ -0,0 +1,202 @@
+/**
+ * 'sygnal/diagnostics' — runtime consistency checks (PLAN-1 workstream 1A).
+ *
+ *   import 'sygnal/diagnostics'
+ *
+ * Importing this entry registers every check with the diagnostics core of the
+ * 'sygnal' package (a side-effect import) and installs the RxJS-operator hints.
+ * Checks only run while diagnostics are on (run(App, drivers, { diagnostics }),
+ * or globalThis.__SYGNAL_DEV__ from the Vite plugin in dev). None of this code
+ * is in the main 'sygnal' bundle.
+ *
+ * | Code   | Check                                                  | Module         |
+ * |--------|--------------------------------------------------------|----------------|
+ * | SYG101 | intent action has no model entry                       | wiring.ts      |
+ * | SYG102 | model entry has no intent trigger (info)               | wiring.ts      |
+ * | SYG103 | intent selector never matched (info -> warn)           | dom.ts         |
+ * | SYG104 | intent selector only matches inside a child component  | dom.ts         |
+ * | SYG105 | EVENTS type emitted-not-selected / selected-not-emitted| events.ts      |
+ * | SYG106 | parent prop overwritten by a reserved view argument    | props.ts       |
+ * | SYG112 | reply action has no model entry                        | replies.ts     |
+ * | SYG630 | cached request that isn't idempotent (POST + cache)    | fetch.ts       |
+ * | SYG631 | validate is not a Standard Schema                      | fetch.ts       |
+ * | SYG632 | invalidate matched nothing (info)                      | fetch.ts       |
+ * | SYG633 | abort names a lane its requests don't use              | fetch.ts       |
+ * | SYG635 | cache: true / staleTime / prefetch without queryCache() | fetch.ts       |
+ * | SYG115 | unknown DOM event shorthand (DOM.key(...))             | shorthand.ts   |
+ * | SYG124 | component where a control or selector is expected      | controls.ts    |
+ * | SYG140 | widget emitted an event it doesn't declare             | widgets.ts     |
+ * | SYG142 | widget command not declared (also a reserved name)     | elementCommands.ts, widgets.ts |
+ * | SYG143 | widget tag used as a selector                          | widgets.ts     |
+ * | SYG144 | declared widget event the host also fires (info)       | widgets.ts     |
+ * | SYG660 | widget mount / update / unmount threw (660/661/662)    | widgets.ts     |
+ * | SYG430 | VirtualCollection: no bounded height; SYG431 items without ids; SYG432 item not one element; SYG433 scroll target not in the list; SYG434 bad estimateSize / overscan | virtual.ts |
+ * | SYG125 | control given component statics / bad spec vnode()     | controls.ts    |
+ * | SYG127 | behavior key in initialState / unresolvable uses entry | behaviors.ts   |
+ * | SYG230 | form: field name not in values; SYG231 not a Standard Schema; SYG232 submit dropped (info); SYG233 value missing from the schema output | forms.ts |
+ * | SYG234 | form submit action has no model entry; SYG235 check names an unknown field / sets reply fields; SYG236 rows without an id | forms.ts |
+ * | SYG145 | sortable: item without its id attribute; SYG146 item / handle selector matches nothing; SYG147 from is not an array | sortable.ts |
+ * | SYG116 | EVENTS value with no string type (a function)          | events.ts      |
+ * | SYG130 | href() names no route / leaves out a param             | router.ts      |
+ * | SYG131 | route params the pattern doesn't use                   | router.ts      |
+ * | SYG132 | declaration static never sent: a root without initialState    | router.ts      |
+ * | SYG133 | SPA router inside a Vike app                           | router.ts      |
+ * | SYG422 | timer spec makeTimerDriver() can't run                 | timers.ts      |
+ * | SYG643 | timers/connections/resources/browser with no driver    | timers.ts      |
+ * | SYG663 | browser entry / BROWSER command that can't run         | browserSources.ts |
+ * | SYG664 | browser source the driver wasn't made with             | browserSources.ts |
+ * | SYG665 | browser source failed with no error action             | browserSources.ts |
+ * | SYG668 | intersection / resize with no element to observe       | browserSources.ts |
+ * | SYG238 | a root with a model but no initialState: renders nothing | state.ts       |
+ * | SYG223 | persist pick/omit key not in initialState              | persist.ts     |
+ * | SYG224 | persist on a component that isn't the root             | persist.ts     |
+ * | SYG645 | viewTransitions without makeViewTransitionDOMDriver(), or not an array | viewTransitions.ts |
+ * | SYG201 | STATE reducer dropped keys                             | state.ts       |
+ * | SYG202 | STATE reducer returned undefined                       | state.ts       |
+ * | SYG221 | set() called with a string                             | state.ts       |
+ * | SYG222 | same object returned after an in-place mutation        | state.ts       |
+ * | SYG301 | RxJS operator used on an xstream stream                | rxjsHints.ts   |
+ * | SYG401 | Collection `from` missing or not an array              | collections.ts |
+ * | SYG421 | invalid data (dataset) key in a view                   | dataset.ts     |
+ * | SYG612 | a form 6.0 removed (also SYG501/504 statically)        | next.ts        |
+ * | SYG502 | retired in 6.0 (never reported; GS-4)                  | —              |
+ * | SYG508 | strict: select()/errors() round trip on a reply source | replies.ts    |
+ * | —      | D152: shared statics frozen (initialState deep)        | statics.ts     |
+ * | —      | inspect(): the runtime app graph (2B)                  | inspect.ts     |
+ *
+ * SYG112, SYG130-133 (PLAN-3), SYG115/116/221/421 (G-143) SYG124/125 (PLAN-4 CT-1) and SYG127 (GS-1) are dev-entry-only codes: their severities live in
+ * DEV_CODE_SEVERITY (codes.ts), registered by ./shared, not in the main bundle.
+ *
+ * Strict checks (SYG5xx) only report after configureStrict(true) (or
+ * renderComponent(C, { strict: true }), or globalThis.__SYGNAL_STRICT__).
+ */
+import type {DiagnosticCheck} from '../index'
+import {Stream} from '../../xstreamCompat'
+import {bridge, resetCheckState, timing} from './shared'
+import {wiringCheck} from './wiring'
+import {stateCheck} from './state'
+import {eventsCheck} from './events'
+import {propsCheck} from './props'
+import {collectionsCheck} from './collections'
+import {domCheck} from './dom'
+import {shorthandCheck} from './shorthand'
+import {controlsCheck, installControlHooks} from './controls'
+import {elementCommandsCheck, installElementCommandHooks} from './elementCommands'
+import {installWidgetHooks} from './widgets'
+import {installVirtualHooks} from './virtual'
+import {behaviorsCheck} from './behaviors'
+import {formsCheck, installFormHooks} from './forms'
+import {installSortableHooks} from './sortable'
+import {datasetCheck} from './dataset'
+import {strictCheck} from './strict'
+import {repliesCheck} from './replies'
+import {routerCheck, installRouterHooks} from './router'
+import {fetchCheck} from './fetch'
+import {timersCheck, installTimerHooks} from './timers'
+import {installBrowserSourceHooks} from './browserSources'
+import {persistCheck} from './persist'
+import {viewTransitionsCheck} from './viewTransitions'
+import {staticsCheck} from './statics'
+import {installRxjsHints} from './rxjsHints'
+import {inspectCheck, installInspect} from './inspect'
+import {nextHooks} from './next'
+
+export {checkEventBus} from './events'
+export {configureStrict, isStrictEnabled} from './strict'
+export type {EventBusSummary} from './events'
+export {RXJS_HINTS} from './rxjsHints'
+export {inspect} from './inspect'
+export type {InspectResource, InspectCacheEntry, InspectGraph, InspectComponent, InspectAction, InspectActionTrigger, InspectChild, InspectSelector, InspectControl, InspectDiagnostic, InspectOptions, InspectRecentAction} from './public'
+export {listCodes, getCodeInfo} from '../codes'
+export type {DiagnosticCodeInfo} from '../codes'
+
+/** Every runtime check in this entry. */
+export const checks: DiagnosticCheck[] = [
+  wiringCheck,
+  stateCheck,
+  eventsCheck,
+  propsCheck,
+  collectionsCheck,
+  domCheck,
+  shorthandCheck,
+  controlsCheck,
+  elementCommandsCheck,
+  behaviorsCheck,
+  formsCheck,
+  datasetCheck,
+  strictCheck,
+  repliesCheck,
+  routerCheck,
+  fetchCheck,
+  timersCheck,
+  persistCheck,
+  viewTransitionsCheck,
+  staticsCheck,
+  inspectCheck,
+]
+
+/**
+ * (Re-)register all checks with the core and install the RxJS hints. Called
+ * on import. Idempotent across duplicate copies of this entry: the previous
+ * installation (stored on the core bridge) is removed first.
+ */
+export function installChecks(): () => void {
+  const core = bridge()
+  if (!core) throw new Error(`[Sygnal] 'sygnal/diagnostics' could not find the Sygnal diagnostics core`)
+  if (typeof core.__uninstallChecks === 'function') core.__uninstallChecks()
+  const unregister = checks.map(check => core.registerCheck(check))
+  const uninstallHints = installRxjsHints(Stream && Stream.prototype)
+  const uninstallInspect = installInspect()
+  const uninstallRouter = installRouterHooks()
+  const uninstallControls = installControlHooks()
+  const uninstallTimers = installTimerHooks()
+  const uninstallBrowser = installBrowserSourceHooks()
+  const uninstallElementCommands = installElementCommandHooks()
+  const uninstallWidgets = installWidgetHooks()
+  const uninstallVirtual = installVirtualHooks()
+  const uninstallForms = installFormHooks()
+  const uninstallSortable = installSortableHooks()
+  // PLAN-4.6 R4: the core reads its hooks from the bridge once per app (checks/next.ts)
+  ;(core.layers ||= new Set()).add(nextHooks)
+  const uninstall = () => {
+    core.layers?.delete(nextHooks)
+    unregister.forEach(fn => fn())
+    uninstallHints()
+    uninstallInspect()
+    uninstallRouter()
+    uninstallControls()
+    uninstallTimers()
+    uninstallBrowser()
+    uninstallElementCommands()
+    uninstallWidgets()
+    uninstallVirtual()
+    uninstallForms()
+    uninstallSortable()
+    if (core.__uninstallChecks === uninstall) core.__uninstallChecks = undefined
+  }
+  core.__uninstallChecks = uninstall
+  return uninstall
+}
+
+export interface ChecksOptions {
+  /** delay after a render before the DOM checks (SYG103/104) run; default 50 ms */
+  settleMs?: number
+  /** render-idle time before SYG103 escalates to warn; default 2000 ms */
+  idleMs?: number
+  /** renders required before SYG103 escalates to warn; default 3 */
+  minRenders?: number
+}
+
+/** Tune the timing of the DOM checks (mostly for tests). */
+export function configureChecks(options: ChecksOptions = {}): void {
+  for (const key of Object.keys(timing) as Array<keyof typeof timing>) {
+    if (typeof options[key] === 'number') timing[key] = options[key] as number
+  }
+}
+
+/** Forget what the checks have seen and reported (dedupe state, registries). For tests. */
+export function resetChecks(): void {
+  resetCheckState()
+}
+
+installChecks()

package/src/extra/diagnostics/checks/inspect.ts

@@ -0,0 +1,427 @@
+/**
+ * inspect() — the machine-readable app graph at runtime (PLAN-1 workstream 2B).
+ *
+ * Built only from what the diagnostics hooks already see, keyed by component
+ * instance (so diagnostics must be on while the app runs):
+ *   onIntent    registers the instance (name, parent, kind) and its intent
+ *               action names; claims the EVENTS.select() types seen since the
+ *               previous onIntent (intent runs synchronously right before it)
+ *   onModel     action -> sinks
+ *   onSink      (checks/next.ts: eventEmitted) the EVENTS types the instance emitted. Since
+ *               B-023 the driver-side emitter name (onBusEmit) is the emitting
+ *               component's, but it is only a name, and this graph is per instance
+ *   onReducer   which model-only actions actually ran (=> dispatched by next(),
+ *               unless a request named them as reply actions: replies.ts, 'reply')
+ *   onBusEmit   EVENTS types seen on the bus
+ *   onBusSelect EVENTS types selected (see onIntent)
+ *   onRender    (PLAN-4 CT-1) the controls the instance renders: its own vtree, up to the
+ *               isolated child components, through ./controls' vnode -> control map
+ *   onDispose   prunes the instance
+ *   (PLAN-4 2-C) the action log (./actionLog: actionHooks, a layer of checks/next.ts) feeds
+ *               inspect({ actions }): the recent actions (the last RECENT_MAX, any instance)
+ * Selectors come from the DOM check (real DOM) or from renderComponent (mock
+ * DOM, passed in as options.selectors). The same shape is produced statically
+ * by `sygnal-check --graph`; the JSON Schema is
+ * sygnal-check/schema/inspect.schema.json, the types are in ./public.d.ts.
+ *
+ * This lives in the 'sygnal/diagnostics' dev entry only (D29: zero bytes in
+ * app bundles). installInspect() publishes inspect() on the core bridge
+ * (renderComponent's t.inspect() reads it there) and on the devtools object
+ * (window.__SYGNAL_DEVTOOLS__, which is getDevTools()) once it exists.
+ */
+import type {DiagnosticCheck} from '../index'
+import type {InspectGraph, InspectComponent, InspectOptions, InspectSelector, InspectDiagnostic, InspectChild, InspectResource, InspectControl, InspectRecentAction} from './public'
+import {clockNow} from './actionLog'
+import type {ActionListener, ActionRecord} from './actionLog'
+import {bridge, onReset, nameOf, isPlainObject, BUILTIN_ACTIONS, replySeen} from './shared'
+import {checkEventBus} from './events'
+import {selectorStatus} from './dom'
+import {controlOfVnode, keyOfSelector} from './controls'
+
+type Kind = InspectComponent['kind']
+
+interface Rec {
+  instance: any
+  id: string
+  name: string
+  parentId: string | null
+  kind: Kind
+  /** null: single-stream intent (no action names) */
+  intentActions: string[] | null
+  injected: Set<string>
+  modelMap: Record<string, string[]>
+  fired: Set<string>
+  eventsSelected: Set<string>
+  eventsEmitted: Set<string>
+  /** CT-1: controls seen in its renders, by key (first-seen order) */
+  controls: Map<string, {element: string | null; kind?: string}>
+}
+
+let records = new Map<any, Rec>()
+let pendingSelects: string[] = []
+/** every EVENTS type seen on the bus */
+let busTypes = new Set<string>()
+/** PLAN-4 2-C (GS-10): the most recent actions of any instance, oldest first */
+const RECENT_MAX = 200
+let recent: ActionRecord[] = []
+let epoch = clockNow()
+export const actionListener: ActionListener = {
+  action(r) { if (recent.push(r) > RECENT_MAX) recent.shift() },
+}
+
+onReset(() => {
+  records = new Map()
+  pendingSelects = []
+  busTypes = new Set()
+  recent = []
+  epoch = clockNow()
+})
+const uniq = <T>(list: Iterable<T>): T[] => [...new Set(list)]
+
+const NEXT_KIND: Record<string, Kind> = {root: 'root', child: 'child', item: 'collection-item', page: 'switchable'}
+
+function kindOf(c: any): Kind {
+  // PLAN-4.6 R4: the core's instance view says it (checks/next.ts)
+  return (c && c.__next && NEXT_KIND[c.__next.kind]) || 'child'
+}
+
+function ensure(c: any): Rec {
+  let r = records.get(c)
+  if (!r) {
+    const parent = c && c.__next && c.__next.parentId
+    r = {
+      instance: c,
+      id: String(c && c._componentNumber),
+      name: nameOf(c),
+      parentId: typeof parent === 'number' ? String(parent) : null,
+      kind: kindOf(c),
+      intentActions: [],
+      injected: new Set(),
+      modelMap: {},
+      fired: new Set(),
+      eventsSelected: new Set(),
+      eventsEmitted: new Set(),
+      controls: new Map(),
+    }
+    records.set(c, r)
+  }
+  return r
+}
+
+let devtools: any
+function attachDevtools(): void {
+  const dt = (globalThis as any).__SYGNAL_DEVTOOLS__
+  if (!dt || typeof dt !== 'object') return
+  devtools = dt
+  if (dt.inspect !== inspect) {
+    try { dt.inspect = inspect } catch (_) { /* frozen: ignore */ }
+  }
+}
+
+export const inspectCheck: DiagnosticCheck = {
+  id: 'inspect',
+
+  onBusSelect(type) {
+    if (type === undefined || type === null || type === '') pendingSelects.push('*')
+    else for (const t of ([] as any[]).concat(type)) if (typeof t === 'string') pendingSelects.push(t)
+    if (pendingSelects.length > 1000) pendingSelects.shift()
+  },
+
+  onIntent(component, actionNames) {
+    attachDevtools()
+    const r = ensure(component)
+    const intent$ = component && component.intent$
+    r.intentActions = actionNames || []
+    r.injected = new Set((intent$ && typeof intent$ === 'object' && intent$.__sygnalTestActions) || [])
+    for (const t of pendingSelects) r.eventsSelected.add(t)
+    pendingSelects = []
+  },
+
+  onModel(component, modelMap) {
+    const r = ensure(component)
+    r.modelMap = modelMap || {}
+  },
+
+  onRender(component, root) {
+    const r = records.get(component)
+    if (r) collectControls(root, r.controls, true)
+  },
+
+  onReducer(component, action) {
+    const r = records.get(component)
+    if (r && typeof action === 'string') r.fired.add(action)
+  },
+
+  onBusEmit(type) {
+    if (typeof type === 'string') busTypes.add(type)
+  },
+
+  onDispose(component) {
+    records.delete(component)
+  },
+}
+
+/** PLAN-4.6 R4 (onSink): an EVENTS value the instance sent */
+export function eventEmitted(component: any, ev: any): void {
+  const r = records.get(component)
+  if (r && ev && typeof ev.type === 'string') r.eventsEmitted.add(ev.type)
+}
+
+/**
+ * CT-1: record the controls in a component's rendered tree (data-control="<Key>"), stopping at
+ * isolated child components (their root carries data.isolate on the real DOM, a '.___<scope>'
+ * class in the mock DOM): the controls inside belong to the child.
+ */
+function collectControls(v: any, out: Rec['controls'], root: boolean): void {
+  if (!v || typeof v != 'object') return
+  if (!root && typeof v.sel == 'string' && ((v.data && v.data.isolate) || v.sel.includes('.___'))) return
+  const key = v.data && v.data.attrs && v.data.attrs['data-control']
+  if (typeof key == 'string' && !out.has(key)) {
+    const control = controlOfVnode(v)
+    const spec = control && control.spec
+    out.set(key, spec && typeof spec == 'object'
+      ? {element: null, kind: String(spec.kind)}
+      : {element: typeof spec == 'string' ? spec : typeof v.sel == 'string' ? v.sel.split(/[.#]/)[0] : null})
+  }
+  for (const k of [].concat(v.children || [], (v.data && v.data.portalChildren) || [])) collectControls(k, out, false)
+}
+
+/** CT-1: the controls a component rendered, `listened` from its intent's selectors */
+function controlsOf(r: Rec, selectors: InspectSelector[]): InspectControl[] | undefined {
+  if (!r.controls.size) return undefined
+  const listened = new Set<string>()
+  for (const s of selectors) for (const m of s.selector.matchAll(/\[data-control="([^"]+)"\]/g)) listened.add(m[1])
+  return [...r.controls].map(([name, {element, kind}]) => ({name, element, ...(kind ? {kind} : {}), listened: listened.has(name)}))
+}
+
+/** CT-1: mark a selector that is a control ([data-control="<Key>"]) with its key */
+const withControl = (s: InspectSelector): InspectSelector => {
+  const key = keyOfSelector(s.selector)
+  return key ? {...s, control: key} : s
+}
+
+const slim = (d: any): InspectDiagnostic => {
+  const out: InspectDiagnostic = {code: d.code, severity: d.severity, message: d.message}
+  if (d.component) out.component = d.component
+  if (d.fix) out.fix = d.fix
+  if (d.docsUrl) out.docsUrl = d.docsUrl
+  if (d.data !== undefined) {
+    // keep it JSON-safe (data can hold errors, vnodes, ...)
+    try { out.data = JSON.parse(JSON.stringify(d.data)) } catch (_) { /* drop */ }
+  }
+  return out
+}
+
+function actionsOf(r: Rec): InspectComponent['actions'] {
+  const intent = (r.intentActions || []).filter(a => !r.injected.has(a))
+  const names = uniq([...intent, ...Object.keys(r.modelMap)]).filter(a => typeof a === 'string' && !a.startsWith('__'))
+  const replies = replySeen.get(r.instance)
+  return names.map(name => ({
+    name,
+    trigger: BUILTIN_ACTIONS.has(name) ? 'builtin'
+      : intent.includes(name) ? 'intent'
+      : replies?.has(name) ? 'reply'
+      : !r.injected.has(name) && r.fired.has(name) ? 'next'
+      : 'unknown',
+    sinks: [...(r.modelMap[name] || [])],
+  }))
+}
+
+function stateKeysOf(c: any, calculated: string[]): string[] {
+  const s = c && c.currentState
+  return isPlainObject(s) ? Object.keys(s).filter(k => !calculated.includes(k)) : []
+}
+
+/** PLAN-3 5-3: the instance's resources (`resources` static) and their state slots */
+function resourcesOf(c: any): InspectResource[] | undefined {
+  const res = c && c.view && c.view.resources
+  if (!res || typeof res !== 'object') return undefined
+  const s = c.currentState || {}
+  return Object.keys(res).map(name => {
+    const r = s[name] || {}
+    return {name, status: r.status ?? 'idle', refreshing: !!r.refreshing, hasData: r.data !== undefined, error: r.error ? String(r.error.message ?? r.error) : undefined}
+  })
+}
+
+/** PLAN-3 5-3: the cache entries of every makeFetchDriver source the instances use, by sink name (sinks with an empty cache left out) */
+function cacheOf(recs: Rec[]): InspectGraph['cache'] {
+  const out: NonNullable<InspectGraph['cache']> = {}
+  for (const r of recs) {
+    const sources = r.instance && r.instance.sources
+    if (!sources || typeof sources !== 'object') continue
+    for (const k of Object.keys(sources)) {
+      const src = sources[k]
+      if (out[k] || !src || src.__sygnalStatic !== 'resources' || typeof src.__inspect !== 'function') continue
+      try { const list = src.__inspect().cache; if (list.length) out[k] = list } catch (_) { /* a driver without the cache listing */ }
+    }
+  }
+  return out
+}
+
+/**
+ * renderComponent's mock DOM (src/extra/testing.ts passes its listener registry):
+ * listener paths are the select() chain with isolation scopes as '.___<scope>' entries;
+ * probe(selectors, scope) matches one against the latest vtree: own = in the component's
+ * own scope, child = the scope of the first (isolated) child component it matches inside.
+ */
+interface MockDom {
+  listeners: Map<string, string[]>
+  evTypes: Record<string, string[]>
+  owners: Map<string, string>
+  scopeIds: Map<string, number>
+  probe: (selectors: string[], scope?: string) => {own: boolean; child?: string}
+  vtree: any
+}
+
+const isScope = (s: string) => s.startsWith('.___')
+
+function mockSelectors(mock: MockDom): Record<string, InspectSelector[]> {
+  const out: Record<string, InspectSelector[]> = {}
+  mock.listeners.forEach((path, key) => {
+    const scope = path.filter(isScope).pop()
+    const id = mock.scopeIds.get(scope || '')
+    if (id === undefined) return
+    const sels = path.filter(s => !isScope(s)).join(' ').split(/[\s>]+/).filter(Boolean)
+    const page = !sels.length || /^(document|body)$/.test(sels[0])
+    const {own, child} = mock.vtree && !page ? mock.probe(sels, scope) : {own: false, child: undefined}
+    ;(out[id] = out[id] || []).push({
+      selector: sels.join(' '),
+      events: uniq(mock.evTypes[key] || []),
+      matched: mock.vtree && !page ? own : null,
+      isolationHit: !own && child ? mock.owners.get(child) || 'a child component' : null,
+    })
+  })
+  return out
+}
+
+function selectorsOf(r: Rec, options: InspectOptions, diags: any[]): InspectSelector[] {
+  const given = options.selectors && options.selectors[r.id]
+  if (given) return given.map(s => withControl({...s}))
+  return (selectorStatus(r.instance) || []).map(({selector, matched, crossed}) => {
+    const hit = diags.find(d => d.code === 'SYG104' && d.component === r.name && d.data && d.data.selector === selector)
+    const missed = diags.some(d => d.code === 'SYG103' && d.component === r.name && d.data && d.data.selector === selector)
+    return withControl({
+      selector,
+      events: null,
+      matched: matched === null && missed ? false : matched,
+      isolationHit: crossed ? ((hit && hit.data.child) || 'a child component') : null,
+    })
+  })
+}
+
+function childrenOf(r: Rec, all: Rec[]): InspectChild[] {
+  const via: Record<Kind, InspectChild['via']> = {root: 'tag', child: 'tag', 'collection-item': 'collection', switchable: 'switchable'}
+  const out = new Map<string, InspectChild>()
+  for (const c of all) {
+    if (c.parentId !== r.id) continue
+    const key = `${c.name}\u0000${via[c.kind]}`
+    const entry = out.get(key)
+    if (entry) entry.count = (entry.count || 1) + 1
+    else out.set(key, {name: c.name, via: via[c.kind], count: 1})
+  }
+  return [...out.values()]
+}
+
+/** The app graph of the live component instances (see ./public.d.ts). */
+export function inspect(options: InspectOptions = {}): InspectGraph {
+  // report SYG105 (info) for EVENTS types selected but never emitted so far
+  try { checkEventBus() } catch (_) { /* 'error' mode: info never throws; be safe */ }
+
+  let diags: any[] = options.diagnostics as any[] || []
+  if (!options.diagnostics) {
+    attachDevtools()
+    try { diags = (devtools && typeof devtools.getDiagnostics === 'function' && devtools.getDiagnostics()) || [] } catch (_) { diags = [] }
+  }
+
+  const mock: MockDom | undefined = (options as any).mock
+  if (mock) options = {...options, selectors: {...mockSelectors(mock), ...options.selectors}}
+
+  const all = [...records.values()]
+  const ids = options.ids && new Set(options.ids.map(String))
+  const recs = ids ? all.filter(r => ids.has(r.id)) : all
+  const names = new Set(recs.map(r => r.name))
+
+  const components: InspectComponent[] = recs.map(r => {
+    const c = r.instance
+    const calculated = c && c.calculated && typeof c.calculated === 'object' ? Object.keys(c.calculated) : []
+    const selectors = selectorsOf(r, options, diags)
+    const controls = controlsOf(r, selectors)
+    return {
+      name: r.name,
+      id: r.id,
+      parentId: r.parentId,
+      kind: r.kind,
+      actions: actionsOf(r),
+      stateKeys: stateKeysOf(c, calculated),
+      calculated,
+      contextProvides: c && isPlainObject(c.context) ? Object.keys(c.context) : [],
+      contextConsumes: null,
+      eventsEmitted: [...r.eventsEmitted],
+      eventsSelected: [...r.eventsSelected],
+      children: childrenOf(r, all),
+      selectors,
+      ...(controls ? {controls} : {}),
+      diagnostics: diags.filter(d => d && d.component === r.name).map(slim),
+      ...(resourcesOf(c) ? {resources: resourcesOf(c)} : {}),
+    }
+  })
+
+  const cache = cacheOf(recs) || {}
+  const events: InspectGraph['events'] = {}
+  const ev = (type: string) => events[type] || (events[type] = {emitters: [], selectors: []})
+  const add = (list: string[], name: string) => { if (!list.includes(name)) list.push(name) }
+  for (const c of components) {
+    for (const t of c.eventsEmitted) add(ev(t).emitters, c.name)
+    for (const t of c.eventsSelected) add(ev(t).selectors, c.name)
+  }
+  // emitted on the bus by something that isn't a listed component (e.g. a driver, a pruned component)
+  if (!ids) for (const t of busTypes) ev(t)
+
+  return {
+    version: 1,
+    source: 'runtime',
+    components,
+    events,
+    diagnostics: diags.filter(d => d && (!d.component || !names.has(d.component))).map(slim),
+    ...(Object.keys(cache).length ? {cache} : {}),
+    ...(options.actions ? {recentActions: recentActions(options.actions, ids)} : {}),
+  }
+}
+
+/** a JSON-safe copy of an action's data (dropped when it doesn't serialize, or is large: a DOM event) */
+function jsonData(d: any): {data?: any} {
+  if (d === undefined) return {}
+  try {
+    const text = JSON.stringify(d)
+    return text === undefined || text.length > 1000 ? {} : {data: JSON.parse(text)}
+  } catch (_) { return {} }
+}
+
+/** PLAN-4 2-C: the last `limit` actions (true: all kept) of the listed instances */
+function recentActions(limit: true | number, ids: Set<string> | undefined): InspectRecentAction[] {
+  const list = ids ? recent.filter(r => ids.has(r.instance)) : recent
+  const n = limit === true ? list.length : Math.max(0, Math.floor(limit))
+  return list.slice(list.length - n).map(r => ({
+    type: r.type,
+    ...jsonData(r.data),
+    component: r.component,
+    instance: r.instance,
+    sinks: [...r.sinks],
+    cause: r.cause,
+    at: r.time - epoch,
+  }))
+}
+
+/** Publish inspect() on the core bridge and the devtools object. Returns an uninstall function. */
+export function installInspect(): () => void {
+  const core = bridge()
+  if (core) core.inspect = inspect
+  attachDevtools()
+  return () => {
+    if (core && core.inspect === inspect) core.inspect = undefined
+    const dt = (globalThis as any).__SYGNAL_DEVTOOLS__
+    if (dt && dt.inspect === inspect) {
+      try { delete dt.inspect } catch (_) { /* ignore */ }
+    }
+  }
+}