sygnal 5.3.7 → 6.0.0

package/src/extra/devtoolsActions.ts

@@ -0,0 +1,379 @@
+/**
+ * PLAN-4 3-E (GS-10): the DevTools action log, in the dev-only 'sygnal/devtools' entry (0 B in
+ * apps: nothing in the core calls it).
+ *
+ * It records every action of every component instance through 2-C's recorder
+ * (./diagnostics/checks/actionLog: actionHooks), a hook layer every app reads from the core's
+ * diagnostics bridge (globalThis.__SYGNAL_DIAGNOSTICS__.layers), so it records with diagnostics
+ * off too. On top of 2-C's record it keeps:
+ *   seq, at        a sequence number, ms since the session started
+ *   parent         the parent instance id (null: a root)
+ *   before, after  the instance's state around the action's STATE reducer (onReducer), when it
+ *                  changed the state (`after` without calculated fields)
+ *   replySink      for a reply action (and RESOURCE): the source that delivered it, and
+ *   replyKind      'fetch' when that source is makeFetchDriver's (renderComponent fakes it)
+ *
+ * A session runs from the recorder's start (or the last clearActions()) to now. getSession()
+ * turns it into a SessionRecording for one instance (./copyAsTest generates the test).
+ */
+import {clockNow, actionHooks} from './diagnostics/checks/actionLog'
+import {addLayer, devFacade} from './devtoolsNext'
+import type {ActionListener, ActionRecord, ActionCause} from './diagnostics/checks/actionLog'
+
+export type {ActionCause}
+
+export interface DevtoolsAction {
+  seq: number
+  type: string
+  data: any
+  component: string
+  instance: string
+  parent: string | null
+  /** live: fills in as the action's reducers run */
+  sinks: string[]
+  cause: ActionCause
+  /** ms since the session started */
+  at: number
+  before?: any
+  after?: any
+  replySink?: string
+  replyKind?: 'fetch' | 'other'
+  /** an intent action whose data is the instance's own state (an intent over STATE.stream) */
+  echo?: true
+}
+
+export interface SessionAction {
+  type: string
+  data: any
+  cause: ActionCause
+  sinks: string[]
+  at: number
+  replySink?: string
+  replyKind?: 'fetch' | 'other'
+  echo?: true
+}
+
+/** One instance's session: what copyAsTest() needs (plain data, raw action data) */
+export interface SessionRecording {
+  version: 1
+  component: string
+  instance: string
+  /** the state when the session started for this instance (undefined: unknown) */
+  initialState?: any
+  /** the component's own `initialState` (renderComponent's default) */
+  definitionInitialState?: any
+  finalState: any
+  /** the action names the component can be sent (model keys, behavior actions); undefined: any */
+  actionNames?: string[]
+  /** source names beyond DOM / EVENTS / STATE / LOG / CHILD / PARENT / READY */
+  drivers: string[]
+  /** those of `drivers` renderComponent fakes (makeFetchDriver sources: t.respond / t.fail) */
+  fakeable: string[]
+  /** the instance's own actions, in order */
+  actions: SessionAction[]
+  /** state changes in descendant instances a root-level replay can't reproduce */
+  foreign: Array<{type: string; component: string; instance: string; cause: ActionCause}>
+  /** the session lost its oldest actions (more than the recorder keeps) */
+  truncated?: boolean
+}
+
+export interface ActionFilter {
+  component?: string
+  instance?: string | number
+  type?: string | RegExp
+  cause?: ActionCause | ActionCause[]
+}
+
+interface Inst {
+  c: any
+  id: string
+  name: string
+  parent: string | null
+  stateName: string
+  /** created after the session started */
+  inSession: boolean
+  hasInitial: boolean
+  initial?: any
+  disposed: boolean
+}
+
+const MAX = 5000
+const STANDARD = /^(DOM|EVENTS|LOG|CHILD|PARENT|READY|props\$|children\$|dispose\$)$/
+
+let actions: DevtoolsAction[] = []
+let seq = 0
+let epoch = clockNow()
+let truncated = false
+let created = 0
+const insts = new Map<string, Inst>()
+const byRec = new WeakMap<ActionRecord, DevtoolsAction>()
+/** instance -> the action whose STATE reducer just produced a value (its onReducer follows) */
+const pendingState = new WeakMap<any, DevtoolsAction>()
+const subscribers = new Set<(a: DevtoolsAction | null, kind: 'add' | 'update' | 'reset') => void>()
+
+const notify = (a: DevtoolsAction | null, kind: 'add' | 'update' | 'reset') => {
+  for (const s of subscribers) try { s(a, kind) } catch (_) { /* a subscriber never breaks the app */ }
+}
+
+const idOf = (c: any) => String(c && c._componentNumber)
+
+function ensure(c: any): Inst {
+  const id = idOf(c)
+  let i = insts.get(id)
+  if (!i || i.c !== c) {
+    const p = c && c.__next && c.__next.parentId
+    i = {c, id, name: c && c.name, parent: typeof p == 'number' ? String(p) : null, stateName: (c && c.stateSourceName) || 'STATE',
+      inSession: true, hasInitial: false, disposed: false}
+    ;(i as any).order = ++created
+    insts.set(id, i)
+  }
+  return i
+}
+
+function clean(c: any, s: any): any {
+  try { return typeof c.cleanupCalculated == 'function' ? c.cleanupCalculated(s) : s } catch (_) { return s }
+}
+
+const listener: ActionListener = {
+  action(r, c) {
+    const info = ensure(c)
+    // the instance's state when its session started: INITIALIZE's data (its initial state), else
+    // the state it had at its first action
+    if (r.type == 'INITIALIZE' && info.inSession) { info.initial = r.data; info.hasInitial = true }
+    else if (!info.hasInitial) { info.initial = c.currentState; info.hasInitial = true }
+    const a: DevtoolsAction = {seq: ++seq, type: r.type, data: r.data, component: r.component, instance: r.instance,
+      parent: info.parent, sinks: r.sinks, cause: r.cause, at: r.time - epoch}
+    const slot = (r as any).source
+    if (slot !== undefined && (r.cause == 'reply' || r.type == 'RESOURCE')) {
+      a.replySink = slot
+      a.replyKind = c.sources && c.sources[slot] && c.sources[slot].__sygnalStatic === 'resources' ? 'fetch' : 'other'
+    }
+    if (r.cause == 'intent' && isStateEcho(r.data, c.currentState)) a.echo = true
+    byRec.set(r, a)
+    actions.push(a)
+    if (actions.length > MAX) { actions.shift(); truncated = true }
+    notify(a, 'add')
+  },
+  sink(r, sink) {
+    const a = byRec.get(r)
+    if (!a) return
+    const info = insts.get(r.instance)
+    if (info && info.c && sink == info.stateName) pendingState.set(info.c, a)
+    notify(a, 'update')
+  },
+}
+
+function onReducer(c: any, name: string, prev: any, next: any): void {
+  const a = pendingState.get(c)
+  if (!a || a.type !== name || 'after' in a) return
+  pendingState.delete(c)
+  a.before = prev
+  a.after = clean(c, next)
+  notify(a, 'update')
+}
+
+function onDispose(c: any): void {
+  const i = insts.get(idOf(c))
+  if (i && i.c === c) { i.disposed = true; i.c = undefined }
+}
+
+let unregister: (() => void) | undefined
+
+/** PLAN-4.6 R4: the same recorder on the core, from its hooks (per app; a facade per instance) */
+function nextLayer(api: any): any {
+  const L: ActionListener = {
+    action: (r, iv) => listener.action(r, devFacade(iv, api)),
+    sink: (r, sink, reducer) => listener.sink!(r, sink, reducer),
+  }
+  const log = actionHooks(L)
+  return {
+    ...log,
+    onCreate(iv: any) { ensure(devFacade(iv, api)); log.onCreate(iv) },
+    onReducer(iv: any, name: string, prev: any, next: any) { onReducer(devFacade(iv, api), name, prev, next) },
+    onDispose(iv: any) { onDispose(devFacade(iv, api)) },
+  }
+}
+
+/**
+ * Start recording actions (idempotent; 'sygnal/devtools' does it on import in a browser). Only
+ * components created afterwards are recorded. Returns a function that stops recording.
+ */
+export function recordActions(): () => void {
+  if (!unregister) {
+    const core = (globalThis as any).__SYGNAL_DIAGNOSTICS__
+    if (!core) return () => {}
+    unregister = addLayer(nextLayer)
+  }
+  return stopRecording
+}
+
+function stopRecording(): void {
+  if (unregister) { unregister(); unregister = undefined }
+}
+
+export const isRecording = (): boolean => !!unregister
+
+/** Start a new session: forget the recorded actions; each live instance's state is its new initial state. */
+export function clearActions(): void {
+  actions = []
+  epoch = clockNow()
+  truncated = false
+  for (const [id, i] of insts) {
+    if (i.disposed) { insts.delete(id); continue }
+    i.inSession = false
+    i.initial = i.c && i.c.currentState
+    i.hasInitial = true
+  }
+  notify(null, 'reset')
+}
+
+const matches = (a: DevtoolsAction, f: ActionFilter) =>
+  (f.component === undefined || a.component === f.component) &&
+  (f.instance === undefined || a.instance === String(f.instance)) &&
+  (f.type === undefined || (typeof f.type == 'string' ? a.type === f.type : f.type.test(a.type))) &&
+  (f.cause === undefined || ([] as ActionCause[]).concat(f.cause).includes(a.cause))
+
+/** The session's actions (oldest first), optionally filtered by component, instance, type or cause. */
+export function getActions(filter?: ActionFilter): DevtoolsAction[] {
+  return filter ? actions.filter(a => matches(a, filter)) : actions.slice()
+}
+
+/** Subscribe to the log: (action, 'add' | 'update') and (null, 'reset'). Returns unsubscribe. */
+export function onAction(fn: (a: DevtoolsAction | null, kind: 'add' | 'update' | 'reset') => void): () => void {
+  subscribers.add(fn)
+  return () => { subscribers.delete(fn) }
+}
+
+/** the live instances, newest first */
+const live = () => [...insts.values()].filter(i => !i.disposed && i.c).sort((a, b) => (b as any).order - (a as any).order)
+
+/**
+ * The instance a session target names: undefined (the newest live root), an instance id, a
+ * component function (its newest live instance) or run()'s result (its root, by DOM source).
+ */
+export function resolveInstance(target?: any): Inst | undefined {
+  const all = live()
+  if (target === undefined || target === null) return all.find(i => i.parent === null)
+  if (typeof target == 'string' || typeof target == 'number') return insts.get(String(target))
+  if (typeof target == 'function') return all.find(i => i.c.view === target)
+  if (typeof target == 'object') {
+    const s = target.sources
+    if (s && typeof s == 'object') {
+      return all.find(i => i.parent === null && Object.keys(s).some(k => k != 'STATE' && s[k] && i.c.sources && i.c.sources[k] === s[k])) ||
+        all.find(i => i.parent === null)
+    }
+  }
+  return undefined
+}
+
+function descendants(id: string): Set<string> {
+  const out = new Set<string>()
+  let grew = true
+  while (grew) {
+    grew = false
+    for (const i of insts.values()) if (i.parent !== null && (i.parent === id || out.has(i.parent)) && !out.has(i.id)) { out.add(i.id); grew = true }
+  }
+  // instances already pruned: their actions still name their parent
+  for (const a of actions) if (a.parent !== null && (a.parent === id || out.has(a.parent))) out.add(a.instance)
+  return out
+}
+
+const REPLAYED = new Set<ActionCause>(['intent', 'simulateAction', 'behavior', 'reply'])
+
+/**
+ * The session of one instance (see resolveInstance for `target`) as plain data: its initial
+ * and final state, its own actions, and the state changes of its descendants (a replay at this
+ * instance can't reproduce them).
+ */
+export function getSession(target?: any): SessionRecording {
+  const info = resolveInstance(target)
+  if (!info) throw new Error('[Sygnal DevTools] getSession: no live component instance matches' + (target === undefined ? ' (no root recorded: import sygnal/devtools before run())' : ''))
+  const c = info.c
+  const desc = descendants(info.id)
+  const stateNameOf = (id: string) => insts.get(id)?.stateName || 'STATE'
+  const model = c.model && typeof c.model == 'object' ? Object.keys(c.model).map(k => k.split('|')[0].trim()) : undefined
+  const behaviors = c._behaviorActions && typeof c._behaviorActions == 'object' ? Object.keys(c._behaviorActions) : []
+  const sources = c.sources || {}
+  const drivers = (c.sourceNames || Object.keys(sources)).filter((n: string) =>
+    !STANDARD.test(n) && n !== info.stateName && n != 'STATE' && n != 'state' && !n.startsWith('__'))
+  return {
+    version: 1,
+    component: info.name,
+    instance: info.id,
+    initialState: info.hasInitial ? info.initial : undefined,
+    definitionInitialState: c.view ? c.view.initialState : undefined,
+    finalState: c.currentState,
+    actionNames: model ? [...model, ...behaviors] : undefined,
+    drivers,
+    fakeable: drivers.filter((n: string) => sources[n] && sources[n].__sygnalStatic === 'resources'),
+    actions: actions.filter(a => a.instance === info.id).map(a => ({
+      type: a.type, data: a.data, cause: a.cause, sinks: [...a.sinks], at: a.at,
+      ...(a.replySink !== undefined ? {replySink: a.replySink, replyKind: a.replyKind} : {}),
+      ...(a.echo ? {echo: true as const} : {}),
+    })),
+    foreign: actions.filter(a => desc.has(a.instance) && REPLAYED.has(a.cause) && a.sinks.includes(stateNameOf(a.instance)))
+      .map(a => ({type: a.type, component: a.component, instance: a.instance, cause: a.cause})),
+    ...(truncated ? {truncated: true} : {}),
+  }
+}
+
+/** A JSON-safe copy for the panel: DOM elements and events become short descriptions. */
+export function preview(v: any): any {
+  if (v === undefined) return undefined
+  const seen = new WeakSet<object>()
+  try {
+    return JSON.parse(JSON.stringify(v, (_k, x) => {
+      if (typeof x == 'function') return `[Function ${x.name || 'anonymous'}]`
+      if (typeof x == 'symbol') return String(x)
+      if (typeof x == 'bigint') return `${x}n`
+      if (x && typeof x == 'object') {
+        if (isElement(x)) return describeElement(x)
+        if (isEvent(x)) return `[${x.constructor && x.constructor.name || 'Event'} ${x.type}]`
+        if (x instanceof Map) return {'[Map]': [...x.entries()]}
+        if (x instanceof Set) return {'[Set]': [...x.values()]}
+        if (seen.has(x)) return '[Circular]'
+        seen.add(x)
+      }
+      return x
+    }))
+  } catch (_) {
+    return '[unserializable]'
+  }
+}
+
+const isPlain = (x: any) => !!x && typeof x == 'object' && (Object.getPrototypeOf(x) === Object.prototype || Object.getPrototypeOf(x) === null)
+
+export function deepEqual(a: any, b: any): boolean {
+  if (Object.is(a, b)) return true
+  if (!a || !b || typeof a != 'object' || typeof b != 'object') return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  const ka = Object.keys(a).filter(k => a[k] !== undefined), kb = Object.keys(b).filter(k => b[k] !== undefined)
+  return ka.length == kb.length && ka.every(k => deepEqual(a[k], b[k]))
+}
+
+/**
+ * The data is the state itself (STATE.stream in the intent; calculated fields may be added): the
+ * replay sends it again by itself, so it isn't replayed.
+ */
+function isStateEcho(data: any, state: any): boolean {
+  if (!isPlain(data) || !isPlain(state)) return false
+  const keys = Object.keys(state)
+  return keys.length > 0 && (data === state || keys.every(k => deepEqual(data[k], state[k])))
+}
+
+export const isElement = (x: any): boolean => !!x && typeof x == 'object' && x.nodeType === 1 && typeof x.tagName == 'string'
+export const isEvent = (x: any): boolean => !!x && typeof x == 'object' && typeof x.type == 'string' && typeof x.preventDefault == 'function' && 'target' in x
+
+const describeElement = (el: any) => {
+  const cls = typeof el.className == 'string' && el.className.trim() ? '.' + el.className.trim().split(/\s+/).join('.') : ''
+  return `<${String(el.tagName).toLowerCase()}${el.id ? '#' + el.id : ''}${cls}>`
+}
+
+/** test seam: forget everything (sessions, instances); recording stays as it is */
+export function _resetActionLog(): void {
+  actions = []
+  seq = 0
+  epoch = clockNow()
+  truncated = false
+  insts.clear()
+}

