@jarenjs/app 0.34.0

package/src/diagnostics.js

@@ -0,0 +1,77 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+/**
+ * @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 function createTransactionLog(options = {}) {
+  const limit = options.limit ?? 200;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new TypeError('createTransactionLog: "limit" must be a positive integer');
+  }
+  const redact = options.redact ?? null;
+  /** @type {any[]} */
+  let entries = [];
+
+  return {
+    /**
+     * The observer to register with `app.observe`.
+     * @param {any} record
+     */
+    observer(record) {
+      let entry = record;
+      if (redact !== null) {
+        entry = redact(record);
+        if (entry === null || entry === undefined) return;
+      }
+      entries.push(entry);
+      if (entries.length > limit) entries.splice(0, entries.length - limit);
+    },
+    /** The retained records, oldest first (a fresh array each call). */
+    entries() {
+      return entries.slice();
+    },
+    /** Drop every retained record. */
+    clear() {
+      entries = [];
+    },
+    /**
+     * 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() {
+      return { version: 1, entries: entries.slice() };
+    },
+  };
+}

package/src/docstore.js

@@ -0,0 +1,71 @@
+//@ts-check
+/**
+ * @file A tiny persisted document store plus a share-link codec — the
+ * save / load / delete / list + share primitives an IDE-style surface (the
+ * studio, the play playground) needs, with the storage backend injected by
+ * the host so the package stays free of `localStorage`.
+ *
+ * `createDocStore` is a keyed CRUD over an injected `storage` ({ read, write }):
+ * the store is one JSON object `{ [key]: { name → value } }`, read once at
+ * creation and written back on every mutation. `encodeShare` / `decodeShare`
+ * turn a small snapshot into a Unicode-safe base64url token and back —
+ * forgivingly: a corrupt token decodes to `null`, never a throw.
+ */
+
+/**
+ * @param {Object} opts
+ * @param {{ read: () => any, write: (store: any) => void }} opts.storage
+ *   the host persistence adapter (localStorage in the browser, an in-memory
+ *   object in tests)
+ * @param {string} [opts.key='experiments'] - the store's collection key
+ * @returns {{
+ *   save: (name: string, value: any) => void,
+ *   load: (name: string) => any,
+ *   remove: (name: string) => void,
+ *   names: () => string[],
+ *   all: () => Record<string, any>,
+ * }}
+ */
+export function createDocStore({ storage, key = 'experiments' }) {
+  // read once; keep the SAME object reference for every write-back
+  const store = storage.read() ?? {};
+  if (store[key] === undefined || store[key] === null) store[key] = {};
+  return {
+    save(name, value) { store[key][name] = value; storage.write(store); },
+    load(name) { return store[key][name]; },
+    remove(name) { delete store[key][name]; storage.write(store); },
+    names() { return Object.keys(store[key]).sort(); },
+    all() { return store[key]; },
+  };
+}
+
+/**
+ * Encode a snapshot as a base64url token: Unicode-safe (TextEncoder),
+ * portable between browser and Node.
+ * @param {any} snapshot
+ * @returns {string} the base64url token
+ */
+export function encodeShare(snapshot) {
+  const bytes = new TextEncoder().encode(JSON.stringify(snapshot));
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Decode a base64url token back to its snapshot, forgivingly.
+ * @param {string} token
+ * @returns {any} the snapshot object, or `null` when the token is unusable
+ */
+export function decodeShare(token) {
+  try {
+    const binary = atob(token.replace(/-/g, '+').replace(/_/g, '/'));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    const snapshot = JSON.parse(new TextDecoder().decode(bytes));
+    return snapshot !== null && typeof snapshot === 'object' ? snapshot : null;
+  }
+  catch {
+    return null;
+  }
+}

package/src/errors.js

@@ -0,0 +1,245 @@
+//@ts-check
+/**
+ * @file Error types for @jarenjs/app, built on `@jarenjs/core`'s coded
+ * contract: every failure carries a stable `code` (JA0xxx compile,
+ * JA2xxx runtime), a bare `reason`, a composed `message`, and — where
+ * one exists — the `docPath` of the offending member of the app
+ * document. The feedback shape a repair loop needs.
+ */
+
+import { CodedError } from '@jarenjs/core/errors';
+
+/**
+ * The runtime code table (the `CSV_CODES` shape): one entry per code
+ * this package can raise, proven in sync with APP-FORMAT.md's normative
+ * table by a test.
+ */
+export const APP_CODES = Object.freeze({
+  JA0001: 'the app document is not an object',
+  JA0002: 'view is missing or failed to compile',
+  JA0003: 'actions is not an object of named documents',
+  JA0004: 'an action document failed to compile',
+  JA0005: 'subs is not an array of subscription entries',
+  JA0006: 'a subscription entry is malformed or its when failed to compile',
+  JA0007: 'the app failed to boot after compilation succeeded',
+  JA0008: 'a subscription dynamic member failed to compile or combines invalidly',
+  JA2001: 'an unknown action was dispatched',
+  JA2002: 'an action, when document or event-field extractor threw',
+  JA2003: 'an action produced a transition that is not an object',
+  JA2004: 'a transition patch failed to apply',
+  JA2005: 'the next state violated the app invariants',
+  JA2006: 'a transition named an effect with no registered handler',
+  JA2007: 'an effect handler threw',
+  JA2008: 'a subscription entry names no registered handler',
+  JA2009: 'a binding requested an unknown event field',
+  JA2010: 'the dispatch loop exceeded maxTurns transactions in one drain',
+  JA2011: 'a state listener or transaction observer threw',
+  JA2012: 'a cleanup threw while stopping, reconciling or destroying',
+  JA2013: 'a subscription handler threw while starting',
+  JA2014: 'a post-render intent named a data-ref with no rendered target',
+  JA2015: 'the validateState hook itself threw',
+  JA2016: 'a subscription dynamic query (withQuery, key or for) failed at runtime',
+  JA2017: 'a subscription fan-out exceeded maxSubInstances',
+});
+
+/**
+ * A defect in the app document itself, raised while `createApp` compiles
+ * it. Codes:
+ *
+ *  - `JA0001` — the app document is not an object
+ *  - `JA0002` — `view` is missing or not a stylesheet document
+ *  - `JA0003` — `actions` is not an object of named documents
+ *  - `JA0004` — an action document failed to compile (see `cause`)
+ *  - `JA0005` — `subs` is not an array of subscription entries
+ *  - `JA0006` — a subscription entry is malformed or its `when` failed
+ *    to compile (see `cause`)
+ *  - `JA0007` — the app failed to boot: the renderer construction, the
+ *    initial-state check, the initial subscriptions, the first frame or
+ *    the queued boot work failed after compilation succeeded; every
+ *    already-acquired resource was rolled back (see `cause`)
+ *  - `JA0008` — a subscription's dynamic member (`withQuery`, `key`,
+ *    `for`) failed to compile (see `cause`), or the members combine
+ *    invalidly (`with` beside `withQuery` or `for`; `key` without
+ *    either)
+ */
+export class AppCompileError extends CodedError {
+  /**
+   * @param {string} code
+   * @param {string} reason - The bare reason; `message` is composed as
+   *   `${code}: ${reason} at ${docPath}` per the coded contract.
+   * @param {string} [docPath] - JSON Pointer into the app document;
+   *   `''` is the document root, `undefined` means no location (never
+   *   normalized to `''` — root and unknown are different facts).
+   * @param {Error} [cause]
+   */
+  constructor(code, reason, docPath, cause) {
+    super('AppCompileError', code, reason, docPath,
+      cause !== undefined ? { cause } : undefined);
+  }
+}
+
+/**
+ * A failure while the app is running. Codes:
+ *
+ *  - `JA2001` — an unknown action was dispatched
+ *  - `JA2002` — an action or `when` document threw while evaluating,
+ *    or a registered event-field extractor threw (see `cause`; the
+ *    extractor's member binds `null` and the dispatch still runs)
+ *  - `JA2003` — an action produced a transition that is not an object
+ *  - `JA2004` — a transition's `patch` failed to apply (see `cause`)
+ *  - `JA2005` — the next state violated the app's invariants
+ *    (`validateState` rejected it); the transition was NOT applied
+ *  - `JA2006` — a transition named an effect with no registered handler
+ *  - `JA2007` — an effect handler threw (see `cause`)
+ *  - `JA2008` — a subscription entry names no registered handler
+ *  - `JA2009` — a binding requested an unknown event field (the member
+ *    is bound `null`; the dispatch itself is NOT dropped)
+ *  - `JA2010` — the dispatch loop exceeded `maxTurns` transactions in
+ *    one drain (an accidental action/effect loop); the queue was
+ *    abandoned
+ *  - `JA2011` — a state listener or transaction observer threw
+ *    (isolated; the queue drains on)
+ *  - `JA2012` — a cleanup threw while stopping/reconciling/destroying
+ *    (isolated; sibling cleanups still run)
+ *  - `JA2013` — a subscription handler threw while starting; the slot
+ *    stays stopped
+ *  - `JA2014` — a post-render focus/measure intent named a `data-ref`
+ *    with no rendered target
+ *  - `JA2015` — the `validateState` hook itself threw (see `cause`) —
+ *    distinct from a rejection verdict (`JA2005`); the transaction
+ *    fails and the queue keeps draining
+ *  - `JA2016` — a subscription's dynamic query (`withQuery`, `key` or
+ *    `for`) threw while evaluating — a cyclic resolved value included —
+ *    and the subscription failed closed (see `cause`; `docPath` names
+ *    the member)
+ *  - `JA2017` — a subscription fan-out resolved more instances than
+ *    `maxSubInstances`; the previous instance set was kept
+ */
+export class AppRuntimeError extends CodedError {
+  /**
+   * @param {string} code
+   * @param {string} reason - The bare reason; `message` is composed
+   *   from `code`, `reason` and the location per the coded contract.
+   * @param {{ docPath?: string, cause?: Error }} [options] - `docPath`
+   *   is a JSON Pointer into the app document where one exists
+   *   (`undefined` when there is no location — never `''`, which means
+   *   the document root); `cause` retains what host code threw.
+   */
+  constructor(code, reason, options) {
+    super('AppRuntimeError', code, reason, options?.docPath,
+      options !== undefined && options.cause !== undefined
+        ? { cause: options.cause }
+        : undefined);
+    /** Structured detail, e.g. validateState errors for JA2005. */
+    this.detail = undefined;
+  }
+}
+
+/**
+ * A non-Error value thrown by host code, wrapped for the framework's
+ * error channels. JavaScript permits `throw null`, `throw undefined`,
+ * strings, numbers and arbitrary objects; host extension points
+ * (effects, subscriptions, validators, extractors, listeners,
+ * observers, widgets, sinks) may produce any of them, and the
+ * framework's isolation guarantees must hold for all of them.
+ *
+ * The original value is retained as an OWN `cause` property — set even
+ * when the value is `undefined`, so `Object.hasOwn(err, 'cause')`
+ * distinguishes "threw undefined" from "no cause" — and the message
+ * describes the value without invoking any user coercion (`toString`
+ * on a hostile object is never called).
+ */
+export class HostValueError extends Error {
+  /** @param {unknown} value - The value host code threw. */
+  constructor(value) {
+    super(`host code threw a non-Error value (${describeThrown(value)})`);
+    this.name = 'HostValueError';
+    Object.defineProperty(this, 'cause', {
+      value, writable: true, enumerable: false, configurable: true,
+    });
+  }
+}
+
+/**
+ * Describe a thrown non-Error value without observing it: only
+ * conversions no host code can trap are used — never a `toString`,
+ * never `Symbol.toPrimitive`, and never proxy-observable reflection
+ * (`Array.isArray` runs the proxy-sensitive IsArray operation, so a
+ * revoked proxy is simply "an object"). `typeof` and identity
+ * comparisons are untrappable, which is the whole vocabulary here.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeThrown(value) {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  switch (typeof value) {
+    case 'string': {
+      const short = value.length > 80 ? value.slice(0, 80) + '…' : value;
+      return JSON.stringify(short);
+    }
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+      return String(value);
+    case 'symbol':
+      return 'a symbol';
+    case 'function':
+      return 'a function';
+    default:
+      return 'an object';
+  }
+}
+
+/**
+ * `value instanceof Error` without trusting the value: `instanceof`
+ * walks the prototype chain, which a revoked or hostile proxy turns
+ * into a throw. A value whose very classification throws is treated as
+ * not-an-Error and wrapped.
+ * @param {unknown} value
+ * @returns {value is Error}
+ */
+export function isErrorSafely(value) {
+  try {
+    return value instanceof Error;
+  }
+  catch {
+    return false;
+  }
+}
+
+/**
+ * Read an error's `message` without trusting it: JavaScript permits an
+ * own `message` accessor (or a proxy `get` trap) that throws, and the
+ * framework must never fail while formatting a failure. The original
+ * error object is never mutated — it stays the causal identity; this
+ * only projects a safe diagnostic string.
+ * @param {Error} error
+ * @returns {string}
+ */
+export function safeErrorMessage(error) {
+  try {
+    const message = error.message;
+    if (typeof message === 'string') return message;
+  }
+  catch { /* a hostile accessor is a diagnostic, not a crash */ }
+  return 'host error (message unavailable)';
+}
+
+/**
+ * The one host-failure normalization policy (APP-FORMAT §10.1): every
+ * value caught at a host boundary passes through here, and the policy
+ * is TOTAL — no ECMAScript value, revoked proxies and throwing
+ * accessors included, can make it throw. An `Error` instance passes by
+ * IDENTITY — wherever a contract promises the original error as
+ * `cause`, that identity survives; anything else (a value whose
+ * classification itself throws included) is wrapped in a
+ * {@link HostValueError} that retains the original value as an own
+ * `cause` property. No caught value is ever assumed to have
+ * `.message`, and no thrown value is ever used as an absence sentinel.
+ * @param {unknown} value - Whatever host code threw.
+ * @returns {Error}
+ */
+export function toError(value) {
+  return isErrorSafely(value) ? /** @type {Error} */ (value) : new HostValueError(value);
+}

package/src/focus.js

@@ -0,0 +1,188 @@
+//@ts-check
+/**
+ * @file The post-render focus/measurement queue (APP-FORMAT §8.4).
+ *
+ * Focus, text selection and measurement need a real DOM element at a
+ * moment when the frame is committed — but DOM nodes must never enter
+ * state. The bridge is a JSON intent naming a `data-ref` token that the
+ * view places as an ordinary attribute:
+ *
+ *   view:    ["input", { "data-ref": "search" }]
+ *   action:  { "effects": [{ "run": "focus", "with": { "ref": "search" } }] }
+ *
+ * Intents queue during the transaction and flush after the NEXT
+ * committed frame — after the DOM patch and after widget mounts, so a
+ * target inside freshly rendered markup is already connected. Only a
+ * state change schedules a frame: an intent queued by an effect-only
+ * action (no state transition) waits until the next state-changing
+ * transaction or a manual `render()` commits one — pair the intent
+ * with the transition that produces its target. A missing target is a
+ * diagnosable `JA2014`, never a silent no-op. Destroying the app (or
+ * `dispose()`) cancels pending intents; a headless app never flushes
+ * (there is no frame), which makes the queue a documented no-op there.
+ */
+
+import { AppRuntimeError } from './errors.js';
+
+/**
+ * @typedef {Object} FocusEffectOptions
+ * @property {any} container - The rendered root (the same element
+ *   handed to `createApp` as `node`); intents resolve inside it.
+ * @property {(error: Error) => void} [onError] - Sink for `JA2014`
+ *   missing-target diagnostics; default: the first one is thrown after
+ *   the flush completes (siblings still run). The sink itself is
+ *   isolated: a throwing sink never stops the flush — every sibling
+ *   intent still resolves, and the first error the sink threw
+ *   surfaces after the flush completes.
+ */
+
+/**
+ * The effect handler returned by {@link createFocusEffect}, with its
+ * host-side controls.
+ * @typedef {((props: any, dispatch: (name: string, payload?: any) => void) => void) & {
+ *   flush: () => void,
+ *   dispose: () => void,
+ * }} FocusEffect
+ */
+
+/**
+ * Create the post-render intent queue as a registered effect. Intent
+ * props (all JSON):
+ *
+ *  - `ref` (REQUIRED, string) — the `data-ref` token to resolve;
+ *  - `op`  (OPTIONAL) — `"focus"` (default), `"select"`, or
+ *    `"measure"`;
+ *  - `done` (REQUIRED for `measure`) — the action dispatched with
+ *    `{ id, ref, rect }` where `rect` is the JSON-reduced bounding
+ *    rect;
+ *  - `id`  (OPTIONAL) — echoed in the `measure` completion payload.
+ *
+ * Wire `flush` as the app's `afterRender` so intents resolve exactly
+ * once per committed frame, ordered after widget mounts:
+ *
+ * @example
+ * const focus = createFocusEffect({ container: node });
+ * const app = createApp(doc, {
+ *   node,
+ *   effects: { focus },
+ *   afterRender: focus.flush,
+ * });
+ * // app.destroy() disposes the queue through the handler's dispose()
+ *
+ * @param {FocusEffectOptions} options
+ * @returns {FocusEffect}
+ */
+export function createFocusEffect(options) {
+  const container = options?.container;
+  if (container === null || container === undefined) {
+    throw new TypeError('createFocusEffect: an options.container element is required');
+  }
+  const onError = options.onError ?? null;
+
+  /** @type {Array<{ props: any, dispatch: (name: string, payload?: any) => void }>} */
+  let queue = [];
+  let disposed = false;
+
+  /** @type {any} */
+  const focusEffect = function focusEffect(props, dispatch) {
+    if (props === null || typeof props !== 'object' || typeof props.ref !== 'string') {
+      throw new TypeError('createFocusEffect: the effect props must carry a string "ref"');
+    }
+    const op = props.op ?? 'focus';
+    if (op !== 'focus' && op !== 'select' && op !== 'measure') {
+      throw new TypeError(`createFocusEffect: unknown op '${String(op)}'`);
+    }
+    if (op === 'measure' && typeof props.done !== 'string') {
+      throw new TypeError('createFocusEffect: a "measure" intent must carry a "done" action name');
+    }
+    if (disposed) return;
+    queue.push({ props, dispatch });
+  };
+
+  /**
+   * Resolve every queued intent against the committed frame. Missing
+   * targets report `JA2014`; every sibling intent still runs.
+   */
+  focusEffect.flush = function flush() {
+    if (disposed || queue.length === 0) return;
+    const batch = queue;
+    queue = [];
+    /** A presence record: a sink may legally throw `null`, which must
+     * still surface after the batch completes.
+     * @type {{ value: unknown } | null} */
+    let firstError = null;
+    for (const { props, dispatch } of batch) {
+      const target = findByRef(container, props.ref);
+      if (target === null) {
+        const err = new AppRuntimeError('JA2014',
+          `a post-render intent named data-ref '${props.ref}' but no rendered element carries it`);
+        if (onError !== null) {
+          // the sink is host code: isolate it like the app loop does,
+          // so one throwing report never starves the sibling intents
+          try {
+            onError(err);
+          }
+          catch (thrown) {
+            if (firstError === null) firstError = { value: thrown };
+          }
+        }
+        else if (firstError === null) firstError = { value: err };
+        continue;
+      }
+      const op = props.op ?? 'focus';
+      if (op === 'focus') {
+        if (typeof target.focus === 'function') target.focus();
+      }
+      else if (op === 'select') {
+        if (typeof target.select === 'function') target.select();
+        else if (typeof target.focus === 'function') target.focus();
+      }
+      else {
+        const rect = typeof target.getBoundingClientRect === 'function'
+          ? target.getBoundingClientRect()
+          : null;
+        dispatch(props.done, {
+          id: props.id ?? null,
+          ref: props.ref,
+          rect: rect === null ? null : {
+            x: rect.x, y: rect.y,
+            width: rect.width, height: rect.height,
+            top: rect.top, left: rect.left,
+            right: rect.right, bottom: rect.bottom,
+          },
+        });
+      }
+    }
+    if (firstError !== null) throw firstError.value;
+  };
+
+  /** Terminal: drop pending intents and ignore new ones. Idempotent. */
+  focusEffect.dispose = function dispose() {
+    disposed = true;
+    queue = [];
+  };
+
+  return focusEffect;
+}
+
+/**
+ * Depth-first search for the element whose `data-ref` attribute equals
+ * the token. Attribute-based on purpose: it works on any DOM the
+ * renderer can write to (real, stub, test), independent of
+ * `querySelector` and CSS escaping rules.
+ * @param {any} node
+ * @param {string} token
+ * @returns {any | null}
+ */
+function findByRef(node, token) {
+  if (typeof node?.getAttribute === 'function' && node.getAttribute('data-ref') === token) {
+    return node;
+  }
+  const children = node?.childNodes;
+  if (children === undefined) return null;
+  for (let i = 0; i < children.length; i++) {
+    const found = findByRef(children[i], token);
+    if (found !== null) return found;
+  }
+  return null;
+}