attaform 0.17.2 → 0.18.1

package/dist/shared/{attaform.C_5aB6EQ.d.cts → attaform.Dj9mwbaV.d.ts}

@@ -1,4 +1,4 @@
-import { Ref, ObjectDirective, ComputedRef } from 'vue';
+import { ObjectDirective, Ref, ComputedRef } from 'vue';
 
 /**
  * Schema-attached field metadata — the shared types used by both Zod
@@ -114,7 +114,7 @@ type Unset = typeof _unsetBrand;
  * every realm gets the same sentinel.
  *
  * @see {@link isUnset} — type guard that narrows a value back to {@link Unset}.
- * @see `docs/recipes/blank-inputs.md` — the conceptual model behind blank-aware fields.
+ * @see `docs/validation/blank.md` — the conceptual model behind blank-aware fields.
  */
 declare const unset: Unset;
 /**
@@ -136,6 +136,16 @@ declare function isUnset(value: unknown): value is Unset;
 type GenericForm = Record<string, unknown>;
 /** Internal helper — `true` when `T` is an object or array. */
 type IsObjectOrArray<T> = T extends GenericForm ? true : T extends Array<unknown> ? true : false;
+/**
+ * Implementation detail backing `FlatPath` in its default
+ * (partial-path) mode. Exported so `rollup-plugin-dts` preserves it
+ * as a named alias in the bundled `.d.ts` rather than inlining the
+ * full template-literal recursion body at every reference site
+ * (`FlatPath`, `RegisterFlatPath`, every path-addressed API method).
+ * Inlining at consumer call sites compounds into TS2589 territory
+ * when multiple complex forms share a scope. Consumers should reach
+ * for `FlatPath` instead; this alias is not part of the stable surface.
+ */
 type PartialFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? `${Key}` | `${Key}.${number}` | `${Key}.${number}.${PartialFlatPath<ArrayItem>}` : Value extends GenericForm ? `${Key}` | `${Key}.${PartialFlatPath<Value>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${PartialFlatPath<Form[Key]>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}` | `${Key}.${number}.${PartialFlatPath<ArrayItem>}` : `${Key}.${number}` : never) : never : never;
 type CompleteFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? `${Key}.${number}.${CompleteFlatPath<ArrayItem>}` : Value extends GenericForm ? `${Key}.${CompleteFlatPath<Value>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${CompleteFlatPath<Form[Key]>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}.${CompleteFlatPath<ArrayItem>}` : `${Key}.${number}` : never) : never : never;
 /**
@@ -259,6 +269,14 @@ type DeepPartial<T> = T extends Primitive ? T : T extends Array<infer ArrayItem>
  * never reach this depth.
  */
 type NestedType<RootValue, FlattenedPath extends string, FilterOutNullishTypesDuringRecursion extends boolean = true, _RootValue = FilterOutNullishTypesDuringRecursion extends false ? RootValue : NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, Key>, Rest, FilterOutNullishTypesDuringRecursion> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, NumericKey>, Rest, FilterOutNullishTypesDuringRecursion> : never : never : Key extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, Key>, Rest, FilterOutNullishTypesDuringRecursion> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, NumericKey> : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> : never;
+/**
+ * Implementation-detail primitive-leaf marker used by `DeepPartial`
+ * and sibling structural walkers. Exported so the bundled `.d.ts`
+ * references one alias instead of re-emitting the union at every
+ * recursion branch of every walker that depends on it. Not part of
+ * the stable consumer-facing surface — reach for `DeepPartial`
+ * instead.
+ */
 type Primitive = string | number | boolean | symbol | bigint | null | undefined;
 /**
  * Distinguish a tuple from a regular array.
@@ -334,10 +352,14 @@ type ArrayItem<Form, Path extends ArrayPath<Form>> = NestedType<Form, Path> exte
  * the array-recursion branch so positionally-typed array literals
  * survive intact.
  *
- * Read-side types (handleSubmit's `data` argument,
- * validate*() result payloads) intentionally stay STRICT — those
- * payloads have been parsed by the schema, so the widened shape
- * doesn't apply.
+ * `WriteShape<T>` stays STRICT — no `| Unset` widening. It's used for
+ * the callback's prev-value argument in `setValue(path, prev => ...)`
+ * (which always receives a real value, never the sentinel), for
+ * read-side types where consumers expect a structural form shape, and
+ * by internal types like `FieldStateMap<T>`. The consumer-facing
+ * write-value type is `DefaultValuesShape<T>` (composed via
+ * `SetValuePayload`), which adds `| Unset` at every recursable
+ * position.
  */
 type WriteShape<T> = T extends string | number | boolean | bigint | symbol | null | undefined ? T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends bigint ? bigint : T extends symbol ? symbol : T : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown) ? T : T extends readonly [unknown, ...unknown[]] ? {
     -readonly [K in keyof T]: WriteShape<T[K]>;
@@ -352,30 +374,75 @@ type WriteShape<T> = T extends string | number | boolean | bigint | symbol | nul
  * brand-typed sentinel consumers pass to indicate "this leaf starts
  * displayed-empty" in `defaultValues`, `setValue`, and `reset`.
  *
- * Non-primitive leaves (`Date`, `RegExp`, `Map`, `Set`, functions)
- * stay strict — `defaultValues: { joinedAt: unset }` against a
- * `Date`-typed leaf is a type error.
+ * `Unset` is admitted at every position — primitive leaves, opaque
+ * leaves (`Date`, `RegExp`, `Map`, `Set`, functions), and containers
+ * (objects, arrays, tuples, records, DUs, optional / nullable
+ * wrappers). A container `unset` recursively marks every primitive
+ * descendant blank, so `defaultValues: { profile: unset }` and
+ * `setValue('cargo', unset)` typecheck cleanly.
  *
  * The recursion mirrors `WriteShape<T>` exactly so `defaultValues`
- * stays compatible at every nested position; the only divergence is
- * the leaf widening. Tuple positions, unbounded arrays, and nested
- * records all flow through unchanged.
+ * stays compatible at every nested position. Tuple positions,
+ * unbounded arrays, and nested records all flow through unchanged.
  *
  * Example:
  *
  *   DefaultValuesShape<{ income: number; name: string; age: 21 }>
- *     // → { income: number | Unset; name: string | Unset; age: number | Unset }
+ *     // → { income: number | Unset; name: string | Unset; age: number | Unset } | Unset
  *
  * Used by `UseFormConfiguration.defaultValues`, `setValue`'s value
- * parameter, and `reset`'s parameter (commit 7 widens all three).
+ * parameter, and `reset`'s parameter.
  */
-type DefaultValuesShape<T> = T extends string | number | boolean | bigint | symbol | null | undefined ? T extends string ? string | Unset : T extends number ? number | Unset : T extends boolean ? boolean | Unset : T extends bigint ? bigint | Unset : T extends symbol ? symbol : T : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown) ? T : T extends readonly [unknown, ...unknown[]] ? {
+type DefaultValuesShape<T> = T extends string | number | boolean | bigint | symbol | null | undefined ? T extends string ? string | Unset : T extends number ? number | Unset : T extends boolean ? boolean | Unset : T extends bigint ? bigint | Unset : T extends symbol ? symbol : T : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown) ? T | Unset : T extends readonly [unknown, ...unknown[]] ? {
     -readonly [K in keyof T]: DefaultValuesShape<T[K]>;
-} : T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? {
+} | Unset : T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? {
     -readonly [K in keyof T]: DefaultValuesShape<T[K]>;
-} : Array<DefaultValuesShape<U>> : T extends object ? {
+} | Unset : Array<DefaultValuesShape<U>> | Unset : T extends object ? {
     [K in keyof T]: DefaultValuesShape<T[K]>;
-} : T;
+} | Unset : T;
+/**
+ * Single-walker fusion of `DeepPartial` and `DefaultValuesShape` — the
+ * type accepted at `defaultValues`, `reset()`'s parameter, and every
+ * partial-shape consumer. Every level is optional and every position
+ * — primitive leaf, opaque leaf, or container — admits `| Unset`, in
+ * one tree walk where the prior `DeepPartial<DefaultValuesShape<F>>`
+ * composition walked twice.
+ *
+ * Both passes had identical topology (object → mapped, tuple →
+ * positional, array → recurse, primitive → terminal) — the doubled
+ * recursion exhausted the depth budget at consumer call sites that
+ * wire multiple complex forms into one scope. Collapsing them buys
+ * back the headroom plus a side fix: opaque leaves (`Date`, `Map`,
+ * `Set`, `RegExp`, functions) now stay intact when their containing
+ * property is optional, rather than getting structurally destructured
+ * by `DeepPartial`'s pass.
+ *
+ * Tuple positions, array elements, and discriminated-union variants
+ * all flow through unchanged from the prior semantics. Container
+ * positions widen with `| Unset` so `defaultValues: { profile: unset }`
+ * and `reset({ cargo: unset })` typecheck — the runtime recursively
+ * marks every primitive descendant blank.
+ *
+ * ```ts
+ * type T = DefaultValuesInput<{
+ *   email: string
+ *   joinedAt: Date
+ *   profile: { name: string; age: number }
+ * }>
+ * // → {
+ * //   email?: string | Unset
+ * //   joinedAt?: Date | Unset
+ * //   profile?: { name?: string | Unset; age?: number | Unset } | Unset
+ * // } | Unset
+ * ```
+ */
+type DefaultValuesInput<T> = T extends string ? string | Unset : T extends number ? number | Unset : T extends boolean ? boolean | Unset : T extends bigint ? bigint | Unset : T extends symbol ? symbol : T extends null | undefined ? T : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown) ? T | Unset : T extends readonly [unknown, ...unknown[]] ? {
+    -readonly [K in keyof T]?: DefaultValuesInput<T[K]>;
+} | Unset : T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? {
+    -readonly [K in keyof T]?: DefaultValuesInput<T[K]>;
+} | Unset : Array<DefaultValuesInput<U>> | Unset : T extends object ? {
+    [K in keyof T]?: DefaultValuesInput<T[K]>;
+} | Unset : T;
 
 /**
  * Per-form options threaded from `useForm` into the adapter factory.
@@ -469,6 +536,42 @@ declare const ROOT_PATH_KEY: PathKey;
  */
 declare function isPathPrefix(prefix: readonly Segment[], path: readonly Segment[]): boolean;
 
