attaform 0.27.5 → 0.28.0

package/dist/shared/{attaform.CzL2CZ8U.d.ts → attaform.Cgu-hdSb.d.mts}

@@ -164,6 +164,65 @@ declare const ROOT_PATH_KEY: PathKey;
  */
 declare function isPathPrefix(prefix: readonly Segment[], path: readonly Segment[]): boolean;
 
+/**
+ * Per-path field status. Replaced wholesale (not mutated in place) on
+ * every change. Five semantic groups:
+ *
+ *   - `connected` — is a DOM element registered for this path?
+ *   - `focused` / `blurred` — DOM-state flags. `null` while no element
+ *     is connected (no DOM means the concepts don't apply); plain
+ *     booleans once connected, with the invariant `blurred === !focused`
+ *     enforced by `markFocused`.
+ *   - `touched` — focus/blur history, not DOM state. Always a plain
+ *     boolean: `false` at registration, sticky `true` after first blur,
+ *     cleared only by `form.reset()` / `form.resetField(path)`. Persists
+ *     across disconnects so v-if'd-away fields don't lose their touched
+ *     state on rehide (wizard "show review of touched fields" patterns
+ *     rely on this).
+ *   - `interacted` — value-mutation history, not DOM state. Plain
+ *     boolean: `false` at registration, sticky `true` once the user
+ *     issues a value edit through the directive's input listeners
+ *     (never on hydration, default seeding, or programmatic setValue);
+ *     cleared with `touched` by `form.reset()` / `form.resetField(path)`.
+ *   - `blurredAfterInteraction` — the first blur that follows a value
+ *     edit (the field has been edited and then left). Plain boolean,
+ *     sticky `true`. A tab-through blur with no prior edit does NOT set
+ *     it (`interacted` is still false at that blur). Composes
+ *     `interacted` with the departure; drives the default display gate.
+ */
+type FieldRecord = {
+    readonly path: Path;
+    readonly updatedAt: string | null;
+    readonly connected: boolean;
+    readonly focused: boolean | null;
+    readonly blurred: boolean | null;
+    readonly touched: boolean;
+    readonly interacted: boolean;
+    readonly blurredAfterInteraction: boolean;
+};
+/** Per-path DOM element tracking. Client-only. */
+type ElementRecord = {
+    /**
+     * Original Path captured at first registration. Stored alongside the
+     * elements Set so the DOM-order sort cache can recover the structured
+     * Path without round-tripping through `JSON.parse(pathKey)`.
+     */
+    readonly path: Path;
+    readonly elements: Set<HTMLElement>;
+};
+/**
+ * Per-path record stored in `originals`. Pairing `segments` with the tracked
+ * value means `dirty` and `resetField`'s container loop don't have to
+ * `JSON.parse(pathKey)` on every iteration — the canonical Path is already
+ * sitting next to the value it belongs to. PathKey still keys the Map (the
+ * stable string is the only collision-free identifier), but downstream
+ * iteration reads `segments` directly.
+ */
+type OriginalsRecord = {
+    readonly segments: Path;
+    readonly value: unknown;
+};
+
 /** Internal brand for the `Unset` type. Never exposed at runtime. */
 declare const _unsetBrand: unique symbol;
 /**
@@ -722,11 +781,13 @@ interface JsonObject {
  * structured array — `['user', 'address', 0, 'line1']` for a nested
  * field, `[]` (the root path) for a form-level error (root `.refine()`
  * messages, `setErrors` entries with no path, hydration failures,
- * server-emitted form banners). `formKey` identifies which form
- * produced the error so a single error list can be routed to multiple
- * forms. The optional `data` slot carries an arbitrary server payload.
+ * server-emitted form banners). Which form produced an error is
+ * envelope-level identity: the `ValidationResponse` / submit result
+ * that carries the list stamps `formKey` once, and aggregators that
+ * merge lists across forms (the wizard) stamp their own envelope. The
+ * optional `data` slot carries an arbitrary server payload.
  *
- * Returned by `validate()` / `validateAsync()` / `handleSubmit`'s
+ * Returned by `validate()` / `parse()` / `handleSubmit`'s
  * `onError` callback, and accepted (leniently, as `ErrorInput`) by
  * `form.setErrors`.
  */
