attaform 0.21.0 → 0.21.2

package/dist/shared/{attaform.B1nyO4ec.d.ts → attaform.ory-3WhV.d.ts}

@@ -73,6 +73,123 @@ type ResolvedFieldMeta = {
     readonly meta: Readonly<FieldMetaPayload>;
 };
 
+/**
+ * Path primitives for advanced integrations. The form library accepts
+ * paths in dotted-string form (`'user.email'`) at every public API.
+ * These primitives are exposed for adapter authors who need to
+ * canonicalise user-provided paths.
+ */
+declare const pathKeyBrand: unique symbol;
+/**
+ * Branded string identifier for a canonicalised path. Useful as a
+ * `Map` key — two paths that resolve to the same canonical form
+ * produce the same `PathKey`. Treat as opaque; don't try to parse.
+ */
+type PathKey = string & {
+    readonly [pathKeyBrand]: 'PathKey';
+};
+/** A single path segment — a property name or array index. */
+type Segment = string | number;
+/** A structured path as a read-only sequence of segments. */
+type Path = readonly Segment[];
+/**
+ * Parse a dotted-string path into structured segments.
+ *
+ * ```ts
+ * parseDottedPath('user.address.line1')   // ['user', 'address', 'line1']
+ * parseDottedPath('items.0.name')         // ['items', 0, 'name']
+ * parseDottedPath('')                     // ['']  (the empty-string key)
+ * ```
+ *
+ * The empty-string input `''` is the **literal empty-key path**, not
+ * the root. Use the array form `[]` for root. Form-level errors
+ * (root `.refine()`) live at the empty-string path bucket so
+ * `errors('')` returns them without sweeping every field error too.
+ *
+ * Throws `InvalidPathError` for paths with empty INTERNAL segments
+ * (`'a..b'`, leading or trailing dots). For keys containing literal
+ * dots, pass an array form (`['user.name']`) instead.
+ */
+declare function parseDottedPath(path: string): Segment[];
+/**
+ * Canonicalise a path into structured segments plus a stable string
+ * key. Accepts either dotted-string or array form; integer-looking
+ * segments normalise to numbers.
+ *
+ * ```ts
+ * canonicalizePath('items.0.name')
+ * // { segments: ['items', 0, 'name'], key: '["items",0,"name"]' as PathKey }
+ *
+ * canonicalizePath(['items', 0, 'name'])
+ * // → same result
+ * ```
+ *
+ * The returned `key` is suitable as a `Map`/`Set` key — equal paths
+ * produce equal keys regardless of input form.
+ */
+declare function canonicalizePath(input: string | Path): {
+    segments: readonly Segment[];
+    key: PathKey;
+};
+/**
+ * The root path — an empty segment tuple. Pass to APIs that accept
+ * a `Path` to address the form value as a whole.
+ */
+declare const ROOT_PATH: Path;
+/** Stable string key for the root path. */
+declare const ROOT_PATH_KEY: PathKey;
+/**
+ * `true` when `path` starts with every segment of `prefix` (in order).
+ * The empty `prefix` matches every path — ROOT prefix is universal.
+ *
+ * Walks segments rather than `PathKey` strings because the data this
+ * helper operates on (e.g. `meta.errors[].path`) carries segment
+ * arrays directly.
+ *
+ * ```ts
+ * isPathPrefix(['cargo'], ['cargo', 'items', 0, 'sku'])  // true
+ * isPathPrefix(['cargo', 'items'], ['cargo'])             // false (path shorter)
+ * isPathPrefix([], ['anything'])                          // true (root prefix)
+ * ```
+ */
+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;
+};
+
 /** Internal brand for the `Unset` type. Never exposed at runtime. */
 declare const _unsetBrand: unique symbol;
 /**
@@ -230,6 +347,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
@@ -530,6 +662,15 @@ type DefaultValuesInput<T> = T extends string ? string | Unset : T extends numbe
     [K in keyof T]?: DefaultValuesInput<T[K]>;
 } | Unset : T;
 
+/**
+ * Identifier for a form. A `FormKey` is the string passed via
+ * `useForm({ key })`, used to look up a form by name from a distant
+ * component, namespace persisted drafts, and label errors and
+ * DevTools entries. Anonymous `useForm` calls allocate one
+ * automatically; you only need to pick one when the form needs
+ * stable identity.
+ */
+type FormKey = string;
 /**
  * Per-form options threaded from `useForm` into the adapter factory.
  * Today carries the resolved `maxRecursionDepth` so adapter walks can
@@ -540,133 +681,6 @@ interface SchemaFactoryOptions {
     /** Resolved recursion ceiling (per-form > app-default > library default). */
     maxRecursionDepth: number;
 }
