@jarenjs/app 0.34.0

package/README.md

@@ -0,0 +1,197 @@
+# @jarenjs/app
+
+Applications as JSON documents. This package rebuilds [hyperapp](https://github.com/jorgebucaran/hyperapp)'s dispatch loop on the Jaren suite and pushes its philosophy — *everything is data* — the rest of the way: hyperapp made effects and subscriptions data but kept actions and views as JavaScript functions; here **the whole application is one JSON value**:
+
+| Slot | Written as | Compiled by |
+|---|---|---|
+| `state` | a JSON document | — |
+| `view` | a [JSLT stylesheet](../json/docs/JSLT-FORMAT.md) producing [vnodes](../view/docs/VIEW-FORMAT.md) | `@jarenjs/json/jslt` |
+| `actions` | named [query documents](../json/docs/QUERY-FORMAT.md) producing transitions | `@jarenjs/json/query` |
+| transitions | next state, or an RFC 6902 **JSON Patch** | `@jarenjs/json/patch` |
+| `subs` | entries with an EBV `when` query deciding liveness | `@jarenjs/json/query` |
+
+Everything compiles **once** at `createApp` time; the running loop only calls specialized closures — the same design contract as every other Jaren engine. JavaScript enters at named, registered boundaries only: effect and subscription handlers, the `compileTypeTest` hook, the `validateState` invariant hook. No `eval`, CSP-safe, and the entire app is serializable: snapshot it, diff it, ship it over the wire, or have a constrained decoder generate it — an LLM cannot emit a syntactically invalid program in this framework.
+
+The document contract is [docs/APP-FORMAT.md](docs/APP-FORMAT.md).
+
+## A complete app
+
+```javascript
+import { createApp } from '@jarenjs/app';
+
+const app = createApp({
+  "$app": "0.1",
+  "state": { "count": 0 },
+
+  "view": [
+    { "match": "$", "body":
+      ["main", {},
+        ["h1", {}, "Count: ", "$.count"],
+        ["button", { "on": { "click": "inc" } }, "+"],
+        ["button", { "on": { "click": { "action": "add", "with": 10 } } }, "+10"]] }
+  ],
+
+  "actions": {
+    "inc": { "patch": [{ "op": "replace", "path": "/count",
+                         "value": { "$add": ["$.count", 1] } }] },
+    "add": { "patch": [{ "op": "replace", "path": "/count",
+                         "value": { "$add": ["$.count", "$payload"] } }] }
+  }
+}, { node: document.getElementById('app') });
+```
+
+The view is a JSLT stylesheet: rules match state by location (JSONPath) and shape (JSON Schema, via `compileTypeTest`), bodies are query documents producing vnodes, and `$path`/`$root` are in scope — a rule rendering `/todos/3` can embed its own pointer in an event binding, which is why there are no payload-creator functions anywhere.
+
+## Actions and transitions
+
+An action document is evaluated with `$` bound to the current state, `$event` bound to serializable event data (`{ type, value, checked, key }`) and `$payload` bound to the binding's `with` value. A binding can request more of the event declaratively — `{ "action": "selectRow", "with": { "id": "$.id" }, "event": ["shiftKey", "ctrlKey"] }` adds those members to `$event` from a closed allow-list of serializable fields (modifier keys, pointer coordinates, selection offsets, ...), and the `eventFields` option registers named JS extractors for anything the allow-list can't serialize (APP-FORMAT §3.1/§5.4). It returns a **transition**:
+
+```json
+{ "state":   "the next state, whole — optional",
+  "patch":   "an RFC 6902 patch applied copy-on-write — optional",
+  "effects": [{ "run": "http", "with": { "url": "/api" } }] }
+```
+
+Returning nothing is a no-op. State updates are immutable and structure-sharing (the patch engine's copy-on-write), which feeds the renderer's `oldVnode === newVnode` fast path.
+
+## Effects and subscriptions
+
+Side effects stay at the edges, as registered handlers:
+
+```javascript
+createApp(doc, {
+  node,
+  effects: {
+    http: (props, dispatch) =>
+      fetch(props.url).then((r) => r.json()).then((data) => dispatch(props.done, data)),
+  },
+  subs: {
+    interval: (props, dispatch) => {
+      const id = setInterval(() => dispatch(props.tick), props.ms);
+      return () => clearInterval(id);       // cleanup
+    },
+  },
+});
+```
+
+Subscription entries in the document carry a `when` query; after every state change the loop starts and stops handlers to match (`{ "run": "interval", "with": { "ms": 1000, "tick": "tick" }, "when": "$.running" }`). A broken `when` fails **closed** — a broken rule must never keep side effects alive — and is reported through `onError`.
+
+## Async tasks
+
+Async work follows a documented convention — **correctness lives in state, cancellation lives in the host** — with one shipped helper packaging the host half:
+
+```javascript
+import { createTaskEffect } from '@jarenjs/app';
+
+// state:  "tasks": { "list": { "id": 0, "status": "idle", "error": null } }
+// start:  patch increments /tasks/list/id AND the effect's with.id
+//         carries the same increment expression (evaluated pre-transition!)
+// finish: the completion action guards { "$eq": ["$payload.id", "$.tasks.list.id"] }
+//         and yields the empty sequence for anything stale
+effects: {
+  http: createTaskEffect((props, signal) =>
+    fetch(props.url, { signal }).then((r) => r.json())),
+}
+```
+
+The helper aborts a slot's in-flight predecessor (`mode: "switch"`, the default — `"exhaust"`, `"concat"` and `"parallel"` pick the other per-slot concurrency semantics), dispatches `done` with `{ id, result }` on resolve and `fail ?? done` with `{ id, error }` (a string) on failure, and dispatches nothing for an abort. The abort is only an optimization — an aborted request may already have resolved — so the state-side id guard is the guarantee: out-of-order and polling responses are rejected by construction. The handler exposes `cancel(slot)`/`cancelAll()`/`dispose()`; `app.destroy()` disposes it automatically. The full convention, with a runnable worked example the test suite executes verbatim, is [docs/TASKS.md](docs/TASKS.md).
+
+## One FIFO queue, observable transactions
+
+Every dispatch — from the DOM, an effect, a listener, a subscription or a widget — is one **transaction** on one FIFO queue; nested dispatches queue, never interleave, so every listener observes every transaction in the same order with the state that transaction produced ([APP-FORMAT §8](docs/APP-FORMAT.md)). Boot is a transaction too: a failure in renderer construction, the initial-state check, a starting subscription, the first frame or the queued boot work rolls back everything acquired (effect handlers disposed, container emptied) and throws `JA0007`. `app.stop()` halts the loop one-way (no resume); `app.destroy()` is the terminal teardown — subscriptions cleaned, effect handlers disposed, widgets unmounted exactly once, the container emptied.
+
+`app.observe(fn)` streams one bounded JSON record per transaction (`seq`, `action`, `source`, `status`, `changedPaths`, `scheduledEffects`, `durationMs`, `errorCode` — payloads only with the `capturePayloads` opt-in), and `createTransactionLog({ limit, redact })` packages the ring buffer with a redaction hook for support exports. `createFocusEffect({ container })` bridges focus, text selection and measurement through post-render `data-ref` intents, so accessible dialogs restore focus without a DOM node ever entering state (§8.4).
+
+## Widgets — imperative islands, declarative everything else
+
+An irreducibly imperative island — a virtualized grid, a canvas, a map — lives behind a **registered widget** ([VIEW-FORMAT §7](../view/docs/VIEW-FORMAT.md)); the app document stays JSON and the app option only names the boundary, like `effects` and `subs`:
+
+```javascript
+createApp({
+  state: { grid: { rows: hugeArray, scrollTop: 0 }, selected: null },
+  view: [
+    { "match": "$", "body": ["main", {}, { "$apply": "$.grid" }] },
+    { "match": "$.grid", "body":
+      ["jaren-widget", { "name": "virtual-list", "key": "list", "props": {
+        "rows": "$.rows", "scrollTop": "$.scrollTop",
+        "binding": { "action": "select", "with": {} } } }] },
+  ],
+  actions: { select: { patch: [{ op: 'add', path: '/selected', value: '$payload.id' }] } },
+}, { node, widgets: { 'virtual-list': virtualListWidget } });
+```
+
+Jaren owns state and orchestration; the widget owns its DOM. Its `props` come from the view stylesheet and are compared **by reference** — the JSLT memo means a transition that doesn't touch the widget's state slice never calls into the widget at all. The widget dispatches by composing runtime data into the binding its props carry and handing it to `emit`, which flows through the ordinary binding path — `with` payloads and `event` extraction included — and it is unmounted deterministically when it leaves the tree.
+
+### A ready-made splitter, and a document store
+
+Two IDE-shaped primitives ship ready to bind, so a two-pane surface (the studio, the play playground) doesn't re-implement them:
+
+- **`createSplitterWidget({ action, grid, rail, cssVar, min, max, step })`** — a drag handle over a pane boundary. It drives a CSS ratio variable *live* during a drag (no per-move dispatch — that would flood the transaction log and undo) and commits the ratio through `action` on pointer-up only, plus keyboard resize as an ARIA separator. Register it like any widget; parameterize the grid/rail selectors, the CSS variable and the commit action so each surface binds its own.
+- **`createDocStore({ storage, key })`** — a keyed `save`/`load`/`remove`/`names`/`all` CRUD over an injected `storage` (`localStorage` in the browser, an in-memory object in tests), so the package never touches `localStorage` itself. Paired with **`encodeShare(snapshot)`** / **`decodeShare(token)`**, a Unicode-safe base64url share-link codec (a corrupt token decodes to `null`, never a throw), it is the new/save/load/delete/share pattern behind the studio and play surfaces.
+
+## Invariants the model can't cheat
+
+```javascript
+import { JarenValidator } from '@jarenjs/validate';
+import { createTypeTestCompiler } from '@jarenjs/validate/query';
+
+const validate = new JarenValidator().compile(stateSchema);   // may carry $query assertions
+
+createApp(doc, {
+  node,
+  compileTypeTest: createTypeTestCompiler(),   // enables schema matches & $valid/$assert/$as
+  validateState: (state) => validate(state),   // every transition checked; rejected = not applied
+});
+```
+
+`validateState` runs against every candidate next state; a rejection blocks the transition (fail closed) and surfaces as a `JA2005` error with the validator's structured errors in `detail`. The app package itself never imports the validator — the same boundary discipline as `@jarenjs/forms`.
+
+## The standard forms stylesheet
+
+The marquee integration: render any [`@jarenjs/forms`](../forms) model with **zero hand-written render code**. `createFormView()` returns a plain-JSON JSLT rule set that dispatches over a `buildFormViewModel` tree by *shape* (JSONPath filter selectors on each node's `control`), and `createFormActions()` returns the matching action documents that write keystrokes back into the state — choosing the correct RFC 6902 op per node (`replace` for array elements, where `add` would insert; `add` for object members, where it means set-or-replace).
+
+```javascript
+import { createApp, createFormView, createFormActions, formEventFields } from '@jarenjs/app';
+import { buildFormModel, compileFormRules, createInitialData, buildFormViewModel } from '@jarenjs/forms';
+
+const model = buildFormModel(schema);
+const rules = compileFormRules(model);
+
+const app = createApp({
+  state: { data: createInitialData(model) },
+  view: [
+    ...createFormView(),                                  // the shipped rule set
+    { match: '$', body: ['main', {}, { $apply: '$.form' }] },
+  ],
+  actions: createFormActions({ dataPointer: '/data' }),
+}, {
+  node: document.getElementById('app'),
+  eventFields: { ...formEventFields() },                  // decode the JSON-carrying controls
+  viewModel: (state) => ({                                // the derivation boundary
+    form: buildFormViewModel(model, state.data, { rules, validateFields: true }),
+  }),
+});
+```
+
+Schema in, live form out: text/email/number/date/color inputs, textareas, checkboxes, selects with precomputed options, nested object fieldsets, arrays with add/remove buttons, inline errors, and `x-form` visibility/enablement/computed reacting per keystroke. The `viewModel` option is the general **derivation boundary**: it maps state to the view stylesheet's input before every render, so JS-computed derivations enter the render path without ever entering the state. A DOM control's value is a string, and two controls carry something else: a select over a non-string enum, and the `json` editor over a structured value. Both round-trip through JSON text and decode it in `formEventFields()`, the format's one sanctioned place for host JavaScript at the DOM boundary (APP-FORMAT §5.4) — **register it or those two controls write nothing**. Remaining 0.1 limits (documented in `src/forms.js`): a cleared number input writes `null`, and arrays need to exist in the data (give them `default: []` in the schema).
+
+## Headless and server-side
+
+Without a `node`, the app runs headless: `getVnode()` returns the current view output for any renderer, and SSR is one composition:
+
+```javascript
+import { renderToString } from '@jarenjs/view';
+renderToString(createApp(doc).getVnode());
+```
+
+## API
+
+`createApp(appDoc, options)` → `{ dispatch(name, payload?), getState(), getVnode(), render(), subscribe(listener), observe(observer), stop(), destroy() }`
+
+Also exported: `compileActions`, `compileSubs`, `createFormView`, `createFormActions`, `formEventFields`, `createTaskEffect`, `createFocusEffect`, `createTransactionLog`, `createSplitterWidget`, `createDocStore`, `encodeShare`, `decodeShare`, and the error classes (`AppCompileError`, `AppRuntimeError`, `HostValueError`, `toError`, `APP_CODES`).
+
+Options: `node`, `document`, `effects`, `subs`, `eventFields` (named `$event` field extractors), `widgets` (registered widget definitions, forwarded to the renderer), `compileTypeTest`, `validateState`, `viewModel`, `onError` (default rethrows), `schedule` (render batching; default microtask — pass `(f) => f()` for synchronous tests). Compile failures throw `AppCompileError` (`JA0xxx`, with a `docPath` into the app document); runtime failures route `AppRuntimeError` (`JA2xxx`) through `onError`. The full code table is in [APP-FORMAT.md](docs/APP-FORMAT.md) §10.
+
+## Development
+
+Unit tests live in `test/app/` at the repository root (`npm run test:app`). See [ROADMAP](../../docs/ROADMAP.md) for what's next: dirty-path-pruned re-rendering and time-travel tooling over the action log.

package/dist/types/actions.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file Compiling the transition vocabulary of an app document: named
+ * action documents and subscription entries. Everything here runs once,
+ * at `createApp` time — the loop only ever calls compiled closures.
+ *
+ * An **action document** is a Jaren JSON Query document (QUERY-FORMAT.md)
+ * evaluated with `$` bound to the current state and two externals:
+ *
+ *  - `$event`   — the serializable event data (`{ type, value, checked,
+ *    key }`) when the dispatch came from the DOM, else `null`
+ *  - `$payload` — the binding's `with` value, else `null`
+ *
+ * It returns a **transition object** (or nothing for a no-op):
+ *
+ *  - `state`   — the next state, whole
+ *  - `patch`   — an RFC 6902 JSON Patch applied to the state (after
+ *    `state`, when both are present)
+ *  - `effects` — `[{ "run": name, "with"?: props }]` handed to the
+ *    registered effect handlers
+ */
+export type ActionCompileOptions = {
+    /**
+     * Enables `$valid`/`$assert`/`$as` schema operators inside action
+     * documents; typically `createTypeTestCompiler()` from
+     * `@jarenjs/validate/query`.
+     */
+    compileTypeTest?: (schema: any, docPath: string) => ((value: any) => boolean);
+};
+/**
+ * The compile-time options shared by every embedded query document.
+ * @typedef {Object} ActionCompileOptions
+ * @property {(schema: any, docPath: string) => ((value: any) => boolean)} [compileTypeTest]
+ *   Enables `$valid`/`$assert`/`$as` schema operators inside action
+ *   documents; typically `createTypeTestCompiler()` from
+ *   `@jarenjs/validate/query`.
+ */
+/**
+ * Compile the `actions` member of an app document.
+ * @param {any} actions
+ * @param {ActionCompileOptions} options
+ * @returns {Map<string, any>} action name → compiled query
+ */
+export declare function compileActions(actions: any, options: ActionCompileOptions): Map<string, any>;
+export type CompiledSub = {
+    /**
+     * - The registered handler name.
+     */
+    run: string;
+    /**
+     * - The entry's `with` value (`null` when absent).
+     */
+    props: any;
+    /**
+     * - Compiled liveness query, or `null` (always live).
+     */
+    when: any;
+    /**
+     * - Compiled props query evaluated against the
+     * state (with `$item` bound per instance under `for`), or `null`.
+     */
+    withQuery: any;
+    /**
+     * - Compiled restart-key query, or `null` (the
+     * key derives from the resolved props by value).
+     */
+    keyQuery: any;
+    /**
+     * - Compiled fan-out query yielding the item
+     * set, or `null` (a single-instance subscription).
+     */
+    forQuery: any;
+};
+/**
+ * Compile the `subs` member of an app document:
+ * `[{ "run": name, "with"?: props, "when"?: <EBV query>,
+ *     "withQuery"?: query, "key"?: query, "for"?: query }]`.
+ *
+ * `with` is verbatim data; `withQuery` derives the props from the state
+ * and makes the subscription DYNAMIC — it restarts when its resolved
+ * key changes (`key` overrides the derived-from-props default). `for`
+ * fans the declaration out to one instance per item of its result. The
+ * combinations that would make one entry ambiguous are JA0008: `with`
+ * beside `withQuery`, `with` beside `for`, and `key` without either
+ * `withQuery` or `for`.
+ * @param {any} subs
+ * @param {ActionCompileOptions} options
+ * @returns {CompiledSub[]}
+ */
+export declare function compileSubs(subs: any, options: ActionCompileOptions): CompiledSub[];

package/dist/types/app.d.ts

@@ -0,0 +1,293 @@
+/**
+ * @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.
+ */
+export type AppOptions = {
+    /**
+     * - DOM element to mount into; omit for a headless
+     * app (drive it via `getVnode`/`subscribe`).
+     */
+    node?: any;
+    /**
+     * - The DOM document (defaults to
+     * `node.ownerDocument`).
+     */
+    document?: any;
+    /**
+     * 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).
+     */
+    effects?: Record<string, (props: any, dispatch: Dispatch) => void>;
+    /**
+     * Subscription handlers by name; may return a cleanup function.
+     */
+    subs?: Record<string, (props: any, dispatch: Dispatch) => (() => void) | void>;
+    /**
+     * 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).
+     */
+    eventFields?: Record<string, (nativeEvent: any) => any>;
+    /**
+     * - 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.
+     */
+    widgets?: Record<string, any>;
+    /**
+     * Enables JSON Schema operators (`$valid`/`$assert`/`$as`) and schema
+     * matches inside the view and the action documents.
+     */
+    compileTypeTest?: (schema: any, docPath: string) => ((value: any) => boolean);
+    /**
+     * 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}).
+     */
+    validateState?: (state: any, context: ValidateContext) => boolean | {
+        valid: boolean;
+        errors?: any;
+    };
+    /**
+     * - 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.
+     */
+    viewModel?: (state: any) => any;
+    /**
+     * - 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.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * - Render scheduler;
+     * default batches on a microtask. Pass `(f) => f()` for synchronous
+     * rendering (tests, SSR pipelines).
+     */
+    schedule?: (flush: () => void) => void;
+    /**
+     * - 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.
+     */
+    afterRender?: () => void;
+    /**
+     * - 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.
+     */
+    maxTurns?: number;
+    /**
+     * - 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.
+     */
+    maxSubInstances?: number;
+    /**
+     * - Include `payload` and `event`
+     * values in transaction records handed to observers (default false —
+     * diagnostics must not leak data by default).
+     */
+    capturePayloads?: boolean;
+};
+export type ValidateContext = {
+    /**
+     * - The state the transition started from
+     * (`null` for the boot-time initial-state check).
+     */
+    previous: any;
+    /**
+     * - The acting action name (`null`
+     * for the boot-time initial-state check).
+     */
+    action: string | null;
+    /**
+     * - The dispatch payload (`null` when absent).
+     */
+    payload: any;
+    /**
+     * - Changed JSON Pointers when the
+     * transition was patch-only, else `null` (= unknown, validate fully).
+     */
+    changes: string[] | null;
+};
+export type TransactionRecord = {
+    /**
+     * - Monotonic transaction sequence number.
+     */
+    seq: number;
+    /**
+     * - The dispatched action name.
+     */
+    action: string;
+    /**
+     * - What queued it: `'dispatch'` (external),
+     * `'binding'` (DOM/widget), `'effect'`, `'subscription'`, or
+     * `'setState'` (a whole-state replacement from outside the loop).
+     */
+    source: string;
+    status: 'applied' | 'noop' | 'rejected' | 'failed';
+    /**
+     * - Changed JSON Pointers, or
+     * `null` when the whole state was replaced (unknown = everything).
+     */
+    changedPaths: string[] | null;
+    /**
+     * - Names of effects invoked.
+     */
+    scheduledEffects: string[];
+    durationMs: number;
+    /**
+     * - The `JA2xxx` code when the
+     * transaction failed or was rejected.
+     */
+    errorCode: string | null;
+    payload?: any;
+    event?: any;
+};
+export type Dispatch = (name: string, payload?: any, domEvent?: any, eventFields?: string[] | null) => void;
+/**
+ * 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 declare function createApp(appDoc: any, options?: AppOptions): {
+    dispatch: (name: string, payload?: any, domEvent?: any, eventFields?: string[] | null) => void;
+    /** The current state (treat as immutable). */
+    getState: () => any;
+    /**
+     * 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: any): void;
+    /** The current view output — for SSR or custom renderers. */
+    getVnode: () => any;
+    render: () => void;
+    /**
+     * 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: (state: any, changes: string[] | null) => void): () => void;
+    /**
+     * 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: (tx: TransactionRecord) => void): () => void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+};

package/dist/types/diagnostics.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file A bounded transaction log over `app.observe` (APP-FORMAT §8.3).
+ *
+ * The log lives OUTSIDE application state by design: diagnostics are
+ * host memory, never data. Records are the observer's bounded JSON
+ * metadata; payload capture stays whatever the app was created with
+ * (`capturePayloads`), so the log adds no leak surface of its own. A
+ * redaction hook lets a host scrub or drop records before they are
+ * retained at all.
+ */
+export type TransactionLogOptions = {
+    /**
+     * - Maximum retained records (default 200);
+     * older records fall off the front.
+     */
+    limit?: number;
+    /**
+     * - Applied to every record
+     * before retention; return the (possibly rewritten) record, or
+     * `null`/`undefined` to drop it entirely. Secrets and personal data
+     * are the host's responsibility — this is the hook to enforce it.
+     */
+    redact?: (record: any) => any;
+};
+/**
+ * @typedef {Object} TransactionLogOptions
+ * @property {number} [limit] - Maximum retained records (default 200);
+ *   older records fall off the front.
+ * @property {(record: any) => any} [redact] - Applied to every record
+ *   before retention; return the (possibly rewritten) record, or
+ *   `null`/`undefined` to drop it entirely. Secrets and personal data
+ *   are the host's responsibility — this is the hook to enforce it.
+ */
+/**
+ * Create a bounded transaction log. Wire it up with
+ * `app.observe(log.observer)`; read it back with `log.entries()`;
+ * export it as versioned JSON with `log.export()`.
+ *
+ * @example
+ * const log = createTransactionLog({ limit: 100 });
+ * const stop = app.observe(log.observer);
+ * // ... later, in a support bundle:
+ * const dump = log.export(); // { version: 1, entries: [...] }
+ *
+ * @param {TransactionLogOptions} [options]
+ */
+export declare function createTransactionLog(options?: TransactionLogOptions): {
+    /**
+     * The observer to register with `app.observe`.
+     * @param {any} record
+     */
+    observer(record: any): void;
+    /** The retained records, oldest first (a fresh array each call). */
+    entries(): any[];
+    /** Drop every retained record. */
+    clear(): void;
+    /**
+     * A versioned export envelope for support bundles. The version
+     * covers the envelope shape; record fields follow the observer
+     * contract of the app that produced them.
+     * @returns {{ version: 1, entries: any[] }}
+     */
+    export(): {
+        version: 1;
+        entries: any[];
+    };
+};