@@ -741,8 +802,6 @@ type ValidationError = {
      * literal empty-key field.
      */
     path: (string | number)[];
-    /** Identifies which form produced this error. */
-    formKey: FormKey;
     /**
      * Stable machine identifier for the failure, scoped by prefix:
      *
@@ -764,6 +823,23 @@ type ValidationError = {
      */
     data?: Json | null;
 };
+/**
+ * One path's slot in the form's tagged error store. The two sources
+ * that can put an error at a path stay segregated inside the cell:
+ * `schema` holds the validation pipeline's verdicts, `user` holds
+ * `setErrors` entries (and their history / SSR replays). Reads merge
+ * schema -> derived-blank -> user; each writer replaces exactly its
+ * own side. Cells are immutable — every write replaces the whole cell
+ * (or deletes the key when both sides empty), so Vue's per-key Map
+ * tracking fires for any side's change. An empty side is the shared
+ * frozen `NO_ERRORS` array, never a fresh allocation.
+ *
+ * @internal
+ */
+type ErrorCell = {
+    readonly schema: readonly ValidationError[];
+    readonly user: readonly ValidationError[];
+};
 /**
  * The lenient input shape `form.setErrors` accepts: a real `Error`, or
  * a partial `ValidationError` where every field is optional.
@@ -773,20 +849,17 @@ type ValidationError = {
  *   the path-scoped `setErrors(path, …)` form, which stamps its own.
  * - `code`: defaults to `atta:user-error`.
  * - `data`: forwarded verbatim onto the produced `ValidationError`.
- * - `formKey`: accepted but ignored — the form always stamps its own.
  *
- * Because every field is optional and `formKey` is accepted-and-ignored,
- * `ValidationError` is a subtype of `ErrorInput`: a `ValidationError[]`
- * you read back, or a server response that already emits the shape, pipes
- * straight into `form.setErrors` with no adapter and no excess-property
- * friction.
+ * Because every field is optional, `ValidationError` is a subtype of
+ * `ErrorInput`: a `ValidationError[]` you read back, or a server
+ * response that already emits the shape, pipes straight into
+ * `form.setErrors` with no adapter.
  */
 type ErrorInput = Error | {
     message?: string;
     path?: (string | number)[];
     code?: string;
     data?: Json | null;
-    formKey?: FormKey;
 };
 /** Settled validation result when the form (or subtree) parsed successfully. */
 type ValidationResponseSuccess<TData> = {
@@ -831,10 +904,19 @@ type ValidationResponse<TData> = ValidationResponseSuccess<TData> | ValidationRe
 type DefaultValuesResponse<TData> = ValidationResponseSuccess<TData> | ValidationResponseErrorWithData<TData>;
 /**
  * Trimmed `ValidationResponse` that omits the `data` payload. Used by
- * `validate()` / `validateAsync()` since consumers usually only need
- * the success flag and error list at those entry points.
+ * the reactive `validate()` status, whose consumers only need the
+ * success flag and error list.
  */
 type ValidationResponseWithoutValue<Form> = Omit<ValidationResponse<Form>, 'data'>;
+/**
+ * Options bag for `form.parse`. `commit: true` turns the pure read
+ * into an authoritative run: the verdict is committed to the error
+ * store at the parsed scope and in-flight per-field validation runs
+ * are cancelled first. Default `false`.
+ */
+type ParseOptions = {
+    readonly commit?: boolean;
+};
 /**
  * Sync-or-async return shape for `AbstractSchema.validateAtPath`. The
  * adapter returns the response inline when the schema and the
@@ -998,7 +1080,7 @@ type AbstractSchema<Form, GetValueFormType> = {
      * 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.
+     * parse), not at `setValue` time.
      *
      * Path-prefix semantic: returns true if ANY ancestor of `path`
      * resolves to such a wrapper, so descendants under a preprocess-
@@ -1010,25 +1092,24 @@ type AbstractSchema<Form, GetValueFormType> = {
      * Distinguish a tuple (fixed-length, position-typed) from an
      * unbounded array at `path`. The runtime calls this on every
      * `mergeStructural` / `setAtPathWithSchemaFill` write that descends
-     * into an array branch — caching the answer at the schema level
-     * replaces the per-write 1M-index probe + sequential probe loop
-     * (up to 1024 schema lookups) the runtime previously used.
+     * into an array branch, and the answer is definitive — the runtime
+     * never second-guesses it.
      *
      * Return values:
      * - `number` → tuple of this structural length. The runtime pads
      *   the consumer to this length and recurses position-by-position.
-     * - `null` → unbounded array. The runtime uses the consumer's
-     *   length and reuses one element default for every position.
-     * - `undefined` → the path doesn't resolve to an array OR the
-     *   adapter can't determine the shape. The runtime falls back to
-     *   a probe loop in this case (defensive — every built-in adapter
-     *   returns `number` or `null`).
+     * - `null` → not a tuple. Covers the unbounded array (the runtime
+     *   uses the consumer's length and reuses one element default for
+     *   every position) and every path that doesn't resolve to an
+     *   array at all — there `getDefaultAtPath` yields no element
+     *   default either, so the consumer's array passes through
+     *   unchanged.
      *
      * Wrappers (optional / nullable / default / readonly / catch /
      * pipe / lazy) are peeled transparently before the type check, so
      * `optional(z.tuple([...]))` reports its tuple length.
      */
-    arrayShapeAtPath(path: Path): number | null | undefined;
+    arrayShapeAtPath(path: Path): number | null;
     /**
      * 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
@@ -1307,6 +1388,19 @@ type AbstractSchema<Form, GetValueFormType> = {
      * toward returning `true` when in doubt.
      */
     hasContainerOrRootRefine?(): boolean;
+    /**
+     * `true` when the schema tree contains at least one discriminated
+     * union at any depth (inside arrays, tuples, records, and lazy
+     * schemas included). The store computes its per-form DU capability
+     * flag from this once at construction: `false` lets every write skip
+     * the cross-variant ancestor guard and the variant-reshape dispatch,
+     * and DU stub correction never runs. Optional: an adapter that omits
+     * it is treated as containing unions, keeping the conservative
+     * per-write probes on. Never return `false` for a schema that DOES
+     * hold a discriminated union — that disables variant reshape and
+     * stub correction for the form.
+     */
+    hasDiscriminatedUnions?(): boolean;
 };
 /**
  * Adapter-returned info for a discriminated union — its discriminator
@@ -1422,7 +1516,7 @@ type OnInvalidSubmitPolicy = 'none' | 'focus-first-error' | 'scroll-to-first-err
  *   registered field. No debounce — `debounceMs` is rejected by the
  *   type.
  * - `'submit'`: no live validation. `handleSubmit` and explicit
- *   `validate()` / `validateAsync()` calls are the only validation
+ *   `validate()` / `parse()` calls are the only validation
  *   surfaces. `debounceMs` is rejected by the type.
  */
 type ValidateOn = 'change' | 'blur' | 'submit';
