attaform 0.23.0 → 0.24.1

package/dist/shared/{attaform.BJnNK75Y.d.ts → attaform.DBhrKb2j.d.mts}

@@ -101,10 +101,11 @@ type Path = readonly Segment[];
  * parseDottedPath('')                     // ['']  (the empty-string key)
  * ```
  *
- * The empty-string input `''` is the **literal empty-key path**, not
- * the root. Use the array form `[]` for root. Form-level errors
- * (root `.refine()`) live at the empty-string path bucket so
- * `errors('')` returns them without sweeping every field error too.
+ * The empty-string input `''` is the **literal empty-key path** `['']`,
+ * an ordinary (if rare) field address, not the root. Use the array
+ * form `[]` for the root. Form-level errors (root `.refine()`,
+ * `setErrors` with no path) live at the root path `[]` and are read via
+ * `errors([])`, never `errors('')`.
  *
  * Throws `InvalidPathError` for paths with empty INTERNAL segments
  * (`'a..b'`, leading or trailing dots). For keys containing literal
@@ -132,8 +133,17 @@ declare function canonicalizePath(input: string | Path): {
     key: PathKey;
 };
 /**
- * The root path — an empty segment tuple. Pass to APIs that accept
- * a `Path` to address the form value as a whole.
+ * The root path — an empty segment tuple. Pass to APIs that accept a
+ * `Path` to address the form value as a whole, and the home for
+ * form-level (global) errors: root `.refine()` messages, hydration
+ * failures, and `setErrors` entries with no path all live at `[]`. Aggregate
+ * reads (`errors()`, `meta.errors`) surface them alongside field
+ * errors; `errors([])` returns the global bucket alone.
+ *
+ * The empty SEGMENT tuple `[]` is structurally unconstructible as a
+ * field path, so it can never collide with a schema key, unlike the
+ * empty STRING key `''` (path `['']`, key `'[""]'`), which is an
+ * ordinary field address.
  */
 declare const ROOT_PATH: Path;
 /** Stable string key for the root path. */
@@ -248,8 +258,17 @@ type FlatPathBuilder<Form, Mode extends 'partial' | 'register', Key extends keyo
  * Inlining at consumer call sites compounds into TS2589 territory
  * when multiple complex forms share a scope. Consumers should reach
  * for `FlatPath` instead; this alias is not part of the stable surface.
+ *
+ * The `Form extends unknown` wrapper distributes over a top-level
+ * union so each member contributes its OWN `keyof` — a discriminated-
+ * union root (`z.discriminatedUnion`) thus exposes every variant's
+ * keys as addressable paths, not just the discriminator that naked
+ * `keyof (A | B)` would intersect to. For a single object / array /
+ * record `Form` it is a one-member no-op and stays byte-identical to
+ * the prior walk. Interior unions already distribute inside
+ * `FlatPathBuilder` via its `infer Value` step.
  */
-type PartialFlatPath<Form, Key extends keyof Form = keyof Form> = FlatPathBuilder<Form, 'partial', Key>;
+type PartialFlatPath<Form> = Form extends unknown ? FlatPathBuilder<Form, 'partial'> : never;
 /**
  * Union of dotted-string paths reachable inside `Form`, e.g. for
  * `{ user: { email: string }, items: string[] }`:
@@ -260,7 +279,7 @@ type PartialFlatPath<Form, Key extends keyof Form = keyof Form> = FlatPathBuilde
  * `register(path)`, `toRef(path)`, etc.) so paths autocomplete in
  * the IDE and typos compile-error.
  */
-type FlatPath<Form, Key extends keyof Form = keyof Form> = PartialFlatPath<Form, Key>;
+type FlatPath<Form> = PartialFlatPath<Form>;
 /**
  * Convert a tuple of path segments to its dotted-string equivalent.
  *
@@ -645,25 +664,45 @@ interface SchemaFactoryOptions {
     /** Resolved recursion ceiling (per-form > app-default > library default). */
     maxRecursionDepth: number;
 }
+/**
+ * A JSON-serialisable value: the recursive shape of anything that
+ * survives a `JSON.stringify` / `JSON.parse` round-trip unchanged.
+ * The type of `ValidationError.data`.
+ *
+ * The object arm is a named interface rather than an inline index
+ * signature: TypeScript expands an anonymous recursive alias eagerly
+ * and tips into a depth-limit error (TS2589) when `Json` is checked
+ * inside a large structural type (e.g. the form store). A named
+ * reference defers that expansion.
+ */
+type Json = string | number | boolean | null | JsonArray | JsonObject;
+interface JsonArray extends Array<Json> {
+}
+interface JsonObject {
+    [key: string]: Json;
+}
 /**
  * One validation failure. `path` points at the offending field as a
  * structured array — `['user', 'address', 0, 'line1']` for a nested
- * field, `['']` (the empty-string path) for a form-level error
- * (root `.refine()` messages, `setFormErrors()` entries, server-
- * emitted form banners). `formKey` identifies which form produced
- * the error so a single error list can be routed to multiple forms.
+ * field, `[]` (the root path) for a form-level error (root `.refine()`
+ * messages, `setErrors` entries with no path, hydration failures,
+ * server-emitted form banners). `formKey` identifies which form
+ * produced the error so a single error list can be routed to multiple
+ * forms. The optional `data` slot carries an arbitrary server payload.
  *
  * Returned by `validate()` / `validateAsync()` / `handleSubmit`'s
- * `onError` callback, and by `parseApiErrors` for server responses.
+ * `onError` callback, and accepted (leniently, as `ErrorInput`) by
+ * `form.setErrors`.
  */
 type ValidationError = {
     /** Human-readable message describing the failure. */
     message: string;
     /**
-     * Structured path of the offending field. The empty-string path
-     * `['']` is the form-level bucket — the dedicated home for errors
-     * that don't belong to any specific field, distinct from the
-     * whole-form subtree address `[]`.
+     * Structured path of the offending field. The root path `[]` is the
+     * form-level bucket — the dedicated home for errors that don't belong
+     * to any specific field (root `.refine()`, `setErrors`, hydration
+     * failures). The empty-STRING path `['']` is unrelated: an ordinary
+     * literal empty-key field.
      */
     path: (string | number)[];
     /** Identifies which form produced this error. */
@@ -680,6 +719,38 @@ type ValidationError = {
      *   exact-message string matching.
      */
     code: string;
+    /**
+     * Optional structured payload attached to the error. Attaform never
+     * sets or reads this; it is a passthrough slot for whatever a server
+     * sends alongside the message (a captcha challenge, a lockout
+     * `unlocks_at` timestamp, an MFA step-up descriptor) so the UI can
+     * act on it. Survives serialise / hydrate and undo / redo unchanged.
+     */
+    data?: Json | null;
+};
+/**
+ * The lenient input shape `form.setErrors` accepts: a real `Error`, or
+ * a partial `ValidationError` where every field is optional.
+ *
+ * - `message`: omitted or empty coerces to `"Unknown error"`.
+ * - `path`: defaults to `[]` (a global, form-level error). Ignored by
+ *   the path-scoped `setErrors(path, …)` form, which stamps its own.
+ * - `code`: defaults to `atta:user-error`.
+ * - `data`: forwarded verbatim onto the produced `ValidationError`.
+ * - `formKey`: accepted but ignored — the form always stamps its own.
+ *
+ * Because every field is optional and `formKey` is accepted-and-ignored,
+ * `ValidationError` is a subtype of `ErrorInput`: a `ValidationError[]`
+ * you read back, or a server response that already emits the shape, pipes
+ * straight into `form.setErrors` with no adapter and no excess-property
+ * friction.
+ */
+type ErrorInput = Error | {
+    message?: string;
+    path?: (string | number)[];
+    code?: string;
+    data?: Json | null;
+    formKey?: FormKey;
 };
 /** Settled validation result when the form (or subtree) parsed successfully. */
 type ValidationResponseSuccess<TData> = {
@@ -1931,9 +2002,11 @@ type AttaformDefaults = {
  */
 type OnSubmit<Form extends GenericForm> = (form: Form) => void | Promise<void>;
 /**
- * Callback invoked by `handleSubmit` when validation fails. Receives
- * the full list of errors. Bind this when you want to react to
- * submit failures explicitly (alongside or instead of the
+ * Callback invoked by `handleSubmit` on a failed submit. Fires when
+ * client validation fails AND when the submit callback leaves errors in
+ * 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).
  */
 type OnError = (error: ValidationError[]) => void | Promise<void>;
@@ -2124,7 +2197,7 @@ type MetaTrackerValue = {
      */
     blank: boolean;
 };
-type RegisterFlatPath<Form, Key extends keyof Form = keyof Form> = FlatPathBuilder<Form, 'register', Key>;
+type RegisterFlatPath<Form> = Form extends unknown ? FlatPathBuilder<Form, 'register'> : never;
 /**
  * A transformation applied to a field's value as user input flows
  * from DOM through the directive's assigner. Composes left-to-right
@@ -3306,13 +3379,17 @@ type LeafWalker<T, Kind extends keyof LeafSchemeFor<unknown>, StripOptional exte
 type DiscriminatedLeaf<T, K extends PropertyKey, Kind extends keyof LeafSchemeFor<unknown>, StripOptional extends boolean> = [T] extends [Record<K, unknown>] ? LeafWalker<PresentValueOfUnion<T, K>, Kind, StripOptional> : LeafWalker<PresentValueOfUnion<T, K>, Kind, StripOptional> | undefined;
 /**
  * Intersection augmenting every container in the `form.errors` walker
- * with a `''` sentinel slot — the per-container home for cross-field
- * refine errors, server-side container marks, and (at root) form-level
- * errors. Gated on `Kind extends 'errors'` so `form.values` and
- * `form.fields` surfaces stay untouched. Carve-out for schemas that
+ * with a `''` slot. At a depth >= 1 container it's the container-self
+ * sentinel — the home for cross-field refine errors and server-side
+ * container marks; at root the `''` property addresses the literal
+ * empty-key field. Gated on `Kind extends 'errors'` so `form.values`
+ * and `form.fields` surfaces stay untouched. Carve-out for schemas that
  * legitimately declare a `''` field: the declared field type wins; at
  * runtime the two collide harmlessly (errors at the literal leaf and
  * any container-self errors share the slot via array concat).
+ *
+ * Global (root) errors are NOT this slot: they live at the root `[]`
+ * and are read via the `errors([])` call-form, never `errors['']`.
  */
 type ContainerSelfErrorsSlot<T, Kind> = Kind extends 'errors' ? '' extends keyof T ? unknown : {
     readonly ['']: readonly ValidationError[];
@@ -3442,9 +3519,11 @@ type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
     <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
     (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
-     * No-arg call returns the form-level error aggregate — same as
-     * `form.errors([])` and `form.meta.errors`. Always a readonly array;
-     * empty when the form has no errors.
+     * No-arg call returns the whole-form error aggregate — same as
+     * `form.meta.errors`: every field error plus the global bucket.
+     * Distinct from `form.errors([])`, which returns ONLY the global
+     * (root) bucket. Always a readonly array; empty when the form has no
+     * errors.
      */
     (): readonly ValidationError[];
 };
@@ -3500,63 +3579,6 @@ type ValuesSurface<F> = Readonly<LiftedValueShape<F>> & {
     (path: ReadonlyArray<string | number>): unknown;
     (): Readonly<F>;
 };
-/**
- * A single server-side error entry. Carries both the human-readable
- * `message` and a stable `code` identifier — both fields are required.
- * The `code` is stamped verbatim onto the produced `ValidationError`,
- * so consumers can branch on it without string-matching on `message`.
- *
- * Pick a prefix for your codes (`api:`, `auth:`, etc.) and stay
- * consistent so error-rendering UIs can switch on the code.
- */
-type ApiErrorEntry = {
-    /** Human-readable failure description. */
-    message: string;
-    /**
-     * Stable machine identifier for the failure (e.g. `'api:duplicate-email'`).
-     * Forwarded verbatim onto the produced `ValidationError`.
-     */
-    code: string;
-};
-/**
- * Shape of a server-side error details record. Keys are dotted field
- * paths; values are either a single entry, an array of entries, or a
- * mix of structured and bare-string entries. Each entry is one of:
- *
- * - **Structured** — `{ message: string, code: string }`. The `code`
- *   forwards verbatim onto the produced `ValidationError`.
- * - **Bare string** — a plain string. The Rails / Django REST
- *   Framework / Laravel default JSON shape (`{ field: ["msg"] }`).
- *   Synthesized into `{ message: <string>, code: <defaultCode> }` at
- *   parse time, where `defaultCode` defaults to `'api:unknown'` and
- *   is configurable via `parseApiErrors`'s options bag.
- *
- * Multiple entries at the same path produce multiple
- * `ValidationError`s — useful for a single field that fails multiple
- * checks (e.g. `password` is too short *and* missing a digit).
- */
-type ApiErrorDetails = Record<string, ApiErrorValue>;
-/**
- * One entry inside an {@link ApiErrorDetails} value — either the
- * strict `{ message, code }` object, or a bare string (synthesised
- * with the parser's `defaultCode`).
- */
-type ApiErrorValue = string | ApiErrorEntry | ReadonlyArray<string | ApiErrorEntry>;
-/**
- * Outer envelope `parseApiErrors` accepts. Both the wrapped form
- * (`{ error: { details } }`) and the unwrapped form (`{ details }`)
- * are recognised; raw detail records (`{ email: { message, code } }`)
- * are also accepted directly.
- */
-type ApiErrorEnvelope = {
-    /** Wrapped error envelope — `parseApiErrors` reads `details` from inside. */
-    error?: {
-        details?: ApiErrorDetails;
-        [k: string]: unknown;
-    };
-    /** Unwrapped error envelope. */
-    details?: ApiErrorDetails;
-};
 /**
  * Reactive form-level flags, counters, and aggregates returned as
  * `form.meta`. "Meta" because every other surface (`form.values`,
@@ -3629,10 +3651,14 @@ type FormMeta<F = unknown> = FieldState<F> & {
      *
      * The submit handler does NOT re-throw — its returned promise always
      * resolves, so binding it to `@submit.prevent` never manufactures a
-     * `window` unhandledrejection. This is the single channel for "the
-     * submit failed", read the same way in templates and after an
-     * imperative `await submit()`. Like `hydrateError`, it stays distinct
-     * from the curated user-error store: render it where you choose:
+     * `window` unhandledrejection. This is the channel for an UNEXPECTED
+     * submit failure (a thrown exception or rejected promise), read the
+     * same way in templates and after an imperative `await submit()`. An
+     * EXPECTED rejection handled the documented way (`setErrors(...)` then
+     * `return`, no throw) surfaces through the error store and `onError`
+     * instead, leaving `submitError` `null`. Like `hydrateError`, it stays
+     * distinct from the curated user-error store: render it where you
+     * choose:
      *
      * ```vue
      * <p v-if="form.meta.submitError">{{ form.meta.submitError.message }}</p>
