sygnal 5.4.0 → 6.0.0

package/src/core/actions.ts

@@ -0,0 +1,134 @@
+/**
+ * PLAN-4.6 core: running one action (03-proposal §3, 04 §2.4.1).
+ *
+ * The action's handlers run in model order with (pre, data, next, props), where `pre` is the
+ * state (calculated fields included) from before the action, for every sink:
+ * - STATE: applied at once (D165). ABORT, or the object it was given (GS-4), is no change.
+ *   D205: during an input / change event (an action triggered by typing in a field), no change
+ *   still re-renders the instance, so a controlled field shows the model's value again
+ * - EFFECT: run synchronously (preventDefault on the live event still works); `props.signal`
+ *   aborts on dispose; a returned value is SYG219, a rejected promise SYG214.
+ * - PARENT: straight to the parent's CHILD.select listeners as { name, component, value }.
+ * - READY: the instance's ready flag (the parent re-renders it with data-sygnal-ready).
+ * - ELEMENT: element commands, run after the next patch (extra/elementCommands).
+ * - any other sink (EVENTS, LOG, drivers): stamped and scoped (send), then the app's bus.
+ * A dispatch from a handler (a driver answering synchronously, an EFFECT) is queued (FIFO).
+ */
+import type {Inst} from './instance'
+import {isAbort} from '../shared'
+import {isObj} from './define'
+import {warn, error as logError, fail} from '../extra/diagnostics/legacy'
+import {runElementCommands} from '../extra/elementCommands'
+import {viewOf} from './view'
+import {checkStatics} from './statics'
+import {objIsEqual} from '../cycle/state/objIsEqual'
+import {dbg} from './debug'
+
+export function handle(inst: Inst, type: string, data: any, cause: any, src?: string) {
+  const hs = inst.def.handlers.get(type), app = inst.app, H = app.hooks
+  // (an action with no model entry is seen too: the action log lists it with no sinks)
+  if (H.onAction) H.onAction(viewOf(inst), {type, data, cause, target: viewOf(inst), source: src})
+  dbg(inst, () => `<${type}> Action triggered`)
+  if (!hs) return
+  const def = inst.def
+  const pre = inst.cell.get()
+  let props: any, outs: any[] | undefined
+  const next = (t: string, d?: any, ms: any = 10, effect?: boolean) => {
+    if (typeof ms !== 'number') fail('SYG215', inst, `next() delay in '${type}' must be a number`, "Use next('ACTION', data, ms)")
+    // G-300: none for an instance being disposed; dispose() clears the pending ones
+    if (inst.disposed || inst.dying) return dbg(inst, () => `next(${t}) ignored: disposed`)
+    H.onNext?.(viewOf(inst), t, d, ms)
+    dbg(inst, () => `<${type}> ${effect ? 'EFFECT triggered' : 'Triggered'} a next() action: <${t}> ${ms}ms delay`)
+    const ts = inst.timers ||= new Set()
+    const id = setTimeout(() => { ts.delete(id); inst.disposed || app.dispatch(inst, t, d, 'next') }, ms)
+    ts.add(id)
+  }
+  for (const [sink, h0] of hs) {
+    const h = H.wrapHandler ? H.wrapHandler(viewOf(inst), type, sink, h0) || h0 : h0
+    if (sink == 'EFFECT') {
+      if (typeof h != 'function') continue
+      const failed = (e: any) => app.caught(inst, 'SYG214', `EFFECT handler '${type}' threw`, e, 'effect', type)
+      try {
+        const p = {...(props ||= inst_props(inst, pre)), signal: (inst.ac ||= globalThis.AbortController && new AbortController())?.signal}
+        const r = h(pre, data, (t: string, d?: any, ms?: any) => next(t, d, ms, true), p)
+        if (r?.then) r.then(null, failed)
+        else if (r !== undefined && !isAbort(r)) warn('SYG219', inst, `EFFECT handler '${type}' returned a value, which is ignored`, 'Use a STATE or driver sink')
+      } catch (e) { failed(e) }
+      continue
+    }
+    let v: any
+    if (typeof h == 'function') {
+      try { v = h(pre, data, next, props ||= inst_props(inst, pre)) } catch (e) {
+        app.caught(inst, 'SYG216', `Reducer for '${type}' threw; ${sink == 'STATE' ? 'state unchanged' : 'nothing sent'}`, e, 'reducer', type)
+        continue
+      }
+    } else v = h === undefined || h === true ? data : h
+    if (sink == 'STATE' && (isAbort(v) || v === pre)) {
+      // D205: the DOM event being dispatched (window.event) is the one this action came from
+      if (/^(input|change)$/.test((globalThis as any).event?.type)) inst.refresh()
+      continue
+    }
+    if (isAbort(v)) continue
+    if (sink == 'STATE') {
+      H.onReducer?.(viewOf(inst), type, pre, v)
+      dbg(inst, () => `<${type}> State reducer added`)
+      inst.cell.set(v)
+      // GS-12: this app's DOM driver patches inside a View Transition (makeViewTransitionDOMDriver
+      // reads the flag on its IsolateModule); includes?.: a non-array static lists nothing (G-228).
+      // Only for a state that changed structurally: today an equal one renders nothing (its
+      // request expires unused); here it would re-render the same view, so it asks for nothing
+      if (def.view.viewTransitions?.includes?.(type) && (v === undefined || !objIsEqual(pre, inst.cell.get()))) { const m = inst.dom?._isolateModule; if (m) m.vt = 1 }
+      continue
+    }
+    if (typeof v == 'symbol') { logError('SYG218', inst, `Reducer for '${type}' returned a symbol; nothing sent`, 'Return a value, or ABORT to send nothing'); continue }
+    if (v === undefined) warn('SYG217', inst, `Reducer for '${type}' sent undefined to the driver`, 'Return a value, or ABORT to send nothing')
+    if (H.onSink) H.onSink(viewOf(inst), type, sink, v)
+    dbg(inst, () => `<${type}> Data sent to [${sink}]: ${JSON.stringify(v)}`)
+    if (sink == 'PARENT') {
+      const e = {name: def.name, component: def.view, value: v}
+      if (inst.parent) inst.parent.toChild(e)
+      else app.out('PARENT', e)
+    } else if (sink == 'READY') inst.setReady(!!v)
+    else if (sink == 'ELEMENT') {
+      // onElementCommand returning false: recorded, not run (renderComponent's mock DOM)
+      if (H.onElementCommand?.(viewOf(inst), v) !== false) runElementCommands(inst.el ||= {name: def.name, DOMSourceName: 'DOM', sources: {DOM: inst.dom}, get _disposed() { return inst.disposed }}, v)
+    } else if (inst.st) (outs ||= []).push(sink, v)
+    else send(inst, sink, v)
+  }
+  // G-158 (D170/Q21): a static this action changed reaches its driver before the action's own
+  // driver values (a connection the action opens exists before its first message)
+  if (inst.st) {
+    checkStatics(inst)
+    if (outs) for (let i = 0; i < outs.length; i += 2) send(inst, outs[i], outs[i + 1])
+  }
+}
+
+/** the handlers' 4th argument: the props, children, slots, context, uid and the pre-action state */
+function inst_props(inst: Inst, pre: any) {
+  return {...inst.props, children: inst.children, slots: inst.slots, context: inst.context(), uid: inst.uid, state: pre}
+}
+
+/**
+ * A sink value of an instance: stamped with its sender (EVENTS; object values for a reply-capable
+ * source), scoped through every ancestor's isolation (a driver's value-level isolateValue, else
+ * one stream per instance and sink through isolateSink), then onto the app's bus for that sink.
+ */
+export function send(inst: Inst, n: string, v: any) {
+  const app = inst.app, src = app.sources[n]
+  if (n == 'EVENTS' || (src?.__sygnalReplies && isObj(v))) {
+    v = Object.defineProperties({...v}, {__emitterId: {value: inst.id, configurable: true}, __emitterName: {value: inst.def.name, configurable: true}})
+  }
+  if (inst.parent && src && typeof src.isolateSink == 'function') {
+    let w = v
+    for (let i: Inst = inst; i.parent; i = i.parent) {
+      const o = i.parent.src(n)
+      if (typeof o?.isolateValue != 'function') return app.pipe(inst, n, v, (s$: any) => {
+        for (let j: Inst = inst; j.parent; j = j.parent) { const p = j.parent.src(n); if (typeof p?.isolateSink == 'function') s$ = p.isolateSink(s$, j.scope) }
+        return s$
+      }, (x: any) => app.out(n, x))
+      w = o.isolateValue(w, i.scope)
+    }
+    v = w
+  }
+  app.out(n, v)
+}