@@ -1499,8 +1593,8 @@ type WriteMeta = {
     readonly skipDiscriminatorReshape?: boolean;
     /**
      * Records an array structural mutation precisely enough to replay the
-     * exact index permutation it produced, set by `field-arrays.ts`
-     * helpers. `setValueAtPath` uses it to surgically clear variant memory
+     * exact index permutation it produced, set by the typed array helpers
+     * in `array-engine.ts`. `setValueAtPath` uses it to surgically clear variant memory
      * for the indices the operation invalidated. Without this hint, a raw
      * whole-array `setValue(arrayPath, [...])` clears all memory under the
      * array (the runtime can't tell which indices stayed put). Internal —
@@ -1551,19 +1645,68 @@ type WriteMeta = {
     readonly hydration?: boolean;
 };
 /**
- * Undo/redo configuration passed via `useForm({ history })`.
+ * The store slice the history runtime binds to. Structural on purpose:
+ * `historyPlugin()` ships from the separate `attaform/history` entry, so
+ * the runtime receives the store through this seam instead of importing
+ * the store module (which would pull the history internals onto every
+ * form's eager path). A FormStore satisfies it as-is.
  *
- * - `true` — enable with the default position cap (`max: 128`).
- * - `{ max }` — enable and tune the bounded history size.
+ * @internal
+ */
+type HistoryKernel = {
+    readonly form: Ref<unknown>;
+    readonly blankPaths: Set<PathKey>;
+    readonly errorCells: Map<PathKey, ErrorCell>;
+    onFormChange(listener: (next: unknown, meta?: WriteMeta) => void): () => void;
+    applyFormReplacement(next: unknown): void;
+    restoreErrorCells(entries: ReadonlyArray<readonly [PathKey, ErrorCell]>): void;
+};
+/**
+ * The live undo/redo runtime a {@link HistoryPlugin} attaches to one
+ * form. Cached on the FormStore so every `useForm` / `injectForm`
+ * consumer of the same key shares one chain; `buildFormApi` adapts it
+ * into the public `form.history` namespace.
  *
- * When enabled, every mutation records a forward delta; `form.history.undo()`
+ * @internal
+ */
+type HistoryModule = {
+    undo(): boolean;
+    redo(): boolean;
+    clear(): void;
+    canUndo: Readonly<ComputedRef<boolean>>;
+    canRedo: Readonly<ComputedRef<boolean>>;
+    historySize: Readonly<ComputedRef<number>>;
+    dispose(): void;
+};
+/**
+ * Opt-in undo/redo, created by `historyPlugin()` from `attaform/history`
+ * and passed via `useForm({ history })`:
+ *
+ * ```ts
+ * import { historyPlugin } from 'attaform/history'
+ *
+ * const form = useForm({ schema, history: historyPlugin({ max: 200 }) })
+ * ```
+ *
+ * When enabled, every mutation records a position; `form.history.undo()`
  * / `form.history.redo()` walk the chain. `reset()` is itself a mutation —
  * the pre-reset state stays one undo away. Persistence hydration is the
  * floor: after hydrate applies, the chain reseeds with the hydrated value
  * and `undo()` cannot reach the transient pre-hydration default.
+ *
+ * One plugin instance is a reusable configuration, not per-form state:
+ * passing the same instance to several forms (or setting it once via
+ * `createAttaform({ defaults: { history } })`) gives each form its own
+ * independent chain.
  */
-type HistoryConfig = true | {
-    max?: number;
+type HistoryPlugin = {
+    /**
+     * Bind a fresh history runtime to one form's store. Called by
+     * `useForm` when the store is first created.
+     *
+     * @internal
+     */
+    readonly attach: (kernel: HistoryKernel) => HistoryModule;
 };
 /**
  * Consolidated undo/redo namespace at `form.history`. All history-related
@@ -1781,16 +1924,17 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      */
     debounceMs?: number;
     /**
-     * Opt-in undo/redo. Off by default. `true` enables with a 128-position
-     * cap; `{ max: N }` tunes the cap.
+     * Opt-in undo/redo. Off by default. Pass `historyPlugin()` from
+     * `attaform/history` — a 128-position cap by default,
+     * `historyPlugin({ max: N })` to tune it.
      *
-     * Every mutation records a forward delta. `form.history.undo()` walks
+     * Every mutation records a position. `form.history.undo()` walks
      * one step back; `form.history.redo()` walks one step forward.
      * `reset()` is itself a mutation, so the pre-reset state stays one
      * undo away. The consolidated `form.history` namespace also exposes
      * `clear()`, `canUndo`, `canRedo`, and `size`.
      */
-    history?: HistoryConfig;
+    history?: HistoryPlugin;
     /**
      * Whether to remember the typed state of each discriminated-union
      * variant across switches. Default `true`.
@@ -1936,8 +2080,8 @@ type AttaformDefaults = {
      * `validateOn` resolves to `'change'`. Default `0` (synchronous).
      */
     debounceMs?: number;
-    /** Default for `useForm({ history })`. */
-    history?: HistoryConfig;
+    /** Default for `useForm({ history })` — a `historyPlugin()` instance. */
+    history?: HistoryPlugin;
     /** Default for `useForm({ rememberVariants })`. */
     rememberVariants?: boolean;
     /** Default for `useForm({ disabled })` — freeze the form's data. */
@@ -2016,7 +2160,7 @@ type AttaformDefaults = {
      *
      * "Permissive fallback" means storage and reads keep working at any
      * depth; only the per-write type gate stops checking past the cap.
-     * Full schema validation (`validateAsync`, `handleSubmit`) still runs
+     * Full schema validation (`parse`, `handleSubmit`) still runs
      * against the real schema, so refinement errors at any depth still
      * surface — the cap only affects the *write-time gate*.
      *
@@ -2425,6 +2569,49 @@ type RegisterOptions = {
      */
     autoAria?: boolean;
 };
+/**
+ * The narrow kernel surface the DOM binding drives. Structurally a
+ * subset of the form store: the field-record connect/disconnect
+ * transitions, focus marking (which owns blur-validation), the record
+ * and merged-error reads the focus walk needs, and the async-transform
+ * abort for a fully-detached path.
+ * @internal
+ */
+type DomBindingKernel = {
+    readonly noteDomConnected: (path: Path) => void;
+    readonly noteDomDisconnected: (path: Path) => void;
+    readonly markFocused: (path: Path, focused: boolean, meta?: {
+        readonly instance?: WriteMeta['instance'];
+    }) => void;
+    readonly getFieldRecord: (path: Path) => FieldRecord | undefined;
+    readonly getErrorsForPath: (path: Path) => ValidationError[];
+    readonly cancelTransformsUnder: (prefix: Path) => void;
+};
+/**
+ * The form store's DOM slice: the element registry backing
+ * `field.element` / `field.elements`, no-latch host focus anchors, and
+ * first-error focus resolution. Implemented in the directive cluster's
+ * lazy graph and armed into the store's `domBinding` slot on first use
+ * (see `RegisterValue.ensureDomBinding`); a `null` slot means nothing
+ * in the app ever registered an element.
+ * @internal
+ */
+type AttaformDomBinding = {
+    readonly elements: Map<PathKey, ElementRecord>;
+    readonly attach: (segments: Path, element: HTMLElement, formInstanceId: string, instanceMeta: WriteMeta['instance'] | undefined) => void;
+    readonly detach: (segments: Path, element: HTMLElement) => void;
+    readonly markHostConnected: (segments: Path, connected: boolean, hostEl: HTMLElement, formInstanceId: string) => void;
+    readonly getFirstErrorElement: (formInstanceId: string) => {
+        path: Path;
+        element: HTMLElement;
+    } | null;
+};
+/**
+ * Factory the directive / `useRegister` inject through
+ * `RegisterValue.ensureDomBinding` to arm a store's `domBinding` slot.
+ * @internal
+ */
+type DomBindingFactory = (kernel: DomBindingKernel) => AttaformDomBinding;
 /**
  * The object returned by `form.register(path)`. Pass it to a native
  * input via `v-register`:
@@ -2530,6 +2717,17 @@ type RegisterValue<Value = unknown> = Readonly<{
      * @internal
      */
     hasRegisteredDescendant: (hostElement: HTMLElement) => boolean;
+    /**
+     * Arm this binding's form store with the DOM-binding implementation
+     * (element registry, focus listeners, first-error focus resolution).
+     * The implementation lives in the directive cluster's lazy graph, so
+     * the directive and `useRegister` inject its factory here before any
+     * element call; once armed, the store's `domBinding` slot serves every
+     * later registration. Optional so hand-rolled RegisterValues, which
+     * own their element handling, don't have to declare it.
+     * @internal
+     */
+    ensureDomBinding?: (factory: DomBindingFactory) => void;
     /**
      * Canonical, JSON-encoded path key for this binding (e.g.
      * `'["items",0,"name"]'`). Useful for stable Map / Set keys, log
@@ -2958,10 +3156,10 @@ type RegisterModelDynamicCustomDirective = ObjectDirective<HTMLInputElement | HT
  * See `RegisterTextModifier` / `RegisterSelectModifier` for
  * per-modifier semantics.
  *
- * Registered globally by `createAttaform()` (and by the
- * `attaform/nuxt` module). Most consumers don't import the
- * directive itself — it's exposed for integrations that install
- * directives manually.
+ * Delivered by the Vite / Nuxt plugin's compile-time binding, or by
+ * `installVRegister(app)` from `attaform/directive` everywhere else.
+ * Most consumers don't import the directive itself — it's exposed for
+ * integrations that install directives manually.
  */
 type RegisterDirective = RegisterTextCustomDirective | RegisterCheckboxCustomDirective | RegisterSelectCustomDirective | RegisterRadioCustomDirective | RegisterModelDynamicCustomDirective;
 /**
@@ -3206,7 +3404,7 @@ type FieldState<Value = unknown> = {
      * `true` while a per-field validation run is in flight at this path.
      * Reflects field-level debounced runs (`validate-on-change`) and
      * cross-field re-validations targeting this path. Whole-form
-     * `validate()` / `validateAsync()` calls drive `form.meta.validating`
+     * `validate()` / `parse()` calls drive `form.meta.validating`
      * only — they don't flip per-field flags.
      *
      * Per-field analogue of `form.meta.validating`. Use for a tight
@@ -3637,12 +3835,20 @@ type FieldStateMap<Form extends GenericForm> = LeafWalker<Form, 'field'> & {
      */
     <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.
-     * Equivalent to `form.fields[a][b][...]` but useful when the path
-     * is built from variables.
+     * Tuple-segment form. The segment-array spelling of the string
+     * call-form above, for a path built from variables — the two resolve
+     * to the same proxy, so `form.fields(['users', i, 'email'])` and
+     * `form.fields(\`users.${i}.email\`)` are interchangeable.
+     *
+     * Resolves to that path's `FieldState`, which at a container is its
+     * rolled-up aggregate (`displayState`, `valid`, `dirty`, ... all
+     * exist regardless of the value type), exactly as the string form
+     * does. Note this is the CALL form: it hands back the path's state,
+     * not a drillable sub-proxy. To walk into a container's children use
+     * dot/bracket access (`form.fields.users[i].email`), which is what
+     * descends.
      */
-    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): FieldStateMapEntry<NestedType<Form, JoinSegments<S>>>;
+    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): FieldState<NestedType<Form, JoinSegments<S>>>;
     /**
      * Dynamic-array fallback for callers passing `Path`-typed (runtime)
      * segment arrays — e.g. forwarding `RegisterValue.segments` to
@@ -4165,19 +4371,6 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * settles to results from the most recent call.
      */
     validate: (path?: FlatPath<Form>) => Readonly<Ref<ReactiveValidationStatus<Form>>>;
-    /**
-     * Run validation once and return the result. Unlike `validate()`,
-     * this does not subscribe to form reactivity.
-     *
-     * ```ts
-     * const result = await form.validateAsync()
-     * if (!result.success) showErrors(result.errors)
-     * ```
-     *
-     * Pass a path to validate a subtree. `state.validating` flips
-     * `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.
@@ -4199,9 +4392,9 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      */
     settleTransforms: (path?: FlatPath<Form>) => Promise<void>;
     /**
-     * Imperative one-shot parse. Same pipeline as `validateAsync` —
-     * runs refinements, applies `.transform()`s, composes blank-required
-     * errors — but RETAINS the parsed data instead of stripping it.
+     * Imperative one-shot parse. Runs the full pipeline — refinements,
+     * `.transform()`s, blank-required composition — against the current
+     * form snapshot and RETAINS the parsed data.
      *
      * Storage holds the "honest input view" — values you wrote, with
      * preprocess normalization applied but `.transform()` deferred. For
@@ -4219,16 +4412,31 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * }
      * ```
      *
+     * By default the call is a PURE read: nothing is written to
+     * `form.errors`, and in-flight per-field validation runs are left
+     * alone. Pass `{ commit: true }` to make the run authoritative —
+     * the verdict is committed to the error store at the parsed scope
+     * and any in-flight per-field runs are cancelled first (mirroring
+     * `handleSubmit`), so `await form.parse('email', { commit: true })`
+     * lands a deterministic view of `form.errors.email`:
+     *
+     * ```ts
+     * const result = await form.parse({ commit: true })
+     * if (!result.success) showErrors(result.errors)
+     * ```
+     *
      * 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).
+     * flips `true` while the promise is in flight.
      */
-    parse: (path?: FlatPath<Form>) => Promise<ValidationResponse<GetValueFormType>>;
+    parse: {
+        (path?: FlatPath<Form>, options?: ParseOptions): Promise<ValidationResponse<GetValueFormType>>;
+        (options: ParseOptions): Promise<ValidationResponse<GetValueFormType>>;
+    };
     /**
      * Bind a path to a native input via `v-register`. Returns a
      * `RegisterValue` carrying the live ref and event handlers the
@@ -4583,11 +4791,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      */
     applyInvalidSubmitPolicy: (policy?: OnInvalidSubmitPolicy) => void;
     /**
-     * Programmatically mark fields as touched — the sticky flag the
-     * standard "show errors after interaction" pattern reads. Closes
-     * the gap when fields are populated without a DOM gesture (post-
-     * import, paste, autofill, server-seeded values you want to
-     * validate immediately).
+     * Programmatically mark fields as `touched` — the descriptive
+     * "this field was visited" flag.
      *
      * ```ts
      * form.touch('email')                 // one leaf
@@ -4596,12 +4801,57 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * form.touch()                        // every leaf in the form
      * ```
      *
+     * **This does not reveal errors under the default display
+     * heuristic.** `touched` also flips on a bare focus → blur with no
+     * edit, so the library-default gate deliberately ignores it and
+     * reads `blurredAfterInteraction` instead — the stricter bit that
+     * only a blur *following* an edit sets. Reach for `touch()` when a
+     * custom `getDisplayState` reducer or your analytics reads
+     * `touched`; reach for {@link UseFormReturnType.interact} to make
+     * seeded or imported values surface their errors.
+     *
      * Pure flag write — does not mutate value, focused, blurred, or
      * trigger validation. Idempotent: re-calling on an already-touched
      * field is a no-op. Touched is sticky-true; pair with
      * `form.reset()` / `form.resetField()` to clear.
      */
     touch: (path?: FlatPath<Form> | (string | number)[]) => void;
+    /**
+     * Simulate a complete focus → edit → blur over every leaf under
+     * `path` (the whole form when omitted), so values that arrived
+     * without a DOM gesture reveal their errors under the default
+     * display heuristic.
+     *
+     * ```ts
+     * form.interact('profile')            // arm one subtree
+     * await form.interact(['members', 2]) // errors committed on resolve
+     * form.interact()                     // every leaf in the form
+     * ```
+     *
+     * Flips the full interaction ladder (`touched`, `interacted`, and
+     * `blurredAfterInteraction`) and runs the subtree's validation, so
+     * the default gate — `submissionAttempts > 0 ||
+     * blurredAfterInteraction` — opens through its front door. Use it
+     * to arm one region's errors without a form-wide submit, which
+     * would light up every other field on the page: a field-array row
+     * edited in a modal, a server-seeded section, a pasted import.
+     *
+     * Walks schema leaves, so it reaches fields that are currently
+     * `v-if`'d away or were never mounted; the flags are sticky, so
+     * such a subtree stays revealed when it remounts.
+     *
+     * Flags land synchronously — the returned promise resolves once the
+     * subtree's validation has committed, so an awaiting caller can read
+     * `showErrors` / `errors` immediately after. It never rejects, and
+     * ignoring it is fine.
+     *
+     * No-op on a disabled form, matching every other interaction-
+     * lifecycle write. Does not mutate value, `focused`, or `blurred`:
+     * those are DOM-owned, and the display gate reads none of them.
+     * Sticky like `touched`; pair with `form.reset()` /
+     * `form.resetField()` to clear.
+     */
+    interact: (path?: FlatPath<Form> | (string | number)[]) => Promise<void>;
     /**
      * Append `value` to the array at `path`.
      *
@@ -4709,5 +4959,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as X, ROOT_PATH_KEY as Y, canonicalizePath as al, isPathPrefix as am, isUnset as an, parseDottedPath as ao, unset as ap };
-export type { RegisterFlatPath as $, AbstractSchema as A, NestedType as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput 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, OnInvalidSubmitPolicy as P, OnSubmit as Q, PartialFlatPath as R, Path as S, PathKey as T, UseFormConfiguration as U, PendingValidationStatus as V, Primitive as W, ReactiveValidationStatus as Z, RegisterDirective as _, UseFormReturnType as a, RegisterOptions as a0, RegisterSelectModifier as a1, RegisterTextModifier as a2, RegisterTransform as a3, RegisterValue as a4, Segment as a5, SetValueCallback as a6, SetValuePayload as a7, SettledValidationStatus as a8, SlimPrimitiveKind as a9, SlimRuntimeOf as aa, SubmitHandler as ab, Unset as ac, ValidateOn as ad, ValidateOnConfig as ae, ValidationError as af, ValidationResponse as ag, ValidationResponseWithoutValue as ah, ValueOfUnion as ai, WriteMeta as aj, WriteShape as ak, AcceptableDefaults as aq, SchemaFactoryOptions as ar, TransformAbortHolder as as, RegisterModelDynamicCustomDirective as at, ArrayItem as b, ArrayPath as c, AttaformDefaults as d, CoercionRegistry as e, CoercionResult as f, CustomDirectiveRegisterAssignerFn as g, DeepPartial as h, DefaultValuesResponse as i, DefaultValuesShape as j, DisplayCtx as k, DisplayMachine as l, DisplayState as m, ErrorsProxyShape 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, GetDisplayState as w, HistoryConfig as x, IsUnion as y, Json as z };
+export { ROOT_PATH as Y, ROOT_PATH_KEY as Z, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
+export type { RegisterDirective as $, AbstractSchema as A, NestedType as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput 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, OnInvalidSubmitPolicy as P, OnSubmit as Q, ParseOptions as R, PartialFlatPath as S, Path as T, UseFormConfiguration as U, PathKey as V, PendingValidationStatus as W, Primitive as X, ReactiveValidationStatus as _, UseFormReturnType as a, RegisterFlatPath as a0, RegisterOptions as a1, RegisterSelectModifier as a2, RegisterTextModifier as a3, RegisterTransform as a4, RegisterValue as a5, Segment as a6, SetValueCallback as a7, SetValuePayload as a8, SettledValidationStatus as a9, SlimPrimitiveKind as aa, SlimRuntimeOf as ab, SubmitHandler as ac, Unset as ad, ValidateOn as ae, ValidateOnConfig as af, ValidationError as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, RegisterModelDynamicCustomDirective as ar, AcceptableDefaults as as, SchemaFactoryOptions as at, FieldRecord as au, ErrorCell as av, OriginalsRecord as aw, AttaformDomBinding as ax, TransformAbortHolder as ay, ArrayItem as b, ArrayPath as c, AttaformDefaults as d, CoercionRegistry as e, CoercionResult as f, CustomDirectiveRegisterAssignerFn as g, DeepPartial as h, DefaultValuesResponse as i, DefaultValuesShape as j, DisplayCtx as k, DisplayMachine as l, DisplayState as m, ErrorsProxyShape 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, GetDisplayState as w, HistoryPlugin as x, IsUnion as y, Json as z };

package/dist/shared/attaform.Cs2Rbdlo.mjs

@@ -791,4 +791,3 @@ function hasPreamble(element) {
 }
 
 export { vRegisterPreambleTransform as a, componentBridgeTransform as c, inputTextAreaNodeTransform as i, redundantBindingWarnTransform as r, vRegisterHintTransform as v };
-//# sourceMappingURL=attaform.Cs2Rbdlo.mjs.map