attaform 0.19.0 → 0.20.1

package/dist/shared/{attaform.C0uGZQ4M.d.ts → 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 /
@@ -388,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
@@ -401,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:
@@ -413,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
@@ -713,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;
     /**
@@ -1092,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
@@ -1795,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
@@ -2022,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:
@@ -2235,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
@@ -2341,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;
     /**
@@ -2528,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
@@ -4347,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;

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

@@ -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 /
@@ -388,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
@@ -401,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:
@@ -413,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
@@ -713,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;
     /**
@@ -1092,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
@@ -1795,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
@@ -2022,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:
@@ -2235,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
@@ -2341,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;
     /**
@@ -2528,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
@@ -4347,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;