attaform 0.20.2 → 0.21.1

package/dist/shared/{attaform.99cfHcIt.d.cts → attaform.D0dWZsJt.d.cts}

@@ -230,6 +230,21 @@ type KeyofUnion<T> = T extends unknown ? keyof T : never;
  * variants and the runtime returns a stable stub there.
  */
 type ValueOfUnion<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? T[K] : undefined : never;
+/**
+ * Value at key `K` across union members of `T`, dropping members that
+ * LACK `K` entirely (they contribute `never`, not `undefined`). The
+ * counterpart to `ValueOfUnion`: where that injects a SYNTHETIC
+ * `undefined` for absent-variant keys (so chained reads stay safe),
+ * this yields only the PRESENT value type.
+ *
+ * `form.fields` uses it at discriminated-union keys so a variant-only
+ * field types as node-optional `FieldState<X> | undefined` (the node is
+ * absent when its variant isn't active) rather than value-optional
+ * `FieldState<X | undefined>` (which would falsely promise a readable
+ * node). A genuine `undefined` from an OPTIONAL declaration survives —
+ * only the synthetic absent-variant `undefined` is stripped.
+ */
+type PresentValueOfUnion<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? T[K] : never : never;
 /**
  * Apply the discriminated-union "lift" to a value shape (i.e., a
  * shape carrying actual values, not metadata leaves like
@@ -814,6 +829,12 @@ type AbstractSchema<Form, GetValueFormType> = {
      * Structural fingerprint of the schema. Same shape → same string;
      * different shape → (best-effort) different string.
      *
+     * Resolves a `Promise` so adapters can defer the structural walk (and
+     * its `canonicalStringify` helper) onto a dynamic import. The framework
+     * only ever needs the fingerprint on opt-in async paths (the multi-tab
+     * channel name, the persistence storage key) plus a dev-only mismatch
+     * warning, so none of those bytes belong on the eager `useForm` path.
+     *
      * The library uses this to detect schema mismatches at a shared
      * form key: two `useForm({ key: 'x', schema })` calls are allowed
      * to land on the same `FormStore` (the "shared store" semantic),
@@ -841,7 +862,7 @@ type AbstractSchema<Form, GetValueFormType> = {
      *   look identical. The warning is a footgun catcher, not a
      *   soundness guarantee.
      */
-    fingerprint(): string;
+    fingerprint(): Promise<string>;
     getDefaultValues(config: GetDefaultValuesConfig<Form>): DefaultValuesResponse<Form>;
     /**
      * Return the schema-prescribed default value at the given path. The
@@ -938,6 +959,29 @@ type AbstractSchema<Form, GetValueFormType> = {
      * `optional(z.tuple([...]))` reports its tuple length.
      */
     arrayShapeAtPath(path: Path): number | null | undefined;
