attaform 0.25.0 → 0.27.0

package/dist/shared/{attaform.B5GFS3Su.d.cts → attaform.D99pd7JG.d.cts}

@@ -1,931 +1,556 @@
-import { F as FormKey, b as UseFormReturnType, G as GenericForm, W as PathKey, m as DisplayCtx, d as GetDisplayState, n as DisplayMachine, V as Path, aa as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, ag as ValidationError, a as AbstractSchema, ak as WriteMeta, j as DeepPartial, al as WriteShape, at as TransformAbortHolder, ae as ValidateOn, A as AttaformDefaults, c as RegisterValue } from './attaform.i_LA3X9o.cjs';
-import { Ref, ComputedRef, App, InjectionKey } from 'vue';
+import { G as GenericForm, F as FormKey, a as UseFormReturnType, a4 as RegisterValue, T as PathKey, k as DisplayCtx, w as GetDisplayState, l as DisplayMachine, S as Path, a9 as SlimPrimitiveKind, C as CoercionEntry, e as CoercionRegistry, af as ValidationError, A as AbstractSchema, aj as WriteMeta, h as DeepPartial, ak as WriteShape, as as TransformAbortHolder, ad as ValidateOn, d as AttaformDefaults, at as RegisterModelDynamicCustomDirective } from './attaform.C3WnCDXz.cjs';
+import { Ref, ComputedRef, App, InjectionKey, Plugin } 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.
+ * 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 AnyForm = {
-    readonly key: FormKey;
+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;
 };
 /**
- * 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.
+ * 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.
  *
- * 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).
+ * Three ways to call it:
  *
- * 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 WizardAggregateError = {
-    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.
+ * ```ts
+ * // Reach the nearest ancestor's anonymous useForm() call.
+ * const form = injectForm<SignupShape>()
  *
- * 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.
+ * // Reach a specific form by its key — works from anywhere in the app.
+ * const cart = injectForm<CartShape>('cart')
  *
- * 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`.
+ * // 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 yet). A dev-mode warning points at the
+ * call site, lists the registered keys, and flags the mount-timing case
+ * (a form created by a child or sibling isn't registered until its own
+ * setup runs). 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.
  */
-type WizardCtxForm = AnyForm & {
-    readonly values: Readonly<Record<string, unknown>>;
-};
+declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
+
 /**
- * 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.
+ * 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).
  *
- * 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.
+ * ```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.
  */
-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.
+ * 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.
  */
-declare const _lazyBrand: unique symbol;
+type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined>;
+declare function useRegister<V = unknown>(): UseRegisterReturn<V> | undefined;
+
 /**
- * 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.
+ * Per-form display engine: owns the clock and the timers that the pure
+ * `getDisplayState` reducer policy needs, so the reducer itself stays a
+ * deterministic `(prev, ctx) => next` function.
  *
- * 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.
+ * It keeps a `Map` of the machines that are still *active* (a spinner is
+ * showing, a verdict is being held, or a `reviewAt` deadline is pending),
+ * a single reactive `tick` ref, and a single `setTimeout` aimed at the
+ * nearest `reviewAt` across every active field. When a field-state
+ * computed reads `resolve`, it subscribes to `tick`; when the timer
+ * fires, `tick` bumps and every dependent computed re-runs the reducer,
+ * so a field whose deadline elapsed transitions (verdict → spinner, or
+ * spinner → settled verdict) without any per-field watcher.
+ *
+ * Eviction: a machine is dropped once it reaches a terminal *idle* state
+ * with no pending review. Error / success / pending machines are retained
+ * so the reducer can hold the prior verdict under the show-delay window of
+ * the *next* validation streak (no success → idle → success flicker). The
+ * retained set is bounded by the rendered non-idle fields; none of them
+ * arm a timer, so retention costs memory, never CPU.
+ *
+ * Untrusted reducer: `getDisplayState` is consumer-overridable, so the
+ * engine treats the returned `reviewAt` as untrusted. A non-finite deadline
+ * (NaN / ±Infinity from a custom predicate's bad arithmetic) is ignored
+ * rather than handed to `setTimeout`, where it coerces to 0 and spins; an
+ * over-large finite deadline is clamped below the 32-bit `setTimeout`
+ * overflow; and the timer refuses to re-arm for the exact deadline it just
+ * fired, so a predicate re-emitting a fixed or past `reviewAt` can't drive an
+ * infinite fire loop. None of these arise from the library default, which
+ * always advances its deadline or drops it.
+ *
+ * Background tabs: `setTimeout` is throttled to >= 1s while a tab is hidden,
+ * so a min-visible hold can overshoot. A `visibilitychange` listener bumps
+ * the clock on return to the foreground, so any overdue deadline resolves at
+ * once instead of lingering.
+ *
+ * SSR: no clock, no timers, no listener. With `now` frozen and nothing
+ * validating at render, the reducer returns the plain verdict (never
+ * pending) and the engine stores nothing, so the server HTML and the
+ * client's first render agree — no hydration mismatch on the display
+ * projection.
  */