+/**
+ * Per-FormStore registry tracking which DOM elements have opted into
+ * persistence for which paths. Lives on the FormStore so that two SFCs
+ * sharing a key share the registry — opt-ins are per-element, not
+ * per-component.
+ *
+ * The directive's input handler computes `meta.persist` for each write
+ * by calling `hasOptIn(elementId, path)` — only THIS element's writes
+ * persist if THIS element opted in. Other call sites that aren't tied
+ * to a single element (history undo/redo, field-array helpers, devtools
+ * edits) use `hasAnyOptInForPath(path)` — persist if any element has
+ * opted into that path.
+ *
+ * Internal data structure: `Map<PathKey, Set<elementId>>`. Small forms
+ * have ~10-50 paths; iteration is cheap. All operations are O(1) given
+ * (id, path).
+ */
+type PersistOptInRegistry = {
+    /** Add an opt-in entry; idempotent. */
+    add(elementId: string, path: PathKey): void;
+    /** Remove a single (element, path) entry. */
+    remove(elementId: string, path: PathKey): void;
+    /** Remove every opt-in for `elementId`. Called from directive's beforeUnmount. */
+    removeAllFor(elementId: string): void;
+    /** Check whether THIS element has opted into THIS path. */
+    hasOptIn(elementId: string, path: PathKey): boolean;
+    /** Check whether ANY element has opted into this path. */
+    hasAnyOptInForPath(path: PathKey): boolean;
+    /** Iterate every path that currently has at least one opt-in. */
+    optedInPaths(): IterableIterator<PathKey>;
+    /** True iff no element has opted into any path. */
+    isEmpty(): boolean;
+    /** Drop every entry. Called from FormStore.dispose. */
+    clear(): void;
+};
+
 /**
  * Identifier for a form. A `FormKey` is the string passed via
  * `useForm({ key })`, used to look up a form by name from a distant
@@ -699,37 +802,24 @@ type AbstractSchema<Form, GetValueFormType> = {
      */
     getEmptyValueAtPath(path: Path): unknown;
     /**
-     * Give the schema a chance to normalize the consumer's write value
-     * before it lands in storage / hits the slim-primitive gate. Each
-     * schema library exposes this concept differently — Zod calls it
-     * `z.preprocess(fn, inner)`, Yup calls it `.transform()`, Valibot
-     * spells it `pipe(transform(fn), inner)` — but the shape is the
-     * same: "this input shape gets coerced into that storage shape at
-     * the boundary."
-     *
-     * Runs SYNCHRONOUSLY at the write boundary so storage holds the
-     * post-normalization shape. Without this, a schema like `notify:
-     * z.preprocess(v => v == null ? defaultVar : v, innerDU)` would
-     * let the consumer write `null` and lock storage into `null` —
-     * because the gate sees the raw input (which the preprocess wrapper
-     * accepts as `unknown`) and storage holds a shape no variant
-     * matches.
-     *
-     * Adapters MUST:
-     *   - Return `value` unchanged when no normalization is declared at
-     *     the path.
-     *   - Return `value` unchanged when the user's normalization fn
-     *     returns a `Promise` (async coercion can't run at write time —
-     *     validation handles it during parse).
-     *   - Let user-thrown errors propagate (the user wrote the fn; we
-     *     just tag the path in the wrapper error for diagnostics).
-     *
-     * Normalization runs when `path` equals the wrapper's exact
-     * location. Writes deeper than the wrapper bypass it (a wrapper
-     * over the whole subtree can't be invoked from a partial leaf
-     * write).
-     */
-    normalizeWriteValueAtPath(value: unknown, path: Path): unknown;
+     * Reports whether `path` resolves to (or descends through) a
+     * schema-side normalizer that runs at parse, not at the write
+     * boundary. In Zod v4 that's `z.preprocess(fn, inner)` and
+     * `z.coerce.X()` (both desugar to `ZodPipe<ZodTransform, inner>`);
+     * in Zod v3 it's `ZodEffects` with `_def.effect.type === 'preprocess'`.
+     *
+     * Consulted by the slim-primitive write gate. When true at a path,
+     * the gate accepts the consumer's raw value verbatim and stops
+     * walking children — storage holds the user's input, and the
+     * normalizer fires during `safeParse` (handleSubmit / validate /
+     * validateAsync), not at `setValue` time.
+     *
+     * Path-prefix semantic: returns true if ANY ancestor of `path`
+     * resolves to such a wrapper, so descendants under a preprocess-
+     * wrapped container also short-circuit the gate. Adapters cache
+     * the result by canonicalized path key.
+     */
+    isPreprocessOrCoerceLeaf(path: Path): boolean;
     /**
      * Distinguish a tuple (fixed-length, position-typed) from an
      * unbounded array at `path`. The runtime calls this on every
@@ -1021,7 +1111,7 @@ type UnionDiscriminatorContext = {
  * the set of kinds the path's leaf schema accepts. A write is gated
  * by `accepted.has(slimKindOf(value))`.
  */