@@ -3649,11 +3675,18 @@ type FormMeta<F = unknown> = FieldState<F> & {
      */
     readonly errorCount: number;
     /**
-     * `true` once a `handleSubmit` callback has resolved without
-     * throwing. Independent of `submissionAttempts` — a failed submit
-     * (validation failure or callback rejection) increments attempts but
-     * leaves `submitted` at `false`. Templates read it as "the form has
-     * been submitted successfully at least once."
+     * `true` once a `handleSubmit` callback has resolved without throwing
+     * AND left no errors behind. Independent of `submissionAttempts` — a
+     * failed submit (validation failure, callback rejection, or a callback
+     * that calls `setErrors` and returns) increments attempts but leaves
+     * `submitted` at `false`. Templates read it as "the form has been
+     * submitted successfully at least once."
+     *
+     * The error check is scoped to the user-error layer (`setErrors` /
+     * `clearErrors`): the documented server-rejection pattern
+     * (`setErrors(response.errors); return`) is a failed submit, so it does
+     * not flip `submitted`. A background async refinement that writes a
+     * schema error mid-submit does not retroactively fail it.
      *
      * Cleared by `form.reset()` alongside `submissionAttempts` and
      * `submitError`. For "the user has attempted a submit," read
@@ -3760,6 +3793,19 @@ interface BlankPathsView {
     /** Iterates the blank-marked paths as segment arrays. */
     [Symbol.iterator](): IterableIterator<Path>;
 }