-type LazyMarker<Ctx = WizardCtx> = {
-    readonly [_lazyBrand]: true;
-    readonly resolve: (ctx: Ctx) => AnyForm | string | null | undefined;
+type DisplayEngine = {
+    /**
+     * Resolve a path's next `DisplayMachine`. Subscribes the calling
+     * computed to the engine clock, threads the path's previous machine
+     * through `reducer`, persists or evicts the result, and re-arms the
+     * single timer to the nearest deadline.
+     */
+    resolve(key: PathKey, ctx: DisplayCtx, reducer: GetDisplayState): DisplayMachine;
+    /** Drop every retained machine and cancel the timer (used by `reset()`). */
+    clear(): void;
+    /** Tear down for good: `clear()` plus detaching the visibility listener. */
+    dispose(): void;
+    /** Introspection for tests: count of retained machines. */
+    size(): number;
+    /** Introspection for tests: whether a path currently has a retained machine. */
+    has(key: PathKey): boolean;
+    /** Introspection for tests: whether a deadline timer is currently armed. */
+    hasTimer(): boolean;
 };
+
 /**
- * One position in the source `useWizard({ steps })` array. Each slot
- * resolves to a compiled `{ key, form }` step, or drops out:
+ * Per-path field status. Replaced wholesale (not mutated in place) on
+ * every change. Five semantic groups:
  *
- *  - `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).
- *  - `null` / `undefined` — a literal absence, dropped from the compiled
- *                        list. Lets a conditional step read inline as
- *                        `cond ? form : null` without pre-filtering the
- *                        array.
- *  - function          — eager slot, re-evaluates reactively. Returns
- *                        one of the above, or `null` / `undefined` to
- *                        drop the slot from the compiled list.
- *  - `LazyMarker`      — memoized function slot (see `lazy`).
- */
-type StepSlot<Ctx = WizardCtx> = AnyForm | string | null | undefined | ((ctx: Ctx) => AnyForm | string | null | 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.
+ *   - `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` — focus/blur 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).
+ *   - `interacted` — value-mutation history, not DOM state. Plain
+ *     boolean: `false` at registration, sticky `true` once the user
+ *     issues a value edit through the directive's input listeners
+ *     (never on hydration, default seeding, or programmatic setValue);
+ *     cleared with `touched` by `form.reset()` / `form.resetField(path)`.
+ *   - `blurredAfterInteraction` — the first blur that follows a value
+ *     edit (the field has been edited and then left). Plain boolean,
+ *     sticky `true`. A tab-through blur with no prior edit does NOT set
+ *     it (`interacted` is still false at that blur). Composes
+ *     `interacted` with the departure; drives the default display gate.
  */
-type WizardRestoreState = {
-    readonly step?: FormKey;
+type FieldRecord = {
+    readonly path: Path;
+    readonly updatedAt: string | null;
+    readonly connected: boolean;
+    readonly focused: boolean | null;
+    readonly blurred: boolean | null;
+    readonly touched: boolean;
+    readonly interacted: boolean;
+    readonly blurredAfterInteraction: 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>;
 };
 /**
- * `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.
+ * 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 WizardPersistFn = (state: WizardRestoreState) => void;
+type OriginalsRecord = {
+    readonly segments: Path;
+    readonly value: unknown;
+};
+
 /**
- * Submit context passed to the `onSubmit` callback registered via
- * `wizard.handleSubmit(onSubmit, onError?)`. `handleSubmit` always
- * processes the whole step list, so `values` carries every form's
- * parsed output regardless of which step fired the submit.
+ * 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.
  *
- *  - `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`. Positional only: it reports where the
- *               submit fired, never what got validated. A user who steps
- *               back, edits, and submits from the middle sees
- *               `isFinal === false`, yet the whole list is still
- *               processed and `done` still latches on success.
+ * 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 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-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.
  */
-type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
+declare function defineCoercion<I extends SlimPrimitiveKind, O extends SlimPrimitiveKind>(entry: CoercionEntry<I, O>): CoercionEntry<I, O>;
 /**
- * Optional `onError` callback registered via `wizard.handleSubmit`.
- * Receives the aggregate error list spanning EVERY step (handleSubmit
- * validates the whole wizard), so a failed submit surfaces every form's
- * errors at once, not just the active step's. Entries originate from
- * per-form validation, activation failures (`atta:activation-failed`),
- * and a submit callback that left errors on a processed step (the
- * `setErrors(...); return` server-rejection path). Sync or async; the
- * returned promise gates `wizard.submitting`.
+ * 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 WizardOnError = (errors: readonly WizardAggregateError[]) => void | Promise<void>;
+type CoercionIndex = ReadonlyMap<`${SlimPrimitiveKind}->${SlimPrimitiveKind}`, CoercionEntry>;
 /**
- * Options for `useWizard({ steps, … })`. `steps` is the only required
- * field; the rest are optional and default sensibly for the common
- * URL-synchronized wizard case.
+ * 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.
  */
-type WizardOptions = {
+declare const defaultCoercionRules: CoercionRegistry;
+
+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>;
     /**
-     * Ordered list of slots that compile into the wizard's positional
-     * step list. See `StepSlot` for the per-slot shape contract.
+     * 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. `setErrors` / `clearErrors` do NOT touch this Map.
      */
-    readonly steps: ReadonlyArray<StepSlot>;
+    readonly schemaErrors: Map<PathKey, ValidationError[]>;
     /**
-     * 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.
+     * User-injected errors. Written ONLY by the `setErrors` / `clearErrors`
+     * API surface (and history / hydration replay). Survives schema revalidation and
+     * successful submits — the consumer owns its lifetime explicitly.
      */
-    readonly key?: string;
+    readonly userErrors: Map<PathKey, ValidationError[]>;
     /**
-     * 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.
+     * 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)`.
      *
-     * 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
+     * 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/validation/blank.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.
      *
-     * Unknown keys in the seed object dev-warn so a stale resume payload
-     * surfaces at construction.
+     * 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/validation/blank.md` for the conceptual model.
      */
-    readonly defaultStatuses?: Record<string, FormStatus> | (() => Record<string, FormStatus>) | (() => Promise<Record<string, FormStatus>>);
+    readonly blankPaths: Set<PathKey>;
     /**
-     * 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.
+     * 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 `getDisplayState` predicate driving `field.displayState`,
+     * the `show*` booleans, and their `form.meta` rollups. Resolved once
+     * at construction via `resolveGetDisplayState(options.getDisplayState)`;
+     * `undefined` config falls through to `defaultDisplayState`. The
+     * field-state computeds read the resolved function directly on every
+     * read.
+     */
+    readonly getDisplayState: GetDisplayState;
+    /**
+     * Per-form display engine: owns the clock and the single timer the timed
+     * `getDisplayState` reducer policy needs, keeping the reducer itself a
+     * pure `(prev, ctx) => next` function. The field-state computeds route
+     * every `displayState` read through `displayEngine.resolve(...)`, which
+     * threads the path's previous machine, persists or evicts the result, and
+     * re-arms the nearest-deadline timer. Constructed once at form
+     * construction; torn down via `registerCleanup` on store eviction.
+     */
+    readonly displayEngine: DisplayEngine;
+    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<Error | null>;
+    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` when this store carries an SSR prefetch queue (server path
+     * where `state.activate()` must enqueue intent before deciding
+     * whether to fire). The flag lets `buildFormApi` skip the lazy
+     * activation gate for forms with no factory AND no SSR prefetch —
+     * the common client-side case where `gated()` is otherwise pure
+     * reactive overhead on every public method call.
+     */
+    readonly hasSsrPrefetch: boolean;
+    /**
+     * `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.
      *
-     * The override is invoked inside a Vue `computed` so it must be
-     * synchronous and may only read reactive sources.
+     * Does NOT touch dirty / touched / submit state — chain
+     * `form.reset()` if you want a clean baseline.
      */
-    readonly progress?: (steps: ReadonlyArray<CompiledStep>) => number;
+    rehydrate(): Promise<void>;
     /**
-     * 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.
+     * 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 focusFirstError?: boolean;
+    readonly submissionGeneration: Ref<number>;
     /**
-     * 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.).
+     * 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 restore?: WizardRestoreFn | false;
+    readonly activeValidations: Ref<number>;
     /**
-     * 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;
-};
-/**
- * True when a single slot is guaranteed to contribute exactly one
- * compiled step: a bare form or affordance string that is neither
- * nullish nor a (maybe-absent) function / `lazy()` slot. One of these
- * anywhere in the tuple proves the compiled list is non-empty.
- */
-type IsGuaranteedStep<T> = [null] extends [T] ? false : [undefined] extends [T] ? false : T extends LazyMarker | ((...args: unknown[]) => unknown) ? false : T extends string ? true : T extends {
-    readonly key: string;
-} ? true : false;
-/**
- * Predicate: is the steps tuple statically guaranteed to compile to a
- * non-empty list? True when at least one element is a guaranteed step
- * (see `IsGuaranteedStep`). Function / `lazy()` slots may resolve to
- * nothing, and `null` / `undefined` (a literal absence or a
- * `cond ? form : null` union) is an explicit drop, so none of those
- * prove non-emptiness; a tuple of only maybe-absent slots stays
- * honestly `| undefined`.
- *
- * 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 [infer First, ...infer Rest] ? IsGuaranteedStep<First> extends true ? true : StaticallyNonEmpty<Rest> : 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, schema-erased to `UseFormReturnType<GenericForm>`
- * and narrowed to non-`undefined` when `S` is statically safe. The runtime
- * value is a live facade over the active step, so reads (`.values`, `.meta`,
- * `.history`) and `.handleSubmit` always target the current step. Values are
- * loose here because the active step's schema is not statically known; reach
- * for the original form ref or `ctx.get(ref)` when you need typed per-step
- * values.
- */
-type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? UseFormReturnType<GenericForm> : UseFormReturnType<GenericForm> | undefined;
-/**
- * Per-slot contribution to {@link FormsRecordOf}. Strips a `null` /
- * `undefined` (a literal absence or a `cond ? form : null` union) off the
- * slot first, so a conditionally-present form still maps to its key and
- * stays concretely typed on `wizard.forms`; a purely nullish slot
- * contributes nothing.
- */
-type SlotRecord<First, F = Exclude<First, null | undefined>> = [F] extends [never] ? unknown : F extends string ? {
-    readonly [P in F]: AnyForm;
-} : F extends {
-    readonly key: infer K extends string;
-} ? {
-    readonly [P in K]: F;
-} : unknown;
-/**
- * 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. A form kept behind a `cond ? form : null`
- *    conditional still maps to its key.
- *  - **`null` / `undefined` slot**: contributes nothing.
- *  - **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>
-] ? SlotRecord<First> & 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`  — a LIVE view of the active step's form. Operating
- *                    through it always targets the current step, so a
- *                    handler captured once at setup
- *                    (`wizard.activeForm.handleSubmit(() =>
- *                    wizard.next())`) retargets as the wizard advances.
- *                    No longer `===` the raw per-step handle; reach for
- *                    `wizard.forms[key]` when you need raw identity.
- *                    Same `undefined` 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
- *                    `handleSubmit` resolves without throwing AND leaves
- *                    no errors set on any step, and stays `true` through
- *                    subsequent edits or invalidations. A callback that
- *                    calls `setErrors` and returns (the documented
- *                    server-rejection path) is a failed submit, so it
- *                    does not flip `done`. 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.
- *  - `submitError` — the error THROWN by the most recent
- *                    `wizard.handleSubmit` callback (or its `onError`),
- *                    coerced to a real `Error`. Mirrors
- *                    `form.meta.submitError`: this is the unexpected-throw
- *                    channel, so an expected rejection handled via
- *                    `setErrors` (no throw) surfaces through the error
- *                    surface and `onError` instead, leaving this `null`.
- *                    Cleared at submit entry and by `reset()`, parked here
- *                    rather than re-thrown, so the handler resolves and
- *                    never manufactures a `window` unhandledrejection.
- *                    `null` on success.
- *  - `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`.
- *  - `tryNext()`   — validate the active step, then advance iff it
- *                    passed; invalid input keeps the pin put under the
- *                    form's standard error reveal (first error focused,
- *                    display state advanced). The inline-bindable
- *                    shorthand for `activeForm.handleSubmit(() =>
- *                    next())`. Resolves to whether the pin moved. No-ops
- *                    to `false` on a degenerate or final-step wizard
- *                    (finish via `handleSubmit`).
- *  - `handleSubmit(onSubmit, onError?)` — always validates the entire
- *                    step list, from any step, and never advances the
- *                    pin: on success it latches `done`; on any error it
- *                    focuses the first failing step and fires `onError`
- *                    with errors spanning every step. To gate advancing
- *                    a step on its own validity, compose with the active
- *                    form's submit: `activeForm.handleSubmit(() =>
- *                    wizard.next())`. 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 WizardAggregateError[]>>;
-    readonly progress: number;
-    readonly canAdvance: boolean;
-    readonly canGoBack: boolean;
-    readonly complete: boolean;
-    readonly done: boolean;
-    readonly submitting: boolean;
-    readonly submissionAttempts: number;
-    readonly submitError: Error | null;
-    readonly visited: readonly FormKey[];
-    readonly next: () => Promise<void>;
-    readonly back: () => void;
-    readonly goTo: (key: string) => void;
-    readonly tryNext: () => Promise<boolean>;
-    readonly handleSubmit: (onSubmit: WizardOnSubmit, onError?: WizardOnError) => (event?: Event) => Promise<void>;
-    readonly reset: () => void;
-};
-
-/**
- * Per-form display engine: owns the clock and the timers that the pure
- * `getDisplayState` reducer policy needs, so the reducer itself stays a
- * deterministic `(prev, ctx) => next` function.
- *
- * It keeps a `Map` of the machines that are still *active* (a spinner is
- * showing, a verdict is being held, or a `reviewAt` deadline is pending),
- * a single reactive `tick` ref, and a single `setTimeout` aimed at the
- * nearest `reviewAt` across every active field. When a field-state
- * computed reads `resolve`, it subscribes to `tick`; when the timer
- * fires, `tick` bumps and every dependent computed re-runs the reducer,
- * so a field whose deadline elapsed transitions (verdict → spinner, or
- * spinner → settled verdict) without any per-field watcher.
- *
- * Eviction: a machine is dropped once it reaches a terminal *idle* state
- * with no pending review. Error / success / pending machines are retained
- * so the reducer can hold the prior verdict under the show-delay window of
- * the *next* validation streak (no success → idle → success flicker). The
- * retained set is bounded by the rendered non-idle fields; none of them
- * arm a timer, so retention costs memory, never CPU.
- *
- * Untrusted reducer: `getDisplayState` is consumer-overridable, so the
- * engine treats the returned `reviewAt` as untrusted. A non-finite deadline
- * (NaN / ±Infinity from a custom predicate's bad arithmetic) is ignored
- * rather than handed to `setTimeout`, where it coerces to 0 and spins; an
- * over-large finite deadline is clamped below the 32-bit `setTimeout`
- * overflow; and the timer refuses to re-arm for the exact deadline it just
- * fired, so a predicate re-emitting a fixed or past `reviewAt` can't drive an
- * infinite fire loop. None of these arise from the library default, which
- * always advances its deadline or drops it.
- *
- * Background tabs: `setTimeout` is throttled to >= 1s while a tab is hidden,
- * so a min-visible hold can overshoot. A `visibilitychange` listener bumps
- * the clock on return to the foreground, so any overdue deadline resolves at
- * once instead of lingering.
- *
- * SSR: no clock, no timers, no listener. With `now` frozen and nothing
- * validating at render, the reducer returns the plain verdict (never
- * pending) and the engine stores nothing, so the server HTML and the
- * client's first render agree — no hydration mismatch on the display
- * projection.
- */
-type DisplayEngine = {
-    /**
-     * Resolve a path's next `DisplayMachine`. Subscribes the calling
-     * computed to the engine clock, threads the path's previous machine
-     * through `reducer`, persists or evicts the result, and re-arms the
-     * single timer to the nearest deadline.
-     */
-    resolve(key: PathKey, ctx: DisplayCtx, reducer: GetDisplayState): DisplayMachine;
-    /** Drop every retained machine and cancel the timer (used by `reset()`). */
-    clear(): void;
-    /** Tear down for good: `clear()` plus detaching the visibility listener. */
-    dispose(): void;
-    /** Introspection for tests: count of retained machines. */
-    size(): number;
-    /** Introspection for tests: whether a path currently has a retained machine. */
-    has(key: PathKey): boolean;
-    /** Introspection for tests: whether a deadline timer is currently armed. */
-    hasTimer(): boolean;
-};
-
-/**
- * Per-path field status. Replaced wholesale (not mutated in place) on
- * every change. Five 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` — focus/blur 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).
- *   - `interacted` — value-mutation history, not DOM state. Plain
- *     boolean: `false` at registration, sticky `true` once the user
- *     issues a value edit through the directive's input listeners
- *     (never on hydration, default seeding, or programmatic setValue);
- *     cleared with `touched` by `form.reset()` / `form.resetField(path)`.
- *   - `blurredAfterInteraction` — the first blur that follows a value
- *     edit (the field has been edited and then left). Plain boolean,
- *     sticky `true`. A tab-through blur with no prior edit does NOT set
- *     it (`interacted` is still false at that blur). Composes
- *     `interacted` with the departure; drives the default display gate.
- */
-type FieldRecord = {
-    readonly path: Path;
-    readonly updatedAt: string | null;
-    readonly connected: boolean;
-    readonly focused: boolean | null;
-    readonly blurred: boolean | null;
-    readonly touched: boolean;
-    readonly interacted: boolean;
-    readonly blurredAfterInteraction: 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;
-};
-
-/**
- * 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;
-
-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. `setErrors` / `clearErrors` do NOT touch this Map.
-     */
-    readonly schemaErrors: Map<PathKey, ValidationError[]>;
-    /**
-     * User-injected errors. Written ONLY by the `setErrors` / `clearErrors`
-     * API surface (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/validation/blank.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/validation/blank.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 `getDisplayState` predicate driving `field.displayState`,
-     * the `show*` booleans, and their `form.meta` rollups. Resolved once
-     * at construction via `resolveGetDisplayState(options.getDisplayState)`;
-     * `undefined` config falls through to `defaultDisplayState`. The
-     * field-state computeds read the resolved function directly on every
-     * read.
-     */
-    readonly getDisplayState: GetDisplayState;
-    /**
-     * Per-form display engine: owns the clock and the single timer the timed
-     * `getDisplayState` reducer policy needs, keeping the reducer itself a
-     * pure `(prev, ctx) => next` function. The field-state computeds route
-     * every `displayState` read through `displayEngine.resolve(...)`, which
-     * threads the path's previous machine, persists or evicts the result, and
-     * re-arms the nearest-deadline timer. Constructed once at form
-     * construction; torn down via `registerCleanup` on store eviction.
-     */
-    readonly displayEngine: DisplayEngine;
-    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<Error | null>;
-    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` when this store carries an SSR prefetch queue (server path
-     * where `state.activate()` must enqueue intent before deciding
-     * whether to fire). The flag lets `buildFormApi` skip the lazy
-     * activation gate for forms with no factory AND no SSR prefetch —
-     * the common client-side case where `gated()` is otherwise pure
-     * reactive overhead on every public method call.
-     */
-    readonly hasSsrPrefetch: boolean;
-    /**
-     * `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.
+     * `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>;
     /**
@@ -1214,132 +839,658 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * `transformError`, register `holder` for later abort. Returns the run
      * token. See `InternalRegisterValue.beginTransform`.
      */
-    beginTransform(key: PathKey, holder: TransformAbortHolder): number;
-    /** `true` while `token` is the live async-transform run at `key`. */
-    isCurrentTransform(key: PathKey, token: number): boolean;
+    beginTransform(key: PathKey, holder: TransformAbortHolder): number;
+    /** `true` while `token` is the live async-transform run at `key`. */
+    isCurrentTransform(key: PathKey, token: number): boolean;
+    /**
+     * Close the run `token` at `key`: release the counters (no-op if the
+     * run was already released by a supersede / cancel) and flush settled
+     * `settleTransforms` waiters.
+     */
+    endTransform(key: PathKey, token: number): void;
+    /** Record a per-field normalization failure at `key` (`field.transformError`). */
+    setTransformError(key: PathKey, err: Error): void;
+    /**
+     * Abort + release every in-flight async-transform run (all paths) and
+     * clear `transformErrors`. Mirrors `cancelFieldValidation`; called by
+     * `reset()` and store teardown.
+     */
+    cancelTransforms(): void;
+    /**
+     * Path-scoped counterpart to `cancelTransforms`: abort + release only
+     * the runs at-or-under `prefix`, clearing their `transformError`.
+     * Called by `resetField`.
+     */
+    cancelTransformsUnder(prefix: Path): void;
+    /**
+     * Resolve once async transforms are quiescent — globally (`path`
+     * omitted) or at-or-under `path`. Resolve-never-reject. See
+     * `UseFormReturnType.settleTransforms`.
+     */
+    settleTransforms(path?: string | Path): Promise<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 undo/redo to hook the single
+     * mutation funnel. The optional `meta` carries the originating call
+     * site's intent; 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. The DevTools panel rides this to surface a
+     * submit event. 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>;
     /**
-     * Close the run `token` at `key`: release the counters (no-op if the
-     * run was already released by a supersede / cancel) and flush settled
-     * `settleTransforms` waiters.
+     * 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`.
      */
-    endTransform(key: PathKey, token: number): void;
-    /** Record a per-field normalization failure at `key` (`field.transformError`). */
-    setTransformError(key: PathKey, err: Error): void;
+    readonly coerceIndex: CoercionIndex;
     /**
-     * Abort + release every in-flight async-transform run (all paths) and
-     * clear `transformErrors`. Mirrors `cancelFieldValidation`; called by
-     * `reset()` and store teardown.
+     * 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`.
      */
-    cancelTransforms(): void;
+    dispose(): void;
+};
+
+/**
+ * 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 WizardAggregateError = {
+    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 | null | undefined;
+};
+/**
+ * One position in the source `useWizard({ steps })` array. Each slot
+ * resolves to a compiled `{ key, form }` step, or drops out:
+ *
+ *  - `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).
+ *  - `null` / `undefined` — a literal absence, dropped from the compiled
+ *                        list. Lets a conditional step read inline as
+ *                        `cond ? form : null` without pre-filtering the
+ *                        array.
+ *  - function          — eager slot, re-evaluates reactively. Returns
+ *                        one of the above, or `null` / `undefined` to
+ *                        drop the slot from the compiled list.
+ *  - `LazyMarker`      — memoized function slot (see `lazy`).
+ */
+type StepSlot<Ctx = WizardCtx> = AnyForm | string | null | undefined | ((ctx: Ctx) => AnyForm | string | null | 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?)`. `handleSubmit` always
+ * processes the whole step list, so `values` carries every form's
+ * parsed output regardless of which step fired the submit.
+ *
+ *  - `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`. Positional only: it reports where the
+ *               submit fired, never what got validated. A user who steps
+ *               back, edits, and submits from the middle sees
+ *               `isFinal === false`, yet the whole list is still
+ *               processed and `done` still latches on success.
+ */
+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 spanning EVERY step (handleSubmit
+ * validates the whole wizard), so a failed submit surfaces every form's
+ * errors at once, not just the active step's. Entries originate from
+ * per-form validation, activation failures (`atta:activation-failed`),
+ * and a submit callback that left errors on a processed step (the
+ * `setErrors(...); return` server-rejection path). Sync or async; the
+ * returned promise gates `wizard.submitting`.
+ */
+type WizardOnError = (errors: readonly WizardAggregateError[]) => 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 = {
     /**
-     * Path-scoped counterpart to `cancelTransforms`: abort + release only
-     * the runs at-or-under `prefix`, clearing their `transformError`.
-     * Called by `resetField`.
+     * Ordered list of slots that compile into the wizard's positional
+     * step list. See `StepSlot` for the per-slot shape contract.
      */
-    cancelTransformsUnder(prefix: Path): void;
+    readonly steps: ReadonlyArray<StepSlot>;
     /**
-     * Resolve once async transforms are quiescent — globally (`path`
-     * omitted) or at-or-under `path`. Resolve-never-reject. See
-     * `UseFormReturnType.settleTransforms`.
+     * 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.
      */
-    settleTransforms(path?: string | Path): Promise<void>;
+    readonly key?: string;
     /**
-     * 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.
+     * 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.
      *
-     * `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.
+     * 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
      *
-     * `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 undo/redo to hook the single
-     * mutation funnel. The optional `meta` carries the originating call
-     * site's intent; 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. The DevTools panel rides this to surface a
-     * submit event. 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.
+     * Unknown keys in the seed object dev-warn so a stale resume payload
+     * surfaces at construction.
      */
-    registerDrain(fn: () => Promise<void>): void;
+    readonly defaultStatuses?: Record<string, FormStatus> | (() => Record<string, FormStatus>) | (() => Promise<Record<string, FormStatus>>);
     /**
-     * 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.
+     * 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.
      */
-    awaitPendingWrites(): Promise<void>;
+    readonly progress?: (steps: ReadonlyArray<CompiledStep>) => number;
     /**
-     * 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'`).
+     * 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 modules: Map<string, unknown>;
+    readonly focusFirstError?: boolean;
     /**
-     * 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`.
+     * 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 coerceIndex: CoercionIndex;
+    readonly restore?: WizardRestoreFn | false;
     /**
-     * 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`.
+     * 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.
      */
-    dispose(): void;
+    readonly persist?: WizardPersistFn | false;
+};
+/**
+ * True when a single slot is guaranteed to contribute exactly one
+ * compiled step: a bare form or affordance string that is neither
+ * nullish nor a (maybe-absent) function / `lazy()` slot. One of these
+ * anywhere in the tuple proves the compiled list is non-empty.
+ */
+type IsGuaranteedStep<T> = [null] extends [T] ? false : [undefined] extends [T] ? false : T extends LazyMarker | ((...args: unknown[]) => unknown) ? false : T extends string ? true : T extends {
+    readonly key: string;
+} ? true : false;
+/**
+ * Predicate: is the steps tuple statically guaranteed to compile to a
+ * non-empty list? True when at least one element is a guaranteed step
+ * (see `IsGuaranteedStep`). Function / `lazy()` slots may resolve to
+ * nothing, and `null` / `undefined` (a literal absence or a
+ * `cond ? form : null` union) is an explicit drop, so none of those
+ * prove non-emptiness; a tuple of only maybe-absent slots stays
+ * honestly `| undefined`.
+ *
+ * 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 [infer First, ...infer Rest] ? IsGuaranteedStep<First> extends true ? true : StaticallyNonEmpty<Rest> : 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, schema-erased to `UseFormReturnType<GenericForm>`
+ * and narrowed to non-`undefined` when `S` is statically safe. The runtime
+ * value is a live facade over the active step, so reads (`.values`, `.meta`,
+ * `.history`) and `.handleSubmit` always target the current step. Values are
+ * loose here because the active step's schema is not statically known; reach
+ * for the original form ref or `ctx.get(ref)` when you need typed per-step
+ * values.
+ */
+type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? UseFormReturnType<GenericForm> : UseFormReturnType<GenericForm> | undefined;
+/**
+ * Per-slot contribution to {@link FormsRecordOf}. Strips a `null` /
+ * `undefined` (a literal absence or a `cond ? form : null` union) off the
+ * slot first, so a conditionally-present form still maps to its key and
+ * stays concretely typed on `wizard.forms`; a purely nullish slot
+ * contributes nothing.
+ */
+type SlotRecord<First, F = Exclude<First, null | undefined>> = [F] extends [never] ? unknown : F extends string ? {
+    readonly [P in F]: AnyForm;
+} : F extends {
+    readonly key: infer K extends string;
+} ? {
+    readonly [P in K]: F;
+} : unknown;
+/**
+ * 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. A form kept behind a `cond ? form : null`
+ *    conditional still maps to its key.
+ *  - **`null` / `undefined` slot**: contributes nothing.
+ *  - **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>
+] ? SlotRecord<First> & 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`  — a LIVE view of the active step's form. Operating
+ *                    through it always targets the current step, so a
+ *                    handler captured once at setup
+ *                    (`wizard.activeForm.handleSubmit(() =>
+ *                    wizard.next())`) retargets as the wizard advances.
+ *                    No longer `===` the raw per-step handle; reach for
+ *                    `wizard.forms[key]` when you need raw identity.
+ *                    Same `undefined` 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
+ *                    `handleSubmit` resolves without throwing AND leaves
+ *                    no errors set on any step, and stays `true` through
+ *                    subsequent edits or invalidations. A callback that
+ *                    calls `setErrors` and returns (the documented
+ *                    server-rejection path) is a failed submit, so it
+ *                    does not flip `done`. 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.
+ *  - `submitError` — the error THROWN by the most recent
+ *                    `wizard.handleSubmit` callback (or its `onError`),
+ *                    coerced to a real `Error`. Mirrors
+ *                    `form.meta.submitError`: this is the unexpected-throw
+ *                    channel, so an expected rejection handled via
+ *                    `setErrors` (no throw) surfaces through the error
+ *                    surface and `onError` instead, leaving this `null`.
+ *                    Cleared at submit entry and by `reset()`, parked here
+ *                    rather than re-thrown, so the handler resolves and
+ *                    never manufactures a `window` unhandledrejection.
+ *                    `null` on success.
+ *  - `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`.
+ *  - `tryNext()`   — validate the active step, then advance iff it
+ *                    passed; invalid input keeps the pin put under the
+ *                    form's standard error reveal (first error focused,
+ *                    display state advanced). The inline-bindable
+ *                    shorthand for `activeForm.handleSubmit(() =>
+ *                    next())`. Resolves to whether the pin moved. No-ops
+ *                    to `false` on a degenerate or final-step wizard
+ *                    (finish via `handleSubmit`).
+ *  - `handleSubmit(onSubmit, onError?)` — always validates the entire
+ *                    step list, from any step, and never advances the
+ *                    pin: on success it latches `done`; on any error it
+ *                    focuses the first failing step and fires `onError`
+ *                    with errors spanning every step. To gate advancing
+ *                    a step on its own validity, compose with the active
+ *                    form's submit: `activeForm.handleSubmit(() =>
+ *                    wizard.next())`. 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 WizardAggregateError[]>>;
+    readonly progress: number;
+    readonly canAdvance: boolean;
+    readonly canGoBack: boolean;
+    readonly complete: boolean;
+    readonly done: boolean;
+    readonly submitting: boolean;
+    readonly submissionAttempts: number;
+    readonly submitError: Error | null;
+    readonly visited: readonly FormKey[];
+    readonly next: () => Promise<void>;
+    readonly back: () => void;
+    readonly goTo: (key: string) => void;
+    readonly tryNext: () => Promise<boolean>;
+    readonly handleSubmit: (onSubmit: WizardOnSubmit, onError?: WizardOnError) => (event?: Event) => Promise<void>;
+    readonly reset: () => void;
 };
 
 /**
@@ -1484,218 +1635,67 @@ type AttaformRegistry = {
      */
     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 yet). A dev-mode warning points at the
