attaform 0.27.5 → 0.28.0

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

@@ -1,2484 +0,0 @@
-import { G as GenericForm, F as FormKey, a as UseFormReturnType, a4 as RegisterValue, T as PathKey, k as DisplayCtx, w as GetDisplayState, l as DisplayMachine, S as Path, a9 as SlimPrimitiveKind, C as CoercionEntry, e as CoercionRegistry, af as ValidationError, A as AbstractSchema, aj as WriteMeta, h as DeepPartial, ak as WriteShape, as as TransformAbortHolder, ad as ValidateOn, d as AttaformDefaults, at as RegisterModelDynamicCustomDirective } from './attaform.CzL2CZ8U.mjs';
-import { Ref, ComputedRef, App, InjectionKey, Plugin } from 'vue';
-
-/**
- * Options accepted by `injectForm` when passing an object instead of
- * a bare key string. `__ssrAccessed: true` is set by the Phase 3
- * `attaform-vite` transform on descendant calls whose template reads
- * the injected form's reactive state — it tells the runtime to
- * enqueue the form for SSR prefetch and register the descendant's
- * `onServerPrefetch` hook. Consumers may set it manually as the
- * escape hatch when the transform isn't installed or doesn't see
- * the reference.
- */
-type InjectFormInput = {
-    readonly key?: FormKey;
-    /**
-     * Set by the Vite transform when this `injectForm` call site sits in
-     * a component whose template / script reads the form's reactive
-     * state. On the server, this enqueues the form for SSR prefetch and
-     * wires `onServerPrefetch` so the descendant awaits the activation
-     * promise before its render emits HTML.
-     *
-     * @internal Transform-emitted. Manual use is the documented escape
-     * hatch when the transform can't reach the reference (dynamic
-     * property access, untransformed bundlers).
-     */
-    readonly __ssrAccessed?: boolean;
-};
-/**
- * Access an existing form from a descendant component without passing
- * it through props. Counterpart to `useForm` — `useForm` creates and
- * provides; `injectForm` looks up via Vue's inject mechanism.
- *
- * Three ways to call it:
- *
- * ```ts
- * // Reach the nearest ancestor's anonymous useForm() call.
- * const form = injectForm<SignupShape>()
- *
- * // Reach a specific form by its key — works from anywhere in the app.
- * const cart = injectForm<CartShape>('cart')
- *
- * // Options form. The Vite transform emits this with `__ssrAccessed: true`
- * // when the descendant's template / script reads the form's reactive
- * // state, so the descendant participates in SSR prefetch coordination.
- * const cart = injectForm<CartShape>({ key: 'cart', __ssrAccessed: true })
- * ```
- *
- * Resolution rules (no-key form):
- * - Closest ambient ancestor wins.
- * - Only anonymous `useForm()` (no `key`) fills the ambient slot;
- *   keyed forms are reachable only via `injectForm(key)`.
- * - Inherits the resolved ancestor's `formInstanceId`.
- *
- * Resolution rules (keyed form): registry lookup by string key,
- * independent of component-tree position.
- *
- * Returns `null` when no matching form exists (no ambient ancestor, or
- * the named key isn't registered yet). A dev-mode warning points at the
- * call site, lists the registered keys, and flags the mount-timing case
- * (a form created by a child or sibling isn't registered until its own
- * setup runs). Always narrow before using:
- *
- * ```ts
- * const form = injectForm<Shape>('signup')
- * if (!form) return
- * form.register('email')
- * ```
- *
- * Pass the `Form` generic explicitly — Vue's provide/inject erases
- * generics, so the library can't recover the shape automatically.
- *
- * The form is kept alive for this component's lifetime; once every
- * consumer unmounts, the form is cleaned up automatically.
- */
-declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(input?: FormKey | InjectFormInput): UseFormReturnType<Form, GetValueFormType> | null;
-
-/**
- * Re-bind a parent's `v-register` onto an inner native element. Use
- * inside a component that wraps a single form field whose root is
- * NOT the input itself (e.g. a labelled-row that renders `<label>`
- * around the input).
- *
- * ```vue
- * <!-- Parent -->
- * <MyInput v-register="form.register('email')" />
- *
- * <!-- MyInput.vue -->
- * <script setup lang="ts">
- *   import { useRegister } from 'attaform'
- *   const rv = useRegister()
- *   // rv.path / rv.segments / rv.formKey / rv.formInstanceId / rv.innerRef
- *   // are all reachable directly — no `.value` unwrap.
- * </script>
- *
- * <template>
- *   <label class="field">
- *     <span>Email</span>
- *     <input v-register="rv" />
- *   </label>
- * </template>
- * ```
- *
- * Returns a hybrid Proxy: it answers `__v_isRef` / `.value` like a
- * Vue `Ref<RegisterValue | undefined>` (so templates auto-unwrap
- * correctly and `v-register="rv"` feeds the underlying RV to the
- * directive — preserving the directive's path-migration diff across
- * renders), AND every other property read pierces to the captured
- * RV's field (so `rv.path` works directly in script setup). Reads
- * inside reactive scopes (`computed` / `watchEffect`) track the
- * underlying `shallowRef`, so `rv.path` re-runs when the parent
- * rebinds to a different path.
- *
- * Unbound state: when the parent didn't pass `v-register`, every
- * piercing read returns `undefined` at runtime, and the return type
- * surfaces this honestly as `UseRegisterReturn<V> | undefined`.
- * Consumers defend with optional chaining (`rv?.formKey`,
- * `rv?.segments`); the directive accepts `undefined` peacefully (its
- * binding value type is already `RegisterValue<V> | undefined`), so
- * `v-register="rv"` works whether or not a parent has bound. The
- * composable's `onMounted` warn fires once per instance to surface
- * the misuse case at runtime.
- *
- * Diagnostic: in dev mode, a single `console.warn` fires per instance
- * at `onMounted` if the captured value is still `undefined` — by then
- * the parent has had its full mount lifecycle to bind, so a missing
- * binding is conclusive misuse. The warn does NOT fire on every read
- * of the proxy, and is intentionally silent under SSR
- * (`renderToString` skips `onMounted`); the CSR hydration pass
- * surfaces the same diagnostic without double-counting through Nuxt's
- * `dev:ssr-logs` channel.
- *
- * When the wrapper's root IS the input itself, Vue's attribute
- * fallthrough handles the binding and `useRegister` is unnecessary.
- * For wrappers that bind multiple fields (compound forms), use
- * `injectForm<Form>(key?)` and call `ctx.register(...)` directly.
- */
-
-/**
- * Return type of `useRegister()`. Hybrid of `RegisterValue<V>` (so
- * `rv.path` / `rv.segments` / `rv.formKey` etc. work directly in
- * script setup) and `Ref<RegisterValue<V> | undefined>` (so Vue's
- * template auto-unwrap surfaces the underlying RV to `v-register`
- * and the directive's path-migration diff sees the real RV across
- * renders).
- *
- * The two surfaces don't clash at the type level: `RegisterValue`
- * doesn't carry a `value` field, and `Ref<T>`'s `value: T` becomes
- * the hybrid's only `.value`. Older code that read `rv.value?.path`
- * keeps working; new code can write `rv.path` directly.
- */
-type UseRegisterReturn<V = unknown> = RegisterValue<V> & Ref<RegisterValue<V> | undefined>;
-declare function useRegister<V = unknown>(): UseRegisterReturn<V> | undefined;
-
-/**
- * Per-form display engine: owns the clock and the timers that the pure
- * `getDisplayState` reducer policy needs, so the reducer itself stays a
- * deterministic `(prev, ctx) => next` function.
- *
- * It keeps a `Map` of the machines that are still *active* (a spinner is
- * showing, a verdict is being held, or a `reviewAt` deadline is pending),
- * a single reactive `tick` ref, and a single `setTimeout` aimed at the
- * nearest `reviewAt` across every active field. When a field-state
- * computed reads `resolve`, it subscribes to `tick`; when the timer
- * fires, `tick` bumps and every dependent computed re-runs the reducer,
- * so a field whose deadline elapsed transitions (verdict → spinner, or
- * spinner → settled verdict) without any per-field watcher.
- *
- * Eviction: a machine is dropped once it reaches a terminal *idle* state
- * with no pending review. Error / success / pending machines are retained
- * so the reducer can hold the prior verdict under the show-delay window of
- * the *next* validation streak (no success → idle → success flicker). The
- * retained set is bounded by the rendered non-idle fields; none of them
- * arm a timer, so retention costs memory, never CPU.
- *
- * Untrusted reducer: `getDisplayState` is consumer-overridable, so the
- * engine treats the returned `reviewAt` as untrusted. A non-finite deadline
- * (NaN / ±Infinity from a custom predicate's bad arithmetic) is ignored
- * rather than handed to `setTimeout`, where it coerces to 0 and spins; an
- * over-large finite deadline is clamped below the 32-bit `setTimeout`
- * overflow; and the timer refuses to re-arm for the exact deadline it just
- * fired, so a predicate re-emitting a fixed or past `reviewAt` can't drive an
- * infinite fire loop. None of these arise from the library default, which
- * always advances its deadline or drops it.
- *
- * Background tabs: `setTimeout` is throttled to >= 1s while a tab is hidden,
- * so a min-visible hold can overshoot. A `visibilitychange` listener bumps
- * the clock on return to the foreground, so any overdue deadline resolves at
- * once instead of lingering.
- *
- * SSR: no clock, no timers, no listener. With `now` frozen and nothing
- * validating at render, the reducer returns the plain verdict (never
- * pending) and the engine stores nothing, so the server HTML and the
- * client's first render agree — no hydration mismatch on the display
- * projection.
- */
-type DisplayEngine = {
-    /**
-     * Resolve a path's next `DisplayMachine`. Subscribes the calling
-     * computed to the engine clock, threads the path's previous machine
-     * through `reducer`, persists or evicts the result, and re-arms the
-     * single timer to the nearest deadline.
-     */
-    resolve(key: PathKey, ctx: DisplayCtx, reducer: GetDisplayState): DisplayMachine;
-    /** Drop every retained machine and cancel the timer (used by `reset()`). */
-    clear(): void;
-    /** Tear down for good: `clear()` plus detaching the visibility listener. */
-    dispose(): void;
-    /** Introspection for tests: count of retained machines. */
-    size(): number;
-    /** Introspection for tests: whether a path currently has a retained machine. */
-    has(key: PathKey): boolean;
-    /** Introspection for tests: whether a deadline timer is currently armed. */
-    hasTimer(): boolean;
-};
-
-/**
- * Per-path field status. Replaced wholesale (not mutated in place) on
- * every change. Five semantic groups:
- *
- *   - `connected` — is a DOM element registered for this path?
- *   - `focused` / `blurred` — DOM-state flags. `null` while no element
- *     is connected (no DOM means the concepts don't apply); plain
- *     booleans once connected, with the invariant `blurred === !focused`
- *     enforced by `markFocused`.
- *   - `touched` — focus/blur history, not DOM state. Always a plain
- *     boolean: `false` at registration, sticky `true` after first blur,
- *     cleared only by `form.reset()` / `form.resetField(path)`. Persists
- *     across disconnects so v-if'd-away fields don't lose their touched
- *     state on rehide (wizard "show review of touched fields" patterns
- *     rely on this).
- *   - `interacted` — value-mutation history, not DOM state. Plain
- *     boolean: `false` at registration, sticky `true` once the user
- *     issues a value edit through the directive's input listeners
- *     (never on hydration, default seeding, or programmatic setValue);
- *     cleared with `touched` by `form.reset()` / `form.resetField(path)`.
- *   - `blurredAfterInteraction` — the first blur that follows a value
- *     edit (the field has been edited and then left). Plain boolean,
- *     sticky `true`. A tab-through blur with no prior edit does NOT set
- *     it (`interacted` is still false at that blur). Composes
- *     `interacted` with the departure; drives the default display gate.
- */
-type FieldRecord = {
-    readonly path: Path;
-    readonly updatedAt: string | null;
-    readonly connected: boolean;
-    readonly focused: boolean | null;
-    readonly blurred: boolean | null;
-    readonly touched: boolean;
-    readonly interacted: boolean;
-    readonly blurredAfterInteraction: boolean;
-};
-/** Per-path DOM element tracking. Client-only. */
-type ElementRecord = {
-    /**
-     * Original Path captured at first registration. Stored alongside the
-     * elements Set so the DOM-order sort cache can recover the structured
-     * Path without round-tripping through `JSON.parse(pathKey)`.
-     */
-    readonly path: Path;
-    readonly elements: Set<HTMLElement>;
-};
-/**
- * Per-path record stored in `originals`. Pairing `segments` with the tracked
- * value means `dirty` and `resetField`'s container loop don't have to
- * `JSON.parse(pathKey)` on every iteration — the canonical Path is already
- * sitting next to the value it belongs to. PathKey still keys the Map (the
- * stable string is the only collision-free identifier), but downstream
- * iteration reads `segments` directly.
- */
-type OriginalsRecord = {
-    readonly segments: Path;
-    readonly value: unknown;
-};
-
-/**
- * Schema-driven coercion of user-typed DOM values at the v-register
- * directive layer. When the slim schema declares a numeric or
- * boolean type at a path, the directive coerces incoming string
- * values (`'25'` → `25`, `'true'` → `true`) before the slim-primitive
- * gate sees the write — making the schema authoritative for storage
- * shape and freeing consumers from sprinkling `.number` modifiers
- * across templates.
- *
- * Coercion is consumer-extensible: a `CoercionRegistry` is just an
- * `Array<CoercionEntry>` keyed at config time by `(input, output)`
- * `SlimPrimitiveKind` literals. The library ships
- * `defaultCoercionRules` (string→number, string→boolean) and
- * `defineCoercion` for type-narrowed authoring; consumers spread the
- * defaults to extend or supply their own array to replace.
- *
- * Coercion applies ONLY to user-typed DOM values flowing through
- * the directive's assigner. Programmatic writes (`form.setValue`,
- * `setValueWithInternalPath`) bypass coercion — they're authoritative
- * writes whose strict typing is on the caller. This mirrors the
- * `transforms` pipeline's user-input-only contract.
- */
-
-/**
- * Type-narrowing helper for authoring entries. At runtime it's
- * identity; at compile time it preserves the `input` / `output`
- * literal types so `transform`'s parameter is narrowed to the
- * runtime type instead of widening to `SlimRuntimeOf<SlimPrimitiveKind>`.
- *
- * Without this helper, authoring `{ input: 'string', output:
- * 'number', transform: (s) => ... }` against the broader
- * `CoercionEntry` widens `s` to `string | number | boolean | ...`,
- * forcing a cast in every transform body. `defineCoercion` is the
- * opaque-free idiom.
- */
-declare function defineCoercion<I extends SlimPrimitiveKind, O extends SlimPrimitiveKind>(entry: CoercionEntry<I, O>): CoercionEntry<I, O>;
-/**
- * Internal index built from a `CoercionRegistry` at config-resolve
- * time. Keyed by `${input}->${output}` for O(1) per-keystroke
- * dispatch. The authoring shape (array, ergonomic, type-narrowing-
- * friendly) and the dispatch shape (Map, fast) decouple cleanly.
- */
-type CoercionIndex = ReadonlyMap<`${SlimPrimitiveKind}->${SlimPrimitiveKind}`, CoercionEntry>;
-/**
- * The library's built-in registry. Two cells: string→number and
- * string→boolean. Re-exported so consumers can spread it when
- * supplying a custom registry that extends defaults.
- */
-declare const defaultCoercionRules: CoercionRegistry;
-
-type FormStore<F extends GenericForm, G extends GenericForm = F> = {
-    readonly formKey: FormKey;
-    readonly form: Ref<F>;
-    readonly fields: Map<PathKey, FieldRecord>;
-    readonly elements: Map<PathKey, ElementRecord>;
-    /**
-     * Schema-driven errors. Written ONLY by the schema validation pipeline:
-     * `scheduleFieldValidation`, `handleSubmit`, the construction-time seed,
-     * history restore, and hydration. Cleared by `reset` / `resetField` and by
-     * a successful submit. `setErrors` / `clearErrors` do NOT touch this Map.
-     */
-    readonly schemaErrors: Map<PathKey, ValidationError[]>;
-    /**
-     * User-injected errors. Written ONLY by the `setErrors` / `clearErrors`
-     * API surface (and history / hydration replay). Survives schema revalidation and
-     * successful submits — the consumer owns its lifetime explicitly.
-     */
-    readonly userErrors: Map<PathKey, ValidationError[]>;
-    /**
-     * Reactively-derived "No value supplied" errors. Pure function of
-     * `(blankPaths, schema.isRequiredAtPath)` — no writers, no clears.
-     * Membership tracks `blankPaths` automatically: typing a value into
-     * a blank required numeric field removes the path from `blankPaths`
-     * and the derived error vanishes; clearing the numeric input re-adds
-     * the path and the error reappears. The `errors` proxy and
-     * `getErrorsForPath` merge this map in alongside `schemaErrors` and
-     * `userErrors`, so consumers see the "this required field is empty"
-     * error the moment it's true — no `validate()` / `handleSubmit`
-     * call required. Honors the founding principle that
-     * `errors = f(schema, state)`.
-     *
-     * Most entries flow through this map for `number` / `bigint` leaves
-     * (where the side-channel is needed to distinguish "user typed 0"
-     * from "user supplied nothing"). String / boolean leaves only land
-     * here when the consumer explicitly opted in via the `unset`
-     * sentinel — see `docs/validation/blank.md`.
-     */
-    readonly derivedBlankErrors: ComputedRef<ReadonlyMap<PathKey, ValidationError[]>>;
-    readonly originals: Map<PathKey, OriginalsRecord>;
-    /**
-     * Reactive set of paths whose displayed state should be EMPTY even
-     * though storage holds a real, schema-conformant value (the slim
-     * default). It exists exclusively to record **storage / display
-     * divergence** — the case where the runtime can't tell "user typed
-     * 0" from "user supplied nothing" by looking at storage alone.
-     *
-     * The mechanism shines for `number` / `bigint`: storage holds the
-     * slim default (`0` / `0n`) but the DOM input shows `''`, so the
-     * directive's input listener marks the path here on clear. Strings
-     * and booleans don't need it — `''` storage equals `''` display,
-     * `false` storage equals unchecked display — so they're never
-     * auto-marked. Consumers can still mark any primitive leaf
-     * explicitly via the `unset` sentinel (`defaultValues: { x: unset }`,
-     * `setValue('x', unset)`, `reset({ x: unset })`); the mark is then
-     * a documented signal of consumer intent rather than runtime
-     * inference.
-     *
-     * Reads (`displayValue` computed, `fields.<path>.blank`,
-     * `derivedBlankErrors` computed) track via Vue 3.5's reactive Set
-     * handlers. Writes happen inside `setValueAtPath` (gate-hook
-     * bookkeeping: `blank: true` meta adds the path; any other write
-     * removes it) and `reset`.
-     *
-     * Storage NEVER reflects this set — calculations and reads against
-     * `form.value` see the slim default. The set is purely a UI/intent
-     * channel that `derivedBlankErrors` consults to surface
-     * "No value supplied" errors for required schemas.
-     *
-     * See `docs/validation/blank.md` for the conceptual model.
-     */
-    readonly blankPaths: Set<PathKey>;
-    /**
-     * Snapshot of `blankPaths` captured at construction (and
-     * re-captured on `reset(args)`). Used by dirty calculation: a path
-     * whose membership differs from the snapshot is dirty even if
-     * storage matches the original. Eagerly populated to avoid a "dirty
-     * on first read" race after construction.
-     */
-    readonly originalBlankPaths: Set<PathKey>;
-    readonly schema: AbstractSchema<F, G>;
-    /**
-     * Server-side flag, plumbed in from `registry.ssr`. The
-     * `register()`-returned `markConnectedOptimistically()` reads this
-     * before flipping `connected: true`; on the client it's a no-op so
-     * the eventual directive lifecycle remains the source of truth.
-     */
-    readonly ssr: boolean;
-    /**
-     * Resolved `getDisplayState` predicate driving `field.displayState`,
-     * the `show*` booleans, and their `form.meta` rollups. Resolved once
-     * at construction via `resolveGetDisplayState(options.getDisplayState)`;
-     * `undefined` config falls through to `defaultDisplayState`. The
-     * field-state computeds read the resolved function directly on every
-     * read.
-     */
-    readonly getDisplayState: GetDisplayState;
-    /**
-     * Per-form display engine: owns the clock and the single timer the timed
-     * `getDisplayState` reducer policy needs, keeping the reducer itself a
-     * pure `(prev, ctx) => next` function. The field-state computeds route
-     * every `displayState` read through `displayEngine.resolve(...)`, which
-     * threads the path's previous machine, persists or evicts the result, and
-     * re-arms the nearest-deadline timer. Constructed once at form
-     * construction; torn down via `registerCleanup` on store eviction.
-     */
-    readonly displayEngine: DisplayEngine;
-    readonly submitting: Ref<boolean>;
-    readonly activeSubmissions: Ref<number>;
-    readonly submissionAttempts: Ref<number>;
-    /**
-     * `true` once a `handleSubmit` callback resolved without throwing.
-     * Independent of `submissionAttempts` — a failed submit increments
-     * attempts but leaves `submitted` at `false`. Cleared by `reset()`
-     * alongside the rest of the submission surface.
-     */
-    readonly submitted: Ref<boolean>;
-    readonly submitError: Ref<Error | null>;
-    readonly departAttempts: Ref<number>;
-    /**
-     * 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 this `true` for a
-     * locked step's member form; ORed into `effectiveDisabled` so the
-     * wizard lock is authoritative and a member form cannot escape it by
-     * passing `disabled: false`. Default `false`.
-     */
-    readonly externalLock: Ref<boolean>;
-    /**
-     * `true` while a function-form `defaultValues` factory is in flight.
-     * Stays `false` for plain-value `defaultValues`. Shared across every
-     * `useForm({ key })` call that resolves to this store — the second
-     * caller sees the first caller's hydration state.
-     */
-    readonly hydrating: Ref<boolean>;
-    /**
-     * Error from the most recent function-form `defaultValues` factory.
-     * Normalized to a `ValidationError` (code `atta:hydration-failed`) so the
-     * shape matches `form.errors` / `form.meta.errors` entries. `null` when
-     * no factory has fired or the last one succeeded.
-     */
-    readonly hydrateError: Ref<ValidationError | null>;
-    /**
-     * The function-form `defaultValues` factory, captured at the first
-     * `useForm({ key })` call that wired this store. `undefined` for
-     * plain-value forms. Read by `form.rehydrate()`.
-     */
-    readonly defaultValuesFactory: Ref<(() => unknown | Promise<unknown>) | undefined>;
-    /**
-     * `true` when this store carries an SSR prefetch queue (server path
-     * where `state.activate()` must enqueue intent before deciding
-     * whether to fire). The flag lets `buildFormApi` skip the lazy
-     * activation gate for forms with no factory AND no SSR prefetch —
-     * the common client-side case where `gated()` is otherwise pure
-     * reactive overhead on every public method call.
-     */
-    readonly hasSsrPrefetch: boolean;
-    /**
-     * `true` once the form's effective defaults have been applied —
-     * sync `defaultValues` at construction, or async factory whose
-     * settle completed. Stays `false` for dormant lazy forms until they
-     * activate. Read by `useWizard` to decide whether seed status or
-     * live meta should surface.
-     */
-    readonly defaultsResolved: Ref<boolean>;
-    /**
-     * `true` once the captured async factory has been kicked off (set
-     * synchronously by `activate()`, before the factory itself resolves).
-     * Distinct from `defaultsResolved`, which only flips after the factory
-     * settles. The pair lets the API surface tell "we've started" apart
-     * from "we're done."
-     */
-    readonly activated: Ref<boolean>;
-    /**
-     * In-flight activation promise. Concurrent callers (cross-component
-     * SSR consumers, recursive factory reads, parallel `activate()`
-     * calls) receive the same promise, ensuring the factory runs once
-     * even under contention.
-     */
-    readonly activationPromise: Ref<Promise<void> | undefined>;
-    /**
-     * Idempotent activation entrypoint. Fires the captured function-form
-     * `defaultValues` factory on first call and stores the in-flight
-     * promise. Subsequent calls return the same promise until the factory
-     * settles; thereafter calls return `Promise.resolve()`. Plain-value
-     * forms (no factory captured) always return a resolved promise. The
-     * public API surface routes all reactive interactions (getters and
-     * methods, except `key`) through this entrypoint so the form
-     * activates on first use.
-     */
-    activate(): Promise<void>;
-    /**
-     * Re-fire the captured function-form `defaultValues` factory. Throws
-     * synchronously when no factory was captured (plain-value form).
-     * Resolves after `hydrating` flips back to `false`; consumers can
-     * `await form.rehydrate()` to gate UI on the fresh load.
-     *
-     * Does NOT touch dirty / touched / submit state — chain
-     * `form.reset()` if you want a clean baseline.
-     */
-    rehydrate(): Promise<void>;
-    /**
-     * Incremented by every `reset()` call. The submit wrapper captures
-     * this at entry and skips writing `submitError` from a catch that
-     * fires *after* a reset — otherwise a reset-during-submit would
-     * visibly clear `submitError` and then have it reappear when the
-     * in-flight promise rejects.
-     */
-    readonly submissionGeneration: Ref<number>;
-    /**
-     * Counts in-flight validation calls across every `validate()` ref and
-     * every `validateAsync(...)` / `handleSubmit` pre-check. `validating`
-     * on the public API mirrors `activeValidations.value > 0`. Tracked
-     * separately from submissions because a validate-while-submitting
-     * (e.g. a debounced field check overlapping a submit) needs to show
-     * the union of both surfaces.
-     */
-    readonly activeValidations: Ref<number>;
-    /**
-     * `true` once the form has completed at least one validation pass
-     * — flips when `activeValidations` returns to 0 from any positive
-     * value. Until that happens, `meta.valid` and `field.valid` report
-     * `false` even when `schemaErrors.size === 0`, because the absence
-     * of errors at frame 1 is just "we haven't checked yet," not "we
-     * checked and it's clean."
-     *
-     * This closes the brief flash window for schemas where the slim
-     * default-derivation parse strips refinements (`.refine`,
-     * `.superRefine`, async validators): the slim parse passes, no
-     * construction-time errors land, and the queued microtask hasn't
-     * run yet — so without the gate, frame 1 paints the form as
-     * "valid" before the real verdict arrives a tick later.
-     *
-     * Initialized to `!strict`: non-strict consumers opt out of the
-     * validation pipeline by design, so locking them on
-     * `firstValidationDone === false` would defeat the opt-out.
-     * Reset is left untouched — the post-reset validation flips it
-     * back true on completion, same as the construction-time path.
-     */
-    readonly firstValidationDone: Ref<boolean>;
-    /**
-     * `true` when the sub-schema rooted at `path` (or any of its
-     * descendants) declares async work — composes
-     * `schema.getSchemasAtPath(path)` with each candidate's
-     * `needsAsyncValidation()`, memoised per canonical path key for
-     * the lifetime of the FormStore. Used by `meta.valid` /
-     * `field.valid` to skip the `firstValidationDone` gate on subtrees
-     * that are fully synchronous: their verdict resolves at construction
-     * (or on the next per-field run) without waiting on a microtask, so
-     * honouring the form-wide gate would just play dumb about a known
-     * answer.
-     */
-    pathHasAsyncValidation(path: Path): boolean;
-    /**
-     * Precomputed-key shortcut for `pathHasAsyncValidation`. The
-     * canonical key is required and must correspond to `segments`; the
-     * helper skips the `canonicalizePath` round-trip so descendant-walk
-     * loops (whose Map iteration already yields the canonical key) can
-     * read the async-gate verdict without a per-leaf canonicalize.
-     */
-    pathHasAsyncValidationByKey(key: PathKey, segments: Path): boolean;
-    /**
-     * Per-path counter of in-flight field-level validation runs.
-     * `field.validating` on `FieldState` mirrors
-     * `(fieldValidationCounts.get(key) ?? 0) > 0`.
-     *
-     * Incremented at the same point as `activeValidations` inside
-     * `scheduleFieldValidation`'s `run` closure (right before the schema
-     * call) and decremented in the matching `.finally` — so the per-path
-     * bookkeeping is exactly co-extensive with the form-wide counter for
-     * the field-scheduled branch. Whole-form `validate()` /
-     * `validateAsync()` runs touch `activeValidations` only; they don't
-     * have a single field path and so don't contribute here.
-     *
-     * Counter (not Set) because two runs for the same path can briefly
-     * overlap: when an in-flight run is aborted and a new run starts,
-     * the new run increments before the aborted run's `.finally`
-     * decrements. With `> 0` semantics the field stays "validating"
-     * across the abort/restart boundary.
-     *
-     * Reactive Map: Vue 3's `reactive(new Map())` proxy makes `.get()`,
-     * `.has()`, and `.size` track per-key, so the FieldState
-     * computed only re-runs when the count for ITS key changes.
-     */
-    readonly fieldValidationCounts: Map<PathKey, number>;
-    /**
-     * Per-path `Date.now()` stamp marking when the field's LATEST validation
-     * run started, re-anchored on every run start (every increment), deleted
-     * on the `→ 0` edge. The display reducer reads it as `ctx.validatingSince`
-     * to time the anti-flash spinner, which measures `now - validatingSince`:
-     * re-anchoring on each run means a burst of keystrokes (each aborting the
-     * prior run and starting a new one) keeps pushing the stamp forward, so the
-     * spinner stays suppressed until the user pauses rather than surfacing
-     * mid-typing. Anchoring only at the streak start would pin it to the first
-     * keystroke, because with `debounceMs: 0` the aborted run's decrement lands
-     * after the next run's increment and the count never returns to 0 between
-     * fast keystrokes. The field-state container walk takes the descendant-min
-     * so a row spinner anchors at its earliest still-active leaf. Runtime-only,
-     * never hydrated, like the counts. REACTIVE: the display computed reads this
-     * (as `ctx.validatingSince`) but not the `validating` flag, and a long
-     * validation that settles with an unchanged verdict (same error, still
-     * invalid) leaves `errors` / `valid` untouched — so a non-reactive map would
-     * leave a held `pending` spinner stranded after the run ends, until some
-     * unrelated reactive change happened to re-run the computed. Reactivity ties
-     * the computed to both the streak start (set) and end (delete).
-     */
-    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`. Counter, not flag, for the
-     * same overlap reason as `fieldValidationCounts`, except a superseding
-     * input releases the prior run synchronously before incrementing the
-     * new one — so the count is the live in-flight depth at the path
-     * (effectively 0 or 1). Reactive Map, like the validation counters.
-     */
-    readonly fieldTransformCounts: Map<PathKey, number>;
-    /**
-     * Per-path `ssr ? 0 : Date.now()` stamp marking when the path's latest
-     * async transform opened; the display reducer reads it (as
-     * `ctx.transformingSince`) to time the gated busy spinner. Mirrors
-     * `fieldValidatingSince` exactly: re-anchored on each run start,
-     * deleted on the `→ 0` edge, reactive for the held-spinner reason.
-     */
-    readonly fieldTransformingSince: Map<PathKey, number>;
-    /**
-     * Per-path latest async-transform failure (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 separate from validation `errors`.
-     */
-    readonly transformErrors: Map<PathKey, Error | null>;
-    /**
-     * Form-wide count of in-flight async-transform runs. Drives the
-     * `settleTransforms` quiescence guard and the `handleSubmit` drain
-     * barrier. `Math.max(0, …)`-clamped on release so a doubled decrement
-     * (a run's own `endTransform` after a synchronous cancel release)
-     * can't drive it negative.
-     */
-    readonly activeTransforms: Ref<number>;
-    /**
-     * Replace the form value wholesale. Optional `meta` is forwarded to
-     * every `onFormChange` listener so they can decide whether THIS write
-     * is one they care about (e.g. history tagging a hydration replay).
-     */
-    applyFormReplacement(next: F, meta?: WriteMeta): void;
-    /**
-     * Set a single path's value. `meta` is forwarded to listeners via
-     * `applyFormReplacement` (see above). Public `form.setValue` passes no
-     * meta.
-     *
-     * Returns `false` when the slim-primitive gate rejects the write
-     * (the value's primitive shape doesn't match the schema's slim
-     * shape at the path). The store is unchanged in that case.
-     */
-    setValueAtPath(path: Path, value: unknown, meta?: WriteMeta): boolean;
-    getValueAtPath(path: Path): unknown;
-    /**
-     * Stable identity for the array element at `path`. An array element
-     * (numeric last segment) carries its allocated identity token,
-     * maintained by `array-identity.ts` across structural mutations.
-     * Empty for any non-array-element path: a record entry, a
-     * fixed-object field, a container, or 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 `schemaErrors` under `path` with `errors`, keying each
-     * error by its OWN absolute path. Used by validation pipelines
-     * (scheduleFieldValidation, validateAsync, handleSubmit, reset)
-     * to commit a parse result wholesale — entries not in the new
-     * pass get dropped from the subtree, surviving keys update in
-     * place to preserve insertion order. Pass `path === []` for the
-     * whole-form scope.
-     */
-    applySchemaErrorsForSubtree(path: Path, errors: ValidationError[]): void;
-    setAllUserErrors(errors: readonly ValidationError[]): void;
-    setUserErrorsForPath(path: Path, errors: readonly ValidationError[]): void;
-    clearUserErrors(path?: Path): void;
-    /**
-     * Merged read — returns `[...schemaErrors[path], ...userErrors[path]]`.
-     * Schema errors come first (structural validation before business logic),
-     * matching the iteration order for `getFirstErrorElement` and the
-     * top-level `errors` drillable Proxy.
-     */
-    getErrorsForPath(path: Path): ValidationError[];
-    /**
-     * Returns a stable schema-declaration ordinal for `key`, assigning a
-     * fresh one if the path hasn't been seen before. Drives
-     * `form.meta.errors` sort order so the aggregate is a function of the
-     * SET of errors currently present (not the temporal order their
-     * Map keys were last `set`). Construction-time seed walks every leaf
-     * in the schema's slim default; runtime callers (DU variant 2, dynamic
-     * array indices, refines targeting cross-field paths) pick up
-     * first-encounter ordinals and keep them for the form's lifetime.
-     */
-    ensurePathOrdinal(key: PathKey): number;
-    /**
-     * Register `element` as a binding for `path`, tagged with the calling
-     * `useForm()` instance's `formInstanceId`. The ID is the disambiguator
-     * used by `getFirstErrorElement` to scope focus / scroll to elements
-     * THIS form instance owns — important when two `useForm()` calls share
-     * a `key` (e.g. sidebar + main rendering the same form), since both
-     * write into one shared element store.
-     */
-    registerElement(path: Path, element: HTMLElement, formInstanceId: string): boolean;
-    deregisterElement(path: Path, element: HTMLElement): number;
-    /**
-     * Optional `meta.instance` carries per-`useForm()`-instance overrides
-     * for `validateOn` / `debounceMs` so the blur-trigger respects the
-     * caller's config when sibling instances share a FormStore.
-     */
-    markFocused(path: Path, focused: boolean, meta?: {
-        readonly instance?: WriteMeta['instance'];
-    }): void;
-    /**
-     * Flip `interacted: true` on a leaf — the sticky value-mutation flag.
-     * Driven by the directive's input listeners (via the RegisterValue's
-     * `markInteracted`); idempotent, never set by programmatic writes.
-     */
-    markInteracted(path: Path): void;
-    /**
-     * Walk every active-variant leaf under `segments` and flip
-     * `touched: true`. Powers `form.touch(path?)`. Idempotent;
-     * does not mutate value / focused / blurred or trigger validation.
-     */
-    touchAtPath(segments: Path): void;
-    /**
-     * SSR-only optimistic mark: flip `connected: true` on the field
-     * record without an actual DOM element. Called by the `vRegisterHint`
-     * compile-time transform via `RegisterValue.markConnectedOptimistically()`
-     * for every element rendered with `v-register`. Idempotent + no-op on
-     * the client (the directive's `created` hook is the authoritative
-     * source there).
-     */
-    markConnectedOptimistically(path: Path): void;
-    /**
-     * Client-side connected mark for a `v-register` component host that binds
-     * value via the v-model channel but has no single inner control to latch
-     * (a composite widget, or none found). The directive calls it on mount
-     * (`true`) and unmount (`false`). Distinct from the SSR-only
-     * `markConnectedOptimistically`; idempotent on the leading edge.
-     *
-     * `hostEl` (the host root) is recorded on connect as this path's
-     * focus-first-error anchor, scoped to `formInstanceId` the same way a
-     * registered control is. A no-latch host enters no `elements` record, so
-     * without this it is absent from `getFirstErrorElement`'s walk; the anchor
-     * lets that walk resolve a focus target from the host subtree.
-     */
-    markHostConnected(path: Path, connected: boolean, hostEl: HTMLElement, formInstanceId: string): void;
-    /**
-     * Leaf-only pristine check. `originals` is populated via
-     * `diffAndApply`'s `added` patches, which fire only on primitive
-     * leaves — a container path (e.g. `['profile']`) that isn't in
-     * `originals` returns `true` here even when a descendant is dirty.
-     * Callers that need container semantics should either loop over
-     * leaves or walk `originals` manually. The public `getFieldState`
-     * surface is typed to accept leaf paths only, so in practice this
-     * isn't exposed to consumers.
-     */
-    isPristineAtPath(path: Path): boolean;
-    /**
-     * Precomputed-key shortcut for `isPristineAtPath`. The canonical
-     * key is required and must correspond to `segments`; the helper
-     * skips the `canonicalizePath` round-trip so descendant-walk loops
-     * (whose Map iteration already yields the canonical key) can read
-     * the pristine verdict without a per-leaf canonicalize.
-     */
-    isPristineAtPathByKey(key: PathKey, segments: Path): boolean;
-    /**
-     * Whether any tracked array under `path` has changed shape — a reorder,
-     * insert, or removal — relative to 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 can
-     * no longer see the shape change.
-     */
-    hasStructuralChangeUnder(path: Path): boolean;
-    /**
-     * Whether a baseline-present container under `path` was replaced wholesale by
-     * a non-container (e.g. `setValue('profile', undefined)`) and is still absent.
-     * The other half of removal-driven `dirty`: such a subtree's leaves vanish
-     * from the live value, so neither the present-leaf walk nor the array tracker
-     * can see the loss. Self-filters by current liveness, so a refilled path stops
-     * counting.
-     */
-    hasRemovedSubtreeUnder(path: Path): boolean;
-    getFieldRecord(path: Path): FieldRecord | undefined;
-    getOriginalAtPath(path: Path): unknown;
-    /**
-     * Returns the first errored field's first connected, visible DOM
-     * element scoped to `formInstanceId` — the target that
-     * `focusFirstError` / `scrollToFirstError` act on. "First" is
-     * VISUAL-first (DOM-tree order via `compareDocumentPosition`), not
-     * schema-declaration order, so a field rendered above another in the
-     * template focuses first regardless of which one the schema declared
-     * earlier. CSS `order:` flexbox/grid reordering is NOT respected
-     * (DOM-tree order wins) — documented as a tradeoff against forcing
-     * sync layout on every comparison.
-     *
-     * The `formInstanceId` filter scopes focus to elements registered
-     * through THIS form instance. When two `useForm({ key })` calls share
-     * a key, both register into the same element store; without the
-     * filter, the sidebar form's submit could focus the main form's
-     * input. With it, each `useForm()` callsite focuses only its own
-     * elements.
-     *
-     * Returns `null` when every errored path has no currently-attached
-     * element registered to this instance (fields behind `v-if="false"`,
-     * unmounted components, or a hidden `display:none` parent). Callers
-     * get the choice of no-op or a dev-only warning.
-     */
-    getFirstErrorElement(formInstanceId: string): {
-        path: Path;
-        element: HTMLElement;
-    } | null;
-    /**
-     * Cancel every in-flight field-level validation run — clears timers
-     * for debounced 'change' runs that haven't fired, latches `aborted`
-     * for runs whose async parse is in flight. Called by `handleSubmit`
-     * at entry (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`, register `holder` for later abort. Returns the run
-     * token. See `InternalRegisterValue.beginTransform`.
-     */
-    beginTransform(key: PathKey, holder: TransformAbortHolder): number;
-    /** `true` while `token` is the live async-transform run at `key`. */
-    isCurrentTransform(key: PathKey, token: number): boolean;
-    /**
-     * Close the run `token` at `key`: release the counters (no-op if the
-     * run was already released by a supersede / cancel) and flush settled
-     * `settleTransforms` waiters.
-     */
-    endTransform(key: PathKey, token: number): void;
-    /** Record a per-field normalization failure at `key` (`field.transformError`). */
-    setTransformError(key: PathKey, err: Error): void;
-    /**
-     * Abort + release every in-flight async-transform run (all paths) and
-     * clear `transformErrors`. Mirrors `cancelFieldValidation`; called by
-     * `reset()` and store teardown.
-     */
-    cancelTransforms(): void;
-    /**
-     * Path-scoped counterpart to `cancelTransforms`: abort + release only
-     * the runs at-or-under `prefix`, clearing their `transformError`.
-     * Called by `resetField`.
-     */
-    cancelTransformsUnder(prefix: Path): void;
-    /**
-     * Resolve once async transforms are quiescent — globally (`path`
-     * omitted) or at-or-under `path`. Resolve-never-reject. See
-     * `UseFormReturnType.settleTransforms`.
-     */
-    settleTransforms(path?: string | Path): Promise<void>;
-    /**
-     * Kick off (or schedule) a field-level validation run for `path`. Pass
-     * `path = []` to cover the whole form; `applySchemaErrorsForSubtree`
-     * then wipes every `schemaErrors` entry and replaces them with the
-     * adapter's full async response. Used by persistence's post-hydration
-     * revalidation and by the construction-time async-refine seed.
-     *
-     * `immediate: true` skips the debounce window — the runtime kicks off
-     * the adapter call on the next microtask. Internal callsites use this
-     * for one-shot triggers; the per-keystroke writers pass `false` to
-     * coalesce rapid mutations under the configured debounceMs.
-     *
-     * `override` carries per-`useForm()`-instance values: when provided,
-     * the scheduler honors `override.mode` instead of the store's
-     * captured `validateOn`, and `override.debounceMs` instead of the
-     * store's captured `debounceMs`. Used so sibling instances sharing a
-     * FormStore can each validate on their own cadence.
-     */
-    scheduleFieldValidation(path: Path, immediate: boolean, override?: {
-        readonly mode?: ValidateOn;
-        readonly debounceMs?: number;
-    }): void;
-    /**
-     * Subscribe to every `applyFormReplacement`. Fires synchronously
-     * after `form.value` has been swapped to `next` and all field /
-     * originals bookkeeping has run. Used by undo/redo to hook the single
-     * mutation funnel. The optional `meta` carries the originating call
-     * site's intent; subscribers that don't care about meta can ignore the
-     * parameter. Returns an unsubscribe function.
-     */
-    onFormChange(listener: (next: F, meta?: WriteMeta) => void): () => void;
-    /**
-     * Subscribe to successful submissions. Fires after the consumer's
-     * `onSubmit` callback has resolved — not on validation failure,
-     * not on callback throw. The DevTools panel rides this to surface a
-     * submit event. Returns an unsubscribe function.
-     */
-    onSubmitSuccess(listener: () => void): () => void;
-    /**
-     * Subscribe to `reset()` calls. Fires AFTER reset has replaced
-     * the form and cleared errors + lifecycle, so listeners see the
-     * fresh post-reset state. Used by the history module to drop the
-     * undo/redo stack on reset. Returns an unsubscribe function.
-     */
-    onReset(listener: () => void): () => void;
-    /**
-     * Internal: notify submit-success subscribers. Called by
-     * `handleSubmit` in `process-form.ts` once the user callback has
-     * resolved. Consumers shouldn't call this directly.
-     */
-    emitSubmitSuccess(): void;
-    /**
-     * Register a teardown function whose lifetime is bound to the
-     * FormStore itself (not a consumer's Vue effect scope). Called by
-     * `dispose()` when the last consumer unmounts. Used by persistence /
-     * history wiring so their subscribers aren't detached prematurely
-     * when only the first consumer unmounts but others remain.
-     */
-    registerCleanup(fn: () => void): void;
-    /**
-     * Register an async drain function. Called by the registry before
-     * `dispose()` so async background work — chiefly the persistence
-     * layer's debounced storage writes — has a chance to settle without
-     * losing the last keystroke. Each registered function is awaited in
-     * parallel; failures are swallowed to keep eviction reliable.
-     */
-    registerDrain(fn: () => Promise<void>): void;
-    /**
-     * Drain async work registered via `registerDrain`. Resolves once
-     * every registered drain has settled (in parallel). Safe to call
-     * repeatedly — registered drains decide their own idempotency.
-     */
-    awaitPendingWrites(): Promise<void>;
-    /**
-     * Cache for per-state modules (history, persistence) that must
-     * outlive any single consumer. Subsequent `useForm` / `injectForm`
-     * calls for the same key read from this map so the public API shape
-     * is identical regardless of mount order. Keyed by a string identifier
-     * owned by the caller (e.g. `'history'`).
-     */
-    readonly modules: Map<string, unknown>;
-    /**
-     * Resolved schema-coercion index — the merged config from
-     * `createAttaform({ defaults: { coerce } })` ∪ `useForm({ coerce })`,
-     * keyed by `${input}->${output}` for O(1) per-keystroke dispatch.
-     * Empty Map when coercion is disabled. Read at `register()` time
-     * by `buildCoerceFn` to bake the per-path coerce closure on
-     * `RegisterValue.coerce`.
-     */
-    readonly coerceIndex: CoercionIndex;
-    /**
-     * Tear down non-reactive resources owned by this FormStore. Invoked
-     * by the registry when the last consumer unmounts. Cancels pending
-     * field-validation timers, drops every subscriber, and fires each
-     * cleanup hook registered via `registerCleanup`.
-     */
-    dispose(): void;
-};
-
-/**
- * Public types for `useWizard` — the multistep-form orchestrator.
- *
- * The wizard is built around an ordered list of step slots. Each slot
- * resolves to a participating form: an existing `useForm` reference, a
- * bare string key (desugared to a noop form so affordance steps
- * participate uniformly), an eagerly-evaluated function slot for
- * runtime branching, or a `lazy()`-wrapped function slot that caches
- * its resolution and re-fires only on its own tracked deps.
- *
- * The wizard surface is loosely keyed (`Record<FormKey, …>`).
- * Cross-component flows threaded through `injectWizard` lose lexical
- * key knowledge anyway, so the public read surface is a string-keyed
- * record. Typed per-form access flows back through the original form
- * refs and through `wizard.handleSubmit`'s `ctx.get(formRef)` accessor.
- */
-
-/**
- * Minimum structural shape the wizard requires from a participating
- * form. Constraining to the full `UseFormReturnType` would force
- * contravariant unification of the storage / read shapes across all
- * steps; the wizard does not care about those — it routes by `key` at
- * runtime and exposes the original form objects untouched.
- */
-type AnyForm = {
-    readonly key: FormKey;
-};
-/**
- * Per-form summary surface — what `wizard.statuses[key]` exposes (and
- * what `defaultStatuses` seeds). Distinct from `form.meta`: `FormStatus`
- * is the cross-step rollup optimized for template ergonomics
- * (`{{ wizard.statuses.cargo.valid }}`), while `form.meta` carries the
- * full per-form lifecycle surface.
- *
- * Field semantics:
- *  - `valid` — `form.meta.valid`. `false` while errors exist or while
- *    the first-validation-done gate has not flipped.
- *  - `dirty` — `form.meta.dirty`. `true` once any value differs from
- *    the original defaults.
- *  - `submitted` — `form.meta.submitted`. `true` once a `handleSubmit`
- *    callback has resolved without throwing. A failed submit
- *    (validation or callback rejection) leaves this `false`;
- *    `submissionAttempts > 0` is the "user has tried" signal.
- *  - `errorCount` — `form.meta.errorCount`. Count of active validation
- *    errors (zero when valid).
- *  - `locked`: `true` when this step sits after an uncleared gate. Its
- *    member form is frozen (data writes no-op) and navigation to it is
- *    refused, so a stepper can render it as an unreachable step. `false`
- *    when no gate seals it. Orthogonal to `gate`: the first uncleared
- *    gate reads `locked: false` (you must reach it to clear it), while a
- *    later gate sealed behind it reads both `gate: 'uncleared'` and
- *    `locked: true`.
- *  - `gate`: this step's own role as a hard prerequisite. `null` when the
- *    step is not a `gate()`; `'uncleared'` while its member form is
- *    unconfirmed (so it seals every later step); `'cleared'` once
- *    confirmed by a clean member submit or seeded cleared via
- *    `defaultStatuses`. Reflects the live compiled shape, so a conditional
- *    `gate()` that a function slot drops resolves to `null`.
- *
- * Noop forms generated for string slots surface as default-valid
- * (`{ valid: true, dirty: false, submitted: false, errorCount: 0, locked: false, gate: null }`),
- * unless the string slot is a `gate('...')`, whose `gate` tracks the
- * in-session acknowledgment.
- */
-type FormStatus = {
-    readonly valid: boolean;
-    readonly dirty: boolean;
-    readonly submitted: boolean;
-    readonly errorCount: number;
-    readonly locked: boolean;
-    readonly gate: 'cleared' | 'uncleared' | null;
-};
-/**
- * Seed shape accepted by `useWizard({ defaultStatuses })`. Every field is
- * optional; an omitted meta field falls back to the pending sentinel on
- * read.
- *
- * `locked` is never accepted: it is purely live-derived (sealed behind an
- * earlier uncleared gate) and overlaid on every status read, so a seeded
- * value would be ignored.
- *
- * `gate` is a WRITE-only seed, not a status field echoed back on read. A
- * seed of `'cleared'` latches the gate's cleared state once at construction
- * (an SSR restore of 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 — other keys ignore it.
- */
-type FormStatusSeed = {
-    readonly valid?: boolean;
-    readonly dirty?: boolean;
-    readonly submitted?: boolean;
-    readonly errorCount?: number;
-    readonly gate?: 'cleared' | 'uncleared';
-};
-/**
- * Flat error shape returned per form by `wizard.allErrors[key]`. Each
- * entry carries the formKey + path tuple so consumers can route to the
- * offending field from a wizard-wide error summary.
- */
-type WizardAggregateError = {
-    readonly formKey: FormKey;
-    readonly path: ReadonlyArray<string | number>;
-    readonly message: string;
-    readonly code?: string;
-};
-/**
- * Mirror of `form.values`' call-or-read pattern, one level deep.
- * Drillable as `wizard.statuses.cargo.valid` (readable), as
- * `wizard.statuses('cargo')` (callable single-key), or as
- * `wizard.statuses()` (callable no-arg returns the whole record).
- */
-type WizardStatusesProxy<S extends Record<string, FormStatus>> = ((key?: keyof S) => FormStatus | S) & Readonly<S>;
-/**
- * One compiled position in the wizard's flow. The wizard surface
- * exposes an ordered array of these as `wizard.steps`, plus a
- * `wizard.forms` record keyed by `step.key` for direct lookup.
- *
- * String slots in the source `steps` array desugar to noop forms
- * before compilation, so every compiled step carries a `form`
- * regardless of source kind.
- */
-type CompiledStep = {
-    readonly key: FormKey;
-    readonly form: AnyForm;
-};
-/**
- * Shape of a participating form as seen from inside a function slot's
- * `ctx.forms[key]` lookup. Adds `values` to the structural `AnyForm`
- * minimum so routing decisions can read live form state.
- *
- * Values are typed loose because the wizard does not generically thread
- * each step's schema through `ctx.forms`. For typed access inside slot
- * bodies, close over the original form ref instead of routing through
- * `ctx.forms`.
- */
-type WizardCtxForm = AnyForm & {
-    readonly values: Readonly<Record<string, unknown>>;
-};
-/**
- * Context object passed to function slots in the `steps` array. The
- * `forms` record exposes the wizard's statically-known forms (every
- * top-level `AnyForm` slot plus every noop form synthesized for a
- * top-level string slot). `currentKey` mirrors the live wizard step.
- *
- * Function slots re-evaluate reactively when the values they read
- * mutate (typically `ctx.forms.<key>.values.<path>`). The `forms`
- * accumulator itself is stable across re-evaluations so the slot's
- * lookup identity stays referentially equal. Effectful slot bodies
- * should be avoided; routing decisions live here.
- */
-type WizardCtx = {
-    readonly forms: Readonly<Record<FormKey, WizardCtxForm>>;
-    readonly currentKey: FormKey | undefined;
-};
-/**
- * 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;
-/**
- * Internal phantom brand for `LazyMarker`. The runtime brand symbol
- * lives in `core/wizard-lazy.ts`; this declaration keeps the marker
- * type unforgeable without circular module imports.
- */
-declare const _lazyBrand: unique symbol;
-/**
- * Brand-typed marker returned by `lazy((ctx) => …)`. Wrapping a
- * function slot in `lazy()` gives that slot its own memoization cache:
- * the resolver fires once on the first compile pass, and the result
- * stays cached until one of the resolver's own tracked reactive reads
- * changes (or `wizard.reset()` invalidates the cache). Heavy or
- * one-shot lookups (network-backed factories, expensive derivations)
- * do not re-fire because an unrelated slot's deps changed.
- *
- * Construct via the `lazy()` helper exported from the same entry as
- * `useWizard`. The marker is opaque at the type level; consumers do
- * not assemble it directly.
- */
-type LazyMarker<Ctx = WizardCtx> = {
-    readonly [_lazyBrand]: true;
-    readonly resolve: (ctx: Ctx) => SlotResolution<Ctx>;
-};
-/**
- * Internal phantom brand for `GateMarker`. The runtime brand symbol
- * lives in `core/wizard-gate.ts`; this declaration keeps the marker
- * type unforgeable without circular module imports.
- */
-declare const _gateBrand: unique symbol;
-/**
- * Brand-typed marker returned by `gate(step)`. Wrapping a slot in
- * `gate()` makes it a hard prerequisite: an uncleared gate seals every
- * step positioned 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` stays
- * 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 from the same entry as
- * `useWizard`. The marker is opaque at the type level; consumers do not
- * assemble it directly.
- */
-type GateMarker<Inner = unknown> = {
-    readonly [_gateBrand]: true;
-    readonly inner: Inner;
-};
-/**
- * Strip every `gate()` wrapper off a slot type, exposing the inner
- * slot's static shape. A gate is identity-on-shape — it changes runtime
- * reachability, never the compiled type — so the forms map and the
- * non-empty-tuple predicate both unwrap it before inspecting a slot.
- * Recursive, so a doubly-wrapped `gate(gate(form))` still resolves to
- * `form`. This is what makes `gate(lazy(s))` and `lazy((ctx) => gate(s))`
- * agree at the type level as well as at runtime.
- */
-type UnwrapGate<T> = T extends GateMarker<infer Inner> ? UnwrapGate<Inner> : T;
-/**
- * One position in the source `useWizard({ steps })` array. Each slot
- * resolves to a compiled `{ key, form }` step, or drops out:
- *
- *  - `AnyForm`         — a form declared via `useForm`. Surfaced as-is.
- *  - `string`          — bare key. The wizard generates a noop form
- *                        under the hood so the external surface stays
- *                        uniform across affordance positions (intro,
- *                        terms, congratulations, review surfaces).
- *  - `null` / `undefined` — a literal absence, dropped from the compiled
- *                        list. Lets a conditional step read inline as
- *                        `cond ? form : null` without pre-filtering the
- *                        array.
- *  - function          — eager slot, re-evaluates reactively. Returns a
- *                        `SlotResolution`, or `null` / `undefined` to
- *                        drop the slot from the compiled list.
- *  - `LazyMarker`      — memoized function slot (see `lazy`).
- *  - `GateMarker`      — hard-prerequisite wrapper (see `gate`). Wraps
- *                        any of the above; transparent to the compiled
- *                        step's type, opaque to reachability.
- */
-type StepSlot<Ctx = WizardCtx> = AnyForm | string | null | undefined | ((ctx: Ctx) => SlotResolution<Ctx>) | LazyMarker<Ctx> | GateMarker;
-/**
- * Shape returned by the `restore` callback. Carries the active step's
- * key; intentionally open-ended (object form) so future additions land
- * without a callback-signature break.
- */
-type WizardRestoreState = {
-    readonly step?: FormKey;
-};
-/**
- * `restore` callback signature. Invoked at construction and watched
- * reactively via `watchEffect` so external state changes (browser
- * back/forward, cross-tab events, route changes) re-apply through the
- * wizard. Returning `undefined` falls through to the first step.
- */
-type WizardRestoreFn = () => WizardRestoreState | undefined;
-/**
- * `persist` callback signature. Invoked whenever `wizard.currentStep`
- * changes; the wizard diffs against the last persisted value to break
- * the restore-persist loop, so the callback only fires when the active
- * step actually moves.
- */
-type WizardPersistFn = (state: WizardRestoreState) => void;
-/**
- * Submit context passed to the `onSubmit` callback registered via
- * `wizard.handleSubmit(onSubmit, onError?)`. `handleSubmit` always
- * processes the whole step list, so `values` carries every form's
- * parsed output regardless of which step fired the submit.
- *
- *  - `values` — namespaced aggregate keyed by form key, mirroring
- *               `wizard.allValues`. Reflects parsed output for every
- *               form whose validation has settled; noops contribute an
- *               empty record.
- *  - `get(form)` — typed accessor that reads the parsed output for a
- *               specific form ref. Works across cross-component graphs
- *               because the form ref carries its schema info.
- *  - `currentKey` — key of the step that fired this submission.
- *  - `isFinal`   — `true` when `currentKey` is the last position in
- *               `wizard.steps`. Positional only: it reports where the
- *               submit fired, never what got validated. A user who steps
- *               back, edits, and submits from the middle sees
- *               `isFinal === false`, yet the whole list is still
- *               processed and `done` still latches on success.
- */
-type WizardSubmitContext = {
-    readonly values: Readonly<Record<FormKey, unknown>>;
-    readonly get: <F extends AnyForm>(form: F) => F extends {
-        readonly values: infer V;
-    } ? V : unknown;
-    readonly currentKey: FormKey;
-    readonly isFinal: boolean;
-};
-/**
- * `onSubmit` callback registered via `wizard.handleSubmit`. Sync or
- * async; the returned promise gates `wizard.submitting`.
- */
-type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
-/**
- * Optional `onError` callback registered via `wizard.handleSubmit`.
- * Receives the aggregate error list spanning EVERY step (handleSubmit
- * validates the whole wizard), so a failed submit surfaces every form's
- * errors at once, not just the active step's. Entries originate from
- * per-form validation, activation failures (`atta:activation-failed`),
- * and a submit callback that left errors on a processed step (the
- * `setErrors(...); return` server-rejection path). Sync or async; the
- * returned promise gates `wizard.submitting`.
- */
-type WizardOnError = (errors: readonly WizardAggregateError[]) => void | Promise<void>;
-/**
- * Options for `useWizard({ steps, … })`. `steps` is the only required
- * field; the rest are optional and default sensibly for the common
- * URL-synchronized wizard case.
- */
-type WizardOptions = {
-    /**
-     * Ordered list of slots that compile into the wizard's positional
-     * step list. See `StepSlot` for the per-slot shape contract.
-     */
-    readonly steps: ReadonlyArray<StepSlot>;
-    /**
-     * Identifier used to register the wizard handle in the per-app
-     * registry. Descendant components call `injectWizard(key)` to reach
-     * the same wizard without prop-threading. Anonymous wizards (option
-     * omitted) get a synthetic `__atta:anon-wizard:<id>` key resolved
-     * via `useId()` so SSR-rendered and client-hydrated trees agree on
-     * the same registry entry; the synthetic key is opaque and
-     * descendants reach an anonymous wizard via ambient `injectWizard()`
-     * rather than by key.
-     *
-     * Duplicate-key registration is first-wins-silently (dev-warn on the
-     * second registration) to mirror `useForm`'s shared-key behavior.
-     * The dev-warn fires only for explicit keys — two anonymous wizards
-     * are guaranteed distinct synthetic keys, so the warning never
-     * misfires on independent anonymous wizards on the same page.
-     */
-    readonly key?: string;
-    /**
-     * Seed status payload used while a form is pre-resolved (async
-     * `defaultValues` in flight, or wizard-deferred non-current).
-     * Mirrors `defaultValues`' trichotomy: plain object, sync factory,
-     * or async factory.
-     *
-     * Status resolution priority per form:
-     *   1. `store.defaultsResolved === true` → derive from `form.meta`
-     *   2. else noop form → built-in always-valid status
-     *   3. else seed value for this key → seed over the pending sentinel
-     *   4. else → pending sentinel
-     *
-     * `locked` is never seeded: it is computed live from the wizard's gates
-     * and overlaid on every status read. `gate: 'cleared'` IS honored, but as
-     * a one-shot seed of the gate's cleared latch at construction (an SSR
-     * restore of a confirmed prerequisite), not as a status field echoed on
-     * read — the live `gate` overlay owns the read. Only a step that compiles
-     * to a `gate()` honors it. See `FormStatusSeed`.
-     *
-     * SSR note: the async factory resolves after hydration (client-only), so
-     * a gate seeded through it clears post-hydration. For a gate that must
-     * render open on the first server byte, use the plain or sync-factory
-     * form (resolve server truth in the page's `setup` await).
-     *
-     * Unknown keys in the seed object dev-warn so a stale resume payload
-     * surfaces at construction.
-     */
-    readonly defaultStatuses?: Record<string, FormStatusSeed> | (() => Record<string, FormStatusSeed>) | (() => Promise<Record<string, FormStatusSeed>>);
-    /**
-     * Optional progress override. When omitted, the wizard exposes
-     * `progress` as `valid_step_count / count` (normalised to `[0, 1]`).
-     * When provided, the returned number is used as-is — the consumer is
-     * responsible for any normalisation.
-     *
-     * The override is invoked inside a Vue `computed` so it must be
-     * synchronous and may only read reactive sources.
-     */
-    readonly progress?: (steps: ReadonlyArray<CompiledStep>) => number;
-    /**
-     * When `wizard.handleSubmit` finds errors, automatically focus the
-     * first failing form: jump to its step and invoke its
-     * `applyInvalidSubmitPolicy()` (focus / scroll per the form's own
-     * `onInvalidSubmit` configuration). Default `true`; pass `false` to
-     * keep the active step where the user left it and handle navigation
-     * manually in the `onError` callback.
-     */
-    readonly focusFirstError?: boolean;
-    /**
-     * Source of truth for the active step. Invoked at construction and
-     * re-evaluated reactively via `watchEffect`. Default callback reads
-     * `?step=<key>` from the URL via `wizard-history.ts`; pass `false`
-     * to disable URL sync, or provide a custom callback for non-router
-     * persistence (localStorage, broadcast channel, etc.).
-     */
-    readonly restore?: WizardRestoreFn | false;
-    /**
-     * Destination for the active step. Invoked whenever `currentStep`
-     * changes, with a diff check to break the restore-persist loop.
-     * Default callback writes `?step=<key>` via `wizard-history.ts`;
-     * pass `false` to disable persistence, or provide a custom callback
-     * to scope the param name or write to alternate storage.
-     */
-    readonly persist?: WizardPersistFn | false;
-};
-/**
- * True when a single slot is guaranteed to contribute exactly one
- * compiled step: a bare form or affordance string that is neither
- * nullish nor a (maybe-absent) function / `lazy()` slot. One of these
- * anywhere in the tuple proves the compiled list is non-empty.
- */
-type IsGuaranteedStep<T, 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;
-/**
- * Predicate: is the steps tuple statically guaranteed to compile to a
- * non-empty list? True when at least one element is a guaranteed step
- * (see `IsGuaranteedStep`). Function / `lazy()` slots may resolve to
- * nothing, and `null` / `undefined` (a literal absence or a
- * `cond ? form : null` union) is an explicit drop, so none of those
- * prove non-emptiness; a tuple of only maybe-absent slots stays
- * honestly `| undefined`.
- *
- * Used to narrow `currentStep` / `activeForm` to their non-`undefined`
- * shapes in the common-case wizard, while keeping the honest union
- * everywhere a runtime drop is reachable.
- */
-type StaticallyNonEmpty<S> = S extends readonly [infer First, ...infer Rest] ? IsGuaranteedStep<First> extends true ? true : StaticallyNonEmpty<Rest> : false;
-/** Active step's key, narrowed to `string` when `S` is statically safe. */
-type CurrentStepOf<S> = StaticallyNonEmpty<S> extends true ? FormKey : FormKey | undefined;
-/**
- * Active step's form handle, schema-erased to `UseFormReturnType<GenericForm>`
- * and narrowed to non-`undefined` when `S` is statically safe. The runtime
- * value is a live facade over the active step, so reads (`.values`, `.meta`,
- * `.history`) and `.handleSubmit` always target the current step. Values are
- * loose here because the active step's schema is not statically known; reach
- * for the original form ref or `ctx.get(ref)` when you need typed per-step
- * values.
- */
-type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? UseFormReturnType<GenericForm> : UseFormReturnType<GenericForm> | undefined;
-/**
- * Per-slot contribution to {@link FormsRecordOf}. Unwraps a `gate()`
- * wrapper (transparent to the compiled type) and strips a `null` /
- * `undefined` (a literal absence or a `cond ? form : null` union) off the
- * slot first, so both a conditionally-present form and a `gate(form)`
- * 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;
-/**
- * Recursive tuple walk that builds the static portion of
- * `wizard.forms`. Each step slot contributes to the record:
- *
- *  - **String slot** (`'review'`): the literal becomes the record key
- *    and the value is `AnyForm` (the noop form synthesized for the
- *    affordance position is opaque at the type level).
- *  - **Form slot** (a `useForm` reference with a literal `key` field):
- *    the form's own `key` becomes the record key, and the value is
- *    the concrete form handle type — so drilling
- *    `wizard.forms.shipping.values.address` carries the schema-derived
- *    field types through. A form kept behind a `cond ? form : null`
- *    conditional still maps to its key.
- *  - **`null` / `undefined` slot**: contributes nothing.
- *  - **Function / `lazy()` slot**: contributes nothing to the static
- *    map. Runtime-resolved forms are still reachable via the
- *    catch-all index signature on `WizardForms` (typed as `AnyForm`).
- *  - **`gate()` slot**: transparent — unwrapped to the slot it wraps, so
- *    `gate(form)` contributes the form's key and `gate(lazy(fn))`
- *    contributes nothing, exactly like the wrapped slot on its own.
- *
- * Recursion is bounded by the tuple length; real-world wizards land
- * well below the TS instantiation budget.
- */
-type FormsRecordOf<S> = S extends readonly [
-    infer First,
-    ...infer Rest extends ReadonlyArray<StepSlot>
-] ? SlotRecord<First> & FormsRecordOf<Rest> : unknown;
-/**
- * `wizard.forms` typed view. Combines the static per-step type map
- * with a catch-all `Record<FormKey, AnyForm>` fallback so:
- *
- *   - Statically known slot keys → concrete form type via `FormsRecordOf`
- *   - Any other string key → `AnyForm` via the index signature
- *
- * The intersection collapses to the concrete form for statically
- * known keys (because the concrete form type extends `AnyForm`) and
- * to `AnyForm` for unknown keys.
- */
-type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
-/**
- * Return shape of `useWizard({ steps, … })`. Every reactive read is a
- * plain getter (no `.value`) — `wizard.currentStep`, `wizard.progress`,
- * `wizard.allValues` track inside `computed` / template effects
- * directly.
- *
- * Parameterized by the steps tuple `S` so active-position fields
- * (`currentStep`, `activeForm`) narrow to non-undefined for the common
- * case (all positional Form / string slots) and stay as honest unions
- * when a function or `lazy()` slot can drop the compiled position at
- * runtime. The `const` type parameter on `useWizard` preserves literal
- * tuple types without consumer-side `as const`, so the narrowing
- * happens automatically from the call site.
- *
- *  - `currentStep` — key of the active step. Narrows to `string` when
- *                    the steps tuple is statically guaranteed to
- *                    compile to a non-empty list (all positional
- *                    Form / string slots, no function or `lazy()`
- *                    slots). Otherwise reads as `string | undefined`
- *                    so the degenerate case (empty list at runtime)
- *                    surfaces honestly.
- *  - `activeForm`  — a LIVE view of the active step's form. Operating
- *                    through it always targets the current step, so a
- *                    handler captured once at setup
- *                    (`wizard.activeForm.handleSubmit(() =>
- *                    wizard.next())`) retargets as the wizard advances.
- *                    No longer `===` the raw per-step handle; reach for
- *                    `wizard.forms[key]` when you need raw identity.
- *                    Same `undefined` narrowing as `currentStep`. Noop
- *                    forms cover string slots in the normal path.
- *  - `activeIndex` — 0-based position of the active step.
- *  - `isFinalStep` — `true` when `currentStep === steps[count - 1].key`.
- *  - `steps`       — ordered list of compiled `{ key, form }` slots.
- *  - `forms`       — record indexable by step key; the value is the
- *                    full form handle resolved for that slot.
- *  - `count`       — `steps.length`.
- *  - `statuses`    — callable readonly proxy over the per-key
- *                    `FormStatus` record. Noop-form keys always read
- *                    as default-valid.
- *  - `allValues`   — namespaced aggregate of each form's values, keyed
- *                    by step key.
- *  - `allErrors`   — namespaced aggregate of each form's validation
- *                    errors, keyed by step key. Noop forms map to an
- *                    empty list.
- *  - `progress`    — normalised step-validity ratio (or the consumer's
- *                    `progress` override). Forward-looking: noops count
- *                    as always-valid.
- *  - `canAdvance`  — `true` when `activeIndex < count - 1`. Pure
- *                    positional check; navigation never gates on
- *                    validity.
- *  - `canGoBack`   — `true` when `activeIndex > 0`.
- *  - `complete`    — `isFinalStep && every step's form is valid`.
- *                    Forward-looking; reactive to current form
- *                    validity. Gates "Finish button enable" style UI.
- *  - `done`        — monotonic latch: flips `true` the first time a
- *                    `handleSubmit` resolves without throwing AND leaves
- *                    no errors set on any step, and stays `true` through
- *                    subsequent edits or invalidations. A callback that
- *                    calls `setErrors` and returns (the documented
- *                    server-rejection path) is a failed submit, so it
- *                    does not flip `done`. Only `reset()` flips it back.
- *                    Gates "show success card" style UI that should
- *                    reflect submission history rather than current
- *                    validity.
- *  - `submitting`  — `true` while a `wizard.handleSubmit` call is in
- *                    flight. Global re-entrance guard: every
- *                    navigation method also refuses while this is on.
- *  - `submissionAttempts` — count of `wizard.handleSubmit` invocations
- *                    (success or failure). Always bumps, including on
- *                    noop-form steps.
- *  - `submitError` — the error THROWN by the most recent
- *                    `wizard.handleSubmit` callback (or its `onError`),
- *                    coerced to a real `Error`. Mirrors
- *                    `form.meta.submitError`: this is the unexpected-throw
- *                    channel, so an expected rejection handled via
- *                    `setErrors` (no throw) surfaces through the error
- *                    surface and `onError` instead, leaving this `null`.
- *                    Cleared at submit entry and by `reset()`, parked here
- *                    rather than re-thrown, so the handler resolves and
- *                    never manufactures a `window` unhandledrejection.
- *                    `null` on success.
- *  - `visited`     — append-only breadcrumb of navigated step keys.
- *                    `back()` does not pop; the trail is the audit
- *                    log, not the back-stack.
- *  - `next/back/goTo` — pure navigation. Refuses while `submitting`.
- *  - `tryNext()`   — submit the active step, and once that submit
- *                    resolves clean, advance; invalid input keeps the pin
- *                    put under the form's standard error reveal (first
- *                    error focused, 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()"`); resolves to whether
- *                    the pin moved. No-ops to `false` on a degenerate or
- *                    final-step wizard (finish via `handleSubmit`).
- *  - `handleSubmit(onSubmit, onError?)` — always validates the entire
- *                    step list, from any step, and never advances the
- *                    pin: on success it latches `done`; on any error it
- *                    focuses the first failing step and fires `onError`
- *                    with errors spanning every step. To gate advancing
- *                    a step on its own validity, compose with the active
- *                    form's submit: `activeForm.handleSubmit(() =>
- *                    wizard.next())`. Returns an event handler suitable
- *                    for `<form @submit>` or imperative use.
- *  - `reset()`     — zeros wizard lifecycle (`submissionAttempts`,
- *                    `visited`), resets every form, returns
- *                    `currentStep` to `steps[0].key`, and invokes
- *                    `persist` with the cleared state. Re-applies the
- *                    `defaultStatuses` gate seed, so a reboot returns to
- *                    the seeded initial clearance, not fully sealed.
- *  - `relock(key, commit)` — 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 it as-is. Seal-only (never
- *                    opens a gate), so it cannot 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; never rejects.
- *                    Resolves `false` (dev-warn) on a non-gate key.
- */
-type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepSlot>> = {
-    readonly key: string;
-    readonly currentStep: CurrentStepOf<S>;
-    readonly activeForm: ActiveFormOf<S>;
-    readonly activeIndex: number;
-    readonly isFinalStep: boolean;
-    readonly steps: ReadonlyArray<CompiledStep>;
-    readonly forms: WizardForms<S>;
-    readonly count: number;
-    readonly statuses: WizardStatusesProxy<Record<string, FormStatus>>;
-    readonly allValues: Readonly<Record<FormKey, unknown>>;
-    readonly allErrors: Readonly<Record<FormKey, readonly WizardAggregateError[]>>;
-    readonly progress: number;
-    readonly canAdvance: boolean;
-    readonly canGoBack: boolean;
-    readonly complete: boolean;
-    readonly done: boolean;
-    readonly submitting: boolean;
-    readonly submissionAttempts: number;
-    readonly submitError: Error | null;
-    readonly visited: readonly FormKey[];
-    readonly next: () => Promise<void>;
-    readonly back: () => void;
-    readonly goTo: (key: string) => void;
-    readonly tryNext: () => Promise<boolean>;
-    readonly handleSubmit: (onSubmit: WizardOnSubmit, onError?: WizardOnError) => (event?: Event) => Promise<void>;
-    readonly reset: () => void;
-    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 all form state instances. Each
- * `app.use(createAttaform())` call gets its own registry,
- * so the library runs under bare Vue 3 + SSR (via
- * `@vue/server-renderer`) and Nuxt with the same code path.
- *
- * Each form's state lives in `forms: Map<FormKey, FormStore<GenericForm>>`.
- * The type relaxation at storage time is necessary because different
- * forms in the same app have different `Form` generics; callers recover
- * the specific form type via `useForm`'s overloads.
- */
-/**
- * Serialised snapshot of one form's state, captured by
- * `renderAttaformState` for SSR and replayed by
- * `hydrateAttaformState` on the client. Round-trips through
- * JSON-safe tuples; field references are intentionally omitted
- * (DOM nodes don't survive serialisation).
- */
-type SerializedFormData = {
-    /** The form's value at snapshot time. */
-    readonly form: unknown;
-    /**
-     * Errors produced by the schema at snapshot time. Replayed into
-     * the client form's error state at hydration; cleared on
-     * successful re-validation client-side.
-     */
-    readonly schemaErrors: ReadonlyArray<readonly [string, unknown]>;
-    /**
-     * Errors set explicitly via `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. Round-trips the "displayed empty" UI state across
-     * the SSR boundary — without it, the client briefly renders
-     * `String(slim-default)` (e.g. `'0'`) for fields the server
-     * rendered as blank. Optional in the wire format so older payload
-     * shapes deserialise cleanly.
-     */
-    readonly blankPaths?: ReadonlyArray<string>;
-};
-type PendingHydration = Map<FormKey, SerializedFormData>;
-/**
- * The library's per-Vue-app container. One `AttaformRegistry` is
- * created per `app.use(createAttaform())` call.
- *
- * Most consumers never touch this directly — `useForm` and
- * `injectForm` reach the registry on your behalf. Access it
- * explicitly only when wiring SSR or a custom plugin integration.
- */
-type AttaformRegistry = {
-    /**
-     * Live forms keyed by `FormKey`.
-     * @internal
-     */
-    readonly forms: Map<FormKey, FormStore<GenericForm>>;
-    /**
-     * Live wizards keyed by the consumer-supplied `key` option. Populated
-     * by `useWizard(entryForm, { key })`; consulted by `injectWizard(key)` to
-     * resolve cross-component wizard handles. Anonymous wizards (no
-     * `key`) do NOT register here — they're reachable only via ambient
-     * provide/inject.
-     * @internal
-     */
-    readonly wizards: Map<string, UseWizardReturnType>;
-    /**
-     * Snapshots staged by `hydrateAttaformState` waiting to be consumed by the next `useForm` call.
-     * @internal
-     */
-    readonly pendingHydration: PendingHydration;
-    /** `true` while running on the server during SSR; `false` on the client. */
-    readonly ssr: boolean;
-    /** App-level defaults applied to every `useForm` call. */
-    readonly defaults: AttaformDefaults;
-    /**
-     * Track a consumer of `key`. Returns a dispose function — call it
-     * when the consumer unmounts. The form is evicted automatically
-     * when the last consumer disposes, so long-running SPAs don't
-     * leak detached state across navigations.
-     * @internal
-     */
-    readonly trackConsumer: (key: FormKey) => () => void;
-    /**
-     * Track a consumer of wizard `key`. Returns a dispose function — call
-     * it when the consumer unmounts. The wizard handle is evicted from
-     * `wizards` once the last consumer disposes, mirroring the form
-     * consumer-counting mechanics. Anonymous wizards never enter this
-     * counter (they have no key to count under).
-     * @internal
-     */
-    readonly trackWizardConsumer: (key: string) => () => void;
-    /**
-     * Mark a form as eligible for SSR prefetch. The form's
-     * `onServerPrefetch` hook consults `shouldPrefetch(key)` and runs the
-     * captured `defaultValues` factory only when this set contains the
-     * key (and the skip set does not). Set by `form.activate()`,
-     * `useWizard`'s current-step auto-mark, and the future Vite transform.
-     * @internal
-     */
-    readonly enqueuePrefetch: (key: FormKey) => void;
-    /**
-     * Mark a form as ineligible for SSR prefetch. Overrides `enqueuePrefetch`.
-     * Used by `useWizard` to keep non-current steps dormant on the
-     * server even when a transform mark or stray `activate()` would
-     * otherwise enqueue them — the wizard's "user isn't on this step"
-     * signal wins.
-     * @internal
-     */
-    readonly skipPrefetch: (key: FormKey) => void;
-    /**
-     * Whether `key`'s SSR prefetch should run. Returns `true` iff the key
-     * is enqueued AND not skipped.
-     * @internal
-     */
-    readonly shouldPrefetch: (key: FormKey) => boolean;
-    /**
-     * Wait for all pending persistence writes across every live form
-     * to settle. Useful for SSR shutdown and integration tests that
-     * need a deterministic teardown.
-     * @internal
-     */
-    readonly shutdown: () => Promise<void>;
-};
-/**
- * The Vue `InjectionKey` under which the registry is provided on the
- * app. Most consumers never need this — `useForm` and
- * `injectForm` resolve the registry automatically.
- */
-declare const kAttaformRegistry: InjectionKey<AttaformRegistry>;
-declare module 'vue' {
-    interface App {
-        /** @internal */
-        _attaform?: AttaformRegistry;
-    }
-}
-/** Options for `createRegistry`. */
-type CreateRegistryOptions = SSRDetectOptions & {
-    /**
-     * App-level defaults applied to every `useForm` call. Per-form
-     * options always win. Omitted is equivalent to `{}`.
-     */
-    defaults?: AttaformDefaults;
-};
-/**
- * Create a fresh `AttaformRegistry`. `createAttaform()` calls
- * this internally — most consumers never need to call it directly.
- * Use it when building a custom plugin that doesn't want the
- * `createAttaform` plugin's auto-install behaviour (e.g. test
- * harnesses, embedded apps).
- */
-declare function createRegistry(options?: CreateRegistryOptions): AttaformRegistry;
-/**
- * Look up the current app's registry from inside a component's
- * `setup()` (or any synchronous code on the setup call stack).
- *
- * Most consumers don't need this — `useForm` and `injectForm`
- * call it on your behalf. Reach for it directly when building
- * custom integrations that need the raw registry.
- *
- * Throws:
- * - `OutsideSetupError` when called outside a Vue setup context
- *   (e.g. from an event handler or async callback). Move the call
- *   into setup, or trigger it from a child component.
- * - `RegistryNotInstalledError` when called inside setup but the
- *   plugin wasn't installed. Add
- *   `app.use(createAttaform())` to your app entry.
- */
-declare function useRegistry(): AttaformRegistry;
-/**
- * Look up a Vue app's registry by `App` reference. Used by
- * SSR helpers (`renderAttaformState`, `hydrateAttaformState`) that
- * run outside a component setup context.
- *
- * Throws `RegistryNotInstalledError` when the app hasn't been wired
- * with `createAttaform()`.
- */
-declare function getRegistryFromApp(app: App): AttaformRegistry;
-
-/**
- * Multistep-form orchestrator built around an ordered list of step slots.
- * Each slot resolves to a participating form: an existing `useForm`
- * reference, a bare string key (desugared to a noop form so affordance
- * steps participate uniformly), an eagerly-evaluated function slot for
- * runtime branching, or a `lazy()`-wrapped function slot that caches
- * its resolution and re-fires only on its own tracked deps.
- *
- * The wizard's surface is read-only from the consumer's side:
- * navigation (`next` / `back` / `goTo`) walks positional indices,
- * `handleSubmit` validates the whole step list from any step and never
- * advances (gate advance with `activeForm.handleSubmit(() =>
- * wizard.next())`), and URL synchronization rides on `restore` /
- * `persist` callbacks that default to `?step=<key>`.
- */
-declare function useWizard<const S extends ReadonlyArray<StepSlot>>(options: WizardOptions & {
-    readonly steps: S;
-}): UseWizardReturnType<S>;
-
-/**
- * Options accepted by `injectWizard` when passing an object instead of
- * a bare key string. Mirrors `injectForm`'s `InjectFormInput` shape so
- * the two composables present an identical call surface.
- */
-type InjectWizardInput = {
-    readonly key?: string | undefined;
-};
-/**
- * Access an existing wizard handle from a descendant component without
- * passing it through props. Counterpart to `useWizard` — `useWizard`
- * creates and provides; `injectWizard` looks up via Vue's inject
- * mechanism or the per-app registry.
- *
- * Three ways to call it:
- *
- * ```ts
- * // Reach the nearest ancestor's useWizard call (ambient).
- * const wizard = injectWizard()
- *
- * // Reach a specific wizard by its key — works from anywhere in the app.
- * const signup = injectWizard('signup-wizard')
- *
- * // Object form (equivalent; convenient for spread).
- * const signup = injectWizard({ key: 'signup-wizard' })
- * ```
- *
- * Resolution rules (no-key form):
- *  - Closest ambient ancestor wins via `provide(kAttaformAncestorWizard)`.
- *  - Only anonymous (no-`key`) `useWizard()` calls fill the ambient
- *    slot. Descendants of a keyed wizard must address it explicitly
- *    via `injectWizard('the-key')`. Mirrors `useForm`'s ambient gate.
- *
- * Resolution rules (keyed form): registry lookup by string key,
- * independent of component-tree position. The wizard must have been
- * constructed with `useWizard({ steps, key })` to be reachable.
- *
- * Returns `null` when no matching wizard exists (no ambient ancestor,
- * or the named key isn't registered yet). A dev-mode warning points at
- * the call site, lists the registered keys, and flags the mount-timing
- * case (a wizard created by a child or sibling isn't registered until
- * its own setup runs). Always narrow before using:
- *
- * ```ts
- * const wizard = injectWizard('signup')
- * if (!wizard) return
- * wizard.next()
- * ```
- *
- * Consumer ref-counting: keyed lookups pin the wizard handle in the
- * registry for this component's lifetime, so the handle survives even
- * if the parent `useWizard` component unmounts before the child does.
- * Once every consumer disposes, the registry evicts the entry on the
- * next microtask. Ambient lookups don't ref-count — the parent
- * `useWizard`'s scope owns the lifetime.
- */
-declare function injectWizard(input?: string | InjectWizardInput): UseWizardReturnType | null;
-
-/**
- * Wrap a function slot in `lazy()` to give that slot its own memoized
- * cache, distinct from the wizard-wide step compiler.
- *
- * Default function slots in `useWizard({ steps })` re-evaluate whenever
- * the compiled step list re-evaluates, including when an unrelated
- * slot's reactive deps change. That keeps the rail correct but can
- * trigger spurious work in a resolver that is expensive (a network
- * lookup, a heavy schema derivation, an async-derived factory).
- *
- * `lazy()` isolates each wrapped slot behind its own cache. The
- * resolver runs eagerly on the first compile pass; subsequent reads
- * reuse the cached form. The cache invalidates only when one of the
- * resolver's own tracked reactive dependencies changes (Vue's
- * `computed` semantics applied to a slot), or when `wizard.reset()`
- * triggers a global re-compile:
- *
- *   const wizard = useWizard({
- *     steps: [
- *       account,
- *       lazy((ctx) => loadShippingForm(ctx.forms.account.values.region)),
- *       confirm,
- *     ],
- *   })
- *
- * Resolution semantics:
- *  - Eager at construction so `wizard.steps` and SSR markup are honest
- *    from t=0.
- *  - Memoized: the resolver re-fires only when one of its own tracked
- *    reads changes. An unrelated slot re-evaluating does not re-fire
- *    this one.
- *  - `wizard.reset()` clears every lazy slot's cache so a reboot truly
- *    resolves from scratch.
- *  - Resolving to `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 / 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 — user hasn't supplied a value. */
-    readonly NoValueSupplied: "atta:no-value-supplied";
-    /** The schema adapter's `validateAtPath` threw synchronously. */
-    readonly AdapterThrew: "atta:adapter-threw";
-    /**
-     * User code inside a `z.preprocess`, `.refine`, or `.transform`
-     * threw (sync or async). The adapter caught the throw and surfaced
-     * it as a `ValidationError` at the field path so the form's normal
-     * error pipeline handles it instead of leaking as an unhandled
-     * rejection or routing through `submitError`.
-     */
-    readonly ValidatorThrew: "atta:validator-threw";
-    /**
-     * A function-form `defaultValues` factory threw or its promise
-     * rejected. The runtime captures the raw error on `form.hydrateError`
-     * and ALSO surfaces a form-level `ValidationError` (path `[]`) so
-     * the standard error pipeline carries the signal. Critical for the
-     * SSR round-trip: `hydrateError` itself does not ride the wire
-     * payload, but `schemaErrors` does, so the client sees the failure
-     * after rehydration without an extra channel.
-     */
-    readonly HydrationFailed: "atta:hydration-failed";
-    /** The supplied path didn't resolve to any node in the schema. */
-    readonly PathNotFound: "atta:path-not-found";
-    /**
-     * A walked form's `activate()` (async `defaultValues` factory) threw
-     * during `wizard.handleSubmit`'s path walk. Surfaced as a synthetic
-     * `ValidationError` at the form-level path (`[]`) so the wizard's
-     * aggregate error pipeline can carry the failure alongside ordinary
-     * validation errors. The raw factory error remains on
-     * `form.hydrateError` for retry UX.
-     */
-    readonly ActivationFailed: "atta:activation-failed";
-    /**
-     * 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";
-};
-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;
-    /**
-     * App-level defaults applied to every `useForm` call in this app.
-     * Per-form options always win. See `AttaformDefaults` for
-     * the supported option set and the merge rules.
-     *
-     * ```ts
-     * app.use(
-     *   createAttaform({
-     *     defaults: { debounceMs: 100 },
-     *   })
-     * )
-     * ```
-     */
-    defaults?: AttaformDefaults;
-};
-/**
- * Create the Vue plugin that installs the form library on a Vue
- * application. Required only when you want app-wide options
- * (`defaults`, `devtools: false`, `ssr: true`) — for the default
- * setup, `useForm` / `injectForm` / `useRegister` lazy-install the
- * registry on first use.
- *
- * ```ts
- * import { createApp } from 'vue'
- * import { createAttaform } from 'attaform'
- *
- * createApp(App)
- *   .use(createAttaform({ defaults: { debounceMs: 100 } }))
- *   .mount('#app')
- * ```
- *
- * Under SSR with bare Vue 3, install explicitly with `{ ssr: true }`
- * from your server entry — the SSR serialization helpers
- * (`renderAttaformState` / `hydrateAttaformState`) require an
- * already-attached registry and don't trigger lazy install. Under
- * Nuxt, install via `attaform/nuxt` instead — the Nuxt module wires
- * both server and client automatically.
- *
- * Installing more than once on the same app is a no-op (the second
- * call logs a dev-mode warning).
- */
-declare function createAttaform(options?: AttaformPluginOptions): Plugin;
-
-/**
- * Serialised snapshot of every form in a Vue app, produced by
- * `renderAttaformState` and consumed by `hydrateAttaformState`.
- *
- * JSON-safe — pass to `JSON.stringify`, `devalue`, or any other
- * serialiser before embedding in your SSR payload.
- */
-type SerializedAttaformState = {
-    /** Tuples of `[formKey, snapshot]` for every form in the app. */
-    readonly forms: ReadonlyArray<readonly [FormKey, SerializedFormData]>;
-};
-/**
- * Snapshot every form on a Vue app for SSR. Call from your server
- * entry after rendering the app:
- *
- * ```ts
- * import { renderToString } from '@vue/server-renderer'
- * import { renderAttaformState, escapeForInlineScript } from 'attaform'
- *
- * const html = await renderToString(app)
- * const state = renderAttaformState(app)
- * const payload = escapeForInlineScript(JSON.stringify(state))
- *
- * return `
- *   ${html}
- *   <script>window.__ATTAFORM_STATE__ = ${payload}</script>
- * `
- * ```
- *
- * Pair with `hydrateAttaformState` on the client to restore the
- * forms in their server-rendered state. Nuxt users don't need this —
- * `attaform/nuxt` wires SSR automatically.
- */
-declare function renderAttaformState(app: App): SerializedAttaformState;
-/**
- * Restore forms from a server-rendered snapshot on the client. Call
- * from your client entry before mounting:
- *
- * ```ts
- * import { createApp } from 'vue'
- * import { createAttaform, hydrateAttaformState } from 'attaform'
- *
- * const app = createApp(App).use(createAttaform())
- * hydrateAttaformState(app, window.__ATTAFORM_STATE__)
- * app.mount('#app')
- * ```
- *
- * The next `useForm({ key })` call for each serialised form picks up
- * the snapshot transparently — no further action is required.
- */
-declare function hydrateAttaformState(app: App, payload: SerializedAttaformState): void;
-
-/**
- * Escape a JSON string so it's safe to embed inside an inline
- * `<script>` tag during SSR. Plain `JSON.stringify` is not safe — a
- * form value containing the literal substring `</script>` would
- * break out of the script tag.
- *
- * ```ts
- * const payload = escapeForInlineScript(JSON.stringify(renderAttaformState(app)))
- * // `<script>window.__ATTAFORM_STATE__ = ${payload}</script>` is safe.
- * ```
- *
- * Output remains valid JSON — `JSON.parse` round-trips back to the
- * original value on the client.
- */
-declare function escapeForInlineScript(json: string): string;
-
-/**
- * Symbol slot used by custom directive integrations to install an
- * assigner on the bound element. Read by the v-register directive
- * when a DOM event fires:
- *
- * ```ts
- * import { assignKey } from 'attaform'
- * el[assignKey] = (value) => myCustomWriter(value)
- * ```
- *
- * Most consumers never need this — the built-in directives wire
- * default assigners for text inputs, checkboxes, radios, and selects.
- */
-declare const assignKey: unique symbol;
-
-/**
- * The `v-register` directive. Bind a form field to a native input,
- * select, textarea, checkbox, or radio:
- *
- * ```vue
- * <input v-register="form.register('email')" />
- * <select v-register="form.register('country')">
- *   <option value="us">US</option>
- *   <option value="uk">UK</option>
- * </select>
- * ```
- *
- * The directive picks the right binding strategy automatically based
- * on the element's `tagName` and `type`. Registered globally by
- * `createAttaform()`. Most consumers never import it directly, but
- * it's exposed for advanced integrations that wire directives
- * manually.
- */
-declare const vRegister: RegisterModelDynamicCustomDirective;
-
-/**
- * Type guard for a `RegisterValue`. Returns `true` when `val` looks
- * like the object returned from `form.register(path)`.
- *
- * ```ts
- * if (isRegisterValue(slotValue)) {
- *   // slotValue.innerRef is now a Ref<unknown>
- * }
- * ```
- *
- * Useful when building wrapper components that accept either a
- * `RegisterValue` or a plain ref via the same prop.
- */
-declare function isRegisterValue<Value = unknown>(val: unknown): val is RegisterValue<Value>;
-
-/**
- * Shared building blocks for Attaform's two devtools surfaces — the Vue
- * DevTools (Chrome-extension) inspector wired up in `./devtools.ts`, and
- * the Nuxt DevTools (overlay) panel wired up via `../../nuxt.ts` +
- * `../pages/_attaform_devtools.vue`.
- *
- * Houses the window-bridge contract both surfaces consume so a new
- * bridge field lands in one file. Both surfaces render RAW form values
- * by design — DevTools is a dev-only surface, and redaction across every
- * place a value surfaces is impractical security theater rather than a
- * real safeguard.
- */
-
-/**
- * Property key on `window` that the Nuxt-side dev plugin attaches the
- * bridge object to. The iframe-mounted overlay panel reads
- * `window.parent[DEVTOOLS_WINDOW_KEY]` to reach the host app's registry.
- *
- * Underscored + namespaced to make accidental collision with consumer
- * globals vanishingly unlikely. Stable across versions — bumping it
- * would silently disconnect older library builds from newer overlay
- * panels in the same browser tab during a library upgrade.
- */
-declare const DEVTOOLS_WINDOW_KEY = "__attaform_devtools__";
-/**
- * Shape of the object the host plugin attaches to `window` in dev mode.
- * The iframe overlay panel reads this to discover the live registry and
- * render its forms.
- *
- * Single-registry assumption: the latest `createAttaform()` install
- * wins. Multi-app pages (rare; typically only seen in micro-frontend
- * setups) will only see one app's forms in the panel. Documented but
- * not actively supported — the alternative (a Set of registries with
- * union-rendering) is a future call if a real consumer hits it.
- */
-interface AttaformDevtoolsBridge {
-    registry: AttaformRegistry;
-    /**
-     * The library version, surfaced in the panel's footer for support /
-     * bug-report context. Read from `package.json` at host-plugin init.
-     */
-    version: string;
-}
-declare global {
-    interface Window {
-        [DEVTOOLS_WINDOW_KEY]?: AttaformDevtoolsBridge;
-    }
-}
-
-/**
- * Typed error classes thrown by the form library. Each one signals a
- * distinct misuse so calling code can branch on `instanceof` instead
- * of pattern-matching error messages.
- *
- * Every class extends `AttaformError`, so consumers can write a single
- * polymorphic catch (`catch (e) { if (e instanceof AttaformError) ... }`)
- * instead of OR-chaining checks for each subclass. `AttaformError` itself
- * extends the standard `Error`, so existing `instanceof Error` usage
- * keeps working.
- */
-
-/**
- * Base for every error class thrown by `attaform`. Sets
- * `this.name` from the constructor's `new.target.name`, so subclasses
- * don't have to redeclare their own name override.
- */
-declare class AttaformError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
-/**
- * Thrown when a path string is malformed — typically a dotted path
- * with empty segments (e.g. `'a..b'`, leading or trailing dots).
- * Use array form (`['a', 'b']`) for keys that contain literal dots.
- */
-declare class InvalidPathError extends AttaformError {
-}
-/**
- * Thrown when `useForm` receives an invalid configuration — most often
- * a schema passed directly as the first argument, or no argument at
- * all. The configuration is an options bag; the schema is one of
- * several fields, even when it's the only one in use.
- *
- * ```ts
- * // ✗ Crashes deep inside the validator with an opaque message:
- * const form = useForm(z.object({ ... }))
- * // ✗ Same:
- * const form = useForm()
- * // ✓ Pass the schema as the `schema` field:
- * const form = useForm({ schema: z.object({ ... }) })
- * ```
- *
- * The same shape applies to every entry point: `attaform/zod`,
- * `attaform/zod-v3`, `attaform/zod-v4`, and the schema-agnostic
- * `attaform` root.
- */
-declare class InvalidUseFormConfigError extends AttaformError {
-    constructor();
-}
-/**
- * Thrown when a `handleSubmit`-supplied `onError` callback itself
- * throws or rejects. Wraps the inner failure so both the original
- * cause (via `error.cause`) and the propagation site are visible.
- */
-declare class SubmitErrorHandlerError extends AttaformError {
-}
-/**
- * Thrown when an `attaform` API needs the registry attached to a Vue
- * app but it isn't there yet. Component-level entry points (`useForm`,
- * `injectForm`, `useRegister`) lazy-install the registry on first use,
- * so this error is mostly reached by SSR helpers — `renderAttaformState`
- * and `hydrateAttaformState` — which run outside a setup context and
- * have no current instance to install against.
- *
- * Fix: add `app.use(createAttaform())` (or `app.use(createAttaform({
- * ssr: true }))` on the server) to your SSR entry, before
- * `renderToString` / hydration. Under Nuxt, `attaform/nuxt` already
- * does this; the error usually points at a non-Nuxt SSR setup that
- * hasn't installed explicitly.
- */
-declare class RegistryNotInstalledError extends AttaformError {
-    constructor();
-}
-/**
- * Thrown when `useForm` / `injectForm` is called outside of a
- * Vue `setup()` function — typically from an event handler, watcher,
- * or async callback that runs after mount.
- *
- * Fix: move the call into `setup()`, or trigger it from a child
- * component whose `setup()` runs the composable.
- */
-declare class OutsideSetupError extends AttaformError {
-    constructor();
-}
-/**
- * Thrown when a `useForm({ key })` call uses a key starting with
- * `__atta:`. That prefix is reserved for keys the library generates
- * internally (e.g. for anonymous `useForm()` calls without an
- * explicit key). Pick a different prefix for your form.
- */
-declare class ReservedFormKeyError extends AttaformError {
-    constructor(key: string);
-}
-
-/**
- * Anti-flash timing for the library-default display reducer.
- *
- * - `showDelay` — how long in-flight work (a validation run or an async
- *   register transform) may run before its spinner is allowed to show. Work
- *   that settles inside this window never reveals `'pending'` at all, so a
- *   fast (often synchronous) check does not flash a spinner on every keystroke.
- * - `minVisible` — once shown, the minimum time the spinner stays up. Work
- *   that lands just past `showDelay` is held here so the spinner does not
- *   itself flash on and immediately off.
- *
- * Both are milliseconds.
- */
-type DisplayTimings = {
-    readonly showDelay: number;
-    readonly minVisible: number;
-};
-/**
- * Library-default anti-flash timings. `showDelay: 120` cleanly swallows
- * synchronous, microtask-resolved, and tiny-async work (validation runs and
- * async register transforms alike) so none of them flash a spinner;
- * `minVisible: 120` keeps a shown spinner snappy once one does land.
- * Retune via {@link makeDefaultDisplayState} without touching the engine.
- */
-declare const DEFAULT_TIMINGS: DisplayTimings;
-/**
- * Build a default `getDisplayState` reducer with custom anti-flash timing.
- * Power users who want a tighter or looser spinner than {@link DEFAULT_TIMINGS}
- * pass their own `{ showDelay, minVisible }`:
- *
- * ```ts
- * import { makeDefaultDisplayState } from 'attaform'
- *
- * useForm({
- *   schema,
- *   getDisplayState: makeDefaultDisplayState({ showDelay: 50, minVisible: 200 }),
- * })
- * ```
- *
- * The returned reducer is pure: the engine injects `now` and threads the
- * previous machine, so the same `(prev, ctx)` always yields the same next
- * machine. It shapes only the display projection — `errors`, `valid`,
- * `validating`, and the underlying validation run exactly as before.
- */
-declare function makeDefaultDisplayState({ showDelay, minVisible, }: DisplayTimings): GetDisplayState;
-/**
- * Library-default `getDisplayState` reducer. Resolves every path's
- * `field.displayState` — and thus `field.show*` and the `form.meta`
- * rollups — whenever the consumer has not configured an override at the
- * per-form or plugin level. Built from {@link DEFAULT_TIMINGS}; publicly
- * re-exported so an override can compose with it (a layered reducer that
- * special-cases a subtree but otherwise defers picks up future
- * refinements for free):
- *
- * ```ts
- * import { defaultDisplayState } from 'attaform'
- *
- * useForm({
- *   schema,
- *   getDisplayState: (prev, ctx) => {
- *     const next = defaultDisplayState(prev, ctx)
- *     return next.display === 'success' && ctx.field.path[0] === 'username'
- *       ? { display: 'idle' }
- *       : next
- *   },
- * })
- * ```
- */
-declare const defaultDisplayState: GetDisplayState;
-
-export { renderAttaformState as $, createAttaform as B, DEFAULT_TIMINGS as D, createRegistry as E, defaultCoercionRules as H, defaultDisplayState as J, defineCoercion as K, escapeForInlineScript as M, gate as N, OutsideSetupError as O, getRegistryFromApp as P, hydrateAttaformState as Q, RegistryNotInstalledError as R, injectForm as T, injectWizard as V, isRegisterValue as X, kAttaformRegistry as Y, lazy as Z, makeDefaultDisplayState as _, useRegister as a0, useRegistry as a1, useWizard as a2, vRegister as a3, AttaformError as c, AttaformErrorCode as d, DEVTOOLS_WINDOW_KEY as f, InvalidPathError as i, InvalidUseFormConfigError as j, ReservedFormKeyError as k, SubmitErrorHandlerError as n, assignKey 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, UseRegisterReturn as U, WizardAggregateError as W, AnyForm as a, AttaformDevtoolsBridge as b, AttaformPluginOptions as e, DisplayTimings as g, FormStatusSeed as h, SerializedFormData as l, StepSlot as m, UseWizardReturnType as o, WizardCtx as p, WizardCtxForm as q, WizardOnError as r, WizardOnSubmit as s, WizardOptions as t, WizardPersistFn as u, WizardRestoreFn as v, WizardRestoreState as w, WizardStatusesProxy as x, WizardSubmitContext as y };