+    /**
+     * Whether the schema at `path` is a FIXED object: a closed set of
+     * declared keys (`z.object`), as opposed to an open or union container
+     * (array / record / map / set / union / discriminated union) whose
+     * element schema matches any segment.
+     *
+     * The surface proxies (`form.fields` / `form.errors`) use this to
+     * resolve a collision: a fixed object's declared keys are known ahead
+     * of any data, so a key the schema owns descends to a real terminal
+     * even when the live value hasn't been populated yet (a declared-but-
+     * absent `optional` field stays registrable). An open container can't
+     * make that promise — its element schema accepts ANY segment, so the
+     * proxy must fall back to the keys the data currently holds and read
+     * a genuinely-absent key (out-of-bounds index, missing record key,
+     * inactive variant key) as `undefined` rather than a phantom node.
+     *
+     * The empty path (the root form) is always a fixed object. Wrappers
+     * (optional / nullable / default / readonly / catch / pipe / lazy)
+     * are peeled before the kind check, so `z.object({...}).optional()`
+     * still reports `true`. A path the schema doesn't declare reports
+     * `false`.
+     */
+    isFixedObjectAtPath(path: Path): boolean;
     /**
      * Return every sub-schema that could resolve at the given structured
      * path. Multiple results are only expected for discriminated / union
@@ -2047,29 +2091,31 @@ type AttaformDefaults = {
      *   useForm({ getDisplayState })  >  AttaformDefaults  >  library default
      *
      * The library default opens one timing gate, then resolves by
-     * precedence: gate closed → `'idle'`; a run in flight → `'pending'`;
-     * an own-path error → `'error'`; otherwise `valid` → `'success'`, else
-     * `'idle'`. The gate opens after the first submit attempt OR once the
-     * field is touched and not currently focused:
+     * precedence: gate closed → `'idle'`; a run in flight → a delayed
+     * `'pending'` (held briefly to smooth fast validations, then held a
+     * minimum so it never flashes); an own-path error → `'error'`;
+     * otherwise earned `valid` → `'success'`, else `'idle'`. The gate opens
+     * after the first submit attempt OR once the field is edited and left:
      *
      * ```ts
-     * (field, formMeta) => {
+     * (prev, ctx) => {
      *   const gateOpen =
-     *     formMeta.submissionAttempts > 0 ||
-     *     (field.touched === true && field.focused !== true)
-     *   if (!gateOpen) return 'idle'
-     *   if (field.validating === true) return 'pending'
-     *   // ...own-path error → 'error'; valid → 'success'; else 'idle'
+     *     ctx.formMeta.submissionAttempts > 0 ||
+     *     ctx.field.blurredAfterInteraction === true
+     *   if (!gateOpen) return { display: 'idle' }
+     *   // ...timed 'pending' while validating; own-path error → 'error';
+     *   //    earned valid → 'success'; else 'idle'
      * }
      * ```
      *
      * Compose with the library default via the public `defaultDisplayState`
-     * export. The predicate runs on every field-state read, so it owns the
+     * export, or retune its timing via `makeDefaultDisplayState`. The
+     * reducer runs on every field-state read, so it owns the
      * idle / pending / error / success decision outright.
      *
-     * The predicate's args are `Omit`'d of the derived `displayState` /
-     * `show*` / `firstError` keys (see `FieldStateDerivedKey`) to prevent
-     * a self-referential predicate.
+     * The reducer's `ctx.field` / `ctx.formMeta` are `Omit`'d of the
+     * derived `displayState` / `show*` / `firstError` keys (see
+     * `FieldStateDerivedKey`) to prevent a self-referential reducer.
      */
     getDisplayState?: GetDisplayState;
     /**
@@ -2230,16 +2276,64 @@ type DisplayState = 'idle' | 'pending' | 'error' | 'success';
  */
 type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
 /**
- * Predicate that resolves a path's `displayState`. Receives the field's
- * reactive state plus the form's reactive meta (both minus the derived
- * `displayState` / `show*` / `firstError` keys — see `FieldStateDerivedKey`)
- * and returns the single enum verdict; the `show*` booleans derive from
- * the result. Runs unconditionally on every field-state read, so the
- * idle / pending / error / success decision lives in exactly one place
- * and the whole app's validation-display behavior flows from it.
+ * One step of the display state machine: the verdict the field should
+ * render right now (`display`, projected to `displayState` and the
+ * `show*` booleans) plus two optional timing cells the engine reads.
+ *
+ * - `reviewAt` — an absolute `Date.now()` millisecond stamp telling the
+ *   engine "re-evaluate this field no later than here." The engine keeps
+ *   a single timer per form aimed at the nearest `reviewAt` across all
+ *   active fields; when it fires, the dependent field computeds re-run
+ *   and call the reducer again. A machine with no `reviewAt` and a
+ *   non-pending `display` is terminal — the engine evicts it.
+ * - `pendingShownAt` — the stamp at which `'pending'` was first shown,
+ *   the memory the min-visible hold needs so a spinner that just appeared
+ *   is not yanked away the instant validation resolves. Opaque to the
+ *   engine; a custom reducer may carry its own extra memory fields too.
+ */
+type DisplayMachine = {
+    readonly display: DisplayState;
+    readonly reviewAt?: number;
+    readonly pendingShownAt?: number;
+};
+/**
+ * Inputs to a `getDisplayState` reducer. `field` and `formMeta` are the
+ * same reactive snapshots a predicate has always received (still minus
+ * the derived `displayState` / `show*` / `firstError` keys — see
+ * `FieldStateDerivedKey` — so a reducer can never read its own output and
+ * form a cycle), now joined by:
+ *
+ * - `validatingSince` — `Date.now()` at which the field's current
+ *   validation streak opened, or `null` when nothing is in flight. This,
+ *   not `field.validating`, is the timing anchor: the elapsed wait is
+ *   `now - validatingSince`. Pinned to the start of the streak, so
+ *   overlapping sub-runs do not reset it.
+ * - `transformingSince` — the same anchor for an in-flight async
+ *   `register` transform, or `null` when none is running. Folds into the
+ *   one in-flight clock the reducer already runs for validation, so a
+ *   deferred transform rides the anti-flash spinner timing identically.
+ *   `null` for a sync-only chain, which never defers.
+ * - `now` — the engine's clock, injected so the reducer stays pure and
+ *   deterministic (and frozen to `0` under SSR, where there is no clock).
+ */
+type DisplayCtx = {
+    readonly field: Omit<FieldState, FieldStateDerivedKey>;
+    readonly formMeta: Omit<FormMeta, FieldStateDerivedKey>;
+    readonly validatingSince: number | null;
+    readonly transformingSince: number | null;
+    readonly now: number;
+};
+/**
+ * Pure transition reducer that resolves a path's `displayState`. Given
+ * the field's previous `DisplayMachine` and the current `DisplayCtx`, it
+ * returns the next machine; the engine owns the clock and the timers, the
+ * reducer owns the timing policy. Runs on every field-state read (and
+ * again whenever a `reviewAt` deadline fires), so the whole app's
+ * validation-display behavior flows from this one function.
  *
- * The library default — `defaultDisplayState` — is publicly exported so
- * a layered predicate can compose with it:
+ * The library default — `defaultDisplayState` — is publicly exported so a
+ * layered reducer can compose with it, and `makeDefaultDisplayState`
+ * builds a default with custom anti-flash timings:
  *
  * ```ts
  * import { defaultDisplayState } from 'attaform'
@@ -2247,14 +2341,16 @@ type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'sho
  * useForm({
  *   schema,
  *   // Defer to the default everywhere, but never show a success check on `username`.
- *   getDisplayState: (field, formMeta) => {
- *     const state = defaultDisplayState(field, formMeta)
- *     return field.path[0] === 'username' && state === 'success' ? 'idle' : state
+ *   getDisplayState: (prev, ctx) => {
+ *     const next = defaultDisplayState(prev, ctx)
+ *     return next.display === 'success' && ctx.field.path[0] === 'username'
+ *       ? { display: 'idle' }
+ *       : next
  *   },
  * })
  * ```
  */
