attaform 0.29.0 → 0.30.1

package/dist/shared/attaform.BcQwgWaq.d.mts

@@ -0,0 +1,2153 @@
+import { G as GenericForm, F as FormKey, a as UseFormReturnType, _ as RegisterValue, v as Path, w as PathKey, ar as DisplayCtx, as as GetDisplayState, at as DisplayMachine, au as FieldRecord, av as ErrorCell, ad as ValidationError, aw as OriginalsRecord, A as AbstractSchema, ah as WriteMeta, d as DeepPartial, ai as WriteShape, ax as AttaformDomBinding, ay as TransformAbortHolder } from './attaform.Br8EBn5B.mjs';
+import { Ref, ComputedRef, ShallowRef, App, InjectionKey, Plugin } from 'vue';
+
+/** Options accepted by `injectForm` in place of a bare key string. */
+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;
+};
+/**
+ * Reach an existing form from a descendant component without threading
+ * it through props. The counterpart to `useForm`: `useForm` creates and
+ * provides, `injectForm` looks up.
+ *
+ * ```ts
+ * // The nearest ancestor's anonymous useForm() call.
+ * const form = injectForm<SignupShape>()
+ *
+ * // A specific form by key, from anywhere in the app.
+ * const cart = injectForm<CartShape>('cart')
+ * ```
+ *
+ * A keyed call is a registry lookup, so it is independent of
+ * component-tree position. A no-key call takes the closest ambient
+ * ancestor and inherits its `formInstanceId`; only an anonymous
+ * `useForm()` fills that ambient slot, so a keyed form is reachable
+ * only by its key.
+ *
+ * Returns `null` when nothing matches, so narrow before use:
+ *
+ * ```ts
+ * const form = injectForm<Shape>('signup')
+ * if (!form) return
+ * form.register('email')
+ * ```
+ *
+ * A keyed miss warns in dev with the registered keys and the call site.
+ * Pass the `Form` generic explicitly, since Vue's provide/inject erases
+ * generics. The form stays alive for this component's lifetime and is
+ * cleaned up once every consumer has unmounted.
+ */
+declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
+
+/**
+ * Return type of `useRegister()`. Hybrid of `RegisterValue<V>` (so
+ * `rv.path` / `rv.segments` / `rv.formKey` etc. work directly in
+ * script setup) and `Ref<RegisterValue<V> | undefined>` (so Vue's
+ * template auto-unwrap surfaces the underlying RV to `v-register`
+ * and the directive's path-migration diff sees the real RV across
+ * renders).
+ *
+ * The two surfaces don't clash at the type level: `RegisterValue`
+ * doesn't carry a `value` field, and `Ref<T>`'s `value: T` becomes
+ * the hybrid's only `.value`. Older code that read `rv.value?.path`
+ * keeps working; new code can write `rv.path` directly.
+ */
+type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined> & {
+    /**
+     * Whether a parent has actually bound this wrapper. `false` until a
+     * `RegisterValue` lands, `true` once one has, and reactive in both
+     * directions: a parent that binds on a later render flips it, and
+     * so does one that stops binding.
+     *
+     * This is the test a dual-mode wrapper reaches for, and the reason
+     * it exists as a field rather than a truthiness check on the
+     * return: the composable cannot answer "is this bound" at setup
+     * time. A parent is free to bind on a later render
+     * (`v-register="ready ? form.register('x') : undefined"`), and
+     * `useRegister` has to keep serving that, so it can never return a
+     * plain `undefined` for "unbound right now". Script-setup code
+     * reading `rv` directly sees the hybrid Proxy, which is an object
+     * and therefore always truthy; a template sees the unwrapped ref,
+     * which IS `undefined` when unbound. `rv?.isBound` reads the same
+     * on both sides (#620).
+     */
+    readonly isBound: boolean;
+};
+/**
+ * Options for `useRegister`.
+ */
+type UseRegisterOptions = {
+    /**
+     * Declares that this wrapper is used both with and without a form, so
+     * a render with no parent binding is intended rather than a mistake.
+     * Silences the unbound diagnostic; nothing else changes.
+     *
+     * The diagnostic exists because a single-mode wrapper whose parent
+     * forgot `v-register` renders a field that looks fine and stores
+     * nothing, which is an expensive afternoon. Once a wrapper is
+     * deliberately dual-mode, the same signal fires on correct code and
+     * tells the author to do something wrong, so this is the one fact
+     * that separates the two cases and only the author has it (#620).
+     *
+     * Pair it with `rv?.isBound` to branch on what actually happened.
+     */
+    readonly optional?: boolean;
+};
+/**
+ * Re-bind a parent's `v-register` onto an inner native element. Use it
+ * inside a component that wraps a single form field whose root is NOT
+ * the input itself, such as 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()
+ * </script>
+ *
+ * <template>
+ *   <label class="field">
+ *     <span>Email</span>
+ *     <input v-register="rv" />
+ *   </label>
+ * </template>
+ * ```
+ *
+ * The return is a hybrid: `v-register="rv"` hands the directive the
+ * parent's own `RegisterValue`, and `rv.path` / `rv.segments` /
+ * `rv.formKey` / `rv.innerRef` read directly in script setup with no
+ * `.value` unwrap. Reads inside a `computed` or `watchEffect` re-run
+ * when the parent rebinds to a different path.
+ *
+ * When no parent bound, every field reads `undefined`, so reach for
+ * `rv?.path`. `v-register="rv"` is still safe. A wrapper that is meant
+ * to render both with and without a form declares it with
+ * `useRegister({ optional: true })` and branches on `rv?.isBound`.
+ *
+ * When the wrapper's root IS the input, Vue's attribute fallthrough
+ * already binds it and `useRegister` is unnecessary. For a wrapper
+ * that binds several fields, use `injectForm<Form>(key?)` and call
+ * `ctx.register(...)` directly.
+ */
+declare function useRegister<V = unknown>(options?: UseRegisterOptions): UseRegisterReturn<V> | undefined;
+
+type DynamicPathSweep = {
+    /**
+     * Note that a cache has just stored an entry for `segments` under
+     * `key`. Paths a schema shape bounds are ignored, so only the
+     * candidates the sweep could ever drop are walked.
+     */
+    readonly track: (segments: Path, key: PathKey) => void;
+    /**
+     * Register a cache's own eviction. It receives the canonical
+     * `PathKey` of a path the form no longer has, and deletes whatever it
+     * files under that path. A cache keying by more than the path (a
+     * shape sigil, say) deletes every variant; a key it never held is a
+     * no-op.
+     */
+    readonly onEvict: (evict: (key: PathKey) => void) => void;
+};
+
+/**
+ * Per-form display engine: owns the clock and the timers the display
+ * reducer's timing 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.
+ *
+ * The `setTimeout` invariants on a returned `reviewAt` are enforced here
+ * rather than trusted from the reducer. A non-finite deadline is ignored
+ * instead of 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 a deadline it just fired
+ * that has also already passed. That last one is load-bearing, not
+ * belt-and-braces: Attaform's own reducer re-emits ONE fixed instant for
+ * the length of a min-visible hold, which is exactly the shape that can
+ * strand a field on `'pending'` forever (see `rearm`).
+ *
+ * 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, with 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. Dev builds only. */
+    size?(): number;
+    /** Introspection for tests: whether a path has a retained machine. Dev builds only. */
+    has?(key: PathKey): boolean;
+    /** Introspection for tests: whether a deadline timer is armed. Dev builds only. */
+    hasTimer?(): boolean;
+};
+
+/**
+ * The error stores, indexed by path prefix.
+ *
+ * `aggregateErrorsAt(state, prefix)` answers "every active error at or
+ * under this path". Scanning all three stores per call makes a table's
+ * reads O(rows x errors) where the answer is O(errors), so keys are
+ * collected once per change, resolved to segments once and sorted, and
+ * a query binary-searches its own window.
+ *
+ * A `PathKey` is `JSON.stringify(segments)`, which is what makes a
+ * sorted array enough. Every key under `["rows",0]` begins
+ * `["rows",0,`: the parent's key minus its closing bracket, plus a
+ * comma. Call that the marker. Every descendant is >= the marker, and
+ * every descendant is <= the parent's own key, because the two agree
+ * up to the last character and `,` (0x2C) sorts before `]` (0x5D). So
+ * `[marker, parentKey]` is a contiguous window holding every
+ * descendant and the parent itself.
+ *
+ * The window is a SUPERSET: callers still apply `isPathPrefix`, so this
+ * encoding argument cannot quietly become the definition of a prefix.
+ * The root has no marker (`[,` begins nothing) and matches everything,
+ * so it is answered with the whole index.
+ */
+
+/** One indexed path: its key, and the segments that key decodes to. */
+type ErrorPathEntry = {
+    readonly key: PathKey;
+    readonly segments: Path;
+};
+
+/**
+ * The per-form kernel each `useForm` call owns: form value, field records,
+ * element references, the error stores and the submission, validation and
+ * transform lifecycles, all keyed by `(formKey, path)` so two forms cannot
+ * collide over shared DOM state.
+ *
+ * Not a singleton. Every `useForm` call builds one; the registry supplies SSR
+ * hydration, and otherwise the state is per component per form.
+ */
+type FormStore<F extends GenericForm, G extends GenericForm = F> = {
+    /**
+     * The form's single liveness sweep over every per-path cache. It lives on
+     * the store, not on `buildFormApi`, because the store's own maps (`fields`,
+     * `originals`, `authoredPaths`, `fieldValidationState`) are the largest
+     * thing it evicts and they exist whether or not a form API was ever built
+     * around them. Read surfaces register their evictions into it, so one
+     * subscription and one walk serve all of them. See `dynamic-path-sweep.ts`.
+     */
+    readonly pathSweep: DynamicPathSweep;
+    readonly formKey: FormKey;
+    readonly form: Ref<F>;
+    readonly fields: Map<PathKey, FieldRecord>;
+    /**
+     * The tagged error store: one cell per error-bearing path, each segregating
+     * its two sources. The `schema` side is written only by the validation
+     * pipeline (`scheduleFieldValidation`, `handleSubmit`, the construction
+     * seed, history restore, hydration) and cleared by `reset` / `resetField`
+     * and a successful submit. The `user` side is written only by `setErrors` /
+     * `clearErrors` (plus history / hydration replay) and survives both schema
+     * revalidation and a successful submit, so the consumer owns its lifetime.
+     * A key exists iff a side is non-empty, and cells are replaced rather than
+     * mutated so Vue's per-key Map tracking fires for either side. Derived blank
+     * entries are not stored here; they synthesize at read
+     * (`derivedBlankErrors`).
+     */
+    readonly errorCells: Map<PathKey, ErrorCell>;
+    /**
+     * Reactively-derived "No value supplied" errors: a pure function of
+     * `(blankPaths, schema.isRequiredAtPath)` with no writers and no clears.
+     * Membership follows `blankPaths`, so typing into a blank required numeric
+     * field makes the error vanish and clearing the input brings it back. The
+     * `errors` proxy and `getErrorsForPath` merge this alongside the schema and
+     * user sides, so the "this required field is empty" error is true the moment
+     * it is true, with no `validate()` / `handleSubmit` call.
+     *
+     * Most entries are `number` / `bigint` leaves, where the side channel is the
+     * only way to tell "user typed 0" from "user supplied nothing". String and
+     * boolean leaves land here only when the consumer opts in with the `unset`
+     * sentinel. See `docs/validation/blank.md`.
+     */
+    readonly derivedBlankErrors: ComputedRef<ReadonlyMap<PathKey, ValidationError[]>>;
+    /**
+     * Every path carrying an error at or under `prefix`, sorted by key.
+     * `aggregateErrorsAt` takes its candidates from here rather than rescanning
+     * all three error stores per call, which is what keeps a table of N rows at
+     * O(errors) instead of O(N x errors). See `error-path-index.ts`.
+     *
+     * Going through this rather than the form-global index is also what isolates
+     * containers from each other: the index is one value for the whole form, so
+     * any path gaining or losing an error gives it a fresh identity. Each prefix
+     * gets a memoised `computed` that hands back its previous array when its own
+     * window is unchanged, so the global change stops there. See `errorWindowAt`.
+     */
+    readonly errorWindowAt: (prefix: Path, prefixKey: PathKey) => readonly ErrorPathEntry[];
+    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
+     * records storage / display divergence, the case where storage alone cannot
+     * tell "user typed 0" from "user supplied nothing".
+     *
+     * `number` / `bigint` are the reason it exists: storage holds `0` / `0n`
+     * while the DOM input shows `''`, so the directive's input listener marks
+     * the path on clear. Strings and booleans need no mark (`''` storage is `''`
+     * display, `false` is unchecked), so they are never auto-marked. Consumers
+     * can still mark any primitive leaf through the `unset` sentinel
+     * (`defaultValues: { x: unset }`, `setValue('x', unset)`,
+     * `reset({ x: unset })`), where the mark is declared intent rather than
+     * runtime inference.
+     *
+     * Reads (the `displayValue` computed, `fields.<path>.blank`,
+     * `derivedBlankErrors`) track through Vue's reactive Set handlers; writes
+     * happen in `setValueAtPath` (`blank: true` meta adds, any other write
+     * removes) and `reset`.
+     *
+     * Storage never reflects this set: reads against `form.value` see the slim
+     * default. It is a display / intent channel that `derivedBlankErrors`
+     * consults. See `docs/validation/blank.md`.
+     */
+    readonly blankPaths: Set<PathKey>;
+    /**
+     * Snapshot of `blankPaths` taken at construction and re-taken on
+     * `reset(args)`. Dirty calculation compares against it, so a path whose
+     * membership diverges is dirty even when storage matches the original.
+     * Populated eagerly, so there is no "dirty on first read" window.
+     */
+    readonly originalBlankPaths: Set<PathKey>;
+    readonly schema: AbstractSchema<F, G>;
+    /**
+     * Server-side flag, plumbed in from `registry.ssr`.
+     * `markConnectedOptimistically()` reads it before flipping
+     * `connected: true`; on the client it is a no-op, leaving the directive
+     * lifecycle as the source of truth.
+     */
+    readonly ssr: boolean;
+    /**
+     * Per-form display engine. It owns the clock and the single timer the timed
+     * display policy needs, which is what keeps the reducer a pure
+     * `(prev, ctx) => next`. 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. Torn down through `registerCleanup` on 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
+     * and leaves `submitted` at `false`. Cleared by `reset()`.
+     */
+    readonly submitted: Ref<boolean>;
+    readonly submitError: Ref<Error | null>;
+    readonly departAttempts: Ref<number>;
+    /**
+     * Effective data-freeze state: `true` when either the form's own
+     * `disabled` config resolves truthy or `externalLock` is set. Read at
+     * the write chokepoint (`setValueAtPath`), the register value's
+     * `disabled`, and the field display predicate.
+     */
+    readonly effectiveDisabled: ComputedRef<boolean>;
+    /**
+     * Wizard-driven freeze channel. `useWizard` sets it `true` for a locked
+     * step's member form, and `effectiveDisabled` ORs it in, so a member form
+     * cannot escape the lock by passing `disabled: false`. Default `false`.
+     */
+    readonly externalLock: Ref<boolean>;
+    /**
+     * `true` while a function-form `defaultValues` factory is in flight, and
+     * always `false` for plain-value `defaultValues`. Shared across every
+     * `useForm({ key })` call resolving to this store, so 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, the server path
+     * where `activate()` must enqueue intent before deciding whether to fire.
+     * `buildFormApi` uses it to skip the lazy activation gate for forms with
+     * neither a factory nor a prefetch, the common client case where `gated()`
+     * is pure overhead on every public method call.
+     */
+    readonly hasSsrPrefetch: boolean;
+    /**
+     * `true` once the form's effective defaults have been applied, whether from
+     * a sync `defaultValues` at construction or an async factory that settled.
+     * Stays `false` for a dormant lazy form until it activates. `useWizard`
+     * reads it to decide between surfacing seed status and live meta.
+     */
+    readonly defaultsResolved: Ref<boolean>;
+    /**
+     * `true` once the captured async factory has been kicked off, set
+     * synchronously by `activate()` before the factory resolves. Paired with
+     * `defaultsResolved` (which flips only on settle) so the API surface can
+     * tell "started" from "done".
+     */
+    readonly activated: Ref<boolean>;
+    /**
+     * In-flight activation promise. Concurrent callers (cross-component SSR
+     * consumers, recursive factory reads, parallel `activate()` calls) all
+     * receive this one, so the factory runs once under contention.
+     */
+    readonly activationPromise: Ref<Promise<void> | undefined>;
+    /**
+     * Idempotent activation entrypoint. Fires the captured function-form
+     * `defaultValues` factory on the first call and publishes the in-flight
+     * promise; later calls return that promise until it settles and
+     * `Promise.resolve()` afterwards. A plain-value form always resolves
+     * immediately. Every public getter and method except `key` routes through
+     * here, so the form activates on first use.
+     */
+    activate(): Promise<void>;
+    /**
+     * Re-fire the captured function-form `defaultValues` factory. Throws
+     * synchronously on a plain-value form, where no factory was captured.
+     * Resolves once `hydrating` is back to `false`, so `await form.rehydrate()`
+     * can gate UI on the fresh load.
+     *
+     * Leaves touched / submit state alone; chain `form.reset()` for a clean
+     * surface. It does re-seat the defaults (see `adoptResolvedDefaults`), so
+     * afterwards dirty means "differs from what the factory just returned" and
+     * `form.reset()` lands on the fresh values instead of discarding them.
+     */
+    rehydrate(): Promise<void>;
+    /**
+     * Adopt a resolved async-defaults value as the form's durable defaults and
+     * re-seed the dirty baseline from it. Called by the activate / rehydrate
+     * orchestrator once its factory settles. It hangs off the store rather than
+     * being imported because `form-activation` imports this module, and a value
+     * import back the other way would close a cycle.
+     */
+    adoptResolvedDefaults(value: unknown): void;
+    /**
+     * Incremented by every `reset()`. The submit wrapper captures it at entry
+     * and skips writing `submitError` from a catch that fires after a reset,
+     * which is what stops a reset-during-submit clearing `submitError` only for
+     * it to reappear when the in-flight promise rejects.
+     */
+    readonly submissionGeneration: Ref<number>;
+    /**
+     * Counts in-flight validation calls across every `validate()` ref and every
+     * committing `parse(...)` / `handleSubmit` pre-check; public `validating`
+     * mirrors `> 0`. Separate from the submission counters because a debounced
+     * field check overlapping a submit must show the union of both.
+     */
+    readonly activeValidations: Ref<number>;
+    /**
+     * `true` once the form has completed at least one validation pass, flipping
+     * when `activeValidations` returns to 0 from a positive value. Until then
+     * `meta.valid` and `field.valid` report `false` even with an empty schema
+     * side, because no errors at frame 1 means "not checked yet", not "checked
+     * and clean".
+     *
+     * The window it closes: where the slim default-derivation parse strips
+     * refinements (`.refine`, `.superRefine`, async validators) the slim parse
+     * passes, no construction errors land, and the queued microtask has not run,
+     * so frame 1 would paint the form valid a tick before the real verdict.
+     *
+     * `reset()` restores it to the same construction-time seed, so the post-reset
+     * window gates exactly like the post-mount one.
+     */
+    readonly firstValidationDone: Ref<boolean>;
+    /**
+     * Async-gate verdict for a path whose canonical key the caller already
+     * holds. `key` is required and must correspond to `segments`; skipping the
+     * `canonicalizePath` round-trip is what lets a descendant walk, whose Map
+     * iteration already yields the key, avoid a canonicalize per leaf.
+     */
+    pathHasAsyncValidationByKey(key: PathKey, segments: Path): boolean;
+    /**
+     * Per-path counter of in-flight field-level validation runs;
+     * `FieldState.validating` mirrors `> 0`. Incremented and decremented in
+     * lockstep with `activeValidations` inside `scheduleFieldValidation`'s `run`
+     * closure, so the two are co-extensive on the field-scheduled branch.
+     * Whole-form `validate()` / `parse()` runs have no single path and touch
+     * only `activeValidations`.
+     *
+     * A counter rather than a Set because two runs at one path can overlap: an
+     * aborted run's `.finally` lands after its replacement's increment, and
+     * `> 0` keeps the field validating across that boundary.
+     *
+     * Reactive Map, so `.get()` / `.has()` / `.size` track per key and a
+     * FieldState computed re-runs only for its own key.
+     */
+    readonly fieldValidationCounts: Map<PathKey, number>;
+    /**
+     * Per-path `Date.now()` stamp for the start of the field's latest validation
+     * run, re-anchored on every run start and deleted on the edge back to 0. The
+     * display reducer reads it as `ctx.validatingSince` and times the anti-flash
+     * spinner off `now - validatingSince`.
+     *
+     * Re-anchoring per run, not per streak, is the point: a burst of keystrokes
+     * keeps pushing the stamp forward and the spinner stays suppressed until the
+     * user pauses. Anchoring at the streak start would pin it to the first
+     * keystroke, because at `debounceMs: 0` an aborted run's decrement lands
+     * after the next run's increment and the count never reaches 0 between fast
+     * keystrokes. The container walk takes the descendant minimum, so a row
+     * spinner anchors at its earliest still-active leaf.
+     *
+     * Reactive, and that is load-bearing: the display computed reads this stamp
+     * but not the `validating` flag, and a long run that settles on an unchanged
+     * verdict leaves `errors` / `valid` untouched. Without reactivity a held
+     * `pending` spinner would strand after the run ended, waiting on some
+     * unrelated change to re-run the computed. Runtime-only, never hydrated.
+     */
+    readonly fieldValidatingSince: Map<PathKey, number>;
+    /**
+     * Per-path counter of in-flight async-transform runs, the async branch of
+     * the `register({ transforms })` pipeline; `> 0` drives
+     * `field.transforming` / `field.busy`. A counter for the same overlap reason
+     * as `fieldValidationCounts`, except a superseding input releases the prior
+     * run synchronously first, so in practice the value is 0 or 1.
+     */
+    readonly fieldTransformCounts: Map<PathKey, number>;
+    /**
+     * Per-path `ssr ? 0 : Date.now()` stamp for the opening of the path's latest
+     * async transform, read by the display reducer as `ctx.transformingSince` to
+     * time the gated busy spinner. Mirrors `fieldValidatingSince` exactly, down
+     * to why it is reactive.
+     */
+    readonly fieldTransformingSince: Map<PathKey, number>;
+    /**
+     * Per-path latest async-transform failure, either a rejected transform or a
+     * resolved value the write gate refused, surfaced as `field.transformError`.
+     * Cleared when a fresh run opens at the path and on `reset()`. A channel of
+     * its own, separate from validation `errors`.
+     */
+    readonly transformErrors: Map<PathKey, Error | null>;
+    /**
+     * Form-wide count of in-flight async-transform runs, behind the
+     * `settleTransforms` quiescence guard and the `handleSubmit` drain barrier.
+     * Clamped at 0 on release, so a run's own late `endTransform` after a
+     * synchronous cancel cannot drive it negative.
+     */
+    readonly activeTransforms: Ref<number>;
+    /**
+     * Replace the form value wholesale. `meta` is forwarded to every
+     * `onFormChange` listener so each can decide whether this write is one it
+     * cares about, the way history tags a hydration replay.
+     */
+    applyFormReplacement(next: F, meta?: WriteMeta): void;
+    /**
+     * Set a single path's value. `meta` reaches listeners through
+     * `applyFormReplacement`; public `form.setValue` passes none.
+     *
+     * Returns `false` when the slim-primitive gate rejects the write, meaning
+     * the value's primitive shape does not match the schema's slim shape at the
+     * path. The store is unchanged in that case.
+     */
+    setValueAtPath(path: Path, value: unknown, meta?: WriteMeta): boolean;
+    getValueAtPath(path: Path): unknown;
+    /**
+     * Stable identity for the array element at `path`, the token the array
+     * engine maintains across structural mutations. Empty for anything that is
+     * not an array element (a record entry, a fixed-object field, a container,
+     * the root). Backs `FieldState.key`.
+     */
+    arrayElementKey(path: Path): string;
+    reset(nextDefaultValues?: DeepPartial<WriteShape<F>>): void;
+    resetField(path: Path): void;
+    setSchemaErrorsForPath(path: Path, errors: ValidationError[]): void;
+    setAllSchemaErrors(errors: readonly ValidationError[]): void;
+    clearSchemaErrors(path?: Path): void;
+    /**
+     * Replace the schema side under `path` with `errors`, keying each error by
+     * its OWN absolute path. The validation pipelines
+     * (`scheduleFieldValidation`, the committing parse, `handleSubmit`, `reset`)
+     * commit a parse result through here: entries missing from the new pass drop
+     * out of the subtree, and surviving keys update in place so insertion order
+     * holds. Pass `[]` for whole-form scope.
+     */
+    applySchemaErrorsForSubtree(path: Path, errors: ValidationError[]): void;
+    setAllUserErrors(errors: readonly ValidationError[]): void;
+    setUserErrorsForPath(path: Path, errors: readonly ValidationError[]): void;
+    clearUserErrors(path?: Path): void;
+    /**
+     * Rebuild the whole tagged store from a snapshot's `[key, cell]` entries,
+     * the history ring buffer's restore road. Entry arrays are cloned in so the
+     * snapshot stays detached from the live store, and a cell with both sides
+     * empty is skipped.
+     */
+    restoreErrorCells(entries: ReadonlyArray<readonly [PathKey, ErrorCell]>): void;
+    /**
+     * Merged read of the cell at `path`, in schema -> blank -> user order:
+     * structural validation first, the synthesized blank entry between, user
+     * entries last. Same order as `getFirstErrorElement` and the top-level
+     * `errors` proxy iterate in.
+     */
+    getErrorsForPath(path: Path): ValidationError[];
+    /**
+     * A stable schema-declaration ordinal for `key`, assigned on first sight.
+     * `form.meta.errors` sorts by it, so the aggregate is a function of the SET
+     * of errors present rather than of the order their Map keys were last `set`.
+     * The construction seed walks every leaf of the schema's slim default;
+     * runtime paths (a second DU variant, a dynamic array index, a refine
+     * targeting a cross-field path) take first-encounter ordinals and keep them
+     * for the form's lifetime.
+     */
+    ensurePathOrdinal(key: PathKey): number;
+    /**
+     * The store's DOM slice, `null` until the directive cluster or `useRegister`
+     * arms it through `RegisterValue.ensureDomBinding`. Element registration,
+     * host anchors and first-error focus resolution live behind it; eager
+     * readers treat `null` as an empty registry.
+     */
+    readonly domBinding: ShallowRef<AttaformDomBinding | null>;
+    /**
+     * Field-record connect transition, driven by the DOM binding on element
+     * attach or host connect, and by the SSR-only
+     * `markConnectedOptimistically`. Sets `connected: true` and lifts
+     * `focused` / `blurred` from `null` to optimistic booleans only while they
+     * are null, so a boolean from an early focus event is never clobbered.
+     */
+    noteDomConnected(path: Path): void;
+    /**
+     * Field-record disconnect transition, driven by the DOM binding when a
+     * path's last element detaches or its host disconnects. `connected: false`,
+     * and `focused` / `blurred` back to `null`, since those describe an element
+     * that no longer exists. Interaction history stays.
+     */
+    noteDomDisconnected(path: Path): void;
+    /**
+     * `meta.instance` carries per-`useForm()`-instance overrides for
+     * `validateOn` / `debounceMs`, so the blur trigger honours the caller's own
+     * config when sibling instances share a FormStore.
+     */
+    markFocused(path: Path, focused: boolean, meta?: {
+        readonly instance?: WriteMeta['instance'];
+    }): void;
+    /**
+     * Flip the sticky `interacted` bit on a leaf. Driven by the directive's
+     * input listeners through `RegisterValue.markInteracted`. Idempotent, and
+     * never set by a programmatic write.
+     */
+    markInteracted(path: Path): void;
+    /**
+     * Walk every active-variant leaf under `segments` and flip `touched: true`.
+     * Powers `form.touch(path?)`. Idempotent, and touches neither value nor
+     * `focused` / `blurred`, nor does it trigger validation.
+     */
+    touchAtPath(segments: Path): void;
+    /**
+     * Walk every active-variant leaf under `segments` and flip the whole
+     * interaction ladder (`touched` / `interacted` / `blurredAfterInteraction`),
+     * as though the user had focused, edited and left each one. Powers
+     * `form.interact(path?)`. Idempotent, and leaves value / `focused` /
+     * `blurred` alone. Returns whether any leaf resolved, so the caller can skip
+     * validation and dev-warn on an empty path.
+     */
+    interactAtPath(segments: Path): boolean;
+    /**
+     * SSR-only optimistic mark: `connected: true` with no DOM element behind it.
+     * The `vRegisterHintTransform` compile-time transform calls it through
+     * `RegisterValue.markConnectedOptimistically()` for every element rendered
+     * with `v-register`. Idempotent, and a no-op on the client, where the
+     * directive's `created` hook is authoritative.
+     */
+    markConnectedOptimistically(path: Path): void;
+    /**
+     * Pristine verdict for a path whose canonical key the caller already holds.
+     * `key` is required and must correspond to `segments`; skipping the
+     * `canonicalizePath` round-trip is what lets a descendant walk, whose Map
+     * iteration already yields the key, avoid a canonicalize per leaf.
+     */
+    isPristineAtPathByKey(key: PathKey, segments: Path): boolean;
+    /**
+     * Whether any tracked array under `path` has changed shape (a reorder,
+     * insert or removal) against its construction / reset baseline. The
+     * structural half of `dirty`: per-element baselines travel with their
+     * element across a mutation, so a positional value comparison alone cannot
+     * see the shape change.
+     */
+    hasStructuralChangeUnder(path: Path): boolean;
+    /**
+     * Whether a baseline-present container under `path` was replaced wholesale
+     * by a non-container (`setValue('profile', undefined)` and the like) and is
+     * still absent. The other half of removal-driven `dirty`: every leaf in such
+     * a subtree vanishes at once, so neither the present-leaf walk nor the array
+     * tracker sees the loss. Self-filters by current liveness, so a refilled
+     * path stops counting.
+     */
+    hasRemovedSubtreeUnder(path: Path): boolean;
+    getFieldRecord(path: Path): FieldRecord | undefined;
+    /**
+     * Cancel every in-flight field-level validation run: clear the timers of
+     * debounced 'change' runs that have not fired, and latch `aborted` on runs
+     * whose async parse is in flight. Called by `handleSubmit` at entry, where
+     * submit validation is authoritative, and by `reset()`.
+     */
+    cancelFieldValidation(): void;
+    /**
+     * Open an async-transform run at `key`: bump the run token, increment the
+     * in-flight counters, stamp `transformingSince`, clear any prior
+     * `transformError` and register `holder` for a 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;
+    /**
+     * Close the run `token` at `key`: release the counters, a no-op when a
+     * supersede or cancel already released them, 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;
+    /**
+     * 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, either form-wide (`path`
+     * omitted) or at and under `path`. Resolves, never rejects. See
+     * `UseFormReturnType.settleTransforms`.
+     */
+    settleTransforms(path?: string | Path): Promise<void>;
+    /**
+     * Kick off, or schedule, a field-level validation run for `path`. Pass `[]`
+     * for whole-form scope, where `applySchemaErrorsForSubtree` replaces every
+     * schema-side entry with the adapter's full response. That is the road the
+     * construction-time async-refine seed takes.
+     *
+     * `immediate: true` skips the debounce window and calls the adapter on the
+     * next microtask; one-shot triggers use it, while the per-keystroke writers
+     * pass `false` so rapid mutations coalesce under `debounceMs`.
+     *
+     * `instance` carries per-`useForm()`-instance overrides for `validateOn` and
+     * `debounceMs`, so sibling instances sharing a FormStore each validate on
+     * their own cadence.
+     */
+    scheduleFieldValidation(path: Path, immediate: boolean, instance?: WriteMeta['instance']): void;
+    /**
+     * Subscribe to every `applyFormReplacement`. Fires synchronously once
+     * `form.value` holds `next` and all field / originals bookkeeping has run,
+     * which is how undo/redo hooks the single mutation funnel. `meta` carries
+     * the originating call site's intent and can be ignored. Returns an
+     * unsubscribe function.
+     */
+    onFormChange(listener: (next: F, meta?: WriteMeta) => void): () => void;
+    /**
+     * Subscribe to successful submissions. Fires once the consumer's `onSubmit`
+     * callback has resolved, so neither a validation failure nor a callback
+     * throw reaches it. The DevTools panel rides it to surface a submit event.
+     * Returns an unsubscribe function.
+     */
+    onSubmitSuccess(listener: () => void): () => void;
+    /**
+     * Subscribe to `reset()`. Fires after reset has replaced the form and
+     * cleared errors and lifecycle, so a listener sees the post-reset state.
+     * The history module uses it to drop the undo/redo stack. Returns an
+     * unsubscribe function.
+     */
+    onReset(listener: () => void): () => void;
+    /**
+     * Notify submit-success subscribers. `handleSubmit` in `process-form.ts`
+     * calls it once the consumer callback has resolved. Not for consumer use.
+     */
+    emitSubmitSuccess(): void;
+    /**
+     * Register a teardown bound to the FormStore's own lifetime rather than to a
+     * consumer's Vue effect scope; `dispose()` runs it when the last consumer
+     * unmounts. The history wiring needs this, so its subscribers survive one
+     * consumer unmounting while others remain.
+     */
+    registerCleanup(fn: () => void): void;
+    /**
+     * Cache for per-state modules, chiefly history, that must outlive any single
+     * consumer. Later `useForm` / `injectForm` calls for the same key read from
+     * here, so the public API shape does not depend on mount order. Keyed by a
+     * caller-owned string such as `'history'`.
+     */
+    readonly modules: Map<string, unknown>;
+    /**
+     * Whether schema-driven coercion runs for this form, `false` only when the
+     * consumer passed `useForm({ coerce: false })`. `buildCoerceFn` reads it at
+     * `register()` time to bake the per-path closure on `RegisterValue.coerce`.
+     */
+    readonly coerceEnabled: boolean;
+    /**
+     * Tear down the non-reactive resources this FormStore owns. The registry
+     * calls it when the last consumer unmounts: pending field-validation timers
+     * are cancelled, every subscriber is dropped, and each `registerCleanup`
+     * hook fires.
+     */
+    dispose(): void;
+};
+
+/**
+ * Public types for `useWizard`, the multistep-form orchestrator.
+ *
+ * A wizard is an ordered list of step slots. Each slot resolves to a
+ * participating form: a `useForm` reference, a bare string key
+ * (desugared to a noop form so affordance steps participate
+ * uniformly), a function slot for runtime branching, or a `lazy()`
+ * function slot that caches its resolution.
+ *
+ * The read surface is string-keyed (`Record<FormKey, ...>`), because a
+ * flow threaded through `injectWizard` has no lexical key knowledge.
+ * Typed per-form access flows back through the original form refs and
+ * through `wizard.handleSubmit`'s `ctx.get(formRef)` accessor.
+ */
+
+/**
+ * Minimum shape the wizard requires from a participating form. The
+ * wizard routes by `key` at runtime and hands back the original form
+ * objects untouched, so it never constrains their value shapes.
+ */
+type AnyForm = {
+    readonly key: FormKey;
+};
+/**
+ * Per-form summary at `wizard.statuses[key]`, and what `defaultStatuses`
+ * seeds. This is the cross-step rollup built for templates
+ * (`{{ wizard.statuses.cargo.valid }}`); `form.meta` carries the full
+ * per-form lifecycle surface.
+ *
+ * A noop form generated for a string slot reads as default-valid,
+ * unless that slot is a `gate('...')`, whose `gate` tracks the
+ * in-session acknowledgment.
+ */
+type FormStatus = {
+    /** `form.meta.valid`. `false` while errors exist, or before the first validation pass. */
+    readonly valid: boolean;
+    /** `form.meta.dirty`. `true` once any value differs from the original defaults. */
+    readonly dirty: boolean;
+    /**
+     * `form.meta.submitted`. `true` once a `handleSubmit` callback has
+     * resolved without throwing. A failed submit leaves it `false`;
+     * `submissionAttempts > 0` is the "user has tried" signal.
+     */
+    readonly submitted: boolean;
+    /** `form.meta.errorCount`. Active validation errors, zero when valid. */
+    readonly errorCount: number;
+    /**
+     * `true` when this step sits after an uncleared gate: its form is
+     * frozen and navigation to it is refused, so a stepper can render it
+     * as unreachable.
+     *
+     * Orthogonal to `gate`. The first uncleared gate reads
+     * `locked: false`, since you must reach it to clear it; a later gate
+     * sealed behind it reads both `gate: 'uncleared'` and `locked: true`.
+     */
+    readonly locked: boolean;
+    /**
+     * This step's own role as a hard prerequisite. `null` when the step is
+     * not a `gate()`, `'uncleared'` while its form is unconfirmed (so it
+     * seals every later step), `'cleared'` once confirmed by a clean
+     * submit or seeded via `defaultStatuses`.
+     *
+     * Reflects the live compiled shape, so a conditional `gate()` that a
+     * function slot drops resolves to `null`.
+     */
+    readonly gate: 'cleared' | 'uncleared' | null;
+};
+/**
+ * Seed accepted by `useWizard({ defaultStatuses })`. An omitted field
+ * falls back to the pending sentinel on read.
+ *
+ * `locked` is not accepted: it is derived live from the wizard's gates
+ * and overlaid on every status read, so a seeded value would be ignored.
+ */
+type FormStatusSeed = {
+    readonly valid?: boolean;
+    readonly dirty?: boolean;
+    readonly submitted?: boolean;
+    readonly errorCount?: number;
+    /**
+     * Write-only, and not echoed back on read. `'cleared'` latches the
+     * gate's cleared state once at construction, for restoring a
+     * confirmed prerequisite; the live `gate` overlay then owns the read.
+     * `'uncleared'` is the default and seeds nothing. Only a step that
+     * compiles to a `gate()` honors it.
+     */
+    readonly gate?: 'cleared' | 'uncleared';
+};
+/**
+ * One error from `wizard.allErrors[key]`. Carries the formKey and path
+ * so a wizard-wide error summary can route to the offending field.
+ */
+type WizardAggregateError = {
+    readonly formKey: FormKey;
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+    readonly code?: string;
+};
+/**
+ * The per-key `FormStatus` record, readable three ways:
+ * `wizard.statuses.cargo.valid`, `wizard.statuses('cargo')`, or
+ * `wizard.statuses()` for the whole record.
+ */
+type WizardStatusesProxy<S extends Record<string, FormStatus>> = ((key?: keyof S) => FormStatus | S) & Readonly<S>;
+/**
+ * One compiled position in the flow, as exposed by `wizard.steps`.
+ * String slots desugar to noop forms before compilation, so every
+ * compiled step carries a `form` whatever its source kind.
+ */
+type CompiledStep = {
+    readonly key: FormKey;
+    readonly form: AnyForm;
+};
+/**
+ * A participating form as seen from a function slot's `ctx.forms[key]`.
+ * Adds `values` to `AnyForm` so routing decisions can read live state.
+ *
+ * Values are loose here. For typed access inside a slot body, close
+ * over the original form ref instead of routing through `ctx.forms`.
+ */
+type WizardCtxForm = AnyForm & {
+    readonly values: Readonly<Record<string, unknown>>;
+};
+/**
+ * Context passed to function slots in the `steps` array. `forms` holds
+ * the statically-known forms: every top-level `AnyForm` slot plus every
+ * noop form synthesized for a top-level string slot.
+ *
+ * Function slots re-evaluate reactively when the values they read
+ * mutate, typically `ctx.forms.<key>.values.<path>`. The `forms`
+ * accumulator keeps its identity across re-evaluations. Keep slot
+ * bodies free of side effects; they are routing decisions.
+ */
+type WizardCtx = {
+    readonly forms: Readonly<Record<FormKey, WizardCtxForm>>;
+    readonly currentKey: FormKey | undefined;
+};
+/**
+ * What a function slot or a `lazy()` / `gate()` resolver may yield: a
+ * participating form, a bare affordance key, a nested `lazy()` /
+ * `gate()` wrapper (so the two compose in either order), or `null` /
+ * `undefined` to drop the position from the compiled list.
+ */
+type SlotResolution<Ctx = WizardCtx> = AnyForm | string | null | undefined | LazyMarker<Ctx> | GateMarker;
+/**
+ * Phantom brand for `LazyMarker`. The runtime brand symbol lives in
+ * `core/wizard-lazy.ts`; this declaration keeps the marker unforgeable
+ * without a circular import.
+ */
+declare const _lazyBrand: unique symbol;
+/**
+ * Marker returned by `lazy((ctx) => ...)`, which gives a function slot
+ * its own memoization cache: the resolver fires once on the first
+ * compile pass and stays cached until one of its own tracked reactive
+ * reads changes, or `wizard.reset()` invalidates it. An unrelated
+ * slot's deps changing does not re-fire it, so heavy or one-shot
+ * lookups stay one-shot.
+ *
+ * Construct via the `lazy()` helper exported alongside `useWizard`. The
+ * marker is opaque; consumers do not assemble it directly.
+ */
+type LazyMarker<Ctx = WizardCtx> = {
+    readonly [_lazyBrand]: true;
+    readonly resolve: (ctx: Ctx) => SlotResolution<Ctx>;
+};
+/**
+ * Phantom brand for `GateMarker`. The runtime brand symbol lives in
+ * `core/wizard-gate.ts`; this declaration keeps the marker unforgeable
+ * without a circular import.
+ */
+declare const _gateBrand: unique symbol;
+/**
+ * Marker returned by `gate(step)`, which makes a slot a hard
+ * prerequisite: an uncleared gate seals every step after it, and the
+ * gate's own form is the only way past. A gate clears on a member
+ * form's clean submit (confirmation), never on a value merely going
+ * valid (intent), and its form freezes once cleared so a back
+ * navigation is a read-only review.
+ *
+ * `Inner` carries the wrapped slot's static type, so `gate` is
+ * transparent to the type machinery: `gate(form)` still contributes the
+ * form's key to `wizard.forms` and still counts as a guaranteed step,
+ * while `gate(lazy(fn))` stays maybe-absent exactly like the lazy slot
+ * it wraps. See {@link UnwrapGate}.
+ *
+ * Construct via the `gate()` helper exported alongside `useWizard`. The
+ * marker is opaque; consumers do not assemble it directly.
+ */
+type GateMarker<Inner = unknown> = {
+    readonly [_gateBrand]: true;
+    readonly inner: Inner;
+};
+/**
+ * Strip every `gate()` wrapper off a slot type. A gate changes runtime
+ * reachability, never the compiled type, so the forms map and the
+ * non-empty-tuple predicate both unwrap before inspecting a slot.
+ * Recursive, which is what makes `gate(lazy(s))` and
+ * `lazy((ctx) => gate(s))` agree at the type level as they do at
+ * runtime.
+ */
+type UnwrapGate<T> = T extends GateMarker<infer Inner> ? UnwrapGate<Inner> : T;
+/**
+ * One position in the source `useWizard({ steps })` array. Each slot
+ * compiles to a `{ key, form }` step, or drops out:
+ *
+ *  - `AnyForm`: a form declared via `useForm`. Surfaced as-is.
+ *  - `string`: a bare key. The wizard generates a noop form so
+ *    affordance positions (intro, terms, review, congratulations) look
+ *    the same from outside as real steps.
+ *  - `null` / `undefined`: dropped from the compiled list, so a
+ *    conditional step reads inline as `cond ? form : null`.
+ *  - function: eager slot, re-evaluated reactively. Returns a
+ *    `SlotResolution`, or nullish to drop the position.
+ *  - `LazyMarker`: memoized function slot, see `lazy`.
+ *  - `GateMarker`: hard-prerequisite wrapper, see `gate`. Wraps any of
+ *    the above.
+ */
+type StepSlot<Ctx = WizardCtx> = AnyForm | string | null | undefined | ((ctx: Ctx) => SlotResolution<Ctx>) | LazyMarker<Ctx> | GateMarker;
+/** What the `restore` callback returns: the key of the step to activate. */
+type WizardRestoreState = {
+    readonly step?: FormKey;
+};
+/**
+ * `restore` callback. Invoked at construction and watched reactively,
+ * so browser back/forward, cross-tab events and route changes re-apply
+ * through the wizard. Returning `undefined` falls through to the first
+ * step.
+ */
+type WizardRestoreFn = () => WizardRestoreState | undefined;
+/**
+ * `persist` callback. Invoked when `wizard.currentStep` actually moves;
+ * the wizard diffs against the last persisted value to break the
+ * restore-persist loop.
+ */
+type WizardPersistFn = (state: WizardRestoreState) => void;
+/**
+ * Context passed to the `onSubmit` registered via
+ * `wizard.handleSubmit`. That call always processes the whole step
+ * list, so `values` carries every form's parsed output no matter which
+ * step fired the submit.
+ */
+type WizardSubmitContext = {
+    /**
+     * Namespaced aggregate keyed by form key, mirroring
+     * `wizard.allValues`. Noop forms contribute an empty record.
+     */
+    readonly values: Readonly<Record<FormKey, unknown>>;
+    /**
+     * Typed parsed output for a specific form ref. Works across
+     * cross-component graphs, because the ref carries its own schema.
+     */
+    readonly get: <F extends AnyForm>(form: F) => F extends {
+        readonly values: infer V;
+    } ? V : unknown;
+    /** Key of the step that fired this submission. */
+    readonly currentKey: FormKey;
+    /**
+     * `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 `false`, yet the whole list is still processed and `done` still
+     * latches on success.
+     */
+    readonly isFinal: boolean;
+};
+/**
+ * `onSubmit` registered via `wizard.handleSubmit`. Sync or async; the
+ * returned promise gates `wizard.submitting`.
+ */
+type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
+/**
+ * Optional `onError` registered via `wizard.handleSubmit`. Receives
+ * errors spanning EVERY step, since `handleSubmit` validates the whole
+ * wizard, so a failed submit surfaces every form's errors at once
+ * rather than only the active step's. Entries come from per-form
+ * validation, activation failures (`atta:activation-failed`), and a
+ * submit callback that left errors on a processed step via 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, ... })`. Only `steps` is required. */
+type WizardOptions = {
+    /**
+     * Ordered list of slots that compile into the positional step list.
+     * See `StepSlot` for the per-slot contract.
+     */
+    readonly steps: ReadonlyArray<StepSlot>;
+    /**
+     * Identifier this wizard registers under, so descendants reach it
+     * with `injectWizard(key)` instead of prop-threading. Omit it and the
+     * wizard gets a synthetic key from `useId()`, so the server-rendered
+     * and client-hydrated trees agree on one registry entry; that key is
+     * opaque, and descendants reach an anonymous wizard through ambient
+     * `injectWizard()`.
+     *
+     * Registering a key twice is first-wins, with a dev warning on the
+     * second, mirroring `useForm`. The warning fires only for explicit
+     * keys, since two anonymous wizards are always given distinct keys.
+     */
+    readonly key?: string;
+    /**
+     * Seed statuses used while a form is still pre-resolved: async
+     * `defaultValues` in flight, or a wizard-deferred non-current step.
+     * Mirrors `defaultValues`' trichotomy of plain object, sync factory
+     * or async factory.
+     *
+     * Per form, the first of these that applies wins:
+     *   1. defaults resolved, so derive from `form.meta`
+     *   2. noop form, so the built-in always-valid status
+     *   3. a seed for this key
+     *   4. the pending sentinel
+     *
+     * `gate: 'cleared'` is honored as a one-shot seed of the gate's
+     * cleared latch at construction, for restoring a confirmed
+     * prerequisite, and only on a step that compiles to a `gate()`. See
+     * `FormStatusSeed` for what the seed does and does not carry.
+     *
+     * SSR note: an async factory resolves after hydration, so a gate
+     * seeded through it clears client-side. For a gate that must render
+     * open on the first server byte, use the plain or sync-factory form
+     * and resolve server truth in the page's `setup` await.
+     *
+     * Unknown keys dev-warn, so a stale resume payload surfaces at
+     * construction.
+     *
+     * A factory that throws, or a promise that rejects, seeds nothing and
+     * reports once in development, the same as omitting the option.
+     */
+    readonly defaultStatuses?: Record<string, FormStatusSeed> | (() => Record<string, FormStatusSeed>) | (() => Promise<Record<string, FormStatusSeed>>);
+    /**
+     * Override for `wizard.progress`. Omitted, progress is
+     * `valid_step_count / count`, normalised to `[0, 1]`. Provided, the
+     * returned number is used as-is and normalising it is yours to do.
+     *
+     * Invoked inside a `computed`, so it must be synchronous and may only
+     * read reactive sources. A throw falls back to the built-in ratio and
+     * reports once in development.
+     */
+    readonly progress?: (steps: ReadonlyArray<CompiledStep>) => number;
+    /**
+     * When `wizard.handleSubmit` finds errors, jump to the first failing
+     * form's step and invoke its `applyInvalidSubmitPolicy()`, which
+     * honors that form's own `focusOnInvalidSubmit` choice. Default
+     * `true`. Pass `false` to leave the active step where the user left
+     * it and navigate yourself from `onError`.
+     */
+    readonly focusFirstError?: boolean;
+    /**
+     * Source of truth for the active step, invoked at construction and
+     * re-evaluated reactively. The default reads `?step=<key>` from the
+     * URL. Pass `false` to disable URL sync, or your own callback for
+     * non-router persistence.
+     *
+     * A throw yields no step, so the wizard stays where it is, and reports
+     * once in development.
+     */
+    readonly restore?: WizardRestoreFn | false;
+    /**
+     * Destination for the active step, invoked whenever `currentStep`
+     * moves. The default writes `?step=<key>`. Pass `false` to disable
+     * persistence, or your own callback to scope the param name or write
+     * elsewhere.
+     *
+     * A throw does not block the navigation that triggered it, so the step
+     * is live but unrecorded, and reports once in development.
+     */
+    readonly persist?: WizardPersistFn | false;
+};
+/**
+ * True when a slot is guaranteed to contribute exactly one compiled
+ * step: a bare form or affordance string, 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, U = UnwrapGate<T>> = [null] extends [U] ? false : [undefined] extends [U] ? false : U extends LazyMarker | ((...args: unknown[]) => unknown) ? false : U extends string ? true : U extends {
+    readonly key: string;
+} ? true : false;
+/**
+ * Is the steps tuple statically guaranteed to compile to a non-empty
+ * list? True when at least one element is an `IsGuaranteedStep`.
+ * Function and `lazy()` slots may resolve to nothing, and nullish slots
+ * are an explicit drop, so a tuple of only those stays honestly
+ * `| undefined`.
+ *
+ * This is what narrows `currentStep` and `activeForm` in the
+ * common-case wizard while keeping the union wherever 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. Values are loose because the active step's
+ * schema is not statically known; reach for the original form ref or
+ * `ctx.get(ref)` for typed per-step values.
+ */
+type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? UseFormReturnType<GenericForm> : UseFormReturnType<GenericForm> | undefined;
+/**
+ * One slot's contribution to {@link FormsRecordOf}. Unwraps `gate()`
+ * and strips nullish off the slot first, so a conditionally-present
+ * form and a `gate(form)` both still map to their key and stay
+ * concretely typed on `wizard.forms`. A purely nullish slot contributes
+ * nothing.
+ */
+type SlotRecord<First, U = UnwrapGate<First>, F = Exclude<U, 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;
+/**
+ * Builds the static portion of `wizard.forms` by walking the steps
+ * tuple. Per slot kind:
+ *
+ *  - **string** (`'review'`): the literal is the record key, and the
+ *    value is `AnyForm`, since the synthesized noop form is opaque at
+ *    the type level.
+ *  - **form**: the form's own `key` is the record key and the value is
+ *    the concrete handle, so `wizard.forms.shipping.values.address`
+ *    carries schema-derived field types through. A form behind a
+ *    `cond ? form : null` still maps to its key.
+ *  - **nullish**: contributes nothing.
+ *  - **function / `lazy()`**: contributes nothing statically.
+ *    Runtime-resolved forms stay reachable as `AnyForm` through the
+ *    catch-all index signature on `WizardForms`.
+ *  - **`gate()`**: unwrapped, so it contributes exactly what the slot
+ *    it wraps would.
+ */
+type FormsRecordOf<S> = S extends readonly [
+    infer First,
+    ...infer Rest extends ReadonlyArray<StepSlot>
+] ? SlotRecord<First> & FormsRecordOf<Rest> : unknown;
+/**
+ * `wizard.forms` typed view: the static per-step map, intersected with
+ * a catch-all so a statically known key resolves to its concrete form
+ * type and any other string key resolves to `AnyForm`.
+ */
+type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
+/**
+ * What `useWizard({ steps, ... })` returns. Every reactive read is a
+ * plain getter, no `.value`, so `wizard.currentStep`, `wizard.progress`
+ * and `wizard.allValues` track inside `computed` and templates
+ * directly.
+ *
+ * Parameterized by the steps tuple `S` so the active-position fields
+ * narrow to non-`undefined` when every slot is positional, and stay
+ * honest unions when a function or `lazy()` slot can drop the position
+ * at runtime. `useWizard`'s `const` type parameter preserves the
+ * literal tuple, so that narrowing happens without a consumer-side
+ * `as const`.
+ */
+type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepSlot>> = {
+    readonly key: string;
+    /**
+     * Key of the active step. Narrows to `string` when the steps tuple is
+     * statically guaranteed non-empty; otherwise `string | undefined`, so
+     * an empty compiled list surfaces honestly.
+     */
+    readonly currentStep: CurrentStepOf<S>;
+    /**
+     * A live view of the active step's form, so operating through it
+     * always targets the current step: a handler captured once at setup
+     * (`wizard.activeForm.handleSubmit(() => wizard.next())`) retargets as
+     * the wizard advances. It is a facade, not the raw per-step handle;
+     * reach for `wizard.forms[key]` when you need identity. Same
+     * `undefined` narrowing as `currentStep`.
+     */
+    readonly activeForm: ActiveFormOf<S>;
+    /** 0-based position of the active step. */
+    readonly activeIndex: number;
+    /** `true` when `currentStep` is the last compiled step. */
+    readonly isFinalStep: boolean;
+    /** The ordered compiled `{ key, form }` slots. */
+    readonly steps: ReadonlyArray<CompiledStep>;
+    /** Every step's form, indexable by step key. */
+    readonly forms: WizardForms<S>;
+    /** `steps.length`. */
+    readonly count: number;
+    /**
+     * Callable readonly proxy over the per-key `FormStatus` record.
+     * Noop-form keys always read as default-valid.
+     */
+    readonly statuses: WizardStatusesProxy<Record<string, FormStatus>>;
+    /** Each form's values, keyed by step key. */
+    readonly allValues: Readonly<Record<FormKey, unknown>>;
+    /** Each form's validation errors, keyed by step key. Noop forms map to an empty list. */
+    readonly allErrors: Readonly<Record<FormKey, readonly WizardAggregateError[]>>;
+    /**
+     * Normalised step-validity ratio, or the `progress` override's
+     * return. Forward-looking: noop steps count as valid.
+     */
+    readonly progress: number;
+    /**
+     * `true` when `activeIndex < count - 1`. Purely positional;
+     * navigation never gates on validity.
+     */
+    readonly canAdvance: boolean;
+    /** `true` when `activeIndex > 0`. */
+    readonly canGoBack: boolean;
+    /**
+     * `isFinalStep` and every step's form valid. Reactive to current
+     * validity, so this is the "enable the Finish button" signal.
+     */
+    readonly complete: boolean;
+    /**
+     * Monotonic latch: `true` the first time a `handleSubmit` resolves
+     * without throwing AND leaves no errors on any step, and stays `true`
+     * through later edits. A callback that calls `setErrors` and returns
+     * is a failed submit, so it does not flip this. Only `reset()` clears
+     * it. Gates success UI that should reflect submission history rather
+     * than current validity.
+     */
+    readonly done: boolean;
+    /**
+     * `true` while a `wizard.handleSubmit` call is in flight. Every
+     * navigation method refuses while it is on.
+     */
+    readonly submitting: boolean;
+    /** `wizard.handleSubmit` invocations, success or failure. */
+    readonly submissionAttempts: number;
+    /**
+     * The error THROWN by the most recent `handleSubmit` callback or its
+     * `onError`, coerced to a real `Error`, and `null` on success. Like
+     * `form.meta.submitError`, this is the unexpected-throw channel: an
+     * expected rejection handled through `setErrors` surfaces on the
+     * error surface and in `onError` instead, leaving this `null`. It is
+     * parked here rather than re-thrown, so the handler always resolves
+     * and never manufactures an unhandled rejection. Cleared at submit
+     * entry and by `reset()`.
+     */
+    readonly submitError: Error | null;
+    /**
+     * Append-only breadcrumb of navigated step keys. `back()` does not
+     * pop: the trail is an audit log, not a back-stack.
+     */
+    readonly visited: readonly FormKey[];
+    /**
+     * Advance one step. Refuses while `submitting`. On an UNCLEARED
+     * `gate()` step it behaves as `tryNext()`, so wiring a Next button
+     * straight to it can never skip the gate's confirmation; once that
+     * gate clears it is plain navigation again and does not re-submit.
+     */
+    readonly next: () => Promise<void>;
+    /** Go back one step. Refuses while `submitting`. */
+    readonly back: () => void;
+    /** Jump to a step by key. Refuses while `submitting`. */
+    readonly goTo: (key: string) => void;
+    /**
+     * Submit the active step, and advance once that submit resolves
+     * clean. Invalid input keeps the pin put under the form's standard
+     * error reveal, with the first error focused and display state
+     * advanced. The advance runs after the submit settles, so a `gate()`
+     * on the active step clears in a single call.
+     *
+     * Inline-bindable (`@click="wizard.tryNext()"`), and resolves to
+     * whether the pin moved. `false` on a degenerate or final-step wizard;
+     * finish through `handleSubmit` instead.
+     *
+     * Called while the active step already has a submit in flight, the
+     * usual case being from inside that form's own callback, it rides
+     * that submit rather than starting a second one, so one action costs
+     * one submission. The pin has not moved by the time it resolves, so
+     * the answer is `false` and the advance lands with the in-flight
+     * submit.
+     */
+    readonly tryNext: () => Promise<boolean>;
+    /**
+     * Validate the entire step list, from any step, and never advance the
+     * pin. On success `done` latches; on any error the first failing step
+     * is focused and `onError` fires with errors spanning every step.
+     *
+     * To gate advancing a step on its own validity, compose with the
+     * active form's submit instead:
+     * `activeForm.handleSubmit(() => wizard.next())`.
+     *
+     * Returns a handler for `<form @submit>` or for imperative use.
+     */
+    readonly handleSubmit: (onSubmit: WizardOnSubmit, onError?: WizardOnError) => (event?: Event) => Promise<void>;
+    /**
+     * Zero the wizard lifecycle (`submissionAttempts`, `visited`, `done`),
+     * reset every form, return to `steps[0].key`, and invoke `persist`
+     * with the cleared state. Re-applies the `defaultStatuses` gate seed,
+     * so a reboot returns to the seeded clearance rather than fully
+     * sealed.
+     */
+    readonly reset: () => void;
+    /**
+     * Re-seal a cleared gate, contingent on `commit`. Awaits `commit`, a
+     * server-side revoke, and re-seals only if it resolves clean, so the
+     * gate reflects server-confirmed truth the same way a clearing submit
+     * does; a thrown `commit` leaves the gate as-is.
+     *
+     * Seal-only, so it can never become the leading-signal foot-gun
+     * `gate()` exists to prevent. `commit` is required: pass `() => {}`
+     * for a deliberate client-only re-seal. Resolves whether the gate
+     * ended up sealed and never rejects; resolves `false` with a dev
+     * warning on a non-gate key.
+     */
+    readonly relock: (key: FormKey, commit: () => void | Promise<void>) => Promise<boolean>;
+};
+
+/**
+ * Portable SSR detection. The plugin captures this value at install time and
+ * exposes it via the registry so every runtime branch reads a single source
+ * of truth instead of sniffing `import.meta.*` (bundler-specific) at each
+ * call site.
+ *
+ * Consumers can override the heuristic explicitly via
+ * `createAttaform({ ssr: true })`; the default handles the common
+ * Node-vs-browser split without relying on any bundler-injected flag.
+ */
+interface SSRDetectOptions {
+    /**
+     * Force SSR-vs-client mode, bypassing the `typeof window` heuristic.
+     * `true` activates the SSR code paths (no devtools, no persistence
+     * wiring, payload serialisation enabled); `false` forces client mode.
+     * The Nuxt plugin sets this from `import.meta.server` so SSR detection
+     * never depends on whether `window` is polyfilled. Tests that need to
+     * exercise the SSR code paths under jsdom pass `ssr: true`.
+     */
+    ssr?: boolean;
+}
+
+/**
+ * Per-Vue-app container for every form state instance. Each
+ * `app.use(createAttaform())` call gets its own registry, so Attaform runs
+ * under bare Vue 3, SSR through `@vue/server-renderer`, and Nuxt on one
+ * code path.
+ *
+ * Forms are stored as `Map<FormKey, FormStore<GenericForm>>`. The generic
+ * has to relax at storage time because two forms in one app have different
+ * `Form` generics; a caller recovers the specific type through `useForm`'s
+ * overloads.
+ */
+
+/**
+ * Serialised snapshot of one form's state, captured by
+ * `renderAttaformState` for SSR and replayed by
+ * `hydrateAttaformState` on the client. Round-trips through
+ * JSON-safe tuples; field references are intentionally omitted
+ * (DOM nodes don't survive serialisation).
+ */
+type SerializedFormData = {
+    /** The form's value at snapshot time. */
+    readonly form: unknown;
+    /**
+     * Errors produced by the schema at snapshot time. Replayed into
+     * the client form's error state at hydration; cleared on
+     * successful re-validation client-side.
+     */
+    readonly schemaErrors: ReadonlyArray<readonly [string, unknown]>;
+    /**
+     * Errors set explicitly via `setErrors` (typically a server
+     * response) at snapshot time. Replayed at hydration; persists across
+     * client-side re-validation.
+     */
+    readonly userErrors: ReadonlyArray<readonly [string, unknown]>;
+    /** Per-field metadata (timestamps, raw values, connection flags) captured at snapshot time. */
+    readonly fields: ReadonlyArray<readonly [string, unknown]>;
+    /**
+     * Path keys that were in the form's `blankPaths` set at snapshot time,
+     * carrying the "displayed empty" UI state across the SSR boundary.
+     * Without it the client briefly renders `String(slim-default)` (`'0'`,
+     * say) for a field the server rendered blank. Optional in the wire
+     * format, so an older payload shape still deserialises.
+     */
+    readonly blankPaths?: ReadonlyArray<string>;
+};
+type PendingHydration = Map<FormKey, SerializedFormData>;
+/**
+ * Attaform's per-Vue-app container, one per `app.use(createAttaform())`
+ * call.
+ *
+ * Most consumers never touch it: `useForm` and `injectForm` reach the
+ * registry for you. Access it explicitly only when wiring SSR or a custom
+ * plugin integration.
+ */
+type AttaformRegistry = {
+    /**
+     * Live forms keyed by `FormKey`.
+     * @internal
+     */
+    readonly forms: Map<FormKey, FormStore<GenericForm>>;
+    /**
+     * Live wizards keyed by the consumer-supplied `key` option. Populated by
+     * `useWizard(entryForm, { key })` and read by `injectWizard(key)` to
+     * resolve a cross-component wizard handle. An anonymous wizard does NOT
+     * register here, and is reachable only through ambient provide/inject.
+     * @internal
+     */
+    readonly wizards: Map<string, UseWizardReturnType>;
+    /**
+     * Snapshots staged by `hydrateAttaformState` waiting to be consumed by the next `useForm` call.
+     * @internal
+     */
+    readonly pendingHydration: PendingHydration;
+    /** `true` while running on the server during SSR; `false` on the client. */
+    readonly ssr: boolean;
+    /**
+     * Track a consumer of `key`, returning a dispose function to call when
+     * that consumer unmounts. The form is evicted once the last consumer
+     * disposes, so a long-running SPA does not leak detached state across
+     * navigations.
+     * @internal
+     */
+    readonly trackConsumer: (key: FormKey) => () => void;
+    /**
+     * Track a consumer of wizard `key`, returning a dispose function to call
+     * when that consumer unmounts. The handle leaves `wizards` once the last
+     * consumer disposes, mirroring the form consumer counting. An anonymous
+     * wizard never enters this counter, having no key to count under.
+     * @internal
+     */
+    readonly trackWizardConsumer: (key: string) => () => void;
+    /**
+     * Mark a form as eligible for SSR prefetch. The form's
+     * `onServerPrefetch` hook reads `shouldPrefetch(key)` and runs the
+     * captured `defaultValues` factory only when this set holds the key and
+     * the skip set does not. Set by `form.activate()` and by `useWizard`'s
+     * current-step auto-mark.
+     * @internal
+     */
+    readonly enqueuePrefetch: (key: FormKey) => void;
+    /**
+     * Mark a form as ineligible for SSR prefetch, overriding
+     * `enqueuePrefetch`. `useWizard` uses it to keep a non-current step
+     * dormant on the server even when a stray `activate()` enqueued it: the
+     * wizard's "the user is not on this step" signal wins.
+     * @internal
+     */
+    readonly skipPrefetch: (key: FormKey) => void;
+    /**
+     * Whether `key`'s SSR prefetch should run. Returns `true` iff the key
+     * is enqueued AND not skipped.
+     * @internal
+     */
+    readonly shouldPrefetch: (key: FormKey) => boolean;
+};
+/**
+ * The Vue `InjectionKey` the registry is provided under on the app. Most
+ * consumers never need it: `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;
+/**
+ * Create a fresh `AttaformRegistry`. `createAttaform()` calls it
+ * internally, so reach for it directly only when building a custom plugin
+ * that does not want `createAttaform`'s auto-install behaviour: a test
+ * harness, or an embedded app.
+ */
+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 do not need it, since `useForm` and `injectForm` call it
+ * for you. Reach for it when building a custom integration that needs the
+ * raw registry.
+ *
+ * Throws:
+ * - `OutsideSetupError` when called outside a Vue setup context, from an
+ *   event handler or an async callback. Move the call into setup, or
+ *   trigger it from a child component.
+ * - `RegistryNotInstalledError` when called inside setup with the plugin
+ *   not installed. Add `app.use(createAttaform())` to your app entry.
+ */
+declare function useRegistry(): AttaformRegistry;
+/**
+ * Look up a Vue app's registry by `App` reference, for the SSR helpers
+ * (`renderAttaformState`, `hydrateAttaformState`) that run outside a
+ * component setup context.
+ *
+ * Throws `RegistryNotInstalledError` when the app was never wired with
+ * `createAttaform()`.
+ */
+declare function getRegistryFromApp(app: App): AttaformRegistry;
+
+/**
+ * Multistep-form orchestrator built around an ordered list of step
+ * slots. A slot resolves to a participating form four ways: an existing
+ * `useForm` reference, a bare string key (desugared to a noop form, so
+ * an affordance step participates like any other), an eager function
+ * slot for runtime branching, or a `lazy()`-wrapped function slot that
+ * caches its resolution and re-fires only on its own tracked deps.
+ *
+ * Navigation (`next` / `back` / `goTo`) walks positional indices.
+ * `handleSubmit` validates the whole step list from any step and never
+ * advances; to gate an advance, write
+ * `activeForm.handleSubmit(() => wizard.next())`. URL sync rides on the
+ * `restore` / `persist` callbacks, which default to `?step=<key>`.
+ */
+declare function useWizard<const S extends ReadonlyArray<StepSlot>>(options: WizardOptions & {
+    readonly steps: S;
+}): UseWizardReturnType<S>;
+
+/** Options accepted by `injectWizard` in place of a bare key string. */
+type InjectWizardInput = {
+    readonly key?: string | undefined;
+};
+/**
+ * Reach an existing wizard from a descendant component without threading
+ * it through props. The counterpart to `useWizard`: `useWizard` creates
+ * and provides, `injectWizard` looks up.
+ *
+ * ```ts
+ * // The nearest ancestor's useWizard call.
+ * const wizard = injectWizard()
+ *
+ * // A specific wizard by key, from anywhere in the app.
+ * const signup = injectWizard('signup-wizard')
+ * ```
+ *
+ * A keyed call is a registry lookup, independent of component-tree
+ * position, and reaches any wizard built with `useWizard({ steps, key
+ * })`. A no-key call takes the closest ambient ancestor; only an
+ * anonymous `useWizard()` fills that slot, so a keyed wizard has to be
+ * addressed by its key, exactly as on the form side.
+ *
+ * Returns `null` when nothing matches, so narrow before use:
+ *
+ * ```ts
+ * const wizard = injectWizard('signup')
+ * if (!wizard) return
+ * wizard.next()
+ * ```
+ *
+ * A keyed miss warns in dev with the registered keys and the call site.
+ * A keyed lookup also pins the handle for this component's lifetime, so
+ * it outlives a parent `useWizard` that unmounts first, and the registry
+ * evicts the entry a microtask after the last consumer disposes. An
+ * ambient lookup does not pin: the parent's scope owns that lifetime.
+ */
+declare function injectWizard(input?: string | InjectWizardInput): UseWizardReturnType | null;
+
+/**
+ * Wrap a function slot in `lazy()` to give that slot its own memoized
+ * cache, distinct from the wizard-wide step compiler.
+ *
+ * Default function slots in `useWizard({ steps })` re-evaluate whenever
+ * the compiled step list re-evaluates, including when an unrelated
+ * slot's reactive deps change. That keeps the rail correct but can
+ * trigger spurious work in a resolver that is expensive (a network
+ * lookup, a heavy schema derivation, an async-derived factory).
+ *
+ * `lazy()` isolates each wrapped slot behind its own cache. The
+ * resolver runs eagerly on the first compile pass; subsequent reads
+ * reuse the cached form. The cache invalidates only when one of the
+ * resolver's own tracked reactive dependencies changes (Vue's
+ * `computed` semantics applied to a slot), or when `wizard.reset()`
+ * triggers a global re-compile:
+ *
+ *   const wizard = useWizard({
+ *     steps: [
+ *       account,
+ *       lazy((ctx) => loadShippingForm(ctx.forms.account.values.region)),
+ *       confirm,
+ *     ],
+ *   })
+ *
+ * Resolution semantics:
+ *  - Eager at construction so `wizard.steps` and SSR markup are honest
+ *    from t=0.
+ *  - Memoized: the resolver re-fires only when one of its own tracked
+ *    reads changes. An unrelated slot re-evaluating does not re-fire
+ *    this one.
+ *  - `wizard.reset()` clears every lazy slot's cache so a reboot truly
+ *    resolves from scratch.
+ *  - Resolving to `null` or `undefined` drops the slot from the compiled
+ *    list until the resolver next re-fires.
+ *  - The resolver may return a `gate()` wrapper, so a lazy slot can gate
+ *    what it resolves to; `lazy((ctx) => gate(s))` and `gate(lazy(s))`
+ *    resolve identically.
+ *
+ * The runtime brand returned by `lazy()` is opaque. Use
+ * {@link isLazyMarker} to detect it.
+ */
+declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => SlotResolution<Ctx>): LazyMarker<Ctx>;
+
+/**
+ * Wrap a step slot in `gate()` to make it a hard prerequisite: while the
+ * gate is uncleared, every step positioned after it is inaccessible, and
+ * the gate's own form is the only way past.
+ *
+ * A gate is safe by construction. It does not hand the consumer a
+ * predicate to key on; it bakes the correct semantics in:
+ *
+ *  - **Confirmation, not intent.** The gate clears only when a member
+ *    form submits clean, never when a value merely goes valid. Checking
+ *    the box does nothing; submitting the consent step is what opens the
+ *    rail. This is the whole reason `gate()` exists: a leading value
+ *    signal lets a downstream step collect data before the prerequisite
+ *    is confirmed.
+ *  - **Linear-forward.** An uncleared gate seals every step after it.
+ *    Order places it: put `gate(step)` immediately before what it
+ *    guards. Everything downstream is both un-navigable and, through the
+ *    `disabled` data freeze, un-fillable, so a deep link, the browser
+ *    back button, or a stray `goTo` all redirect to the gate.
+ *  - **Freeze-after-clear.** A cleared gate's own form freezes, so
+ *    navigating back to it is a read-only review with no withdrawal
+ *    path. There is no re-lock dance.
+ *
+ * Wrap any slot kind:
+ *
+ *   const wizard = useWizard({ steps: [gate(consent), shipping, payment] })
+ *
+ * A **form** gate (`gate(consentForm)`) clears when its form submits
+ * clean, and is treated as pre-cleared on reload when its member form
+ * rehydrates already valid (a persisted consent), so a seeded-valid gate
+ * SSR-renders open. A bare-string **affordance** gate (`gate('terms')`)
+ * clears on acknowledgment (advancing past it), and re-prompts each
+ * session because that acknowledgment is ephemeral.
+ *
+ * Conditional gates come from composition, not an options bag:
+ *
+ *   () => (transfer.values.amount > 10_000 ? gate(kyc) : kyc)
+ *
+ * `gate()` composes with `lazy()` in either order:
+ * `gate(lazy(fn))` and `lazy((ctx) => gate(fn(ctx)))` resolve
+ * identically.
+ *
+ * The runtime brand returned by `gate()` is opaque. Use
+ * {@link isGateMarker} to detect it.
+ */
+declare function gate<const Inner extends StepSlot>(step: Inner): GateMarker<Inner>;
+
+/**
+ * Stable identifiers for library-emitted `ValidationError` codes.
+ *
+ * Convention: `<scope>:<kebab-case-identifier>`. Three scopes are
+ * recognised by the library:
+ *
+ * - `atta:`: emitted by the framework-agnostic core (this map).
+ * - `zod:`: emitted by the Zod adapter, computed inline from
+ *   `issue.code` (e.g. `zod:too_small`). No enum here because
+ *   Zod's code list evolves.
+ * - consumer-defined: anything the consumer's backend or app stamps
+ *   onto a `ValidationError` (a server response handed to `setErrors`,
+ *   or a code passed inline). Pick a scope (`api:`, `auth:`, etc.) and
+ *   stay consistent.
+ *
+ * Use these constants in tests and error-routing UI:
+ *
+ * ```ts
+ * if (error.code === AttaformErrorCode.NoValueSupplied) {
+ *   // user hasn't filled this field
+ * }
+ * ```
+ */
+declare const AttaformErrorCode: {
+    /** A required field is in the blank set: no value was supplied. */
+    readonly NoValueSupplied: "atta:no-value-supplied";
+    /** The schema adapter's `validateAtPath` threw synchronously. */
+    readonly AdapterThrew: "atta:adapter-threw";
+    /**
+     * User code inside a `z.preprocess`, `.refine`, or `.transform`
+     * threw (sync or async). The adapter caught the throw and surfaced
+     * it as a `ValidationError` at the field path so the form's normal
+     * error pipeline handles it instead of leaking as an unhandled
+     * rejection or routing through `submitError`.
+     */
+    readonly ValidatorThrew: "atta:validator-threw";
+    /**
+     * A function-form `defaultValues` factory threw or its promise
+     * rejected. The runtime captures the raw error on `form.hydrateError`
+     * and ALSO surfaces a form-level `ValidationError` (path `[]`) so
+     * the standard error pipeline carries the signal. Critical for the
+     * SSR round-trip: `hydrateError` itself does not ride the wire
+     * payload, but `schemaErrors` does, so the client sees the failure
+     * after rehydration without an extra channel.
+     */
+    readonly HydrationFailed: "atta:hydration-failed";
+    /** The supplied path didn't resolve to any node in the schema. */
+    readonly PathNotFound: "atta:path-not-found";
+    /**
+     * A walked form's `activate()` (async `defaultValues` factory) threw
+     * during `wizard.handleSubmit`'s path walk. Surfaced as a synthetic
+     * `ValidationError` at the form-level path (`[]`) so the wizard's
+     * aggregate error pipeline can carry the failure alongside ordinary
+     * validation errors. The raw factory error remains on
+     * `form.hydrateError` for retry UX.
+     */
+    readonly ActivationFailed: "atta:activation-failed";
+    /**
+     * Default code stamped on a manual error set through `form.setErrors`
+     * when the caller omits an explicit `code`. The `setErrors` input is
+     * lenient (`code` optional), so this is the fallback that keeps every
+     * produced `ValidationError` carrying a stable, branchable identifier.
+     * 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";
+    /**
+     * Synthesized by `wizard.handleSubmit` when the whole-wizard submit
+     * would otherwise succeed but a `gate()` step is still uncleared. A
+     * gate clears only on its member form's clean submit (confirmation), so
+     * a downstream step that happens to be valid-by-default must not let the
+     * wizard finish past an unconfirmed prerequisite. Emitted at the gate
+     * form's key (path `[]`) so the aggregate error pipeline routes focus to
+     * the gate, and `done` never latches.
+     */
+    readonly GateNotCleared: "atta:gate-not-cleared";
+};
+/** Every `atta:`-prefixed code Attaform itself can put on an error. */
+type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
+
+/**
+ * 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;
+};
+/**
+ * Create the Vue plugin that installs the form library on a Vue
+ * application. Required only when you want app-wide options
+ * (`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({ devtools: false }))
+ *   .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 it to `JSON.stringify`, `devalue`, or any other
+ * serialiser before embedding in your SSR payload.
+ */
+type SerializedAttaformState = {
+    /** Envelope version; see {@link ATTAFORM_STATE_VERSION}. */
+    readonly v: number;
+    /** 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 do not need it:
+ * `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')
+ * ```
+ *
+ * Accepts `unknown` because the payload crosses the wire untyped
+ * (an inline `<script>` tag, `JSON.parse`): the envelope is
+ * validated at runtime, and anything that isn't a version-matched
+ * `renderAttaformState` snapshot is skipped wholesale, so forms
+ * construct fresh from their schemas instead.
+ *
+ * The next `useForm({ key })` call for each serialised form picks up
+ * the snapshot transparently, with no further action required.
+ */
+declare function hydrateAttaformState(app: App, payload: unknown): 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, so `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;
+
+/**
+ * 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. It must stay stable across versions:
+ * 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 the 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);
+}
+
+export { createRegistry as B, DEVTOOLS_WINDOW_KEY as D, escapeForInlineScript as E, gate as H, getRegistryFromApp as J, hydrateAttaformState as K, injectForm as M, injectWizard as N, OutsideSetupError as O, isRegisterValue as P, kAttaformRegistry as Q, RegistryNotInstalledError as R, lazy as T, renderAttaformState as V, useRegister as X, useRegistry as Y, useWizard as Z, AttaformError as c, AttaformErrorCode as d, InvalidPathError as g, InvalidUseFormConfigError as h, ReservedFormKeyError as i, SubmitErrorHandlerError as l, assignKey as y, createAttaform as z };
+export type { AttaformRegistry as A, CompiledStep as C, FormStatus as F, GateMarker as G, InjectWizardInput as I, LazyMarker as L, SerializedAttaformState as S, UseRegisterOptions as U, WizardAggregateError as W, AnyForm as a, AttaformDevtoolsBridge as b, AttaformPluginOptions as e, FormStatusSeed as f, SerializedFormData as j, StepSlot as k, UseRegisterReturn as m, 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 };