package/src/core/cell.ts

@@ -0,0 +1,202 @@
+/**
+ * PLAN-4.6 core: state cells (03-proposal §4). Pull-based views of the one state tree,
+ * memoized on the parent value's identity. A write goes straight to the parent (no reducer
+ * wrappers climbing the tree); the root's (or an isolated instance's local) write commits.
+ *
+ * | cell  | get                                        | set                                     |
+ * | root  | app.state                                  | app.state = v; commit                   |
+ * | key   | parent.get()[k] (or a default, isolated)   | parent.set({...p, [k]: v}); SYG409 when k is a calculated field of the parent |
+ * | lens  | lens.get(parent.get())                     | parent.set(lens.set(p, v))              |
+ * | local | its own value; the parent's until written  | own value; commit (isolatedState)       |
+ *
+ * Calculated fields (and `idle` defaults) are a decorator: get() adds them, memoized per input
+ * identity and per declared dependency values; set() stores them (the only behaviour after D164).
+ * Children read through their parent's decorated cell, so they see its calculated fields, and a
+ * child's write stores freshly computed ones (4-F).
+ */
+import {uidPart} from '../shared'
+import type {CoreDef} from './define'
+import {isObj} from './define'
+import {warn, error as logError} from '../extra/diagnostics/legacy'
+
+export interface Cell {
+  get(): any
+  set(v: any): void
+}
+export interface CalcCell extends Cell {
+  /** the raw value (calculated fields only as stored), for STATE.stream */
+  raw(): any
+}
+
+export const rootCell = (app: {state: any; commit(): void}): Cell =>
+  ({get: () => app.state, set: (v) => { app.state = v; app.commit() }})
+
+/** isolatedState without a `state` prop: owned by the instance; the parent's state until first written */
+export function localCell(app: {commit(): void}, parent: Cell): Cell {
+  let v: any, own = false
+  return {local: true, get: () => (own ? v : parent.get()), set: (n) => { v = n; own = true; app.commit() }} as 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).
+ */
+export function keyCell(parent: Cell, k: string, owner?: string | false, dflt?: any, what = 'Sub-component'): Cell & {has(): boolean} {
+  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 }
+      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')
+      const p = parent.get()
+      if (p?.[k] !== v) parent.set({...p, [k]: v})
+    },
+    has: () => parent.get()?.[k] !== undefined,
+  }
+}
+
+/**
+ * state={{ get, set }} (no get: SYG410, the parent's whole state). G-298: a get() that throws
+ * keeps the last value (SYG410, and `onErr` for the app's onError). `dflt`, `has()`: as keyCell's
+ * (G-314, D179: an isolated child's initialState read while the lensed slice is undefined)
+ */
+export function lensCell(parent: Cell, lens: any, owner: string, onErr?: (e: any) => void, dflt?: any): Cell & {has?(): boolean} {
+  if (typeof lens?.get != 'function') {
+    logError('SYG410', owner, `Sub-component 'state' prop ${isObj(lens) ? 'has no get()' : `is a ${typeof lens}`}; it gets the parent's whole state`, 'Use a state key string or { get, set }')
+    return parent
+  }
+  let lp: any = {}, lv: any, raw: any
+  return {
+    get() {
+      const p = parent.get()
+      if (p !== lp) {
+        lp = p
+        try { raw = lv = lens.get(p) } catch (e) {
+          logError('SYG410', owner, "Sub-component 'state' lens get() threw; it keeps its last value", 'Guard the getter against missing data', e)
+          onErr?.(e)
+        }
+        if (lv === undefined) lv = dflt
+      }
+      return lv
+    },
+    has() { this.get(); return raw !== undefined },
+    set(v) {
+      if (typeof lens.set != 'function') return
+      const p = parent.get(), n = lens.set(p, v)
+      if (n !== p) parent.set(n)
+    },
+  }
+}
+
+/** calculated fields and `idle` defaults over a base cell */
+export function calcCell(base: Cell, def: CoreDef): CalcCell {
+  const calc = def.calculated, idle = def.idle
+  const caches = calc ? calc.map(() => ({v: null as any[] | null, r: undefined as any})) : []
+  let ls: any = {}, lr: any
+  const add = (s: any) => {
+    if (!isObj(s)) return s
+    if (s === ls) return lr
+    ls = s
+    let m = idle ? {...idle, ...s} : s
+    if (calc) {
+      if (m === s) m = {...s}
+      for (let i = 0; i < calc.length; i++) {
+        const [f, fn, deps] = calc[i], c = caches[i]
+        const dv = deps && deps.map(d => m[d])
+        if (dv && c.v && dv.every((x, j) => x === c.v![j])) { m[f] = c.r; continue }
+        try {
+          const r = fn(m)
+          if (dv) c.v = dv, c.r = r
+          m[f] = r
+        } catch (e: any) {
+          warn('SYG220', def.name, `Calculated field '${f}' threw (${e instanceof Error ? e.message : e}); skipped this update`, 'Guard against missing data')
+        }
+      }
+    }
+    return (lr = m)
+  }
+  return {
+    raw: () => base.get(),
+    get: () => add(base.get()),
+    set(v) {
+      if (!isObj(v) || !(calc || idle)) return base.set(v)
+      // stored with its calculated fields (and idle defaults), as cleanupCalculated did
+      const c = {...add(v)}
+      ls = c; lr = c
+      base.set(c)
+    },
+  }
+}
+
+
+// ------------------------------------------------------------------ Collection items
+
+/**
+ * An item's key: the `id` of an object item (anything but undefined / null, compared as a string,
+ * as today's stringified keys), else its raw index in the state array (D169: not its
+ * filtered/sorted position), in a namespace of its own ('\0' + index: G-306/G-307, so an index
+ * never collides with an id).
+ */
+export const keyOf = (it: any, i: number): string => (isObj(it) && it.id != null ? '' + it.id : '\0' + i)
+/**
+ * the key as it appears in an item's uid: an id through uidPart; an index key as `_i<index>`
+ * (G-322: uidPart never makes '_' followed by a letter, so an index never collides with an id,
+ * e.g. `[{ t }, { id: 0 }]`; renderToString matches it)
+ */
+export const keyName = (k: string) => (k[0] == '\0' ? '_i' + k.slice(1) : uidPart(k))
+const hasId = (it: any) => isObj(it) && it.id != null
+
+const EMPTY: any[] = []
+export type Index = () => [items: any[], byKey: Map<any, number>]
+
+/** one per Collection: the key -> raw index map (first occurrence), rebuilt once per array identity, shared by its items */
+export function indexer(arr: Cell): Index {
+  let la: any, map = new Map<any, number>()
+  return () => {
+    const g = arr.get(), a = Array.isArray(g) ? g : EMPTY
+    if (a !== la) {
+      la = a
+      map = new Map()
+      for (let i = 0; i < a.length; i++) { const k = keyOf(a[i], i); if (!map.has(k)) map.set(k, i) }
+    }
+    return [a, map]
+  }
+}
+
+/**
+ * A Collection item: the element of its key. An id-less element is a copy with its index as `id`
+ * (a primitive `{ value, id }`, written back as the primitive); that `id` is not written back. Writing `undefined` removes the
+ * element; the other elements keep their identity (PF-1).
+ */
+export function itemCell(arr: Cell, index: Index, key: any): Cell {
+  let lraw: any = {}, lval: any
+  return {
+    get() {
+      const [a, m] = index(), j = m.get(key)
+      // removed: its last state (a disposing item's DISPOSE / dispose$ handlers read it, as today)
+      if (j === undefined) return lval
+      const raw = a[j]
+      if (raw === lraw) return lval
+      lraw = raw
+      return (lval = isObj(raw) ? (hasId(raw) ? raw : {...raw, id: j}) : {value: raw, id: j})
+    },
+    set(v) {
+      const [a, m] = index(), j = m.get(key)
+      if (j === undefined) return
+      if (v === undefined) return arr.set(a.filter((_: any, x: number) => x !== j))
+      const cur = a[j]
+      if (v === cur || (v === lval && cur === lraw)) return
+      const n = a.slice()
+      if (isObj(cur) || !isObj(v)) {
+        // G-306: the index id an id-less element was given is not stored
+        if (isObj(cur) && !hasId(cur) && isObj(v) && v.id === j) { v = {...v}; delete v.id }
+        n[j] = v
+      } else n[j] = v.value
+      arr.set(n)
+    },
+  }
+}