package/src/extra/devtoolsHook.ts

@@ -0,0 +1,9 @@
+import type {SygnalDevTools} from './devtools';
+
+/**
+ * The installed DevTools bridge, or undefined (D77: the bridge itself lives in the
+ * 'sygnal/devtools' dev entry, which sygnal/vite injects in dev).
+ */
+export function getDevTools(): SygnalDevTools | undefined {
+  return (globalThis as any).__SYGNAL_DEVTOOLS__;
+}

package/src/extra/devtoolsNext.ts

@@ -0,0 +1,83 @@
+/**
+ * PLAN-4.6 R4: 'sygnal/devtools' on the next component core (04 §3.5).
+ *
+ * The core calls no `window.__SYGNAL_DEVTOOLS__` method itself: each app reads the dev
+ * entries' hook layers once (`__SYGNAL_DIAGNOSTICS__.layers`), and this file's layer maps the
+ * hooks onto the bridge's existing methods (onComponentCreated, onStateChanged, ...). The bridge
+ * keeps a facade per instance with the fields it reads from today's instances (currentState,
+ * model, sourceNames, ...); time travel and the debug toggle go through the app's runtime API
+ * (`setState`, `setDebug`) instead of `sinks.STATE.shamefullySendNext` and `instance._debug`.
+ */
+const facades = new WeakMap<object, any>()
+
+/** the bridge's view of a core instance (an InstanceView + its app's runtime API) */
+export function devFacade(iv: any, api: any): any {
+  let f = facades.get(iv)
+  if (f) return f
+  f = {
+    __next: iv,
+    __api: api,
+    get _componentNumber() { return iv.id },
+    get name() { return iv.name },
+    get isSubComponent() { return !iv.isRoot },
+    get parentId() { return iv.parentId },
+    get view() { return iv.def.view },
+    get model() {
+      const m: Record<string, any> = {}
+      iv.def.handlers.forEach((hs: any[], a: string) => { const e: any = m[a] = {}; for (const [s, fn] of hs) e[s] = fn })
+      return m
+    },
+    get intent() { return iv.def.intent },
+    get context() { return iv.def.view.context },
+    get calculated() { return iv.def.view.calculated },
+    get _behaviorActions() { return iv.def.behaviorActions },
+    get currentState() { return iv.state },
+    get currentContext() { return iv.context },
+    get currentProps() { return iv.props },
+    get sources() { return iv.sources },
+    get sourceNames() { return Object.keys(iv.sources) },
+    stateSourceName: 'STATE',
+    get _debug() { return false },
+    /** the state without its calculated fields (as today's cleanupCalculated) */
+    cleanupCalculated(s: any) {
+      const c = iv.def.calcNames
+      if (!c || !s || typeof s != 'object' || Array.isArray(s)) return s
+      const out = {...s}
+      c.forEach((k: string) => { delete out[k] })
+      return out
+    },
+  }
+  facades.set(iv, f)
+  return f
+}
+
+/** the hook layer of the DevTools bridge `dt` for one app */
+export function devtoolsHooks(dt: any, api: any): any {
+  const mounted = new WeakSet<object>()
+  return {
+    onCreate(iv: any) {
+      const f = devFacade(iv, api)
+      dt.onComponentCreated(iv.id, iv.name, f)
+      if (iv.parentId !== undefined) dt.onSubComponentRegistered(iv.parentId, iv.id)
+      // a Collection's first item (today's onCollectionMounted)
+      if (iv.kind == 'item' && iv.parentId !== undefined) {
+        const p = api.get(iv.parentId)
+        if (p && !mounted.has(p)) { mounted.add(p); dt.onCollectionMounted(p.id, p.name, iv.name, null) }
+      }
+    },
+    onStateChanged(iv: any, s: any) { dt.connected && dt.onStateChanged(iv.id, iv.name, s) },
+    onPropsChanged(iv: any, p: any) { dt.connected && dt.onPropsChanged(iv.id, iv.name, p) },
+    onContextChanged(iv: any, c: any) { dt.connected && dt.onContextChanged(iv.id, iv.name, c) },
+    onAction(iv: any, a: any) { dt.connected && dt.onActionDispatched(iv.id, iv.name, a.type, a.data) },
+    onReady(p: any, c: any, ready: boolean) { dt.connected && dt.onReadyChanged(p.id, p.name, c.name, ready) },
+    onDispose(iv: any) { dt.onComponentDisposed(iv.id, iv.name) },
+  }
+}
+
+/** register a hook layer factory with the core (read by each app at its start) */
+export function addLayer(f: (api: any) => any): () => void {
+  const core = (globalThis as any).__SYGNAL_DIAGNOSTICS__
+  if (!core) return () => {}
+  ;(core.layers ||= new Set()).add(f)
+  return () => { core.layers?.delete(f) }
+}

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

