attaform 0.28.0 → 0.30.0

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

@@ -359,6 +359,48 @@ type JoinSegments<S extends ReadonlyArray<string | number>, Acc extends string =
     infer Head extends string | number,
     ...infer Rest extends ReadonlyArray<string | number>
 ] ? Acc extends '' ? JoinSegments<Rest, `${Head}`> : JoinSegments<Rest, `${Acc}.${Head}`> : Acc;
+/**
+ * The advice half of a segment-array rejection, used when `S` never
+ * inferred a tuple at all.
+ *
+ * A caller who passes a plain `string` reaches this branch, because
+ * inference falls back to the constraint and `JoinSegments` of a
+ * non-tuple array is `''`. Naming a path would be a lie there, so the
+ * message names the remedies instead. This is the case behind #568: a
+ * row component received its path prefix as an untyped `string` prop,
+ * every concatenation widened to `string`, and the only signal was
+ * `segments: never`.
+ */
+type PlainStringAdvice = 'attaform: a plain string cannot be checked against the schema. Pass a literal path, type the dynamic prefix, or use the segment-array form.';
+/**
+ * Why a segment array was rejected, as a type the compiler prints.
+ *
+ * Every segment-array overload brands its parameter
+ * `S & (<joined path is valid> ? unknown : <this>)`. The brand used to
+ * be `never`, and `S & never` is `never`, so TypeScript reported the
+ * parameter as `never` and said nothing about what was wrong. A string
+ * literal intersects without collapsing, so the sentence survives into
+ * the diagnostic and the argument keeps its inferred tuple type:
+ *
+ * ```
+ * Argument of type '["boxes", 3, "nope"]' is not assignable to parameter
+ * of type 'readonly ["boxes", 3, "nope"] &
+ *   "attaform: 'boxes.3.nope' is not a path in this form's schema"'.
+ * ```
+ *
+ * Nothing can satisfy the brand, so a wrong path is still a compile
+ * error; only the message changes.
+ */
+type SegmentPathRejection<Joined extends string> = [Joined] extends [''] ? PlainStringAdvice : `attaform: '${Joined}' is not a path in this form's schema`;
+/**
+ * `SegmentPathRejection` for `register`, whose accepted set is
+ * `RegisterFlatPath` rather than `FlatPath`.
+ *
+ * The distinction is worth its own sentence: a container path is in the
+ * schema and still not registrable, so "not a path in this form's
+ * schema" would be false where it is most likely to be read.
+ */
+type SegmentRegisterRejection<Joined extends string> = [Joined] extends [''] ? PlainStringAdvice : `attaform: '${Joined}' is not a registrable path. v-register binds a leaf input, so container paths are excluded.`;
 /**
  * `true` when `T` is a union (multiple members), `false` when it's a
  * single type. Used to gate non-homomorphic mapped-type forms so
@@ -523,44 +565,89 @@ type IsTuple<T extends readonly unknown[]> = number extends T['length'] ? false
  * runtime possibility of a missing array position.
  */
 type NestedReadType<RootValue, FlattenedPath extends string> = NestedTypeBuilder<RootValue, FlattenedPath, true>;
+/**
+ * The array a path actually addresses, nullish stripped, or `never`
+ * when the path does not address an array. Shared by `ArrayPath`
+ * (membership) and `ArrayItem` (element type) so the filter and the
+ * extractor cannot disagree about what counts as one.
+ *
+ * The strip is the load-bearing part. `Form` is the schema's INPUT
+ * shape, so `z.array(row).default([])` resolves to `row[] | undefined`,
+ * and `NestedType` tags a discriminated union's per-variant keys the
+ * same way on purpose: that tagging is what keeps `NestedType` in
+ * lockstep with `FlatPath`, so every path `FlatPath` offers resolves to
+ * a useful value type. A bare `extends readonly unknown[]` predicate
+ * read the tag as "not an array", which is how every optional,
+ * defaulted, nullable, and DU-variant array fell out of the field-array
+ * helpers while the runtime went on accepting all of them (#541).
+ *
+ * `extends infer Leaf` binds the stripped leaf once so the guards below
+ * do not re-instantiate `NestedType`, and the tuple wraps suppress
+ * distribution so a union leaf is judged whole: `A[] | B[]` is an
+ * array, `A[] | string` is not.
+ *
+ * Exported so `rollup-plugin-dts` keeps it as a named alias in the
+ * bundled `.d.ts` instead of inlining the body at every reference.
+ * Consumers reach for `ArrayPath` / `ArrayItem`; this alias is not part
+ * of the stable surface.
+ */
+type ArrayLeafOf<Form, P extends string> = Exclude<NestedType<Form, P>, undefined | null> extends infer Leaf ? [Leaf] extends [never] ? never : [Leaf] extends [readonly unknown[]] ? Leaf : never : never;
 /**
  * Filter FlatPath<Form> down to the subset of paths whose resolved leaf
  * is an array. Used by the typed field-array helpers (append / remove /
  * swap / ...) so those helpers only accept paths that actually address
  * an array — calling `append('email', ...)` on a `{ email: string }`
- * is a compile error.
+ * is a compile error. Optionality is not a disqualifier; see
+ * `ArrayLeafOf` for what "is an array" means here.
  *
  * `P extends string` re-triggers distribution over the `FlatPath<Form>`
  * union so the conditional evaluates per member. Without it, the
  * branch would reduce against the union as a whole and collapse to
  * `never` whenever a single member failed the predicate.
  */
-type ArrayPath<Form, P extends FlatPath<Form> = FlatPath<Form>> = P extends string ? NestedType<Form, P> extends readonly unknown[] ? P : never : never;
+type ArrayPath<Form, P extends FlatPath<Form> = FlatPath<Form>> = P extends string ? [ArrayLeafOf<Form, P>] extends [never] ? never : P : never;
 /**
  * Extract the element type of the array addressed by `Path`. Callers
  * constrain `Path extends ArrayPath<Form>` so this is always well-defined.
+ * Rides on `ArrayLeafOf`, the same alias `ArrayPath` admits the path
+ * with, so an accepted path never hands its helper a `never` value slot.
+ */
+type ArrayItem<Form, Path extends ArrayPath<Form>> = ArrayLeafOf<Form, Path> extends ReadonlyArray<infer Item> ? Item : never;
+/**
+ * The record a path actually addresses, nullish stripped, or `never`
+ * when the path does not address one. Shared by `RecordPath`
+ * (membership) and `RecordValue` (value type).
+ *
+ * `string extends keyof Leaf` 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.
+ *
+ * Nullish is stripped first for the reason `ArrayLeafOf` gives, with an
+ * extra bite here: `keyof (Record<string, V> | undefined)` is `never`,
+ * so on a `.default({})` or `.optional()` record the probe could not
+ * fire at all and `form.record(path)` rejected the path (#541).
+ *
+ * Exported for the same `.d.ts` reason as `ArrayLeafOf`, and equally
+ * not part of the stable surface.
  */