+/**
+ * The no-arg `form.record()` call form, present only when the form root
+ * is itself an open record (`z.record(K, V)`). `string extends keyof
+ * Form` is the open-keyset probe: true for `Record<string, V>`, false
+ * for a fixed `z.object` shape. On a fixed object this resolves to
+ * `unknown`, which contributes nothing to the intersection in `record`
+ * below, so the no-arg call form simply does not exist there (and
+ * `form.record()` stays a compile error, as it should when the root has
+ * a closed key set). On a record root it mirrors the path-addressed
+ * `record(path)` overload: one `FieldState` per entry, keyed by the
+ * record's own runtime keys.
+ */
+type RootRecordView<Form> = string extends keyof Form ? Form extends Record<string, infer RootValue> ? () => Readonly<Record<string, FieldState<RootValue>>> : unknown : unknown;
 type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form, ReadForm extends GenericForm = Form, K extends FormKey = FormKey> = {
     /**
      * Wraps your submit logic with validation and error routing.
@@ -4008,18 +4054,14 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * user-typed values before they reach form state.
      */
     register: {
-        <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, Path>>;
-        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form, keyof Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>;
+        <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>>>;
     };
     /**
      * The form's identifier — either the explicit `key` passed to
      * `useForm` or an auto-generated unique id when `key` was omitted.
-     * Use it when feeding API errors through `parseApiErrors`:
-     *
-     * ```ts
-     * const result = parseApiErrors(serverPayload, { formKey: form.key })
-     * if (result.ok) form.setFieldErrors(result.errors)
-     * ```
+     * Every `ValidationError` this form produces carries it as `formKey`,
+     * so a shared error list can be routed back to the right form.
      *
      * Typed as the literal `K` when an explicit `key` was passed; falls
      * back to `FormKey` when omitted (auto-generated id).
@@ -4131,9 +4173,9 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * (`form.errors['user.profile.email']`) — JS dot notation splits
      * on literal dots.
      *
-     * Read-only — populate via `setFieldErrors`, `addFieldErrors`, and
-     * `clearFieldErrors`. Server-side errors flow through
-     * `parseApiErrors` first.
+     * Read-only — populate via `setErrors` / `clearErrors`. A server
+     * response that already emits `ValidationError[]` pipes straight into
+     * `setErrors` with no adapter.
      */
     errors: FormErrorsSurface<Form>;
     /**
@@ -4156,76 +4198,61 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
         <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<ReadForm>, JoinSegments<S>>>>;
     };
     /**
-     * Replace every field error for this form with the provided list.
-     * Useful after `parseApiErrors` produces a fresh batch from a
-     * server response.
+     * Set the form's manual error layer. One surface for server-side
+     * errors, optimistic-UI errors, and form-level banners: a field error
+     * and a global (form-level) error are the same thing at different
+     * paths, so there is no separate field/form split.
      *
-     * ```ts
-     * const result = parseApiErrors(payload, { formKey: form.key })
-     * if (result.ok) form.setFieldErrors(result.errors)
-     * ```
-     */
-    setFieldErrors: (errors: ValidationError[]) => void;
-    /**
-     * Append errors to the existing set without clearing prior entries.
-     * Use when reporting an additional issue alongside existing errors
-     * (e.g. a partial server response).
-     */
-    addFieldErrors: (errors: ValidationError[]) => void;
-    /**
-     * Clear errors. Pass a path to clear errors for a single field;
-     * call with no arguments to clear every error on the form.
+     * Input is lenient ({@link ErrorInput}): a real `Error`, a partial
+     * `{ message?, path?, code?, data? }`, or an array of either. The form
+     * stamps its own `formKey`, defaults a missing `code` to
+     * `atta:user-error`, and coerces a missing or empty `message` to
+     * `"Unknown error"` instead of throwing. A server that already emits
+     * `ValidationError[]` satisfies the input shape directly, so
+     * `form.setErrors(response.errors)` needs no adapter.
      *
-     * ```ts
-     * form.clearFieldErrors('email')   // clear one field
-     * form.clearFieldErrors()          // clear all
-     * ```
-     */
-    clearFieldErrors: (path?: string | (string | number)[]) => void;
-    /**
-     * Replace the form-level errors — the entries at the empty path
-     * (`path: []`) — without disturbing any field-level errors. Pass an
-     * empty array to clear them all.
+     * Three call forms, mirroring `setValue`:
      *
      * ```ts
-     * form.setFormErrors([{ message: 'Capacity exceeded' }])
-     * form.setFormErrors([
-     *   { message: 'Capacity exceeded', code: 'capacity:exceeded' },
-     *   { message: 'Pickup window full' },
-     * ])
-     * form.setFormErrors([])  // clear
+     * // Whole-layer replace. An entry with no `path` is a global,
+     * // form-level error (path `[]`); add a `path` to target a field.
+     * form.setErrors([{ path: ['email'], message: 'Already taken' }])
+     * form.setErrors({ message: 'Capacity exceeded' })   // global banner
+     * form.setErrors(new Error('Network unreachable'))   // message coerced
+     *
+     * // Functional update. `prev` is the current manual layer, flat.
+     * form.setErrors((prev) => [...prev, { message: 'And one more' }])
+     *
+     * // Path-scoped. The path is stamped onto every entry, and only that
+     * // path's bucket is replaced. `prev` is that path's manual errors.
+     * form.setErrors('email', [{ message: 'Already taken' }])
+     * form.setErrors(['profile', 'handle'], { message: 'Reserved' })
+     * form.setErrors('email', (prev) => prev.slice(0, 1))
      * ```
      *
-     * Only `message` is required. `code` defaults to `'atta:form-error'`.
-     * Any caller-provided `path` or `formKey` is ignored — `path` is
-     * always forced to `[]` (this API is form-level-only by definition)
-     * and `formKey` is filled in from the form instance. The lenient
-     * input shape lets you pipe `parseApiErrors` output (or any
-     * `ValidationError[]`) straight in:
+     * Replaces only the manual layer; schema/validation errors live in a
+     * separate store and merge on read. Pass `[]` to clear the manual
+     * layer (or use `clearErrors`, which also clears the schema layer).
+     */
+    setErrors: {
+        (update: (prev: ValidationError[]) => ErrorInput | ErrorInput[]): void;
+        (errors: ErrorInput | ErrorInput[]): void;
+        (path: string | (string | number)[], errors: ErrorInput | ErrorInput[] | ((prev: ValidationError[]) => ErrorInput | ErrorInput[])): void;
+    };
+    /**
+     * Clear errors at one path, or everywhere. Clears BOTH the manual
+     * layer (set through `setErrors`) and the schema/validation layer at
+     * the target. With always-on validation the schema half re-populates
+     * on the next mutation if the value is still invalid, so the cleared
+     * state is short-lived for a field that is still wrong.
      *
      * ```ts
-     * const result = parseApiErrors(payload, { formKey: form.key })
-     * if (result.ok) form.setFormErrors(result.errors)
+     * form.clearErrors('email')   // one field
+     * form.clearErrors([])        // the global, form-level bucket
+     * form.clearErrors()          // every error on the form
      * ```
-     *
-     * Form-level errors land at the empty-string path bucket
-     * (`path: ['']`). They surface in `form.meta.errors` (alongside
-     * field errors), in `form.errors()` / `form.errors([])` (whole-form
-     * subtree aggregates), and — uniquely — in `form.errors('')`,
-     * which returns ONLY the form-level bucket. They're excluded from
-     * the path-keyed `form.errors` drill proxy because no nested-object
-     * key represents the empty-string path. Read them via
-     * `meta.errors.filter(e => e.path.length === 1 && e.path[0] === '')`
-     * if you need a programmatic split.
      */
-    setFormErrors: (errors: ReadonlyArray<Partial<ValidationError> & {
-        message: string;
-    }>) => void;
-    /**
-     * Clear every form-level error. Equivalent to `setFormErrors([])`;
-     * field errors are untouched.
-     */
-    clearFormErrors: () => void;
+    clearErrors: (path?: string | (string | number)[]) => void;
     /**
      * Form-level reactive flags, counters, and aggregates (`dirty`,
      * `valid`, `submitting`, `submissionAttempts`, and the flat `errors`
@@ -4436,8 +4463,19 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * when the key leaves. `form.fields(path)` remains the single
      * aggregated container for the whole record; `record` is the
      * per-entry view.
+     *
+     * When the form root is itself a record (`useForm({ schema:
+     * z.record(K, V) })` — a dictionary form), call `form.record()` with
+     * no argument for the root entry view:
+     *
+     * ```vue
+     * <div v-for="(member, id) in form.record()" :key="id">
+     *   <input v-register="form.register(id)" />
+     *   <p v-if="member.showErrors">{{ member.firstError?.message }}</p>
+     * </div>
+     * ```
      */
-    record: <Path extends RecordPath<Form>>(path: Path) => Readonly<Record<string, FieldState<RecordValue<Form, Path>>>>;
+    record: RootRecordView<Form> & (<Path extends RecordPath<Form>>(path: Path) => Readonly<Record<string, FieldState<RecordValue<Form, Path>>>>);
     /**
      * Read-only view of the form's blank path set. Reactive — Vue 3.5
      * tracks `.has()` / `for..of` / size accesses, so consumers can drive
@@ -4465,5 +4503,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { ROOT_PATH as $, ROOT_PATH_KEY as a0, canonicalizePath as an, isPathPrefix as ao, isUnset as ap, parseDottedPath as aq, unset as ar };
-export type { AttaformDefaults as A, HistoryConfig as B, CoercionEntry as C, DefaultValuesInput as D, ErrorsProxyShape as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, IsUnion as J, JoinSegments as K, KeyofUnion as L, LiftedValueShape as M, MetaTrackerValue as N, NestedReadType as O, NestedType as P, OnError as Q, RegisterModelDynamicCustomDirective as R, OnInvalidSubmitPolicy as S, OnSubmit as T, UseFormConfiguration as U, ValidationError as V, PartialFlatPath as W, Path as X, PathKey as Y, PendingValidationStatus as Z, Primitive as _, AbstractSchema as a, ReactiveValidationStatus as a1, RegisterDirective as a2, RegisterFlatPath as a3, RegisterOptions as a4, RegisterSelectModifier as a5, RegisterTextModifier as a6, RegisterTransform as a7, Segment as a8, SetValueCallback as a9, SetValuePayload as aa, SettledValidationStatus as ab, SlimPrimitiveKind as ac, SlimRuntimeOf as ad, SubmitHandler as ae, Unset as af, ValidateOn as ag, ValidateOnConfig as ah, ValidationResponse as ai, ValidationResponseWithoutValue as aj, ValueOfUnion as ak, WriteMeta as al, WriteShape as am, SchemaFactoryOptions as as, TransformAbortHolder as at, UseFormReturnType as b, RegisterValue as c, GetDisplayState as d, ApiErrorEnvelope as e, ApiErrorDetails as f, ApiErrorEntry as g, ArrayItem as h, ArrayPath as i, CoercionRegistry as j, CoercionResult as k, CustomDirectiveRegisterAssignerFn as l, DeepPartial as m, DefaultValuesResponse as n, DefaultValuesShape as o, DisplayCtx as p, DisplayMachine as q, DisplayState as r, FieldMetaPayload as s, FieldState as t, FieldStateMap as u, FieldStateMapEntry as v, FlatPath as w, FormErrorRecord as x, FormErrorsSurface as y, FormMeta as z };
+export { ROOT_PATH as Z, ROOT_PATH_KEY as _, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
+export type { ReactiveValidationStatus as $, AttaformDefaults as A, Json 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, NestedType as O, OnError as P, OnInvalidSubmitPolicy as Q, RegisterModelDynamicCustomDirective as R, OnSubmit as S, PartialFlatPath as T, UseFormConfiguration as U, Path as V, PathKey as W, PendingValidationStatus as X, Primitive as Y, AbstractSchema as a, RegisterDirective as a0, RegisterFlatPath as a1, RegisterOptions as a2, RegisterSelectModifier as a3, RegisterTextModifier as a4, RegisterTransform 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, SchemaFactoryOptions as ar, TransformAbortHolder as as, UseFormReturnType as b, RegisterValue as c, GetDisplayState as d, ArrayItem as e, ArrayPath as f, CoercionRegistry as g, CoercionResult as h, CustomDirectiveRegisterAssignerFn as i, DeepPartial as j, DefaultValuesResponse as k, DefaultValuesShape as l, DisplayCtx as m, DisplayMachine as n, DisplayState as o, ErrorsProxyShape as p, FieldMetaPayload as q, FieldState as r, FieldStateMap as s, FieldStateMapEntry as t, FlatPath as u, FormErrorRecord as v, FormErrorsSurface as w, FormMeta as x, HistoryConfig as y, IsUnion as z };