-type SlimPrimitiveKind = 'string' | 'number' | 'boolean' | 'bigint' | 'date' | 'null' | 'undefined' | 'object' | 'array' | 'symbol' | 'function' | 'map' | 'set';
+type SlimPrimitiveKind = 'string' | 'number' | 'boolean' | 'bigint' | 'date' | 'null' | 'undefined' | 'object' | 'array' | 'symbol' | 'function' | 'map' | 'set' | 'file';
 /**
  * The "no result yet" status returned by the reactive `validate()` ref
  * while a validation run is in flight.
@@ -1053,15 +1143,23 @@ type SettledValidationStatus<Form> = {
 type ReactiveValidationStatus<Form> = PendingValidationStatus | SettledValidationStatus<Form>;
 /**
  * What to do when a submit attempt fails validation. The library can
- * focus and/or scroll the first errored field into view without
- * wiring an `onError` callback yourself. Off by default.
- *
- * - `'none'` (default): no automatic UI nudge.
- * - `'focus-first-error'`: focus the first errored field's first
- *   visible element (with `preventScroll: true` so it doesn't fight
- *   any `'scroll-to-first-error'` choice you make).
- * - `'scroll-to-first-error'`: scroll that element into view.
- * - `'both'`: scroll first, then focus.
+ * focus and/or scroll the first errored field into view without you
+ * wiring an `onError` callback yourself. Defaults to
+ * `'focus-first-error'` because moving keyboard / screen-reader focus
+ * to the broken field on submit is an accessibility baseline; opt out
+ * with `'none'` if you're managing focus elsewhere.
+ *
+ * - `'focus-first-error'` (default): focus the first errored field's
+ *   first visible element. Modern browsers scroll the focused element
+ *   into view by default; pair with `'both'` if you want an explicit
+ *   scroll alongside.
+ * - `'scroll-to-first-error'`: scroll that element into view without
+ *   moving focus.
+ * - `'both'`: scroll first, then focus (with `preventScroll: true` so
+ *   the browser doesn't undo the explicit scroll).
+ * - `'none'`: no automatic UI nudge; the dev handles focus / scroll
+ *   manually via `form.focusFirstError()` or `form.scrollToFirstError()`
+ *   from an `onError` callback.
  *
  * If no errored field has a currently mounted, visible element, the
  * policy silently no-ops.
@@ -1428,7 +1526,7 @@ type PersistConfig = FormStorageKind | FormStorage | PersistConfigOptions;
  * })
  * ```
  */
-type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema extends AbstractSchema<Form, GetValueFormType>, DefaultValues extends DeepPartial<DefaultValuesShape<Form>>> = {
+type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema extends AbstractSchema<Form, GetValueFormType>, DefaultValues extends DefaultValuesInput<Form>, K extends FormKey = FormKey> = {
     /**
      * The schema describing the form's shape and validation rules.
      * Typed entry points like `attaform/zod` accept the
@@ -1459,8 +1557,12 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      *
      * Keys starting with `__atta:` are reserved for internal use and
      * throw `ReservedFormKeyError` if passed.
+     *
+     * When passed as a string literal, the literal is preserved on
+     * `form.key` so `useWizard` and other consumers can discriminate
+     * against the union of known keys at compile time.
      */
-    key?: FormKey;
+    key?: K;
     /**
      * Initial values applied over the schema's defaults. Each field
      * falls back to the schema default (or the primitive default for
@@ -1472,8 +1574,30 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * membership, length / range bounds). Refinement-invalid defaults
      * pass through and surface as field errors — this lets you
      * rehydrate stale saved data without losing the user's input.
+     *
+     * Accepts a plain value, a sync function, or an async function:
+     *
+     * ```ts
+     * // Plain value — applies at construction.
+     * defaultValues: { email: '' }
+     *
+     * // Sync function — invoked on a microtask after construction.
+     * defaultValues: () => buildDraft()
+     *
+     * // Async function — form starts with the schema's slim defaults
+     * // and `form.hydrating` flips true while the promise is
+     * // in flight; on resolve the values apply and `hydrating` flips
+     * // false. Under SSR the factory fires via `onServerPrefetch` so
+     * // the resolved payload bakes into hydration transfer state and
+     * // the client never re-fetches.
+     * defaultValues: async () => api.fetchDraft(userId)
+     * ```
+     *
+     * Errors thrown by a function-form factory surface on
+     * `form.hydrateError`; the form stays usable with slim defaults.
+     * Call `form.rehydrate()` to re-fire the factory.
      */
-    defaultValues?: DefaultValues;
+    defaultValues?: DefaultValues | (() => DefaultValues) | (() => Promise<DefaultValues>);
     /**
      * Whether to validate default values at construction. Default
      * `true`.
@@ -1481,7 +1605,7 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * - `true` (default): the schema is run against the derived
      *   defaults immediately; any failures populate `form.errors` from
      *   the first frame. The UI decides when to *show* errors — gate
-     *   on `form.fields.<path>.touched`, `form.meta.submitCount`, etc.
+     *   on `form.fields.<path>.touched`, `form.meta.submissionAttempts`, etc.
      * - `false`: refinements are stripped during defaults derivation
      *   and construction-time validation is skipped. Useful for
      *   multi-step wizards, field arrays seeded with placeholder
@@ -1494,12 +1618,16 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
     /**
      * Automatic UI nudge on submit-validation failure. Fires after
      * errors are populated and before your `onError` callback runs.
-     * Default `'none'`.
+     * Default `'focus-first-error'`, which moves keyboard / screen-reader
+     * focus to the broken field as an accessibility baseline.
      *
-     * - `'focus-first-error'`: focus the first errored field's first
-     *   visible element (without scrolling).
-     * - `'scroll-to-first-error'`: scroll it into view.
+     * - `'focus-first-error'` (default): focus the first errored field's
+     *   first visible element.
+     * - `'scroll-to-first-error'`: scroll it into view without focusing.
      * - `'both'`: scroll, then focus.
+     * - `'none'`: opt out entirely; handle focus / scroll yourself in an
+     *   `onError` callback via `form.focusFirstError()` or
+     *   `form.scrollToFirstError()`.
      *
      * If no errored field has a currently-mounted, visible element,
      * the policy silently no-ops.
@@ -1658,31 +1786,53 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      */
     sensitiveNames?: readonly string[];
     /**
-     * Cross-tab synchronisation via BroadcastChannel. Defaults to `true`
-     * (when the browser supports it and the page is in a secure
-     * context): a keyed `useForm` callsite auto-pairs with same-keyed
-     * siblings in other same-origin tabs and mirrors their mutations
-     * in near real-time.
+     * Cross-tab synchronisation via BroadcastChannel. **Defaults to
+     * `false` (opt-in).** Setting `true` on a keyed `useForm` callsite
+     * auto-pairs the form with same-keyed siblings in other same-origin
+     * tabs and mirrors their mutations in near real-time.
      *
      * **Resolution order (per-register override > per-form > global > library):**
      *
-     *   register(path, { multiTab })  >  useForm({ multiTab })  >  AttaformDefaults.multiTab  >  library default (`true`)
+     *   register(path, { multiTab })  >  useForm({ multiTab })  >  AttaformDefaults.multiTab  >  library default (`false`)
      *
-     * **When to set `false`:** forms holding PII / PHI, contexts where
-     * tab isolation is required by policy, or any flow where conflicting
-     * tab edits could corrupt user intent. Sensitive-named paths (via
-     * `sensitiveNames`) are always stripped from outbound broadcasts
-     * regardless of this setting.
+     * **Why opt-in.** Same-keyed forms broadcasting by default leaks
+     * surprise: a user editing in one tab sees their values appear in a
+     * sibling tab they forgot was open, including PII / PHI for forms
+     * that don't explicitly use `sensitiveNames`. Mirrors the `persist`
+     * default (also opt-in): both opt-in surfaces compose into one
+     * consistent "richer state needs explicit consent" rule.
      *
-     * **Secure-context requirement.** Multi-tab sync is silently disabled
-     * outside `window.isSecureContext === true` (HTTPS or localhost). On
-     * plain HTTP a one-shot dev warning fires and the module noops.
+     * **What's stripped even when opt-in.** `File` and `Blob` values
+     * never traverse the channel regardless of this flag (security +
+     * `structuredClone` cost). Sensitive-named paths (via
+     * `sensitiveNames`) are stripped both directions. See the
+     * multi-tab sync page for the full security model.
+     *
+     * **Secure-context requirement.** Even with `multiTab: true`, sync
+     * is silently disabled outside `window.isSecureContext === true`
+     * (HTTPS or localhost). On plain HTTP a one-shot dev warning fires
+     * and the module noops.
      *
      * **Anonymous (auto-keyed) forms skip sync entirely** — without a
      * consumer-supplied `key`, cross-tab identity is undefined and the
      * channel would be solo by construction.
      */
     multiTab?: boolean;
+    /**
+     * @internal
+     * SSR prefetch mark — set by the `attaform/vite` compile-time
+     * transform on `useForm` calls whose surrounding SFC template (or a
+     * computed feeding it) reads the form's reactive state. The flag
+     * enqueues the form on the registry's SSR prefetch queue so an
+     * async `defaultValues` factory runs inside `onServerPrefetch` and
+     * the resolved payload bakes into the hydration transfer state.
+     *
+     * Consumers do not write this directly — `form.activate()` is the
+     * documented escape hatch when the transform's static analysis
+     * can't see a reference (cross-module sharing, dynamic property
+     * access, headless contexts).
+     */
+    __ssrAccessed?: boolean;
 };
 /**
  * App-level defaults applied to every `useForm` call. Set these once
@@ -1762,7 +1912,7 @@ type AttaformDefaults = {
      *
      * ```ts
      * (field, formMeta) =>
-     *   formMeta.submitCount > 0 || (field.touched === true && field.dirty)
+     *   formMeta.submissionAttempts > 0 || (field.touched === true && field.dirty)
      * ```
      *
      * Compose with the library default via the public
@@ -1851,25 +2001,28 @@ type AttaformDefaults = {
      */
     sensitiveNames?: readonly string[];
     /**
-     * App-wide default for `useForm({ multiTab })`. Default `true` when
-     * the runtime supports `BroadcastChannel` AND `window.isSecureContext`
-     * is true (HTTPS in production, localhost in development) — same gate
-     * browsers apply to other sensitive APIs (clipboard, geolocation,
-     * push, web crypto subtle).
-     *
-     * Set to `false` once at the plugin level for a multi-tenant
-     * deployment that prefers tab-isolation by default; individual forms
-     * can still opt back in via `useForm({ multiTab: true })`.
+     * App-wide default for `useForm({ multiTab })`. Library default is
+     * `false` (opt-in) — same posture as `persist`. Set to `true` once
+     * at the plugin level to enable cross-tab sync for every form in
+     * the app by default; individual forms can still opt out via
+     * `useForm({ multiTab: false })`.
      *
      * **Resolution order (per-form wins):**
      *
-     *   useForm({ multiTab })  >  AttaformDefaults.multiTab  >  library default (`true`)
+     *   useForm({ multiTab })  >  AttaformDefaults.multiTab  >  library default (`false`)
      *
-     * **Secure-context gate.** Multi-tab sync only activates over HTTPS
-     * or localhost. On plain HTTP, the module silently noops with a
-     * one-shot dev-mode warning — production deployments MUST be served
-     * over HTTPS for sync to function. See the multi-tab-sync recipe's
-     * Security section for the threat model.
+     * **Why opt-in.** Auto-broadcasting same-keyed forms surprises users
+     * (a value typed in one tab appearing in another they forgot was
+     * open) and leaks state for forms that don't explicitly use
+     * `sensitiveNames`. Paired with `persist` (also opt-in), the two
+     * "richer state" surfaces follow one consistent rule: explicit
+     * consent.
+     *
+     * **Secure-context gate.** Even with `multiTab: true`, sync only
+     * activates over HTTPS or localhost. On plain HTTP, the module
+     * silently noops with a one-shot dev-mode warning — production
+     * deployments MUST be served over HTTPS for sync to function. See
+     * the multi-tab-sync recipe's Security section for the threat model.
      */
     multiTab?: boolean;
 };