-type ArrayItem<Form, Path extends ArrayPath<Form>> = NestedType<Form, Path> extends ReadonlyArray<infer Item> ? Item : never;
+type RecordLeafOf<Form, P extends string> = Exclude<NestedType<Form, P>, undefined | null> extends infer Leaf ? [Leaf] extends [never] ? never : [Leaf] extends [readonly unknown[]] ? never : [Leaf] extends [Record<string, unknown>] ? string extends keyof Leaf ? Leaf : never : never : 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;
+type RecordPath<Form, P extends FlatPath<Form> = FlatPath<Form>> = P extends string ? [RecordLeafOf<Form, P>] extends [never] ? never : P : 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.
+ * well-defined. Rides on `RecordLeafOf`, the same alias `RecordPath`
+ * admits the path with, so the two cannot disagree.
  */
-type RecordValue<Form, Path extends RecordPath<Form>> = NestedType<Form, Path> extends Record<string, infer Value> ? Value : never;
+type RecordValue<Form, Path extends RecordPath<Form>> = RecordLeafOf<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."
@@ -751,12 +838,12 @@ type AcceptableDefaultsOf<DVI, SchemaInput> = DVI | SchemaInput | (() => DVI | S
 type FormKey = string;
 /**
  * Per-form options threaded from `useForm` into the adapter factory.
- * Today carries the resolved `maxRecursionDepth` so adapter walks can
- * cap their descent through recursive schemas; future per-form runtime
- * knobs land here too.
+ * Today carries `maxRecursionDepth` so adapter walks can cap their
+ * descent through recursive schemas; future per-form runtime knobs
+ * land here too.
  */
 interface SchemaFactoryOptions {
-    /** Resolved recursion ceiling (per-form > app-default > library default). */
+    /** Recursion ceiling for walks through recursive schemas. */
     maxRecursionDepth: number;
 }
 /**
@@ -861,27 +948,49 @@ type ErrorInput = Error | {
     code?: string;
     data?: Json | null;
 };
-/** Settled validation result when the form (or subtree) parsed successfully. */
-type ValidationResponseSuccess<TData> = {
+/**
+ * A parse verdict as an `AbstractSchema` produces it.
+ *
+ * A schema knows nothing about which form asked: it is a pure function
+ * of the schema it wraps, which is what lets one `AbstractSchema` serve
+ * every form built on the same schema. The owning store stamps its own
+ * `formKey` on the way out, producing the `ValidationResponse*` arms
+ * below. Adapter authors implement THESE.
+ */
+type SchemaParseSuccess<TData> = {
     /** The parsed value at the validated subtree (whole form when `validate()` was called without a path). */
     data: TData;
     errors: undefined;
     success: true;
-    formKey: FormKey;
 };
-/** Settled validation result when no data could be produced (e.g. a top-level type mismatch). */
-type ValidationResponseErrorWithoutData = {
+/** Schema-level verdict when no data could be produced (e.g. a top-level type mismatch). */
+type SchemaParseErrorWithoutData = {
     data: undefined;
     /** Non-empty list of failures. */
     errors: ValidationError[];
     success: false;
-    formKey: FormKey;
 };
-/** Settled validation result when the parser produced partial data alongside failures. */
-type ValidationResponseErrorWithData<TData> = {
+/** Schema-level verdict when the parser produced partial data alongside failures. */
+type SchemaParseErrorWithData<TData> = {
     data: TData;
     errors: ValidationError[];
     success: false;
+};
+/** Settled schema-level verdict. Discriminate on `success`. */
+type SchemaParseResult<TData> = SchemaParseSuccess<TData> | SchemaParseErrorWithData<TData> | SchemaParseErrorWithoutData;
+/** Schema-level `getDefaultValues` verdict: defaults always come back. */
+type SchemaDefaultsResult<TData> = SchemaParseSuccess<TData> | SchemaParseErrorWithData<TData>;
+/** Settled validation result when the form (or subtree) parsed successfully. */
+type ValidationResponseSuccess<TData> = SchemaParseSuccess<TData> & {
+    /** The form this verdict belongs to. Stamped by the store, not the schema. */
+    formKey: FormKey;
+};
+/** Settled validation result when no data could be produced (e.g. a top-level type mismatch). */
+type ValidationResponseErrorWithoutData = SchemaParseErrorWithoutData & {
+    formKey: FormKey;
+};
+/** Settled validation result when the parser produced partial data alongside failures. */
+type ValidationResponseErrorWithData<TData> = SchemaParseErrorWithData<TData> & {
     formKey: FormKey;
 };
 /**
@@ -896,12 +1005,6 @@ type ValidationResponseErrorWithData<TData> = {
  * ```
  */
 type ValidationResponse<TData> = ValidationResponseSuccess<TData> | ValidationResponseErrorWithData<TData> | ValidationResponseErrorWithoutData;
-/**
- * Result of resolving the form's default values. Always returns at
- * least the shape derived from the schema; `errors` carry any
- * failures from validating those defaults against the schema.
- */
-type DefaultValuesResponse<TData> = ValidationResponseSuccess<TData> | ValidationResponseErrorWithData<TData>;
 /**
  * Trimmed `ValidationResponse` that omits the `data` payload. Used by
  * the reactive `validate()` status, whose consumers only need the
@@ -949,21 +1052,13 @@ type ValidateOptions = {
 /**
  * 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.
+ * empty/falsy fallbacks) 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;
-    /**
-     * Whether to keep schema refinements when deriving slim defaults.
-     * `true` (default) — preserve refinements; `false` — strip them so
-     * placeholder data lands without immediate construction-time
-     * errors. Mirrors `useForm({ strict })`.
-     */
-    strict?: boolean;
     constraints?: DeepPartial<WriteShape<Form>> | undefined;
 };
 /**
@@ -977,45 +1072,7 @@ type GetDefaultValuesConfig<Form> = {
  * adding support for a new schema library (Valibot, ArkType, custom).
  */
 type AbstractSchema<Form, GetValueFormType> = {
-    /**
-     * Structural fingerprint of the schema. Same shape → same string;
-     * different shape → (best-effort) different string.
-     *
-     * Resolves a `Promise` so adapters can defer the structural walk (and
-     * its `canonicalStringify` helper) onto a dynamic import. The framework
-     * only ever needs the fingerprint for the dev-only shared-key schema
-     * mismatch warning, so none of those bytes belong on the eager
-     * `useForm` path.
-     *
-     * The library uses this to detect schema mismatches at a shared
-     * form key: two `useForm({ key: 'x', schema })` calls are allowed
-     * to land on the same `FormStore` (the "shared store" semantic),
-     * but only when their schemas agree. If the second call's
-     * fingerprint differs from the first's, the library emits a
-     * dev-mode warning — the first call's schema stays canonical and
-     * the second call's schema is silently ignored.
-     *
-     * Guarantees adapter authors should provide:
-     * - **Determinism:** equal shapes at different memory addresses
-     *   must produce the same fingerprint. Referential equality fails
-     *   99% of the time across files, so reference-identity is not a
-     *   substitute.
-     * - **Key-order-insensitivity** for record-like shapes (object,
-     *   struct) — two shapes with the same keys but different iteration
-     *   order must match.
-     * - **Order-insensitivity for unbounded unions** — `a | b` and
-     *   `b | a` must match (the set of members is what matters, not
-     *   their source order).
-     *
-     * Compromises adapter authors may accept:
-     * - Function-valued metadata (refinements, transforms, lazy
-     *   defaults) is not stably hashable. Represent it as an opaque
-     *   sentinel; two schemas differing only in refinement logic will
-     *   look identical. The warning is a footgun catcher, not a
-     *   soundness guarantee.
-     */
-    fingerprint(): Promise<string>;
-    getDefaultValues(config: GetDefaultValuesConfig<Form>): DefaultValuesResponse<Form>;
+    getDefaultValues(config: GetDefaultValuesConfig<Form>): SchemaDefaultsResult<Form>;
     /**
      * Return the schema-prescribed default value at the given path. The
      * runtime uses this to fill structural gaps so every `setValue` write
@@ -1088,6 +1145,28 @@ type AbstractSchema<Form, GetValueFormType> = {
      * the result by canonicalized path key.
      */
     isPreprocessOrCoerceLeaf(path: Path): boolean;
+    /**
+     * Reports whether `path` resolves to an opaque leaf: a schema that
+     * declares a value without describing its shape. In Zod v4 that's
+     * `z.any()`, `z.unknown()`, and `z.custom(...)` (the kind both
+     * `z.instanceof(X)` and `z.custom<T>()` compile to); in Zod v3 it's
+     * `z.any()` / `z.unknown()`, with `z.instanceof(X)` peeling through
+     * `ZodEffects` to `ZodAny`.
+     *
+     * Consulted by the slim-primitive write gate. An opaque leaf admits
+     * every kind, INCLUDING containers, and it declares no sub-paths.
+     * Without this the gate accepts an array at the leaf and then walks
+     * into it, checking `files.0` against a schema that never declared
+     * that path; the empty accept set there reads as "not in your
+     * schema" and no-ops the whole write (#542).
+     *
+     * Exact-path semantic, unlike `isPreprocessOrCoerceLeaf`: it answers
+     * for the node at `path` only. Descendants stay unwritable on their
+     * own, because the schema genuinely does not declare them and
+     * fabricating them would put phantom nodes on `form.fields`. Writing
+     * the whole value at the opaque leaf is the supported move.
+     */
+    isOpaqueLeafAtPath(path: Path): boolean;
     /**
      * Distinguish a tuple (fixed-length, position-typed) from an
      * unbounded array at `path`. The runtime calls this on every
@@ -1133,6 +1212,29 @@ type AbstractSchema<Form, GetValueFormType> = {
      * `false`.
      */
     isFixedObjectAtPath(path: Path): boolean;
+    /**
+     * How the container at `path` spells the keys of its own entries:
+     * `'number'` for an array or a tuple, `'string'` for an object or a
+     * record, and for a `z.map` the kind its declared key type accepts.
+     * `undefined` for anything else, a leaf and an undeclared path
+     * included.
+     *
+     * The write walkers consult it at a `Map`, where a new entry has to
+     * be filed under a key of the declared type and the path segment
+     * alone cannot say which: an integer-looking segment canonicalises
+     * to a number, so `scores.42` against a `z.map(z.string(), V)` would
+     * otherwise take the number `42` as its key and fail the map's own
+     * parse. An entry the map already holds needs no ruling — its
+     * existing key wins.
+     *
+     * A map whose key type is neither string-ish nor number-ish, or
+     * which admits both, reports `undefined`: no segment can spell such
+     * a key, so the map stays a whole value with no addressable entries.
+     *
+     * Adapters MAY cache per path; the runtime calls this on the write
+     * path.
+     */
+    entryKeyKindAtPath(path: Path): 'string' | 'number' | undefined;
     /**
      * Return every sub-schema that could resolve at the given structured
      * path. Multiple results are only expected for discriminated / union
@@ -1170,7 +1272,7 @@ type AbstractSchema<Form, GetValueFormType> = {
      * returned as a `success: false` response with a populated
      * `errors` array.
      */
-    validateAtPath(data: unknown, path: Path | undefined, options?: ValidateOptions): MaybePromise<ValidationResponse<GetValueFormType>>;
+    validateAtPath(data: unknown, path: Path | undefined, options?: ValidateOptions): MaybePromise<SchemaParseResult<GetValueFormType>>;
     /**
      * Sync sister to `getSchemasAtPath` / `validateAtPath`. Returns the
      * set of primitive `typeof`-style kinds the path's leaf schema
@@ -1201,11 +1303,14 @@ type AbstractSchema<Form, GetValueFormType> = {
      * - For nullable / optional wrappers: adds `'null'` / `'undefined'`
      *   to the inner's set.
      */
-    getSlimPrimitiveTypesAtPath(path: Path): Set<SlimPrimitiveKind>;
+    getSlimPrimitiveTypesAtPath(path: Path): ReadonlySet<SlimPrimitiveKind>;
     /**
-     * Return `true` iff `path` resolves to a **leaf** in the schema — a
-     * path whose slim primitive set contains only primitive kinds (no
-     * `object`, `array`, `map`, `set`). The runtime proxies (`form.values`,
+     * Return `true` iff `path` resolves to a **leaf** in the schema: a
+     * path the schema declares no sub-paths under. That is every path
+     * whose slim primitive set contains only primitive kinds (no
+     * `object`, `array`, `map`, `set`), plus the opaque leaves, which
+     * admit every kind and are classified by kind instead (below). The
+     * runtime proxies (`form.values`,
      * `form.errors`, `form.fields`) query this at every step to decide
      * between **descend into a sub-proxy** (container) and **terminate
      * with a leaf value** (leaf).
@@ -1223,6 +1328,14 @@ type AbstractSchema<Form, GetValueFormType> = {
      *   date/function) → `true`. `'date'` counts as a leaf (don't drill
      *   into `Date`). `'function'` is a leaf for the same reason — opaque
      *   value.
+     * - **Opaque leaf** (`z.any()`, `z.unknown()`, `z.custom()`, and the
+     *   `z.instanceof(X)` that compiles to it) → `true`, and it answers
+     *   ahead of the kind test. An opaque leaf admits every kind
+     *   INCLUDING the container ones, so reading it off the slim
+     *   primitive set alone classifies it as a container and puts
+     *   phantom nodes under it on `form.fields` — see
+     *   `isOpaqueLeafAtPath`. What leafness asks is whether the schema
+     *   declares sub-paths here, and an opaque leaf declares none.
      * - **Optional / Nullable / Default / Catch** wrappers transparent —
      *   adds `'null'` / `'undefined'` to the inner kind set without
      *   changing the leaf classification.
@@ -1470,38 +1583,6 @@ type SettledValidationStatus<Form> = {
  * `pending` to switch between in-flight and settled states.
  */
 type ReactiveValidationStatus<Form> = PendingValidationStatus | SettledValidationStatus<Form>;
-/**
- * What to do when a submit attempt fails validation. The library can
- * focus and/or scroll the first errored field into view without you
- * wiring an `onError` callback yourself. Defaults to
- * `'focus-first-error'` because moving keyboard / screen-reader focus
- * to the broken field on submit is an accessibility baseline; opt out
- * with `'none'` if you're managing focus elsewhere.
- *
- * - `'focus-first-error'` (default): focus the first errored field's
- *   first visible element. Modern browsers scroll the focused element
- *   into view by default; pair with `'both'` if you want an explicit
- *   scroll alongside.
- * - `'scroll-to-first-error'`: scroll that element into view without
- *   moving focus.
- * - `'both'`: scroll first, then focus (with `preventScroll: true` so
- *   the browser doesn't undo the explicit scroll).
- * - `'none'`: no automatic UI nudge; the dev handles focus / scroll
- *   manually via `form.focusFirstError()` or `form.scrollToFirstError()`
- *   from an `onError` callback.
- *
- * Both focusing policies request `focusVisible: true`, so the browser
- * paints a focus ring even though the move is programmatic. Where a UA
- * doesn't yet support that hint, non-text controls (radio, checkbox,
- * custom widgets) may end up focused without a visible ring after a
- * pointer-driven submit; if you target those browsers, pair the policy
- * with your own indicator (e.g. a `:focus-within` ring on the option
- * wrapper).
- *
- * If no errored field has a currently mounted, visible element, the
- * policy silently no-ops.
- */
-type OnInvalidSubmitPolicy = 'none' | 'focus-first-error' | 'scroll-to-first-error' | 'both';
 /**
  * When per-field VALIDATION runs. Only validation timing varies per
  * mode; storage commit timing is the directive's concern (the
@@ -1695,8 +1776,7 @@ type HistoryModule = {
  * and `undo()` cannot reach the transient pre-hydration default.
  *
  * One plugin instance is a reusable configuration, not per-form state:
- * passing the same instance to several forms (or setting it once via
- * `createAttaform({ defaults: { history } })`) gives each form its own
+ * passing the same instance to several forms gives each form its own
  * independent chain.
  */
 type HistoryPlugin = {
@@ -1780,11 +1860,9 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      *
      * For schemas that depend on the form's identity or per-form
      * options, pass a factory `(key, options) => schema` instead — the
-     * library calls it once per form, after `mergeWithDefaults` has
-     * resolved the options bag (`maxRecursionDepth`, etc.). Most
-     * adapters ignore the options argument; the typed Zod entry points
-     * use it to thread the resolved recursion cap into the adapter
-     * closure.
+     * library calls it once per form. Most adapters ignore the options
+     * argument; the typed Zod entry points use it to thread the
+     * recursion cap into the adapter closure.
      */
     schema: Schema | ((key: FormKey, options: SchemaFactoryOptions) => Schema);
     /**
@@ -1842,40 +1920,29 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      */
     defaultValues?: DefaultValues | (() => DefaultValues) | (() => Promise<DefaultValues>);
     /**
-     * Whether to validate default values at construction. Default
-     * `true`.
+     * Move keyboard / screen-reader focus to the first errored field when
+     * a submit attempt fails validation. Fires after errors are populated
+     * and before your `onError` callback runs.
      *
-     * - `true` (default): the schema is run against the derived
-     *   defaults immediately; any failures populate `form.errors` from
-     *   the first frame. The UI decides when to *show* errors — gate
-     *   on `form.fields.<path>.touched`, `form.meta.submissionAttempts`, etc.
-     * - `false`: refinements are stripped during defaults derivation
-     *   and construction-time validation is skipped. Useful for
-     *   multi-step wizards, field arrays seeded with placeholder
-     *   rows, or any form intentionally mounting with incomplete data.
+     * Default `true`: focusing the broken field on submit is an
+     * accessibility baseline, and modern browsers scroll the focused
+     * element into view as part of the move. Pass `false` when you drive
+     * the nudge yourself from an `onError` callback with
+     * `form.focusFirstError()` or `form.scrollToFirstError()`, both of
+     * which stay available either way.
      *
-     * Runtime validation (per-field on edit, full-form on submit) is
-     * identical regardless of this flag.
-     */
-    strict?: boolean;
-    /**
-     * Automatic UI nudge on submit-validation failure. Fires after
-     * errors are populated and before your `onError` callback runs.
-     * Default `'focus-first-error'`, which moves keyboard / screen-reader
-     * focus to the broken field as an accessibility baseline.
-     *
-     * - `'focus-first-error'` (default): focus the first errored field's
-     *   first visible element.
-     * - `'scroll-to-first-error'`: scroll it into view without focusing.
-     * - `'both'`: scroll, then focus.
-     * - `'none'`: opt out entirely; handle focus / scroll yourself in an
-     *   `onError` callback via `form.focusFirstError()` or
-     *   `form.scrollToFirstError()`.
+     * The focus requests `focusVisible: true`, so the browser paints a
+     * focus ring even though the move is programmatic. Where a UA doesn't
+     * yet support that hint, non-text controls (radio, checkbox, custom
+     * widgets) may end up focused without a visible ring after a
+     * pointer-driven submit; if you target those browsers, pair this with
+     * your own indicator (e.g. a `:focus-within` ring on the option
+     * wrapper).
      *
-     * If no errored field has a currently-mounted, visible element,
-     * the policy silently no-ops.
+     * If no errored field has a currently-mounted, visible element, the
+     * focus silently no-ops.
      */
-    onInvalidSubmit?: OnInvalidSubmitPolicy;
+    focusOnInvalidSubmit?: boolean;
     /**
      * Freeze the form's data. When this resolves truthy every value write
      * no-ops at the store's write chokepoint (programmatic `setValue`, the
@@ -1893,7 +1960,6 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      *
      * Accepts a boolean, a ref, a computed, or a getter, read live so the
      * freeze tracks a reactive source. `undefined` resolves to `false`.
-     * Falls back to `AttaformDefaults.disabled`.
      *
      * A shared FormStore resolves `disabled` from its first `useForm({ key })`
      * call; a later caller passing a different value is ignored.
@@ -1960,68 +2026,18 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
     rememberVariants?: boolean;
     /**
      * Schema-driven coercion of user-typed DOM values at the v-register
-     * directive layer. Per-form override of the plugin-level
-     * `AttaformDefaults.coerce`.
+     * directive layer.
      *
-     * - `true` / `undefined` — runs the built-in `defaultCoercionRules`.
-     * - `false` — disables coercion; the slim gate rejects mismatches.
-     * - `CoercionRegistry` — a custom array of entries (REPLACES, not
-     *   merges, the plugin defaults). Spread `defaultCoercionRules` to
-     *   extend.
+     * Two rules ship: string→number and string→boolean, each firing
+     * only when the schema declares that single type at the path.
+     * Defaults to on; `false` disables coercion form-wide and the slim
+     * gate rejects mismatches instead.
      *
      * Coercion applies ONLY to user-typed DOM values. Programmatic
      * writes (`form.setValue`, `setValueWithInternalPath`) are NEVER
      * coerced.
      */
-    coerce?: boolean | CoercionRegistry;
-    /**
-     * 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.
-     */
-    getDisplayState?: GetDisplayState;
-    /**
-     * Recursion ceiling for schema walks that descend through recursive
-     * schemas (Zod's `z.lazy(...)` today). Default `64`. Per-form value
-     * overrides `AttaformDefaults.maxRecursionDepth`, which overrides
-     * the library default.
-     *
-     * Schemas that don't include a recursive boundary ignore this knob
-     * entirely — it's read only at the descent step through a recursive
-     * wrapper. Set it on the specific form whose schema is recursive
-     * (a comment tree, a category tree, a nested-rule editor):
-     *
-     * ```ts
-     * useForm({ schema: commentTreeSchema, maxRecursionDepth: 128 })
-     * ```
-     *
-     * Past the cap, the slim-primitive type gate falls back to permissive
-     * (write-time type checks skip; full schema validation still runs).
-     * Storage and reads work at any depth; only the per-write type gate
-     * stops short of the cap. Raise the cap if you regularly edit nodes
-     * beyond the default depth.
-     *
-     * See `AttaformDefaults.maxRecursionDepth` for the resolution rules
-     * and the broader description of where the cap is read.
-     */
-    maxRecursionDepth?: number;
-    /**
-     * 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;
+    coerce?: boolean;
     /**
      * @internal
      * SSR prefetch mark — set by the `attaform/vite` compile-time
@@ -2038,176 +2054,6 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      */
     __ssrAccessed?: boolean;
 };
-/**
- * App-level defaults applied to every `useForm` call. Set these once
- * per app via `createAttaform({ defaults })` (bare Vue) or
- * `attaform.defaults` (Nuxt module).
- *
- * Resolution order (per-form wins):
- *
- *   useForm({ ... })  >  createAttaform({ defaults })  >  library default
- *
- * `validateOn` and `debounceMs` resolve per-field — set the debounce
- * globally while still overriding the trigger per form:
- *
- * ```ts
- * createAttaform({
- *   defaults: { debounceMs: 100 },
- * })
- * // later
- * useForm({ schema, validateOn: 'blur' })
- * // → { validateOn: 'blur', debounceMs: <ignored under blur> }
- * ```
- *
- * Note: per the discriminated union, `debounceMs` only takes effect
- * when `validateOn` is `'change'` (or omitted). Setting it as an
- * app-level default is fine — forms that switch to `'blur'` /
- * `'submit'` simply ignore the inherited `debounceMs`.
- *
- * `schema`, `key`, and `defaultValues` are not configurable here —
- * they belong on the per-form call.
- */
-type AttaformDefaults = {
-    /** Default for `useForm({ strict })`. Default `true`. */
-    strict?: boolean;
-    /** Default for `useForm({ onInvalidSubmit })`. */
-    onInvalidSubmit?: OnInvalidSubmitPolicy;
-    /** Default for `useForm({ validateOn })` — when validation runs. */
-    validateOn?: ValidateOn;
-    /**
-     * Default for `useForm({ debounceMs })` — ms to wait after the last
-     * input event before re-running validation. Only meaningful when
-     * `validateOn` resolves to `'change'`. Default `0` (synchronous).
-     */
-    debounceMs?: number;
-    /** Default for `useForm({ history })` — a `historyPlugin()` instance. */
-    history?: HistoryPlugin;
-    /** Default for `useForm({ rememberVariants })`. */
-    rememberVariants?: boolean;
-    /** Default for `useForm({ disabled })` — freeze the form's data. */
-    disabled?: MaybeRefOrGetter<boolean | undefined>;
-    /**
-     * Default for `useForm({ coerce })`. Schema-driven coercion of
-     * user-typed DOM values at the v-register directive layer.
-     *
-     * - `true` (default) — runs the built-in `defaultCoercionRules`
-     *   (`string→number`, `string→boolean`).
-     * - `false` — disables coercion globally; the slim-primitive gate
-     *   rejects type mismatches with its existing dev-warn instead.
-     * - `CoercionRegistry` — a custom array of `CoercionEntry` records.
-     *   Spread `defaultCoercionRules` to extend rather than replace:
-     *   `[...defaultCoercionRules, defineCoercion({ ... })]`.
-     *
-     * Coercion applies ONLY to user-typed DOM values flowing through
-     * the directive's assigner. Programmatic writes (`form.setValue`,
-     * `setValueWithInternalPath`) are NEVER coerced — they're
-     * authoritative writes whose strict typing is on the caller.
-     */
-    coerce?: boolean | CoercionRegistry;
-    /**
-     * 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({ getDisplayState })  >  AttaformDefaults  >  library default
-     *
-     * The library default opens one timing gate, then resolves by
-     * precedence: gate closed → `'idle'`; a run in flight → a delayed
-     * `'pending'` (held briefly to smooth fast validations, then held a
-     * minimum so it never flashes); an own-path error → `'error'`;
-     * otherwise earned `valid` → `'success'`, else `'idle'`. The gate opens
-     * after the first submit attempt OR once the field is edited and left:
-     *
-     * ```ts
-     * (prev, ctx) => {
-     *   const gateOpen =
-     *     ctx.formMeta.submissionAttempts > 0 ||
-     *     ctx.field.blurredAfterInteraction === true
-     *   if (!gateOpen) return { display: 'idle' }
-     *   // ...timed 'pending' while validating; own-path error → 'error';
-     *   //    earned valid → 'success'; else 'idle'
-     * }
-     * ```
-     *
-     * Compose with the library default via the public `defaultDisplayState`
-     * export, or retune its timing via `makeDefaultDisplayState`. The
-     * reducer runs on every field-state read, so it owns the
-     * idle / pending / error / success decision outright.
-     *
-     * The reducer's `ctx.field` / `ctx.formMeta` are `Omit`'d of the
-     * derived `displayState` / `show*` / `firstError` keys (see
-     * `FieldStateDerivedKey`) to prevent a self-referential reducer.
-     */
-    getDisplayState?: GetDisplayState;
-    /**
-     * Default for `useForm({ maxRecursionDepth })`. Recursion ceiling
-     * for schema walks that descend through recursive schemas (Zod's
-     * `z.lazy(...)` today, equivalent constructs in any future adapter).
-     * Library default: `64`.
-     *
-     * Resolution order (per-form wins):
-     *
-     *   useForm({ maxRecursionDepth })  >  AttaformDefaults  >  library default (64)
-     *
-     * Read at every step of a schema walk that crosses a recursive
-     * boundary — default-value derivation at construction, slim-primitive
-     * type gates on each write, path-by-path schema resolution. Walks
-     * track their descent depth and switch to a permissive fallback once
-     * `depth > maxRecursionDepth`.
-     *
-     * "Permissive fallback" means storage and reads keep working at any
-     * depth; only the per-write type gate stops checking past the cap.
-     * Full schema validation (`parse`, `handleSubmit`) still runs
-     * against the real schema, so refinement errors at any depth still
-     * surface — the cap only affects the *write-time gate*.
-     *
-     * Forms with no recursive schemas ignore this entirely — the cap is
-     * read only at the descent step through a recursive wrapper. Setting
-     * it app-wide is the right move when you have multiple recursive
-     * forms that should share one ceiling:
-     *
-     * ```ts
-     * createAttaform({
-     *   defaults: { maxRecursionDepth: 128 },
-     * })
-     * ```
-     *
-     * Per-form override stays available for the one tree-shaped form
-     * whose depth is unusual:
-     *
-     * ```ts
-     * useForm({ schema: deepCategoryTreeSchema, maxRecursionDepth: 256 })
-     * ```
-     *
-     * Setting this app-wide costs nothing for non-recursive forms — the
-     * walks that read the cap never run for them.
-     *
-     * Pass `Infinity` to disable the cap entirely. Walks will then
-     * descend through recursive boundaries until they terminate
-     * structurally; a schema with no structural terminator will exhaust
-     * the JS call stack. Reserve for schemas whose authors are
-     * confident the recursion is bounded by the actual data shape.
-     */
-    maxRecursionDepth?: number;
-    /**
-     * 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.
  * Receives the strictly-typed parsed value — refinements have run, so
@@ -2220,7 +2066,7 @@ type OnSubmit<Form extends GenericForm> = (form: Form) => void | Promise<void>;
  * the user-error layer (the `setErrors(...); return` server-rejection
  * pattern). Receives the full list of errors. Bind this when you want to
  * react to submit failures explicitly (alongside or instead of the
- * automatic `onInvalidSubmit` UI nudge).
+ * automatic `focusOnInvalidSubmit` nudge).
  */
 type OnError = (error: ValidationError[]) => void | Promise<void>;
 /**
@@ -2274,11 +2120,11 @@ type DisplayMachine = {
     readonly pendingShownAt?: number;
 };
 /**
- * Inputs to a `getDisplayState` reducer. `field` and `formMeta` are the
- * same reactive snapshots a predicate has always received (still minus
- * the derived `displayState` / `show*` / `firstError` keys — see
- * `FieldStateDerivedKey` — so a reducer can never read its own output and
- * form a cycle), now joined by:
+ * Inputs to the display reducer. `field` and `formMeta` are the
+ * reactive snapshots it resolves against (minus the derived
+ * `displayState` / `show*` / `firstError` keys — see
+ * `FieldStateDerivedKey` — so the reducer can never read its own output
+ * and form a cycle), joined by:
  *
  * - `validatingSince` — `Date.now()` at which the field's current
  *   validation streak opened, or `null` when nothing is in flight. This,
@@ -2306,26 +2152,9 @@ type DisplayCtx = {
  * returns the next machine; the engine owns the clock and the timers, the
  * reducer owns the timing policy. Runs on every field-state read (and
  * again whenever a `reviewAt` deadline fires), so the whole app's
- * validation-display behavior flows from this one function.
- *
- * The library default — `defaultDisplayState` — is publicly exported so a
- * layered reducer can compose with it, and `makeDefaultDisplayState`
- * builds a default with custom anti-flash timings:
- *
- * ```ts
- * import { defaultDisplayState } from 'attaform'
- *
- * useForm({
- *   schema,
- *   // Defer to the default everywhere, but never show a success check on `username`.
- *   getDisplayState: (prev, ctx) => {
- *     const next = defaultDisplayState(prev, ctx)
- *     return next.display === 'success' && ctx.field.path[0] === 'username'
- *       ? { display: 'idle' }
- *       : next
- *   },
- * })
- * ```
+ * validation-display behavior flows from this one function
+ * (`core/display-state.ts`).
+ * @internal
  */
 type GetDisplayState = (prev: DisplayMachine, ctx: DisplayCtx) => DisplayMachine;
 /**
@@ -2461,60 +2290,6 @@ type RegisterFlatPath<Form> = Form extends unknown ? FlatPathBuilder<Form, 'regi
  * `transformError` channel above, not a throw into the host app.)
  */
 type RegisterTransform = (value: unknown, ctx?: TransformContext) => unknown;
-/**
- * Runtime type for a slim primitive kind. Used to narrow the
- * `transform` parameter and return value on a `CoercionEntry` so
- * authors writing rules don't have to cast `unknown`.
- *
- * Exhaustive over `SlimPrimitiveKind` — adding a new kind to that
- * union must add a corresponding branch here.
- */
-type SlimRuntimeOf<K extends SlimPrimitiveKind> = K extends 'string' ? string : K extends 'number' ? number : K extends 'boolean' ? boolean : K extends 'bigint' ? bigint : K extends 'date' ? Date : K extends 'null' ? null : K extends 'undefined' ? undefined : K extends 'array' ? readonly unknown[] : K extends 'set' ? ReadonlySet<unknown> : K extends 'map' ? ReadonlyMap<unknown, unknown> : K extends 'object' ? Record<string, unknown> : K extends 'symbol' ? symbol : K extends 'function' ? (...args: never[]) => unknown : never;
-/**
- * Outcome of a coercion attempt.
- *
- * - `coerced: true` — the rule produced `value`, which the directive
- *   forwards to the slim gate (the gate may still reject if the
- *   value doesn't satisfy the path's accept set).
- * - `coerced: false` — the rule decided it can't coerce this input.
- *   The directive passes the original value through; the slim gate
- *   decides downstream.
- *
- * Discriminated rather than `O | undefined` so rules with
- * `output: 'undefined'` or `output: 'null'` don't conflict with the
- * "skip" signal.
- */
-type CoercionResult<O> = {
-    coerced: true;
-    value: O;
-} | {
-    coerced: false;
-};
-/**
- * A single coercion rule. `input` and `output` are
- * `SlimPrimitiveKind` literals; `transform` receives a value already
- * narrowed to `SlimRuntimeOf<input>` and returns
- * `CoercionResult<SlimRuntimeOf<output>>`.
- *
- * Rules MUST be sync. They SHOULD NOT throw — wrap internal
- * try/catch when the conversion can fail (e.g. `BigInt(s)` throws
- * for non-numeric strings). The library wraps each invocation in
- * try/catch as defense in depth; throws are caught, logged once per
- * `(input, output)`, and the original value passes through.
- */
-type CoercionEntry<I extends SlimPrimitiveKind = SlimPrimitiveKind, O extends SlimPrimitiveKind = SlimPrimitiveKind> = {
-    readonly input: I;
-    readonly output: O;
-    readonly transform: (value: SlimRuntimeOf<I>) => CoercionResult<SlimRuntimeOf<O>>;
-};
-/**
- * A registry is an ordered array of `CoercionEntry` records.
- * Consumers compose by spreading `defaultCoercionRules` and
- * appending their own entries. Order is observable only when two
- * entries share the same `(input, output)` pair — the library emits
- * a one-shot dev-warn and the LATER entry wins.
- */
-type CoercionRegistry = readonly CoercionEntry[];
 /**
  * Options for `register(path, options)`. Per-field configuration
  * applied at the binding's own call site.
@@ -2552,22 +2327,6 @@ 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 narrow kernel surface the DOM binding drives. Structurally a
@@ -2905,14 +2664,6 @@ type RegisterValue<Value = unknown> = Readonly<{
      * @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
@@ -3213,9 +2964,11 @@ declare module 'vue' {
  * form.setValue((prev) => ({ ...prev, name: 'Ada' }))
  * ```
  *
- * The library fills any missing structural slots (e.g. nested
- * objects) against the schema's defaults after the callback returns,
- * so partial returns are safe.
+ * A whole-form callback replaces the whole form. Any key the return
+ * omits is refilled from the SCHEMA's declared defaults (the slim
+ * value where none is declared), so an omitted key is not carried
+ * over from the previous value or from `defaultValues` — spread
+ * `prev` to keep the rest of the form.
  */
 type SetValueCallback<Read, Write = Read> = (prev: Read) => Read | Write;
 /**
@@ -3459,11 +3212,11 @@ type FieldState<Value = unknown> = {
      * <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.
+     * Resolved by the display heuristic: gate closed → `'idle'`; a run
+     * in flight → a delayed `'pending'`; an own-path error → `'error'`;
+     * otherwise earned `valid` → `'success'`, else `'idle'`. The gate
+     * opens after the first submit attempt OR once the field is edited
+     * and left.
      *
      * Available on container paths too: `form.fields.users[0].displayState`
      * rolls up over the row's descendants.
@@ -3848,7 +3601,7 @@ type FieldStateMap<Form extends GenericForm> = LeafWalker<Form, 'field'> & {
      * dot/bracket access (`form.fields.users[i].email`), which is what
      * descends.
      */
-    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): FieldState<NestedType<Form, JoinSegments<S>>>;
+    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : SegmentPathRejection<JoinSegments<S>>)): FieldState<NestedType<Form, JoinSegments<S>>>;
     /**
      * Dynamic-array fallback for callers passing `Path`-typed (runtime)
      * segment arrays — e.g. forwarding `RegisterValue.segments` to
@@ -3919,7 +3672,7 @@ type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
      * tuples that don't resolve to a known path fail at the call site.
      * Dynamic `Path`-typed inputs hit the untyped fallback overload below.
      */
-    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
+    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : SegmentPathRejection<JoinSegments<S>>)): readonly ValidationError[];
     (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
      * No-arg call returns the whole-form error aggregate, the same as
@@ -3964,6 +3717,27 @@ type ErrorsProxyShape<T> = LeafWalker<T, 'errors', false>;
  * form.values()                      // the whole form value (root)
  * ```
  *
+ * The two shapes answer different questions. Dot access is the
+ * REACTIVE view: per-key tracking, no copying, always the live value.
+ * The call form returns a SNAPSHOT: a detached plain object that keeps
+ * what it held at capture time, so it is the shape to hand an async
+ * call, a serialiser, or a diff.
+ *
+ * ```ts
+ * const before = form.values()   // detached; survives later writes
+ * await api.save(before)         // cannot mutate underneath the call
+ * form.values.email              // reactive read; use this in computed
+ * ```
+ *
+ * Prefer dot access inside a `computed`, `watchEffect`, or template:
+ * it tracks the one key you read, where the call form depends on the
+ * whole form and re-runs the consumer on any change.
+ *
+ * The copy is deep across plain objects and arrays. Non-plain
+ * instances (Map, Set, File, Date) are shared by reference, matching
+ * `JSON.stringify` behaviour; `structuredClone(form.values())` gives a
+ * fully detached copy when one is needed.
+ *
  * Single-bracket dotted access (`form.values['address.city']`) is
  * intentionally NOT supported — JS object semantics treat the dotted
  * string as a single key. Use chained dot/bracket or the callable
@@ -4007,7 +3781,9 @@ type ValuesSurface<F> = Readonly<LiftedValueShape<F>> & {
  * `form.fields.<path>`; this is the aggregate view across the
  * whole form.
  *
- * Read-only at runtime — assignments throw. Destructuring snapshots
+ * Read-only at runtime — an assignment is refused with a dev-console
+ * warning and never lands (Attaform does not throw from a read
+ * surface). Destructuring snapshots
  * the current values; use `toRefs()` if you need reactive handles
  * to individual fields.
  */
@@ -4032,9 +3808,8 @@ type FormMeta<F = unknown> = FieldState<F> & {
      * the counter at its prior value.
      *
      * Pure introspection counter — useful for "this form has been
-     * visited and left" UX (analytics, prior-step badges, layered
-     * `getDisplayState` predicates) but does NOT drive the library's
-     * default `getDisplayState` heuristic. The reveal-on-submit story
+     * visited and left" UX (analytics, prior-step badges) but does NOT
+     * drive the display heuristic. The reveal-on-submit story
      * runs entirely through `submissionAttempts`, which
      * `wizard.handleSubmit` bumps on every form (it always validates the
      * whole step list).
@@ -4351,7 +4126,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
          * `form.setValue([prefix, 'line1'], 'value')`. The resolved leaf
          * type is exact, matching the dotted-string form.
          */
-        <const S extends ReadonlyArray<string | number>, Value extends PathSetValuePayload<NestedType<Form, JoinSegments<S>>>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never), value: Value): boolean;
+        <const S extends ReadonlyArray<string | number>, Value extends PathSetValuePayload<NestedType<Form, JoinSegments<S>>>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : SegmentPathRejection<JoinSegments<S>>), value: Value): boolean;
     };
     /**
      * Reactive validation status. Re-runs whenever the form (or the
@@ -4463,7 +4238,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      */
     register: {
         <Path extends RegisterFlatPath<Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, Path>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form>] ? unknown : SegmentRegisterRejection<JoinSegments<S>>), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>;
     };
     /**
      * The form's identifier — either the explicit `key` passed to
@@ -4544,8 +4319,12 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      *
      * Resolves after `hydrating` flips back to `false`. Throws
      * synchronously when the form was constructed with a plain-value
-     * `defaultValues` (nothing to re-fire). Does NOT clear dirty /
-     * touched / submit state — chain `form.reset()` for that.
+     * `defaultValues` (nothing to re-fire).
+     *
+     * The payload becomes the form's defaults, the same way a
+     * `reset(next)` argument does, so `form.reset()` afterwards lands on
+     * the values just fetched. Does NOT clear touched / submit state;
+     * chain `form.reset()` for that.
      */
     rehydrate(): Promise<void>;
     /**
@@ -4603,7 +4382,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      */
     toRef: {
         <Path extends FlatPath<Form>>(path: Path): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, Path>>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : SegmentPathRejection<JoinSegments<S>>)): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>>;
     };
     /**
      * Set the form's manual error layer. One surface for server-side
@@ -4673,10 +4452,10 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      */
     meta: FormMeta<Form>;
     /**
-     * Restore the form to its initial state. Without arguments,
-     * re-applies the schema defaults (and any `defaultValues` passed
-     * to `useForm`). Pass `nextDefaultValues` to seed the reset with
-     * a fresh set of overrides.
+     * Restore the form to its defaults. Without arguments, re-applies
+     * whatever the defaults currently are: `useForm({ defaultValues })`
+     * on a fresh form, or the last values a `reset(next)` or an async
+     * `defaultValues` factory settled on.
      *
      * Resets:
      *   - the form value back to defaults;
@@ -4685,6 +4464,26 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      *   - touched / focused / blurred per-field flags;
      *   - submission state (`submitting` / `submissionAttempts` /
      *     `submitted` / `submitError`).
+     *
+     * `nextDefaultValues` RE-SEATS the defaults rather than applying for
+     * one call, so the form has a single set of defaults that `reset()`,
+     * `resetField(path)`, and `dirty` all read. That is what makes the
+     * save-then-discard shape work: reset from the resource the server
+     * returned, and a later Discard returns to the save instead of
+     * rolling back across it.
+     *
+     * ```ts
+     * const saved = await api.save(form.values())
+     * form.reset(toValues(saved))   // the saved resource is now the baseline
+     * // …later…
+     * form.reset()                  // back to the saved resource
+     * ```
+     *
+     * The argument is sparse: it folds over the defaults already in
+     * force, so paths it does not name keep the value they had, and
+     * `reset({})` changes nothing. Arrays are replaced wholesale rather
+     * than merged element-wise. Pass `unset` at a path to withdraw its
+     * value and mark it blank.
      */
     reset: (nextDefaultValues?: DefaultValuesInput<Form>) => void;
     /**
@@ -4739,7 +4538,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     clear: {
         (): boolean;
         <Path extends FlatPath<Form> | ''>(path: Path): boolean;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form> | ''] ? unknown : never)): boolean;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form> | ''] ? unknown : SegmentPathRejection<JoinSegments<S>>)): boolean;
     };
     /**
      * Consolidated undo/redo namespace — `form.history.{undo, redo,
@@ -4776,20 +4575,19 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      */
     scrollToFirstError: (options?: ScrollIntoViewOptions) => boolean;
     /**
-     * Drive the form's `onInvalidSubmit` policy imperatively. The same
-     * focus/scroll behavior `handleSubmit` runs after a failed submit,
-     * but available standalone. Defaults to the policy configured via
-     * `useForm({ onInvalidSubmit })` (or `'focus-first-error'` when
-     * omitted). Pass an explicit policy to override for one call.
+     * Run the form's own invalid-submit nudge imperatively: exactly what
+     * `handleSubmit` does after a failed submit, but available standalone
+     * and honoring this form's `useForm({ focusOnInvalidSubmit })` choice.
      *
      * Used by `useWizard` after navigating to the first failing form
      * during `wizard.handleSubmit`, so the failing form's own configured
-     * policy fires once its DOM is in view.
+     * behavior fires once its DOM is in view.
      *
-     * No-op when no errored field is currently registered or when the
-     * resolved policy is `'none'`.
+     * No-op when this form opted out, or when no errored field is
+     * currently registered. Use `focusFirstError()` to focus regardless
+     * of the configured choice.
      */
-    applyInvalidSubmitPolicy: (policy?: OnInvalidSubmitPolicy) => void;
+    applyInvalidSubmitPolicy: () => void;
     /**
      * Programmatically mark fields as `touched` — the descriptive
      * "this field was visited" flag.
@@ -4805,9 +4603,9 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * heuristic.** `touched` also flips on a bare focus → blur with no
      * edit, so the library-default gate deliberately ignores it and
      * reads `blurredAfterInteraction` instead — the stricter bit that
-     * only a blur *following* an edit sets. Reach for `touch()` when a
-     * custom `getDisplayState` reducer or your analytics reads
-     * `touched`; reach for {@link UseFormReturnType.interact} to make
+     * only a blur *following* an edit sets. Reach for `touch()` when
+     * your own analytics reads `touched`; reach for
+     * {@link UseFormReturnType.interact} to make
      * seeded or imported values surface their errors.
      *
      * Pure flag write — does not mutate value, focused, blurred, or
@@ -4959,5 +4757,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as Y, ROOT_PATH_KEY as Z, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
-export type { RegisterDirective as $, AbstractSchema as A, NestedType as B, CoercionEntry as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, OnInvalidSubmitPolicy as P, OnSubmit as Q, ParseOptions as R, PartialFlatPath as S, Path as T, UseFormConfiguration as U, PathKey as V, PendingValidationStatus as W, Primitive as X, ReactiveValidationStatus as _, UseFormReturnType as a, RegisterFlatPath as a0, RegisterOptions as a1, RegisterSelectModifier as a2, RegisterTextModifier as a3, RegisterTransform as a4, RegisterValue as a5, Segment as a6, SetValueCallback as a7, SetValuePayload as a8, SettledValidationStatus as a9, SlimPrimitiveKind as aa, SlimRuntimeOf as ab, SubmitHandler as ac, Unset as ad, ValidateOn as ae, ValidateOnConfig as af, ValidationError as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, RegisterModelDynamicCustomDirective as ar, AcceptableDefaults as as, SchemaFactoryOptions as at, FieldRecord as au, ErrorCell as av, OriginalsRecord as aw, AttaformDomBinding as ax, TransformAbortHolder as ay, ArrayItem as b, ArrayPath as c, AttaformDefaults as d, CoercionRegistry as e, CoercionResult as f, CustomDirectiveRegisterAssignerFn as g, DeepPartial as h, DefaultValuesResponse as i, DefaultValuesShape as j, DisplayCtx as k, DisplayMachine as l, DisplayState as m, ErrorsProxyShape as n, FieldMetaPayload as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormMeta as v, GetDisplayState as w, HistoryPlugin as x, IsUnion as y, Json as z };
+export { ROOT_PATH as R, canonicalizePath as aj, isPathPrefix as ak, isUnset as al, parseDottedPath as am, unset as an, ROOT_PATH_KEY as z };
+export type { SchemaDefaultsResult as $, AbstractSchema as A, ReactiveValidationStatus as B, CustomDirectiveRegisterAssignerFn as C, DefaultValuesInput as D, ErrorInput as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, ParseOptions as P, RecordPath as Q, RecordValue as S, RegisterDirective as T, UseFormConfiguration as U, RegisterFlatPath as V, RegisterOptions as W, RegisterSelectModifier as X, RegisterTextModifier as Y, RegisterTransform as Z, RegisterValue as _, UseFormReturnType as a, SchemaParseErrorWithData as a0, SchemaParseErrorWithoutData as a1, SchemaParseResult as a2, SchemaParseSuccess as a3, Segment as a4, SetValueCallback as a5, SetValuePayload as a6, SettledValidationStatus as a7, SlimPrimitiveKind as a8, SubmitHandler as a9, Unset as aa, ValidateOn as ab, ValidateOnConfig as ac, ValidationError as ad, ValidationResponse as ae, ValidationResponseWithoutValue as af, ValueOfUnion as ag, WriteMeta as ah, WriteShape as ai, RegisterModelDynamicCustomDirective as ao, SchemaFactoryOptions as ap, AcceptableDefaults as aq, DisplayCtx as ar, GetDisplayState as as, DisplayMachine as at, FieldRecord as au, ErrorCell as av, OriginalsRecord as aw, AttaformDomBinding as ax, TransformAbortHolder as ay, ArrayItem as b, ArrayPath as c, DeepPartial as d, DefaultValuesShape as e, DisplayState as f, ErrorsProxyShape as g, FieldMetaPayload as h, FieldState as i, FieldStateMap as j, FieldStateMapEntry as k, FlatPath as l, FormErrorRecord as m, FormErrorsSurface as n, FormMeta as o, HistoryPlugin as p, IsUnion as q, Json as r, NestedType as s, OnSubmit as t, PartialFlatPath as u, Path as v, PathKey as w, PendingValidationStatus as x, Primitive as y };