@jarenjs/app 0.34.0

package/dist/types/docstore.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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 declare function createDocStore({ storage, key }: {
+    storage: {
+        read: () => any;
+        write: (store: any) => void;
+    };
+    key?: string;
+}): {
+    save: (name: string, value: any) => void;
+    load: (name: string) => any;
+    remove: (name: string) => void;
+    names: () => string[];
+    all: () => Record<string, any>;
+};
+/**
+ * Encode a snapshot as a base64url token: Unicode-safe (TextEncoder),
+ * portable between browser and Node.
+ * @param {any} snapshot
+ * @returns {string} the base64url token
+ */
+export declare function encodeShare(snapshot: any): string;
+/**
+ * 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 declare function decodeShare(token: string): any;

package/dist/types/errors.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @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 declare const APP_CODES: Readonly<{
+    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 declare 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: string, reason: string, docPath?: string, cause?: Error);
+}
+/**
+ * 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 declare class AppRuntimeError extends CodedError {
+    /** Structured detail, e.g. validateState errors for JA2005. */
+    detail: any;
+    /**
+     * @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: string, reason: string, options?: {
+        docPath?: string;
+        cause?: Error;
+    });
+}
+/**
+ * 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 declare class HostValueError extends Error {
+    /** @param {unknown} value - The value host code threw. */
+    constructor(value: unknown);
+}
+/**
+ * `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 declare function isErrorSafely(value: unknown): value is Error;
+/**
+ * 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 declare function safeErrorMessage(error: Error): string;
+/**
+ * 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 declare function toError(value: unknown): Error;

package/dist/types/focus.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @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.
+ */
+export type FocusEffectOptions = {
+    /**
+     * - The rendered root (the same element
+     * handed to `createApp` as `node`); intents resolve inside it.
+     */
+    container: any;
+    /**
+     * - 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.
+     */
+    onError?: (error: Error) => void;
+};
+export type FocusEffect = ((props: any, dispatch: (name: string, payload?: any) => void) => void) & {
+    flush: () => void;
+    dispose: () => void;
+};
+/**
+ * @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 declare function createFocusEffect(options: FocusEffectOptions): FocusEffect;

package/dist/types/forms.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @file The standard form rules — the shipped JSLT rule set that renders
+ * any `@jarenjs/forms` view model (`buildFormViewModel`) to vnodes, and
+ * the standard action documents that write user input back into the
+ * state. Everything both factories return is PLAIN JSON: no functions,
+ * no imports from forms — the rules dispatch on the view-model *shape*
+ * (JSONPath filter selectors on `control`), which is the whole point of
+ * the format stack.
+ *
+ * Wiring (see the README for the complete walkthrough):
+ *
+ *   view:    [...createFormView(), { match: '$', body: [..., { $apply: '$.form' }] }]
+ *   actions: { ...createFormActions({ dataPointer: '/data' }) }
+ *   options: { viewModel: (state) => ({ form: buildFormViewModel(model, state.data, { rules }) }) }
+ *
+ * A DOM control's value is a STRING, and two of these controls carry
+ * something else: a select over a non-string enum, and the `json`
+ * editor over an arbitrary value. Both round-trip through the JSON text
+ * the view model precomputes (`option.key`) or the operator types, and
+ * both decode it in a registered event-field extractor —
+ * {@link formEventFields}, the format's one sanctioned place for host
+ * JavaScript at the DOM boundary (APP-FORMAT §5.4). A host that renders
+ * these controls MUST register them.
+ *
+ * Remaining limitation, documented rather than hidden: a cleared number
+ * input writes `null` (which surfaces as a validation error, not a
+ * dispatch error).
+ */
+/**
+ * The event-field extractors the standard form controls need, for
+ * `createApp`'s `eventFields` (APP-FORMAT §5.4).
+ *
+ * One extractor, `formJsonValue`: the control's value parsed as JSON.
+ * A select carries `option.key` (the view model's JSON text for the
+ * typed enum value) and the `json` editor carries whatever the operator
+ * typed. Unparsable text yields `null` rather than throwing, so a
+ * half-typed JSON document is a validation problem — visible, fixable —
+ * instead of a dispatch error; `json` fields therefore want a schema
+ * that rejects `null` if absence is not acceptable.
+ *
+ * @example
+ * createApp(doc, { node, eventFields: { ...formEventFields() } });
+ *
+ * @returns {Record<string, (event: any) => any>}
+ */
+export declare function formEventFields(): Record<string, (event: any) => any>;
+export type FormViewOptions = {
+    /**
+     * - JSONPath of the form view-model node inside
+     * the view input document (default `'$.form'`).
+     */
+    root?: string;
+    /**
+     * - CSS class prefix (default `'jaren-form'`).
+     */
+    classPrefix?: string;
+    /**
+     * - Overrides for the
+     * standard action names (`input`/`check`/`number`/`add`/`remove`).
+     */
+    actions?: Record<string, string>;
+    /**
+     * - Add-item button text (default `'+'`).
+     */
+    addLabel?: string;
+    /**
+     * - Remove-item button text (default `'×'`).
+     */
+    removeLabel?: string;
+    /**
+     * - Accessible
+     * names for the two symbol buttons. `@jarenjs/forms`'
+     * `formChromeLabels(catalog)` resolves them from a message catalog;
+     * the English defaults apply when absent.
+     */
+    labels?: {
+        addItem?: string;
+        removeItem?: string;
+    };
+    /**
+     * - (actions) JSON Pointer to the form
+     * data inside the app state (default `'/data'`).
+     */
+    dataPointer?: string;
+};
+/**
+ * Options shared by `createFormView` / `createFormActions`.
+ * @typedef {Object} FormViewOptions
+ * @property {string} [root] - JSONPath of the form view-model node inside
+ *   the view input document (default `'$.form'`).
+ * @property {string} [classPrefix] - CSS class prefix (default `'jaren-form'`).
+ * @property {Record<string, string>} [actions] - Overrides for the
+ *   standard action names (`input`/`check`/`number`/`add`/`remove`).
+ * @property {string} [addLabel] - Add-item button text (default `'+'`).
+ * @property {string} [removeLabel] - Remove-item button text (default `'×'`).
+ * @property {{addItem?: string, removeItem?: string}} [labels] - Accessible
+ *   names for the two symbol buttons. `@jarenjs/forms`'
+ *   `formChromeLabels(catalog)` resolves them from a message catalog;
+ *   the English defaults apply when absent.
+ * @property {string} [dataPointer] - (actions) JSON Pointer to the form
+ *   data inside the app state (default `'/data'`).
+ */
+/**
+ * The standard form rule set: a JSLT rule array rendering a
+ * `buildFormViewModel` tree. Concatenate it into an app's view
+ * stylesheet and `{"$apply": "<root>"}` the form node from a page rule.
+ *
+ * @param {FormViewOptions} [options]
+ * @returns {any[]} A JSLT rule array (plain JSON).
+ */
+export declare function createFormView(options?: FormViewOptions): any[];
+/**
+ * The standard form actions: named query documents that write user
+ * input into the form data at `dataPointer + payload.pointer`. RFC 6902
+ * `add` is set-or-replace for object members, so untouched (absent)
+ * fields are created on first input.
+ *
+ * @param {FormViewOptions} [options]
+ * @returns {Record<string, any>} An `actions` fragment (plain JSON) to
+ *   spread into an app document.
+ */
+export declare function createFormActions(options?: FormViewOptions): Record<string, any>;