-type GetDisplayState = (field: Omit<FieldState, FieldStateDerivedKey>, formMeta: Omit<FormMeta, FieldStateDerivedKey>) => DisplayState;
+type GetDisplayState = (prev: DisplayMachine, ctx: DisplayCtx) => DisplayMachine;
 /**
  * Submit handler returned by `handleSubmit(onSubmit, onError)`. Bind
  * it to a `<form>`:
@@ -2340,7 +2436,7 @@ type MetaTrackerValue = {
 };
 type RegisterFlatPath<Form, Key extends keyof Form = keyof Form> = FlatPathBuilder<Form, 'register', Key>;
 /**
- * Sync transformation applied to a field's value as user input flows
+ * A transformation applied to a field's value as user input flows
  * from DOM through the directive's assigner. Composes left-to-right
  * via the `transforms: [...]` array on `register()`.
  *
@@ -2360,19 +2456,33 @@ type RegisterFlatPath<Form, Key extends keyof Form = keyof Form> = FlatPathBuild
  * doesn't accept gets rejected at write time with a standard
  * diagnostic.
  *
- * Transforms must be sync. A `Promise` return is treated as a
- * pipeline failure: the write is aborted and a console.error is
- * logged. Use async field validation for canonicalize-before-write
- * patterns; use sync transforms for fire-and-forget side effects
- * (`void doIt(value); return value`).
- *
- * Throws are caught and aborted: attaform wraps each transform call in
- * try/catch so a buggy or defensive-throw transform doesn't crash
- * the host app. On throw the pipeline aborts (subsequent transforms
- * don't run), nothing is written to form state, and the assigner
- * returns `false`.
+ * Transforms may be sync or async. The chain stays fully synchronous —
+ * the value reaches form state in the same tick — until a transform
+ * returns a thenable; from there the write defers, the field reads
+ * `busy` / `transforming` while the chain settles, and the resolved
+ * value commits to canonical state once it lands. Rapid edits discard
+ * all but the latest (latest-request-wins), and a rejection surfaces on
+ * `field.transformError` rather than throwing or logging:
+ *
+ * ```ts
+ * export const normalize: RegisterTransform = async (v, ctx) => {
+ *   const res = await fetch(`/normalize?q=${v}`, { signal: ctx?.signal })
+ *   return res.text()
+ * }
+ * ```
+ *
+ * `ctx.signal` is an `AbortSignal` aborted when the run is superseded by
+ * a newer edit, or torn down by `reset()` / unmount — thread it into
+ * cancellable I/O so a stale request is dropped. A sync chain never
+ * touches it and allocates no controller.
+ *
+ * A synchronous throw is caught and aborts the pipeline: subsequent
+ * transforms don't run, nothing is written to form state, and the
+ * assigner returns `false` — so a buggy or defensive-throw transform
+ * never crashes the host app. (An async rejection is the
+ * `transformError` channel above, not a throw into the host app.)
  */