@@ -2005,7 +2158,7 @@ type MetaTrackerValue = {
      * want pre-error introspection ("the user hasn't decided yet"
      * indicator, "review unanswered fields" hint).
      *
-     * See `docs/recipes/blank-inputs.md` for the full conceptual model.
+     * See `docs/validation/blank.md` for the full conceptual model.
      */
     blank: boolean;
 };
@@ -2222,6 +2375,14 @@ type RegisterValue<Value = unknown> = Readonly<{
      * directives signal whether the write should be persisted.
      */
     setValueWithInternalPath: (value: unknown, meta?: WriteMeta) => boolean;
+    /**
+     * Mark this field as DOM-connected during SSR so a server-rendered
+     * template that reads `form.fields.<path>.connected` doesn't
+     * flicker on hydration. The `v-register` directive calls this for
+     * you; no-op on the client.
+     * @internal
+     */
+    markConnectedOptimistically: () => void;
     /**
      * Canonical, JSON-encoded path key for this binding (e.g.
      * `'["items",0,"name"]'`). Useful for stable Map / Set keys, log
@@ -2260,6 +2421,90 @@ type RegisterValue<Value = unknown> = Readonly<{
      * `key`.
      */
     formInstanceId: string;
+    /**
+     * Whether this binding opted into persistence via `register(path, { persist: true })`.
+     * @internal
+     */
+    persist: boolean;
+    /**
+     * Whether this binding acknowledged a sensitive-name override.
+     * @internal
+     */
+    acknowledgeSensitive: boolean;
+    /**
+     * Per-element persistence opt-in registry. Used by directive integrations.
+     * @internal
+     */
+    persistOptIns: PersistOptInRegistry;
+    /**
+     * Resolved sensitive-path predicate honoring this form's
+     * `sensitiveNames` cascade. The directive calls this through
+     * `enforceSensitiveCheck` when a `register('path', { persist: true })`
+     * binding mounts so a per-form custom list (e.g. extending with
+     * `'mrn'`) gates persistence enrolment correctly.
+     * @internal
+     */
+    isSensitivePath: (path: Path | PathKey | string) => boolean;
+    /**
+     * Whether this binding declared `register('path', { multiTab: false })`.
+     * Drives the directive's mount/unmount lifecycle: when `false`, the
+     * directive's `created` hook bumps `state.noSyncPaths` for this
+     * path, and `beforeUnmount` decrements. When `true` (the default),
+     * the binding rides the form-level cascade.
+     * @internal
+     */
+    multiTab: boolean;
+    /**
+     * Pre-bound mount hook for `multiTab: false` bindings — calls
+     * `state.incrementNoSyncOptOut(path)` with this binding's path.
+     * `undefined` when `multiTab !== false`. The directive invokes
+     * during the mount lifecycle.
+     * @internal
+     */
+    markNoSync?: () => void;
+    /**
+     * Pre-bound unmount hook for `multiTab: false` bindings — calls
+     * `state.decrementNoSyncOptOut(path)`. Paired with `markNoSync`;
+     * the directive invokes on `beforeUnmount` (and on `beforeUpdate`
+     * when the binding transitions out of opt-out).
+     * @internal
+     */
+    unmarkNoSync?: () => void;
+    /**
+     * Sync transform pipeline applied by the directive's assigner to
+     * user-typed values before they reach form state. See
+     * `RegisterOptions.transforms` for the public contract; this is
+     * the readonly internal handle the directive iterates. Optional
+     * so hand-rolled `RegisterValue` mocks (test fixtures, custom
+     * integrations) don't have to declare an empty array — the
+     * directive falls back to a no-op pipeline.
+     * @internal
+     */
+    transforms?: ReadonlyArray<RegisterTransform>;
+    /**
+     * Schema-driven coercion closure baked at register-time. Captures
+     * the path's slim accept set and the resolved coercion index so
+     * the per-event hot path is a single function call. Identity
+     * function when coercion is disabled or the path admits no
+     * coercion target. Optional so hand-rolled `RegisterValue` mocks
+     * (test fixtures, custom integrations) don't have to declare it —
+     * the directive falls back to identity.
+     * @internal
+     */
+    coerce?: (value: unknown) => unknown;
+    /**
+     * Element-level coercion closure for container paths
+     * (`z.array(...)` / `z.set(...)`). Coerces a scalar DOM-side
+     * value (an option's `value` attribute, a checkbox's value)
+     * against the container's element type. `undefined` when the
+     * path isn't a container — scalar paths use `coerce` exclusively.
+     *
+     * Used by the directive's read-side comparisons in setChecked
+     * (array/Set branches) and setSelected (multi-select) to keep
+     * parity with the change handler's WRITE-side path-level coerce.
+     * @internal
+     */
+    coerceElement?: (value: unknown) => unknown;
     /**
      * Read-only, string-form view of the field's current value — what
      * the compile-time `:value` injection reads on every input /
@@ -2272,6 +2517,50 @@ type RegisterValue<Value = unknown> = Readonly<{
      * patching `el.value` back to `'0'` (the slim default).
      */
     displayValue: Readonly<Ref<string>>;
+    /**
+     * Add this field's path to the form's `blankPaths` set,
+     * writing the slim default to storage. Returns the `setValueAtPath`
+     * boolean (`true` accepted, `false` rejected by the slim-primitive
+     * gate). Inherits the binding's `persist` meta so the mark rides
+     * the same persistence channel as user-typed writes.
+     *
+     * Called by the directive's input listener on numeric clear (commit
+     * 5) and by the imperative `setValue(path, unset)` translation
+     * (commit 7). Don't call from consumer code.
+     * @internal
+     */
+    markBlank: () => boolean;
+    /**
+     * `true` when the schema's slim primitive set at this path includes
+     * `'undefined'` — i.e. the leaf was declared `.optional()` (or as
+     * part of a union admitting `undefined`). Cached at register-time.
+     *
+     * Read by the directive's text-input listener to map a DOM clear
+     * (`el.value === ''`) onto `undefined` storage instead of `''`, so
+     * the `.optional()` "absent" semantic survives user interactions.
+     * Without this, a user who typed an invalid value into an optional
+     * field and then cleared it would be stuck with a permanent
+     * validation error (storage holds `''`, which is neither
+     * `undefined` nor a valid inner value).
+     * @internal
+     */
+    acceptsUndefined: boolean;
+    /**
+     * `true` when the schema's slim primitive set at this path includes
+     * `'string'`. Cached at register-time alongside
+     * [[acceptsUndefined]].
+     *
+     * Read by the directive's text-input listener so a DOM clear on a
+     * numeric-only (or boolean-only, bigint-only) leaf takes the
+     * `markBlank` path instead of writing `''` through the assigner:
+     * the slim-primitive gate would reject the empty string anyway,
+     * and the directive's post-write force-sync would then snap the
+     * DOM back to the last accepted value, making the final character
+     * undeletable. With `markBlank`, storage holds the slim default
+     * with the blank meta and the DOM stays empty.
+     * @internal
+     */
+    acceptsString: boolean;
 }>;
 /**
  * Custom assigner installed on an element via the directive's
@@ -2444,6 +2733,48 @@ type RegisterModelDynamicCustomDirective = ObjectDirective<HTMLInputElement | HT
  * directives manually.
  */
 type RegisterDirective = RegisterTextCustomDirective | RegisterCheckboxCustomDirective | RegisterSelectCustomDirective | RegisterRadioCustomDirective | RegisterModelDynamicCustomDirective;