package/dist/types/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file @jarenjs/app — applications as JSON documents: the compiled
+ * dispatch loop over @jarenjs/json engines and the @jarenjs/view
+ * renderer. See README.md and docs/APP-FORMAT.md.
+ */
+export { createApp } from './app.js';
+export { compileActions, compileSubs } from './actions.js';
+export { createFormView, createFormActions, formEventFields } from './forms.js';
+export { createTaskEffect } from './tasks.js';
+export { createFocusEffect } from './focus.js';
+export { createTransactionLog } from './diagnostics.js';
+export { createSplitterWidget } from './splitter.js';
+export { createDocStore, encodeShare, decodeShare } from './docstore.js';
+export { AppCompileError, AppRuntimeError, HostValueError, toError, APP_CODES } from './errors.js';

package/dist/types/splitter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file A reusable drag-splitter widget for a two-pane (or rail|editor|stage)
+ * grid. It drives a CSS ratio variable LIVE during a drag — no per-move
+ * dispatch, which would flood the transaction log and undo — and commits the
+ * ratio on pointer-UP only, plus keyboard resize as an ARIA separator. Every
+ * DOM call is guarded so it mounts inertly over a headless stub (there the
+ * live drag is browser-verified). The host binds it as a widget and
+ * parameterizes the grid/rail selectors, the CSS variable and the commit
+ * action, so studio, play and any future two-pane surface share one splitter.
+ */
+/**
+ * @param {Object} opts
+ * @param {string} opts.action - the app action dispatched with the committed ratio
+ * @param {string} [opts.grid='.jstudio'] - selector for the grid element (the host's closest ancestor)
+ * @param {string} [opts.rail] - selector for a fixed left rail inside the grid; the ratio
+ *   spans from the rail's right edge (or the grid's left when absent) to the grid's right
+ * @param {string} [opts.cssVar='--js-ratio'] - the CSS custom property the grid reads for the split
+ * @param {number} [opts.min=0.1] - the smallest left-pane ratio (also Home)
+ * @param {number} [opts.max=0.9] - the largest left-pane ratio (also End)
+ * @param {number} [opts.step=0.05] - the arrow-key step
+ * @param {number} [opts.fineStep=0.01] - the Shift+arrow step
+ * @returns {{ mount: Function, update: Function, unmount: Function }}
+ */
+export declare function createSplitterWidget(opts: {
+    action: string;
+    grid?: string;
+    rail?: string;
+    cssVar?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    fineStep?: number;
+}): {
+    mount: Function;
+    update: Function;
+    unmount: Function;
+};