package/src/core/debug.ts

@@ -0,0 +1,23 @@
+/**
+ * PLAN-4.6 core: the documented debug logging (integration/debugging: `Component.debug =
+ * true`, `window.SYGNAL_DEBUG = 'true'` / `SYGNAL_DEBUG=true` in Node), as the 5.x core's
+ * `log()`: `[<id> | <Name>] <message>` on the console, and to a connected DevTools extension
+ * (onDebugLog). `inst.debug`: the DevTools toggle for one instance. The message is built only
+ * when logging is on.
+ */
+import type {Inst} from './instance'
+
+declare const process: {env: Record<string, any>}
+const ENV: any = (typeof window != 'undefined' && window) || (typeof process != 'undefined' && process.env) || {}
+
+export function dbg(inst: Inst, msg: () => string) {
+  if (!(inst.debug || inst.def.view.debug || ENV.SYGNAL_DEBUG === 'true' || ENV.SYGNAL_DEBUG === true)) return
+  // G-331: the message (JSON of a BigInt or circular value) and the DevTools bridge never break
+  // the action being logged
+  let m: string
+  try { m = msg() } catch (e) { m = '(message not shown: ' + e + ')' }
+  const text = `[${inst.id} | ${inst.def.name}] ${m}`
+  console.log(text)
+  const dt = typeof window != 'undefined' && (window as any).__SYGNAL_DEVTOOLS__
+  try { if (dt?.connected) dt.onDebugLog(inst.id, text) } catch (_) { /* the bridge's own bug */ }
+}