+/**
+ * Module augmentation: register `v-register` with Vue's template
+ * type system. Lives in `types-api` because every public entry
+ * (`attaform`, `attaform/zod`, `attaform/zod-v3`, `attaform/zod-v4`)
+ * transitively reaches this file via the `useForm` return type, so
+ * the augmentation propagates to consumer SFCs regardless of which
+ * entry they import from — and regardless of whether they install
+ * `attaform/nuxt` or the Vite plugin.
+ *
+ * Augmentation targets `vue` rather than `@vue/runtime-core`:
+ * `GlobalDirectives` is originally declared in `@vue/runtime-core`,
+ * but consumers and Volar's strict-template codegen both resolve
+ * the interface through `vue`'s `export * from '@vue/runtime-dom'`
+ * → `export * from '@vue/runtime-core'` chain. TypeScript merges
+ * interfaces across re-exports, so augmenting `'vue'` reaches Volar
+ * without needing `@vue/runtime-core` to be hoisted into the
+ * library's own `node_modules` for its own typecheck.
+ */
+declare module 'vue' {
+    interface GlobalDirectives {
+        /**
+         * The `v-register` directive. Binds a form field to a native
+         * input, select, textarea, checkbox, or radio:
+         *
+         * ```vue
+         * <input v-register="form.register('email')" />
+         * ```
+         *
+         * Also works on custom components whose root is NOT a native
+         * input — call `useRegister()` in the child's setup to read the
+         * parent's binding, then re-bind `v-register` onto an inner
+         * native element. (When the wrapper's root IS the input itself,
+         * attribute fallthrough handles it; `useRegister` is unnecessary.)
+         *
+         * Modifier support varies by element:
+         *   - text / number / textarea: `.lazy`, `.trim`, `.number`
+         *   - select: `.number`
+         *   - checkbox / radio: none
+         */
+        vRegister: RegisterDirective;
+    }
+}
 /**
  * Callback form of `setValue`'s value argument. Receives the previous
  * value at the path and returns the next value:
@@ -2544,7 +2875,7 @@ type FieldState<Value = unknown> = {
     readonly dirty: boolean;
     readonly focused: boolean | null;
     readonly blurred: boolean | null;
-    readonly touched: boolean | null;
+    readonly touched: boolean;
     readonly connected: boolean;
     /**
      * The first DOM element bound to this path via `v-register`, or
@@ -2732,15 +3063,89 @@ type FieldState<Value = unknown> = {
  * `FieldState<number | undefined>`. Matches the runtime's stub
  * `FieldState` for inactive-variant paths.
  */
