@jarenjs/app 0.34.0

package/src/app.js

@@ -0,0 +1,1622 @@
+//@ts-check
+/**
+ * @file The Jaren application loop.
+ *
+ * `createApp` takes an **app document** — one JSON value holding the
+ * initial state, a JSLT view stylesheet, named action documents and
+ * subscription entries — compiles every embedded document once, and runs
+ * a serialized dispatch loop over the compiled closures:
+ *
+ *   DOM event → binding → action document → transition → next state
+ *     → effects → listeners → subscriptions refresh → batched re-render
+ *
+ * JavaScript enters only at named, registered boundaries: effect and
+ * subscription handlers, the `compileTypeTest` hook, and the optional
+ * `validateState` invariant hook. Everything between the boundaries is
+ * data. See docs/APP-FORMAT.md for the document contract.
+ *
+ * **Transaction model (APP-FORMAT §8).** Every dispatch is one
+ * transaction on one FIFO queue. Only the queue drain evaluates and
+ * applies transitions; a dispatch from an effect, listener, observer,
+ * subscription handler, widget or lifecycle hook queues behind the
+ * current transaction and never nests. Within a transaction the order
+ * is: state commit → effect invocation → listener notification →
+ * subscription reconciliation → render scheduling → observer
+ * notification; all of it completes before the next transaction begins.
+ * Every listener therefore observes every transaction in the same
+ * order, and each notification carries the state produced by exactly
+ * that transaction. Native event data is reduced to JSON synchronously
+ * at dispatch time, before queuing. A listener, observer or cleanup
+ * error is isolated: it is reported through `onError`, and whatever the
+ * sink throws is re-thrown only after the drain has fully completed —
+ * the queue always drains, cleanups are never skipped.
+ */
+
+import { stableStringify } from '@jarenjs/core/object';
+import { compileJsltStylesheet } from '@jarenjs/json/jslt';
+import { applyJSONPatch } from '@jarenjs/json/patch';
+import { createDomRenderer } from '@jarenjs/view';
+
+import { compileActions, compileSubs } from './actions.js';
+import { AppCompileError, AppRuntimeError, toError, safeErrorMessage } from './errors.js';
+
+/**
+ * @typedef {Object} AppOptions
+ * @property {any} [node] - DOM element to mount into; omit for a headless
+ *   app (drive it via `getVnode`/`subscribe`).
+ * @property {any} [document] - The DOM document (defaults to
+ *   `node.ownerDocument`).
+ * @property {Record<string, (props: any, dispatch: Dispatch) => void>} [effects]
+ *   Effect handlers by name. A handler function may carry an optional
+ *   `dispose()` member, called exactly once by `app.destroy()` (a
+ *   handler registered under several names is disposed once).
+ * @property {Record<string, (props: any, dispatch: Dispatch) => (() => void) | void>} [subs]
+ *   Subscription handlers by name; may return a cleanup function.
+ * @property {Record<string, (nativeEvent: any) => any>} [eventFields]
+ *   Named event-field extractors: when a binding requests a field by
+ *   name, an extractor registered here wins over the built-in
+ *   allow-list. An extractor receives the native event and MUST return
+ *   a JSON value (`$event` stays serializable end to end).
+ * @property {Record<string, any>} [widgets] - Registered widget
+ *   definitions by name for `jaren-widget` vnodes (VIEW-FORMAT §7),
+ *   forwarded to the renderer — the mechanism lives in `@jarenjs/view`;
+ *   the app only names the boundary, like effects and subs.
+ * @property {(schema: any, docPath: string) => ((value: any) => boolean)} [compileTypeTest]
+ *   Enables JSON Schema operators (`$valid`/`$assert`/`$as`) and schema
+ *   matches inside the view and the action documents.
+ * @property {(state: any, context: ValidateContext) => boolean | { valid: boolean, errors?: any }} [validateState]
+ *   Invariant hook, called with every candidate next state plus a
+ *   context carrying the previous state, the acting action name, its
+ *   payload and the transition's changed paths (`null` = unknown, the
+ *   whole state must be treated as changed — selective validation on
+ *   `changes` is only sound when the hook falls back to a full check
+ *   for `null`). A rejection (`false` or `{ valid: false }`) blocks the
+ *   transition (fail closed) and reports `JA2005` through `onError`.
+ *   The hook is host code and may itself fail: a throwing validator is
+ *   isolated as `JA2015` (the transaction fails, the original cause is
+ *   preserved, and the queue keeps draining — parked errors from the
+ *   default rethrowing sink surface only after the drain). The hook
+ *   also runs once at boot against the initial state (see
+ *   {@link ValidateContext}).
+ * @property {(state: any) => any} [viewModel] - The derivation boundary:
+ *   maps the state to the view stylesheet's input document before every
+ *   render (default identity). This is where JS-computed derivations —
+ *   `buildFormViewModel` from `@jarenjs/forms`, aggregations, joins —
+ *   enter the render path without ever entering the state.
+ * @property {(error: Error) => void} [onError] - Runtime error sink;
+ *   default rethrows. Errors reported from isolated sites (listeners,
+ *   observers, cleanups, unknown event fields) never break the
+ *   transaction queue: whatever the sink throws surfaces to the outer
+ *   dispatch caller only after the drain completes.
+ * @property {(flush: () => void) => void} [schedule] - Render scheduler;
+ *   default batches on a microtask. Pass `(f) => f()` for synchronous
+ *   rendering (tests, SSR pipelines).
+ * @property {() => void} [afterRender] - Called exactly once per
+ *   settled, NONTERMINAL committed frame: after the DOM patch and
+ *   widget mounts complete, and — when a widget hook error was parked
+ *   during the frame — BEFORE that error is delivered to `onError`
+ *   (the committed frame is real; its callback is never starved by
+ *   error delivery). Never called for a pass that ended in terminal
+ *   teardown, and never on headless apps. The post-render
+ *   focus/measurement queue (`createFocusEffect`) plugs in here.
+ * @property {number} [maxTurns] - The dispatch-loop guard (default
+ *   1000): the maximum number of transactions one drain may process
+ *   before the queue is abandoned with `JA2010` — an accidental
+ *   action→effect→action loop diagnoses instead of hanging.
+ * @property {number} [maxSubInstances] - The subscription fan-out
+ *   bound (default 256): a `for` declaration resolving more instances
+ *   than this reports `JA2017` and keeps its previous instance set —
+ *   an unbounded fan-out driven by state is a resource bug waiting for
+ *   a bad query.
+ * @property {boolean} [capturePayloads] - Include `payload` and `event`
+ *   values in transaction records handed to observers (default false —
+ *   diagnostics must not leak data by default).
+ */
+
+/**
+ * The context handed to `validateState` (second argument). During boot
+ * the hook is called once with the initial state and the **boot
+ * context**: `previous` and `action` are `null` (no transition
+ * produced the state) and `changes` is `null` (validate fully); this
+ * runs before any subscription starts or effect runs.
+ * @typedef {Object} ValidateContext
+ * @property {any} previous - The state the transition started from
+ *   (`null` for the boot-time initial-state check).
+ * @property {string | null} action - The acting action name (`null`
+ *   for the boot-time initial-state check).
+ * @property {any} payload - The dispatch payload (`null` when absent).
+ * @property {string[] | null} changes - Changed JSON Pointers when the
+ *   transition was patch-only, else `null` (= unknown, validate fully).
+ */
+
+/**
+ * A transaction record handed to observers (APP-FORMAT §8.3). Payload
+ * and event members are present only when `capturePayloads` is on.
+ * @typedef {Object} TransactionRecord
+ * @property {number} seq - Monotonic transaction sequence number.
+ * @property {string} action - The dispatched action name.
+ * @property {string} source - What queued it: `'dispatch'` (external),
+ *   `'binding'` (DOM/widget), `'effect'`, `'subscription'`, or
+ *   `'setState'` (a whole-state replacement from outside the loop).
+ * @property {'applied' | 'noop' | 'rejected' | 'failed'} status
+ * @property {string[] | null} changedPaths - Changed JSON Pointers, or
+ *   `null` when the whole state was replaced (unknown = everything).
+ * @property {string[]} scheduledEffects - Names of effects invoked.
+ * @property {number} durationMs
+ * @property {string | null} errorCode - The `JA2xxx` code when the
+ *   transaction failed or was rejected.
+ * @property {any} [payload]
+ * @property {any} [event]
+ */
+
+/**
+ * @callback Dispatch
+ * @param {string} name - The action name.
+ * @param {any} [payload] - Bound to `$payload` (`null` when absent).
+ * @param {any} [domEvent] - A DOM event to derive `$event` from.
+ * @param {string[] | null} [eventFields] - Extra `$event` field names to
+ *   resolve from the event (the binding's `event` member; headless
+ *   callers get the same capability).
+ * @returns {void}
+ */
+
+/** The aggregate envelope message for multiple same-drain sink
+ * failures (see `safeError`); exact-match tested so nesting flattens. */
+const MULTIPLE_SINK_FAILURES = 'multiple failures surfaced in one drain';
+
+/**
+ * Compile an app document and start the loop.
+ *
+ * Boot is a transaction: compiling the documents, creating the
+ * renderer, validating the initial state, starting the initial
+ * subscriptions, painting the first frame and draining the dispatches
+ * queued by starting handlers either all succeed, or every
+ * already-acquired resource (subscriptions, effect handlers, the
+ * renderer — the container ends empty) is disposed and `createApp`
+ * throws `JA0007` (an `AppCompileError` carrying the original failure
+ * as `cause`). `onError` observes individual boot-time failures first —
+ * a sink that swallows a subscription-start failure, the initial-state
+ * check or an error inside queued boot work recovers it and boots the
+ * rest; renderer-construction and first-frame failures are always
+ * fatal; the default rethrowing sink aborts boot on any of them. After
+ * a successful boot the returned app never throws from `createApp`
+ * paths again.
+ *
+ * @param {any} appDoc
+ * @param {AppOptions} [options]
+ */
+export function createApp(appDoc, options = {}) {
+  if (appDoc === null || typeof appDoc !== 'object' || Array.isArray(appDoc)) {
+    throw new AppCompileError('JA0001', 'the app document must be an object', '');
+  }
+  if (appDoc.view === undefined) {
+    throw new AppCompileError('JA0002', 'the app document has no "view" stylesheet', '/view');
+  }
+  const queryOptions = { compileTypeTest: options.compileTypeTest };
+
+  let view;
+  try {
+    // memoized rule outputs: unchanged state subtrees yield reference-
+    // equal vnodes frame over frame, so the renderer's === fast path
+    // skips them (VIEW-FORMAT §5.1). Vnodes are immutable by contract,
+    // which is exactly the discipline memoization needs.
+    view = compileJsltStylesheet(appDoc.view, { ...queryOptions, memo: true });
+  }
+  catch (err) {
+    const cause = toError(err);
+    throw new AppCompileError('JA0002',
+      `the "view" stylesheet failed to compile: ${safeErrorMessage(cause)}`,
+      '/view', cause);
+  }
+  const actions = compileActions(appDoc.actions, queryOptions);
+  const subs = compileSubs(appDoc.subs, queryOptions);
+
+  const effectHandlers = options.effects ?? {};
+  const subHandlers = options.subs ?? {};
+  const eventExtractors = options.eventFields ?? {};
+  const onError = options.onError ?? ((err) => { throw err; });
+  const schedule = options.schedule ?? ((flush) => queueMicrotask(flush));
+  const afterRender = options.afterRender ?? null;
+  const maxTurns = options.maxTurns ?? 1000;
+  // a loop guard that silently coerces (NaN, '50', 2.5, 0) is no guard
+  if (!Number.isInteger(maxTurns) || maxTurns <= 0) {
+    throw new TypeError('createApp: options.maxTurns must be a positive integer');
+  }
+  // Fan-out containment (D-discipline: a bound is printed, never
+  // silent): a `for` subscription resolving more instances than this
+  // reports JA2017 and keeps its previous instance set.
+  const maxSubInstances = options.maxSubInstances ?? 256;
+  if (!Number.isInteger(maxSubInstances) || maxSubInstances <= 0) {
+    throw new TypeError('createApp: options.maxSubInstances must be a positive integer');
+  }
+  const capturePayloads = options.capturePayloads === true;
+
+  let state = appDoc.state;
+  let running = true;
+  let destroyed = false;
+  let renderScheduled = false;
+  /** @type {Set<(state: any, changes: string[] | null) => void>} */
+  const stateListeners = new Set();
+  /** @type {Set<(tx: TransactionRecord) => void>} */
+  const observers = new Set();
+  /** Per compiled sub: the single-instance slot (`live`/`cleanup` plus
+   * the dynamic restart `key`) and, for `for` declarations, the keyed
+   * instance map (`key -> { cleanup, propsKey }`, insertion order =
+   * document order of the resolved item sequence). */
+  const subStates = subs.map(() => ({
+    live: false, cleanup: undefined, key: null,
+    /** True while this slot's handler is running: ownership is claimed
+     * before the handler, so a re-entrant reconciliation cannot start the
+     * same subscription a second time and orphan the first acquisition. */
+    starting: false,
+    /** @type {Map<string, { cleanup: any, propsKey: string }> | null} */
+    instances: null,
+  }));
+
+  /**
+   * The FIFO transaction queue (APP-FORMAT §8). Entries carry the
+   * already-JSON-reduced event — native events never wait in the queue.
+   * A `replace` entry carries a whole next state instead of an action
+   * name: `setState` is a transaction like any other, so it serializes
+   * with dispatches rather than cutting in front of them.
+   * @type {Array<{ kind?: 'replace', state?: any, source: string, name: string, payload: any, event: any, unknownFields: string[] | null, extractorFailures: Array<{ field: string, value: unknown }> | null }>}
+   */
+  const actionQueue = [];
+  let draining = false;
+  let txSeq = 0;
+  /**
+   * Every value the `onError` sink threw while the drain was running,
+   * in report order — a FRAMEWORK-OWNED array, never a structure
+   * derived from the values themselves: appending performs no
+   * reflection or coercion on a sink-thrown value (a revoked proxy, a
+   * hostile accessor or a host-created AggregateError is stored and
+   * later surfaced BY IDENTITY, one element each). The drain always
+   * completes; the failures surface to the outermost caller afterwards
+   * — a single value as itself, several as one AggregateError over the
+   * originals in report order.
+   * @type {unknown[]}
+   */
+  const pendingFailures = [];
+
+  /** @type {(((vnode: any) => void) & { destroy?: () => void }) | null} */
+  let renderer = null;
+  /** Boot atomicity for the frame callback: frames committed while the
+   * boot transaction runs defer `afterRender` (see the renderer's
+   * `onFrame` wiring); after a successful boot one deferred call
+   * fires. A failed boot never fires it. */
+  let booted = false;
+  let bootFrameLive = false;
+  /**
+   * Effect-handler identities, snapshotted inside the boot rollback
+   * BEFORE any resource is acquired: disposal must never depend on
+   * re-enumerating a host registry at destroy time (a hostile
+   * enumeration would skip every disposer with resources already
+   * live). An unenumerable registry fails the boot instead —
+   * rejection before ownership.
+   * @type {Array<[string, any]> | null}
+   */
+  let effectDisposeEntries = null;
+
+  /**
+   * Report an error without ever breaking the drain: the sink runs, and
+   * anything it throws parks on `pendingError` until the drain (or the
+   * calling entry point) finishes.
+   * @param {Error} err
+   */
+  function safeError(err) {
+    try {
+      onError(err);
+    }
+    catch (thrown) {
+      pendingFailures.push(thrown);
+    }
+  }
+
+  /**
+   * Surface the parked sink failures at an entry-point boundary: one
+   * failure crosses by identity; several cross as one AggregateError
+   * over the originals in report order (a host-created AggregateError
+   * stays ONE element — nothing is ever inspected or flattened).
+   */
+  function flushPendingError() {
+    if (pendingFailures.length === 0) return;
+    const failures = pendingFailures.splice(0);
+    if (failures.length === 1) throw failures[0];
+    throw new AggregateError(failures, MULTIPLE_SINK_FAILURES);
+  }
+
+  /**
+   * Queue one transaction and drain if no drain is running. The native
+   * event is reduced to JSON here, synchronously — by the time the
+   * transaction runs, the event object may be recycled by the browser.
+   * @param {string} source
+   * @param {string} name
+   * @param {any} payload
+   * @param {any} domEvent
+   * @param {string[] | null} eventFields
+   */
+  function queueDispatch(source, name, payload, domEvent, eventFields) {
+    if (!running) return;
+    let event = null;
+    let unknownFields = null;
+    let extractorFailures = null;
+    if (domEvent !== null && domEvent !== undefined) {
+      /** @type {string[]} */
+      const unknown = [];
+      /** @type {Array<{ field: string, value: unknown }>} */
+      const failures = [];
+      // tagged outcomes: a thrown `undefined` is a FAILURE, structurally
+      // distinct from an unknown field — the two must never share a signal
+      event = eventData(domEvent, eventFields, eventExtractors,
+        (outcome) => {
+          if (outcome.kind === 'unknown') unknown.push(outcome.field);
+          else failures.push({ field: outcome.field, value: outcome.value });
+        });
+      if (unknown.length > 0) unknownFields = unknown;
+      if (failures.length > 0) extractorFailures = failures;
+    }
+    actionQueue.push({ source, name, payload, event, unknownFields, extractorFailures });
+    drainQueue();
+  }
+
+  /**
+   * Queue a whole-state replacement and drain if no drain is running.
+   * @param {any} next
+   */
+  function queueReplace(next) {
+    if (!running) return;
+    actionQueue.push({
+      kind: 'replace',
+      state: next,
+      source: 'setState',
+      name: 'setState',
+      payload: null,
+      event: null,
+      unknownFields: null,
+      extractorFailures: null,
+    });
+    drainQueue();
+  }
+
+  /** Drain the queue to empty; the sole caller of `runTransaction`. */
+  function drainQueue() {
+    if (draining) return;
+    draining = true;
+    let turns = 0;
+    try {
+      while (actionQueue.length > 0) {
+        if (++turns > maxTurns) {
+          actionQueue.length = 0;
+          safeError(new AppRuntimeError('JA2010',
+            `the dispatch loop exceeded ${maxTurns} queued transactions in one drain; `
+            + 'the queue was abandoned (an action/effect dispatch loop?)'));
+          break;
+        }
+        const entry = /** @type {NonNullable<ReturnType<typeof actionQueue.shift>>} */ (actionQueue.shift());
+        runTransaction(entry);
+      }
+    }
+    finally {
+      draining = false;
+    }
+    flushPendingError();
+  }
+
+  /** @type {Dispatch} */
+  function dispatch(name, payload = null, domEvent = null, eventFields = null) {
+    queueDispatch('dispatch', name, payload, domEvent, eventFields);
+  }
+
+  /** The dispatch handed to effect handlers: tags the source. */
+  function effectDispatch(name, payload = null, domEvent = null, eventFields = null) {
+    queueDispatch('effect', name, payload, domEvent, eventFields);
+  }
+
+  /** The dispatch handed to subscription handlers: tags the source. */
+  function subDispatch(name, payload = null, domEvent = null, eventFields = null) {
+    queueDispatch('subscription', name, payload, domEvent, eventFields);
+  }
+
+  /**
+   * An `on` binding fired by the renderer (or a widget's `emit`): an
+   * action name, or `{ "action": name, "with"?: payload, "event"?:
+   * [fieldName, ...], "preventDefault"?: bool, "stopPropagation"?:
+   * bool }`. The two native controls run synchronously in the event
+   * callback, before the transaction is queued — but only a REGISTERED
+   * action owns the native behavior: an unknown action name suppresses
+   * nothing (it still queues and reports `JA2001`). A registered action
+   * that later fails keeps its already-applied modifiers — whether the
+   * action succeeds cannot retroactively change them. Headless events
+   * without the methods are a documented no-op.
+   * @param {any} binding
+   * @param {any} event
+   */
+  function handleBinding(binding, event) {
+    if (typeof binding === 'string') {
+      queueDispatch('binding', binding, null, event, null);
+      return;
+    }
+    if (binding !== null && typeof binding === 'object'
+      && typeof binding.action === 'string'
+      && (binding.event === undefined || isFieldNameArray(binding.event))
+      && (binding.preventDefault === undefined || typeof binding.preventDefault === 'boolean')
+      && (binding.stopPropagation === undefined || typeof binding.stopPropagation === 'boolean')) {
+      const registered = actions.has(binding.action);
+      if (registered && binding.preventDefault === true
+        && typeof event?.preventDefault === 'function') {
+        event.preventDefault();
+      }
+      if (registered && binding.stopPropagation === true
+        && typeof event?.stopPropagation === 'function') {
+        event.stopPropagation();
+      }
+      queueDispatch('binding', binding.action, binding.with ?? null, event, binding.event ?? null);
+      return;
+    }
+    safeError(new AppRuntimeError('JA2001',
+      `unusable event binding: ${JSON.stringify(binding)}`));
+    if (!draining) flushPendingError();
+  }
+
+  /**
+   * Run one queued transaction to completion: evaluate the action,
+   * commit the state, invoke effects, notify listeners, reconcile
+   * subscriptions, schedule the render, then notify observers.
+   * @param {{ source: string, name: string, payload: any, event: any, unknownFields: string[] | null, extractorFailures: Array<{ field: string, value: unknown }> | null }} entry
+   */
+  function runTransaction(entry) {
+    const started = now();
+    const seq = ++txSeq;
+    /** @type {'applied' | 'noop' | 'rejected' | 'failed'} */
+    let status = 'noop';
+    /** @type {string | null} */
+    let errorCode = null;
+    /** @type {string[] | null} */
+    let changes = null;
+    /** @type {string[]} */
+    const scheduledEffects = [];
+    /** Whether this transaction already scheduled a render (state changed). */
+    let renderScheduled = false;
+
+    // a typo in one requested event field binds null and reports; the
+    // dispatch itself is never dropped (JA2009 contract)
+    if (entry.unknownFields !== null) {
+      for (const field of entry.unknownFields) {
+        safeError(new AppRuntimeError('JA2009',
+          `a binding requested an unknown event field '${field}'`));
+      }
+    }
+    // an extractor is host code: a throw surfaces as the dispatching
+    // action's JA2002 (APP-FORMAT §5.4), the member binds null, and the
+    // dispatch itself is never dropped
+    if (entry.extractorFailures !== null) {
+      for (const { field, value } of entry.extractorFailures) {
+        const cause = toError(value);
+        safeError(new AppRuntimeError('JA2002',
+          `action '${entry.name}' event-field extractor '${field}' threw: ${safeErrorMessage(cause)}`,
+          { cause }));
+      }
+    }
+
+    // ————— a whole-state replacement (`setState`) —————
+    // It commits through the SAME path as an action: validated before
+    // commit, listeners in registration order over one state/changes pair,
+    // subscriptions reconciled once, one render scheduled, one record
+    // observed. Replacing state outside the queue broke every one of those
+    // — validation was skipped, a listener that dispatched saw its own
+    // transaction interleaved, and a sink failure surfaced out of the next
+    // unrelated dispatch instead of at the setState caller.
+    if (entry.kind === 'replace') {
+      const next = entry.state;
+      if (next === state) {
+        finish('noop', null);
+        return;
+      }
+      if (options.validateState !== undefined) {
+        let verdict;
+        try {
+          verdict = options.validateState(next, {
+            previous: state,
+            // the replacement is not an action; the context says so rather
+            // than borrowing a name no reducer ran under
+            action: null,
+            payload: null,
+            changes: null,
+          });
+        }
+        catch (err) {
+          const cause = toError(err);
+          safeError(new AppRuntimeError('JA2015',
+            `the validateState hook threw for an external state replacement: ${safeErrorMessage(cause)}`,
+            { cause }));
+          finish('failed', 'JA2015');
+          return;
+        }
+        if (verdict === false
+          || (verdict !== null && typeof verdict === 'object' && verdict.valid === false)) {
+          const err = new AppRuntimeError('JA2005',
+            'an external state replacement violated the app\'s state invariants; it was rejected');
+          err.detail = typeof verdict === 'object' ? verdict.errors : undefined;
+          safeError(err);
+          finish('rejected', 'JA2005');
+          return;
+        }
+      }
+      state = next;
+      for (const listener of stateListeners) {
+        try {
+          listener(state, null);
+        }
+        catch (err) {
+          const cause = toError(err);
+          safeError(new AppRuntimeError('JA2011',
+            `a state listener threw: ${safeErrorMessage(cause)}`, { cause }));
+        }
+      }
+      refreshSubs();
+      scheduleRender();
+      renderScheduled = true;
+      finish('applied', null);
+      return;
+    }
+
+    const action = actions.get(entry.name);
+    if (action === undefined) {
+      safeError(new AppRuntimeError('JA2001', `unknown action '${entry.name}'`));
+      finish('failed', 'JA2001');
+      return;
+    }
+
+    let transition;
+    try {
+      transition = action.first(state, { event: entry.event, payload: entry.payload });
+    }
+    catch (err) {
+      const cause = toError(err);
+      safeError(new AppRuntimeError('JA2002',
+        `action '${entry.name}' failed: ${safeErrorMessage(cause)}`, { cause }));
+      finish('failed', 'JA2002');
+      return;
+    }
+
+    if (transition === undefined || transition === null) {
+      finish('noop', null);
+      return;
+    }
+    if (typeof transition !== 'object' || Array.isArray(transition)) {
+      safeError(new AppRuntimeError('JA2003',
+        `action '${entry.name}' produced a transition that is not an object`));
+      finish('failed', 'JA2003');
+      return;
+    }
+
+    let next = state;
+    // changed paths for this transition: an array of JSON Pointers when
+    // the transition was patch-only (the engine's tracked writes), else
+    // null = "unknown, treat everything as changed"
+    if ('state' in transition) next = transition.state;
+    if (transition.patch !== undefined) {
+      try {
+        const tracked = applyJSONPatch(next, transition.patch, { changes: true });
+        next = tracked.doc;
+        if (!('state' in transition)) changes = tracked.changes;
+      }
+      catch (err) {
+        const cause = toError(err);
+        safeError(new AppRuntimeError('JA2004',
+          `action '${entry.name}' produced a patch that failed to apply: ${safeErrorMessage(cause)}`,
+          { cause }));
+        finish('failed', 'JA2004');
+        return;
+      }
+    }
+    if (next !== state && options.validateState !== undefined) {
+      let verdict;
+      try {
+        verdict = options.validateState(next, {
+          previous: state,
+          action: entry.name,
+          payload: entry.payload,
+          changes,
+        });
+      }
+      catch (err) {
+        // the validator is host code: a throw is its own failure mode
+        // (JA2015), never a rejection verdict — the transaction fails,
+        // the queue keeps draining
+        const cause = toError(err);
+        safeError(new AppRuntimeError('JA2015',
+          `the validateState hook threw for action '${entry.name}': ${safeErrorMessage(cause)}`,
+          { cause }));
+        finish('failed', 'JA2015');
+        return;
+      }
+      if (verdict === false
+        || (verdict !== null && typeof verdict === 'object' && verdict.valid === false)) {
+        const err = new AppRuntimeError('JA2005',
+          `action '${entry.name}' violated the app's state invariants; transition rejected`);
+        err.detail = typeof verdict === 'object' ? verdict.errors : undefined;
+        safeError(err);
+        finish('rejected', 'JA2005');
+        return;
+      }
+    }
+
+    const changed = next !== state;
+    state = next;
+    if (transition.effects !== undefined) {
+      runEffects(entry.name, transition.effects, scheduledEffects);
+    }
+    if (changed) {
+      for (const listener of stateListeners) {
+        try {
+          listener(state, changes);
+        }
+        catch (err) {
+          const cause = toError(err);
+          safeError(new AppRuntimeError('JA2011',
+            `a state listener threw: ${safeErrorMessage(cause)}`, { cause }));
+        }
+      }
+      refreshSubs();
+      scheduleRender();
+      renderScheduled = true;
+    }
+    finish(changed || scheduledEffects.length > 0 ? 'applied' : 'noop', null);
+
+    /**
+     * Build the transaction record and notify observers (isolated: an
+     * observer failure never reaches the queue).
+     * @param {'applied' | 'noop' | 'rejected' | 'failed'} finalStatus
+     * @param {string | null} code
+     */
+    function finish(finalStatus, code) {
+      status = finalStatus;
+      errorCode = code;
+      // Settlement: a DOM event (a `binding` source) may have moved a
+      // controlled input off authoritative state — a user keystroke — and if
+      // this transaction did not itself change state (a no-op, a rejected or
+      // failed action, an effects-only outcome) no render was scheduled, so
+      // the control would keep the user's value. Schedule one render so the
+      // view reasserts controlled values against the live DOM. It is cheap:
+      // unchanged state re-projects to a reference-equal vnode the patcher
+      // skips, leaving only the controlled reconciliation.
+      if (entry.source === 'binding' && !renderScheduled) {
+        renderScheduled = true;
+        scheduleRender();
+      }
+      if (observers.size === 0) return;
+      /** @type {TransactionRecord} */
+      const record = {
+        seq,
+        action: entry.name,
+        source: entry.source,
+        status,
+        changedPaths: status === 'applied' ? changes : null,
+        scheduledEffects,
+        durationMs: now() - started,
+        errorCode,
+      };
+      if (capturePayloads) {
+        record.payload = entry.payload;
+        record.event = entry.event;
+      }
+      for (const observer of observers) {
+        try {
+          observer(record);
+        }
+        catch (err) {
+          const cause = toError(err);
+          safeError(new AppRuntimeError('JA2011',
+            `a transaction observer threw: ${safeErrorMessage(cause)}`, { cause }));
+        }
+      }
+    }
+  }
+
+  /**
+   * @param {string} name
+   * @param {any} effects
+   * @param {string[]} scheduled - Records invoked effect names.
+   */
+  function runEffects(name, effects, scheduled) {
+    if (!Array.isArray(effects)) {
+      safeError(new AppRuntimeError('JA2003',
+        `action '${name}' produced "effects" that are not an array`));
+      return;
+    }
+    for (const effect of effects) {
+      const run = effect?.run;
+      // registry member acquisition is host-observable (the registry
+      // may be a proxy or carry accessors): lookup and invocation
+      // share one boundary and one failure policy (JA2007)
+      let handler;
+      try {
+        handler = typeof run === 'string' ? effectHandlers[run] : undefined;
+      }
+      catch (err) {
+        const cause = toError(err);
+        safeError(new AppRuntimeError('JA2007',
+          `effect '${String(run)}' threw during lookup: ${safeErrorMessage(cause)}`, { cause }));
+        continue;
+      }
+      if (handler === undefined) {
+        safeError(new AppRuntimeError('JA2006',
+          `action '${name}' invoked unregistered effect '${String(run)}'`));
+        continue;
+      }
+      scheduled.push(run);
+      try {
+        handler(effect.with ?? null, effectDispatch);
+      }
+      catch (err) {
+        const cause = toError(err);
+        safeError(new AppRuntimeError('JA2007',
+          `effect '${run}' threw: ${safeErrorMessage(cause)}`, { cause }));
+      }
+    }
+  }
+
+  /**
+   * The restart key of a resolved value, BY VALUE: `stableStringify`
+   * (never `stableKeyString` — package-private to the query engine, and
+   * its `NaN`-by-name rule is a grouping decision this key does not
+   * want). `undefined` (an empty query result) normalizes to `null`
+   * first, so absence keys deterministically. A cyclic value overflows
+   * `stableStringify` (it has no cycle guard) — callers catch and reject
+   * with `JA2016` rather than hanging.
+   * @param {any} value
+   * @returns {string}
+   */
+  function subKeyOf(value) {
+    return stableStringify(value === undefined ? null : value) ?? 'null';
+  }
+
+  /**
+   * Report a failing dynamic subscription member (`withQuery`, `key`,
+   * `for`) — `JA2016`, carrying the member's own docPath. The
+   * subscription fails CLOSED, like a broken `when`.
+   * @param {any} sub
+   * @param {number} i
+   * @param {string} member
+   * @param {unknown} err
+   */
+  function reportSubQueryFailure(sub, i, member, err) {
+    const cause = toError(err);
+    safeError(new AppRuntimeError('JA2016',
+      `subscription '${sub.run}' has a "${member}" that failed: ${safeErrorMessage(cause)}`,
+      { docPath: `/subs/${i}/${member === 'keyQuery' ? 'key' : member}`, cause }));
+  }
+
+  /**
+   * Look up a subscription handler; `undefined` after a report means
+   * "cannot start" (`JA2008`/`JA2013`-lookup, matching the historical
+   * single-instance behaviour).
+   * @param {any} sub
+   * @returns {any}
+   */
+  function lookupSubHandler(sub) {
+    let handler;
+    try {
+      handler = subHandlers[sub.run];
+    }
+    catch (err) {
+      const cause = toError(err);
+      safeError(new AppRuntimeError('JA2013',
+        `subscription '${sub.run}' threw during lookup; it stays stopped: ${safeErrorMessage(cause)}`,
+        { cause }));
+      return undefined;
+    }
+    if (handler === undefined) {
+      safeError(new AppRuntimeError('JA2008',
+        `subscription '${sub.run}' has no registered handler`));
+    }
+    return handler;
+  }
+
+  /**
+   * Run one subscription cleanup with the standard isolation (`JA2012`
+   * via `reportCleanup`, so destroy-scope collection still applies).
+   * @param {any} sub
+   * @param {any} cleanup
+   */
+  function runSubCleanup(sub, cleanup) {
+    if (typeof cleanup !== 'function') return;
+    try {
+      cleanup();
+    }
+    catch (err) {
+      const cause = toError(err);
+      reportCleanup(
+        `subscription '${sub.run}' threw while cleaning up: ${safeErrorMessage(cause)}`,
+        cause);
+    }
+  }
+
+  /**
+   * Reconcile a `for` declaration's keyed instance set against the
+   * current state: stop removed instances (previous insertion order),
+   * then start added — and restart changed — instances in the document
+   * order of the resolved item sequence. Duplicate keys collapse to the
+   * first occurrence. Resolution failures fail the whole declaration
+   * closed (`JA2016`); exceeding `maxSubInstances` reports `JA2017` and
+   * keeps the previous set (the bound is printed, never silent).
+   * @param {any} sub
+   * @param {any} slot
+   * @param {number} i
+   * @param {boolean} live
+   */
+  function refreshFanout(sub, slot, i, live) {
+    const instances = slot.instances ?? (slot.instances = new Map());
+    let next = null;
+    /** Set when the fan-out bound was crossed mid-enumeration. */
+    let overflow = 0;
+    if (live) {
+      next = new Map();
+      let failingMember = 'for';
+      try {
+        const resolved = sub.forQuery(state);
+        const items = resolved === undefined ? []
+          : Array.isArray(resolved) ? resolved : [resolved];
+        for (let k = 0; k < items.length; k++) {
+          // The bound stops the WORK, not just the retained instances.
+          // Checking it after the loop bounded what was kept while a
+          // runaway `for` query still ran every key and props expression
+          // and serialized every result first — so the limit cost memory
+          // and CPU proportional to the mistake it was there to contain.
+          if (next.size >= maxSubInstances) {
+            overflow = next.size + (items.length - k);
+            break;
+          }
+          const item = items[k];
+          failingMember = sub.keyQuery !== null ? 'key' : 'for';
+          const key = sub.keyQuery !== null
+            ? subKeyOf(sub.keyQuery(state, { item }))
+            : subKeyOf(item);
+          if (next.has(key)) continue; // duplicates collapse, first wins
+          let props;
+          if (sub.withQuery !== null) {
+            failingMember = 'withQuery';
+            const v = sub.withQuery(state, { item });
+            props = v === undefined ? null : v;
+          }
+          else {
+            props = item === undefined ? null : item;
+          }
+          const propsKey = sub.withQuery !== null ? subKeyOf(props) : key;
+          next.set(key, { props, propsKey });
+          failingMember = 'for';
+        }
+      }
+      catch (err) {
+        reportSubQueryFailure(sub, i, failingMember, err);
+        next = null; // fail closed: treat as not live this refresh
+      }
+      if (next !== null && overflow > 0) {
+        safeError(new AppRuntimeError('JA2017',
+          `subscription '${sub.run}' fan-out reached maxSubInstances (${maxSubInstances}) `
+          + `with at least ${overflow} items to resolve; enumeration stopped there`,
+          { docPath: `/subs/${i}/for` }));
+        return; // the previous instance set is kept, deliberately
+      }
+    }
+    if (next === null) { // dead (or failed closed): stop everything
+      if (instances.size === 0) return;
+      for (const [key, inst] of [...instances]) {
+        instances.delete(key);
+        runSubCleanup(sub, inst.cleanup);
+      }
+      return;
+    }
+    // stops first, in previous insertion order
+    for (const [key, inst] of [...instances]) {
+      if (!next.has(key)) {
+        instances.delete(key);
+        runSubCleanup(sub, inst.cleanup);
+      }
+    }
+    // starts and restarts, in resolved document order; the handler is
+    // looked up lazily so a refresh with nothing to start reports no
+    // JA2008, matching the single-instance path's would-start timing
+    let handler;
+    let handlerLooked = false;
+    for (const [key, spec] of next) {
+      const existing = instances.get(key);
+      if (existing !== undefined && existing.propsKey === spec.propsKey)
+        continue; // unchanged instance: untouched
+      if (!handlerLooked) {
+        handlerLooked = true;
+        handler = lookupSubHandler(sub);
+      }
+      if (handler === undefined) break; // reported; retried next refresh
+      if (existing !== undefined) {
+        instances.delete(key);
+        runSubCleanup(sub, existing.cleanup); // restart: stop-then-start
+      }
+      let cleanup;
+      try {
+        cleanup = handler(spec.props, subDispatch);
+      }
+      catch (err) {
+        const cause = toError(err);
+        safeError(new AppRuntimeError('JA2013',
+          `subscription '${sub.run}' threw while starting; it stays stopped: ${safeErrorMessage(cause)}`,
+          { cause }));
+        continue; // this instance stays stopped; siblings proceed
+      }
+      instances.set(key, { cleanup, propsKey: spec.propsKey });
+    }
+  }
+
+  /**
+   * Start and stop subscriptions to match their `when` queries against
+   * the current state. A broken `when` — or a broken dynamic member
+   * (`withQuery`/`key`/`for`, `JA2016`) — fails CLOSED (the
+   * subscription stops; a broken rule must never keep side effects
+   * alive) and is reported through `onError`.
+   *
+   * A DYNAMIC subscription (one with `withQuery`) also restarts when
+   * its resolved key changes: stop, then start with the new props,
+   * within one reconciliation. The key derives from the resolved props
+   * by value, or from the explicit `key` query; a static `with` entry
+   * has no key and never restarts (the historical behaviour, preserved
+   * exactly). `for` declarations reconcile per instance
+   * ({@link refreshFanout}). This is the same "key plus supersede
+   * policy" shape `createTaskEffect` models for effects.
+   *
+   * Startup is resource acquisition: a slot is committed live only
+   * after its handler returned. A throwing handler leaves the slot
+   * stopped (`JA2013`); a throwing cleanup is isolated (`JA2012`) and
+   * never skips its siblings — and never prevents the restart's start
+   * half. Because dispatches queue (they never nest), condition changes
+   * made by a starting handler coalesce: they are observed by the next
+   * transaction's reconciliation, which then disposes the just-started
+   * resource through the ordinary stop path.
+   */
+  function refreshSubs() {
+    for (let i = 0; i < subs.length; i++) {
+      const sub = subs[i];
+      const slot = subStates[i];
+      let live = running;
+      if (live && sub.when !== null) {
+        try {
+          live = sub.when.ebv(state);
+        }
+        catch (err) {
+          live = false;
+          const cause = toError(err);
+          safeError(new AppRuntimeError('JA2002',
+            `subscription '${sub.run}' has a "when" that failed: ${safeErrorMessage(cause)}`, { cause }));
+        }
+      }
+      if (sub.forQuery !== null) {
+        refreshFanout(sub, slot, i, live);
+        continue;
+      }
+      // resolve dynamic props and the restart key while live
+      let props = sub.props;
+      let key = null;
+      if (live && sub.withQuery !== null) {
+        try {
+          const v = sub.withQuery(state);
+          props = v === undefined ? null : v;
+        }
+        catch (err) {
+          live = false;
+          reportSubQueryFailure(sub, i, 'withQuery', err);
+        }
+      }
+      if (live && (sub.withQuery !== null || sub.keyQuery !== null)) {
+        try {
+          key = sub.keyQuery !== null
+            ? subKeyOf(sub.keyQuery(state))
+            : subKeyOf(props);
+        }
+        catch (err) {
+          live = false;
+          reportSubQueryFailure(sub, i, sub.keyQuery !== null ? 'key' : 'withQuery', err);
+        }
+      }
+      const restart = live && slot.live && key !== slot.key;
+      if (restart || (!live && slot.live)) {
+        const cleanup = slot.cleanup;
+        slot.live = false;
+        slot.cleanup = undefined;
+        slot.key = null;
+        runSubCleanup(sub, cleanup);
+      }
+      if (live && !slot.live && !slot.starting) {
+        const handler = lookupSubHandler(sub);
+        if (handler === undefined) continue;
+        let cleanup;
+        // Ownership is claimed BEFORE the handler runs. A handler may
+        // acquire a resource and then re-enter reconciliation — it is host
+        // code, and the app surface is reachable from it — and a slot that
+        // only became `live` on the way out looked startable to that
+        // re-entry. It started again, and again, and each return overwrote
+        // the single cleanup slot: every acquisition but the last leaked,
+        // past destroy, forever.
+        slot.starting = true;
+        try {
+          cleanup = handler(props, subDispatch);
+        }
+        catch (err) {
+          slot.starting = false;
+          const cause = toError(err);
+          safeError(new AppRuntimeError('JA2013',
+            `subscription '${sub.run}' threw while starting; it stays stopped: ${safeErrorMessage(cause)}`,
+            { cause }));
+          continue;
+        }
+        slot.starting = false;
+        slot.live = true;
+        slot.cleanup = cleanup;
+        slot.key = key;
+      }
+    }
+  }
+
+  function scheduleRender() {
+    if (renderer === null || renderScheduled) return;
+    if (!booted) {
+      // boot is ATOMIC under every scheduler: a boot frame commits
+      // inside the boot window, never on a later microtask — a paint
+      // pending outside the transaction would leave the deferred first
+      // `afterRender` running against the OLD DOM, missing targets the
+      // boot transaction already placed in state
+      try {
+        render();
+      }
+      catch (err) {
+        safeError(toError(err));
+      }
+      return;
+    }
+    renderScheduled = true;
+    schedule(() => {
+      renderScheduled = false;
+      if (!running) return;
+      // a renderer failure (a throwing widget hook) always routes
+      // through the app error policy: under a synchronous scheduler it
+      // must not corrupt the transaction queue (the parked error
+      // surfaces after the drain); under a deferred scheduler `onError`
+      // observes it and whatever the sink throws surfaces to the
+      // scheduler's context
+      try {
+        render();
+      }
+      catch (err) {
+        safeError(toError(err));
+      }
+      if (!draining) flushPendingError();
+    });
+  }
+
+  const viewModel = options.viewModel ?? null;
+
+  /** The current view output (through the viewModel derivation). */
+  function vnode() {
+    return view(viewModel !== null ? viewModel(state) : state);
+  }
+
+  /** Render synchronously, now. `afterRender` is NOT called here: the
+   * renderer's `onFrame` channel invokes it exactly once per settled,
+   * nonterminal committed frame — a normal return is the wrong signal
+   * (the renderer may have performed terminal teardown, or may be
+   * about to deliver a parked widget error for a frame that DID
+   * commit). */
+  function render() {
+    if (renderer === null) return;
+    renderDepth++;
+    try {
+      renderer(vnode());
+    }
+    finally {
+      renderDepth--;
+      // catch-all: a destroy requested inside this pass (a widget
+      // hook calling app.destroy()) deferred the renderer teardown
+      // into the pass itself — deliver the destroy-wide cleanup
+      // outcome as the pass unwinds, never earlier and never split
+      if (renderDepth === 0 && destroyed) deliverDestroyFailures();
+    }
+  }
+
+  /**
+   * Dispose every live subscription and clear the listeners; shared by
+   * stop/destroy/boot-rollback. Cleanup errors are isolated.
+   */
+  function teardownLoop() {
+    running = false;
+    actionQueue.length = 0;
+    refreshSubs();
+    stateListeners.clear();
+  }
+
+  /**
+   * The destroy-scope cleanup collector: while `destroy()` runs —
+   * INCLUDING a renderer teardown deferred to the end of the active
+   * render pass when the destroy was requested from inside a widget
+   * hook — every cleanup failure (subscription cleanups, effect
+   * disposal, renderer teardown) collects here and is delivered as
+   * ONE `JA2012` whose cause is the single failure by identity or an
+   * AggregateError over all of them in occurrence order. Outside
+   * `destroy()` (stop(), per-transaction reconciliation) each failure
+   * reports its own `JA2012` as before.
+   * @type {Error[] | null}
+   */
+  let destroyFailures = null;
+  /** Non-zero while the app's render pass is on the stack — the only
+   * path from which a widget hook can request an in-hook destroy. */
+  let renderDepth = 0;
+
+  /** Deliver the destroy-wide cleanup outcome exactly once. */
+  function deliverDestroyFailures() {
+    const failures = destroyFailures;
+    destroyFailures = null;
+    if (failures !== null && failures.length > 0) {
+      const cause = failures.length === 1
+        ? failures[0]
+        : new AggregateError(failures, 'multiple cleanup failures in one destroy');
+      safeError(new AppRuntimeError('JA2012',
+        `cleanup failed while destroying the app: ${failures.length} failure(s)`,
+        { cause: /** @type {any} */ (cause) }));
+    }
+  }
+
+  /**
+   * Route one cleanup failure: into the destroy-scope collector when
+   * one is active, else as its own immediate `JA2012` report.
+   * @param {string} message
+   * @param {Error} cause
+   */
+  function reportCleanup(message, cause) {
+    if (destroyFailures !== null) destroyFailures.push(cause);
+    else safeError(new AppRuntimeError('JA2012', message, { cause }));
+  }
+
+  /** Dispose registered effect handlers, each identity exactly once.
+   * Capability ACQUISITION shares the invocation boundary: a hostile
+   * key enumeration, member read or `dispose` accessor is a cleanup
+   * failure like a throwing `dispose()` — later disposers and the
+   * renderer teardown always still run. */
+  function disposeEffectHandlers() {
+    if (effectDisposeEntries === null) return; // boot failed before the snapshot
+    const seen = new Set();
+    for (const [name, handler] of effectDisposeEntries) {
+      try {
+        if (handler === undefined || handler === null || seen.has(handler)) continue;
+        seen.add(handler);
+        const dispose = /** @type {any} */ (handler).dispose;
+        if (typeof dispose === 'function') dispose.call(handler);
+      }
+      catch (err) {
+        const cause = toError(err);
+        reportCleanup(
+          `effect handler '${name}' threw while disposing: ${safeErrorMessage(cause)}`,
+          cause);
+      }
+    }
+  }
+
+  // boot: renderer construction, the initial-state check, the initial
+  // subscriptions, the first frame AND the queued work they produce are
+  // one transaction — any failure that would escape createApp rolls
+  // back every acquired resource (subscriptions, effect handlers, the
+  // renderer; the container ends empty, scheduled work becomes a no-op)
+  // and throws one JA0007. A custom onError that swallows a reported
+  // boot failure (a subscription start, the initial-state check, an
+  // error inside queued boot work) recovers it and boot continues;
+  // renderer construction and first-frame failures are always fatal.
+  {
+    /** A presence record: a boot step may legally throw `null`.
+     * @type {{ value: unknown } | null} */
+    let bootFailure = null;
+    draining = true; // dispatches made by starting handlers queue
+    try {
+      // snapshot BEFORE ownership begins (see effectDisposeEntries)
+      {
+        const entries = [];
+        for (const name of Object.keys(effectHandlers)) {
+          entries.push([name, effectHandlers[name]]);
+        }
+        effectDisposeEntries = entries;
+      }
+      if (options.node !== undefined) {
+        renderer = createDomRenderer(options.node, {
+          document: options.document,
+          onEvent: handleBinding,
+          widgets: options.widgets,
+          // terminal-cleanup provenance: a widget unmount that throws
+          // during renderer teardown — deferred teardown after an
+          // app.destroy() from inside a hook included — is a CLEANUP
+          // failure (JA2012, original cause preserved, reported after
+          // every sibling cleaned up), never an anonymous render error
+          onCleanupError: (thrown) => {
+            const cause = toError(thrown);
+            reportCleanup(
+              `the renderer threw while being destroyed: ${safeErrorMessage(cause)}`, cause);
+          },
+          // the committed-live-frame boundary: `afterRender` runs once
+          // per SETTLED, NONTERMINAL frame — after the DOM patch and
+          // widget mounts, before a parked hook error is delivered —
+          // and never after terminal teardown (APP-FORMAT §8.4). Boot
+          // is ATOMIC: frames committed during the boot transaction do
+          // not fire the callback; one deferred call runs only after
+          // the whole boot (queued drain included) succeeded, so no
+          // post-render side effect can escape a boot that rolls back.
+          onFrame: (state) => {
+            if (state !== 'live') {
+              // the pass ended in terminal teardown: a deferred
+              // in-hook destroy has now finished its renderer walk —
+              // the destroy-wide cleanup outcome is complete
+              deliverDestroyFailures();
+              return;
+            }
+            if (!booted) {
+              bootFrameLive = true;
+              return;
+            }
+            if (afterRender !== null) {
+              // isolated: an afterRender failure (the focus queue's
+              // JA2014 included) is reported through the app policy and
+              // can never starve the same frame's parked widget error,
+              // which the renderer delivers right after this returns
+              try {
+                afterRender();
+              }
+              catch (err) {
+                safeError(toError(err));
+              }
+            }
+          },
+        });
+      }
+      if (options.validateState !== undefined) {
+        validateInitialState();
+      }
+      refreshSubs();
+      render();
+    }
+    catch (err) {
+      bootFailure = { value: err };
+    }
+    finally {
+      draining = false;
+    }
+    if (bootFailure === null && pendingFailures.length > 0) {
+      const failures = pendingFailures.splice(0);
+      bootFailure = {
+        value: failures.length === 1
+          ? failures[0]
+          : new AggregateError(failures, MULTIPLE_SINK_FAILURES),
+      };
+    }
+    // subscriptions queued dispatches during boot: drain them inside
+    // the boot ownership window, so a queued failure that escapes the
+    // sink still rolls back instead of leaving a half-booted app behind
+    if (bootFailure === null) {
+      try {
+        drainQueue();
+      }
+      catch (err) {
+        bootFailure = { value: err };
+      }
+    }
+    // the boot-atomic first-frame callback: boot's frames coalesce
+    // into ONE deferred afterRender that runs only after the entire
+    // boot transaction succeeded; its failure follows boot policy (a
+    // swallowing sink recovers it, an escaping failure rolls back)
+    if (bootFailure === null) {
+      booted = true;
+      if (bootFrameLive && afterRender !== null) {
+        try {
+          afterRender();
+        }
+        catch (err) {
+          safeError(toError(err));
+        }
+        if (pendingFailures.length > 0) {
+          const failures = pendingFailures.splice(0);
+          bootFailure = {
+            value: failures.length === 1
+              ? failures[0]
+              : new AggregateError(failures, MULTIPLE_SINK_FAILURES),
+          };
+        }
+      }
+    }
+    if (bootFailure !== null) {
+      // rollback: each step is isolated so a throwing cleanup never
+      // skips its siblings; the original boot failure always wins
+      try {
+        teardownLoop();
+      }
+      catch { /* isolated */ }
+      try {
+        disposeEffectHandlers();
+      }
+      catch { /* isolated */ }
+      if (renderer !== null) {
+        try {
+          if (typeof renderer.destroy === 'function') renderer.destroy();
+        }
+        catch { /* isolated */ }
+        renderer = null;
+      }
+      pendingFailures.length = 0;
+      const cause = toError(bootFailure.value);
+      throw new AppCompileError('JA0007',
+        `the app failed to boot: ${safeErrorMessage(cause)}`, '', cause);
+    }
+  }
+
+  /**
+   * The boot-time initial-state check (see {@link ValidateContext}):
+   * a rejection is `JA2005`, a throwing validator `JA2015` — both are
+   * reported first, so a swallowing sink can accept the state and boot
+   * on; under the default rethrowing sink they abort the boot.
+   */
+  function validateInitialState() {
+    /** @type {ReturnType<NonNullable<AppOptions['validateState']>>} */
+    let verdict;
+    try {
+      verdict = /** @type {NonNullable<AppOptions['validateState']>} */ (options.validateState)(
+        state, { previous: null, action: null, payload: null, changes: null });
+    }
+    catch (err) {
+      const cause = toError(err);
+      safeError(new AppRuntimeError('JA2015',
+        `the validateState hook threw for the initial state: ${safeErrorMessage(cause)}`, { cause }));
+      return;
+    }
+    if (verdict === false
+      || (verdict !== null && typeof verdict === 'object' && verdict.valid === false)) {
+      const err = new AppRuntimeError('JA2005',
+        'the initial state violates the app\'s state invariants');
+      err.detail = typeof verdict === 'object' ? verdict.errors : undefined;
+      safeError(err);
+    }
+  }
+
+  return {
+    dispatch,
+    /** The current state (treat as immutable). */
+    getState: () => state,
+    /**
+     * Replace the whole state from OUTSIDE the action loop and re-render.
+     * Unlike `dispatch`, this runs no reducer and no effects — it is the
+     * host-driven override for external state sync: SSR hydration, or a
+     * studio hot-swapping an edited `state` block into a running nested
+     * app without a reboot (the diff re-render keeps the DOM, so focus,
+     * scroll and uncontrolled inputs survive). Listeners are notified with
+     * `null` changed-paths (treat everything as changed); `when`-gated
+     * subscriptions refresh; a render is scheduled. A no-op when the state
+     * is reference-identical or the loop has been stopped.
+     *
+     * It is a TRANSACTION, with every guarantee a dispatch has: it takes
+     * its turn in the FIFO queue, `validateState` decides before the
+     * commit, listeners all observe the same state, the turn guard counts
+     * it, one record reaches the observers, and a sink failure settles at
+     * this caller. Replacing state directly had none of those — a listener
+     * that dispatched saw the two transactions interleave and never
+     * observed its own committed state, an invalid replacement committed
+     * unvalidated, and the resulting `JA2011` emerged from the next
+     * unrelated dispatch.
+     * @param {any} next - the replacement state
+     */
+    setState(next) {
+      queueReplace(next);
+    },
+    /** The current view output — for SSR or custom renderers. */
+    getVnode: vnode,
+    render,
+    /**
+     * Observe state changes. The listener receives the new state and the
+     * transition's changed paths: an array of JSON Pointers when the
+     * transition was patch-only (see the patch engine's `changes` option
+     * for the invalidation-sound semantics), or `null` when the whole
+     * state was replaced — treat everything as changed. Listeners run
+     * inside the transaction, in registration order, all observing the
+     * same state/changes pair; a throwing listener is isolated (JA2011).
+     * @param {(state: any, changes: string[] | null) => void} listener
+     * @returns {() => void} unsubscribe
+     */
+    subscribe(listener) {
+      stateListeners.add(listener);
+      return () => { stateListeners.delete(listener); };
+    },
+    /**
+     * Observe completed transactions (APP-FORMAT §8.3). The observer
+     * receives one bounded JSON metadata record per transaction, after
+     * the transaction fully settled (state, effects, listeners,
+     * subscriptions, render scheduling). Payload/event values are
+     * included only when the app was created with `capturePayloads`.
+     * A throwing observer is isolated and never corrupts the queue.
+     * @param {(tx: TransactionRecord) => void} observer
+     * @returns {() => void} unsubscribe
+     */
+    observe(observer) {
+      observers.add(observer);
+      return () => { observers.delete(observer); };
+    },
+    /**
+     * Stop the loop — one-way and nonterminal, not a resumable pause:
+     * live subscriptions are cleaned up (isolated), listeners are
+     * cleared and further dispatches are ignored, permanently. The
+     * renderer and effect handlers stay untouched — `destroy()` is the
+     * terminal teardown that owns them.
+     */
+    stop() {
+      teardownLoop();
+      flushPendingError();
+    },
+    /**
+     * Terminal teardown: `stop()` plus observer removal, effect-handler
+     * `dispose()` (each handler identity once), and renderer
+     * destruction (widgets unmount exactly once, the container is left
+     * empty). Idempotent; scheduled render flushes become exact no-ops;
+     * every cleanup error is isolated so siblings always run.
+     */
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      destroyFailures = [];
+      teardownLoop();
+      observers.clear();
+      disposeEffectHandlers();
+      if (renderer !== null) {
+        try {
+          if (typeof renderer.destroy === 'function') renderer.destroy();
+        }
+        catch (err) {
+          const cause = toError(err);
+          reportCleanup(
+            `the renderer threw while being destroyed: ${safeErrorMessage(cause)}`, cause);
+        }
+        renderer = null;
+      }
+      // one terminal operation, one machine-readable cleanup outcome:
+      // a single failure is the cause by identity; several aggregate
+      // in occurrence order (subscriptions, then effect disposal, then
+      // the renderer walk — whose own envelope arrives as one element).
+      // When the destroy was requested from inside the active render
+      // pass, the renderer teardown is still pending — the collector
+      // stays open and delivers when that pass settles (onFrame
+      // 'destroyed', with the render unwind as the catch-all).
+      if (renderDepth === 0) deliverDestroyFailures();
+      flushPendingError();
+    },
+  };
+}
+
+/** Monotonic-ish milliseconds for transaction durations. */
+function now() {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+/**
+ * Is this value a binding's `event` member: an array of field names?
+ * @param {any} value
+ * @returns {value is string[]}
+ */
+function isFieldNameArray(value) {
+  if (!Array.isArray(value)) return false;
+  for (const name of value) {
+    if (typeof name !== 'string') return false;
+  }
+  return true;
+}
+
+/**
+ * The built-in `$event` field allow-list (APP-FORMAT §3.1): field name →
+ * where it is read from. Every entry is a JSON primitive by construction;
+ * host-object-valued fields (`target`, `files`, touch lists) are
+ * deliberately absent — `$event` must survive `JSON.stringify`, the same
+ * invariant as state. Null prototype so lookups never walk to
+ * `Object.prototype`.
+ */
+const EVENT_FIELD_SOURCES = Object.freeze(Object.assign(Object.create(null), {
+  shiftKey: 'event', ctrlKey: 'event', altKey: 'event', metaKey: 'event',
+  button: 'event', buttons: 'event',
+  clientX: 'event', clientY: 'event', offsetX: 'event', offsetY: 'event',
+  pageX: 'event', pageY: 'event', screenX: 'event', screenY: 'event',
+  movementX: 'event', movementY: 'event',
+  deltaX: 'event', deltaY: 'event', deltaMode: 'event',
+  code: 'event', repeat: 'event', location: 'event', isComposing: 'event',
+  detail: 'event',
+  pointerId: 'event', pointerType: 'event', pressure: 'event', isPrimary: 'event',
+  selectionStart: 'target', selectionEnd: 'target',
+}));
+
+/** The default `$event` members; a requested name from this set is
+ * already bound and is never overwritten (a `null` re-bind would erase
+ * real data). A registered extractor still wins — the host chose to
+ * redefine the member. */
+const DEFAULT_EVENT_MEMBERS = Object.freeze(Object.assign(Object.create(null), {
+  type: true, value: true, checked: true, key: true,
+}));
+
+/**
+ * Bind one member of the `$event` object without ever mutating a
+ * prototype: `__proto__` becomes an ordinary own data property.
+ * @param {any} obj
+ * @param {string} name
+ * @param {any} value
+ */
+function setEventMember(obj, name, value) {
+  if (name === '__proto__') {
+    Object.defineProperty(obj, name, {
+      value, writable: true, enumerable: true, configurable: true,
+    });
+  }
+  else {
+    obj[name] = value;
+  }
+}
+
+/**
+ * Resolve one requested `$event` field, in precedence order: a registered
+ * host extractor, the built-in allow-list, else `null` + a JA2009 report
+ * (a typo in one field must not swallow the dispatch). `undefined`
+ * coerces to `null` so the result stays JSON.
+ * @param {any} event
+ * @param {string} name
+ * @param {Record<string, (nativeEvent: any) => any>} extractors
+ * @param {(outcome: { kind: 'unknown', field: string }) => void} report
+ * @returns {any}
+ */
+function resolveEventField(event, name, extractors, report) {
+  const source = EVENT_FIELD_SOURCES[name];
+  if (source !== undefined) {
+    const value = source === 'target' ? event?.target?.[name] : event?.[name];
+    return value === undefined ? null : value;
+  }
+  report({ kind: 'unknown', field: name });
+  return null;
+}
+
+/**
+ * The serializable slice of a DOM event bound to `$event`: the default
+ * `{ type, value, checked, key }` plus one member per requested field
+ * name (APP-FORMAT §3.1). Runs synchronously at dispatch time — the
+ * result is plain JSON by contract, never the native event.
+ * @param {any} event
+ * @param {string[] | null} fields - Requested field names, or `null`.
+ * @param {Record<string, (nativeEvent: any) => any>} extractors
+ * @param {(outcome: { kind: 'unknown', field: string } | { kind: 'threw', field: string, value: unknown }) => void} report
+ *   The failure sink, TAGGED so a thrown `undefined` can never be
+ *   mistaken for an unknown field: `'unknown'` = the field name
+ *   resolves nowhere (JA2009), `'threw'` = a registered extractor
+ *   threw (JA2002, the thrown value retained verbatim). Either way the
+ *   member binds `null` and the dispatch continues.
+ * @returns {{ type: string, value: any, checked: any, key: any }}
+ */
+function eventData(event, fields, extractors, report) {
+  const target = event?.target;
+  const data = {
+    type: event?.type ?? '',
+    value: target?.value ?? null,
+    checked: target?.checked ?? null,
+    key: event?.key ?? null,
+  };
+  if (fields !== null) {
+    for (const name of fields) {
+      if (Object.hasOwn(extractors, name)) {
+        let value = null;
+        try {
+          const out = extractors[name](event);
+          value = out === undefined ? null : out;
+        }
+        catch (err) {
+          report({ kind: 'threw', field: name, value: err });
+        }
+        setEventMember(data, name, value);
+        continue;
+      }
+      // a requested default member is already bound; never null it out
+      if (DEFAULT_EVENT_MEMBERS[name] === true) continue;
+      setEventMember(data, name, resolveEventField(event, name, extractors, report));
+    }
+  }
+  return data;
+}