-type RegisterTransform = (value: unknown) => unknown;
+type RegisterTransform = (value: unknown, ctx?: TransformContext) => unknown;
 /**
  * Runtime type for a slim primitive kind. Used to narrow the
  * `transform` parameter and return value on a `CoercionEntry` so
@@ -2497,9 +2607,11 @@ type RegisterOptions = {
      * form.setValue('email', slugify(lowercase(rawValue)))
      * ```
      *
-     * Transforms must be sync. Throws and Promise returns abort the
-     * write and log to `console.error` (see `RegisterTransform` for
-     * the failure-mode contract).
+     * Transforms may be sync or async: the chain stays synchronous until
+     * one returns a thenable, then the write defers and commits the
+     * resolved value (the field reads `busy` meanwhile). A sync throw
+     * aborts the write; an async rejection lands on `field.transformError`
+     * (see `RegisterTransform` for the full contract).
      *
      * For patterns that need to inspect the `RegisterValue` itself
      * (rejection-with-side-effect, redirection to other fields, custom
@@ -2817,6 +2929,64 @@ type RegisterValue<Value = unknown> = Readonly<{
      */
     ariaDisplayState?: Readonly<Ref<DisplayState>>;
 }>;
+/**
+ * Internal extension of `RegisterValue` that includes directive-private
+ * coordination state. Imported by the directive runtime; not part of
+ * the public surface.
+ *
+ * `lastTypedForm` is the user's most recently typed string form for a
+ * numeric field while mid-typing, or `null` once the field has been
+ * blurred / cleared. The directive populates it on every committable
+ * input event and clears it on the change (blur) event so:
+ *
+ *   - Mid-typing: `displayValue` returns the typed form (e.g.
+ *     `'1e2'`) when it parses back to current storage. Vue's
+ *     `:value` patch then targets the typed form, which already
+ *     equals the DOM — idempotent, no cursor reset.
+ *   - On blur: `displayValue` falls back to `String(storage)`
+ *     (`'100'`), Vue patches the DOM to match. The user sees
+ *     exactly what's stored.
+ *
+ * Why a separate field: JavaScript's Number carries no representation
+ * info — `1e2 === 100`, so `String(parseFloat('1e2'))` yields `'100'`.
+ * Tracking the typed form lets us avoid Vue's mid-typing DOM yank
+ * without lying about storage. Only meaningful for `.number` text
+ * inputs and `<input type="number">`; other bindings ignore it.
+ *
+ * @internal
+ */
+/**
+ * Mutable holder for an async-transform run's `AbortController`, shared
+ * between the directive — which lazily creates the controller the first
+ * time a transform reaches for `ctx.signal` — and the store, which
+ * aborts it when the run is superseded, cancelled, or reset.
+ * `controller` stays `null` until `ctx.signal` is actually touched, so a
+ * purely-sync chain never allocates one. `aborted` latches `true` the
+ * moment the store tears the run down, so a signal accessed AFTER
+ * teardown still resolves to an already-aborted signal rather than a
+ * live one.
+ */
+type TransformAbortHolder = {
+    controller: AbortController | null;
+    aborted: boolean;
+};
+/**
+ * The second argument handed to every transform in a `transforms: [...]`
+ * chain. `signal` is an `AbortSignal` that aborts when the run is
+ * superseded by a newer input, or torn down by a reset / cancel — so a
+ * transform doing cancellable I/O (a `fetch`, a worker round-trip) can
+ * pass `ctx.signal` through and bail the moment its result is no longer
+ * wanted.
+ *
+ * The signal is lazy: the backing `AbortController` is allocated only on
+ * first access, so a purely-synchronous chain that never reaches for
+ * `ctx.signal` allocates nothing. It is meaningful for async transforms;
+ * a sync chain has no in-flight I/O to cancel, so its `signal` simply
+ * never aborts.
+ */
+type TransformContext = {
+    readonly signal: AbortSignal;
+};
 /**
  * Custom assigner installed on an element via the directive's
  * `[assignKey]` slot OR an `@update:registerValue` listener. Called
@@ -2876,6 +3046,15 @@ type CustomRegisterDirective<T, Modifiers extends string = string> = ObjectDirec
      * from the user's input.
      */
     _lastAppliedModel?: unknown;
