attaform 0.18.2 → 0.20.0

package/dist/shared/{attaform.Ca5_6Ky-.d.mts → attaform.SfhU0OEY.d.cts}

@@ -136,6 +136,28 @@ declare function isUnset(value: unknown): value is Unset;
 type GenericForm = Record<string, unknown>;
 /** Internal helper — `true` when `T` is an object or array. */
 type IsObjectOrArray<T> = T extends GenericForm ? true : T extends Array<unknown> ? true : false;
+/**
+ * Shared recursion body backing `PartialFlatPath` and `RegisterFlatPath`.
+ * One walk over `Form`; `Mode` controls whether intermediate container
+ * paths are emitted alongside their reachable leaves.
+ *
+ * - `'partial'`: emit every container path (object containers, nested-
+ *   object array roots, array-of-object element containers). Used by
+ *   `setValue` / `form.values.<path>` / every read-side API that needs
+ *   to address a container.
+ * - `'register'`: skip container paths. `v-register` binds onto a
+ *   leaf-backing native element (`<input>`, `<select>`, `<textarea>`),
+ *   so container paths aren't registrable. Primitive arrays still
+ *   admit the array-root path under both modes (multi-select and
+ *   grouped-checkbox bindings register onto the array itself).
+ *
+ * Both walkers were independent recursions before; threading `Mode`
+ * through one body keeps the surface guarded by a single source of
+ * truth, and `PartialFlatPath` / `RegisterFlatPath` stay byte-
+ * identical to the prior hand-written walks (see
+ * `test/types/flat-path-walker.test.ts`).
+ */
+type FlatPathBuilder<Form, Mode extends 'partial' | 'register', Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? Mode extends 'partial' ? `${Key}` | `${Key}.${number}` | `${Key}.${number}.${FlatPathBuilder<ArrayItem, Mode>}` : `${Key}.${number}.${FlatPathBuilder<ArrayItem, Mode>}` : `${Key}` | `${Key}.${number}` : Value extends GenericForm ? Mode extends 'partial' ? `${Key}` | `${Key}.${FlatPathBuilder<Value, Mode>}` : `${Key}.${FlatPathBuilder<Value, Mode>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${FlatPathBuilder<Form[Key], Mode>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? Mode extends 'partial' ? `${Key}.${number}` | `${Key}.${number}.${FlatPathBuilder<ArrayItem, Mode>}` : `${Key}.${number}.${FlatPathBuilder<ArrayItem, Mode>}` : `${Key}.${number}` : never) : never : never;
 /**
  * Implementation detail backing `FlatPath` in its default
  * (partial-path) mode. Exported so `rollup-plugin-dts` preserves it
@@ -146,8 +168,7 @@ type IsObjectOrArray<T> = T extends GenericForm ? true : T extends Array<unknown
  * when multiple complex forms share a scope. Consumers should reach
  * for `FlatPath` instead; this alias is not part of the stable surface.
  */
-type PartialFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? `${Key}` | `${Key}.${number}` | `${Key}.${number}.${PartialFlatPath<ArrayItem>}` : Value extends GenericForm ? `${Key}` | `${Key}.${PartialFlatPath<Value>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${PartialFlatPath<Form[Key]>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}` | `${Key}.${number}.${PartialFlatPath<ArrayItem>}` : `${Key}.${number}` : never) : never : never;
-type CompleteFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? `${Key}.${number}.${CompleteFlatPath<ArrayItem>}` : Value extends GenericForm ? `${Key}.${CompleteFlatPath<Value>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${CompleteFlatPath<Form[Key]>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}.${CompleteFlatPath<ArrayItem>}` : `${Key}.${number}` : never) : never : never;
+type PartialFlatPath<Form, Key extends keyof Form = keyof Form> = FlatPathBuilder<Form, 'partial', Key>;
 /**
  * Union of dotted-string paths reachable inside `Form`, e.g. for
  * `{ user: { email: string }, items: string[] }`:
@@ -157,11 +178,8 @@ type CompleteFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArr
  * Used by every path-addressed API (`setValue(path, value)`,
  * `register(path)`, `toRef(path)`, etc.) so paths autocomplete in
  * the IDE and typos compile-error.
- *
- * Set `ForceFullPath` to `true` to restrict to leaf paths only
- * (no intermediate container paths).
  */
-type FlatPath<Form, Key extends keyof Form = keyof Form, ForceFullPath extends boolean = false> = ForceFullPath extends true ? CompleteFlatPath<Form, Key> : PartialFlatPath<Form, Key>;
+type FlatPath<Form, Key extends keyof Form = keyof Form> = PartialFlatPath<Form, Key>;
 /**
  * Convert a tuple of path segments to its dotted-string equivalent.
  *
@@ -251,6 +269,31 @@ type LiftedValueShape<T> = [T] extends [
 type DeepPartial<T> = T extends Primitive ? T : T extends Array<infer ArrayItem> ? DeepPartial<ArrayItem>[] : T extends object ? {
     [Key in keyof T]?: DeepPartial<T[Key]>;
 } : T;
+/**
+ * Shared descent body backing `NestedType` and `NestedReadType`. The
+ * recursion is identical — segment-by-segment, distributing over
+ * union members via `KeyofUnion` / `ValueOfUnion`. The two walkers
+ * diverge only at the leaf:
+ *
+ * - `TaintArrayCrossings extends false` (`NestedType` mode): leaves
+ *   are returned untouched. Used by strict write-side APIs that need
+ *   the exact resolved type (`setValue`'s value parameter,
+ *   `form.fields.<path>`'s state map).
+ * - `TaintArrayCrossings extends true` (`NestedReadType` mode): leaves
+ *   are widened with `| undefined` whenever any segment in the walk
+ *   was numeric (array index). Reflects the runtime possibility of an
+ *   out-of-bounds read.
+ *
+ * `_Tainted` propagates the array-crossing under taint mode; under
+ * strict mode it stays `false` through every recursion arm. Both
+ * arms strip nullishness at the root (`_RootValue = NonNullable<…>`)
+ * — the prior `NestedType.FilterOutNullishTypesDuringRecursion` flag
+ * was vestigial, never overridden from the outside.
+ *
+ * Not part of the stable consumer surface — reach for `NestedType` or
+ * `NestedReadType` directly.
+ */
+type NestedTypeBuilder<RootValue, FlattenedPath extends string, TaintArrayCrossings extends boolean, _Tainted extends boolean = false, _RootValue = NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedTypeBuilder<ValueOfUnion<_RootValue, Key>, Rest, TaintArrayCrossings, TaintArrayCrossings extends true ? true : _Tainted> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedTypeBuilder<ValueOfUnion<_RootValue, NumericKey>, Rest, TaintArrayCrossings, TaintArrayCrossings extends true ? true : _Tainted> : never : never : Key extends KeyofUnion<_RootValue> ? NestedTypeBuilder<ValueOfUnion<_RootValue, Key>, Rest, TaintArrayCrossings, _Tainted> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? TaintArrayCrossings extends true ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : ValueOfUnion<_RootValue, FlattenedPath> : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? TaintArrayCrossings extends true ? ValueOfUnion<_RootValue, NumericKey> | undefined : ValueOfUnion<_RootValue, NumericKey> : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? _Tainted extends true ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : ValueOfUnion<_RootValue, FlattenedPath> : never;
 /**
  * Resolve the type at a dotted-string path inside `RootValue`. Used
  * by the strict (write-side) APIs to derive the type at a path:
@@ -264,11 +307,16 @@ type DeepPartial<T> = T extends Primitive ? T : T extends Array<infer ArrayItem>
  * useful value type (vs. silently collapsing to `never` because
  * `keyof (A|B|C)` would be the intersection of all variants' keys).
  *
+ * Composed over `NestedTypeBuilder` with array-crossing tainting OFF,
+ * so leaves return their exact resolved type. The companion
+ * `NestedReadType` shares the same recursion body but enables
+ * tainting for read-side APIs.
+ *
  * TypeScript caps conditional-type recursion at around 50 levels;
  * paths deeper than that resolve to `never`. Real form schemas
  * never reach this depth.
  */
-type NestedType<RootValue, FlattenedPath extends string, FilterOutNullishTypesDuringRecursion extends boolean = true, _RootValue = FilterOutNullishTypesDuringRecursion extends false ? RootValue : NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, Key>, Rest, FilterOutNullishTypesDuringRecursion> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, NumericKey>, Rest, FilterOutNullishTypesDuringRecursion> : never : never : Key extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, Key>, Rest, FilterOutNullishTypesDuringRecursion> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, NumericKey> : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> : never;
+type NestedType<RootValue, FlattenedPath extends string> = NestedTypeBuilder<RootValue, FlattenedPath, false>;
 /**
  * Implementation-detail primitive-leaf marker used by `DeepPartial`
  * and sibling structural walkers. Exported so the bundled `.d.ts`
@@ -300,7 +348,7 @@ type IsTuple<T extends readonly unknown[]> = number extends T['length'] ? false
  * `register(path).innerRef` so the compile-time type honours the
  * runtime possibility of a missing array position.
  */
-type NestedReadType<RootValue, FlattenedPath extends string, _Tainted extends boolean = false, _RootValue = NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, Key>, Rest, true> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, NumericKey>, Rest, true> : never : never : Key extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, Key>, Rest, _Tainted> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, NumericKey> | undefined : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? _Tainted extends true ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : ValueOfUnion<_RootValue, FlattenedPath> : never;
+type NestedReadType<RootValue, FlattenedPath extends string> = NestedTypeBuilder<RootValue, FlattenedPath, true>;
 /**
  * Filter FlatPath<Form> down to the subset of paths whose resolved leaf
  * is an array. Used by the typed field-array helpers (append / remove /
@@ -319,6 +367,26 @@ type ArrayPath<Form, P extends FlatPath<Form> = FlatPath<Form>> = P extends stri
  * constrain `Path extends ArrayPath<Form>` so this is always well-defined.
  */
 type ArrayItem<Form, Path extends ArrayPath<Form>> = NestedType<Form, Path> extends ReadonlyArray<infer Item> ? Item : never;
+/**
+ * Companion to `ArrayPath`: filter `FlatPath<Form>` down to the subset
+ * of paths whose resolved leaf is a record (an object with an open
+ * string-keyed index signature, e.g. `z.record(z.string(), V)`). A
+ * fixed-shape object (`z.object({ ... })`) is excluded — its keys are
+ * statically known, so it has no `string` index signature.
+ *
+ * `string extends keyof T` is the index-signature probe: it holds for
+ * `Record<string, V>` (`keyof` is `string`) and fails for a fixed object
+ * (`keyof` is the literal key union). The leading array guard keeps
+ * arrays (which also satisfy the object check) out of the record set.
+ */
+type RecordPath<Form, P extends FlatPath<Form> = FlatPath<Form>> = P extends string ? NestedType<Form, P> extends readonly unknown[] ? never : NestedType<Form, P> extends Record<string, unknown> ? string extends keyof NestedType<Form, P> ? P : never : never : never;
+/**
+ * Value type of the record addressed by `Path` — the `V` in a
+ * `Record<string, V>`. Callers constrain `Path extends RecordPath<Form>`,
+ * so the leaf is always an open string-keyed record and this is
+ * well-defined.
+ */
+type RecordValue<Form, Path extends RecordPath<Form>> = NestedType<Form, Path> extends Record<string, infer Value> ? Value : never;
 /**
  * Widens primitive-literal leaves to their primitive supertype to
  * match the runtime "slim-primitive write contract."
@@ -368,6 +436,28 @@ type WriteShape<T> = T extends string | number | boolean | bigint | symbol | nul
 } : Array<WriteShape<U>> : T extends object ? {
     [K in keyof T]: WriteShape<T[K]>;
 } : T;
+/**
+ * Walk `T` and add `| Unset` at every primitive leaf (except symbol /
+ * null / undefined), every opaque leaf (`Date`, `RegExp`, `Map`,
+ * `Set`, functions), and every container position (object, tuple,
+ * array). The recursion topology mirrors `WriteShape<T>` exactly —
+ * `DefaultValuesShape<T>` is then a 1-line composition.
+ *
+ * Symbol / null / undefined leaves pass through untouched so the
+ * runtime sentinel doesn't pollute leaf semantics it has no business
+ * carrying. Container positions widen so a single `unset` at any
+ * level recursively marks every descendant primitive blank.
+ *
+ * Not part of the stable consumer-facing surface — reach for
+ * `DefaultValuesShape` instead.
+ */
+type AugmentWithUnset<T> = T extends string | number | boolean | bigint ? T | Unset : T extends symbol | null | undefined ? T : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown) ? T | Unset : T extends readonly [unknown, ...unknown[]] ? {
+    -readonly [K in keyof T]: AugmentWithUnset<T[K]>;
+} | Unset : T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? {
+    -readonly [K in keyof T]: AugmentWithUnset<T[K]>;
+} | Unset : Array<AugmentWithUnset<U>> | Unset : T extends object ? {
+    [K in keyof T]: AugmentWithUnset<T[K]>;
+} | Unset : T;
 /**
  * Like `WriteShape<T>`, but additionally widens every primitive leaf
  * (`string`, `number`, `boolean`, `bigint`) to admit `Unset` — the
@@ -381,8 +471,10 @@ type WriteShape<T> = T extends string | number | boolean | bigint | symbol | nul
  * descendant blank, so `defaultValues: { profile: unset }` and
  * `setValue('cargo', unset)` typecheck cleanly.
  *
- * The recursion mirrors `WriteShape<T>` exactly so `defaultValues`
- * stays compatible at every nested position. Tuple positions,
+ * Composed as `AugmentWithUnset<WriteShape<T>>`: stage 1 widens
+ * primitive literals, stage 2 adds `| Unset` everywhere — the prior
+ * inline walker hand-synced this in a single body. The composition
+ * stays compatible at every nested position; tuple positions,
  * unbounded arrays, and nested records all flow through unchanged.
  *
  * Example:
@@ -393,13 +485,7 @@ type WriteShape<T> = T extends string | number | boolean | bigint | symbol | nul
  * Used by `UseFormConfiguration.defaultValues`, `setValue`'s value
  * parameter, and `reset`'s parameter.
  */
-type DefaultValuesShape<T> = T extends string | number | boolean | bigint | symbol | null | undefined ? T extends string ? string | Unset : T extends number ? number | Unset : T extends boolean ? boolean | Unset : T extends bigint ? bigint | Unset : T extends symbol ? symbol : T : T extends Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown) ? T | Unset : T extends readonly [unknown, ...unknown[]] ? {
-    -readonly [K in keyof T]: DefaultValuesShape<T[K]>;
-} | Unset : T extends ReadonlyArray<infer U> ? IsTuple<T> extends true ? {
-    -readonly [K in keyof T]: DefaultValuesShape<T[K]>;
-} | Unset : Array<DefaultValuesShape<U>> | Unset : T extends object ? {
-    [K in keyof T]: DefaultValuesShape<T[K]>;
-} | Unset : T;
+type DefaultValuesShape<T> = AugmentWithUnset<WriteShape<T>>;
 /**
  * Single-walker fusion of `DeepPartial` and `DefaultValuesShape` — the
  * type accepted at `defaultValues`, `reset()`'s parameter, and every
@@ -693,6 +779,15 @@ type MaybePromise<T> = T | Promise<T>;
 type ValidateOptions = {
     sync?: boolean;
 };
+/**
+ * Configuration passed to `AbstractSchema.getDefaultValues`. Adapters
+ * receive `useDefaultSchemaValues` (honor `.default(x)` wrappers vs.
+ * empty/falsy fallbacks), an optional `strict` mode (refinement
+ * preservation), and an optional `constraints` overlay merged into the
+ * derived defaults so the runtime can stamp user-supplied defaults at
+ * construction. Exported so adapter authors can co-implement the
+ * service contract.
+ */
 type GetDefaultValuesConfig<Form> = {
     useDefaultSchemaValues: boolean;
     /**
@@ -1072,6 +1167,32 @@ type AbstractSchema<Form, GetValueFormType> = {
      * answers without a separate top-level overload.
      */
     needsAsyncValidation?(): boolean;
+    /**
+     * Return `true` iff the schema carries a refine / check / transform
+     * at any NON-LEAF position — a container node (object / array /
+     * tuple / union / intersection / record / map / set) or the root
+     * itself. False means every check this schema runs is leaf-local,
+     * so a per-keystroke `validateAtPath(form, leafPath)` catches the
+     * same verdicts as a whole-form pass — no ancestor refine reads
+     * the form's wider state.
+     *
+     * The runtime uses this at the per-keystroke schedule to scope
+     * field-level validation to the changed subtree when it can,
+     * falling back to a whole-form pass when an ancestor refine
+     * (cross-field equality, sum constraints, etc.) could be moved
+     * by a leaf write. Optional. The runtime treats a missing
+     * implementation as `() => true` — conservative whole-form,
+     * preserving correctness for adapters that don't yet model
+     * container-refine detection.
+     *
+     * Detection is best-effort: false negatives (returning `true`
+     * when no container refine exists) only lose a perf win and
+     * still validate correctly; false positives (returning `false`
+     * when a container refine exists) would let an ancestor verdict
+     * go stale and are the real risk — implementations should bias
+     * toward returning `true` when in doubt.
+     */
+    hasContainerOrRootRefine?(): boolean;
 };
 /**
  * Adapter-returned info for a discriminated union — its discriminator
@@ -1308,20 +1429,24 @@ type WriteMeta = {
      */
     readonly skipDiscriminatorReshape?: boolean;
     /**
-     * Hint about an array structural mutation, set by `field-arrays.ts`
-     * helpers so `setValueAtPath` can surgically clear variant memory
-     * for 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 — don't set from consumer code.
+     * 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
+     * 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 —
+     * don't set from consumer code.
      */
     readonly arrayOp?: {
-        readonly kind: 'shift-from';
+        readonly kind: 'insert';
+        readonly index: number;
+    } | {
+        readonly kind: 'remove';
         readonly index: number;
     } | {
-        readonly kind: 'shift-range';
-        readonly fromIndex: number;
-        readonly toIndex: number;
+        readonly kind: 'move';
+        readonly from: number;
+        readonly to: number;
     } | {
         readonly kind: 'swap';
         readonly a: number;
@@ -1736,16 +1861,14 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      */
     coerce?: boolean | CoercionRegistry;
     /**
-     * Per-form override of the `shouldShowErrors` heuristic that drives
-     * `field.showErrors` and `form.meta.showErrors`. Falls back to
-     * `AttaformDefaults.shouldShowErrors`, then to the library default
-     * (`defaultShouldShowErrors`). See `AttaformDefaults.shouldShowErrors`
-     * for the resolution rules and predicate signature.
-     *
-     * Boolean shorthand: `true` → always show *when errors exist*;
-     * `false` → never show.
+     * Per-form override of the `getDisplayState` heuristic that drives
+     * `field.displayState` and the `show*` booleans (and their `form.meta`
+     * rollups). Falls back to `AttaformDefaults.getDisplayState`, then to
+     * the library default (`defaultDisplayState`). See
+     * `AttaformDefaults.getDisplayState` for the resolution rules and
+     * predicate signature.
      */
-    shouldShowErrors?: ShouldShowErrorsConfig;
+    getDisplayState?: GetDisplayState;
     /**
      * Recursion ceiling for schema walks that descend through recursive
      * schemas (Zod's `z.lazy(...)` today). Default `64`. Per-form value
@@ -1773,8 +1896,9 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
     maxRecursionDepth?: number;
     /**
      * Override the path-segment name stems treated as sensitive for this
-     * form. Sensitive paths are excluded from persistence writes,
-     * multi-tab sync broadcasts, AND the DevTools redact walk.
+     * form. Sensitive paths are excluded from persistence writes and
+     * multi-tab sync broadcasts. (DevTools renders raw values by design;
+     * it does not redact.)
      *
      * Resolution: per-form value (this field) > global default
      * (`createAttaform({ defaults: { sensitiveNames } })`) > library
@@ -1818,6 +1942,20 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * channel would be solo by construction.
      */
     multiTab?: boolean;
+    /**
+     * Whether `v-register` automatically manages aria attributes
+     * (`aria-invalid`, `aria-busy`, `aria-required`, `aria-describedby`)
+     * from the field's display state. **Defaults to `true`.**
+     *
+     * **Resolution order (per-register override > per-form > global > library):**
+     *
+     *   register(path, { autoAria })  >  useForm({ autoAria })  >  AttaformDefaults.autoAria  >  library default (`true`)
+     *
+     * Set `false` to leave all aria wiring to your own markup form-wide.
+     * Any aria attribute you author yourself is always left untouched,
+     * independent of this flag.
+     */
+    autoAria?: boolean;
     /**
      * @internal
      * SSR prefetch mark — set by the `attaform/vite` compile-time
@@ -1899,33 +2037,41 @@ type AttaformDefaults = {
      */
     coerce?: boolean | CoercionRegistry;
     /**
-     * Default for `useForm({ shouldShowErrors })`. Centralised heuristic
-     * that drives `field.showErrors` (and `form.meta.showErrors`) — a
-     * boolean that gates whether a path's errors are *ready* to render.
+     * Default for `useForm({ getDisplayState })`. The centralised
+     * heuristic that resolves every path's `field.displayState` — and thus
+     * the `show*` booleans and their `form.meta` rollups — to one of
+     * `'idle' | 'pending' | 'error' | 'success'`.
      *
      * Resolution order (per-form wins):
      *
-     *   useForm({ shouldShowErrors })  >  AttaformDefaults  >  library default
+     *   useForm({ getDisplayState })  >  AttaformDefaults  >  library default
      *
-     * The library default reads "show after the first submit attempt OR
-     * after the field has been interacted with AND changed":
+     * 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:
      *
      * ```ts
-     * (field, formMeta) =>
-     *   formMeta.submissionAttempts > 0 || (field.touched === true && field.dirty)
+     * (field, formMeta) => {
+     *   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'
+     * }
      * ```
      *
-     * Compose with the library default via the public
-     * `defaultShouldShowErrors` export. Boolean shorthand is supported:
-     * `true` → always show *when errors exist*; `false` → never show. The
-     * predicate is invoked only when `errors.length > 0`, so authors
-     * don't re-check inside.
+     * Compose with the library default via the public `defaultDisplayState`
+     * export. The predicate runs on every field-state read, so it owns the
+     * idle / pending / error / success decision outright.
      *
-     * The predicate's args are `Omit`'d of `showErrors` / `firstError`
-     * to prevent recursive predicates — those are derived FROM this
-     * predicate, so reading them inside would be a self-reference.
+     * The predicate's args are `Omit`'d of the derived `displayState` /
+     * `show*` / `firstError` keys (see `FieldStateDerivedKey`) to prevent
+     * a self-referential predicate.
      */
-    shouldShowErrors?: ShouldShowErrorsConfig;
+    getDisplayState?: GetDisplayState;
     /**
      * Default for `useForm({ maxRecursionDepth })`. Recursion ceiling
      * for schema walks that descend through recursive schemas (Zod's
@@ -1978,9 +2124,10 @@ type AttaformDefaults = {
     maxRecursionDepth?: number;
     /**
      * Override the path-segment name stems treated as sensitive.
-     * Sensitive paths are excluded from persistence writes, multi-tab
-     * sync broadcasts, AND the DevTools redact walk — one configurable
-     * source of truth across every surface.
+     * Sensitive paths are excluded from persistence writes and multi-tab
+     * sync broadcasts — one configurable source of truth across those
+     * surfaces. (DevTools renders raw values by design; it does not
+     * redact.)
      *
      * Library default is `DEFAULT_SENSITIVE_NAMES` (exported from
      * `attaform`); compose to extend:
@@ -2025,6 +2172,21 @@ type AttaformDefaults = {
      * the multi-tab-sync recipe's Security section for the threat model.
      */
     multiTab?: boolean;
+    /**
+     * App-wide default for `useForm({ autoAria })`. Library default is
+     * `true`: `v-register` keeps `aria-invalid` / `aria-busy` /
+     * `aria-required` / `aria-describedby` in sync with each field's
+     * display state out of the box.
+     *
+     * **Resolution order (per-form wins):**
+     *
+     *   useForm({ autoAria })  >  AttaformDefaults.autoAria  >  library default (`true`)
+     *
+     * Set `false` once at the plugin level to make every form manage its
+     * own aria markup. Authored aria attributes are always preserved
+     * regardless of this setting.
+     */
+    autoAria?: boolean;
 };
 /**
  * Callback invoked by `handleSubmit` after the form parses successfully.
@@ -2040,45 +2202,59 @@ type OnSubmit<Form extends GenericForm> = (form: Form) => void | Promise<void>;
  */
 type OnError = (error: ValidationError[]) => void | Promise<void>;
 /**
- * Predicate that drives `field.showErrors` (and `form.meta.showErrors`).
- * Receives the field's reactive state plus the form's reactive meta;
- * returns `true` to render the field's errors, `false` to keep them
- * hidden. The framework gates the call on `errors.length > 0`, so
- * authors don't re-check error presence inside.
- *
- * Both arguments are `Omit`'d of `showErrors` / `firstError` — those
- * are derived FROM this predicate, so reading them inside would be a
- * self-reference. The omit is enforced at the type level AND at
- * runtime: the keys literally are not present on the objects passed
- * in, so `as` casting in TS or vanilla-JS bypass cannot create a
- * cycle.
- *
- * The library default — `defaultShouldShowErrors` — is publicly
- * exported so a layered predicate can compose with it:
+ * The display-state verdict at a path: the single signal a UI needs to
+ * decide what (if anything) to surface about validation right now.
+ * Rolled up at containers and at the form root (`form.meta.displayState`).
+ *
+ * - `'idle'` — nothing to surface. Either pre-interaction (the timing
+ *   gate hasn't opened) or gate-open with no verdict worth showing.
+ * - `'pending'` — a validation run is in flight at this path; the prior
+ *   verdict is stale. Drive a spinner / "Checking…" affordance.
+ * - `'error'` — a blocking error the timing gate has cleared for display.
+ * - `'success'` — validation passed and the gate has cleared a positive
+ *   confirmation (the green-check pattern).
+ *
+ * The four `show*` booleans on `FieldState` are sugar over this enum
+ * (`showErrors === (displayState === 'error')`, and so on), so they can
+ * never contradict it.
+ */
+type DisplayState = 'idle' | 'pending' | 'error' | 'success';
+/**
+ * Keys on `FieldState` layered on FROM the display-state predicate
+ * (plus `firstError`, computed alongside them). `Omit`'d from the
+ * predicate's arguments so a predicate cannot read its own output and
+ * form a cycle — enforced at the type level AND at runtime: the base
+ * objects passed in literally lack these keys, so an `as` cast in TS
+ * or a vanilla-JS caller still can't reach them. `FieldStateBase` /
+ * `FormMetaBase` (field-state-api.ts) omit the same set in lockstep.
+ */
+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.
+ *
+ * The library default — `defaultDisplayState` — is publicly exported so
+ * a layered predicate can compose with it:
  *
  * ```ts
- * import { defaultShouldShowErrors } from 'attaform'
+ * import { defaultDisplayState } from 'attaform'
  *
  * useForm({
  *   schema,
- *   shouldShowErrors: (field, formMeta) =>
- *     field.path[0] === 'urgent' || defaultShouldShowErrors(field, formMeta),
+ *   // 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
+ *   },
  * })
  * ```
  */
-type ShouldShowErrors = (field: Omit<FieldState, 'showErrors' | 'firstError'>, formMeta: Omit<FormMeta, 'showErrors' | 'firstError'>) => boolean;
-/**
- * Configuration shape for `shouldShowErrors`. A predicate function or
- * a boolean shorthand:
- *
- * - `true` — always show errors (when any exist).
- * - `false` — never show errors.
- * - function — custom predicate, see `ShouldShowErrors`.
- *
- * Resolved through three tiers (per-form > plugin defaults > library
- * default).
- */
-type ShouldShowErrorsConfig = ShouldShowErrors | boolean;
+type GetDisplayState = (field: Omit<FieldState, FieldStateDerivedKey>, formMeta: Omit<FormMeta, FieldStateDerivedKey>) => DisplayState;
 /**
  * Submit handler returned by `handleSubmit(onSubmit, onError)`. Bind
  * it to a `<form>`:
@@ -2162,7 +2338,7 @@ type MetaTrackerValue = {
      */
     blank: boolean;
 };
-type RegisterFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArray<Form> extends true ? Key extends string ? Form[Key] extends infer Value ? Value extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}.${RegisterFlatPath<ArrayItem>}` : `${Key}` | `${Key}.${number}` : Value extends GenericForm ? `${Key}.${RegisterFlatPath<Value>}` : `${Key}` : never : Key extends number ? `${Key}` | (Form[Key] extends GenericForm ? `${Key}.${RegisterFlatPath<Form[Key]>}` : Form[Key] extends Array<infer ArrayItem> ? IsObjectOrArray<ArrayItem> extends true ? `${Key}.${number}.${RegisterFlatPath<ArrayItem>}` : `${Key}` | `${Key}.${number}` : never) : never : never;
+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
  * from DOM through the directive's assigner. Composes left-to-right
@@ -2268,9 +2444,10 @@ type RegisterOptions = {
      * If multiple inputs bind to the same path, the path keeps
      * persisting as long as any opted-in input is mounted.
      *
-     * Throws `SensitivePersistFieldError` when the path looks
-     * sensitive (password / cvv / ssn / token / etc.) unless
-     * `acknowledgeSensitive: true` is also set.
+     * When the path looks sensitive (password / cvv / ssn / token /
+     * etc.) the opt-in is skipped with a one-shot dev warning unless
+     * `acknowledgeSensitive: true` is also set — the field simply isn't
+     * persisted (the secure default). It never throws.
      */
     persist?: boolean;
     /**
@@ -2330,6 +2507,22 @@ type RegisterOptions = {
      * instead — see the "Custom assigners" section in the API docs.
      */
     transforms?: ReadonlyArray<RegisterTransform>;
+    /**
+     * Per-binding override for automatic aria management, the narrowest
+     * tier of the `autoAria` cascade. By default the directive keeps
+     * `aria-invalid` / `aria-busy` / `aria-required` / `aria-describedby`
+     * in sync with the field's display state. Pass `autoAria: false` to
+     * leave every aria attribute on this element to you (the directive
+     * still manages value binding and registration), or `autoAria: true`
+     * to re-enable management on one binding even when the form set
+     * `useForm({ autoAria: false })`.
+     *
+     * Overrides `useForm({ autoAria })` and
+     * `createAttaform({ defaults: { autoAria } })`. Writing an aria
+     * attribute yourself also locks the directive out of that one
+     * attribute, regardless of this flag.
+     */
+    autoAria?: boolean;
 };
 /**
  * The object returned by `form.register(path)`. Pass it to a native
@@ -2439,7 +2632,7 @@ type RegisterValue<Value = unknown> = Readonly<{
     /**
      * Resolved sensitive-path predicate honoring this form's
      * `sensitiveNames` cascade. The directive calls this through
-     * `enforceSensitiveCheck` when a `register('path', { persist: true })`
+     * `allowSensitivePersist` when a `register('path', { persist: true })`
      * binding mounts so a per-form custom list (e.g. extending with
      * `'mrn'`) gates persistence enrolment correctly.
      * @internal
@@ -2530,6 +2723,16 @@ type RegisterValue<Value = unknown> = Readonly<{
      * @internal
      */
     markBlank: () => boolean;
+    /**
+     * Flip this field's sticky `interacted` flag — the signal that the
+     * user has issued at least one value edit here (an insert or a
+     * delete). Called by the directive's input / change listeners on
+     * every genuine user input; never by hydration or programmatic
+     * writes. Idempotent (the store skips the write once set). Don't
+     * call from consumer code.
+     * @internal
+     */
+    markInteracted: () => void;
     /**
      * `true` when the schema's slim primitive set at this path includes
      * `'undefined'` — i.e. the leaf was declared `.optional()` (or as
@@ -2561,6 +2764,42 @@ type RegisterValue<Value = unknown> = Readonly<{
      * @internal
      */
     acceptsString: boolean;
+    /**
+     * The field's aria satellite ids, mirroring `FieldState.aria`. The
+     * directive points `aria-describedby` at `errorId` while the field
+     * is in its error state. Optional so hand-rolled `RegisterValue`
+     * mocks don't have to declare it; the directive skips aria wiring
+     * when absent.
+     * @internal
+     */
+    aria?: {
+        readonly errorId: string;
+        readonly descriptionId: string;
+    };
+    /**
+     * Whether the schema marks this path required, from
+     * `schema.isRequiredAtPath(segments)`. Drives `aria-required`.
+     * Optional for the same mock-tolerance reason as `aria`.
+     * @internal
+     */
+    isRequired?: boolean;
+    /**
+     * Whether the directive should auto-manage aria attributes for this
+     * binding. Resolves the per-register `autoAria` override against the
+     * form-level value: `options.autoAria ?? formAutoAria`. The directive
+     * treats an absent value as off.
+     * @internal
+     */
+    ariaEnabled?: boolean;
+    /**
+     * The gated display-state verdict for this path, reusing the same
+     * field-state identity as `form.fields`. The directive watches it to
+     * keep `aria-invalid` / `aria-busy` / `aria-describedby` in lockstep
+     * with the visible error state, even on async ticks with no parent
+     * re-render. Optional; the directive skips aria wiring when absent.
+     * @internal
+     */
+    ariaDisplayState?: Readonly<Ref<DisplayState>>;
 }>;
 /**
  * Custom assigner installed on an element via the directive's
@@ -2876,6 +3115,32 @@ type FieldState<Value = unknown> = {
     readonly focused: boolean | null;
     readonly blurred: boolean | null;
     readonly touched: boolean;
+    /**
+     * `true` once the user has issued at least one value edit on this
+     * field through `v-register` (an insert or a delete), sticky
+     * thereafter and preserved across disconnects. Distinct from
+     * `dirty`: typing `"a"` then deleting it back to empty leaves the
+     * field net-unchanged (`dirty: false`) yet `interacted: true`.
+     * Distinct from `touched`: tabbing through a field without editing
+     * flips `touched` but never `interacted`. Set only by user input,
+     * never by hydration or programmatic `setValue`; cleared by
+     * `form.reset()` / `form.resetField(path)`. Containers roll it up as
+     * a disjunction (any descendant interacted).
+     */
+    readonly interacted: boolean;
+    /**
+     * `true` once the user has blurred this field after editing it: the
+     * first time they edit a value and then leave. Sticky thereafter and
+     * preserved across disconnects; a tab-through with no edit never sets
+     * it (`interacted` is still false at that blur). It composes
+     * `interacted` with the departure and drives the default display gate,
+     * so errors reveal once the user finishes a pass and leaves, then stay
+     * visible through a re-focus to be fixed live. Set only by user
+     * input/blur, never by hydration or programmatic writes; cleared by
+     * `form.reset()` / `form.resetField(path)`. Containers roll it up as a
+     * disjunction.
+     */
+    readonly blurredAfterInteraction: boolean;
     readonly connected: boolean;
     /**
      * The first DOM element bound to this path via `v-register`, or
@@ -2932,9 +3197,29 @@ type FieldState<Value = unknown> = {
      */
     readonly valid: boolean;
     /**
-     * Centralised "should I render this field's errors right now?"
-     * gate. Wraps `errors.length > 0 && shouldShowErrors(field, formMeta)`
-     * so templates avoid re-spelling the heuristic at every error site:
+     * The single display-state verdict at this path: `'idle'`,
+     * `'pending'`, `'error'`, or `'success'`. The source of truth the
+     * four `show*` booleans below derive from. Bind it directly when one
+     * branch over the set reads cleaner than four flags:
+     *
+     * ```vue
+     * <FieldStatusIcon :state="form.fields.email.displayState" />
+     * ```
+     *
+     * Resolved by the `getDisplayState` heuristic:
+     * `useForm({ getDisplayState })` →
+     * `createAttaform({ defaults: { getDisplayState } })` → library
+     * default (`defaultDisplayState`). Override per form, app-wide, or
+     * compose with `defaultDisplayState` for a layered predicate.
+     *
+     * Available on container paths too: `form.fields.users[0].displayState`
+     * rolls up over the row's descendants.
+     */
+    readonly displayState: DisplayState;
+    /**
+     * `displayState === 'error'`. The centralised "render this field's
+     * errors right now?" gate, so templates avoid re-spelling the
+     * heuristic at every error site:
      *
      * ```vue
      * <span v-if="form.fields.email.showErrors">
@@ -2942,20 +3227,29 @@ type FieldState<Value = unknown> = {
      * </span>
      * ```
      *
-     * The heuristic itself comes from `useForm({ shouldShowErrors })` →
-     * `createAttaform({ defaults: { shouldShowErrors } })` → library
-     * default (`defaultShouldShowErrors` — show after first submit OR
-     * after touched-and-dirty). Override per form, app-wide, or
-     * compose with `defaultShouldShowErrors` for a layered predicate.
-     *
-     * Falls back to `false` whenever there are no errors — the gate
-     * skips the predicate entirely in that case.
-     *
-     * Available on container paths too: `form.fields.users[0].showErrors`
-     * aggregates over the row's descendants (any descendant with a
-     * qualifying error flips the container on).
+     * Kept plural to match `errors` / `firstError`. On container paths it
+     * rolls up over descendants (any descendant resolving to `'error'`
+     * flips the container on).
      */
     readonly showErrors: boolean;
