jsonisch 0.1.0

package/dist/form-ref-D_xHSaqL.d.ts

@@ -0,0 +1,994 @@
+//#region src/core/types/path.d.ts
+/**
+ * One step of a path: an object property key or an array index.
+ */
+type PathSegment = string | number;
+/**
+ * A path from the form root to a field. Paths are runtime values — our
+ * schemas come from the database, so there is no type-level path inference.
+ */
+type Path = PathSegment[];
+//#endregion
+//#region src/core/types/schema.d.ts
+/**
+ * A JSON-Schema node as stored in the database.
+ *
+ * Structured over the keys the store walk and codec read; everything else
+ * (including the `x-*` vocabulary: `x-column`, `x-formula`, `x-ui`,
+ * `x-relation*`, …) is reachable through the index signature. Schemas are
+ * runtime DB data — there is no compile-time value inference.
+ */
+interface JsonSchema {
+  /**
+   * The JSON-Schema type. May be a union list (e.g. `["string", "null"]`
+   * for nullable fields).
+   */
+  type?: string | string[];
+  /**
+   * Object properties. Presence makes the node an object field store.
+   */
+  properties?: Record<string, JsonSchema>;
+  /**
+   * Required property names of an object node. Properties not listed are
+   * optional and default to `undefined` instead of their empty input.
+   */
+  required?: string[];
+  /**
+   * Array item schema. A single schema makes the node an array field store;
+   * tuple form (an array of schemas) is not supported. An array-typed node
+   * WITHOUT items stays a value leaf whose value is the whole array (legacy
+   * relation arrays).
+   */
+  items?: JsonSchema | JsonSchema[];
+  /**
+   * String format hint (date, email, phone, currency, …).
+   */
+  format?: string;
+  /**
+   * Relation reference (`schema://…`). Makes the node a relation value leaf.
+   */
+  $ref?: string;
+  enum?: unknown[];
+  oneOf?: unknown[];
+  const?: unknown;
+  uniqueItems?: boolean;
+  additionalProperties?: unknown;
+  /**
+   * Our `x-*` vocabulary and any other JSON-Schema keywords.
+   */
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/core/signal.d.ts
+/**
+ * Reactive signal primitive for jsonisch.
+ *
+ * A deliberately tiny push-based reactivity system built for a per-component
+ * subscription model (see `jsonisch/react` `useSignalSnapshot`):
+ *
+ * - Reads made while a listener is active (via `withListener`, or a
+ *   `Tracker`'s `read`) subscribe that listener to the signal.
+ * - Subscriptions are ONE-SHOT: notifying a listener consumes its
+ *   subscription. Listeners are expected to re-read (and thereby
+ *   re-subscribe) as a consequence of being notified — exactly what a React
+ *   component does when its render re-runs.
+ * - `computed` signals are lazy and cached. Staleness propagates through the
+ *   computed graph eagerly (even inside `batch`), so a read always reflects
+ *   the latest written inputs; only plain listener notifications (e.g.
+ *   component re-renders) are deferred by `batch`.
+ *
+ * Known trade-off (documented, not a bug): outside `batch`, a plain listener
+ * whose `notify` synchronously reads other signals may observe a stale
+ * computed across a "diamond" dependency while sibling invalidations are
+ * still propagating. The React adapter is immune because `notify` only
+ * schedules a re-render; core methods that write multiple signals should use
+ * `batch`.
+ */
+/**
+ * A writable reactive signal.
+ */
+interface Signal<T> {
+  /**
+   * The value of the signal. Reading subscribes the active listener;
+   * writing a non-`Object.is`-equal value notifies subscribers.
+   */
+  value: T;
+}
+/**
+ * A read-only reactive signal (the shape returned by `computed`).
+ */
+interface ReadonlySignal<T> {
+  /**
+   * The value of the signal. Reading subscribes the active listener.
+   */
+  readonly value: T;
+}
+/**
+ * A subscription target. One listener typically represents one component
+ * (React adapter) or one computed signal (internal).
+ */
+interface Listener {
+  /**
+   * Notifies the listener that a subscribed signal changed. Deferred (and
+   * de-duplicated) while a `batch` is active.
+   */
+  notify: () => void;
+  /**
+   * The subscriber sets this listener is currently registered in. Used to
+   * clean up subscriptions when the listener goes away (e.g. unmount) and
+   * kept in sync by the one-shot notification cycle.
+   */
+  subscriptions: Set<Set<Listener>>;
+  /**
+   * Optional immediate invalidation hook. When present it runs synchronously
+   * at write time, even inside `batch`. Computed signals use it to mark
+   * themselves stale and propagate invalidation through the graph so that
+   * reads inside a batch never see stale cached values.
+   */
+  invalidate?: () => void;
+}
+/**
+ * Runs a function with the given listener active, restoring the previous
+ * listener afterwards (throw included). This is the ONLY way to activate a
+ * listener — a set-and-forget global (the v1 `setListener`) let one
+ * component's tracking window leak into whatever rendered next; the scoped
+ * form makes that structurally impossible.
+ *
+ * @param listener The listener to activate (or `undefined` to suspend
+ * tracking, the `untrack` case).
+ * @param fn The function whose signal reads subscribe the listener.
+ *
+ * @returns The return value of the function.
+ */
+declare function withListener<T>(listener: Listener | undefined, fn: () => T): T;
+/**
+ * Returns the currently active listener, if any.
+ *
+ * Advanced/internal: exposed for tests that verify subscription bookkeeping.
+ */
+declare function getListener(): Listener | undefined;
+/**
+ * A retained tracked-read handle: `read` subscribes its owner to every
+ * signal the function touches, `dispose` drops all current subscriptions.
+ */
+interface Tracker {
+  /**
+   * Runs the function with the tracker's listener active and returns its
+   * result. One-shot semantics apply: a notification consumes the
+   * subscriptions, so the notified party re-reads (and thereby
+   * re-subscribes) to stay live.
+   */
+  readonly read: <T>(fn: () => T) => T;
+  /**
+   * Drops every current subscription. The tracker stays usable — a later
+   * `read` re-subscribes.
+   */
+  readonly dispose: () => void;
+}
+/**
+ * Creates a tracker: the non-React primitive the react adapter's snapshot
+ * store is built on. `onInvalidate` fires when any signal read during the
+ * last `read` changes (deferred and de-duplicated by an active `batch`).
+ *
+ * @param onInvalidate Called when a tracked signal changes.
+ *
+ * @returns The created tracker.
+ */
+declare function createTracker(onInvalidate: () => void): Tracker;
+/**
+ * Creates a writable reactive signal without an initial value.
+ *
+ * @returns The created signal.
+ */
+declare function createSignal<T>(): Signal<T | undefined>;
+/**
+ * Creates a writable reactive signal with an initial value.
+ *
+ * @param initialValue The initial value.
+ *
+ * @returns The created signal.
+ */
+declare function createSignal<T>(initialValue: T): Signal<T>;
+/**
+ * Creates a lazy, cached, read-only signal derived from other signals.
+ *
+ * The compute function runs on first read and again after any signal it read
+ * during its last run changes (dependencies are re-tracked on every run, so
+ * conditional reads narrow or widen the dependency set). Subscribers of the
+ * computed are notified when it is invalidated; the fresh value is produced
+ * on the next read.
+ *
+ * @param compute The function deriving the value.
+ *
+ * @returns The created read-only signal.
+ */
+declare function computed<T>(compute: () => T): ReadonlySignal<T>;
+/**
+ * Batches signal writes: plain listener notifications (e.g. component
+ * re-renders) are collected, de-duplicated, and delivered once when the
+ * outermost batch ends. Computed invalidation is NOT deferred, so reads
+ * inside the batch observe the written values.
+ *
+ * @param fn The function to execute in the batch.
+ *
+ * @returns The return value of the function.
+ */
+declare function batch<T>(fn: () => T): T;
+/**
+ * Executes a function without tracking signal reads as subscriptions.
+ *
+ * @param fn The function to execute untracked.
+ *
+ * @returns The return value of the function.
+ */
+declare function untrack<T>(fn: () => T): T;
+//#endregion
+//#region src/core/control.d.ts
+/**
+ * The UI-side vocabulary: what kind of widget a field renders as. Distinct
+ * from JSON-Schema `type` — e.g. "string" can map to many kinds (text,
+ * email, currency, …).
+ *
+ * Closed set, deliberately opinionated (US-lending-flavored: ein, ssn,
+ * us-state, legal-id, interest-rate, line-item); widgets are host-supplied,
+ * so unused kinds cost nothing. Add explicitly when a new widget exists.
+ */
+declare const CONTROL_KINDS: readonly ["text", "textarea", "number", "boolean", "date", "address", "email", "email-array", "phone", "phone-array", "link-array", "currency", "percent", "interest-rate", "ein", "ssn", "us-state", "legal-id", "select", "multiselect", "formula", "estimate", "amount-or-percent", "line-item", "object-array", "hidden"];
+type ControlKind = (typeof CONTROL_KINDS)[number];
+/**
+ * Decides which UI widget kind a JSON-Schema node renders as.
+ *
+ * Precedence:
+ *   1. Relations — `$ref`, array-of-`$ref`, or `x-relation`/flat
+ *      `x-relation-target`. Single → select, many → multiselect.
+ *   2. Explicit `x-ui.control`, plus the `estimate: true` attribute
+ *      promoting a formula to an estimate.
+ *   3. `format` — JSON-Schema standard widget hints on strings.
+ *   4. `type` — JSON-Schema primitive fallback.
+ *
+ * @param schema The JSON-Schema node.
+ *
+ * @returns The control kind.
+ */
+declare function inferControl(schema: JsonSchema): ControlKind;
+//#endregion
+//#region src/core/types/visibility.d.ts
+/**
+ * The comparison operator of a `VisibleWhen` condition. `equals`/`one-of`/
+ * `contains` come from a schema `then` branch; the `else` branch flips them
+ * to the `not-` variants. `one-of` (LOS-822) carries an array `value` and
+ * passes while the watched value equals ANY element.
+ */
+type VisibleWhenOp = "equals" | "not-equals" | "one-of" | "not-one-of" | "contains" | "not-contains";
+/**
+ * A resolved conditional-visibility rule: the field renders only while the
+ * watched field's value satisfies the condition. Resolved once at store
+ * init from the root schema's `allOf` `if/then/else` blocks; hidden values
+ * are RETAINED (visibility gates rendering, never state or payload).
+ */
+interface VisibleWhen {
+  /**
+   * The watched field reference: a root-level field key, or the
+   * root-record bracket form (`record[key]` by default) reading `key` off the
+   * object stored under the form's `rootRecordAlias` in the eval scope (the
+   * host layers into `offFormValues` — LOS-463/LOS-471).
+   */
+  readonly field: string;
+  /**
+   * The comparison operator.
+   */
+  readonly op: VisibleWhenOp;
+  /**
+   * The value the watched field is compared against.
+   */
+  readonly value: unknown;
+}
+//#endregion
+//#region src/core/types/field.d.ts
+/**
+ * The structural kind of a field store node, mirroring the JSON-Schema
+ * shape: `properties` → object, single-schema `items` → array, everything
+ * else (including `items`-less array-typed nodes, whose whole array is the
+ * value) → value. Orthogonal to `ControlKind`, the widget vocabulary.
+ */
+type FieldKind = "array" | "object" | "value";
+/**
+ * A DOM element a value field can be bound to.
+ *
+ * Type-only reference: core never touches the DOM at runtime and stays
+ * isomorphic; the react adapter populates these.
+ */
+type FieldElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+/**
+ * The errors of a field: at least one message, or `null` when valid.
+ * Validation issues (AJV) and calc errors land in the same channel.
+ */
+type FieldErrors = [string, ...string[]] | null;
+/**
+ * State shared by every field store node.
+ */
+interface InternalBaseStore {
+  /**
+   * The kind of field store.
+   */
+  kind: FieldKind;
+  /**
+   * The property name of the field (last path segment as a string).
+   */
+  name: string;
+  /**
+   * The path from the form root to the field.
+   */
+  path: Path;
+  /**
+   * The JSON-Schema node this field was derived from.
+   */
+  schema: JsonSchema;
+  /**
+   * The widget kind this field renders as, resolved once at walk time via
+   * `inferControl`.
+   */
+  control: ControlKind;
+  /**
+   * Whether the field accepts a nullish value: its `type` includes `"null"`
+   * or its key is not in the parent's `required` list. Nullish fields keep
+   * `undefined`/`null` instead of defaulting to their empty input.
+   */
+  isNullish: boolean;
+  /**
+   * The DOM elements bound to the field (react adapter only; empty on the
+   * server).
+   */
+  elements: FieldElement[];
+  /**
+   * The elements the field registered itself (its reset baseline). Array
+   * methods move `elements` between field stores during reorders; `reset`
+   * restores each field's original elements via `elements = initialElements`.
+   * Starts as the SAME array reference as `elements` so registrations made
+   * before any reorder land in both.
+   */
+  initialElements: FieldElement[];
+  /**
+   * The errors of the field — the ONE read channel (validation + calc).
+   * For most fields this is the same object as `validationErrors`; a
+   * formula field swaps in a computed composing `validationErrors` with
+   * its derived signal's calc error, so validation passes can never
+   * clobber a calc error (and vice versa).
+   */
+  errors: ReadonlySignal<FieldErrors>;
+  /**
+   * The validation-sourced errors of the field. The ONLY writable error
+   * store — every writer (validate routing, `setErrors`, reset, item-state
+   * transfer) goes through this; calc errors are derived, never written.
+   */
+  validationErrors: Signal<FieldErrors>;
+  /**
+   * Whether the field has been focused.
+   */
+  isTouched: Signal<boolean>;
+  /**
+   * Whether the field's value has ever been changed. Unlike `isDirty` it
+   * stays `true` when the value is changed back; only a reset clears it.
+   */
+  isEdited: Signal<boolean>;
+  /**
+   * Whether the field's value differs from its start input (semantic,
+   * empty-aware compare: `null` ≡ `undefined` ≡ `""`).
+   */
+  isDirty: Signal<boolean>;
+  /**
+   * The conditional-visibility rule of the field, resolved once at store
+   * init from the root schema's `allOf` `if/then/else` blocks. Root-level
+   * fields only (derivation reaches into rows, visibility does not yet);
+   * absent on ungated fields.
+   */
+  visibleWhen?: VisibleWhen | undefined;
+  /**
+   * Whether the field currently renders: a computed over the watched
+   * field's resolved value (form wins, `offFormValues` fills). Present
+   * only alongside `visibleWhen` — absent means always visible. Gates
+   * RENDERING only; a hidden field keeps its state, dirtiness, and place
+   * in the payload.
+   */
+  visible?: ReadonlySignal<boolean> | undefined;
+}
+/**
+ * Presence marker for container (array/object) inputs: `true` when the value
+ * lives in the children, or the nullish value itself.
+ */
+type ContainerInput = true | null | undefined;
+/**
+ * An array field store node.
+ */
+interface InternalArrayStore extends InternalBaseStore {
+  kind: "array";
+  /**
+   * The single item schema, validated non-tuple at walk time (so growth
+   * paths never re-trust `schema.items`).
+   */
+  itemSchema: JsonSchema;
+  /**
+   * The child stores, one per array item.
+   */
+  children: InternalFieldStore[];
+  /**
+   * The initial input presence (reset target; does not move with items).
+   */
+  initialInput: Signal<ContainerInput>;
+  /**
+   * The start input presence (dirty baseline; moves with items).
+   */
+  startInput: Signal<ContainerInput>;
+  /**
+   * The current input presence.
+   */
+  input: Signal<ContainerInput>;
+  /**
+   * The initial item IDs (reset target; does not move with items).
+   */
+  initialItems: Signal<string[]>;
+  /**
+   * The start item IDs (dirty baseline for length changes).
+   */
+  startItems: Signal<string[]>;
+  /**
+   * The current item IDs, one stable ID per array item. The item count is
+   * the authoritative array length (`children` may hold stale stores past
+   * the end after a shrink, kept for baseline reuse on regrow).
+   */
+  items: Signal<string[]>;
+}
+/**
+ * An object field store node.
+ */
+interface InternalObjectStore extends InternalBaseStore {
+  kind: "object";
+  /**
+   * The child stores, keyed by property name.
+   */
+  children: Record<string, InternalFieldStore>;
+  /**
+   * The initial input presence (reset target).
+   */
+  initialInput: Signal<ContainerInput>;
+  /**
+   * The start input presence (dirty baseline).
+   */
+  startInput: Signal<ContainerInput>;
+  /**
+   * The current input presence.
+   */
+  input: Signal<ContainerInput>;
+}
+/**
+ * A leaf value field store node.
+ *
+ * Inputs are `unknown` — our schemas are runtime DB data, so there is no
+ * compile-time value inference.
+ *
+ * Feature state (derivation channels, envelope meta, visibility beyond
+ * the base rule) lives in plugin slots keyed by this store's identity
+ * (`FieldSlotKey`), never here — core's field shape has no compile-time
+ * dependency on any feature.
+ */
+interface InternalValueStore extends InternalBaseStore {
+  kind: "value";
+  /**
+   * The initial input (reset target).
+   */
+  initialInput: Signal<unknown>;
+  /**
+   * The start input (dirty baseline; `applyBaseline` may update it).
+   */
+  startInput: Signal<unknown>;
+  /**
+   * The current input.
+   */
+  input: Signal<unknown>;
+}
+/**
+ * Any field store node.
+ */
+type InternalFieldStore = InternalArrayStore | InternalObjectStore | InternalValueStore;
+//#endregion
+//#region src/core/plugin/key.d.ts
+declare const stateBrand: unique symbol;
+/**
+ * The identity a plugin's state is stored under in the form store's
+ * `pluginState` map (the ProseMirror pattern, minus its string-name
+ * registry). The generic is a phantom — it exists only so `getState`
+ * returns the right type; nothing is stored on the key itself.
+ *
+ * Keys are module-level singletons exported next to their plugin factory.
+ * Cross-plugin reads go through the exported key (derivation imports
+ * `envelopesKey`, never the envelopes implementation), and stay
+ * `T | undefined` — a form without the owning plugin is a legal config.
+ */
+declare class PluginKey<TState> {
+  readonly name: string;
+  private readonly [stateBrand];
+  constructor(name: string);
+  /**
+   * Reads the owning plugin's state off a form store, or `undefined` when
+   * the plugin is not registered on this form.
+   */
+  getState(form: InternalFormStore): TState | undefined;
+}
+/**
+ * A plugin key whose state is a per-field map keyed by field-store
+ * IDENTITY. Field stores are position-fixed — array operations move signal
+ * VALUES between stores, not the stores themselves — so per-field slots
+ * must transfer with item state via the `transferField`/`swapField` hooks,
+ * exactly like the input signals they sit next to.
+ */
+declare class FieldSlotKey<TSlot> extends PluginKey<Map<InternalFieldStore, TSlot>> {
+  /**
+   * Reads one field's slot, or `undefined` when the plugin is absent or the
+   * field carries no slot (a bare scalar to this plugin).
+   */
+  get(form: InternalFormStore, store: InternalFieldStore): TSlot | undefined;
+}
+//#endregion
+//#region src/core/plugin/types.d.ts
+/**
+ * A persisted wire entry split into its halves: the field's own value and
+ * the plugin-owned meta channel nested next to it.
+ */
+interface WireEnvelope {
+  readonly value: unknown;
+  readonly meta: Record<string, unknown>;
+}
+/**
+ * A plugin's STATIC wire behavior — a plain descriptor exported next to the
+ * plugin factory, never runtime state, because the codec is isomorphic: the
+ * server imports the same descriptor for save routing (`encodeDirty`) with
+ * no form store anywhere (D7).
+ */
+interface WireContract {
+  /**
+   * The controls whose persisted shape is the kind-discriminated envelope.
+   * Core's decode paths unwrap these at the value leaf; everything else
+   * stays a bare value.
+   */
+  readonly envelopeControls?: readonly string[];
+  /**
+   * Splits a raw persisted entry into its halves. Non-envelope raw (bad
+   * data) must decode defensively as `{ value: raw, meta: {} }`.
+   */
+  readonly unwrap?: (raw: unknown) => WireEnvelope;
+  /**
+   * Returns whether a declared key's outgoing value must be dropped from
+   * the save payload entirely (`encodeDirty`) — e.g. a formula value, which
+   * is always server-recomputed.
+   */
+  readonly skipValue?: (control: string, dirty: Record<string, unknown>, key: string) => boolean;
+  /**
+   * Normalizes a declared key's outgoing value in `encodeDirty` — the
+   * server-side enforcement twin of the client plugin's `encodeValue` (e.g.
+   * stripping the value half of an estimate envelope that does not pin
+   * `mode: "estimate"`). Returning `undefined` drops the key.
+   */
+  readonly encode?: (control: string, raw: unknown) => unknown;
+}
+/**
+ * The context every per-form plugin hook receives: the form store and the
+ * plugin's own state (created by its `build`).
+ */
+interface PluginCtx<TState> {
+  readonly form: InternalFormStore;
+  readonly state: TState;
+}
+/**
+ * A jsonisch plugin: a plain object from a factory. Config lives in the
+ * factory closure; all mutable state is created inside `build`, keyed to
+ * the form store (a module-scope-hoisted plugin shared by two open forms
+ * must not cross-write). Registration happens only in the `createFormStore`
+ * config — no late registration.
+ *
+ * Every hook is sync — passes run inside `batch(() => untrack(() => …))`
+ * and an `await` there would let React render a half-rebased form.
+ *
+ * Core owns the phases: each hook is a pinned call site in core (a plugin
+ * can never sort itself before the value rebase). Plugins only order among
+ * themselves — array order within each hook, validated by `dependsOn`.
+ */
+interface JsonischPlugin<TState = unknown> {
+  /**
+   * The plugin name (error attribution + uniqueness).
+   */
+  readonly name: string;
+  /**
+   * The identity the plugin's state is stored under. Exported as a
+   * module-level singleton so other plugins can read this plugin's state
+   * without importing its implementation.
+   */
+  readonly key: PluginKey<TState>;
+  /**
+   * Keys of plugins that must be registered EARLIER in the plugins array.
+   * `createFormStore` throws when one is missing or later — turning
+   * ordering comments into hard startup errors (the estimate-pin data-loss
+   * scenario of D2).
+   */
+  readonly dependsOn?: readonly PluginKey<unknown>[];
+  /**
+   * The plugin's static wire contract, collected onto the form store so
+   * core's decode paths can unwrap envelopes. The same descriptor object is
+   * exported next to the factory for the server-side `encodeDirty`.
+   */
+  readonly wire?: WireContract;
+  /**
+   * 1 — creates the plugin's state container, BEFORE the schema walk (so
+   * the walk can dispatch `buildScope` for the rows it creates). No tree
+   * access here — scope work belongs in `buildScope`.
+   */
+  build(form: InternalFormStore, config: FormConfig): TState;
+  /**
+   * 2 — wires one object scope, in plugin array order: the form root
+   * (after the walk, with the raw initial input) and every array-item
+   * object AS THE WALK CREATES IT (with the raw row object). A row created
+   * by an insert or a whole-array write behaves exactly like one the
+   * record loaded with.
+   */
+  buildScope?(ctx: PluginCtx<TState>, scope: InternalObjectStore, raw: unknown): void;
+  /**
+   * 3 — re-seeds an EXISTING row scope that adopts a different row (an
+   * array shrink-then-regrow, a grown baseline row). Signals must be
+   * re-seeded in place, never replaced — computeds already wired to them
+   * keep tracking.
+   */
+  reseedScope?(ctx: PluginCtx<TState>, scope: InternalObjectStore, raw: unknown): void;
+  /**
+   * 4 — per value leaf, from INSIDE reset's existing walk (scoped resets
+   * stay correct for free). Restore live plugin state to its decode-time
+   * baseline.
+   */
+  resetField?(ctx: PluginCtx<TState>, store: InternalFieldStore): void;
+  /**
+   * 4b — live input write for a value leaf (`setFieldInput`). Return
+   * `true` when the plugin wrote `store.input` (and its own slot) so core
+   * does not write the leaf again. Envelope fields use this so a
+   * keystroke updates `envelope.value` through `writeEnvelope`.
+   */
+  syncInput?(ctx: PluginCtx<TState>, store: InternalValueStore, input: unknown): boolean;
+  /**
+   * 4c — `reset({ initialInput })` has just written this leaf's
+   * `initialInput` from `raw`. Re-decode the start envelope from that
+   * same raw so `resetField` restores number and mode from one object.
+   * Not called from `applyBaseline` (rebase owns that adopt).
+   */
+  syncInitial?(ctx: PluginCtx<TState>, store: InternalValueStore, raw: unknown): void;
+  /**
+   * 5 — after the value/baseline rebase of one object scope: the form root
+   * (from `applyBaseline`, with the raw decoded record) and each array-item
+   * object (from the baseline rebase walk, with the fresh raw row). The
+   * plugin owns its own decode of the raw.
+   */
+  rebase?(ctx: PluginCtx<TState>, scope: InternalObjectStore, raw: unknown): void;
+  /**
+   * 6 — item-state transfer: per-field plugin state travels with its row
+   * through an insert, remove or move, exactly like the input signals
+   * (`copyItemState`). Field stores are position-fixed; only values move.
+   */
+  transferField?(ctx: PluginCtx<TState>, from: InternalValueStore, to: InternalValueStore): void;
+  /**
+   * 7 — the swap twin of `transferField` (`swapItemState`).
+   */
+  swapField?(ctx: PluginCtx<TState>, first: InternalValueStore, second: InternalValueStore): void;
+  /**
+   * 8 — whether THIS field's plugin state is dirty (must serialize). Feeds
+   * the subtree dirty walks that decide payload emission.
+   */
+  fieldIsDirty?(ctx: PluginCtx<TState>, store: InternalValueStore): boolean;
+  /**
+   * 9 — wraps a value field's own payload entry (the LOS-573 envelope):
+   * called for a dirty leaf with its outgoing value (`undefined` when only
+   * the plugin half is dirty), returns the wire entry to emit — or
+   * `undefined` for "no opinion" (a bare scalar). Two plugins claiming the
+   * same field throw.
+   */
+  encodeValue?(ctx: PluginCtx<TState>, store: InternalValueStore, valueOut: unknown): unknown;
+  /**
+   * 10 — the plugin's contribution to form-level `isDirty`. Runs inside a
+   * computed, so it MUST read its signals unconditionally — the aggregate
+   * never short-circuits between plugins (an unran handler contributes no
+   * signal reads and deafens the projection).
+   */
+  isDirty?(ctx: PluginCtx<TState>): boolean;
+  /**
+   * 11 — members merged into the react field snapshot, computed inside the
+   * library-owned tracked read (the D5 snapshot model): plain values read
+   * off signals — never getters — plus identity-stable callbacks (a fresh
+   * closure per call would defeat the snapshot equality gate and re-render
+   * every notification; cache them on the plugin's per-field state). Types
+   * ride the `FieldStoreSlots` declare-module augmentation in the plugin's
+   * own file. A key claimed twice, or colliding with a core field member,
+   * throws.
+   */
+  fieldSnapshot?(ctx: PluginCtx<TState>, store: InternalFieldStore, path: Path): Record<string, unknown>;
+}
+/**
+ * The `plugins` config entry: factories may be composed conditionally —
+ * falsy entries and nested arrays are accepted and flattened
+ * (`plugins: [envelopes(), engine && derivation(engine)]`).
+ */
+type PluginsInput = ReadonlyArray<JsonischPlugin<unknown> | false | null | undefined | ReadonlyArray<JsonischPlugin<unknown> | false | null | undefined>>;
+//#endregion
+//#region src/core/plugin/driver.d.ts
+/**
+ * The hooks the driver precomputes implementer lists for (the per-field
+ * ones run in loops; scanning all plugins per field would be quadratic).
+ */
+declare const HOOK_NAMES: readonly ["buildScope", "reseedScope", "resetField", "syncInput", "syncInitial", "rebase", "transferField", "swapField", "fieldIsDirty", "encodeValue", "isDirty", "fieldSnapshot"];
+type HookName = (typeof HOOK_NAMES)[number];
+/**
+ * The resolved plugin runtime on a form store: the flat plugin list,
+ * per-hook implementer lists, and the envelope wire contracts keyed by
+ * control kind — all precomputed once at `createFormStore`.
+ */
+interface PluginDriver {
+  readonly plugins: readonly JsonischPlugin<unknown>[];
+  readonly hooks: Readonly<Record<HookName, readonly JsonischPlugin<unknown>[]>>;
+  /**
+   * Envelope wire contracts by control kind (`estimate` →
+   * `envelopesWire`), consulted by the leaf decode paths.
+   */
+  readonly envelopes: ReadonlyMap<string, WireContract>;
+}
+/**
+ * Whether any plugin's form-level state is dirty. Runs inside the
+ * `isDirty` aggregate computed, so it reads EVERY implementer — never
+ * short-circuits: an unran handler contributes no signal reads and would
+ * deafen the projection.
+ */
+declare function pluginsDirty(form: InternalFormStore): boolean;
+/**
+ * Whether THIS value leaf's plugin state is dirty (must serialize). Reads
+ * every implementer for the same no-short-circuit reason as `pluginsDirty`
+ * — callers may sit inside computeds.
+ */
+declare function fieldPluginDirty(form: InternalFormStore, store: InternalValueStore): boolean;
+/**
+ * Whether any value leaf in the subtree has dirty plugin state — the
+ * plugin half of the dirty walks that decide payload emission (a mode flip
+ * with an unchanged value must still produce a payload). Reads array
+ * `items` (not raw `children`, which may hold stale stores past the end
+ * after a shrink), so a reactive caller subscribes to structural changes.
+ */
+declare function hasPluginDirtyField(form: InternalFormStore, store: InternalFieldStore): boolean;
+/**
+ * Encodes one dirty value leaf's payload entry: asks the `encodeValue`
+ * implementers to wrap it (the LOS-573 envelope). Exactly one plugin may
+ * claim a field; with no claim the outgoing value is emitted as-is.
+ *
+ * @param form The form store.
+ * @param store The value leaf being encoded.
+ * @param valueOut The outgoing value (`undefined` when only plugin state
+ * is dirty).
+ *
+ * @returns The wire entry to emit.
+ */
+declare function encodeFieldValue(form: InternalFormStore, store: InternalValueStore, valueOut: unknown): unknown;
+/**
+ * Unwraps a raw persisted leaf entry through the form's envelope wire
+ * contracts: an envelope-control leaf resolves its value half, everything
+ * else passes through. The single decode seam shared by the walk, reset,
+ * and the baseline rebase — a leaf can never round-trip to two different
+ * values.
+ */
+declare function unwrapLeafInput(form: InternalFormStore, control: string, raw: unknown): unknown;
+//#endregion
+//#region src/core/types/form.d.ts
+/**
+ * When validation runs. `validate` is the mode that arms validation the
+ * first time; `revalidate` takes over once the form is in the "already
+ * validated" state (submitted, or the triggering subtree has errors) — the
+ * formisch two-mode model: validate on submit, revalidate on input.
+ */
+type ValidationMode = "initial" | "touch" | "input" | "change" | "blur" | "submit";
+/**
+ * One validation issue in the injected validator's output. Deliberately
+ * AJV-shaped (`ErrorObject` subset) so an app can pass a compiled AJV
+ * validate function's `errors` through unchanged — jsonisch itself never
+ * depends on AJV.
+ */
+interface ValidationIssue {
+  /**
+   * JSON-Pointer to the failing value (`""` for the root). Routed to the
+   * field store's `errors` signal; an unroutable pointer lands on the
+   * nearest addressable ancestor.
+   */
+  readonly instancePath?: string | undefined;
+  /**
+   * The human-readable message. Falls back to a generic message when absent.
+   */
+  readonly message?: string | undefined;
+  /**
+   * The failed JSON-Schema keyword. `required` issues point at the parent
+   * object; routing appends `params.missingProperty` so the error lands on
+   * the missing field itself.
+   */
+  readonly keyword?: string | undefined;
+  /**
+   * Keyword-specific parameters (e.g. `missingProperty` for `required`).
+   */
+  readonly params?: Record<string, unknown> | undefined;
+}
+/**
+ * The injected validator: compiled ONCE per schema by the caller, returns
+ * the issues for an input (`null`/`undefined`/empty for a valid input).
+ * Synchronous by design — AJV is sync.
+ */
+type FormValidator = (input: unknown) => readonly ValidationIssue[] | null | undefined;
+/**
+ * Configuration for creating a form store.
+ */
+interface FormConfig {
+  /**
+   * The JSON-Schema the form is derived from (runtime DB data).
+   */
+  readonly schema: JsonSchema;
+  /**
+   * The initial input in the nested server-record shape (no pre-flattening).
+   * Keys not declared in the schema never enter form state (the schema is
+   * the allow-list).
+   */
+  readonly initialInput?: unknown;
+  /**
+   * Read-only eval scope for formula resolution (off-form values). Becomes a
+   * settable signal on the store; `applyBaseline` updates it.
+   */
+  readonly offFormValues?: Record<string, unknown>;
+  /**
+   * The identifier the host's stored formulas use for the root record
+   * (`record` by default). Why it exists: a row's eval scope is sealed to
+   * its own columns, so a per-row calc that needs a root value — an
+   * asset's share of `loan[totalLoanAmount]` — can only reach the root
+   * through this one name. Reserved in row scope (it wins over a row
+   * column of the same name); hosts whose schemas already say `loan[…]`
+   * pass `"loan"`.
+   */
+  readonly rootRecordAlias?: string | undefined;
+  /**
+   * The registered plugins, run in array order within each hook. Falsy
+   * entries and one level of nesting are accepted
+   * (`plugins: [envelopes(), engine && derivation(engine)]`). Everything
+   * computed on top of the base pipeline — envelope meta state,
+   * derivation, visibility — registers here; a form without plugins is a
+   * plain schema-walked value store.
+   */
+  readonly plugins?: PluginsInput | undefined;
+  /**
+   * The empty input a required field without an initial input starts at,
+   * keyed by JSON-Schema type. Merged over the default (`{ string: "" }` —
+   * required strings start as `""`, every other type as `undefined`).
+   */
+  readonly emptyInput?: Record<string, unknown>;
+  /**
+   * The injected validator, compiled once per schema by the caller. Without
+   * one the form always validates successfully (enforcement rollout is
+   * per-form opt-in).
+   */
+  readonly validator?: FormValidator | undefined;
+  /**
+   * The validation mode of the form. Defaults to `"submit"`.
+   */
+  readonly validate?: ValidationMode | undefined;
+  /**
+   * The revalidation mode of the form. Defaults to `"input"`.
+   */
+  readonly revalidate?: Exclude<ValidationMode, "initial"> | undefined;
+}
+/**
+ * The `computed`-cached form-level aggregates. Each one wraps a whole-tree
+ * `getFieldBool` walk (plus the meta channel for `isDirty`) so the walk
+ * runs once per invalidation instead of once per read — under the react
+ * adapter's snapshot model `useForm` reads these on every notification,
+ * which without caching would mean four full-tree walks per keystroke.
+ */
+interface FormAggregates {
+  /**
+   * Whether any field in the form has been touched.
+   */
+  readonly isTouched: ReadonlySignal<boolean>;
+  /**
+   * Whether any field in the form has been edited.
+   */
+  readonly isEdited: ReadonlySignal<boolean>;
+  /**
+   * Whether any field differs from its start input, OR any root-level
+   * field's meta channel is dirty (a mode flip with an unchanged value
+   * still produces a payload, so Save must enable).
+   */
+  readonly isDirty: ReadonlySignal<boolean>;
+  /**
+   * Whether no field in the form has validation errors. Calc errors are
+   * excluded — only user-fixable validation gates validity.
+   */
+  readonly isValid: ReadonlySignal<boolean>;
+}
+/**
+ * The internal form store: the root object node plus form-level state.
+ */
+interface InternalFormStore extends InternalObjectStore {
+  /**
+   * The resolved empty-input config (defaults merged with the form config),
+   * read by the walk when defaulting required fields without initial input.
+   */
+  emptyInput: Record<string, unknown>;
+  /**
+   * The resolved root-record alias (config value or the default) —
+   * the one home both the shelf alias writer and the scope resolvers read.
+   */
+  rootRecordAlias: string;
+  /**
+   * The injected validator, or `undefined` for a form without enforcement.
+   */
+  validator: FormValidator | undefined;
+  /**
+   * The resolved plugin runtime: flat plugin list, per-hook implementer
+   * lists, envelope wire contracts by control kind. Set BEFORE the walk so
+   * the walk can dispatch scope hooks for the rows it creates.
+   */
+  pluginDriver: PluginDriver;
+  /**
+   * Each plugin's state container, keyed by its `PluginKey` identity
+   * (created by the plugin's `build`). Read through the exported keys
+   * (`envelopesKey.get(form, store)`), never directly.
+   */
+  pluginState: Map<PluginKey<unknown>, unknown>;
+  /**
+   * The validation mode of the form.
+   */
+  validate: ValidationMode;
+  /**
+   * The revalidation mode of the form.
+   */
+  revalidate: Exclude<ValidationMode, "initial">;
+  /**
+   * The number of active validators (kept as a counter so a future async
+   * validator cannot flicker `isValidating`).
+   */
+  validators: number;
+  /**
+   * The form element (react adapter only; unset on the server).
+   */
+  element?: HTMLFormElement | undefined;
+  /**
+   * Off-form values used to fill `undefined` in formula scope resolution.
+   * Settable: `applyBaseline` updates it and dependents re-resolve.
+   */
+  offFormValues: Signal<Record<string, unknown>>;
+  /**
+   * The submitting state of the form.
+   */
+  isSubmitting: Signal<boolean>;
+  /**
+   * The submitted state of the form.
+   */
+  isSubmitted: Signal<boolean>;
+  /**
+   * The validating state of the form.
+   */
+  isValidating: Signal<boolean>;
+  /**
+   * The cached form-level aggregates (see `FormAggregates`).
+   */
+  aggregates: FormAggregates;
+}
+//#endregion
+//#region src/methods/form-ref.d.ts
+/**
+ * What every method accepts as its form argument: the internal form store
+ * itself, or any wrapper exposing it as `internal` (the react adapter's
+ * public `FormStore`). App code passes the wrapper; core and tests pass the
+ * internal store directly.
+ */
+type FormRef = InternalFormStore | {
+  readonly internal: InternalFormStore;
+};
+/**
+ * Unwraps a `FormRef` to the internal form store.
+ */
+declare function internalOf(form: FormRef): InternalFormStore;
+//#endregion
+export { VisibleWhen as A, createSignal as B, FieldErrors as C, InternalFieldStore as D, InternalBaseStore as E, ReadonlySignal as F, JsonSchema as G, getListener as H, Signal as I, Path as K, Tracker as L, ControlKind as M, inferControl as N, InternalObjectStore as O, Listener as P, batch as R, FieldElement as S, InternalArrayStore as T, untrack as U, createTracker as V, withListener as W, WireContract as _, InternalFormStore as a, PluginKey as b, PluginDriver as c, hasPluginDirtyField as d, pluginsDirty as f, PluginsInput as g, PluginCtx as h, FormValidator as i, VisibleWhenOp as j, InternalValueStore as k, encodeFieldValue as l, JsonischPlugin as m, internalOf as n, ValidationIssue as o, unwrapLeafInput as p, PathSegment as q, FormConfig as r, ValidationMode as s, FormRef as t, fieldPluginDirty as u, WireEnvelope as v, FieldKind as w, ContainerInput as x, FieldSlotKey as y, computed as z };