attaform 0.28.0 → 0.29.0

package/dist/shared/{attaform.wfY8XFvm.mjs → attaform.CZYt_5N_.mjs}

@@ -79,6 +79,16 @@ function groupErrorsByKey(entries) {
 }
 
 const INTEGER_SEGMENT = /^(?:0|[1-9]\d*)$/;
+const SET_MEMBER_SEGMENT = "__atta:member";
+function mapSegmentKeys(value) {
+  const keys = [];
+  for (const key of value.keys()) {
+    if (typeof key === "string") keys.push(key);
+    else if (typeof key === "number" && Number.isInteger(key) && key >= 0) keys.push(key);
+    else return null;
+  }
+  return keys;
+}
 function normalizeSegment(raw) {
   if (typeof raw === "number") {
     if (!Number.isInteger(raw) || raw < 0) {
@@ -194,4 +204,4 @@ function pathsEqual(a, b) {
   return true;
 }
 
-export { AttaformError as A, InvalidPathError as I, OutsideSetupError as O, ROOT_PATH as R, SubmitErrorHandlerError as S, InvalidUseFormConfigError as a, ROOT_PATH_KEY as b, RegistryNotInstalledError as c, ReservedFormKeyError as d, canonicalizePath as e, pathsEqual as f, pathKeyToDotted as g, cellEntriesFor as h, isPathPrefix as i, groupErrorsByKey as j, keyForSegments as k, normalizeErrorInputs as l, coerceToPathKey as m, normalizeErrorInput as n, parseDottedPath as p, segmentsForPathKey as s, toError as t };
+export { AttaformError as A, InvalidPathError as I, OutsideSetupError as O, ROOT_PATH as R, SubmitErrorHandlerError as S, InvalidUseFormConfigError as a, ROOT_PATH_KEY as b, RegistryNotInstalledError as c, ReservedFormKeyError as d, canonicalizePath as e, pathsEqual as f, pathKeyToDotted as g, SET_MEMBER_SEGMENT as h, isPathPrefix as i, cellEntriesFor as j, keyForSegments as k, groupErrorsByKey as l, mapSegmentKeys as m, normalizeErrorInput as n, normalizeErrorInputs as o, parseDottedPath as p, coerceToPathKey as q, segmentsForPathKey as s, toError as t };

package/dist/shared/{attaform.Cgu-hdSb.d.mts → attaform.CsoeRi3P.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."
@@ -1088,6 +1175,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 +1242,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
@@ -1203,9 +1335,12 @@ type AbstractSchema<Form, GetValueFormType> = {
      */
     getSlimPrimitiveTypesAtPath(path: Path): Set<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 +1358,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.
@@ -3213,9 +3356,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;
 /**
@@ -3848,7 +3993,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 +4064,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 +4109,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 +4173,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.
  */
@@ -4351,7 +4519,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 +4631,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 +4712,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 +4775,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 +4845,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 +4857,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 +4931,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,
@@ -4959,5 +5151,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 Y, ROOT_PATH_KEY as Z, canonicalizePath as ao, isPathPrefix as ap, isUnset as aq, parseDottedPath as ar, unset as as };
+export type { RecordPath 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, RecordValue as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterOptions as a3, RegisterSelectModifier as a4, RegisterTextModifier as a5, RegisterTransform as a6, RegisterValue as a7, Segment as a8, SetValueCallback as a9, TransformAbortHolder as aA, SetValuePayload as aa, SettledValidationStatus as ab, SlimPrimitiveKind as ac, SlimRuntimeOf as ad, SubmitHandler as ae, Unset as af, ValidateOn as ag, ValidateOnConfig as ah, ValidationError as ai, ValidationResponse as aj, ValidationResponseWithoutValue as ak, ValueOfUnion as al, WriteMeta as am, WriteShape as an, RegisterModelDynamicCustomDirective as at, SchemaFactoryOptions as au, AcceptableDefaults as av, FieldRecord as aw, ErrorCell as ax, OriginalsRecord as ay, AttaformDomBinding as az, 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 };