-type FieldStateMapEntry<T> = [T] extends [
-    string | number | boolean | bigint | symbol | null | undefined | Date
-] ? FieldState<T> : [T] extends [ReadonlyArray<infer U>] ? {
-    readonly [K: number]: FieldStateMapEntry<U>;
-} : [T] extends [object] ? [IsUnion<T>] extends [true] ? {
-    readonly [K in KeyofUnion<T>]-?: FieldStateMapEntry<ValueOfUnion<T, K>>;
-} : {
-    readonly [K in keyof T]-?: FieldStateMapEntry<T[K]>;
-} : FieldState<T>;
+/**
+ * Leaf-shape dispatch table for `LeafWalker`. Each entry maps a walker
+ * kind to the leaf type that walker produces at primitive / Date /
+ * non-recursable positions. The lookup `LeafSchemeFor<T>[Kind]`
+ * threads `T` through the leaf type when the kind needs it
+ * (`field` carries `FieldState<T>`); kinds that don't depend on
+ * `T` simply ignore it (`errors` always produces
+ * `readonly ValidationError[] | undefined`).
+ *
+ * Adding a new walker is one entry here plus a one-line wrapper
+ * alias (`type FooShape<T> = LeafWalker<T, 'foo'>`). The walker
+ * topology is shared; only the leaf changes.
+ *
+ * The `errors` entry threads `T` to preserve `| undefined` when the
+ * value type itself includes undefined (DU variant-only fields whose
+ * lifted shape resolves to `X | undefined`). Statically-known leaves
+ * collapse to `readonly ValidationError[]` (no undefined); dynamic-key
+ * boundaries (array indices, record keys) re-introduce `| undefined`
+ * via the structural index-signature channels.
+ *
+ * Preprocess / coerce leaves (StorageShape = `unknown`) are
+ * statically known too — the IsUnknown filter keeps them on the
+ * non-optional branch instead of being swept into the dynamic
+ * `| undefined` arm by `undefined extends unknown`.
+ *
+ * Implementation-detail surface — consumers reach for `FieldStateMap`
+ * or `FormErrorsSurface` instead.
+ */
+type IsUnknown<T> = IsAny<T> extends true ? false : unknown extends T ? true : false;
+interface LeafSchemeFor<T> {
+    field: FieldState<T>;
+    errors: IsUnknown<T> extends true ? readonly ValidationError[] : undefined extends T ? readonly ValidationError[] | undefined : readonly ValidationError[];
+}
+/**
+ * Generic walk that produces a proxy shape over `T` with leaves
+ * dispatched via `LeafSchemeFor<T>[Kind]`. The walk topology
+ * (object → mapped homomorphic, object-union → KeyofUnion merge,
+ * array → indexed, primitive / Date → terminal) is identical
+ * across walker kinds; only the leaf type differs.
+ *
+ * Replaces the duplicated bodies of `FieldStateMapEntry` and
+ * `ErrorsProxyShape`. The prior duplication walked the same shape
+ * twice per useForm return type — once for the fields proxy, once
+ * for the errors proxy. Factoring lets the bundled `.d.ts` carry one
+ * shared walker body plus per-kind one-line wrappers, halving the
+ * recursive depth contribution from these two proxies on consumer
+ * call sites.
+ *
+ * `StripOptional` controls whether optional modifiers on input
+ * properties are stripped at every recursion level. `true` (default)
+ * matches the fields proxy semantics — every known leaf carries a
+ * `FieldState` wrapper regardless of source `?`. `false` matches the
+ * errors proxy semantics — the proxy shape stays structurally
+ * identical to the input form, optional keys included.
+ *
+ * Implementation-detail surface — consumers reach for `FieldStateMap`
+ * or `FormErrorsSurface` instead.
+ */
+type LeafWalker<T, Kind extends keyof LeafSchemeFor<unknown>, StripOptional extends boolean = true> = [T] extends [string | number | boolean | bigint | symbol | null | undefined | Date | File] ? LeafSchemeFor<T>[Kind] : [T] extends [ReadonlyArray<infer U>] ? {
+    readonly [K: number]: LeafWalker<U, Kind, StripOptional>;
+} & ContainerSelfErrorsSlot<T, Kind> : [T] extends [object] ? [IsUnion<T>] extends [true] ? StripOptional extends true ? {
+    readonly [K in KeyofUnion<T>]-?: LeafWalker<ValueOfUnion<T, K>, Kind, StripOptional>;
+} & ContainerSelfErrorsSlot<T, Kind> : {
+    readonly [K in KeyofUnion<T>]: LeafWalker<ValueOfUnion<T, K>, Kind, StripOptional>;
+} & ContainerSelfErrorsSlot<T, Kind> : StripOptional extends true ? {
+    readonly [K in keyof T]-?: LeafWalker<T[K], Kind, StripOptional>;
+} & ContainerSelfErrorsSlot<T, Kind> : {
+    readonly [K in keyof T]: LeafWalker<T[K], Kind, StripOptional>;
+} & ContainerSelfErrorsSlot<T, Kind> : LeafSchemeFor<T>[Kind];
+/**
+ * Intersection augmenting every container in the `form.errors` walker
+ * with a `''` sentinel slot — the per-container home for cross-field
+ * refine errors, server-side container marks, and (at root) form-level
+ * errors. Gated on `Kind extends 'errors'` so `form.values` and
+ * `form.fields` surfaces stay untouched. Carve-out for schemas that
+ * legitimately declare a `''` field: the declared field type wins; at
+ * runtime the two collide harmlessly (errors at the literal leaf and
+ * any container-self errors share the slot via array concat).
+ */
+type ContainerSelfErrorsSlot<T, Kind> = Kind extends 'errors' ? '' extends keyof T ? unknown : {
+    readonly ['']: readonly ValidationError[];
+} : unknown;
+type FieldStateMapEntry<T> = LeafWalker<T, 'field'>;
 /**
  * Type of `form.fields` — leaf-aware drillable callable Proxy. At
  * a leaf path the proxy resolves to a `FieldState<Value>`; at
@@ -2803,14 +3208,18 @@ type FieldStateMap<Form extends GenericForm> = ([IsUnion<Form>] extends [true] ?
 type FormErrorRecord = Record<string, ValidationError[]>;
 /**
  * Type of `form.errors`. Leaf-aware drillable callable Proxy. At a
- * leaf path the proxy resolves to `ValidationError[] | undefined`;
- * at a container path it returns a sub-proxy you can keep drilling.
+ * statically-known leaf the proxy resolves to `readonly ValidationError[]`
+ * (empty array when no errors land); at dynamic boundaries (array
+ * indices, record keys, DU variant-only fields) it resolves to
+ * `readonly ValidationError[] | undefined`. At a container path it
+ * returns a sub-proxy you can keep drilling.
  *
  * Dot/bracket access mirrors the schema shape:
  *
  * ```ts
- * form.errors.email                  // ValidationError[] | undefined (leaf)
- * form.errors.user.profile.email     // ValidationError[] | undefined (chained leaves)
+ * form.errors.email                  // readonly ValidationError[] (static leaf)
+ * form.errors.user.profile.email     // readonly ValidationError[] (chained static leaves)
+ * form.errors.posts[3]?.title        // readonly ValidationError[] | undefined (past array boundary)
  * form.errors.address                // sub-proxy (container — descend further)
  * ```
  *
@@ -2829,38 +3238,47 @@ type FormErrorRecord = Record<string, ValidationError[]>;
  */
 /**
  * Recursive shape of the `form.errors` proxy. Mirrors the schema:
- * primitive leaves expose `ValidationError[] | undefined` directly;
- * containers expose a sub-shape you can keep drilling. Arrays expose
- * numeric-indexed sub-shapes.
+ * statically-known primitive leaves expose `readonly ValidationError[]`
+ * (always an array; empty when no errors); leaves whose value type
+ * itself includes `undefined` (DU variant-only fields) keep the
+ * `| undefined` branch. Containers expose a sub-shape you can keep
+ * drilling. Arrays expose numeric-indexed sub-shapes; reading a
+ * numeric index introduces `| undefined` via noUncheckedIndexedAccess.
  *
  * Augmented with the callable signatures so dot-access and function-
  * call coexist on the same identifier.
  */
 type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
-    (path: string): readonly ValidationError[] | undefined;
+    (path: string): readonly ValidationError[];
     /**
      * Tuple-segment form. Validated against `FlatPath<Form>` so literal
      * tuples that don't resolve to a known path fail at the call site.
      * Dynamic `Path`-typed inputs hit the untyped fallback overload below.
      */
-    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[] | undefined;
-    (segments: ReadonlyArray<string | number>): readonly ValidationError[] | undefined;
+    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
+    (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
      * No-arg call returns the form-level error aggregate — same as
-     * `form.errors([])` and `form.meta.errors`. `undefined` when the
-     * form has no errors; readonly array otherwise.
+     * `form.errors([])` and `form.meta.errors`. Always a readonly array;
+     * empty when the form has no errors.
      */
-    (): readonly ValidationError[] | undefined;
+    (): readonly ValidationError[];
 };
-type ErrorsProxyShape<T> = [T] extends [
-    string | number | boolean | bigint | symbol | null | undefined | Date
-] ? readonly ValidationError[] | undefined : [T] extends [ReadonlyArray<infer U>] ? {
-    readonly [K: number]: ErrorsProxyShape<U>;
-} : [T] extends [object] ? [IsUnion<T>] extends [true] ? {
-    readonly [K in KeyofUnion<T>]: ErrorsProxyShape<ValueOfUnion<T, K>>;
-} : {
-    readonly [K in keyof T]: ErrorsProxyShape<T[K]>;
-} : readonly ValidationError[] | undefined;
+/**
+ * Implementation-detail walker backing `form.errors` typed proxy.
+ * Thin alias over `LeafWalker<T, 'errors', false>` — the shared walker
+ * topology is defined once at `LeafWalker` and parameterized via
+ * `LeafSchemeFor`. `false` preserves optional-key modifiers (errors
+ * proxy mirrors the input shape including `?`); contrast with the
+ * fields proxy alias which strips them via the default `true`.
+ *
+ * Exported so the bundled `.d.ts` references a single alias body
+ * rather than re-emitting the full union-aware recursion at every
+ * consumer call site that types `form.errors`. Multiple useForm
+ * instances in one scope otherwise compound this into TS2589
+ * territory. Consumers should reach for `FormErrorsSurface` instead.
+ */
+type ErrorsProxyShape<T> = LeafWalker<T, 'errors', false>;
 /**
  * Type of `form.values`. Drillable readonly callable proxy. Unlike
  * `form.errors` and `form.fields`, containers are USEFUL terminals:
@@ -2994,7 +3412,31 @@ type FormMeta<F = unknown> = FieldState<F> & {
      * outcome (validation failure, callback success, callback throw).
      * Useful for "show errors after first submit attempt" UX.
      */