package/src/core/define.ts

@@ -0,0 +1,242 @@
+/**
+ * PLAN-4.6 core: definitions, normalized once per component function (03-proposal §1.4).
+ *
+ * defOf(view) reads the component's statics into a DefSource, runs the definition hooks on it
+ * (registry.defHooks, then an app's transformDef), and normalizes it into a Def:
+ * - model -> Map<action, [sink, handler][]> in model order (a function entry is STATE); the sinks
+ *   used; INITIALIZE keeps only STATE (SYG210)
+ * - calculated: fn | [deps, fn], Kahn order; SYG206 (invalid entry) and SYG209 (cycle, with its
+ *   path) are thrown here; SYG207 / SYG208 warn
+ * - context entries (functions of the state; anything else is SYG403 and skipped)
+ * - isolatedState, READY presence, onError, name
+ *
+ * The removed forms (D162-D164: 'A | S' keys, string/true context entries, `.components`, ...)
+ * are not read. The cache is a WeakMap per function; an app with its own transformDef keeps its
+ * own cache (the hook is per app).
+ */
+import type {ComponentFn, Def, DefSource, Handler} from './hooks'
+import {defHooks} from './registry'
+import {fail, warn, error as logError} from '../extra/diagnostics/legacy'
+
+export type Calc = [field: string, fn: (s: any) => any, deps: string[] | null]
+
+export interface CoreDef extends Def {
+  readonly handlers: Map<string, Handler[]>
+  readonly sinks: Set<string>
+  readonly calculated: Calc[] | null
+  /** the calculated field names (a child bound to one can't write it: SYG409) */
+  readonly calcNames: Set<string> | null
+  /** the model has a READY entry: the instance starts not ready */
+  readonly ready: boolean
+  /** the definition has a model (a root without one renders from `initialState || true`) */
+  readonly model: boolean
+}
+
+export const isObj = (o: any): o is Record<string, any> => o !== null && typeof o == 'object' && !Array.isArray(o)
+
+/** a component function's name (the removed `.label` is not read, D164) */
+export const nameOf = (view: any): string => view.componentName || view.name || 'FUNCTION_COMPONENT'
+
+function normCalc(name: string, calculated: any, initialState: any): [Calc[], Set<string>] | null {
+  if (!calculated) return null
+  if (!isObj(calculated)) fail('SYG606', name, 'calculated must be an object', 'Use calculated = { field: state => value }')
+  const norm: Record<string, [any, string[] | null]> = {}
+  for (const f in calculated) {
+    const e = calculated[f]
+    if (typeof e == 'function') norm[f] = [e, null]
+    else if (Array.isArray(e) && e.length == 2 && Array.isArray(e[0]) && typeof e[1] == 'function') norm[f] = [e[1], e[0]]
+    else fail('SYG206', name, `Invalid calculated field '${f}'`, 'Use fn or [deps, fn]')
+    if (isObj(initialState) && f in initialState) warn('SYG207', name, `Calculated field '${f}' overwrites the initialState key of the same name`, 'Rename one of them')
+  }
+  const names = new Set(Object.keys(norm))
+  // Kahn: per field the calculated fields it waits for, and its dependents
+  const deps: Record<string, string[]> = {}, waiting: Record<string, number> = {}, dependents: Record<string, string[]> = {}
+  for (const f of names) {
+    for (const d of norm[f][1] || []) {
+      if (!names.has(d) && initialState && !(d in initialState)) warn('SYG208', name, `Calculated field '${f}' depends on unknown key '${d}'`, 'Add it to initialState')
+    }
+    const d = deps[f] = (norm[f][1] || []).filter(x => names.has(x))
+    waiting[f] = d.length
+    dependents[f] ||= []
+    for (const x of d) (dependents[x] ||= []).push(f)
+  }
+  const sorted = [...names].filter(f => !waiting[f])
+  for (let i = 0; i < sorted.length; i++) for (const d of dependents[sorted[i]]) if (!--waiting[d]) sorted.push(d)
+  if (sorted.length != names.size) {
+    const inCycle = [...names].filter(f => !sorted.includes(f)), path: string[] = []
+    const trace = (n: string): boolean => {
+      if (path.includes(n)) return path.push(n), true
+      path.push(n)
+      if (deps[n].some(d => inCycle.includes(d) && trace(d))) return true
+      path.pop()
+      return false
+    }
+    trace(inCycle[0])
+    const start = path[path.length - 1]
+    fail('SYG209', name, `Circular calculated dependency: ${path.slice(path.indexOf(start)).join(' → ')}`, 'Break the cycle')
+  }
+  return [sorted.map(f => [f, norm[f][0], norm[f][1]] as Calc), names]
+}
+
+/** the statics a definition hook may edit, read from the component function */
+export const sourceOf = (view: ComponentFn): DefSource => ({
+  model: view.model, intent: view.intent, initialState: view.initialState, idle: null,
+  calculated: view.calculated, context: view.context, behaviorActions: {},
+})
+
+/**
+ * The definition shim (spike finding 5): the instance fields a behavior's existing
+ * `merge(component, key)` reads and writes, so behaviors / undo / selection run unchanged, once
+ * per function. `isSubComponent: true` sends a slice to `_idle` (the defaults a bound
+ * sub-component reads until it writes them); an `isolatedState` definition gets it in its
+ * initialState, as today. A root gets the slices in its initialState (rootDef). fromShim()
+ * reads the result back.
+ */
+export const shimOf = (src: DefSource, view: ComponentFn): any => ({
+  model: src.model, intent: src.intent, initialState: src.initialState, view, name: nameOf(view),
+  stateSourceName: 'STATE', isSubComponent: true, isolatedState: !!view.isolatedState, _idle: src.idle, _behaviorActions: src.behaviorActions,
+})
+export const fromShim = (shim: any, src: DefSource): DefSource => ({
+  ...src, model: shim.model, intent: shim.intent, initialState: shim.initialState,
+  idle: shim._idle, behaviorActions: shim._behaviorActions || src.behaviorActions,
+})
+
+/** the built-in RESOURCE reducer (a model RESOURCE entry replaces it) */
+const RESOURCE = (s: any, {name, ...r}: any) => ({...s, [name]: r})
+
+/**
+ * The definition-time built-ins, in the 5.x core's order: `resources` (PLAN-3
+ * 3-A: the RESOURCE entry first in the model; each resource reads `{ status: 'idle' }` until
+ * written), then `uses` (GS-1: each behavior's own merge() on the shim, D114; the core only
+ * loops over `uses`).
+ */
+function builtIns(src: DefSource, view: ComponentFn): DefSource {
+  const res = view.resources
+  if (res) {
+    const idle: Record<string, any> = {...src.idle}
+    for (const k in res) idle[k] = {status: 'idle'}
+    src = {...src, model: {RESOURCE, ...src.model}, idle}
+  }
+  const uses = view.uses
+  if (uses) {
+    const shim = shimOf(src, view)
+    for (const k in uses) uses[k]?.merge?.(shim, k)
+    src = fromShim(shim, src)
+  }
+  return src
+}
+
+export function normalize(view: ComponentFn, src: DefSource): CoreDef {
+  const name = nameOf(view)
+  const handlers = new Map<string, Handler[]>(), sinks = new Set<string>()
+  const model = src.model
+  for (const key in model || {}) {
+    let e = model![key]
+    if (typeof e == 'function') e = {STATE: e}
+    else if (!isObj(e)) fail('SYG212', name, `Model entry '${key}' must be a function or an object`, 'Use { STATE: reducer }')
+    if (key == 'INITIALIZE') {
+      for (const s in e) if (s != 'STATE') warn('SYG210', name, `INITIALIZE only supports the STATE sink; ignoring '${s}'`, 'Use another action')
+      if (!('STATE' in e)) continue
+      e = {STATE: e.STATE}
+    }
+    const list: Handler[] = []
+    for (const sink in e) list.push([sink, e[sink]]), sinks.add(sink)
+    handlers.set(key, list)
+  }
+  const c = normCalc(name, src.calculated, src.initialState)
+  let context: Array<[string, (s: any) => any]> | null = null
+  if (src.context !== undefined && src.context !== null) {
+    if (!isObj(src.context)) logError('SYG402', name, `context must be an object, got ${typeof src.context}; ignoring it`, 'Use context = { name: state => value }')
+    else {
+      context = []
+      for (const k in src.context) {
+        const f = src.context[k]
+        if (typeof f == 'function') context.push([k, f])
+        else logError('SYG403', name, `Invalid context entry '${k}' (a ${typeof f}); skipping it`, 'Context entries are functions of state only: { name: state => value }. See https://sygnal.js.org/guide/migrating-to-6#leftovers')
+      }
+    }
+  }
+  const intent = src.intent
+  if (intent !== undefined && typeof intent != 'function') fail('SYG602', name, 'intent must be a function', 'Use intent = sources => ({ ACTION: stream$ })')
+  return {
+    name, view, intent, handlers, sinks,
+    initialState: src.initialState,
+    idle: src.idle,
+    isolated: !!view.isolatedState,
+    calculated: c && c[0], calcNames: c && c[1],
+    context: context && context.length ? context : null,
+    statics: [],
+    behaviorActions: src.behaviorActions,
+    ready: sinks.has('READY'),
+    model: model !== undefined,
+    onError: typeof view.onError == 'function' ? view.onError : undefined,
+  }
+}
+
+const defs = new WeakMap<ComponentFn, CoreDef>()
+/**
+ * the statics a Def was made from: a later assignment (a test, a hot edit) makes a new Def; so
+ * does a definition hook registered since (G-383: the browser driver's, added when the first one
+ * is made, binds a `browser` declarer's DOM), the last entry of the snapshot
+ */
+const KEYS = ['model', 'intent', 'initialState', 'calculated', 'context', 'isolatedState', 'onError', 'componentName', 'uses', 'resources', 'browser']
+const read = new WeakMap<CoreDef, any[]>()
+const stale = (d: CoreDef, view: any) => {
+  const r = read.get(d)!
+  for (let i = 0; i < KEYS.length; i++) if (r[i] !== view[KEYS[i]]) return true
+  return r[KEYS.length] !== defHooks.length
+}
+
+/**
+ * The Def of a component function. `transform`: an app's own transformDef (its Defs are cached
+ * in `cache`, not shared); `override`: renderComponent's root (test intent, initial state, name),
+ * normalized uncached.
+ */
+export function defOf(view: ComponentFn, transform?: (src: DefSource, view: ComponentFn) => DefSource | void, cache?: WeakMap<ComponentFn, CoreDef>, override?: Partial<DefSource> & {name?: string}): CoreDef {
+  const store = transform ? cache! : defs
+  let d = override ? undefined : store.get(view)
+  if (d && !stale(d, view)) return d
+  const r = [...KEYS.map(k => view[k]), defHooks.length]
+  d = normalize(view, pipeline(view, transform, override))
+  if (override?.name) (d as any).name = override.name
+  if (!override) store.set(view, d), read.set(d, r)
+  return d
+}
+
+type Transform = ((src: DefSource, view: ComponentFn) => DefSource | void) | undefined
+
+/** the statics, through the built-ins, a root's own steps, the definition hooks and the app's transformDef */
+function pipeline(view: ComponentFn, transform: Transform, override?: Partial<DefSource> & {name?: string}, root?: (src: DefSource) => DefSource): DefSource {
+  let src = sourceOf(view)
+  if (override) src = {...src, ...override}
+  // G-172: a root without a model renders from `initialState || true`, decided before the
+  // built-ins add a model (as in 5.x)
+  if (root && src.model === undefined && !src.initialState) src = {...src, initialState: true}
+  src = builtIns(src, view)
+  if (root) src = root(src)
+  for (const h of defHooks) src = h(src, view) || src
+  if (transform) src = transform(src, view) || src
+  return src
+}
+
+/**
+ * An app's root Def (uncached; renderComponent's `override` too). As defOf, plus the root-only
+ * steps of today's constructor: a behavior's slice is part of the root's initialState
+ * (behaviors.ts's root merge: the slice wins over an initialState key of its name), then
+ * `setup(src)`: persist's root setup (it may restore into the initialState and rewrites the
+ * model; persist.ts, root only, as in 5.x).
+ */
+export function rootDef(view: ComponentFn, transform: Transform, override?: Partial<DefSource> & {name?: string; testActions?: string[]}, setup?: (src: DefSource) => DefSource): CoreDef {
+  const d = normalize(view, pipeline(view, transform, override, (src) => {
+    const uses = view.uses, idle = src.idle
+    if (uses && idle) {
+      const sl: Record<string, any> = {}
+      for (const k in uses) if (k in idle) sl[k] = idle[k]
+      src = {...src, initialState: {...(isObj(src.initialState) ? src.initialState : {}), ...sl}}
+    }
+    return setup ? setup(src) : src
+  }))
+  if (override?.name) (d as any).name = override.name
+  if (override?.testActions) (d as any).testActions = override.testActions
+  return d
+}