- * call site, lists the registered keys, and flags the mount-timing case
- * (a form created by a child or sibling isn't registered until its own
- * setup runs). 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.
+     * 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 function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
-
+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;
+};
 /**
- * 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.
+ * 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).
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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;
 /**
- * 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).
+ * Look up a Vue app's registry by `App` reference. Used by
+ * SSR helpers (`renderAttaformState`, `hydrateAttaformState`) that
+ * run outside a component setup context.
  *
- * 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.
+ * Throws `RegistryNotInstalledError` when the app hasn't been wired
+ * with `createAttaform()`.
  */
-type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined>;
-declare function useRegister<V = unknown>(): UseRegisterReturn<V> | undefined;
+declare function getRegistryFromApp(app: App): AttaformRegistry;
 
 /**
  * Multistep-form orchestrator built around an ordered list of step slots.
@@ -1880,8 +1880,406 @@ declare const AttaformErrorCode: {
      * Override it per error by passing your own `code` (`api:…`, `auth:…`).
      */
     readonly UserError: "atta:user-error";
+    /**
+     * Stamped on a `ValidationError` synthesized from a throw or rejection
+     * out of a `handleSubmit` `onSubmit` callback. The raw error also lands
+     * on `form.meta.submitError` (a raw-`Error` inspection channel); this
+     * code marks the copy piped into the user-error layer so the failure
+     * also surfaces on `form.errors` / `meta.ownErrors` / `firstOwnError`
+     * where the UI already reads. A throw carrying its own `path` / `code`
+     * keeps them; a bare `Error` or a non-Error throw defaults here at the
+     * form-level path `[]`.
+     */
+    readonly SubmitError: "atta:submit-error";
 };
 type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
 