-    readonly submitCount: number;
+    readonly submissionAttempts: number;
+    /**
+     * How many times wizard navigation (`wizard.next`, `wizard.back`,
+     * `wizard.goTo`) has actually departed this form. Bumped on real
+     * departures only: no-ops like `back()` from the first step, a
+     * same-key `goTo`, or a `next()` blocked by failed activation leave
+     * the counter at its prior value.
+     *
+     * Pure introspection counter — useful for "this form has been
+     * visited and left" UX (analytics, prior-step badges, layered
+     * `shouldShowErrors` predicates) but does NOT drive the library's
+     * default `shouldShowErrors` heuristic. The reveal-on-submit story
+     * runs entirely through `submissionAttempts`, which
+     * `wizard.handleSubmit` bumps on the active form at intermediate
+     * steps and on every form at the final step.
+     *
+     * Distinct from `submissionAttempts`, which counts `handleSubmit`
+     * passes only — wizard departures and form submissions are tracked
+     * separately so consumers can introspect each cleanly. Distinct
+     * from `form.validate()`, which is a read-only inspection primitive
+     * that never bumps any counter.
+     *
+     * Cleared by `form.reset()`.
+     */
+    readonly departAttempts: number;
     /**
      * The error thrown or rejected by the most recent submit callback
      * (or its `onError` handler). Cleared to `null` at the start of
@@ -3005,6 +3447,27 @@ type FormMeta<F = unknown> = FieldState<F> & {
      * `try { await onSubmit() }` instead.
      */
     readonly submitError: unknown;
+    /**
+     * Scalar mirror of `meta.errors.length`. Read it from templates and
+     * `watch()` without indexing the underlying array.
+     *
+     * Always tracks `errors.length` exactly — reactivity is wired through
+     * the same computed graph, so a `watch(form.meta.errorCount, ...)`
+     * fires when (and only when) the aggregate error count changes.
+     */
+    readonly errorCount: number;
+    /**
+     * `true` once a `handleSubmit` callback has resolved without
+     * throwing. Independent of `submissionAttempts` — a failed submit
+     * (validation failure or callback rejection) increments attempts but
+     * leaves `submitted` at `false`. Templates read it as "the form has
+     * been submitted successfully at least once."
+     *
+     * Cleared by `form.reset()` alongside `submissionAttempts` and
+     * `submitError`. For "the user has attempted a submit," read
+     * `submissionAttempts > 0` directly.
+     */
+    readonly submitted: boolean;
     /**
      * Per-`useForm()`-call identity. Stable for the lifetime of one
      * `useForm()` call; new on every fresh mount. Orthogonal to
@@ -3038,7 +3501,7 @@ type FormMeta<F = unknown> = FieldState<F> & {
  * form.register('email')        // bind to <input v-register>
  * form.values.email             // current value (proxy, no .value)
  * form.fields.email.dirty   // per-field flags
- * form.errors.email             // ValidationError[] | undefined
+ * form.errors.email             // readonly ValidationError[]
  * form.setValue('email', 'a@b.c')
  * form.handleSubmit(onSubmit)   // returns a submit handler
  * form.meta.submitting        // form-level reactive flag
@@ -3067,7 +3530,45 @@ type FormMeta<F = unknown> = FieldState<F> & {
  * For schemas without write-boundary wrappers or transforms the three
  * shapes coincide.
  */
