attaform 0.17.2 → 0.18.0

package/dist/shared/attaform.BmDBu4ql.d.ts

@@ -0,0 +1,1651 @@
+import { F as FormKey, af as SlimPrimitiveKind, C as CoercionEntry, j as CoercionRegistry, G as GenericForm, Y as PathKey, X as Path, V as ValidationError, a as AbstractSchema, d as ShouldShowErrors, ao as WriteMeta, m as DeepPartial, ap as WriteShape, aj as ValidateOn, aw as PersistOptInRegistry, S as Segment, A as AttaformDefaults, b as UseFormReturnType, R as RegisterValue } from './attaform.BsMdl-35.js';
+import { Ref, ComputedRef, App, InjectionKey } from 'vue';
+
+/**
+ * Public types for `useWizard` — the multistep-form orchestrator.
+ *
+ * The wizard is built around an ordered list of step slots. Each slot
+ * resolves to a participating form: an existing `useForm` reference, a
+ * bare string key (desugared to a noop form so affordance steps
+ * participate uniformly), an eagerly-evaluated function slot for
+ * runtime branching, or a `lazy()`-wrapped function slot that caches
+ * its resolution and re-fires only on its own tracked deps.
+ *
+ * The wizard surface is loosely keyed (`Record<FormKey, …>`).
+ * Cross-component flows threaded through `injectWizard` lose lexical
+ * key knowledge anyway, so the public read surface is a string-keyed
+ * record. Typed per-form access flows back through the original form
+ * refs and through `wizard.handleSubmit`'s `ctx.get(formRef)` accessor.
+ */
+
+/**
+ * Minimum structural shape the wizard requires from a participating
+ * form. Constraining to the full `UseFormReturnType` would force
+ * contravariant unification of the storage / read shapes across all
+ * steps; the wizard does not care about those — it routes by `key` at
+ * runtime and exposes the original form objects untouched.
+ */
+type AnyForm = {
+    readonly key: FormKey;
+};
+/**
+ * Per-form summary surface — what `wizard.statuses[key]` exposes (and
+ * what `defaultStatuses` seeds). Distinct from `form.meta`: `FormStatus`
+ * is the cross-step rollup optimized for template ergonomics
+ * (`{{ wizard.statuses.cargo.valid }}`), while `form.meta` carries the
+ * full per-form lifecycle surface.
+ *
+ * Field semantics:
+ *  - `valid` — `form.meta.valid`. `false` while errors exist or while
+ *    the first-validation-done gate has not flipped.
+ *  - `dirty` — `form.meta.dirty`. `true` once any value differs from
+ *    the original defaults.
+ *  - `submitted` — `form.meta.submitted`. `true` once a `handleSubmit`
+ *    callback has resolved without throwing. A failed submit
+ *    (validation or callback rejection) leaves this `false`;
+ *    `submissionAttempts > 0` is the "user has tried" signal.
+ *  - `errorCount` — `form.meta.errorCount`. Count of active validation
+ *    errors (zero when valid).
+ *
+ * Noop forms generated for string slots surface as default-valid
+ * (`{ valid: true, dirty: false, submitted: false, errorCount: 0 }`).
+ */
+type FormStatus = {
+    readonly valid: boolean;
+    readonly dirty: boolean;
+    readonly submitted: boolean;
+    readonly errorCount: number;
+};
+/**
+ * Flat error shape returned per form by `wizard.allErrors[key]`. Each
+ * entry carries the formKey + path tuple so consumers can route to the
+ * offending field from a wizard-wide error summary.
+ */
+type AggregateError = {
+    readonly formKey: FormKey;
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+    readonly code?: string;
+};
+/**
+ * Mirror of `form.values`' call-or-read pattern, one level deep.
+ * Drillable as `wizard.statuses.cargo.valid` (readable), as
+ * `wizard.statuses('cargo')` (callable single-key), or as
+ * `wizard.statuses()` (callable no-arg returns the whole record).
+ */
+type WizardStatusesProxy<S extends Record<string, FormStatus>> = ((key?: keyof S) => FormStatus | S) & Readonly<S>;
+/**
+ * One compiled position in the wizard's flow. The wizard surface
+ * exposes an ordered array of these as `wizard.steps`, plus a
+ * `wizard.forms` record keyed by `step.key` for direct lookup.
+ *
+ * String slots in the source `steps` array desugar to noop forms
+ * before compilation, so every compiled step carries a `form`
+ * regardless of source kind.
+ */
+type CompiledStep = {
+    readonly key: FormKey;
+    readonly form: AnyForm;
+};
+/**
+ * Shape of a participating form as seen from inside a function slot's
+ * `ctx.forms[key]` lookup. Adds `values` to the structural `AnyForm`
+ * minimum so routing decisions can read live form state.
+ *
+ * Values are typed loose because the wizard does not generically thread
+ * each step's schema through `ctx.forms`. For typed access inside slot
+ * bodies, close over the original form ref instead of routing through
+ * `ctx.forms`.
+ */
+type WizardCtxForm = AnyForm & {
+    readonly values: Readonly<Record<string, unknown>>;
+};
+/**
+ * Context object passed to function slots in the `steps` array. The
+ * `forms` record exposes the wizard's statically-known forms (every
+ * top-level `AnyForm` slot plus every noop form synthesized for a
+ * top-level string slot). `currentKey` mirrors the live wizard step.
+ *
+ * Function slots re-evaluate reactively when the values they read
+ * mutate (typically `ctx.forms.<key>.values.<path>`). The `forms`
+ * accumulator itself is stable across re-evaluations so the slot's
+ * lookup identity stays referentially equal. Effectful slot bodies
+ * should be avoided; routing decisions live here.
+ */
+type WizardCtx = {
+    readonly forms: Readonly<Record<FormKey, WizardCtxForm>>;
+    readonly currentKey: FormKey | undefined;
+};
+/**
+ * Internal phantom brand for `LazyMarker`. The runtime brand symbol
+ * lives in `core/wizard-lazy.ts`; this declaration keeps the marker
+ * type unforgeable without circular module imports.
+ */
+declare const _lazyBrand: unique symbol;
+/**
+ * Brand-typed marker returned by `lazy((ctx) => …)`. Wrapping a
+ * function slot in `lazy()` gives that slot its own memoization cache:
+ * the resolver fires once on the first compile pass, and the result
+ * stays cached until one of the resolver's own tracked reactive reads
+ * changes (or `wizard.reset()` invalidates the cache). Heavy or
+ * one-shot lookups (network-backed factories, expensive derivations)
+ * do not re-fire because an unrelated slot's deps changed.
+ *
+ * Construct via the `lazy()` helper exported from the same entry as
+ * `useWizard`. The marker is opaque at the type level; consumers do
+ * not assemble it directly.
+ */
+type LazyMarker<Ctx = WizardCtx> = {
+    readonly [_lazyBrand]: true;
+    readonly resolve: (ctx: Ctx) => AnyForm | string | undefined;
+};
+/**
+ * One position in the source `useWizard({ steps })` array. Each slot
+ * resolves to a compiled `{ key, form }` step:
+ *
+ *  - `AnyForm`         — a form declared via `useForm`. Surfaced as-is.
+ *  - `string`          — bare key. The wizard generates a noop form
+ *                        under the hood so the external surface stays
+ *                        uniform across affordance positions (intro,
+ *                        terms, congratulations, review surfaces).
+ *  - function          — eager slot, re-evaluates reactively. Returns
+ *                        one of the above, or `undefined` to drop the
+ *                        slot from the compiled list.
+ *  - `LazyMarker`      — memoized function slot (see `lazy`).
+ */
+type StepSlot<Ctx = WizardCtx> = AnyForm | string | ((ctx: Ctx) => AnyForm | string | undefined) | LazyMarker<Ctx>;
+/**
+ * Shape returned by the `restore` callback. Carries the active step's
+ * key; intentionally open-ended (object form) so future additions land
+ * without a callback-signature break.
+ */
+type WizardRestoreState = {
+    readonly step?: FormKey;
+};
+/**
+ * `restore` callback signature. Invoked at construction and watched
+ * reactively via `watchEffect` so external state changes (browser
+ * back/forward, cross-tab events, route changes) re-apply through the
+ * wizard. Returning `undefined` falls through to the first step.
+ */
+type WizardRestoreFn = () => WizardRestoreState | undefined;
+/**
+ * `persist` callback signature. Invoked whenever `wizard.currentStep`
+ * changes; the wizard diffs against the last persisted value to break
+ * the restore-persist loop, so the callback only fires when the active
+ * step actually moves.
+ */
+type WizardPersistFn = (state: WizardRestoreState) => void;
+/**
+ * Submit context passed to the `onSubmit` callback registered via
+ * `wizard.handleSubmit(onSubmit, onError?)`. Same shape on every step;
+ * `isFinal` distinguishes intermediate vs final calls.
+ *
+ *  - `values` — namespaced aggregate keyed by form key, mirroring
+ *               `wizard.allValues`. Reflects parsed output for every
+ *               form whose validation has settled; noops contribute an
+ *               empty record.
+ *  - `get(form)` — typed accessor that reads the parsed output for a
+ *               specific form ref. Works across cross-component graphs
+ *               because the form ref carries its schema info.
+ *  - `currentKey` — key of the step that fired this submission.
+ *  - `isFinal`   — `true` when `currentKey` is the last position in
+ *               `wizard.steps`. Intermediate calls validate the active
+ *               form only and advance; final calls validate every form
+ *               and stay on the terminal step.
+ */
+type WizardSubmitContext = {
+    readonly values: Readonly<Record<FormKey, unknown>>;
+    readonly get: <F extends AnyForm>(form: F) => F extends {
+        readonly values: infer V;
+    } ? V : unknown;
+    readonly currentKey: FormKey;
+    readonly isFinal: boolean;
+};
+/**
+ * `onSubmit` callback registered via `wizard.handleSubmit`. Sync or
+ * async; the returned promise gates `wizard.submitting`.
+ */
+type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
+/**
+ * Optional `onError` callback registered via `wizard.handleSubmit`.
+ * Receives the aggregate error list — entries originate from per-form
+ * validation and activation failures (`atta:activation-failed`). Sync
+ * or async; the returned promise gates `wizard.submitting`.
+ */
+type WizardOnError = (errors: readonly AggregateError[]) => void | Promise<void>;
+/**
+ * Options for `useWizard({ steps, … })`. `steps` is the only required
+ * field; the rest are optional and default sensibly for the common
+ * URL-synchronized wizard case.
+ */
+type WizardOptions = {
+    /**
+     * Ordered list of slots that compile into the wizard's positional
+     * step list. See `StepSlot` for the per-slot shape contract.
+     */
+    readonly steps: ReadonlyArray<StepSlot>;
+    /**
+     * Identifier used to register the wizard handle in the per-app
+     * registry. Descendant components call `injectWizard(key)` to reach
+     * the same wizard without prop-threading. Anonymous wizards (option
+     * omitted) get a synthetic `__atta:anon-wizard:<id>` key resolved
+     * via `useId()` so SSR-rendered and client-hydrated trees agree on
+     * the same registry entry; the synthetic key is opaque and
+     * descendants reach an anonymous wizard via ambient `injectWizard()`
+     * rather than by key.
+     *
+     * Duplicate-key registration is first-wins-silently (dev-warn on the
+     * second registration) to mirror `useForm`'s shared-key behavior.
+     * The dev-warn fires only for explicit keys — two anonymous wizards
+     * are guaranteed distinct synthetic keys, so the warning never
+     * misfires on independent anonymous wizards on the same page.
+     */
+    readonly key?: string;
+    /**
+     * Seed status payload used while a form is pre-resolved (async
+     * `defaultValues` in flight, or wizard-deferred non-current).
+     * Mirrors `defaultValues`' trichotomy: plain object, sync factory,
+     * or async factory.
+     *
+     * Status resolution priority per form:
+     *   1. `store.defaultsResolved === true` → derive from `form.meta`
+     *   2. else noop form → built-in always-valid status
+     *   3. else seed value for this key → frozen seed
+     *   4. else → pending sentinel
+     *
+     * Unknown keys in the seed object dev-warn so a stale resume payload
+     * surfaces at construction.
+     */
+    readonly defaultStatuses?: Record<string, FormStatus> | (() => Record<string, FormStatus>) | (() => Promise<Record<string, FormStatus>>);
+    /**
+     * Optional progress override. When omitted, the wizard exposes
+     * `progress` as `valid_step_count / count` (normalised to `[0, 1]`).
+     * When provided, the returned number is used as-is — the consumer is
+     * responsible for any normalisation.
+     *
+     * The override is invoked inside a Vue `computed` so it must be
+     * synchronous and may only read reactive sources.
+     */
+    readonly progress?: (steps: ReadonlyArray<CompiledStep>) => number;
+    /**
+     * When `wizard.handleSubmit` finds errors, automatically focus the
+     * first failing form: jump to its step and invoke its
+     * `applyInvalidSubmitPolicy()` (focus / scroll per the form's own
+     * `onInvalidSubmit` configuration). Default `true`; pass `false` to
+     * keep the active step where the user left it and handle navigation
+     * manually in the `onError` callback.
+     */
+    readonly focusFirstError?: boolean;
+    /**
+     * Source of truth for the active step. Invoked at construction and
+     * re-evaluated reactively via `watchEffect`. Default callback reads
+     * `?step=<key>` from the URL via `wizard-history.ts`; pass `false`
+     * to disable URL sync, or provide a custom callback for non-router
+     * persistence (localStorage, broadcast channel, etc.).
+     */
+    readonly restore?: WizardRestoreFn | false;
+    /**
+     * Destination for the active step. Invoked whenever `currentStep`
+     * changes, with a diff check to break the restore-persist loop.
+     * Default callback writes `?step=<key>` via `wizard-history.ts`;
+     * pass `false` to disable persistence, or provide a custom callback
+     * to scope the param name or write to alternate storage.
+     */
+    readonly persist?: WizardPersistFn | false;
+};
+/**
+ * Predicate: is the steps tuple statically guaranteed to compile to a
+ * non-empty list? A tuple passes when (a) it's not the empty array
+ * literal and (b) it carries no function or `lazy()` slot — those
+ * slot kinds can resolve to `undefined` at runtime and drop the
+ * compiled position. Form slots and bare-string affordance slots
+ * always preserve their position; a tuple made of only those kinds is
+ * statically safe.
+ *
+ * Used to narrow `currentStep` / `activeForm` to their non-`undefined`
+ * shapes in the common-case wizard, while keeping the honest union
+ * everywhere a runtime drop is reachable.
+ */
+type StaticallyNonEmpty<S> = S extends readonly [] ? false : S extends readonly (infer Item)[] ? Item extends LazyMarker | ((...args: unknown[]) => unknown) ? false : true : false;
+/** Active step's key, narrowed to `string` when `S` is statically safe. */
+type CurrentStepOf<S> = StaticallyNonEmpty<S> extends true ? FormKey : FormKey | undefined;
+/** Active step's form handle, narrowed to `AnyForm` when `S` is statically safe. */
+type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? AnyForm : AnyForm | undefined;
+/**
+ * Recursive tuple walk that builds the static portion of
+ * `wizard.forms`. Each step slot contributes to the record:
+ *
+ *  - **String slot** (`'review'`): the literal becomes the record key
+ *    and the value is `AnyForm` (the noop form synthesized for the
+ *    affordance position is opaque at the type level).
+ *  - **Form slot** (a `useForm` reference with a literal `key` field):
+ *    the form's own `key` becomes the record key, and the value is
+ *    the concrete form handle type — so drilling
+ *    `wizard.forms.shipping.values.address` carries the schema-derived
+ *    field types through.
+ *  - **Function / `lazy()` slot**: contributes nothing to the static
+ *    map. Runtime-resolved forms are still reachable via the
+ *    catch-all index signature on `WizardForms` (typed as `AnyForm`).
+ *
+ * Recursion is bounded by the tuple length; real-world wizards land
+ * well below the TS instantiation budget.
+ */
+type FormsRecordOf<S> = S extends readonly [
+    infer First,
+    ...infer Rest extends ReadonlyArray<StepSlot>
+] ? (First extends string ? {
+    readonly [P in First]: AnyForm;
+} : First extends {
+    readonly key: infer K extends string;
+} ? {
+    readonly [P in K]: First;
+} : unknown) & FormsRecordOf<Rest> : unknown;
+/**
+ * `wizard.forms` typed view. Combines the static per-step type map
+ * with a catch-all `Record<FormKey, AnyForm>` fallback so:
+ *
+ *   - Statically known slot keys → concrete form type via `FormsRecordOf`
+ *   - Any other string key → `AnyForm` via the index signature
+ *
+ * The intersection collapses to the concrete form for statically
+ * known keys (because the concrete form type extends `AnyForm`) and
+ * to `AnyForm` for unknown keys.
+ */
+type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
+/**
+ * Return shape of `useWizard({ steps, … })`. Every reactive read is a
+ * plain getter (no `.value`) — `wizard.currentStep`, `wizard.progress`,
+ * `wizard.allValues` track inside `computed` / template effects
+ * directly.
+ *
+ * Parameterized by the steps tuple `S` so active-position fields
+ * (`currentStep`, `activeForm`) narrow to non-undefined for the common
+ * case (all positional Form / string slots) and stay as honest unions
+ * when a function or `lazy()` slot can drop the compiled position at
+ * runtime. The `const` type parameter on `useWizard` preserves literal
+ * tuple types without consumer-side `as const`, so the narrowing
+ * happens automatically from the call site.
+ *
+ *  - `currentStep` — key of the active step. Narrows to `string` when
+ *                    the steps tuple is statically guaranteed to
+ *                    compile to a non-empty list (all positional
+ *                    Form / string slots, no function or `lazy()`
+ *                    slots). Otherwise reads as `string | undefined`
+ *                    so the degenerate case (empty list at runtime)
+ *                    surfaces honestly.
+ *  - `activeForm`  — the active step's form handle. Same narrowing as
+ *                    `currentStep`. Noop forms cover string slots in
+ *                    the normal path.
+ *  - `activeIndex` — 0-based position of the active step.
+ *  - `isFinalStep` — `true` when `currentStep === steps[count - 1].key`.
+ *  - `steps`       — ordered list of compiled `{ key, form }` slots.
+ *  - `forms`       — record indexable by step key; the value is the
+ *                    full form handle resolved for that slot.
+ *  - `count`       — `steps.length`.
+ *  - `statuses`    — callable readonly proxy over the per-key
+ *                    `FormStatus` record. Noop-form keys always read
+ *                    as default-valid.
+ *  - `allValues`   — namespaced aggregate of each form's values, keyed
+ *                    by step key.
+ *  - `allErrors`   — namespaced aggregate of each form's validation
+ *                    errors, keyed by step key. Noop forms map to an
+ *                    empty list.
+ *  - `progress`    — normalised step-validity ratio (or the consumer's
+ *                    `progress` override). Forward-looking: noops count
+ *                    as always-valid.
+ *  - `canAdvance`  — `true` when `activeIndex < count - 1`. Pure
+ *                    positional check; navigation never gates on
+ *                    validity.
+ *  - `canGoBack`   — `true` when `activeIndex > 0`.
+ *  - `complete`    — `isFinalStep && every step's form is valid`.
+ *                    Forward-looking; reactive to current form
+ *                    validity. Gates "Finish button enable" style UI.
+ *  - `done`        — monotonic latch: flips `true` the first time a
+ *                    final-step `handleSubmit` resolves without
+ *                    throwing, and stays `true` through subsequent
+ *                    edits or invalidations. Only `reset()` flips it
+ *                    back. Gates "show success card" style UI that
+ *                    should reflect submission history rather than
+ *                    current validity.
+ *  - `submitting`  — `true` while a `wizard.handleSubmit` call is in
+ *                    flight. Global re-entrance guard: every
+ *                    navigation method also refuses while this is on.
+ *  - `submissionAttempts` — count of `wizard.handleSubmit` invocations
+ *                    (success or failure). Always bumps, including on
+ *                    noop-form steps.
+ *  - `visited`     — append-only breadcrumb of navigated step keys.
+ *                    `back()` does not pop; the trail is the audit
+ *                    log, not the back-stack.
+ *  - `next/back/goTo` — pure navigation. Refuses while `submitting`.
+ *  - `handleSubmit(onSubmit, onError?)` — universal across all steps.
+ *                    Intermediate calls validate the active form and
+ *                    advance; final calls validate every form. Returns
+ *                    an event handler suitable for `<form @submit>` or
+ *                    imperative use.
+ *  - `reset()`     — zeros wizard lifecycle (`submissionAttempts`,
+ *                    `visited`), resets every form, returns
+ *                    `currentStep` to `steps[0].key`, and invokes
+ *                    `persist` with the cleared state.
+ */
+type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepSlot>> = {
+    readonly key: string;
+    readonly currentStep: CurrentStepOf<S>;
+    readonly activeForm: ActiveFormOf<S>;
+    readonly activeIndex: number;
+    readonly isFinalStep: boolean;
+    readonly steps: ReadonlyArray<CompiledStep>;
+    readonly forms: WizardForms<S>;
+    readonly count: number;
+    readonly statuses: WizardStatusesProxy<Record<string, FormStatus>>;
+    readonly allValues: Readonly<Record<FormKey, unknown>>;
+    readonly allErrors: Readonly<Record<FormKey, readonly AggregateError[]>>;
+    readonly progress: number;
+    readonly canAdvance: boolean;
+    readonly canGoBack: boolean;
+    readonly complete: boolean;
+    readonly done: boolean;
+    readonly submitting: boolean;
+    readonly submissionAttempts: number;
+    readonly visited: readonly FormKey[];
+    readonly next: () => Promise<void>;
+    readonly back: () => void;
+    readonly goTo: (key: string) => void;
+    readonly handleSubmit: (onSubmit: WizardOnSubmit, onError?: WizardOnError) => (event?: Event) => Promise<void>;
+    readonly reset: () => void;
+};
+
+/**
+ * Schema-driven coercion of user-typed DOM values at the v-register
+ * directive layer. When the slim schema declares a numeric or
+ * boolean type at a path, the directive coerces incoming string
+ * values (`'25'` → `25`, `'true'` → `true`) before the slim-primitive
+ * gate sees the write — making the schema authoritative for storage
+ * shape and freeing consumers from sprinkling `.number` modifiers
+ * across templates.
+ *
+ * Coercion is consumer-extensible: a `CoercionRegistry` is just an
+ * `Array<CoercionEntry>` keyed at config time by `(input, output)`
+ * `SlimPrimitiveKind` literals. The library ships
+ * `defaultCoercionRules` (string→number, string→boolean) and
+ * `defineCoercion` for type-narrowed authoring; consumers spread the
+ * defaults to extend or supply their own array to replace.
+ *
+ * Coercion applies ONLY to user-typed DOM values flowing through
+ * the directive's assigner. Programmatic writes (`form.setValue`,
+ * `setValueWithInternalPath`) bypass coercion — they're authoritative
+ * writes whose strict typing is on the caller. This mirrors the
+ * `transforms` pipeline's user-input-only contract.
+ */
+
+/**
+ * Type-narrowing helper for authoring entries. At runtime it's
+ * identity; at compile time it preserves the `input` / `output`
+ * literal types so `transform`'s parameter is narrowed to the
+ * runtime type instead of widening to `SlimRuntimeOf<SlimPrimitiveKind>`.
+ *
+ * Without this helper, authoring `{ input: 'string', output:
+ * 'number', transform: (s) => ... }` against the broader
+ * `CoercionEntry` widens `s` to `string | number | boolean | ...`,
+ * forcing a cast in every transform body. `defineCoercion` is the
+ * opaque-free idiom.
+ */
+declare function defineCoercion<I extends SlimPrimitiveKind, O extends SlimPrimitiveKind>(entry: CoercionEntry<I, O>): CoercionEntry<I, O>;
+/**
+ * Internal index built from a `CoercionRegistry` at config-resolve
+ * time. Keyed by `${input}->${output}` for O(1) per-keystroke
+ * dispatch. The authoring shape (array, ergonomic, type-narrowing-
+ * friendly) and the dispatch shape (Map, fast) decouple cleanly.
+ */
+type CoercionIndex = ReadonlyMap<`${SlimPrimitiveKind}->${SlimPrimitiveKind}`, CoercionEntry>;
+/**
+ * The library's built-in registry. Two cells: string→number and
+ * string→boolean. Re-exported so consumers can spread it when
+ * supplying a custom registry that extends defaults.
+ */
+declare const defaultCoercionRules: CoercionRegistry;
+
+/**
+ * Per-form closure state — the single store owned by each `useForm` call.
+ * Bundles the form value, the summary record, element references, field
+ * state, the meta tracker, and the error stores under one keyed-by-
+ * `(formKey, path)` instance so cross-form DOM state cannot collide.
+ *
+ * This is NOT a singleton. Each call to `useForm` creates its own FormStore
+ * instance and holds onto it via closure. The registry provides SSR
+ * hydration; otherwise the state is per-component-per-form.
+ */
+/**
+ * Per-path field status. Replaced wholesale (not mutated in place) on
+ * every change. Three semantic groups:
+ *
+ *   - `connected` — is a DOM element registered for this path?
+ *   - `focused` / `blurred` — DOM-state flags. `null` while no element
+ *     is connected (no DOM means the concepts don't apply); plain
+ *     booleans once connected, with the invariant `blurred === !focused`
+ *     enforced by `markFocused`.
+ *   - `touched` — interaction history, not DOM state. Always a plain
+ *     boolean: `false` at registration, sticky `true` after first blur,
+ *     cleared only by `form.reset()` / `form.resetField(path)`. Persists
+ *     across disconnects so v-if'd-away fields don't lose their touched
+ *     state on rehide (wizard "show review of touched fields" patterns
+ *     rely on this).
+ */
+type FieldRecord = {
+    readonly path: Path;
+    readonly updatedAt: string | null;
+    readonly connected: boolean;
+    readonly focused: boolean | null;
+    readonly blurred: boolean | null;
+    readonly touched: boolean;
+};
+/** Per-path DOM element tracking. Client-only. */
+type ElementRecord = {
+    /**
+     * Original Path captured at first registration. Stored alongside the
+     * elements Set so the DOM-order sort cache can recover the structured
+     * Path without round-tripping through `JSON.parse(pathKey)`.
+     */
+    readonly path: Path;
+    readonly elements: Set<HTMLElement>;
+};
+/**
+ * Per-path record stored in `originals`. Pairing `segments` with the tracked
+ * value means `dirty` and `resetField`'s container loop don't have to
+ * `JSON.parse(pathKey)` on every iteration — the canonical Path is already
+ * sitting next to the value it belongs to. PathKey still keys the Map (the
+ * stable string is the only collision-free identifier), but downstream
+ * iteration reads `segments` directly.
+ */
+type OriginalsRecord = {
+    readonly segments: Path;
+    readonly value: unknown;
+};
+type FormStore<F extends GenericForm, G extends GenericForm = F> = {
+    readonly formKey: FormKey;
+    readonly form: Ref<F>;
+    readonly fields: Map<PathKey, FieldRecord>;
+    readonly elements: Map<PathKey, ElementRecord>;
+    /**
+     * Schema-driven errors. Written ONLY by the schema validation pipeline:
+     * `scheduleFieldValidation`, `handleSubmit`, the construction-time seed,
+     * history restore, and hydration. Cleared by `reset` / `resetField` and by
+     * a successful submit. `setFieldErrors*` APIs do NOT touch this Map.
+     */
+    readonly schemaErrors: Map<PathKey, ValidationError[]>;
+    /**
+     * User-injected errors. Written ONLY by the `setFieldErrors*` API surfaces
+     * (and history / hydration replay). Survives schema revalidation and
+     * successful submits — the consumer owns its lifetime explicitly.
+     */
+    readonly userErrors: Map<PathKey, ValidationError[]>;
+    /**
+     * Reactively-derived "No value supplied" errors. Pure function of
+     * `(blankPaths, schema.isRequiredAtPath)` — no writers, no clears.
+     * Membership tracks `blankPaths` automatically: typing a value into
+     * a blank required numeric field removes the path from `blankPaths`
+     * and the derived error vanishes; clearing the numeric input re-adds
+     * the path and the error reappears. The `errors` proxy and
+     * `getErrorsForPath` merge this map in alongside `schemaErrors` and
+     * `userErrors`, so consumers see the "this required field is empty"
+     * error the moment it's true — no `validate()` / `handleSubmit`
+     * call required. Honors the founding principle that
+     * `errors = f(schema, state)`.
+     *
+     * Most entries flow through this map for `number` / `bigint` leaves
+     * (where the side-channel is needed to distinguish "user typed 0"
+     * from "user supplied nothing"). String / boolean leaves only land
+     * here when the consumer explicitly opted in via the `unset`
+     * sentinel — see `docs/recipes/blank-inputs.md`.
+     */
+    readonly derivedBlankErrors: ComputedRef<ReadonlyMap<PathKey, ValidationError[]>>;
+    readonly originals: Map<PathKey, OriginalsRecord>;
+    /**
+     * Reactive set of paths whose displayed state should be EMPTY even
+     * though storage holds a real, schema-conformant value (the slim
+     * default). It exists exclusively to record **storage / display
+     * divergence** — the case where the runtime can't tell "user typed
+     * 0" from "user supplied nothing" by looking at storage alone.
+     *
+     * The mechanism shines for `number` / `bigint`: storage holds the
+     * slim default (`0` / `0n`) but the DOM input shows `''`, so the
+     * directive's input listener marks the path here on clear. Strings
+     * and booleans don't need it — `''` storage equals `''` display,
+     * `false` storage equals unchecked display — so they're never
+     * auto-marked. Consumers can still mark any primitive leaf
+     * explicitly via the `unset` sentinel (`defaultValues: { x: unset }`,
+     * `setValue('x', unset)`, `reset({ x: unset })`); the mark is then
+     * a documented signal of consumer intent rather than runtime
+     * inference.
+     *
+     * Reads (`displayValue` computed, `fields.<path>.blank`,
+     * `derivedBlankErrors` computed) track via Vue 3.5's reactive Set
+     * handlers. Writes happen inside `setValueAtPath` (gate-hook
+     * bookkeeping: `blank: true` meta adds the path; any other write
+     * removes it) and `reset`.
+     *
+     * Storage NEVER reflects this set — calculations and reads against
+     * `form.value` see the slim default. The set is purely a UI/intent
+     * channel that `derivedBlankErrors` consults to surface
+     * "No value supplied" errors for required schemas.
+     *
+     * See `docs/recipes/blank-inputs.md` for the conceptual model.
+     */
+    readonly blankPaths: Set<PathKey>;
+    /**
+     * Snapshot of `blankPaths` captured at construction (and
+     * re-captured on `reset(args)`). Used by dirty calculation: a path
+     * whose membership differs from the snapshot is dirty even if
+     * storage matches the original. Eagerly populated to avoid a "dirty
+     * on first read" race after construction.
+     */
+    readonly originalBlankPaths: Set<PathKey>;
+    readonly schema: AbstractSchema<F, G>;
+    /**
+     * Server-side flag, plumbed in from `registry.ssr`. The
+     * `register()`-returned `markConnectedOptimistically()` reads this
+     * before flipping `connected: true`; on the client it's a no-op so
+     * the eventual directive lifecycle remains the source of truth.
+     */
+    readonly ssr: boolean;
+    /**
+     * Resolved `shouldShowErrors` predicate driving `field.showErrors`
+     * and `form.meta.showErrors`. Resolved once at construction via
+     * `resolveShouldShowErrors(options.shouldShowErrors)` so the
+     * field-state computeds don't repeat the boolean-vs-function
+     * branch on every read. Boolean shorthand has already been lifted
+     * to a constant predicate by the time it lands here; `undefined`
+     * config falls through to `defaultShouldShowErrors`.
+     */
+    readonly shouldShowErrors: ShouldShowErrors;
+    readonly submitting: Ref<boolean>;
+    readonly activeSubmissions: Ref<number>;
+    readonly submissionAttempts: Ref<number>;
+    /**
+     * `true` once a `handleSubmit` callback resolved without throwing.
+     * Independent of `submissionAttempts` — a failed submit increments
+     * attempts but leaves `submitted` at `false`. Cleared by `reset()`
+     * alongside the rest of the submission surface.
+     */
+    readonly submitted: Ref<boolean>;
+    readonly submitError: Ref<unknown>;
+    readonly departAttempts: Ref<number>;
+    /**
+     * `true` while a function-form `defaultValues` factory is in flight.
+     * Stays `false` for plain-value `defaultValues`. Shared across every
+     * `useForm({ key })` call that resolves to this store — the second
+     * caller sees the first caller's hydration state.
+     */
+    readonly hydrating: Ref<boolean>;
+    /**
+     * Error from the most recent function-form `defaultValues` factory.
+     * Normalized to a `ValidationError` (code `atta:hydration-failed`) so the
+     * shape matches `form.errors` / `form.meta.errors` entries. `null` when
+     * no factory has fired or the last one succeeded.
+     */
+    readonly hydrateError: Ref<ValidationError | null>;
+    /**
+     * The function-form `defaultValues` factory, captured at the first
+     * `useForm({ key })` call that wired this store. `undefined` for
+     * plain-value forms. Read by `form.rehydrate()`.
+     */
+    readonly defaultValuesFactory: Ref<(() => unknown | Promise<unknown>) | undefined>;
+    /**
+     * `true` once the form's effective defaults have been applied —
+     * sync `defaultValues` at construction, or async factory whose
+     * settle completed. Stays `false` for dormant lazy forms until they
+     * activate. Read by `useWizard` to decide whether seed status or
+     * live meta should surface.
+     */
+    readonly defaultsResolved: Ref<boolean>;
+    /**
+     * `true` once the captured async factory has been kicked off (set
+     * synchronously by `activate()`, before the factory itself resolves).
+     * Distinct from `defaultsResolved`, which only flips after the factory
+     * settles. The pair lets the API surface tell "we've started" apart
+     * from "we're done."
+     */
+    readonly activated: Ref<boolean>;
+    /**
+     * In-flight activation promise. Concurrent callers (cross-component
+     * SSR consumers, recursive factory reads, parallel `activate()`
+     * calls) receive the same promise, ensuring the factory runs once
+     * even under contention.
+     */
+    readonly activationPromise: Ref<Promise<void> | undefined>;
+    /**
+     * Idempotent activation entrypoint. Fires the captured function-form
+     * `defaultValues` factory on first call and stores the in-flight
+     * promise. Subsequent calls return the same promise until the factory
+     * settles; thereafter calls return `Promise.resolve()`. Plain-value
+     * forms (no factory captured) always return a resolved promise. The
+     * public API surface routes all reactive interactions (getters and
+     * methods, except `key`) through this entrypoint so the form
+     * activates on first use.
+     */
+    activate(): Promise<void>;
+    /**
+     * Re-fire the captured function-form `defaultValues` factory. Throws
+     * synchronously when no factory was captured (plain-value form).
+     * Resolves after `hydrating` flips back to `false`; consumers can
+     * `await form.rehydrate()` to gate UI on the fresh load.
+     *
+     * Does NOT touch dirty / touched / submit state — chain
+     * `form.reset()` if you want a clean baseline.
+     */
+    rehydrate(): Promise<void>;
+    /**
+     * Incremented by every `reset()` call. The submit wrapper captures
+     * this at entry and skips writing `submitError` from a catch that
+     * fires *after* a reset — otherwise a reset-during-submit would
+     * visibly clear `submitError` and then have it reappear when the
+     * in-flight promise rejects.
+     */
+    readonly submissionGeneration: Ref<number>;
+    /**
+     * Counts in-flight validation calls across every `validate()` ref and
+     * every `validateAsync(...)` / `handleSubmit` pre-check. `validating`
+     * on the public API mirrors `activeValidations.value > 0`. Tracked
+     * separately from submissions because a validate-while-submitting
+     * (e.g. a debounced field check overlapping a submit) needs to show
+     * the union of both surfaces.
+     */
+    readonly activeValidations: Ref<number>;
+    /**
+     * `true` once the form has completed at least one validation pass
+     * — flips when `activeValidations` returns to 0 from any positive
+     * value. Until that happens, `meta.valid` and `field.valid` report
+     * `false` even when `schemaErrors.size === 0`, because the absence
+     * of errors at frame 1 is just "we haven't checked yet," not "we
+     * checked and it's clean."
+     *
+     * This closes the brief flash window for schemas where the slim
+     * default-derivation parse strips refinements (`.refine`,
+     * `.superRefine`, async validators): the slim parse passes, no
+     * construction-time errors land, and the queued microtask hasn't
+     * run yet — so without the gate, frame 1 paints the form as
+     * "valid" before the real verdict arrives a tick later.
+     *
+     * Initialized to `!strict`: non-strict consumers opt out of the
+     * validation pipeline by design, so locking them on
+     * `firstValidationDone === false` would defeat the opt-out.
+     * Reset is left untouched — the post-reset validation flips it
+     * back true on completion, same as the construction-time path.
+     */
+    readonly firstValidationDone: Ref<boolean>;
+    /**
+     * `true` when the sub-schema rooted at `path` (or any of its
+     * descendants) declares async work — composes
+     * `schema.getSchemasAtPath(path)` with each candidate's
+     * `needsAsyncValidation()`, memoised per canonical path key for
+     * the lifetime of the FormStore. Used by `meta.valid` /
+     * `field.valid` to skip the `firstValidationDone` gate on subtrees
+     * that are fully synchronous: their verdict resolves at construction
+     * (or on the next per-field run) without waiting on a microtask, so
+     * honouring the form-wide gate would just play dumb about a known
+     * answer.
+     */
+    pathHasAsyncValidation(path: Path): boolean;
+    /**
+     * Per-path counter of in-flight field-level validation runs.
+     * `field.validating` on `FieldState` mirrors
+     * `(fieldValidationCounts.get(key) ?? 0) > 0`.
+     *
+     * Incremented at the same point as `activeValidations` inside
+     * `scheduleFieldValidation`'s `run` closure (right before the schema
+     * call) and decremented in the matching `.finally` — so the per-path
+     * bookkeeping is exactly co-extensive with the form-wide counter for
+     * the field-scheduled branch. Whole-form `validate()` /
+     * `validateAsync()` runs touch `activeValidations` only; they don't
+     * have a single field path and so don't contribute here.
+     *
+     * Counter (not Set) because two runs for the same path can briefly
+     * overlap: when an in-flight run is aborted and a new run starts,
+     * the new run increments before the aborted run's `.finally`
+     * decrements. With `> 0` semantics the field stays "validating"
+     * across the abort/restart boundary.
+     *
+     * Reactive Map: Vue 3's `reactive(new Map())` proxy makes `.get()`,
+     * `.has()`, and `.size` track per-key, so the FieldState
+     * computed only re-runs when the count for ITS key changes.
+     */
+    readonly fieldValidationCounts: Map<PathKey, number>;
+    /**
+     * Replace the form value wholesale. Optional `meta` is forwarded to
+     * every `onFormChange` listener so they can decide whether THIS write
+     * is one they care about — most importantly, the persistence layer
+     * only writes when `meta?.persist === true`. Internal callers that
+     * don't pass meta default to no-persist.
+     */
+    applyFormReplacement(next: F, meta?: WriteMeta): void;
+    /**
+     * Set a single path's value. `meta` is forwarded to listeners via
+     * `applyFormReplacement` (see above). The directive's input handler
+     * computes `meta.persist` from the per-element opt-in registry; other
+     * internal call sites pass `meta.persist = hasAnyOptInForPath(path)`.
+     * Public `form.setValue` passes no meta.
+     *
+     * Returns `false` when the slim-primitive gate rejects the write
+     * (the value's primitive shape doesn't match the schema's slim
+     * shape at the path). The store is unchanged in that case.
+     */
+    setValueAtPath(path: Path, value: unknown, meta?: WriteMeta): boolean;
+    getValueAtPath(path: Path): unknown;
+    reset(nextDefaultValues?: DeepPartial<WriteShape<F>>): void;
+    resetField(path: Path): void;
+    /**
+     * Wipe `path` (or the whole form when `path === ''`) to the
+     * schema's "appropriate nullish value" — the underlying type's
+     * empty/falsy concrete, with `.default()` / `.catch()` wrappers
+     * INTENTIONALLY skipped. Sugar for
+     * `setValueAtPath(path, schema.getEmptyValueAtPath(path))`.
+     */
+    clear(path: Path): boolean;
+    setSchemaErrorsForPath(path: Path, errors: ValidationError[]): void;
+    setAllSchemaErrors(errors: readonly ValidationError[]): void;
+    clearSchemaErrors(path?: Path): void;
+    /**
+     * Replace `schemaErrors` under `path` with `errors`, keying each
+     * error by its OWN absolute path. Used by validation pipelines
+     * (scheduleFieldValidation, validateAsync, handleSubmit, reset)
+     * to commit a parse result wholesale — entries not in the new
+     * pass get dropped from the subtree, surviving keys update in
+     * place to preserve insertion order. Pass `path === []` for the
+     * whole-form scope.
+     */
+    applySchemaErrorsForSubtree(path: Path, errors: ValidationError[]): void;
+    setAllUserErrors(errors: readonly ValidationError[]): void;
+    addUserErrors(errors: readonly ValidationError[]): void;
+    clearUserErrors(path?: Path): void;
+    /**
+     * Merged read — returns `[...schemaErrors[path], ...userErrors[path]]`.
+     * Schema errors come first (structural validation before business logic),
+     * matching the iteration order for `getFirstErrorElement` and the
+     * top-level `errors` drillable Proxy.
+     */
+    getErrorsForPath(path: Path): ValidationError[];
+    /**
+     * Returns a stable schema-declaration ordinal for `key`, assigning a
+     * fresh one if the path hasn't been seen before. Drives
+     * `form.meta.errors` sort order so the aggregate is a function of the
+     * SET of errors currently present (not the temporal order their
+     * Map keys were last `set`). Construction-time seed walks every leaf
+     * in the schema's slim default; runtime callers (DU variant 2, dynamic
+     * array indices, refines targeting cross-field paths) pick up
+     * first-encounter ordinals and keep them for the form's lifetime.
+     */
+    ensurePathOrdinal(key: PathKey): number;
+    /**
+     * Register `element` as a binding for `path`, tagged with the calling
+     * `useForm()` instance's `formInstanceId`. The ID is the disambiguator
+     * used by `getFirstErrorElement` to scope focus / scroll to elements
+     * THIS form instance owns — important when two `useForm()` calls share
+     * a `key` (e.g. sidebar + main rendering the same form), since both
+     * write into one shared element store.
+     */
+    registerElement(path: Path, element: HTMLElement, formInstanceId: string): boolean;
+    deregisterElement(path: Path, element: HTMLElement): number;
+    /**
+     * Optional `meta.instance` carries per-`useForm()`-instance overrides
+     * for `validateOn` / `debounceMs` so the blur-trigger respects the
+     * caller's config when sibling instances share a FormStore.
+     */
+    markFocused(path: Path, focused: boolean, meta?: {
+        readonly instance?: WriteMeta['instance'];
+    }): void;
+    markTouched(path: Path): void;
+    /**
+     * Walk every active-variant leaf under `segments` and flip
+     * `touched: true`. Powers `form.touch(path?)`. Idempotent;
+     * does not mutate value / focused / blurred or trigger validation.
+     */
+    touchAtPath(segments: Path): void;
+    /**
+     * SSR-only optimistic mark: flip `connected: true` on the field
+     * record without an actual DOM element. Called by the `vRegisterHint`
+     * compile-time transform via `RegisterValue.markConnectedOptimistically()`
+     * for every element rendered with `v-register`. Idempotent + no-op on
+     * the client (the directive's `created` hook is the authoritative
+     * source there).
+     */
+    markConnectedOptimistically(path: Path): void;
+    /**
+     * Leaf-only pristine check. `originals` is populated via
+     * `diffAndApply`'s `added` patches, which fire only on primitive
+     * leaves — a container path (e.g. `['profile']`) that isn't in
+     * `originals` returns `true` here even when a descendant is dirty.
+     * Callers that need container semantics should either loop over
+     * leaves or walk `originals` manually. The public `getFieldState`
+     * surface is typed to accept leaf paths only, so in practice this
+     * isn't exposed to consumers.
+     */
+    isPristineAtPath(path: Path): boolean;
+    getFieldRecord(path: Path): FieldRecord | undefined;
+    getOriginalAtPath(path: Path): unknown;
+    /**
+     * Returns the first errored field's first connected, visible DOM
+     * element scoped to `formInstanceId` — the target that
+     * `focusFirstError` / `scrollToFirstError` act on. "First" is
+     * VISUAL-first (DOM-tree order via `compareDocumentPosition`), not
+     * schema-declaration order, so a field rendered above another in the
+     * template focuses first regardless of which one the schema declared
+     * earlier. CSS `order:` flexbox/grid reordering is NOT respected
+     * (DOM-tree order wins) — documented as a tradeoff against forcing
+     * sync layout on every comparison.
+     *
+     * The `formInstanceId` filter scopes focus to elements registered
+     * through THIS form instance. When two `useForm({ key })` calls share
+     * a key, both register into the same element store; without the
+     * filter, the sidebar form's submit could focus the main form's
+     * input. With it, each `useForm()` callsite focuses only its own
+     * elements.
+     *
+     * Returns `null` when every errored path has no currently-attached
+     * element registered to this instance (fields behind `v-if="false"`,
+     * unmounted components, or a hidden `display:none` parent). Callers
+     * get the choice of no-op or a dev-only warning.
+     */
+    getFirstErrorElement(formInstanceId: string): {
+        path: Path;
+        element: HTMLElement;
+    } | null;
+    /**
+     * Cancel every in-flight field-level validation run — clears timers
+     * for debounced 'change' runs that haven't fired, aborts controllers
+     * for runs whose async parse is in flight. Called by `handleSubmit`
+     * at entry (submit validation is authoritative) and by `reset()`.
+     */
+    cancelFieldValidation(): void;
+    /**
+     * Kick off (or schedule) a field-level validation run for `path`. Pass
+     * `path = []` to cover the whole form; `applySchemaErrorsForSubtree`
+     * then wipes every `schemaErrors` entry and replaces them with the
+     * adapter's full async response. Used by persistence's post-hydration
+     * revalidation and by the construction-time async-refine seed.
+     *
+     * `immediate: true` skips the debounce window — the runtime kicks off
+     * the adapter call on the next microtask. Internal callsites use this
+     * for one-shot triggers; the per-keystroke writers pass `false` to
+     * coalesce rapid mutations under the configured debounceMs.
+     *
+     * `override` carries per-`useForm()`-instance values: when provided,
+     * the scheduler honors `override.mode` instead of the store's
+     * captured `validateOn`, and `override.debounceMs` instead of the
+     * store's captured `debounceMs`. Used so sibling instances sharing a
+     * FormStore can each validate on their own cadence.
+     */
+    scheduleFieldValidation(path: Path, immediate: boolean, override?: {
+        readonly mode?: ValidateOn;
+        readonly debounceMs?: number;
+    }): void;
+    /**
+     * Subscribe to every `applyFormReplacement`. Fires synchronously
+     * after `form.value` has been swapped to `next` and all field /
+     * originals bookkeeping has run. Used by persistence + undo/redo
+     * to hook the single mutation funnel. The optional `meta` carries
+     * the originating call site's intent — the persistence subscription
+     * filters on `meta?.persist === true`; subscribers that don't care
+     * about meta can ignore the parameter. Returns an unsubscribe
+     * function.
+     */
+    onFormChange(listener: (next: F, meta?: WriteMeta) => void): () => void;
+    /**
+     * Subscribe to successful submissions. Fires after the consumer's
+     * `onSubmit` callback has resolved — not on validation failure,
+     * not on callback throw. Used by persistence's `clearOnSubmitSuccess`
+     * to drop the stored payload once the form is safely through the
+     * server round-trip. Returns an unsubscribe function.
+     */
+    onSubmitSuccess(listener: () => void): () => void;
+    /**
+     * Subscribe to `reset()` calls. Fires AFTER reset has replaced
+     * the form and cleared errors + lifecycle, so listeners see the
+     * fresh post-reset state. Used by the history module to drop the
+     * undo/redo stack on reset. Returns an unsubscribe function.
+     */
+    onReset(listener: () => void): () => void;
+    /**
+     * Internal: notify submit-success subscribers. Called by
+     * `handleSubmit` in `process-form.ts` once the user callback has
+     * resolved. Consumers shouldn't call this directly.
+     */
+    emitSubmitSuccess(): void;
+    /**
+     * Register a teardown function whose lifetime is bound to the
+     * FormStore itself (not a consumer's Vue effect scope). Called by
+     * `dispose()` when the last consumer unmounts. Used by persistence /
+     * history wiring so their subscribers aren't detached prematurely
+     * when only the first consumer unmounts but others remain.
+     */
+    registerCleanup(fn: () => void): void;
+    /**
+     * Register an async drain function. Called by the registry before
+     * `dispose()` so async background work — chiefly the persistence
+     * layer's debounced storage writes — has a chance to settle without
+     * losing the last keystroke. Each registered function is awaited in
+     * parallel; failures are swallowed to keep eviction reliable.
+     */
+    registerDrain(fn: () => Promise<void>): void;
+    /**
+     * Drain async work registered via `registerDrain`. Resolves once
+     * every registered drain has settled (in parallel). Safe to call
+     * repeatedly — registered drains decide their own idempotency.
+     */
+    awaitPendingWrites(): Promise<void>;
+    /**
+     * Cache for per-state modules (history, persistence) that must
+     * outlive any single consumer. Subsequent `useForm` / `injectForm`
+     * calls for the same key read from this map so the public API shape
+     * is identical regardless of mount order. Keyed by a string identifier
+     * owned by the caller (e.g. `'history'`).
+     */
+    readonly modules: Map<string, unknown>;
+    /**
+     * Per-element persistence opt-in tracker. Empty by default; the
+     * `v-register` directive populates entries on `mount` for each binding
+     * that passed `register('foo', { persist: true })` and clears them on
+     * `beforeUnmount`. Two SFCs sharing a key share this registry — opt-ins
+     * are per-DOM-element, not per-component. Internal to the persistence
+     * subsystem; not part of the consumer API surface.
+     */
+    readonly persistOptIns: PersistOptInRegistry;
+    /**
+     * Resolved sensitive-path predicate for THIS form. Honors the
+     * cascade (`useForm({ sensitiveNames })` > global default >
+     * library `DEFAULT_SENSITIVE_NAMES`). Used by:
+     *  - persistence enforcement (`enforceSensitiveCheck` at write time);
+     *  - the multi-tab sync module (outbound strip + inbound reject);
+     *  - DevTools edit rejection;
+     *  - any future surface that needs to flag "this path holds
+     *    sensitive data."
+     *
+     * Frozen at FormStore construction. Two callsites sharing a key
+     * share the predicate — consistent with the rest of the per-form
+     * resolved-config surface.
+     */
+    readonly isSensitivePath: (path: Path | PathKey | string) => boolean;
+    /**
+     * Single-segment variant of `isSensitivePath`. Used by the DevTools
+     * redact walk to short-circuit whole subtrees the moment any
+     * ancestor segment matches — saving an O(leaves × ancestors) regex
+     * sweep per timeline event. Resolved from the same `sensitiveNames`
+     * cascade as `isSensitivePath`.
+     */
+    readonly segmentMatchesSensitive: (segment: Segment) => boolean;
+    /**
+     * Canonical path keys explicitly opted OUT of multi-tab sync by
+     * `register(path, { multiTab: false })`. The sync module's outbound
+     * broadcaster strips patches at these paths AND the inbound listener
+     * rejects them — symmetric tab-local behaviour for selected fields.
+     *
+     * Read-only Set view; mutate via `incrementNoSyncOptOut` /
+     * `decrementNoSyncOptOut` which maintain a per-path ref count so
+     * multiple bindings on the same path balance correctly across
+     * dynamic conditional renders. Empty by default.
+     */
+    readonly noSyncPaths: ReadonlySet<PathKey>;
+    /**
+     * Ref-counted "this path is tab-local" registration. Called by
+     * `v-register`'s `created` hook for any binding that declared
+     * `register('x', { multiTab: false })`. The first call for a given
+     * path adds it to `noSyncPaths`; subsequent calls just bump the
+     * ref count. Pair with `decrementNoSyncOptOut`.
+     */
+    incrementNoSyncOptOut(path: PathKey): void;
+    /**
+     * Symmetric companion to `incrementNoSyncOptOut`. Called by
+     * `v-register`'s `beforeUnmount` hook. When the ref count for a
+     * path drops to zero, the path is removed from `noSyncPaths` —
+     * dynamic toggling (the binding rendered conditionally) restores
+     * full sync to the path when the last opt-out unmounts.
+     */
+    decrementNoSyncOptOut(path: PathKey): void;
+    /**
+     * Resolved schema-coercion index — the merged config from
+     * `createAttaform({ defaults: { coerce } })` ∪ `useForm({ coerce })`,
+     * keyed by `${input}->${output}` for O(1) per-keystroke dispatch.
+     * Empty Map when coercion is disabled. Read at `register()` time
+     * by `buildCoerceFn` to bake the per-path coerce closure on
+     * `RegisterValue.coerce`.
+     */
+    readonly coerceIndex: CoercionIndex;
+    /**
+     * Tear down non-reactive resources owned by this FormStore. Invoked
+     * by the registry when the last consumer unmounts. Cancels pending
+     * field-validation timers, drops every subscriber, and fires each
+     * cleanup hook registered via `registerCleanup`.
+     */
+    dispose(): void;
+};
+
+/**
+ * Portable SSR detection. The plugin captures this value at install time and
+ * exposes it via the registry so every runtime branch reads a single source
+ * of truth instead of sniffing `import.meta.*` (bundler-specific) at each
+ * call site.
+ *
+ * Consumers can override the heuristic explicitly via
+ * `createAttaform({ ssr: true })`; the default handles the common
+ * Node-vs-browser split without relying on any bundler-injected flag.
+ */
+interface SSRDetectOptions {
+    /**
+     * Force SSR-vs-client mode, bypassing the `typeof window` heuristic.
+     * `true` activates the SSR code paths (no devtools, no persistence
+     * wiring, payload serialisation enabled); `false` forces client mode.
+     * The Nuxt plugin sets this from `import.meta.server` so SSR detection
+     * never depends on whether `window` is polyfilled. Tests that need to
+     * exercise the SSR code paths under jsdom pass `ssr: true`.
+     */
+    ssr?: boolean;
+}
+
+/**
+ * Per-Vue-app container for all form state instances. Each
+ * `app.use(createAttaform())` call gets its own registry,
+ * so the library runs under bare Vue 3 + SSR (via
+ * `@vue/server-renderer`) and Nuxt with the same code path.
+ *
+ * Each form's state lives in `forms: Map<FormKey, FormStore<GenericForm>>`.
+ * The type relaxation at storage time is necessary because different
+ * forms in the same app have different `Form` generics; callers recover
+ * the specific form type via `useForm`'s overloads.
+ */
+/**
+ * Serialised snapshot of one form's state, captured by
+ * `renderAttaformState` for SSR and replayed by
+ * `hydrateAttaformState` on the client. Round-trips through
+ * JSON-safe tuples; field references are intentionally omitted
+ * (DOM nodes don't survive serialisation).
+ */
+type SerializedFormData = {
+    /** The form's value at snapshot time. */
+    readonly form: unknown;
+    /**
+     * Errors produced by the schema at snapshot time. Replayed into
+     * the client form's error state at hydration; cleared on
+     * successful re-validation client-side.
+     */
+    readonly schemaErrors: ReadonlyArray<readonly [string, unknown]>;
+    /**
+     * Errors set explicitly via `setFieldErrors` / `addFieldErrors`
+     * (typically from a server response parsed via `parseApiErrors`)
+     * at snapshot time. Replayed at hydration; persists across
+     * client-side re-validation.
+     */
+    readonly userErrors: ReadonlyArray<readonly [string, unknown]>;
+    /** Per-field metadata (timestamps, raw values, connection flags) captured at snapshot time. */
+    readonly fields: ReadonlyArray<readonly [string, unknown]>;
+    /**
+     * Path keys that were in the form's `blankPaths` set at
+     * snapshot time. Round-trips the "displayed empty" UI state across
+     * the SSR boundary — without it, the client briefly renders
+     * `String(slim-default)` (e.g. `'0'`) for fields the server
+     * rendered as blank. Optional in the wire format so older payload
+     * shapes deserialise cleanly.
+     */
+    readonly blankPaths?: ReadonlyArray<string>;
+};
+type PendingHydration = Map<FormKey, SerializedFormData>;
+/**
+ * The library's per-Vue-app container. One `AttaformRegistry` is
+ * created per `app.use(createAttaform())` call.
+ *
+ * Most consumers never touch this directly — `useForm` and
+ * `injectForm` reach the registry on your behalf. Access it
+ * explicitly only when wiring SSR or a custom plugin integration.
+ */
+type AttaformRegistry = {
+    /**
+     * Live forms keyed by `FormKey`.
+     * @internal
+     */
+    readonly forms: Map<FormKey, FormStore<GenericForm>>;
+    /**
+     * Live wizards keyed by the consumer-supplied `key` option. Populated
+     * by `useWizard(entryForm, { key })`; consulted by `injectWizard(key)` to
+     * resolve cross-component wizard handles. Anonymous wizards (no
+     * `key`) do NOT register here — they're reachable only via ambient
+     * provide/inject.
+     * @internal
+     */
+    readonly wizards: Map<string, UseWizardReturnType>;
+    /**
+     * Snapshots staged by `hydrateAttaformState` waiting to be consumed by the next `useForm` call.
+     * @internal
+     */
+    readonly pendingHydration: PendingHydration;
+    /** `true` while running on the server during SSR; `false` on the client. */
+    readonly ssr: boolean;
+    /** App-level defaults applied to every `useForm` call. */
+    readonly defaults: AttaformDefaults;
+    /**
+     * Track a consumer of `key`. Returns a dispose function — call it
+     * when the consumer unmounts. The form is evicted automatically
+     * when the last consumer disposes, so long-running SPAs don't
+     * leak detached state across navigations.
+     * @internal
+     */
+    readonly trackConsumer: (key: FormKey) => () => void;
+    /**
+     * Track a consumer of wizard `key`. Returns a dispose function — call
+     * it when the consumer unmounts. The wizard handle is evicted from
+     * `wizards` once the last consumer disposes, mirroring the form
+     * consumer-counting mechanics. Anonymous wizards never enter this
+     * counter (they have no key to count under).
+     * @internal
+     */
+    readonly trackWizardConsumer: (key: string) => () => void;
+    /**
+     * Mark a form as eligible for SSR prefetch. The form's
+     * `onServerPrefetch` hook consults `shouldPrefetch(key)` and runs the
+     * captured `defaultValues` factory only when this set contains the
+     * key (and the skip set does not). Set by `form.activate()`,
+     * `useWizard`'s current-step auto-mark, and the future Vite transform.
+     * @internal
+     */
+    readonly enqueuePrefetch: (key: FormKey) => void;
+    /**
+     * Mark a form as ineligible for SSR prefetch. Overrides `enqueuePrefetch`.
+     * Used by `useWizard` to keep non-current steps dormant on the
+     * server even when a transform mark or stray `activate()` would
+     * otherwise enqueue them — the wizard's "user isn't on this step"
+     * signal wins.
+     * @internal
+     */
+    readonly skipPrefetch: (key: FormKey) => void;
+    /**
+     * Whether `key`'s SSR prefetch should run. Returns `true` iff the key
+     * is enqueued AND not skipped.
+     * @internal
+     */
+    readonly shouldPrefetch: (key: FormKey) => boolean;
+    /**
+     * Wait for all pending persistence writes across every live form
+     * to settle. Useful for SSR shutdown and integration tests that
+     * need a deterministic teardown.
+     * @internal
+     */
+    readonly shutdown: () => Promise<void>;
+};
+/**
+ * The Vue `InjectionKey` under which the registry is provided on the
+ * app. Most consumers never need this — `useForm` and
+ * `injectForm` resolve the registry automatically.
+ */
+declare const kAttaformRegistry: InjectionKey<AttaformRegistry>;
+declare module 'vue' {
+    interface App {
+        /** @internal */
+        _attaform?: AttaformRegistry;
+    }
+}
+/** Options for `createRegistry`. */
+type CreateRegistryOptions = SSRDetectOptions & {
+    /**
+     * App-level defaults applied to every `useForm` call. Per-form
+     * options always win. Omitted is equivalent to `{}`.
+     */
+    defaults?: AttaformDefaults;
+};
+/**
+ * Create a fresh `AttaformRegistry`. `createAttaform()` calls
+ * this internally — most consumers never need to call it directly.
+ * Use it when building a custom plugin that doesn't want the
+ * `createAttaform` plugin's auto-install behaviour (e.g. test
+ * harnesses, embedded apps).
+ */
+declare function createRegistry(options?: CreateRegistryOptions): AttaformRegistry;
+/**
+ * Look up the current app's registry from inside a component's
+ * `setup()` (or any synchronous code on the setup call stack).
+ *
+ * Most consumers don't need this — `useForm` and `injectForm`
+ * call it on your behalf. Reach for it directly when building
+ * custom integrations that need the raw registry.
+ *
+ * Throws:
+ * - `OutsideSetupError` when called outside a Vue setup context
+ *   (e.g. from an event handler or async callback). Move the call
+ *   into setup, or trigger it from a child component.
+ * - `RegistryNotInstalledError` when called inside setup but the
+ *   plugin wasn't installed. Add
+ *   `app.use(createAttaform())` to your app entry.
+ */
+declare function useRegistry(): AttaformRegistry;
+/**
+ * Look up a Vue app's registry by `App` reference. Used by
+ * SSR helpers (`renderAttaformState`, `hydrateAttaformState`) that
+ * run outside a component setup context.
+ *
+ * Throws `RegistryNotInstalledError` when the app hasn't been wired
+ * with `createAttaform()`.
+ */
+declare function getRegistryFromApp(app: App): AttaformRegistry;
+
+/**
+ * Options accepted by `injectForm` when passing an object instead of
+ * a bare key string. `__ssrAccessed: true` is set by the Phase 3
+ * `attaform-vite` transform on descendant calls whose template reads
+ * the injected form's reactive state — it tells the runtime to
+ * enqueue the form for SSR prefetch and register the descendant's
+ * `onServerPrefetch` hook. Consumers may set it manually as the
+ * escape hatch when the transform isn't installed or doesn't see
+ * the reference.
+ */
+type InjectFormInput = {
+    readonly key?: FormKey;
+    /**
+     * Set by the Vite transform when this `injectForm` call site sits in
+     * a component whose template / script reads the form's reactive
+     * state. On the server, this enqueues the form for SSR prefetch and
+     * wires `onServerPrefetch` so the descendant awaits the activation
+     * promise before its render emits HTML.
+     *
+     * @internal Transform-emitted. Manual use is the documented escape
+     * hatch when the transform can't reach the reference (dynamic
+     * property access, untransformed bundlers).
+     */
+    readonly __ssrAccessed?: boolean;
+};
+/**
+ * Access an existing form from a descendant component without passing
+ * it through props. Counterpart to `useForm` — `useForm` creates and
+ * provides; `injectForm` looks up via Vue's inject mechanism.
+ *
+ * Three ways to call it:
+ *
+ * ```ts
+ * // Reach the nearest ancestor's anonymous useForm() call.
+ * const form = injectForm<SignupShape>()
+ *
+ * // Reach a specific form by its key — works from anywhere in the app.
+ * const cart = injectForm<CartShape>('cart')
+ *
+ * // Options form. The Vite transform emits this with `__ssrAccessed: true`
+ * // when the descendant's template / script reads the form's reactive
+ * // state, so the descendant participates in SSR prefetch coordination.
+ * const cart = injectForm<CartShape>({ key: 'cart', __ssrAccessed: true })
+ * ```
+ *
+ * Resolution rules (no-key form):
+ * - Closest ambient ancestor wins.
+ * - Only anonymous `useForm()` (no `key`) fills the ambient slot;
+ *   keyed forms are reachable only via `injectForm(key)`.
+ * - Inherits the resolved ancestor's `formInstanceId`.
+ *
+ * Resolution rules (keyed form): registry lookup by string key,
+ * independent of component-tree position.
+ *
+ * Returns `null` when no matching form exists (no ambient ancestor, or
+ * the named key isn't registered). A dev-mode warning points at the
+ * call site to help diagnose typos. Always narrow before using:
+ *
+ * ```ts
+ * const form = injectForm<Shape>('signup')
+ * if (!form) return
+ * form.register('email')
+ * ```
+ *
+ * Pass the `Form` generic explicitly — Vue's provide/inject erases
+ * generics, so the library can't recover the shape automatically.
+ *
+ * The form is kept alive for this component's lifetime; once every
+ * consumer unmounts, the form is cleaned up automatically.
+ */
+declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
+
+/**
+ * Multistep-form orchestrator built around an ordered list of step slots.
+ * Each slot resolves to a participating form: an existing `useForm`
+ * reference, a bare string key (desugared to a noop form so affordance
+ * steps participate uniformly), an eagerly-evaluated function slot for
+ * runtime branching, or a `lazy()`-wrapped function slot that caches
+ * its resolution and re-fires only on its own tracked deps.
+ *
+ * The wizard's surface is read-only from the consumer's side:
+ * navigation (`next` / `back` / `goTo`) walks positional indices,
+ * `handleSubmit` validates the active form on intermediate steps and
+ * the whole wizard on the final step, and URL synchronization rides on
+ * `restore` / `persist` callbacks that default to `?step=<key>`.
+ */
+declare function useWizard<const S extends ReadonlyArray<StepSlot>>(options: WizardOptions & {
+    readonly steps: S;
+}): UseWizardReturnType<S>;
+
+/**
+ * Options accepted by `injectWizard` when passing an object instead of
+ * a bare key string. Mirrors `injectForm`'s `InjectFormInput` shape so
+ * the two composables present an identical call surface.
+ */
+type InjectWizardInput = {
+    readonly key?: string | undefined;
+};
+/**
+ * Access an existing wizard handle from a descendant component without
+ * passing it through props. Counterpart to `useWizard` — `useWizard`
+ * creates and provides; `injectWizard` looks up via Vue's inject
+ * mechanism or the per-app registry.
+ *
+ * Three ways to call it:
+ *
+ * ```ts
+ * // Reach the nearest ancestor's useWizard call (ambient).
+ * const wizard = injectWizard()
+ *
+ * // Reach a specific wizard by its key — works from anywhere in the app.
+ * const signup = injectWizard('signup-wizard')
+ *
+ * // Object form (equivalent; convenient for spread).
+ * const signup = injectWizard({ key: 'signup-wizard' })
+ * ```
+ *
+ * Resolution rules (no-key form):
+ *  - Closest ambient ancestor wins via `provide(kAttaformAncestorWizard)`.
+ *  - Only anonymous (no-`key`) `useWizard()` calls fill the ambient
+ *    slot. Descendants of a keyed wizard must address it explicitly
+ *    via `injectWizard('the-key')`. Mirrors `useForm`'s ambient gate.
+ *
+ * Resolution rules (keyed form): registry lookup by string key,
+ * independent of component-tree position. The wizard must have been
+ * constructed with `useWizard({ steps, key })` to be reachable.
+ *
+ * Returns `null` when no matching wizard exists (no ambient ancestor,
+ * or the named key isn't registered). A dev-mode warning points at the
+ * call site to help diagnose typos. Always narrow before using:
+ *
+ * ```ts
+ * const wizard = injectWizard('signup')
+ * if (!wizard) return
+ * wizard.next()
+ * ```
+ *
+ * Consumer ref-counting: keyed lookups pin the wizard handle in the
+ * registry for this component's lifetime, so the handle survives even
+ * if the parent `useWizard` component unmounts before the child does.
+ * Once every consumer disposes, the registry evicts the entry on the
+ * next microtask. Ambient lookups don't ref-count — the parent
+ * `useWizard`'s scope owns the lifetime.
+ */
+declare function injectWizard(input?: string | InjectWizardInput): UseWizardReturnType | null;
+
+/**
+ * Wrap a function slot in `lazy()` to give that slot its own memoized
+ * cache, distinct from the wizard-wide step compiler.
+ *
+ * Default function slots in `useWizard({ steps })` re-evaluate whenever
+ * the compiled step list re-evaluates, including when an unrelated
+ * slot's reactive deps change. That keeps the rail correct but can
+ * trigger spurious work in a resolver that is expensive (a network
+ * lookup, a heavy schema derivation, an async-derived factory).
+ *
+ * `lazy()` isolates each wrapped slot behind its own cache. The
+ * resolver runs eagerly on the first compile pass; subsequent reads
+ * reuse the cached form. The cache invalidates only when one of the
+ * resolver's own tracked reactive dependencies changes (Vue's
+ * `computed` semantics applied to a slot), or when `wizard.reset()`
+ * triggers a global re-compile:
+ *
+ *   const wizard = useWizard({
+ *     steps: [
+ *       account,
+ *       lazy((ctx) => loadShippingForm(ctx.forms.account.values.region)),
+ *       confirm,
+ *     ],
+ *   })
+ *
+ * Resolution semantics:
+ *  - Eager at construction so `wizard.steps` and SSR markup are honest
+ *    from t=0.
+ *  - Memoized: the resolver re-fires only when one of its own tracked
+ *    reads changes. An unrelated slot re-evaluating does not re-fire
+ *    this one.
+ *  - `wizard.reset()` clears every lazy slot's cache so a reboot truly
+ *    resolves from scratch.
+ *  - Resolving to `undefined` drops the slot from the compiled list
+ *    until the resolver next re-fires.
+ *
+ * The runtime brand returned by `lazy()` is opaque. Use
+ * {@link isLazyMarker} to detect it.
+ */
+declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string | undefined): LazyMarker<Ctx>;
+
+/**
+ * Re-bind a parent's `v-register` onto an inner native element. Use
+ * inside a component that wraps a single form field whose root is
+ * NOT the input itself (e.g. a labelled-row that renders `<label>`
+ * around the input).
+ *
+ * ```vue
+ * <!-- Parent -->
+ * <MyInput v-register="form.register('email')" />
+ *
+ * <!-- MyInput.vue -->
+ * <script setup lang="ts">
+ *   import { useRegister } from 'attaform'
+ *   const rv = useRegister()
+ *   // rv.path / rv.segments / rv.formKey / rv.formInstanceId / rv.innerRef
+ *   // are all reachable directly — no `.value` unwrap.
+ * </script>
+ *
+ * <template>
+ *   <label class="field">
+ *     <span>Email</span>
+ *     <input v-register="rv" />
+ *   </label>
+ * </template>
+ * ```
+ *
+ * Returns a hybrid Proxy: it answers `__v_isRef` / `.value` like a
+ * Vue `Ref<RegisterValue | undefined>` (so templates auto-unwrap
+ * correctly and `v-register="rv"` feeds the underlying RV to the
+ * directive — preserving the directive's path-migration diff across
+ * renders), AND every other property read pierces to the captured
+ * RV's field (so `rv.path` works directly in script setup). Reads
+ * inside reactive scopes (`computed` / `watchEffect`) track the
+ * underlying `shallowRef`, so `rv.path` re-runs when the parent
+ * rebinds to a different path.
+ *
+ * Unbound state: when the parent didn't pass `v-register`, every
+ * piercing read returns `undefined` at runtime, and the return type
+ * surfaces this honestly as `UseRegisterReturn<V> | undefined`.
+ * Consumers defend with optional chaining (`rv?.formKey`,
+ * `rv?.segments`); the directive accepts `undefined` peacefully (its
+ * binding value type is already `RegisterValue<V> | undefined`), so
+ * `v-register="rv"` works whether or not a parent has bound. The
+ * composable's `onMounted` warn fires once per instance to surface
+ * the misuse case at runtime.
+ *
+ * Diagnostic: in dev mode, a single `console.warn` fires per instance
+ * at `onMounted` if the captured value is still `undefined` — by then
+ * the parent has had its full mount lifecycle to bind, so a missing
+ * binding is conclusive misuse. The warn does NOT fire on every read
+ * of the proxy, and is intentionally silent under SSR
+ * (`renderToString` skips `onMounted`); the CSR hydration pass
+ * surfaces the same diagnostic without double-counting through Nuxt's
+ * `dev:ssr-logs` channel.
+ *
+ * When the wrapper's root IS the input itself, Vue's attribute
+ * fallthrough handles the binding and `useRegister` is unnecessary.
+ * For wrappers that bind multiple fields (compound forms), use
+ * `injectForm<Form>(key?)` and call `ctx.register(...)` directly.
+ */
+
+/**
+ * Return type of `useRegister()`. Hybrid of `RegisterValue<V>` (so
+ * `rv.path` / `rv.segments` / `rv.formKey` etc. work directly in
+ * script setup) and `Ref<RegisterValue<V> | undefined>` (so Vue's
+ * template auto-unwrap surfaces the underlying RV to `v-register`
+ * and the directive's path-migration diff sees the real RV across
+ * renders).
+ *
+ * The two surfaces don't clash at the type level: `RegisterValue`
+ * doesn't carry a `value` field, and `Ref<T>`'s `value: T` becomes
+ * the hybrid's only `.value`. Older code that read `rv.value?.path`
+ * keeps working; new code can write `rv.path` directly.
+ */
+type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined>;
+declare function useRegister<V = unknown>(): UseRegisterReturn<V> | undefined;
+
+/**
+ * Stable identifiers for library-emitted `ValidationError` codes.
+ *
+ * Convention: `<scope>:<kebab-case-identifier>`. Three scopes are
+ * recognised by the library:
+ *
+ * - `atta:` — emitted by the framework-agnostic core (this map).
+ * - `zod:` — emitted by the Zod adapter; computed inline from
+ *   `issue.code` (e.g. `zod:too_small`). No enum here because
+ *   Zod's code list evolves.
+ * - consumer-defined — anything the consumer's backend / app stamps
+ *   onto a `ValidationError` (via the `parseApiErrors` wire payload
+ *   or `setFieldErrors` directly). Pick a scope (`api:`, `auth:`,
+ *   etc.) and stay consistent.
+ *
+ * Use these constants in tests and error-routing UI:
+ *
+ * ```ts
+ * if (error.code === AttaformErrorCode.NoValueSupplied) {
+ *   // user hasn't filled this field
+ * }
+ * ```
+ */
+declare const AttaformErrorCode: {
+    /** A required field is in the blank set — user hasn't supplied a value. */
+    readonly NoValueSupplied: "atta:no-value-supplied";
+    /** The schema adapter's `validateAtPath` threw synchronously. */
+    readonly AdapterThrew: "atta:adapter-threw";
+    /**
+     * User code inside a `z.preprocess`, `.refine`, or `.transform`
+     * threw (sync or async). The adapter caught the throw and surfaced
+     * it as a `ValidationError` at the field path so the form's normal
+     * error pipeline handles it instead of leaking as an unhandled
+     * rejection or routing through `submitError`.
+     */
+    readonly ValidatorThrew: "atta:validator-threw";
+    /**
+     * A function-form `defaultValues` factory threw or its promise
+     * rejected. The runtime captures the raw error on `form.hydrateError`
+     * and ALSO surfaces a form-level `ValidationError` (path `[]`) so
+     * the standard error pipeline carries the signal. Critical for the
+     * SSR round-trip: `hydrateError` itself does not ride the wire
+     * payload, but `schemaErrors` does, so the client sees the failure
+     * after rehydration without an extra channel.
+     */
+    readonly HydrationFailed: "atta:hydration-failed";
+    /** The supplied path didn't resolve to any node in the schema. */
+    readonly PathNotFound: "atta:path-not-found";
+    /**
+     * A walked form's `activate()` (async `defaultValues` factory) threw
+     * during `wizard.handleSubmit`'s path walk. Surfaced as a synthetic
+     * `ValidationError` at the form-level path (`[]`) so the wizard's
+     * aggregate error pipeline can carry the failure alongside ordinary
+     * validation errors. The raw factory error remains on
+     * `form.hydrateError` for retry UX.
+     */
+    readonly ActivationFailed: "atta:activation-failed";
+};
+type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
+
+export { AttaformErrorCode as d, createRegistry as p, defaultCoercionRules as q, defineCoercion as r, getRegistryFromApp as s, injectForm as t, injectWizard as u, kAttaformRegistry as v, lazy as w, useRegister as x, useRegistry as y, useWizard as z };
+export type { AttaformRegistry as A, CompiledStep as C, FormStatus as F, InjectWizardInput as I, LazyMarker as L, SSRDetectOptions as S, UseRegisterReturn as U, WizardCtx as W, SerializedFormData as a, AggregateError as b, AnyForm as c, StepSlot as e, UseWizardReturnType as f, WizardCtxForm as g, WizardOnError as h, WizardOnSubmit as i, WizardOptions as j, WizardPersistFn as k, WizardRestoreFn as l, WizardRestoreState as m, WizardStatusesProxy as n, WizardSubmitContext as o };