sygnal 6.4.0 → 6.6.0

package/llms.txt

@@ -4,7 +4,7 @@
 
 ## 1. Mental model
 - A component is a pure view function plus static properties: `.intent` (WHEN: sources → named action streams), `.model` (WHAT: action → one reducer per sink), `.initialState`.
-- There is one state tree. A child sees its parent's whole state, or a slice with `state="key"`. A Collection item sees one array element.
+- There is one state tree. A child sees its parent's whole state, or a slice with `state="key"` (or a path: `state="settings.rules"`, `"boards[0].title"`). A Collection item sees one array element.
 - Every side effect is a sink of a model entry (STATE, EVENTS, PARENT, EFFECT, custom drivers). JSX never has event handlers (`onClick`).
 - Streams are xstream, not RxJS. An intent's DOM selectors only see the component's own JSX, never a child component's.
 
@@ -117,7 +117,7 @@ TaskList.initialState = { picked: null, tasks: [{ id: 1, title: 'Write' }, { id:
 TaskList.intent = ({ CHILD }) => ({ PICKED: CHILD.select(TaskItem) })  // the function, not a string
 TaskList.model = { PICKED: (state, { taskId }) => ({ ...state, picked: taskId }) }
 ```
-- `from` names an array field. Items are keyed by `.id` (by index if they have none). `filter={t => !t.done}`; `sort="title"`, `{ title: 'desc' }`, an array of those, or a compare function. Sorting and filtering only change what renders: the state array keeps its order, and an item's edit (`{ ...state, done: true }`) is written back to its element by key. Items render directly into the parent element, with no wrapper (`<Collection className>` is SYG612: put the class on your own `<ul>`). Switchable: `<Switchable of={{ home: Home, settings: Settings }} current={state.tab} />` (optional `state="slice"`); hidden pages stay alive, and `instance={key}` re-creates the current page with fresh state when the key changes (a router: `instance={state.route.path}`).
+- `from` names an array field (or a path to one: `from="board.cards"`). Items are keyed by `.id` (by index if they have none). `filter={t => !t.done}`; `sort="title"`, `{ title: 'desc' }`, an array of those, or a compare function. Sorting and filtering only change what renders: the state array keeps its order, and an item's edit (`{ ...state, done: true }`) is written back to its element by key. Items render directly into the parent element, with no wrapper (`<Collection className>` is SYG612: put the class on your own `<ul>`). Switchable: `<Switchable of={{ home: Home, settings: Settings }} current={state.tab} />` (optional `state="slice"`); hidden pages stay alive, and `instance={key}` re-creates the current page with fresh state when the key changes (a router: `instance={state.route.path}`).
 ### Behaviors (`uses`): shared state + actions
 - `TaskList.uses = { pager: pager({ pageSize: 10, next: '.newer', prev: '.older' }) }` adds `state.pager` (`{ page, pageSize, total }` + calculated `offset`, `pages`, `hasPrev`, `hasNext`) and the actions `pager.NEXT`, `pager.PREV`, `pager.GOTO`, `pager.SET_TOTAL`; a click on what `next`/`prev` name triggers them. Options set the slice's start values; the key must not also be in `initialState` (SYG127). Also from `'sygnal'`: `selection({ multi: true, item: '.pick', from: 'mails' })` (`data-id` on each item; `isSelected(state.sel, id)`) and `undo({ key: 'doc', undo: '.undo', redo: '.redo' })` (`state.history.canUndo`/`canRedo`; `coalesce: ['TYPE'], coalesceMs: 500` groups only typing, each other action is its own step; `key: ['todo', 'done']` records several keys as one step; `node_modules/sygnal/dist/guide/undo.md`).
 - Your own: `const disclosure = defineBehavior({ initialState: { open: false }, intent: ({ DOM }, { toggle }) => ({ TOGGLE: DOM.click(toggle) }), model: { TOGGLE: (slice) => ({ ...slice, open: !slice.open }) } })`, used as `uses = { more: disclosure({ toggle: '.more' }) }`. Its reducers and `calculated` get and return the slice (`state.more`), its action names have no key, and any sink works. Options: `persist: false` (UI state `persist()` never saves), `undoStep: ['DONE']` (its other actions form one gesture: one undo entry when `DONE` completes it).
@@ -258,7 +258,7 @@ TaskPage.model = {   // a page shares the parent's state: no initialState (SYG40
 - Guides: `node_modules/sygnal/dist/guide/ai-chat.md` (transports, structured `output`, tools, shipping), `ai-decisions.md` (escalation, `decide.openai()`), `ai-compose.md` (catalogs, containers, edits, `byId`), `ai-cards.md` (`chat({ ask })`, client tools), `agent.md` (the in-app assistant `uses = { assistant: chat({ form: '.ask', prompt: '.prompt', instructions }) }`, `commandBar`, security), `webmcp.md` (`experimentalExposeWebMcp(app)`, `form(schema, { tool: formTool({ name, description }) })`: experimental, outside semver), `mcp-apps.md` (`makeMcpAppDriver()`: the app inside Claude or ChatGPT); online https://sygnal.js.org/guide/ai-chat/ (and `/guide/ai-decisions/`, `/guide/ai-compose/`, `/guide/ai-cards/`, `/guide/agent/`, `/guide/webmcp/`, `/guide/mcp-apps/`)
 
 ## 4. API facts
-- **Child props**: `<Rating name="food" value={state.food} />` → `function Rating({ state, name, value })`; reducers read `props.name` (4th arg); intent gets the `props$` stream. Reserved: `state` (lens: `"key"` or `{ get, set }`), `children`, `slots`, `context`, `uid` (SYG106; an error in strict mode). `key={…}` is a child's identity (not a prop; else its `id` prop, else its place in the view): a new key re-creates it. Without `state=` a child shares its parent's whole state. A child rendered by tag (`<Stopwatch state="stopwatch" />`) has no `initialState`: its start values go in the parent's (`stopwatch: { ms: 0 }`); its own throws SYG405 and the parent renders its error fallback (a test rendering the child as the root doesn't show it). Test a child alone with `renderComponent(Child, { initialState, context: { lang: 'fr' } })` (the ancestors' context). `uid(name?)` (a view prop, also on reducers' `props`) is a stable per-instance id for `id`/`for`/`aria-*` pairs: `<label for={uid('email')}>`, `<input id={uid('email')} />`.
+- **Child props**: `<Rating name="food" value={state.food} />` → `function Rating({ state, name, value })`; reducers read `props.name` (4th arg); intent gets the `props$` stream. Reserved: `state` (`"key"`, a path `"a.b"` / `"a[0].b"` (writes copy only the levels on it; for list items use `byId`), or a `{ get, set }` lens), `children`, `slots`, `context`, `uid` (SYG106; an error in strict mode). `key={…}` is a child's identity (not a prop; else its `id` prop, else its place in the view): a new key re-creates it. Without `state=` a child shares its parent's whole state. A child rendered by tag (`<Stopwatch state="stopwatch" />`) has no `initialState`: its start values go in the parent's (`stopwatch: { ms: 0 }`); its own throws SYG405 and the parent renders its error fallback (a test rendering the child as the root doesn't show it). Test a child alone with `renderComponent(Child, { initialState, context: { lang: 'fr' } })` (the ancestors' context). `uid(name?)` (a view prop, also on reducers' `props`) is a stable per-instance id for `id`/`for`/`aria-*` pairs: `<label for={uid('email')}>`, `<input id={uid('email')} />`.
 - **A sliced child with its own start values**: `Editor.isolatedState = true` lets `<Editor state="draft" />` keep an `initialState`, used only while `state.draft` is `undefined` (an existing slice is kept; SYG425 warns when it lacks keys the `initialState` has). To start it from its `initialState` on every mount: `<Editor state="draft" resetState />`.
 - **CHILD.select(Comp)** emits exactly what the child's `PARENT` function returned, for every instance (Collection items too). Put an id in the payload.
 - **Extract a component without changing markup**: snapshot `t.html()` on the unchanged code first; move the elements verbatim into the child (a component adds no wrapper element and no attributes, so the HTML stays identical); props in, `PARENT` out; the parent drops its old selectors and uses `CHILD.select(Child)`; the snapshot must still match. Recipe: https://sygnal.js.org/guide/parent-child/#recipe-extract-a-component-without-changing-the-markup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sygnal",
-  "version": "6.4.0",
+  "version": "6.6.0",
   "description": "An intuitive framework for building fast and small components or applications based on Cycle.js",
   "main": "./dist/index.cjs.js",
   "types": "./dist/index.d.ts",

package/src/core/cell.ts

@@ -38,24 +38,42 @@ export function localCell(app: {commit(): void}, parent: Cell): Cell {
 }
 
 /**
- * state="key". `owner`: the parent's name when `k` is one of its calculated fields (SYG409:
- * writes ignored; `what` names the writer in the message). `dflt`: an isolated child's
- * initialState, read while the slice is undefined. `has()`: the slice itself is defined (D174).
+ * SPIKE (state paths): a state designator as segments. A plain key is one segment; 'a.b.0' and
+ * 'a[0].b' are paths into nested objects and arrays. No array form: an array `from` / `state` is
+ * the data passed by mistake (SYG410 / SYG412), and ['x', 'y'] would be ambiguous.
+ */
+export const pathOf = (p: string): string[] => p.replace(/\[(\d+)\]/g, '.$1').split('.')
+const getIn = (o: any, ks: any[]) => { for (const k of ks) { if (o == null) return undefined; o = o[k] } return o }
+/** `o` with the value at `ks` replaced; only the levels on the path are copied (a missing level becomes {}) */
+function setIn(o: any, ks: any[], i: number, v: any): any {
+  if (i == ks.length) return v
+  const k = ks[i], cur = o?.[k], n = setIn(cur, ks, i + 1, v)
+  if (n === cur && o != null) return o
+  if (Array.isArray(o)) { const c = o.slice(); c[k] = n; return c }
+  return {...o, [k]: n}
+}
+
+/**
+ * state="key" (SPIKE: or a path, 'a.b' / 'a[0].b'). `owner`: the parent's name when the first
+ * segment is one of its calculated fields (SYG409: writes ignored; `what` names the writer in
+ * the message). `dflt`: an isolated child's initialState, read while the slice is undefined.
+ * `has()`: the slice itself is defined (D174).
  */
 export function keyCell(parent: Cell, k: string, owner?: string | false, dflt?: any, what = 'Sub-component'): Cell & {has(): boolean} {
+  const ks = pathOf(k)
   let lp: any = {}, lv: any
   return {
     get() {
       const p = parent.get()
-      if (p !== lp) { lp = p; lv = p == null ? undefined : p[k]; if (lv === undefined) lv = dflt }
+      if (p !== lp) { lp = p; lv = getIn(p, ks); if (lv === undefined) lv = dflt }
       return lv
     },
     set(v) {
-      if (owner) return warn('SYG409', owner, `${what} tried to update calculated field '${k}'; ignored`, 'Bind it to a non-calculated field')
+      if (owner) return warn('SYG409', owner, `${what} tried to update calculated field '${ks[0]}'; ignored`, 'Bind it to a non-calculated field')
       const p = parent.get()
-      if (p?.[k] !== v) parent.set({...p, [k]: v})
+      if (getIn(p, ks) !== v) parent.set(setIn(p, ks, 0, v))
     },
-    has: () => parent.get()?.[k] !== undefined,
+    has: () => getIn(parent.get(), ks) !== undefined,
   }
 }
 

package/src/core/hooks.ts

@@ -100,6 +100,12 @@ export interface InstanceView {
   readonly state: any
   readonly props: Record<string, any>
   readonly context: Record<string, any>
+  /**
+   * PLAN-10 D530: the context keys the latest render's view read (the D168 read tracking), or null
+   * (no render yet, or no context). Holds '\u0000all' when the view read every key (a spread,
+   * Object.keys). Live: read it, don't keep it
+   */
+  readonly reads: ReadonlySet<string> | null
   readonly isRoot: boolean
   /** 'item' (Collection), 'page' (Switchable), 'child' (tag), 'root' */
   readonly kind: 'root' | 'child' | 'item' | 'page'

package/src/core/hosts/collection.ts

@@ -4,8 +4,9 @@
  *
  * It stands where the `<Collection>` marker was in its owner's template and renders the items
  * inside the owner's render: no stream of its own, no pickCombine.
- * - `of`: a component function (D163: no names). `from`: a state key (SYG409 on a calculated
- *   one), a `{ get, set }` lens (SYG412 without get(); SYG401 for a non-array) or none (the
+ * - `of`: a component function (D163: no names). `from`: a state key or path ('board.cards';
+ *   SYG409 on a calculated first segment; SYG401 when it isn't an array: the dev entry's), a
+ *   `{ get, set }` lens (SYG412 without get(); SYG401 for a non-array) or none (the
  *   owner's state is the array).
  * - Items are keyed by `id`, an id-less item by its raw index (D169); one key -> index map per
  *   array identity serves every item (cell.ts indexer). A duplicate key renders its first element
@@ -30,7 +31,7 @@
  */
 import {hosts, resolvers} from '../registry'
 import {Inst, shallowEq} from '../instance'
-import {Cell, Index, indexer, itemCell, keyCell, keyOf, keyName} from '../cell'
+import {Cell, Index, indexer, itemCell, keyCell, keyOf, keyName, pathOf} from '../cell'
 import {CoreDef, isObj} from '../define'
 import {uidPart, vtStyle} from '../../shared'
 import {viewOf} from '../view'
@@ -89,14 +90,8 @@ function arrayCell(owner: Inst, from: any): Cell | null {
       set: (v) => oc.set(v),
     }
   }
-  if (typeof from == 'string') {
-    const cs = oc.get(), calc = owner.def.calcNames?.has(from)
-    if (isObj(cs) && !(from in cs) && !calc) {
-      const arrays = Object.keys(cs).filter(k => Array.isArray(cs[k]))
-      warn('SYG401', name, `Collection from="${from}" is not in state${arrays.length ? ` (array fields: '${arrays.join("', '")}')` : ''}; it renders nothing until it exists`, 'Set it to an array in initialState')
-    } else if (isObj(cs) && !Array.isArray(cs[from])) warn('SYG401', name, `Collection 'from' field '${from}' is not an array; it renders nothing`, 'Set it to an array in initialState')
-    return keyCell(oc, from, calc && name, undefined, 'Collection')
-  }
+  // a key or a path ('board.cards'); SYG401 for one that isn't an array is the dev entry's (checks/collections.ts)
+  if (typeof from == 'string') return keyCell(oc, from, owner.def.calcNames?.has(pathOf(from)[0]) && name, undefined, 'Collection')
   if (isObj(from) && typeof from.get == 'function') {
     let lp: any = {}, lv: any
     return {

package/src/core/hosts/switchable.ts

@@ -18,7 +18,7 @@
 import {hosts} from '../registry'
 import {resolve} from './collection'
 import {Inst, shallowEq} from '../instance'
-import {Cell, keyCell, lensCell, localCell} from '../cell'
+import {Cell, keyCell, lensCell, localCell, pathOf} from '../cell'
 import {isObj} from '../define'
 import {uidPart} from '../../shared'
 import {error as logError, fail} from '../../extra/diagnostics/legacy'
@@ -61,7 +61,7 @@ export class SwitchableHost {
 
   constructor(public owner: Inst, props: Record<string, any>, children: any[], id: string) {
     check(owner, props)
-    const st = props.state, calc = typeof st == 'string' && owner.def.calcNames?.has(st)
+    const st = props.state, calc = typeof st == 'string' && owner.def.calcNames?.has(pathOf(st)[0])
     this.cell = typeof st == 'string' ? keyCell(owner.cell, st, calc && owner.def.name, undefined, 'Switchable sub-component')
       : st !== undefined ? lensCell(owner.cell, st, owner.def.name, (e) => owner.app.appError(owner, e, 'view'))
       : owner.cell

package/src/core/instance.ts

@@ -20,7 +20,7 @@ import {warn, error as logError, fail} from '../extra/diagnostics/legacy'
 import type {App} from './runtime'
 import {tearDown, INST, SEED} from './teardown'
 import {CoreDef, defOf, isObj} from './define'
-import {Cell, CalcCell, calcCell, keyCell, lensCell, localCell} from './cell'
+import {Cell, CalcCell, calcCell, keyCell, lensCell, localCell, pathOf} from './cell'
 import {hosts, posts, pres, resolvers} from './registry'
 import {handle} from './actions'
 import {viewOf} from './view'
@@ -536,7 +536,7 @@ export class Inst {
         fail('SYG405', def.name, 'Sub-component initialState replaces the state its parent passes in', 'Remove initialState, or set isolatedState = true')
       }
       const dflt = def.isolated ? def.initialState : undefined
-      const cell = typeof st == 'string' ? keyCell(this.cell, st, calcOf?.has(st) && this.def.name, dflt)
+      const cell = typeof st == 'string' ? keyCell(this.cell, st, calcOf?.has(pathOf(st)[0]) && this.def.name, dflt)
         : st !== undefined ? lensCell(this.cell, st, this.def.name, (e) => app.appError(this, e, 'view'), dflt)
         : def.isolated ? localCell(app, this.cell) : this.cell
       const scope = app.scope()

package/src/core/view.ts

@@ -14,6 +14,8 @@ class View implements InstanceView {
   get state() { return this.i.cell.get() }
   get props() { return this.i.props }
   get context() { return this.i.context() }
+  /** D530: the context keys the last render's view read (null: none rendered, or no context) */
+  get reads() { return this.i.keys }
   get isRoot() { return !this.i.parent }
   get kind() { return this.i.kind }
   /** false on a hidden Switchable page and below it */

package/src/cycle/dom/utils.ts

@@ -88,9 +88,11 @@ export function makeInsert(
 }
 
 // G-261: a DOM change Sygnal makes outside a patch (a Transition's leave, a Portal mounted late)
-// re-emits the DOM source of the app whose root contains `el` (makeDOMDriver listens on its root)
+// re-emits the DOM source of the app whose root contains `el` (makeDOMDriver listens on its root).
+// The event comes from the element's own window: jsdom refuses an `Event` from another realm (a
+// Transition's leave timer that fires after a jsdom test environment was torn down)
 export const POKE = 'sygnal-dom';
-export const pokeDOM = (el: any): any => el?.dispatchEvent(new Event(POKE, {bubbles: true}));
+export const pokeDOM = (el: any): any => el?.dispatchEvent(new (el.ownerDocument?.defaultView?.Event || Event)(POKE, {bubbles: true}));
 
 const obj = (o: any) => o !== null && typeof o == 'object' && !Array.isArray(o);
 /**

package/src/devtools.d.ts

@@ -168,3 +168,16 @@ export declare function installMcpBridge(
   hot: { on(event: string, cb: (data: any) => void): void; send(event: string, data?: any): void } | undefined,
   options?: McpBridgeOptions
 ): void
+
+// ── PLAN-10 P-2: the app side of sygnal/vite's graph page (/__sygnal/graph) ──
+
+export interface GraphBridgeOptions {
+  /** The BroadcastChannel the graph page listens on (default 'sygnal:graph') */
+  channel?: string
+}
+/**
+ * Answer the dev server's graph page ("Live data": instances, action flashes, state) over a
+ * same-origin BroadcastChannel. sygnal/vite calls it in dev while the graph route is on (the
+ * default; `graph: false` turns it off); you don't call it yourself.
+ */
+export declare function installGraphBridge(options?: GraphBridgeOptions): void

package/src/devtools.ts

@@ -35,3 +35,6 @@ export function copyAsTest(target?: any, options?: CopyAsTestOptions): string {
 
 // PLAN-6 E-1: the page side of sygnal/vite's dev MCP endpoint (`sygnal({ mcp: true })`)
 export {installMcpBridge} from './extra/devMcp'
+
+// PLAN-10 P-2 (D544): the app side of the graph page's "Live data" (sygnal/vite's /__sygnal/graph)
+export {installGraphBridge} from './extra/devGraph'

package/src/extra/devGraph.ts

@@ -0,0 +1,111 @@
+/**
+ * PLAN-10 P-2 (D544): the app side of the graph page's "Live data" (sygnal/vite serves the page at
+ * `/__sygnal/graph` in dev, W-2 / D543). Dev only: it is part of the 'sygnal/devtools' entry, and
+ * sygnal/vite's 'virtual:sygnal/graph' module (served by the dev server, never in a build) calls
+ * installGraphBridge().
+ *
+ * The page is served by the dev server on the app's own origin, so the two talk over a
+ * BroadcastChannel ('sygnal:graph'): no server round trip, no HMR traffic, nothing a page on
+ * another origin can join. Every message carries `v: 1`.
+ *
+ *   page → apps  { type: 'who', watch? }          every 2 s while the page is open; `watch` names
+ *                                                 the tab the page follows (it keeps that tab
+ *                                                 sending for 6 s)
+ *   app  → page  { type: 'here', tab, url, title, at, ok }   the answer, and on load / focus
+ *                                                 (`at`: when the tab was last loaded or focused;
+ *                                                 `ok`: inspect() is there, i.e. diagnostics on)
+ *   app  → page  { type: 'graph', tab, graph }    inspect({ actions: 200 }) of the page's apps, JSON
+ *                                                 safe: when it starts being watched, then 150 ms
+ *                                                 after the last action or component change
+ *   app  → page  { type: 'action', tab, record }  { type, instance, component } at once (a flash)
+ *   page → app   { type: 'get-state', tab, req, id }   an instance's state
+ *   app  → page  { type: 'state', tab, req, id, value?, error? }
+ *   app  → page  { type: 'bye', tab }             the tab is going away (pagehide)
+ *
+ * State values go through the DevTools preview (JSON safe, as the MCP tools send them). The static
+ * keys the page joins on are on the component functions (sygnal/vite's dev transform) and come out
+ * of inspect() as `key`.
+ */
+import {getDevTools} from './devtools'
+import {onAction} from './devtoolsActions'
+import {addLayer} from './devtoolsNext'
+import {pageTools, trackApps} from './devMcp'
+
+export const GRAPH_CHANNEL = 'sygnal:graph'
+const WATCH_MS = 6000
+const SETTLE_MS = 150
+
+export interface GraphBridgeOptions {
+  /** the BroadcastChannel name (default 'sygnal:graph') */
+  channel?: string
+}
+
+let installed = false
+
+/** Connect this page to the graph page's "Live data" (sygnal/vite calls it in dev). Once per page. */
+export function installGraphBridge(options: GraphBridgeOptions = {}): void {
+  const g: any = globalThis
+  if (installed || typeof g.BroadcastChannel != 'function' || !g.window) return
+  installed = true
+  trackApps()
+  const bc = new g.BroadcastChannel(options.channel || GRAPH_CHANNEL)
+  const tab = Math.random().toString(36).slice(2, 10) + Date.now().toString(36)
+  const tools = pageTools({})
+  let at = Date.now()
+  let watchedUntil = 0
+  let timer: any = 0
+
+  const inspect = () => {
+    const f = g.__SYGNAL_DIAGNOSTICS__?.inspect || (getDevTools() as any)?.inspect
+    return typeof f == 'function' ? f : null
+  }
+  const post = (m: any) => { try { bc.postMessage({v: 1, tab, ...m}) } catch (_) { /* closed */ } }
+  const here = () => post({type: 'here', url: String(g.location?.href || ''), title: String(g.document?.title || ''), at, ok: !!inspect()})
+  const watched = () => Date.now() < watchedUntil
+
+  const sendGraph = () => {
+    clearTimeout(timer)
+    timer = 0
+    const f = inspect()
+    if (!watched() || !f) return
+    let graph: any
+    try { graph = JSON.parse(JSON.stringify(f({actions: 200}))) } catch (_) { return }
+    post({type: 'graph', graph})
+  }
+  const settle = () => {
+    if (!watched()) return
+    clearTimeout(timer)
+    timer = setTimeout(sendGraph, SETTLE_MS)
+  }
+  const watch = () => {
+    const was = watched()
+    watchedUntil = Date.now() + WATCH_MS
+    if (!was) sendGraph()
+  }
+
+  bc.onmessage = (e: any) => {
+    const m = e && e.data
+    if (!m || m.v !== 1 || typeof m.type != 'string') return
+    if (m.type == 'who') {
+      if (m.watch === tab) watch()
+      here()
+    } else if (m.type == 'get-state' && m.tab === tab) {
+      let value: any, error: string | undefined
+      try { value = (tools.get_state({component: String(m.id)}, m.req) as any).state } catch (err: any) { error = String(err?.message || err) }
+      post({type: 'state', req: m.req, id: m.id, ...(error ? {error} : {value})})
+    }
+  }
+
+  onAction((a: any, kind) => {
+    if (!watched()) return
+    if (kind == 'add' && a) post({type: 'action', record: {type: a.type, instance: String(a.instance), component: a.component}})
+    settle()
+  })
+  addLayer(() => ({onCreate: settle, onDispose: settle}))
+
+  const seen = () => { at = Date.now(); here() }
+  g.addEventListener?.('focus', seen)
+  g.document?.addEventListener?.('visibilitychange', () => { if (g.document.visibilityState == 'visible') seen() })
+  g.addEventListener?.('pagehide', () => post({type: 'bye'}))
+  here()
+}

package/src/extra/devMcp.ts

@@ -91,7 +91,7 @@ function appLayer(api: any) {
   }
 }
 
-function trackApps() {
+export function trackApps(): void {
   if (tracking) return
   tracking = true
   addLayer(appLayer)

package/src/extra/devtools.ts

@@ -146,6 +146,24 @@ export class SygnalDevTools {
       case 'GET_STATE':
         this._sendComponentState(msg.payload.componentId);
         break;
+      case 'GET_GRAPH':
+        this._post('GRAPH', this._graph(msg.payload));
+        break;
+    }
+  }
+
+  /**
+   * PLAN-10 P-1: the runtime app graph for the panel's App graph view: inspect() with the recent
+   * actions, JSON-safe. inspect() is on this object only when 'sygnal/diagnostics' is loaded
+   * (sygnal/vite loads it in dev); without it the panel shows why.
+   */
+  _graph(opts?: {actions?: number}): {graph: any; reason?: string; message?: string} {
+    const inspect = (this as any).inspect;
+    if (typeof inspect !== 'function') return {graph: null, reason: 'no-diagnostics'};
+    try {
+      return {graph: JSON.parse(JSON.stringify(inspect({actions: opts?.actions ?? 200})))};
+    } catch (e: any) {
+      return {graph: null, reason: 'error', message: String(e?.message ?? e)};
     }
   }
 

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

@@ -1,18 +1,13 @@
 /**
- * SYG401 — <Collection> has no `from` and the whole state is not an array (warn).
- * A defined `from` is checked by the core (D22).
+ * SYG401 — a <Collection> / <VirtualCollection> whose items aren't an array (warn):
+ *   - no `from`, and the whole state is not an array
+ *   - `from` a key or a path ('board.cards') that isn't in state, or isn't an array there
+ * A lens `from` (a getter that returns a non-array, SYG401) and an invalid `from` (SYG412) are
+ * the core's. The string `from` checks moved here from the core in 6.5.0 (production apps don't
+ * print them; dev and tests do: sygnal/vite and renderComponent load this entry).
  *
- * Reported through diagnostics in addition to the existing console output.
- *
- * Mechanism: the core has no hook at Collection instantiation, and the
- * Collection marker vnode is gone by the time onRender sees the tree. So, at
- * onModel (construction time, before the first render), this check wraps the
- * component INSTANCE's instantiateCollection method (an own property that
- * shadows the prototype method; Component calls `this.instantiateCollection`
- * for every new Collection). The wrapper inspects the marker's props and the
- * component's current state, then always calls the original. This only
- * happens when the dev-only 'sygnal/diagnostics' entry is loaded and
- * diagnostics are on. Reported once per component name and `from` value.
+ * Called by the dev layer (next.ts onHostProps) with the owner's facade and the host's props.
+ * Reported once per component name and `from` value.
  */
 import type {DiagnosticCheck} from '../index'
 import {reportSafely, once, nameOf, isPlainObject} from './shared'
@@ -30,25 +25,36 @@ export function checkCollection(component: any, el: any): void {
   let state = component.currentState
   try { if (typeof component.addCalculated === 'function') state = component.addCalculated(state) } catch (_) {}
 
-  let problem: string | undefined
-  let fix = `Pass the name of an array field in ${name}'s state, e.g. <Collection of={${ofName}} from="items" />, and initialize that field to [] in initialState`
-  // Every defined `from` (string field, lens object, or an invalid value) is reported by
-  // the core itself (SYG401/SYG412, retrofitted in 1E) in every diagnostics mode (D22), so
-  // this check only covers a missing `from`.
+  if (typeof from === 'string') return checkFrom(component, name, from, ofName, state)
+  // a lens or an invalid value: the core's (SYG401 / SYG412)
   if (from !== undefined) return
-  if (!Array.isArray(state) && !(state && Array.isArray(state.value))) {
-    problem = `has no 'from' prop, so it uses ${name}'s whole state, which is ${describe(state)}, not an array`
-  }
-
-  if (!problem || !once(`SYG401:${name}:undefined`)) return
+  if (Array.isArray(state) || (state && Array.isArray(state.value))) return
+  if (!once(`SYG401:${name}:undefined`)) return
   reportSafely('SYG401', {
     component,
-    message: `<Collection of={${ofName}}> ${problem}, so it renders no items`,
-    fix,
+    message: `<Collection of={${ofName}}> has no 'from' prop, so it uses ${name}'s whole state, which is ${describe(state)}, not an array, so it renders no items`,
+    fix: `Pass the name of an array field in ${name}'s state, e.g. <Collection of={${ofName}} from="items" />, and initialize that field to [] in initialState`,
     data: {from: 'undefined', of: ofName},
   })
 }
 
+/** `from` a key or a path ('board.cards', 'boards[0].cards'), as the core reads it (cell.ts pathOf) */
+function checkFrom(component: any, name: string, from: string, ofName: string, state: any): void {
+  const ks = from.replace(/\[(\d+)\]/g, '.$1').split('.')
+  const calc = component._calculatedFieldNames
+  if (calc?.has?.(ks[0])) return
+  const at = ks.slice(0, -1).reduce((o: any, k: string) => (o == null ? o : o[k]), state), last = ks[ks.length - 1]
+  if (!isPlainObject(at) && !Array.isArray(at)) return // a level still missing: renders once it appears (D178)
+  let message: string
+  if (!(last in at)) {
+    const arrays = Object.keys(at).filter(k => Array.isArray(at[k]))
+    message = `Collection from="${from}" is not in state${arrays.length ? ` (array fields: '${arrays.join("', '")}')` : ''}; it renders nothing until it exists`
+  } else if (!Array.isArray(at[last])) message = `Collection 'from' field '${from}' is not an array; it renders nothing`
+  else return
+  if (!once(`SYG401:${name}:${from}`)) return
+  reportSafely('SYG401', {component, message, fix: 'Set it to an array in initialState', data: {from, of: ofName}})
+}
+
 const WRAPPED = '__sygnalDiagWrapped'
 
 export const collectionsCheck: DiagnosticCheck = {

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

@@ -110,7 +110,7 @@ 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, InspectRelatedLocation, InspectFix, InspectTextEdit, InspectOptions, InspectRecentAction} from './public'
+export type {InspectResource, InspectCacheEntry, InspectGraph, InspectComponent, InspectAction, InspectActionTrigger, InspectChild, InspectSelector, InspectControl, InspectDiagnostic, InspectRelatedLocation, InspectFix, InspectTextEdit, InspectOptions, InspectRecentAction, InspectLocation, InspectChildSelect} from './public'
 export {listCodes, getCodeInfo} from '../codes'
 export type {DiagnosticCodeInfo} from '../codes'
 

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

@@ -17,6 +17,15 @@
  *   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-10 D522, read from the instance view at inspect() time, no core change) viewOnly (the
+ *               component function has no statics), entry (an app's root), app (which run() the
+ *               instance belongs to), shown: false (a hidden Switchable page and below), the
+ *               instance ids on children entries and in events[type].emitterIds / selectorIds.
+ *               D530: contextConsumes from InstanceView.reads (the keys the latest render read);
+ *               diagnostics keep their `timestamp`.
+ *               `key` (PLAN-10 P-2, D544): the static 'file#name' (D521) that sygnal/vite stamps on
+ *               the component function in dev (a non-enumerable `__sygnalKey`), when it is there;
+ *               the runtime itself has no source file
  *   (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
@@ -205,6 +214,8 @@ const slim = (d: any): InspectDiagnostic => {
   if (d.component) out.component = d.component
   if (d.fix) out.fix = d.fix
   if (d.docsUrl) out.docsUrl = d.docsUrl
+  // PLAN-10 P-1: when it was reported (runtime diagnostics are reported once per process)
+  if (typeof d.timestamp === 'number') out.timestamp = d.timestamp
   if (d.data !== undefined) {
     // keep it JSON-safe (data can hold errors, vnodes, ...)
     try { out.data = JSON.parse(JSON.stringify(d.data)) } catch (_) { /* drop */ }
@@ -316,12 +327,55 @@ function childrenOf(r: Rec, all: Rec[]): InspectChild[] {
     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})
+    if (entry) entry.count = entry.ids!.push(c.id)
+    else out.set(key, {name: c.name, via: via[c.kind], count: 1, ids: [c.id]})
   }
   return [...out.values()]
 }
 
+/** the statics sygnal-check reads (its STATIC_PROPS): a component function with none is view-only */
+const STATICS = ['intent', 'model', 'initialState', 'isolatedState', 'context', 'calculated', 'connections', 'resources', 'route', 'head', 'uses', 'timers', 'persist', 'viewTransitions', 'browser', 'agent']
+
+/** PLAN-10 D522: no statics and nothing the core added (renderComponent's test intent, a behavior's model) */
+function isViewOnly(c: any): boolean {
+  const def = c && c.__next && c.__next.def
+  if (!def || def.intent || (def.handlers && def.handlers.size) || def.initialState !== undefined) return false
+  const fn = def.view
+  return !!fn && STATICS.every(k => fn[k] === undefined)
+}
+
+/** PLAN-10 P-2 (D544): the static key sygnal/vite's dev transform stamped on the component function */
+function stampedKey(c: any): string | undefined {
+  const fn = c && c.__next && c.__next.def && c.__next.def.view
+  const k = fn && fn.__sygnalKey
+  return typeof k === 'string' ? k : undefined
+}
+
+/** PLAN-10 D530: the context keys the instance's latest render read (InstanceView.reads); every key when it read them all */
+function contextReadsOf(c: any): string[] {
+  const v = c && c.__next
+  const reads: ReadonlySet<string> | null | undefined = v && v.reads
+  if (!reads) return []
+  const out = [...reads].filter(k => k !== '\u0000all')
+  if (reads.has('\u0000all')) { try { for (const k of Object.keys(v.context || {})) if (!out.includes(k)) out.push(k) } catch (_) { /* no context */ } }
+  return out
+}
+
+/** PLAN-10 D522: the app (run()) of each instance: the index of its root among the live roots, oldest first */
+function appsOf(all: Rec[]): Map<Rec, number> {
+  const byId = new Map(all.map(r => [r.id, r]))
+  const roots = all.filter(r => r.parentId === null).sort((a, b) => Number(a.id) - Number(b.id))
+  const index = new Map(roots.map((r, i) => [r, i]))
+  const out = new Map<Rec, number>()
+  for (const r of all) {
+    let top: Rec | undefined = r
+    for (let n = 0; top && top.parentId !== null && n < 10000; n++) top = byId.get(top.parentId)
+    const i = top && index.get(top)
+    if (i !== undefined) out.set(r, i)
+  }
+  return out
+}
+
 /** 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
@@ -340,22 +394,29 @@ export function inspect(options: InspectOptions = {}): InspectGraph {
   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 apps = appsOf(all)
 
   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)
+    const key = stampedKey(c)
     return {
       name: r.name,
       id: r.id,
+      ...(key ? {key} : {}),
       parentId: r.parentId,
       kind: r.kind,
+      ...(isViewOnly(c) ? {viewOnly: true as const} : {}),
+      ...(r.parentId === null ? {entry: true as const} : {}),
+      ...(apps.has(r) ? {app: apps.get(r)} : {}),
+      ...(c && c.__next && c.__next.shown === false ? {shown: false as const} : {}),
       actions: actionsOf(r),
       stateKeys: stateKeysOf(c, calculated),
       calculated,
       contextProvides: c && isPlainObject(c.context) ? Object.keys(c.context) : [],
-      contextConsumes: null,
+      contextConsumes: contextReadsOf(c),
       eventsEmitted: [...r.eventsEmitted],
       eventsSelected: [...r.eventsSelected],
       children: childrenOf(r, all),
@@ -368,11 +429,12 @@ export function inspect(options: InspectOptions = {}): InspectGraph {
 
   const cache = cacheOf(recs) || {}
   const events: InspectGraph['events'] = {}
-  const ev = (type: string) => events[type] || (events[type] = {emitters: [], selectors: []})
+  // names once each (as before); PLAN-10 D522: every instance's id in emitterIds / selectorIds
+  const ev = (type: string) => events[type] || (events[type] = {emitters: [], selectors: [], emitterIds: [], selectorIds: []})
   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)
+    for (const t of c.eventsEmitted) { const e = ev(t); add(e.emitters, c.name); e.emitterIds!.push(c.id) }
+    for (const t of c.eventsSelected) { const e = ev(t); add(e.selectors, c.name); e.selectorIds!.push(c.id) }
   }
   // 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)