-type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form> = {
+/**
+ * Read-only view returned by `form.blankPaths.value`. Exposes lookup
+ * (`.has`), aggregate (`.size`), and iteration over the form's
+ * blank-marked paths.
+ *
+ * `.has(input)` and the iterator yield consistent results across both
+ * input conventions the library accepts everywhere a path is named:
+ *
+ *  - **Dotted string**: `'user.email'`, matching what `register('user.email')`
+ *    or `setValue('items.0.sku', …)` accept. Convenient when no segment
+ *    contains a literal dot.
+ *  - **Array form**: `['user', 'email']`, mirroring `register(['user', 'email'])`.
+ *    Required when a single segment contains literal dots (e.g.
+ *    `['address.primary']` for a top-level key named `address.primary` —
+ *    the dotted form `'address.primary'` would be parsed as two
+ *    segments).
+ *
+ * Iteration yields `Path` arrays so the structure is unambiguous —
+ * consumers building debug UI or persisting the set never have to guess
+ * whether a dot in a segment is a separator or part of the name.
+ *
+ * Mutating the view does nothing — writes still go through
+ * `setValue(path, unset)`, `markBlank()` on a register binding, or the
+ * directive's input listener on numeric clear.
+ */
+interface BlankPathsView {
+    /** Number of blank-marked paths. */
+    readonly size: number;
+    /**
+     * `true` when the path is in the blank set. Accepts dotted-string
+     * form (parsed by [[parseDottedPath]]) or the array form.
+     */
+    has(input: string | Path): boolean;
+    /** Snapshot of all blank-marked paths as segment arrays. */
+    values(): readonly Path[];
+    /** Iterates the blank-marked paths as segment arrays. */
+    [Symbol.iterator](): IterableIterator<Path>;
+}
+type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form, K extends FormKey = FormKey> = {
     /**
      * Wraps your submit logic with validation and error routing.
      *
@@ -3306,8 +3807,96 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * const result = parseApiErrors(serverPayload, { formKey: form.key })
      * if (result.ok) form.setFieldErrors(result.errors)
      * ```
+     *
+     * Typed as the literal `K` when an explicit `key` was passed; falls
+     * back to `FormKey` when omitted (auto-generated id).
+     */
+    key: K;
+    /**
+     * `true` while a function-form `defaultValues` factory is in flight
+     * — between `useForm` construction and the moment the factory
+     * resolves (sync function on the next microtask; async function when
+     * its promise settles). `false` otherwise, including when
+     * `defaultValues` is a plain value.
+     *
+     * The form is fully usable while `hydrating` is `true` — it holds
+     * the schema's slim defaults. The flag exists so templates can show
+     * a spinner / dim the form while real data loads:
+     *
+     * ```vue
+     * <div :aria-busy="form.hydrating">…</div>
+     * ```
+     *
+     * Exposed as an auto-unwrapping `boolean` (no `.value`); reactivity
+     * is preserved via a getter that tracks the underlying ref at the
+     * access site, so `watch(() => form.hydrating, …)` and template
+     * reads both fire on change. Reading this property activates the
+     * form's factory under the lazy-by-default rule.
+     */
+    readonly hydrating: boolean;
+    /**
+     * The error from the most recent function-form `defaultValues` factory,
+     * normalized to a `ValidationError` (code `atta:hydration-failed`) so the
+     * shape matches every other surface in `form.errors` / `form.meta.errors`.
+     * `null` on construction, on successful resolution, and whenever no
+     * factory has fired. Updates with each `form.rehydrate()` call.
+     *
+     * Distinct from `meta.submitError` so retry buttons and recovery UX can
+     * stay focused on the load-time failure without entangling the submit
+     * pipeline. Read directly in templates and script (no `.value`);
+     * reactivity is preserved via a getter:
+     *
+     * ```vue
+     * <p v-if="form.hydrateError">{{ form.hydrateError.message }}</p>
+     * ```
      */
-    key: FormKey;
+    readonly hydrateError: ValidationError | null;
+    /**
+     * `true` once the form's defaults have been applied — either a plain
+     * `defaultValues` value at construction or an async factory whose
+     * settle completed successfully. Stays `false` for dormant lazy
+     * forms (factory not yet activated) and for failed activations
+     * (`hydrateError` set). Once `true`, stays `true` through refetches
+     * so stale-while-revalidate UIs can keep rendering the prior values
+     * while a `rehydrate()` is in flight.
+     *
+     * Composes with `hydrating` and `hydrateError`:
+     *
+     * ```vue
+     * <Spinner v-if="!form.ready && form.hydrating" />
+     * <ErrorBanner v-if="!form.ready && form.hydrateError" :error="form.hydrateError" />
+     * <form v-if="form.ready">…</form>
+     * ```
+     *
+     * Exposed as a reactive `boolean` (no `.value`). Reading it activates
+     * the factory under the lazy-by-default rule — observing readiness
+     * implies use.
+     */
+    readonly ready: boolean;
+    /**
+     * Re-fire the captured `defaultValues` factory and re-apply its
+     * payload over the current form values. Useful when the upstream
+     * source changes (the user picks a different draft, a background
+     * sync indicates fresh server data, etc.).
+     *
+     * Resolves after `hydrating` flips back to `false`. Throws
+     * synchronously when the form was constructed with a plain-value
+     * `defaultValues` (nothing to re-fire). Does NOT clear dirty /
+     * touched / submit state — chain `form.reset()` for that.
+     */
+    rehydrate(): Promise<void>;
+    /**
+     * Idempotent activation. Forms are lazy-by-default: a function-form
+     * `defaultValues` factory fires on the first reactive interaction
+     * (reading `form.values`, calling `form.setValue`, etc.). Call
+     * `form.activate()` to kick the factory explicitly — typically from
+     * `setup` so SSR's `onServerPrefetch` hook awaits the resolution
+     * before the page renders. Subsequent calls return the in-flight
+     * promise until the factory settles, after which they resolve
+     * immediately. Plain-value forms (no factory captured) always
+     * return a resolved promise.
+     */
+    activate(): Promise<void>;
     /**
      * Reactive map of field errors, keyed by dotted path. Populated
      * automatically by `handleSubmit` and per-field validation; cleared
@@ -3426,7 +4015,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     clearFormErrors: () => void;
     /**
      * Form-level reactive flags, counters, and aggregates (`dirty`,
-     * `valid`, `submitting`, `submitCount`, and the flat `errors`
+     * `valid`, `submitting`, `submissionAttempts`, and the flat `errors`
      * array). See `FormMeta` for the full shape. Read leaves directly
      * with no `.value`.
      *
@@ -3446,13 +4035,14 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      *   - the dirty baseline (so the next edit flips `dirty` correctly);
      *   - field errors;
      *   - touched / focused / blurred per-field flags;
-     *   - submission state (`submitting` / `submitCount` / `submitError`);
+     *   - submission state (`submitting` / `submissionAttempts` /
+     *     `submitted` / `submitError`);
      *   - the persisted draft, if persistence is configured.
      *
      * The next edit on a still-mounted opted-in input will start
      * persisting again automatically.
      */
-    reset: (nextDefaultValues?: DeepPartial<DefaultValuesShape<Form>>) => void;
+    reset: (nextDefaultValues?: DefaultValuesInput<Form>) => void;
     /**
      * Restore a single field (or a sub-tree like `'user'`) to its
      * initial value. Clears errors and touched flags for the field
@@ -3565,6 +4155,21 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * `options` is forwarded to `Element.scrollIntoView` unchanged.
      */
     scrollToFirstError: (options?: ScrollIntoViewOptions) => boolean;
+    /**
+     * Drive the form's `onInvalidSubmit` policy imperatively. The same
+     * focus/scroll behavior `handleSubmit` runs after a failed submit,
+     * but available standalone. Defaults to the policy configured via
+     * `useForm({ onInvalidSubmit })` (or `'focus-first-error'` when
+     * omitted). Pass an explicit policy to override for one call.
+     *
+     * Used by `useWizard` after navigating to the first failing form
+     * during `wizard.handleSubmit`, so the failing form's own configured
+     * policy fires once its DOM is in view.
+     *
+     * No-op when no errored field is currently registered or when the
+     * resolved policy is `'none'`.
+     */
+    applyInvalidSubmitPolicy: (policy?: OnInvalidSubmitPolicy) => void;
     /**
      * Programmatically mark fields as touched — the sticky flag the
      * standard "show errors after interaction" pattern reads. Closes
@@ -3613,28 +4218,31 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     /** Replace the element at `index` with `value`. No-op when out of range. */
     replace: <Path extends ArrayPath<Form>>(path: Path, index: number, value: ArrayItem<Form, Path>) => void;
     /**
-     * Read-only view of the form's blank path set. Each entry
-     * is a canonical `PathKey` (the `JSON.stringify(segments)` form
-     * `canonicalizePath` produces). The set is reactive — Vue 3.5
-     * tracks `.has()` / `for..of` / size accesses, so consumers can
-     * drive conditional UI off it directly:
+     * Read-only view of the form's blank path set. Reactive — Vue 3.5
+     * tracks `.has()` / `for..of` / size accesses, so consumers can drive
+     * conditional UI off it directly:
      *
      * ```ts
      * watchEffect(() => {
      *   if (form.blankPaths.value.size > 0) {
-     *     console.warn('unanswered fields:', [...form.blankPaths.value])
+     *     const paths = [...form.blankPaths.value]   // Path[][] — array of segments per entry
+     *     console.warn('unanswered fields:', paths.map((p) => p.join('.')))
      *   }
      * })
      * ```
      *
+     * `.has(input)` accepts the dotted-string form (`'user.email'`) or
+     * the array form (`['user', 'email']`). The array form disambiguates
+     * keys with literal dots (e.g. `['address.primary']`). See
+     * [[BlankPathsView]] for the full surface.
+     *
      * For per-path access, use `form.fields.<path>.blank`.
      * Writes happen through `setValue(path, unset)`,
      * `markBlank()` on a register binding, and the directive's
-     * input listener on numeric clear. Mutating the snapshot returned
-     * here does nothing — it's `Object.freeze`-d.
+     * input listener on numeric clear.
      */
-    blankPaths: ComputedRef<ReadonlySet<string>>;
+    blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH_KEY as $, ROOT_PATH as _, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
-export type { AttaformDefaults as A, NestedType as B, CoercionRegistry as C, DeepPartial as D, OnInvalidSubmitPolicy as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, OnSubmit as P, Path as Q, RegisterValue as R, SlimPrimitiveKind as S, PathKey as T, UseFormConfiguration as U, ValidationError as V, PendingValidationStatus as W, PersistConfig as X, PersistConfigOptions as Y, PersistIncludeMode as Z, CoercionEntry as a, ReactiveValidationStatus as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterOptions as a3, RegisterSelectModifier as a4, RegisterTextModifier as a5, RegisterTransform as a6, Segment as a7, SetValueCallback as a8, SetValuePayload as a9, SettledValidationStatus as aa, ShouldShowErrorsConfig as ab, SlimRuntimeOf as ac, SubmitHandler as ad, Unset as ae, ValidateOn as af, ValidateOnConfig as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, SchemaFactoryOptions as ar, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ShouldShowErrors as f, ApiErrorEnvelope as g, ApiErrorDetails as h, ApiErrorEntry as i, ArrayItem as j, ArrayPath as k, CoercionResult as l, CustomDirectiveRegisterAssignerFn as m, DefaultValuesResponse as n, FieldMetaPayload as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormMeta as v, FormStorage as w, FormStorageKind as x, HistoryConfig as y, IsUnion as z };
+export { ROOT_PATH as a2, ROOT_PATH_KEY as a3, canonicalizePath as aq, isPathPrefix as ar, isUnset as as, parseDottedPath as at, unset as au };
+export type { PersistConfigOptions as $, AttaformDefaults as A, IsUnion as B, CoercionEntry as C, DefaultValuesInput as D, ErrorsProxyShape as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, NestedType as O, OnError as P, OnInvalidSubmitPolicy as Q, RegisterValue as R, Segment as S, OnSubmit as T, UseFormConfiguration as U, ValidationError as V, PartialFlatPath as W, Path as X, PathKey as Y, PendingValidationStatus as Z, PersistConfig as _, AbstractSchema as a, PersistIncludeMode as a0, Primitive as a1, ReactiveValidationStatus as a4, RegisterDirective as a5, RegisterFlatPath as a6, RegisterOptions as a7, RegisterSelectModifier as a8, RegisterTextModifier as a9, RegisterTransform as aa, SetValueCallback as ab, SetValuePayload as ac, SettledValidationStatus as ad, ShouldShowErrorsConfig as ae, SlimPrimitiveKind as af, SlimRuntimeOf as ag, SubmitHandler as ah, Unset as ai, ValidateOn as aj, ValidateOnConfig as ak, ValidationResponse as al, ValidationResponseWithoutValue as am, ValueOfUnion as an, WriteMeta as ao, WriteShape as ap, SchemaFactoryOptions as av, PersistOptInRegistry as aw, UseFormReturnType as b, RegisterModelDynamicCustomDirective as c, ShouldShowErrors as d, ApiErrorEnvelope as e, ApiErrorDetails as f, ApiErrorEntry as g, ArrayItem as h, ArrayPath as i, CoercionRegistry as j, CoercionResult as k, CustomDirectiveRegisterAssignerFn as l, DeepPartial as m, DefaultValuesResponse as n, DefaultValuesShape as o, FieldMetaPayload as p, FieldState as q, FieldStateMap as r, FieldStateMapEntry as s, FlatPath as t, FormErrorRecord as u, FormErrorsSurface as v, FormMeta as w, FormStorage as x, FormStorageKind as y, HistoryConfig as z };