@@ -0,0 +1,108 @@
+/**
+ * PLAN-4 2-C (GS-10): the action log. Records every action a component instance runs as
+ *   { type, data, component, instance, sinks, cause, time }
+ * for renderComponent's t.actions / t.explain() (src/extra/testing.ts), inspect({ actions }) in
+ * the 'sygnal/diagnostics' dev entry (./inspect.ts) and the DevTools action log
+ * (src/extra/devtoolsActions.ts).
+ *
+ * 0 B in apps: nothing in the core calls this. actionHooks() is a hook layer of the core
+ * (04-hooks-contract §3.3): onAction opens the record (the core passes the cause: 'intent',
+ * 'next', 'reply', 'built-in', 'simulateAction'; an intent action a behavior owns is
+ * 'behavior'), wrapHandler sees which sinks produced a value. (The old core's version patched
+ * each instance; R5 removed it.)
+ *
+ * Sinks: a function reducer counts when it returns a value: not ABORT (or another symbol, which
+ * the core drops), and for STATE not the state it was given (GS-4: no change); EFFECT counts when
+ * the handler ran without ABORT. A constant / `true` entry always sends. A throwing reducer
+ * sends nothing.
+ */
+import {isAbort, ORIGINAL} from '../../../shared'
+
+export type ActionCause = 'intent' | 'next' | 'reply' | 'built-in' | 'simulateAction' | 'behavior'
+
+export interface ActionRecord {
+  type: string
+  data: any
+  /** the component's name */
+  component: string
+  /** the instance's id (its component number, as inspect()'s component ids) */
+  instance: string
+  /** sinks that produced a value for this action (live: STATE fills in when the reducer runs) */
+  sinks: string[]
+  cause: ActionCause
+  /** clock time (fake-timer aware) when the action reached the model */
+  time: number
+  /** a reply: the source that delivered it */
+  source?: string
+}
+
+export interface ActionListener {
+  action(record: ActionRecord, component: any): void
+  /** a sink produced a value for `record` (reducer: the model's function, when there is one) */
+  sink?(record: ActionRecord, sink: string, reducer: any): void
+}
+
+const BUILT_IN = /^(BOOTSTRAP|INITIALIZE|DISPOSE|RESOURCE)$/
+
+/** now on the test's fake clock when there is one (vi.useFakeTimers()), else Date.now() */
+export const clockNow = (): number => {
+  const c = (setTimeout as any).clock
+  return c ? c.now : Date.now()
+}
+
+/**
+ * PLAN-4.6 R4: the same log on the core, from its hooks (04 §3.3) instead of instance
+ * patches: onAction opens the record (the core passes the cause: 'intent', 'next', 'reply',
+ * 'built-in', 'simulateAction'), wrapHandler sees which sinks produced a value. Same records,
+ * same cause rules: a built-in type is 'built-in' unless simulated; an intent action a behavior
+ * owns is 'behavior'. `only(inst)`: the instances to record (renderComponent: its own tree).
+ */
+export function actionHooks(listener: ActionListener, only?: (inst: any) => boolean): any {
+  const cur = new WeakMap<object, [ActionRecord, string[]]>()
+  // INITIALIZE: the core writes the initial state at creation (no action, unless the model
+  // has an INITIALIZE entry); today's log has an INITIALIZE record with STATE, so it is opened here
+  const init = new WeakMap<object, ActionRecord>()
+  return {
+    onCreate(inst: any) {
+      const d = inst.def
+      if ((only && !only(inst)) || d.initialState === undefined || !(inst.isRoot || d.isolated)) return
+      const rec: ActionRecord = {type: 'INITIALIZE', data: d.initialState, component: inst.name, instance: String(inst.id), sinks: [], cause: 'built-in', time: clockNow()}
+      init.set(inst, rec)
+      try { listener.action(rec, inst) } catch (_) { /* ignore */ }
+      addSink(listener, rec, ['STATE'], 'STATE', undefined)
+    },
+    onAction(inst: any, a: any) {
+      if (only && !only(inst)) return
+      const type = String(a.type), owned = inst.def.behaviorActions
+      const hs = inst.def.handlers.get(type) || [], order = hs.map((h: any) => h[0])
+      const opened = type == 'INITIALIZE' && init.get(inst)
+      if (opened) { init.delete(inst); cur.set(inst, [opened, order]); return }
+      const cause: ActionCause = a.cause == 'simulateAction' ? a.cause : BUILT_IN.test(type) ? 'built-in'
+        : a.cause == 'next' || a.cause == 'reply' ? a.cause
+        : owned && Object.prototype.hasOwnProperty.call(owned, type) ? 'behavior' : 'intent'
+      const rec: ActionRecord = {type, data: a.data, component: inst.name, instance: String(inst.id), sinks: [], cause, time: clockNow(), ...(a.source !== undefined && {source: a.source})}
+      cur.set(inst, [rec, order])
+      try { listener.action(rec, inst) } catch (_) { /* a listener never breaks the app */ }
+      // a constant / `true` entry always sends (EFFECT runs functions only)
+      for (const [sink, h] of hs) if (typeof h != 'function' && sink != 'EFFECT') addSink(listener, rec, order, sink, undefined)
+    },
+    wrapHandler(inst: any, type: string, sink: string, fn: any) {
+      const c = cur.get(inst)
+      if (!c || c[0].type !== type || typeof fn != 'function') return
+      const [rec, order] = c, isState = sink == 'STATE', isEffect = sink == 'EFFECT'
+      return function (this: any, state: any) {
+        const r = fn.apply(this, arguments)
+        if (!isAbort(r) && (isEffect || typeof r != 'symbol') && !(isState && r === state)) addSink(listener, rec, order, sink, fn[ORIGINAL] || fn)
+        return r
+      }
+    },
+  }
+}
+
+function addSink(l: ActionListener, rec: ActionRecord, order: string[], sink: string, reducer: any): void {
+  if (!rec.sinks.includes(sink)) {
+    rec.sinks.push(sink)
+    rec.sinks.sort((a, b) => order.indexOf(a) - order.indexOf(b))
+  }
+  try { l.sink?.(rec, sink, reducer) } catch (_) { /* ignore */ }
+}

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