+    /**
+     * Variant-specific "repaint the DOM from current storage" closure,
+     * stashed by each input directive's `created` hook (it mirrors that
+     * variant's post-write force-sync block). The deferred async-transform
+     * orchestrator calls it once the resolved value has committed, so a
+     * bare `<input v-register>` with no other reactive reader still paints
+     * the normalized result without depending on a parent re-render.
+     */
+    _syncFromStorage?: () => void;
     [S: symbol]: CustomDirectiveRegisterAssignerFn;
 }, RegisterValue | undefined, Modifiers, string>;
 /**
@@ -3211,8 +3390,38 @@ type FieldState<Value = unknown> = {
      * is in flight (`errors.length === 0 && !validating`). Confidence
      * that "we've checked, and we have no problems right now." Use for
      * green-checkmark / `aria-invalid` UX.
+     *
+     * Validation-only: an in-flight async transform does NOT clamp
+     * `valid` to `false`. `valid` is the verdict on the last committed
+     * value; `busy` is the union "work in flight" signal.
      */
     readonly valid: boolean;
+    /**
+     * `true` while an async `register` transform is in flight at this
+     * path: a transform returned a thenable and the resolved value has
+     * not yet committed to form state. Always `false` for a sync-only
+     * chain, which reaches form state in the same tick with no deferral.
+     * Containers roll it up as a disjunction (any descendant transforming).
+     */
+    readonly transforming: boolean;
+    /**
+     * `transforming || validating` — the union "work is in flight at this
+     * path" signal. Drives `aria-busy` through `displayState` on a
+     * revealed field, and is the surface to bind for a busy indicator on a
+     * field not yet revealed (where `displayState` stays idle by the
+     * reveal gate). Containers roll it up as a disjunction.
+     */
+    readonly busy: boolean;
+    /**
+     * The `Error` from the most recent async transform that rejected at
+     * this path, else `null`. A per-field normalization-failure channel
+     * separate from validation `errors`: a transform that rejects (a
+     * failed fetch, a parse error) surfaces here instead of crashing the
+     * host app or logging. Cleared when a fresh transform starts or a
+     * write supersedes it. Leaf-only — containers do not roll it up (it is
+     * always `null` at a container path).
+     */
+    readonly transformError: Error | null;
     /**
      * The single display-state verdict at this path: `'idle'`,
      * `'pending'`, `'error'`, or `'success'`. The source of truth the
@@ -3481,15 +3690,33 @@ interface LeafSchemeFor<T> {
  */
 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> : [T] extends [object] ? string extends keyof T ? {
+    readonly [K in keyof T]: LeafWalker<T[K], Kind, StripOptional>;
+} & ContainerSelfErrorsSlot<T, Kind> : [IsUnion<T>] extends [true] ? StripOptional extends true ? {
+    readonly [K in KeyofUnion<T>]-?: DiscriminatedLeaf<T, K, Kind, StripOptional>;
 } & ContainerSelfErrorsSlot<T, Kind> : {
-    readonly [K in KeyofUnion<T>]: LeafWalker<ValueOfUnion<T, K>, Kind, StripOptional>;
+    readonly [K in KeyofUnion<T>]: DiscriminatedLeaf<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];
+/**
+ * One key of a discriminated-union container in `LeafWalker`. A key
+ * present (and required) in EVERY variant is universal — its node is
+ * always reachable. A variant-only or optional-in-some key is a dynamic
+ * hop: its node is `undefined` when its variant isn't active, so it
+ * carries node-optionality (`LeafWalker<…> | undefined`), NOT value-
+ * optionality (`LeafWalker<… | undefined>`). `PresentValueOfUnion`
+ * strips the synthetic absent-variant `undefined` so the present node
+ * resolves to the precise value type; a genuine `undefined` from an
+ * `optional` declaration survives.
+ *
+ * Universality is `[T] extends [Record<K, unknown>]` — true iff `T`
+ * (the whole union) satisfies "has K, required", which holds only when
+ * every variant declares K as a required property.
+ */
+type DiscriminatedLeaf<T, K extends PropertyKey, Kind extends keyof LeafSchemeFor<unknown>, StripOptional extends boolean> = [T] extends [Record<K, unknown>] ? LeafWalker<PresentValueOfUnion<T, K>, Kind, StripOptional> : LeafWalker<PresentValueOfUnion<T, K>, Kind, StripOptional> | undefined;
 /**
  * Intersection augmenting every container in the `form.errors` walker
  * with a `''` sentinel slot — the per-container home for cross-field
@@ -3504,6 +3731,22 @@ type ContainerSelfErrorsSlot<T, Kind> = Kind extends 'errors' ? '' extends keyof
     readonly ['']: readonly ValidationError[];
 } : unknown;
 type FieldStateMapEntry<T> = LeafWalker<T, 'field'>;
+/**
+ * Result of the `form.fields(path)` string call-form. A path the schema
+ * declares resolves to its `FieldState` — a leaf's value type, or a
+ * container's rolled-up aggregate (every FieldState property exists
+ * regardless of the value type). A path the schema lacks resolves to
+ * `undefined`, because a typo is not a field and the runtime hands back
+ * `undefined` rather than a phantom stub. A non-literal `string` could
+ * be either, so it widens to `FieldState<unknown> | undefined`.
+ *
+ * Named (rather than inlined into the `FieldStateMap` call signature) so
+ * the conditional is one cached type — keeps two structurally-identical
+ * `FieldStateMap` instantiations (e.g. the unified `attaform/zod` return
+ * and `UseFormReturnV4`) relatable instead of collapsing to a nominal
+ * "two different types with this name" mismatch.
+ */
+type FieldCallResult<Form, P extends string> = [P] extends [FlatPath<Form>] ? FieldState<NestedType<Form, P>> : string extends P ? FieldState<unknown> | undefined : undefined;
 /**
  * Type of `form.fields` — leaf-aware drillable callable Proxy. At
  * a leaf path the proxy resolves to a `FieldState<Value>`; at
@@ -3524,18 +3767,14 @@ type FieldStateMapEntry<T> = LeafWalker<T, 'field'>;
  * string as a single key. Use chained dot/bracket or the callable
  * form.
  */