-
-/**
- * Path primitives for advanced integrations. The form library accepts
- * paths in dotted-string form (`'user.email'`) at every public API.
- * These primitives are exposed for adapter authors who need to
- * canonicalise user-provided paths.
- */
-declare const pathKeyBrand: unique symbol;
-/**
- * Branded string identifier for a canonicalised path. Useful as a
- * `Map` key — two paths that resolve to the same canonical form
- * produce the same `PathKey`. Treat as opaque; don't try to parse.
- */
-type PathKey = string & {
-    readonly [pathKeyBrand]: 'PathKey';
-};
-/** A single path segment — a property name or array index. */
-type Segment = string | number;
-/** A structured path as a read-only sequence of segments. */
-type Path = readonly Segment[];
-/**
- * Parse a dotted-string path into structured segments.
- *
- * ```ts
- * parseDottedPath('user.address.line1')   // ['user', 'address', 'line1']
- * parseDottedPath('items.0.name')         // ['items', 0, 'name']
- * parseDottedPath('')                     // ['']  (the empty-string key)
- * ```
- *
- * The empty-string input `''` is the **literal empty-key path**, not
- * the root. Use the array form `[]` for root. Form-level errors
- * (root `.refine()`) live at the empty-string path bucket so
- * `errors('')` returns them without sweeping every field error too.
- *
- * Throws `InvalidPathError` for paths with empty INTERNAL segments
- * (`'a..b'`, leading or trailing dots). For keys containing literal
- * dots, pass an array form (`['user.name']`) instead.
- */
-declare function parseDottedPath(path: string): Segment[];
-/**
- * Canonicalise a path into structured segments plus a stable string
- * key. Accepts either dotted-string or array form; integer-looking
- * segments normalise to numbers.
- *
- * ```ts
- * canonicalizePath('items.0.name')
- * // { segments: ['items', 0, 'name'], key: '["items",0,"name"]' as PathKey }
- *
- * canonicalizePath(['items', 0, 'name'])
- * // → same result
- * ```
- *
- * The returned `key` is suitable as a `Map`/`Set` key — equal paths
- * produce equal keys regardless of input form.
- */
-declare function canonicalizePath(input: string | Path): {
-    segments: readonly Segment[];
-    key: PathKey;
-};
-/**
- * The root path — an empty segment tuple. Pass to APIs that accept
- * a `Path` to address the form value as a whole.
- */
-declare const ROOT_PATH: Path;
-/** Stable string key for the root path. */
-declare const ROOT_PATH_KEY: PathKey;
-/**
- * `true` when `path` starts with every segment of `prefix` (in order).
- * The empty `prefix` matches every path — ROOT prefix is universal.
- *
- * Walks segments rather than `PathKey` strings because the data this
- * helper operates on (e.g. `meta.errors[].path`) carries segment
- * arrays directly.
- *
- * ```ts
- * isPathPrefix(['cargo'], ['cargo', 'items', 0, 'sku'])  // true
- * isPathPrefix(['cargo', 'items'], ['cargo'])             // false (path shorter)
- * isPathPrefix([], ['anything'])                          // true (root prefix)
- * ```
- */
-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
- * component, namespace persisted drafts, and label errors and
- * DevTools entries. Anonymous `useForm` calls allocate one
- * automatically; you only need to pick one when the form needs
- * stable identity.
- */
-type FormKey = string;
 /**
  * One validation failure. `path` points at the offending field as a
  * structured array — `['user', 'address', 0, 'line1']` for a nested
@@ -944,6 +958,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
@@ -2270,6 +2307,11 @@ type DisplayMachine = {
  *   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).
  */