package/dist/types/tasks.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @file The host half of the async-task convention (docs/TASKS.md).
+ *
+ * The convention has two halves and this module is deliberately only one
+ * of them: **correctness lives in state** — a task slot's monotonic `id`
+ * and the completion action's guard reject stale responses — while
+ * **cancellation and concurrency live here**, as an optimization that
+ * stops wasting the wire. An aborted fetch may already have resolved and
+ * its dispatch may already be queued, so a host that only aborts is
+ * still wrong; the state-side guard is the guarantee.
+ *
+ * No timers, no state beyond the per-slot records, no dependencies
+ * (`AbortController` is platform).
+ */
+export type TaskRun = (props: any, signal: AbortSignal) => any | PromiseLike<any>;
+export type TaskMode = 'switch' | 'exhaust' | 'concat' | 'parallel';
+export type TaskEffectOptions = {
+    /**
+     * - The per-slot concurrency mode
+     * (default `"switch"`).
+     */
+    mode?: TaskMode;
+};
+export type TaskEffect = ((props: any, dispatch: (name: string, payload?: any) => void) => void) & {
+    cancel: (slot?: string) => void;
+    cancelAll: () => void;
+    dispose: () => void;
+};
+/**
+ * The host's task function, typically wrapping `fetch`. A synchronous
+ * return is allowed — the effect settles every result through one
+ * uniform promise boundary either way.
+ * @callback TaskRun
+ * @param {any} props - The effect's `with` value, verbatim.
+ * @param {AbortSignal} signal - Aborted when the slot's concurrency mode
+ *   supersedes this task, when the host cancels the slot, or when the
+ *   effect is disposed; pass it to `fetch` (or ignore it — the
+ *   state-side id guard stays correct either way).
+ * @returns {any | PromiseLike<any>} The JSON result, or a promise of it.
+ */
+/**
+ * Per-slot concurrency modes (APP-FORMAT §9.2):
+ *
+ *  - `"switch"`   (default) — starting a task aborts the slot's
+ *    in-flight predecessor; the newest request wins.
+ *  - `"exhaust"`  — while the slot has an in-flight task, new starts are
+ *    ignored entirely (nothing dispatched) — the mode for a
+ *    non-idempotent commit where a double-click must not double-run.
+ *  - `"concat"`   — new starts queue and run one after another, in
+ *    order — only for deliberately ordered commands.
+ *  - `"parallel"` — every start runs concurrently; the consumer owns
+ *    the merge rule.
+ *
+ * Whatever the mode, correctness stays visible in JSON state: the task
+ * slot's monotonic `id` and the completion action's guard remain the
+ * authority on which response may land.
+ * @typedef {'switch' | 'exhaust' | 'concat' | 'parallel'} TaskMode
+ */
+/**
+ * @typedef {Object} TaskEffectOptions
+ * @property {TaskMode} [mode] - The per-slot concurrency mode
+ *   (default `"switch"`).
+ */
+/**
+ * The effect handler returned by {@link createTaskEffect}, with its
+ * host-side controls.
+ * @typedef {((props: any, dispatch: (name: string, payload?: any) => void) => void) & {
+ *   cancel: (slot?: string) => void,
+ *   cancelAll: () => void,
+ *   dispose: () => void,
+ * }} TaskEffect
+ */
+/**
+ * Package `run` as a registered effect handler implementing the
+ * async-task convention. The effect's `with` props (all JSON):
+ *
+ *  - `id`   (REQUIRED) — the task identity, echoed back verbatim in the
+ *    completion payload for the state-side guard;
+ *  - `done` (REQUIRED) — the action dispatched on settle;
+ *  - `fail` (OPTIONAL, string) — the action for rejections; absent,
+ *    rejections dispatch `done` with `{ id, error }` instead of
+ *    `{ id, result }` — one completion action guarding on
+ *    `$payload.error` is the query-friendliest shape;
+ *  - `slot` (OPTIONAL, string) — the concurrency key, default `""`;
+ *    what a new start does to the slot's in-flight task is the
+ *    effect's `mode` (see {@link TaskMode});
+ *  - anything else `run` needs (a URL, a query, ...).
+ *
+ * Settlement, exactly: `run` is invoked through a uniform promise
+ * boundary, so a synchronous throw and a non-promise return settle
+ * through the same path as a rejection/resolution. A resolution
+ * dispatches `done` with `{ id, result }`; an abort rejection
+ * (`err.name === "AbortError"`) dispatches **nothing** — a superseded
+ * task is dead by design, its successor's dispatch carries the story;
+ * any other rejection dispatches `fail ?? done` with `{ id, error }`
+ * where `error` is a string, never an Error object — JSON only crosses
+ * the boundary. After `dispose()` no settlement dispatches anything.
+ * A malformed `id`/`done`/`fail`/`slot` is a host programming error:
+ * the handler throws a `TypeError`, which the loop reports as `JA2007`.
+ * Settlement is TOTAL for every rejection value (hostile accessors,
+ * revoked proxies included) and never creates an unhandled rejection
+ * from framework code; a settlement dispatch that itself throws (a
+ * rethrowing error sink surfacing at the dispatch boundary) is
+ * re-raised on its own microtask so the host's global error handling
+ * observes it.
+ *
+ * Host-side controls on the returned handler:
+ *
+ *  - `cancel(slot)` — abort the slot's in-flight task(s) and discard
+ *    its queued (`concat`) starts;
+ *  - `cancelAll()`  — `cancel` for every slot;
+ *  - `dispose()`    — terminal: `cancelAll()` plus a permanent guard —
+ *    late settlements can no longer dispatch, and new starts are
+ *    ignored. Idempotent. `app.destroy()` calls it automatically for
+ *    every registered handler exposing it.
+ *
+ * @example
+ * createApp(doc, {
+ *   effects: {
+ *     http: createTaskEffect((props, signal) =>
+ *       fetch(props.url, { signal }).then((r) => r.json())),
+ *   },
+ * });
+ *
+ * @param {TaskRun} run
+ * @param {TaskEffectOptions} [options]
+ * @returns {TaskEffect}
+ */
+export declare function createTaskEffect(run: TaskRun, options?: TaskEffectOptions): TaskEffect;