+    /**
+     * `displayState === 'pending'`. A per-field validation run is in
+     * flight at this path and the prior verdict is stale; drive a spinner
+     * or a "Checking…" affordance.
+     */
+    readonly showPending: boolean;
+    /**
+     * `displayState === 'success'`. Validation has passed and the timing
+     * gate has cleared a positive confirmation; drive the green-check
+     * pattern.
+     */
+    readonly showSuccess: boolean;
+    /**
+     * `displayState === 'idle'`. Nothing to surface yet — pre-interaction,
+     * or gate-open with no verdict worth showing. Read it to suppress
+     * helper text the moment any other signal takes over.
+     */
+    readonly showIdle: boolean;
     /**
      * The first `ValidationError` at this path in the deterministic
      * schema-declaration order — equivalent to `errors[0]`, exposed as
@@ -2977,6 +3271,53 @@ type FieldState<Value = unknown> = {
      */
     readonly firstError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
+    /**
+     * Stable, SSR-safe DOM id for this field, unique across every mount
+     * on the page. Derived from the form's key and this path, folded with
+     * the form's per-mount `instanceId` so two simultaneous mounts of the
+     * same keyed form never collide. Bind it to wire a label and its
+     * input without inventing your own id:
+     *
+     * ```vue
+     * <label :for="form.fields.email.id">Email</label>
+     * <input :id="form.fields.email.id" v-register="form.register('email')" />
+     * ```
+     *
+     * Treat as identity, not state: stable for the path across the form's
+     * lifetime, opaque, not meant to be parsed.
+     */
+    readonly id: string;
+    /**
+     * Satellite ids derived from {@link id} for the elements that
+     * describe this field. Wire them to an error node and a description
+     * node so assistive tech announces them with the input. The
+     * `v-register` directive points `aria-describedby` at `errorId`
+     * automatically while the field is in its error state; you render the
+     * matching element and id it:
+     *
+     * ```vue
+     * <input v-register="form.register('email')" />
+     * <span :id="form.fields.email.aria.errorId" v-if="form.fields.email.showErrors">
+     *   {{ form.fields.email.firstError?.message }}
+     * </span>
+     * ```
+     *
+     * `descriptionId` is for opt-in help text; chain it into your own
+     * `aria-describedby` when you render a persistent description element.
+     */
+    readonly aria: {
+        readonly errorId: string;
+        readonly descriptionId: string;
+    };
+    /**
+     * Stable identity for this field as an element of its parent array,
+     * suitable as a Vue `:key` when iterating array elements. An allocated
+     * token (not derived from the element's value) that follows the
+     * element across inserts, removals, moves, and swaps, so a row keeps
+     * its component instance across a reorder. Empty for fields that are
+     * not array elements. Treat as opaque identity, not state.
+     */
+    readonly key: string;
     readonly blank: boolean;
     /**
      * Presentational label for this field. Resolves through the
@@ -3422,8 +3763,8 @@ type FormMeta<F = unknown> = FieldState<F> & {
      *
      * Pure introspection counter — useful for "this form has been
      * visited and left" UX (analytics, prior-step badges, layered
-     * `shouldShowErrors` predicates) but does NOT drive the library's
-     * default `shouldShowErrors` heuristic. The reveal-on-submit story
+     * `getDisplayState` predicates) but does NOT drive the library's
+     * default `getDisplayState` heuristic. The reveal-on-submit story
      * runs entirely through `submissionAttempts`, which
      * `wizard.handleSubmit` bumps on the active form at intermediate
      * steps and on every form at the final step.
@@ -4110,9 +4451,9 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * paths in the persisted draft are preserved (this is a merge,
      * not a replace).
      *
-     * Throws `SensitivePersistFieldError` for sensitive-looking paths
-     * unless you pass `{ acknowledgeSensitive: true }`. No-op when
-     * `useForm({ persist })` wasn't configured.
+     * For sensitive-looking paths, warns once and no-ops unless you pass
+     * `{ acknowledgeSensitive: true }` — it never throws. Also a no-op
+     * when `useForm({ persist })` wasn't configured.
      */
     persist: (path: FlatPath<Form>, options?: {
         acknowledgeSensitive?: boolean;
@@ -4217,6 +4558,48 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     move: <Path extends ArrayPath<Form>>(path: Path, from: number, to: number) => void;
     /** Replace the element at `index` with `value`. No-op when out of range. */
     replace: <Path extends ArrayPath<Form>>(path: Path, index: number, value: ArrayItem<Form, Path>) => void;
+    /**
+     * Read-only, reactive view of the array at `path` as one `FieldState`
+     * per element, in index order. Each entry carries its element `key`,
+     * an allocated identity token, so a `v-for` keyed by it keeps a row's
+     * component instance across an insert, removal, move, or swap:
+     *
+     * ```vue
+     * <div v-for="(row, i) in form.list('contacts')" :key="row.key">
+     *   <input v-register="form.register(`contacts.${i}.name`)" />
+     *   <p v-if="row.showErrors">{{ row.firstError?.message }}</p>
+     * </div>
+     * ```
+     *
+     * Entries are the same field states `form.fields` exposes, so reads
+     * stay live. `form.fields(path)` remains the single aggregated
+     * container for the whole array; `list` is the per-element view.
+     * For a record, reach for `record`, which keys each entry by its own
+     * key.
+     */
+    list: <Path extends ArrayPath<Form>>(path: Path) => readonly FieldState<ArrayItem<Form, Path>>[];
+    /**
+     * Read-only, reactive view of the record at `path` as one `FieldState`
+     * per entry, keyed by the entry's own key. Where `list` hands back an
+     * ordered array for an array path, `record` hands back a keyed object
+     * for a record path, so you iterate it by key:
+     *
+     * ```vue
+     * <div v-for="(field, key) in form.record('scoresByTeam')" :key="key">
+     *   <label>{{ key }}</label>
+     *   <input v-register="form.register(`scoresByTeam.${key}`)" />
+     *   <p v-if="field.showErrors">{{ field.firstError?.message }}</p>
+     * </div>
+     * ```
+     *
+     * Entries are the same field states `form.fields` exposes, so reads
+     * stay live, and the keyed shape mirrors the record's own keys: an
+     * entry appears once you write its key (`form.setValue`) and drops
+     * when the key leaves. `form.fields(path)` remains the single
+     * aggregated container for the whole record; `record` is the
+     * per-entry view.
+     */
+    record: <Path extends RecordPath<Form>>(path: Path) => Readonly<Record<string, FieldState<RecordValue<Form, Path>>>>;
     /**
      * Read-only view of the form's blank path set. Reactive — Vue 3.5
      * tracks `.has()` / `for..of` / size accesses, so consumers can drive
@@ -4244,5 +4627,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as Y, ROOT_PATH_KEY as Z, canonicalizePath as as, isPathPrefix as at, isUnset as au, parseDottedPath as av, unset as aw };
-export type { RegisterDirective as $, AbstractSchema as A, OnSubmit 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, PartialFlatPath as P, Path as Q, PathKey as R, PendingValidationStatus as S, PersistConfig as T, PersistConfigOptions as U, PersistIncludeMode as V, PersistOptInRegistry as W, Primitive as X, ReactiveValidationStatus as _, ApiErrorDetails as a, RegisterFlatPath as a0, RegisterModelDynamicCustomDirective as a1, RegisterOptions as a2, RegisterSelectModifier as a3, RegisterTextModifier as a4, RegisterTransform as a5, RegisterValue as a6, SchemaFactoryOptions as a7, Segment as a8, SetValueCallback as a9, SetValuePayload as aa, SettledValidationStatus as ab, ShouldShowErrors as ac, ShouldShowErrorsConfig 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, FieldState as m, FieldStateMap as n, FieldStateMapEntry as o, FlatPath as p, FormErrorRecord as q, FormErrorsSurface as r, FormKey as s, FormMeta as t, FormStorage as u, FormStorageKind as v, HistoryConfig as w, IsUnion as x, NestedType as y, OnInvalidSubmitPolicy as z };
+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 };