@@ -2277,6 +2319,7 @@ type DisplayCtx = {
     readonly field: Omit<FieldState, FieldStateDerivedKey>;
     readonly formMeta: Omit<FormMeta, FieldStateDerivedKey>;
     readonly validatingSince: number | null;
+    readonly transformingSince: number | null;
     readonly now: number;
 };
 /**
@@ -2392,7 +2435,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()`.
  *
@@ -2412,19 +2455,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
@@ -2549,9 +2606,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
@@ -2869,6 +2928,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
@@ -2928,6 +3045,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>;
 /**
@@ -3263,8 +3389,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
@@ -3533,15 +3689,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
@@ -3556,6 +3730,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
@@ -3576,18 +3766,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.
@@ -3598,10 +3784,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
@@ -3848,15 +4034,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.
@@ -3926,7 +4120,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`,
@@ -4023,7 +4217,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>>;
     /**
@@ -4150,6 +4344,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
@@ -4159,11 +4373,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 {
@@ -4171,11 +4385,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
@@ -4696,5 +4915,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as a0, ROOT_PATH_KEY as a1, canonicalizePath as au, isPathPrefix as av, isUnset as aw, parseDottedPath as ax, unset as ay };
-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, Unset as aj, UseFormConfiguration as ak, UseFormReturnType as al, ValidateOn as am, ValidateOnConfig as an, ValidationError as ao, ValidationResponse as ap, ValidationResponseWithoutValue as aq, ValueOfUnion as ar, WriteMeta as as, WriteShape as at, 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 };
+export { ROOT_PATH as a4, ROOT_PATH_KEY as a5, canonicalizePath as as, isPathPrefix as at, isUnset as au, parseDottedPath as av, unset as aw };
+export type { PendingValidationStatus as $, AttaformDefaults as A, FormStorage as B, CoercionEntry as C, DefaultValuesInput as D, ErrorsProxyShape as E, FormKey as F, GenericForm as G, FormStorageKind as H, HandleSubmit as I, HistoryConfig as J, IsTuple as K, IsUnion as L, JoinSegments as M, KeyofUnion as N, LiftedValueShape as O, MetaTrackerValue as P, NestedReadType as Q, RegisterModelDynamicCustomDirective as R, NestedType as S, OnError as T, UseFormConfiguration as U, ValidationError as V, OnInvalidSubmitPolicy as W, OnSubmit as X, PartialFlatPath as Y, Path as Z, PathKey as _, AbstractSchema as a, PersistConfig as a0, PersistConfigOptions as a1, PersistIncludeMode as a2, Primitive as a3, ReactiveValidationStatus as a6, RegisterDirective as a7, RegisterFlatPath as a8, RegisterOptions as a9, RegisterSelectModifier as aa, RegisterTextModifier as ab, RegisterTransform as ac, Segment as ad, SetValueCallback as ae, SetValuePayload as af, SettledValidationStatus as ag, SlimPrimitiveKind as ah, SlimRuntimeOf as ai, SubmitHandler as aj, Unset as ak, ValidateOn as al, ValidateOnConfig as am, ValidationResponse as an, ValidationResponseWithoutValue as ao, ValueOfUnion as ap, WriteMeta as aq, WriteShape as ar, SchemaFactoryOptions as ax, TransformAbortHolder as ay, PersistOptInRegistry as az, UseFormReturnType as b, RegisterValue as c, GetDisplayState 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, DisplayCtx as p, DisplayMachine as q, DisplayState as r, FieldMetaPayload as s, FieldState as t, FieldStateMap as u, FieldStateMapEntry as v, FlatPath as w, FormErrorRecord as x, FormErrorsSurface as y, FormMeta as z };