@@ -0,0 +1,49 @@
+/**
+ * PLAN-4 GS-1, runtime behavior checks (dev entry only; the static `uses` resolution is 3-D's).
+ *
+ * SYG127 (error), once per component name (not per Collection item; again in each renderComponent):
+ *   - a `uses` key that the host's own `initialState` static already has (the behavior's slice
+ *     replaces it);
+ *   - a `uses` value that isn't a defineBehavior() result (no `merge`): the core skips it, so
+ *     state[key] and its actions never exist.
+ *   A host intent or model entry named like a behavior action ('pager.NEXT') is an override,
+ *   not a collision.
+ * Mechanism: onModel (every instance gets one, with or without a model) reads the static
+ * `view.uses` and `view.initialState`.
+ */
+import type {DiagnosticCheck} from '../index'
+import {devReport, nameOf, once} from './shared'
+
+const what = (v: any): string =>
+  v === null || v === undefined ? String(v)
+  : typeof v == 'function' ? 'a function (a defineBehavior factory not called?)'
+  : typeof v == 'object' ? 'a plain object'
+  : `a ${typeof v}`
+
+export const behaviorsCheck: DiagnosticCheck = {
+  id: 'behaviors',
+
+  onModel(component) {
+    const view = component?.view, uses = view?.uses
+    if (!uses || typeof uses != 'object' || !once('SYG127:' + nameOf(component))) return
+    const init = view.initialState
+    for (const key of Object.keys(uses)) {
+      const b = uses[key]
+      if (typeof b?.merge != 'function') {
+        devReport('SYG127', {
+          component,
+          message: `uses entry '${key}' is ${what(b)}, not a defineBehavior() result; it was skipped, so state.${key} and its '${key}.*' actions don't exist`,
+          fix: `Use a defineBehavior() factory's result: uses = { ${key}: behavior(options) }`,
+          data: {key, reason: 'unresolvable'},
+        })
+      } else if (init && typeof init == 'object' && key in init) {
+        devReport('SYG127', {
+          component,
+          message: `uses key '${key}' is also a key of ${nameOf(component)}'s initialState; the behavior's slice replaces that value`,
+          fix: `Remove '${key}' from initialState (pass its values as the behavior's options), or rename the uses key`,
+          data: {key, reason: 'initialState'},
+        })
+      }
+    }
+  },
+}