-export { AttaformErrorCode as c, 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, WizardAggregateError as W, SerializedFormData as a, AnyForm as b, StepSlot as d, UseWizardReturnType as e, WizardCtx 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 };
+/**
+ * Options for `createAttaform()`.
+ */
+type AttaformPluginOptions = SSRDetectOptions & {
+    /**
+     * Whether to install the Vue DevTools integration. Default `true`.
+     * The integration is dev-only: the `import('./devtools')` sits behind
+     * the `__DEV__` flag, so a consumer's production build folds it out
+     * entirely (no devtools chunk shipped, no fetch attempted). In
+     * development the DevTools peer is loaded lazily and a missing peer
+     * fails silently. Pass `false` to skip the integration even in dev.
+     */
+    devtools?: boolean;
+    /**
+     * App-level defaults applied to every `useForm` call in this app.
+     * Per-form options always win. See `AttaformDefaults` for
+     * the supported option set and the merge rules.
+     *
+     * ```ts
+     * app.use(
+     *   createAttaform({
+     *     defaults: { debounceMs: 100 },
+     *   })
+     * )
+     * ```
+     */
+    defaults?: AttaformDefaults;
+};
+/**
+ * Create the Vue plugin that installs the form library on a Vue
+ * application. Required only when you want app-wide options
+ * (`defaults`, `devtools: false`, `ssr: true`) — for the default
+ * setup, `useForm` / `injectForm` / `useRegister` lazy-install the
+ * registry on first use.
+ *
+ * ```ts
+ * import { createApp } from 'vue'
+ * import { createAttaform } from 'attaform'
+ *
+ * createApp(App)
+ *   .use(createAttaform({ defaults: { debounceMs: 100 } }))
+ *   .mount('#app')
+ * ```
+ *
+ * Under SSR with bare Vue 3, install explicitly with `{ ssr: true }`
+ * from your server entry — the SSR serialization helpers
+ * (`renderAttaformState` / `hydrateAttaformState`) require an
+ * already-attached registry and don't trigger lazy install. Under
+ * Nuxt, install via `attaform/nuxt` instead — the Nuxt module wires
+ * both server and client automatically.
+ *
+ * Installing more than once on the same app is a no-op (the second
+ * call logs a dev-mode warning).
+ */
+declare function createAttaform(options?: AttaformPluginOptions): Plugin;
+
+/**
+ * Serialised snapshot of every form in a Vue app, produced by
+ * `renderAttaformState` and consumed by `hydrateAttaformState`.
+ *
+ * JSON-safe — pass to `JSON.stringify`, `devalue`, or any other
+ * serialiser before embedding in your SSR payload.
+ */
+type SerializedAttaformState = {
+    /** Tuples of `[formKey, snapshot]` for every form in the app. */
+    readonly forms: ReadonlyArray<readonly [FormKey, SerializedFormData]>;
+};
+/**
+ * Snapshot every form on a Vue app for SSR. Call from your server
+ * entry after rendering the app:
+ *
+ * ```ts
+ * import { renderToString } from '@vue/server-renderer'
+ * import { renderAttaformState, escapeForInlineScript } from 'attaform'
+ *
+ * const html = await renderToString(app)
+ * const state = renderAttaformState(app)
+ * const payload = escapeForInlineScript(JSON.stringify(state))
+ *
+ * return `
+ *   ${html}
+ *   <script>window.__ATTAFORM_STATE__ = ${payload}</script>
+ * `
+ * ```
+ *
+ * Pair with `hydrateAttaformState` on the client to restore the
+ * forms in their server-rendered state. Nuxt users don't need this —
+ * `attaform/nuxt` wires SSR automatically.
+ */
+declare function renderAttaformState(app: App): SerializedAttaformState;
+/**
+ * Restore forms from a server-rendered snapshot on the client. Call
+ * from your client entry before mounting:
+ *
+ * ```ts
+ * import { createApp } from 'vue'
+ * import { createAttaform, hydrateAttaformState } from 'attaform'
+ *
+ * const app = createApp(App).use(createAttaform())
+ * hydrateAttaformState(app, window.__ATTAFORM_STATE__)
+ * app.mount('#app')
+ * ```
+ *
+ * The next `useForm({ key })` call for each serialised form picks up
+ * the snapshot transparently — no further action is required.
+ */
+declare function hydrateAttaformState(app: App, payload: SerializedAttaformState): void;
+
+/**
+ * Escape a JSON string so it's safe to embed inside an inline
+ * `<script>` tag during SSR. Plain `JSON.stringify` is not safe — a
+ * form value containing the literal substring `</script>` would
+ * break out of the script tag.
+ *
+ * ```ts
+ * const payload = escapeForInlineScript(JSON.stringify(renderAttaformState(app)))
+ * // `<script>window.__ATTAFORM_STATE__ = ${payload}</script>` is safe.
+ * ```
+ *
+ * Output remains valid JSON — `JSON.parse` round-trips back to the
+ * original value on the client.
+ */
+declare function escapeForInlineScript(json: string): string;
+
+/**
+ * Symbol slot used by custom directive integrations to install an
+ * assigner on the bound element. Read by the v-register directive
+ * when a DOM event fires:
+ *
+ * ```ts
+ * import { assignKey } from 'attaform'
+ * el[assignKey] = (value) => myCustomWriter(value)
+ * ```
+ *
+ * Most consumers never need this — the built-in directives wire
+ * default assigners for text inputs, checkboxes, radios, and selects.
+ */
+declare const assignKey: unique symbol;
+
+/**
+ * The `v-register` directive. Bind a form field to a native input,
+ * select, textarea, checkbox, or radio:
+ *
+ * ```vue
+ * <input v-register="form.register('email')" />
+ * <select v-register="form.register('country')">
+ *   <option value="us">US</option>
+ *   <option value="uk">UK</option>
+ * </select>
+ * ```
+ *
+ * The directive picks the right binding strategy automatically based
+ * on the element's `tagName` and `type`. Registered globally by
+ * `createAttaform()`. Most consumers never import it directly, but
+ * it's exposed for advanced integrations that wire directives
+ * manually.
+ */
+declare const vRegister: RegisterModelDynamicCustomDirective;
+
+/**
+ * Type guard for a `RegisterValue`. Returns `true` when `val` looks
+ * like the object returned from `form.register(path)`.
+ *
+ * ```ts
+ * if (isRegisterValue(slotValue)) {
+ *   // slotValue.innerRef is now a Ref<unknown>
+ * }
+ * ```
+ *
+ * Useful when building wrapper components that accept either a
+ * `RegisterValue` or a plain ref via the same prop.
+ */
+declare function isRegisterValue<Value = unknown>(val: unknown): val is RegisterValue<Value>;
+
+/**
+ * Shared building blocks for Attaform's two devtools surfaces — the Vue
+ * DevTools (Chrome-extension) inspector wired up in `./devtools.ts`, and
+ * the Nuxt DevTools (overlay) panel wired up via `../../nuxt.ts` +
+ * `../pages/_attaform_devtools.vue`.
+ *
+ * Houses the window-bridge contract both surfaces consume so a new
+ * bridge field lands in one file. Both surfaces render RAW form values
+ * by design — DevTools is a dev-only surface, and redaction across every
+ * place a value surfaces is impractical security theater rather than a
+ * real safeguard.
+ */
+
+/**
+ * Property key on `window` that the Nuxt-side dev plugin attaches the
+ * bridge object to. The iframe-mounted overlay panel reads
+ * `window.parent[DEVTOOLS_WINDOW_KEY]` to reach the host app's registry.
+ *
+ * Underscored + namespaced to make accidental collision with consumer
+ * globals vanishingly unlikely. Stable across versions — bumping it
+ * would silently disconnect older library builds from newer overlay
+ * panels in the same browser tab during a library upgrade.
+ */
+declare const DEVTOOLS_WINDOW_KEY = "__attaform_devtools__";
+/**
+ * Shape of the object the host plugin attaches to `window` in dev mode.
+ * The iframe overlay panel reads this to discover the live registry and
+ * render its forms.
+ *
+ * Single-registry assumption: the latest `createAttaform()` install
+ * wins. Multi-app pages (rare; typically only seen in micro-frontend
+ * setups) will only see one app's forms in the panel. Documented but
+ * not actively supported — the alternative (a Set of registries with
+ * union-rendering) is a future call if a real consumer hits it.
+ */
+interface AttaformDevtoolsBridge {
+    registry: AttaformRegistry;
+    /**
+     * The library version, surfaced in the panel's footer for support /
+     * bug-report context. Read from `package.json` at host-plugin init.
+     */
+    version: string;
+}
+declare global {
+    interface Window {
+        [DEVTOOLS_WINDOW_KEY]?: AttaformDevtoolsBridge;
+    }
+}
+
+/**
+ * Typed error classes thrown by the form library. Each one signals a
+ * distinct misuse so calling code can branch on `instanceof` instead
+ * of pattern-matching error messages.
+ *
+ * Every class extends `AttaformError`, so consumers can write a single
+ * polymorphic catch (`catch (e) { if (e instanceof AttaformError) ... }`)
+ * instead of OR-chaining checks for each subclass. `AttaformError` itself
+ * extends the standard `Error`, so existing `instanceof Error` usage
+ * keeps working.
+ */
+
+/**
+ * Base for every error class thrown by `attaform`. Sets
+ * `this.name` from the constructor's `new.target.name`, so subclasses
+ * don't have to redeclare their own name override.
+ */
+declare class AttaformError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a path string is malformed — typically a dotted path
+ * with empty segments (e.g. `'a..b'`, leading or trailing dots).
+ * Use array form (`['a', 'b']`) for keys that contain literal dots.
+ */
+declare class InvalidPathError extends AttaformError {
+}
+/**
+ * Thrown when `useForm` receives an invalid configuration — most often
+ * a schema passed directly as the first argument, or no argument at
+ * all. The configuration is an options bag; the schema is one of
+ * several fields, even when it's the only one in use.
+ *
+ * ```ts
+ * // ✗ Crashes deep inside the validator with an opaque message:
+ * const form = useForm(z.object({ ... }))
+ * // ✗ Same:
+ * const form = useForm()
+ * // ✓ Pass the schema as the `schema` field:
+ * const form = useForm({ schema: z.object({ ... }) })
+ * ```
+ *
+ * The same shape applies to every entry point: `attaform/zod`,
+ * `attaform/zod-v3`, `attaform/zod-v4`, and the schema-agnostic
+ * `attaform` root.
+ */
+declare class InvalidUseFormConfigError extends AttaformError {
+    constructor();
+}
+/**
+ * Thrown when a `handleSubmit`-supplied `onError` callback itself
+ * throws or rejects. Wraps the inner failure so both the original
+ * cause (via `error.cause`) and the propagation site are visible.
+ */
+declare class SubmitErrorHandlerError extends AttaformError {
+}
+/**
+ * Thrown when an `attaform` API needs the registry attached to a Vue
+ * app but it isn't there yet. Component-level entry points (`useForm`,
+ * `injectForm`, `useRegister`) lazy-install the registry on first use,
+ * so this error is mostly reached by SSR helpers — `renderAttaformState`
+ * and `hydrateAttaformState` — which run outside a setup context and
+ * have no current instance to install against.
+ *
+ * Fix: add `app.use(createAttaform())` (or `app.use(createAttaform({
+ * ssr: true }))` on the server) to your SSR entry, before
+ * `renderToString` / hydration. Under Nuxt, `attaform/nuxt` already
+ * does this; the error usually points at a non-Nuxt SSR setup that
+ * hasn't installed explicitly.
+ */
+declare class RegistryNotInstalledError extends AttaformError {
+    constructor();
+}
+/**
+ * Thrown when `useForm` / `injectForm` is called outside of a
+ * Vue `setup()` function — typically from an event handler, watcher,
+ * or async callback that runs after mount.
+ *
+ * Fix: move the call into `setup()`, or trigger it from a child
+ * component whose `setup()` runs the composable.
+ */
+declare class OutsideSetupError extends AttaformError {
+    constructor();
+}
+/**
+ * Thrown when a `useForm({ key })` call uses a key starting with
+ * `__atta:`. That prefix is reserved for keys the library generates
+ * internally (e.g. for anonymous `useForm()` calls without an
+ * explicit key). Pick a different prefix for your form.
+ */
+declare class ReservedFormKeyError extends AttaformError {
+    constructor(key: string);
+}
+
+/**
+ * Anti-flash timing for the library-default display reducer.
+ *
+ * - `showDelay` — how long in-flight work (a validation run or an async
+ *   register transform) may run before its spinner is allowed to show. Work
+ *   that settles inside this window never reveals `'pending'` at all, so a
+ *   fast (often synchronous) check does not flash a spinner on every keystroke.
+ * - `minVisible` — once shown, the minimum time the spinner stays up. Work
+ *   that lands just past `showDelay` is held here so the spinner does not
+ *   itself flash on and immediately off.
+ *
+ * Both are milliseconds.
+ */
+type DisplayTimings = {
+    readonly showDelay: number;
+    readonly minVisible: number;
+};
+/**
+ * Library-default anti-flash timings. `showDelay: 120` cleanly swallows
+ * synchronous, microtask-resolved, and tiny-async work (validation runs and
+ * async register transforms alike) so none of them flash a spinner;
+ * `minVisible: 120` keeps a shown spinner snappy once one does land.
+ * Retune via {@link makeDefaultDisplayState} without touching the engine.
+ */
+declare const DEFAULT_TIMINGS: DisplayTimings;
+/**
+ * Build a default `getDisplayState` reducer with custom anti-flash timing.
+ * Power users who want a tighter or looser spinner than {@link DEFAULT_TIMINGS}
+ * pass their own `{ showDelay, minVisible }`:
+ *
+ * ```ts
+ * import { makeDefaultDisplayState } from 'attaform'
+ *
+ * useForm({
+ *   schema,
+ *   getDisplayState: makeDefaultDisplayState({ showDelay: 50, minVisible: 200 }),
+ * })
+ * ```
+ *
+ * The returned reducer is pure: the engine injects `now` and threads the
+ * previous machine, so the same `(prev, ctx)` always yields the same next
+ * machine. It shapes only the display projection — `errors`, `valid`,
+ * `validating`, and the underlying validation run exactly as before.
+ */
+declare function makeDefaultDisplayState({ showDelay, minVisible, }: DisplayTimings): GetDisplayState;
+/**
+ * Library-default `getDisplayState` reducer. Resolves every path's
+ * `field.displayState` — and thus `field.show*` and the `form.meta`
+ * rollups — whenever the consumer has not configured an override at the
+ * per-form or plugin level. Built from {@link DEFAULT_TIMINGS}; publicly
+ * re-exported so an override can compose with it (a layered reducer that
+ * special-cases a subtree but otherwise defers picks up future
+ * refinements for free):
+ *
+ * ```ts
+ * import { defaultDisplayState } from 'attaform'
+ *
+ * useForm({
+ *   schema,
+ *   getDisplayState: (prev, ctx) => {
+ *     const next = defaultDisplayState(prev, ctx)
+ *     return next.display === 'success' && ctx.field.path[0] === 'username'
+ *       ? { display: 'idle' }
+ *       : next
+ *   },
+ * })
+ * ```
+ */
+declare const defaultDisplayState: GetDisplayState;
+
+export { useWizard as $, createRegistry as B, DEFAULT_TIMINGS as D, defaultCoercionRules as E, defaultDisplayState as G, defineCoercion as H, escapeForInlineScript as J, getRegistryFromApp as K, hydrateAttaformState as M, injectForm as N, OutsideSetupError as O, injectWizard as P, isRegisterValue as Q, RegistryNotInstalledError as R, kAttaformRegistry as T, lazy as V, makeDefaultDisplayState as X, renderAttaformState as Y, useRegister as Z, useRegistry as _, vRegister as a0, AttaformError as c, AttaformErrorCode as d, DEVTOOLS_WINDOW_KEY as f, InvalidPathError as h, InvalidUseFormConfigError as i, ReservedFormKeyError as j, SubmitErrorHandlerError as m, assignKey as y, createAttaform as z };
+export type { AttaformRegistry as A, CompiledStep as C, FormStatus as F, InjectWizardInput as I, LazyMarker as L, SerializedAttaformState as S, UseRegisterReturn as U, WizardAggregateError as W, AnyForm as a, AttaformDevtoolsBridge as b, AttaformPluginOptions as e, DisplayTimings as g, SerializedFormData as k, StepSlot as l, UseWizardReturnType as n, WizardCtx as o, WizardCtxForm as p, WizardOnError as q, WizardOnSubmit as r, WizardOptions as s, WizardPersistFn as t, WizardRestoreFn as u, WizardRestoreState as v, WizardStatusesProxy as w, WizardSubmitContext as x };