-type FieldStateMap<Form extends GenericForm> = ([IsUnion<Form>] extends [true] ? {
-    readonly [K in KeyofUnion<Form>]-?: FieldStateMapEntry<ValueOfUnion<Form, K>>;
-} : {
-    readonly [K in keyof Form]-?: FieldStateMapEntry<Form[K]>;
-}) & {
+type FieldStateMap<Form extends GenericForm> = LeafWalker<Form, 'field'> & {
     /**
-     * Dotted-string fallback for dynamic paths. Returns
-     * `FieldState<unknown>` — the runtime always lands on a FieldState
-     * terminal at any depth (leaf or container). Cast to
-     * `FieldState<TypedValue>` when the caller knows the leaf type.
+     * String-path form (dynamic / programmatic). See {@link FieldCallResult}:
+     * a path the schema declares resolves to its precise `FieldState`, a
+     * path it lacks to `undefined`, and a non-literal `string` to
+     * `FieldState<unknown> | undefined`.
      */
-    (path: string): FieldState<unknown>;
+    <P extends string>(path: P): FieldCallResult<Form, P>;
     /**
      * Tuple-segment form. Returns the typed `FieldStateMapEntry` for
      * the resolved path when the tuple resolves to a known path.
@@ -3546,10 +3785,10 @@ type FieldStateMap<Form extends GenericForm> = ([IsUnion<Form>] extends [true] ?
     /**
      * Dynamic-array fallback for callers passing `Path`-typed (runtime)
      * segment arrays — e.g. forwarding `RegisterValue.segments` to
-     * resolve a field view. Returns `FieldState<unknown>`; cast when
-     * the value type is known.
+     * resolve a field view. The path may not resolve, so the result
+     * widens with `| undefined`; cast when the value type is known.
      */
-    (segments: ReadonlyArray<string | number>): FieldState<unknown>;
+    (segments: ReadonlyArray<string | number>): FieldState<unknown> | undefined;
     /**
      * No-arg call returns the root FieldState — same as
      * `form.fields([])`. Aggregates over the whole form (one
@@ -3796,15 +4035,23 @@ type FormMeta<F = unknown> = FieldState<F> & {
      */
     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
-     * each new submission attempt; stays `null` on success.
+     * The error thrown or rejected by the most recent submit callback (or
+     * its `onError` handler), coerced to a real `Error` (a non-`Error`
+     * throw keeps its origin on `.cause`). Cleared to `null` at the start
+     * of each new submission attempt; stays `null` on success.
      *
-     * The submit handler still throws normally — this is the reactive
-     * mirror for templates. Imperative callers can use
-     * `try { await onSubmit() }` instead.
+     * The submit handler does NOT re-throw — its returned promise always
+     * resolves, so binding it to `@submit.prevent` never manufactures a
+     * `window` unhandledrejection. This is the single channel for "the
+     * submit failed", read the same way in templates and after an
+     * imperative `await submit()`. Like `hydrateError`, it stays distinct
+     * from the curated user-error store: render it where you choose:
+     *
+     * ```vue
+     * <p v-if="form.meta.submitError">{{ form.meta.submitError.message }}</p>
+     * ```
      */
-    readonly submitError: unknown;
+    readonly submitError: Error | null;
     /**
      * Scalar mirror of `meta.errors.length`. Read it from templates and
      * `watch()` without indexing the underlying array.
@@ -3874,7 +4121,7 @@ type FormMeta<F = unknown> = FieldState<F> & {
  *
  * - `GetValueFormType` — the **output / parsed shape**
  *   (`z.output<Schema>`). Used by `handleSubmit`'s `onSubmit`
- *   callback and by `form.process()`'s success payload. This is the
+ *   callback and by `form.parse()`'s success payload. This is the
  *   shape after refinements have fired and transforms have run.
  *
  * - `ReadForm` — the **read / storage shape**. Used by `values`,
@@ -3971,7 +4218,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * `z.input<Schema>` shape — `.transform()`s have NOT run, so for
      * a schema like `z.string().transform(v => v.length > 10)` the
      * value reads as `string`, not `boolean`. Use `handleSubmit` or
-     * `form.process()` when you need the post-transform output shape.
+     * `form.parse()` when you need the post-transform output shape.
      */
     values: ValuesSurface<WriteShape<ReadForm>>;
     /**
@@ -4098,6 +4345,26 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * `true` while the promise is in flight.
      */
     validateAsync: (path?: FlatPath<Form>) => Promise<ValidationResponseWithoutValue<Form>>;
+    /**
+     * Resolve once every in-flight async `register({ transforms })` run
+     * has settled — globally, or (with `path`) only at-or-under that path.
+     * Resolve-never-reject: a transform that throws still settles the
+     * field (its failure lands on `field.transformError`), so the returned
+     * promise always resolves.
+     *
+     * `handleSubmit` awaits this internally before parsing, so a submit
+     * fired the instant after an async transform still validates the
+     * resolved value. Reach for it directly when you need the same
+     * guarantee outside submit — e.g. before reading `form.values` in an
+     * imperative flow or a test:
+     *
+     * ```ts
+     * input.value = '  a@b.com '
+     * await form.settleTransforms('email')
+     * // form.values.email is now the normalized value
+     * ```
+     */
+    settleTransforms: (path?: FlatPath<Form>) => Promise<void>;
     /**
      * Imperative one-shot parse. Same pipeline as `validateAsync` —
      * runs refinements, applies `.transform()`s, composes blank-required
@@ -4107,11 +4374,11 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * preprocess normalization applied but `.transform()` deferred. For
      * schemas where the input type differs from the output type (e.g.,
      * `z.string().transform(v => v.length > 10)`), `form.values.X` is
-     * the input shape and `(await form.process()).data?.X` is the
+     * the input shape and `(await form.parse()).data?.X` is the
      * output shape.
      *
      * ```ts
-     * const result = await form.process()
+     * const result = await form.parse()
      * if (result.success) {
      *   // result.data matches z.output<typeof schema>
      * } else {
@@ -4119,11 +4386,16 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * }
      * ```
      *
-     * Pass a path to parse a subtree only. Async because refinements may
-     * be async. `meta.validating` flips `true` while the promise is in
-     * flight (shared with validateAsync).
+     * Always async, and there is no synchronous variant by design: a
+     * schema can carry async refinements or transforms, so a sync parse
+     * would silently miss them the moment one is added. One always-
+     * awaited `parse` closes that category of bug entirely. The returned
+     * promise never rejects (a thrown adapter lands as a `success: false`
+     * response). Pass a path to parse a subtree only. `meta.validating`
+     * flips `true` while the promise is in flight (shared with
+     * validateAsync).
      */
-    process: (path?: FlatPath<Form>) => Promise<ValidationResponse<GetValueFormType>>;
+    parse: (path?: FlatPath<Form>) => Promise<ValidationResponse<GetValueFormType>>;
     /**
      * Bind a path to a native input via `v-register`. Returns a
      * `RegisterValue` carrying the live ref and event handlers the
@@ -4644,5 +4916,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH_KEY as $, ROOT_PATH as _, canonicalizePath as as, isPathPrefix as at, isUnset as au, parseDottedPath as av, unset as aw };
-export type { AbstractSchema as A, NestedType as B, CoercionEntry as C, DeepPartial as D, ErrorsProxyShape as E, FieldMetaPayload 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, OnInvalidSubmitPolicy as P, OnSubmit as Q, PartialFlatPath as R, Path as S, PathKey as T, PendingValidationStatus as U, PersistConfig as V, PersistConfigOptions as W, PersistIncludeMode as X, PersistOptInRegistry as Y, Primitive as Z, ApiErrorDetails as a, ReactiveValidationStatus as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterModelDynamicCustomDirective as a3, RegisterOptions as a4, RegisterSelectModifier as a5, RegisterTextModifier as a6, RegisterTransform as a7, RegisterValue as a8, SchemaFactoryOptions as a9, Segment as aa, SetValueCallback as ab, SetValuePayload as ac, SettledValidationStatus as ad, SlimPrimitiveKind as ae, SlimRuntimeOf as af, SubmitHandler as ag, Unset as ah, UseFormConfiguration as ai, UseFormReturnType as aj, ValidateOn as ak, ValidateOnConfig as al, ValidationError as am, ValidationResponse as an, ValidationResponseWithoutValue as ao, ValueOfUnion as ap, WriteMeta as aq, WriteShape as ar, ApiErrorEntry as b, ApiErrorEnvelope as c, ArrayItem as d, ArrayPath as e, AttaformDefaults as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DefaultValuesInput as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayState as m, FieldState as n, FieldStateMap as o, FieldStateMapEntry as p, FlatPath as q, FormErrorRecord as r, FormErrorsSurface as s, FormKey as t, FormMeta as u, FormStorage as v, FormStorageKind as w, GetDisplayState as x, HistoryConfig as y, IsUnion as z };
+export { ROOT_PATH as a0, ROOT_PATH_KEY as a1, canonicalizePath as av, isPathPrefix as aw, isUnset as ax, parseDottedPath as ay, unset as az };
+export type { Primitive as $, AbstractSchema as A, HistoryConfig as B, CoercionEntry as C, DeepPartial as D, ErrorsProxyShape as E, FieldMetaPayload as F, GenericForm as G, HandleSubmit as H, IsTuple as I, IsUnion as J, JoinSegments as K, KeyofUnion as L, LiftedValueShape as M, MetaTrackerValue as N, NestedReadType as O, NestedType as P, OnError as Q, OnInvalidSubmitPolicy as R, OnSubmit as S, PartialFlatPath as T, Path as U, PathKey as V, PendingValidationStatus as W, PersistConfig as X, PersistConfigOptions as Y, PersistIncludeMode as Z, PersistOptInRegistry as _, ApiErrorDetails as a, ReactiveValidationStatus as a2, RegisterDirective as a3, RegisterFlatPath as a4, RegisterModelDynamicCustomDirective as a5, RegisterOptions as a6, RegisterSelectModifier as a7, RegisterTextModifier as a8, RegisterTransform as a9, RegisterValue as aa, SchemaFactoryOptions as ab, Segment as ac, SetValueCallback as ad, SetValuePayload as ae, SettledValidationStatus as af, SlimPrimitiveKind as ag, SlimRuntimeOf as ah, SubmitHandler as ai, TransformAbortHolder as aj, Unset as ak, UseFormConfiguration as al, UseFormReturnType as am, ValidateOn as an, ValidateOnConfig as ao, ValidationError as ap, ValidationResponse as aq, ValidationResponseWithoutValue as ar, ValueOfUnion as as, WriteMeta as at, WriteShape as au, ApiErrorEntry as b, ApiErrorEnvelope as c, ArrayItem as d, ArrayPath as e, AttaformDefaults as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DefaultValuesInput as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayCtx as m, DisplayMachine as n, DisplayState as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormKey as v, FormMeta as w, FormStorage as x, FormStorageKind as y, GetDisplayState as z };