attaform 0.22.0 → 0.24.0

package/dist/shared/{attaform.DvUH4a3o.d.cts → attaform.GJbSmwLB.d.mts}

@@ -1,4 +1,4 @@
-import { ObjectDirective, Ref, MaybeRefOrGetter, ComputedRef } from 'vue';
+import { ObjectDirective, Ref, ComputedRef } from 'vue';
 
 /**
  * Schema-attached field metadata — the shared types used by both Zod
@@ -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. */
@@ -154,42 +164,6 @@ declare const ROOT_PATH_KEY: PathKey;
  */
 declare function isPathPrefix(prefix: readonly Segment[], path: readonly Segment[]): boolean;
 
-/**
- * Per-FormStore registry tracking which DOM elements have opted into
- * persistence for which paths. Lives on the FormStore so that two SFCs
- * sharing a key share the registry — opt-ins are per-element, not
- * per-component.
- *
- * The directive's input handler computes `meta.persist` for each write
- * by calling `hasOptIn(elementId, path)` — only THIS element's writes
- * persist if THIS element opted in. Other call sites that aren't tied
- * to a single element (history undo/redo, field-array helpers, devtools
- * edits) use `hasAnyOptInForPath(path)` — persist if any element has
- * opted into that path.
- *
- * Internal data structure: `Map<PathKey, Set<elementId>>`. Small forms
- * have ~10-50 paths; iteration is cheap. All operations are O(1) given
- * (id, path).
- */
-type PersistOptInRegistry = {
-    /** Add an opt-in entry; idempotent. */
-    add(elementId: string, path: PathKey): void;
-    /** Remove a single (element, path) entry. */
-    remove(elementId: string, path: PathKey): void;
-    /** Remove every opt-in for `elementId`. Called from directive's beforeUnmount. */
-    removeAllFor(elementId: string): void;
-    /** Check whether THIS element has opted into THIS path. */
-    hasOptIn(elementId: string, path: PathKey): boolean;
-    /** Check whether ANY element has opted into this path. */
-    hasAnyOptInForPath(path: PathKey): boolean;
-    /** Iterate every path that currently has at least one opt-in. */
-    optedInPaths(): IterableIterator<PathKey>;
-    /** True iff no element has opted into any path. */
-    isEmpty(): boolean;
-    /** Drop every entry. Called from FormStore.dispose. */
-    clear(): void;
-};
-
 /** Internal brand for the `Unset` type. Never exposed at runtime. */
 declare const _unsetBrand: unique symbol;
 /**
@@ -284,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[] }`:
@@ -296,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.
  *
@@ -665,8 +648,8 @@ type DefaultValuesInput<T> = T extends string ? string | Unset : T extends numbe
 /**
  * Identifier for a form. A `FormKey` is the string passed via
  * `useForm({ key })`, used to look up a form by name from a distant
- * component, namespace persisted drafts, and label errors and
- * DevTools entries. Anonymous `useForm` calls allocate one
+ * component and to label errors and DevTools entries. Anonymous
+ * `useForm` calls allocate one
  * automatically; you only need to pick one when the form needs
  * stable identity.
  */
@@ -681,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. */
@@ -716,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> = {
@@ -830,9 +865,9 @@ type AbstractSchema<Form, GetValueFormType> = {
      *
      * 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 on opt-in async paths (the multi-tab
-     * channel name, the persistence storage key) plus a dev-only mismatch
-     * warning, so none of those bytes belong on the eager `useForm` path.
+     * 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
@@ -1394,64 +1429,11 @@ type ValidateOnConfig = {
     debounceMs?: never;
 };
 /**
- * Built-in storage backends:
- *
- * - `'local'` — browser `localStorage` (persists across tabs and reloads).
- * - `'session'` — browser `sessionStorage` (cleared when the tab closes).
- * - `'indexeddb'` — IndexedDB via a zero-dependency wrapper (handles
- *   structured-cloneable data; suitable for larger drafts).
- *
- * For anything else (encrypted storage, a native bridge, a cookie
- * store) pass a custom `FormStorage` object instead.
- */
-type FormStorageKind = 'local' | 'session' | 'indexeddb';
-/**
- * Custom persistence backend. Implement this when none of the built-in
- * `'local'` / `'session'` / `'indexeddb'` backends fit (e.g. encrypted
- * storage, a cross-window broadcast layer, or a native mobile bridge).
- *
- * All methods are async. Pass values through unchanged — `getItem`
- * should return whatever `setItem` was given, including non-string
- * values. The library handles serialization for the built-in
- * `'local'` / `'session'` backends; custom adapters can store the
- * value directly if their backing store accepts structured data.
- *
- * `listKeys(prefix)` returns every key starting with `prefix`. The
- * library uses it on mount to clean up entries left over from older
- * schema versions (each persisted entry carries a schema fingerprint
- * suffix; mismatched entries are dropped automatically).
- */
-type FormStorage = {
-    /** Fetch the value previously stored under `key`. Resolve to `null`/`undefined` for misses. */
-    getItem(key: string): Promise<unknown>;
-    /** Persist `value` under `key`. */
-    setItem(key: string, value: unknown): Promise<void>;
-    /** Remove the entry at `key`. No-op if not present. */
-    removeItem(key: string): Promise<void>;
-    /** Return every key in this backend whose name starts with `prefix`. */
-    listKeys(prefix: string): Promise<string[]>;
-};
-/**
- * What to include when persisting:
- *
- * - `'form'` (default) — only the form value. Errors get repopulated
- *   by validation on reload anyway.
- * - `'form+errors'` — also persist the current error list. Useful when
- *   the error context is expensive to recompute (e.g. cross-field
- *   refinements that depend on server data).
- */
-type PersistIncludeMode = 'form' | 'form+errors';
-/**
- * Per-write metadata. Used internally to flag which writes should
- * reach the persistence layer (e.g. only writes from elements opted
- * into persistence via `register(path, { persist: true })`).
- *
- * Custom directive integrations may set `persist: true` to forward
- * a write to the configured storage adapter; otherwise leave unset.
+ * Per-write metadata. Used internally to tag writes so listeners and
+ * the write funnel can treat a write specially (a blank mark, an array
+ * structural op, a hydration replay, a per-instance config override).
  */
 type WriteMeta = {
-    /** When `true`, this write is forwarded to the configured persistence backend. */
-    readonly persist?: boolean;
     /**
      * When `true`, the path being written is added to the FormStore's
      * `blankPaths` set — meaning storage holds a real, schema-
@@ -1513,159 +1495,16 @@ type WriteMeta = {
         readonly rememberVariants?: boolean;
     };
     /**
-     * When `true`, marks this `applyFormReplacement` call as the
-     * persistence hydration step. Modules that snapshot the form state
-     * (notably the history module) treat hydration as the baseline:
-     * stacks reset to a single seed of the post-hydration value, so a
-     * subsequent `undo()` can't recover the transient pre-hydration
-     * default. Internal — set by `wirePersistence`. Don't set from
-     * consumer code.
+     * When `true`, marks this `applyFormReplacement` call as a hydration
+     * step (the async-`defaultValues` / `activate()` / `rehydrate()`
+     * path). Modules that snapshot the form state (notably the history
+     * module) treat hydration as the baseline: stacks reset to a single
+     * seed of the post-hydration value, so a subsequent `undo()` can't
+     * recover the transient pre-hydration default. Internal — set by the
+     * activate path in `create-form-store.ts`. Don't set from consumer
+     * code.
      */
     readonly hydration?: boolean;
-    /**
-     * When `true`, this write originated from a sibling tab's
-     * BroadcastChannel broadcast (the multi-tab sync module's inbound
-     * apply). Listeners that initiate side effects check this flag to
-     * avoid amplification loops and spurious side effects:
-     *
-     * - The multi-tab sync OUTBOUND broadcaster skips so a remote-driven
-     *   write doesn't echo back across the channel.
-     * - The history module updates its diff anchor but does NOT push a
-     *   delta — remote writes aren't part of the local user's undo
-     *   timeline.
-     * - The persistence writer skips so the receiving tab doesn't
-     *   double-persist a value the originating tab already wrote.
-     *
-     * Internal — set by `createMultiTabSyncModule`. Don't set from
-     * consumer code.
-     */
-    readonly crossTab?: boolean;
-    /**
-     * When `true`, this write lands normally (storage, validation,
-     * persistence, history) but does NOT notify `form.onChange` handlers.
-     * The side-channel reacts to user edits, not programmatic rebaselines:
-     * `reset()` tags its replacement with this flag, and the public
-     * `setValue(path, value, { silent: true })` option forwards it so a
-     * consumer hydrating the form (loading a saved record into the fields)
-     * can land values without echoing each one back through an autosave
-     * loop. The store's internal taggers and that single consumer-facing
-     * option are the only writers.
-     */
-    readonly silent?: boolean;
-};
-/** Options for a `setValue` write. */
-type SetValueOptions = {
-    /**
-     * When `true`, the write lands normally (storage, validation, persistence,
-     * history) but does NOT notify `form.onChange` handlers. Use it to hydrate
-     * the form (load a saved record into the fields) without echoing every
-     * field back through an autosave loop.
-     */
-    readonly silent?: boolean;
-};
-/**
- * A source address for `form.onChange` — the subtree(s) a handler reacts to.
- *
- * - a dotted path string (`'user.email'`) — one leaf or subtree;
- * - a list of path strings (`['shipping', 'billing']`) — react to any of
- *   several paths; the handler fires once per matched path, `ctx.path`
- *   distinguishing which;
- * - a getter or ref / computed resolving to either — re-read on each write,
- *   so the aim can follow a moving target (the active list row). Re-aiming
- *   is never itself a trigger; only a real write dispatches.
- *
- * Omit the source entirely (`form.onChange(handler)`) to react to the whole
- * form. An empty list (`form.onChange([], handler)`) lists zero paths, so it
- * never fires — that is a deliberate no-op, NOT a shorthand for the root.
- */
-type OnChangeSource = MaybeRefOrGetter<string | readonly string[]>;
-/**
- * Context handed to an `onChange` handler alongside the changed value.
- *
- * `onChange` is a pure side-channel: it reacts to value changes and runs
- * side effects, but never touches the form's own lifecycle. Nothing a
- * handler does here marks the form dirty, pending, or validating — autosave
- * status lives in the consumer's own state, validation in `.refine` and
- * `field.show*`.
- */
-type OnChangeContext<FormApi = unknown> = {
-    /**
-     * The source path this fire is for, in dotted form (`'user.email'`).
-     * The empty string `''` is the whole form (a root handler). For a
-     * multi-path source, the handler fires once per matched path and `path`
-     * names which one.
-     */
-    readonly path: string;
-    /**
-     * The value at the source path BEFORE this change, seeded at registration.
-     * Accurate for leaf sources. For a container or the whole form, an
-     * in-place leaf edit preserves the container's reference, so `previous`
-     * can be reference-equal to the current value (Vue's deep-watch gotcha) —
-     * snapshot inside the handler if a true container diff is needed.
-     */
-    readonly previous: unknown;
-    /**
-     * Aborted when a newer write to the same source supersedes this run. A
-     * debounced or awaiting handler should bail on `signal.aborted` (or pass
-     * `signal` straight to `fetch`) so superseded work cancels itself.
-     */
-    readonly signal: AbortSignal;
-    /** Retry counter — `0` on the first run, incremented by `onError`'s `retry()`. */
-    readonly attempt: number;
-    /**
-     * The form handle, so a portable `useForm({ onChange })` handler can reach
-     * back into the form (e.g. `ctx.form.validateAsync(ctx.path)` to gate an
-     * autosave on validity). Typed precisely by the `form.onChange` overload.
-     */
-    readonly form: FormApi;
-    /**
-     * The leaf path(s), in dotted form, that actually changed in this
-     * dispatch. For a leaf source this is just `[path]`; for a container or
-     * the whole form it is every changed descendant.
-     */
-    readonly changed: readonly string[];
-};
-/**
- * Context handed to an `onChange` handler's `onError` callback when the
- * handler throws or rejects.
- */
-type OnChangeErrorContext<FormApi = unknown> = {
-    /** The source path this run was for, in dotted form (`''` for the whole form). */
-    readonly path: string;
-    /** The value passed to the handler that failed. */
-    readonly value: unknown;
-    /** The attempt number that failed (`0` on the first run). */
-    readonly attempt: number;
-    /**
-     * Re-run the handler with the same value and `attempt + 1`. A no-op once a
-     * newer write has superseded this run — stale work is never resurrected.
-     * Backoff and a retry cap are the consumer's to impose.
-     */
-    readonly retry: () => void;
-    /** The form handle. Typed precisely by the `form.onChange` overload. */
-    readonly form: FormApi;
-};
-/** A reaction to form value changes. Its return is ignored; throws route to `onError`. */
-type OnChangeHandler<Value = unknown, FormApi = unknown> = (value: Value, ctx: OnChangeContext<FormApi>) => void | Promise<void>;
-/** Handles a throw / rejection from an `onChange` handler. Must not throw. */
-type OnChangeErrorHandler<FormApi = unknown> = (error: unknown, ctx: OnChangeErrorContext<FormApi>) => void;
-/** Options for `form.onChange`. */
-type OnChangeOptions<FormApi = unknown> = {
-    /**
-     * Called when the handler throws or its promise rejects. Without it, a
-     * failure is swallowed (logged in dev). `onChange` never throws into the
-     * write that triggered it.
-     */
-    readonly onError?: OnChangeErrorHandler<FormApi>;
-};
-/**
- * The `useForm({ onChange })` option — a whole-form handler registered at
- * construction, bound to the form's lifetime. Either a bare handler or a
- * `{ handler, onError }` pair.
- */
-type OnChangeConfig<Value = unknown, FormApi = unknown> = OnChangeHandler<Value, FormApi> | {
-    readonly handler: OnChangeHandler<Value, FormApi>;
-    readonly onError?: OnChangeErrorHandler<FormApi>;
 };
 /**
  * Undo/redo configuration passed via `useForm({ history })`.
@@ -1731,81 +1570,6 @@ type FormHistoryNamespace = {
      */
     readonly size: number;
 };
-/**
- * Full options bag for `useForm({ persist })`. Use this when you need
- * to override defaults beyond picking the backend.
- *
- * For backend-only setup, the shorthand forms are equivalent:
- *
- * ```ts
- * useForm({ persist: 'local' })
- * // same as
- * useForm({ persist: { storage: 'local' } })
- * ```
- */
-type PersistConfigOptions = {
-    /**
-     * Where to persist. Pass `'local'` / `'session'` / `'indexeddb'` to
-     * use a built-in backend, or a custom `FormStorage` object for
-     * anything else. The built-in backends are loaded on demand, so
-     * picking `'local'` doesn't pull in IndexedDB code.
-     */
-    storage: FormStorageKind | FormStorage;
-    /**
-     * Storage key namespace. Defaults to `attaform:${formKey}`.
-     * Override when you need a custom prefix (e.g. multi-tenant apps
-     * where the same form key may exist per-tenant).
-     */
-    key?: string;
-    /**
-     * How long to wait after the last mutation before writing. Default
-     * `300` ms.
-     *
-     * Pass `0` to disable debouncing — every form change writes to the
-     * storage adapter immediately, no `setTimeout` indirection. Almost
-     * never the right choice for production (the storage adapter sees
-     * every keystroke), but useful for tests or for diagnosing perceived
-     * lag.
-     */
-    debounceMs?: number;
-    /**
-     * What to persist. `'form'` (default) is sufficient for most cases —
-     * fresh validation on reload repopulates errors. Pick `'form+errors'`
-     * when the error state is expensive to recompute (e.g. server-side
-     * cross-field validation).
-     */
-    include?: PersistIncludeMode;
-    /**
-     * When `true` (default), the persisted entry is wiped after
-     * `handleSubmit`'s submit callback resolves successfully. Set to
-     * `false` if you need the draft to survive across submissions.
-     */
-    clearOnSubmitSuccess?: boolean;
-};
-/**
- * Persistence configuration for `useForm({ persist })`. Off by default —
- * with no config, the form does no reads, no writes, and pulls in no
- * storage code.
- *
- * Three input forms; pick the one that reads best at the call site:
- *
- * ```ts
- * // shorthand: built-in backend
- * useForm({ persist: 'local' })
- *
- * // shorthand: custom adapter
- * useForm({ persist: encryptedStorage })
- *
- * // full options bag
- * useForm({ persist: { storage: 'local', debounceMs: 500 } })
- * ```
- *
- * Per-field opt-in: setting `persist` is necessary but not sufficient.
- * Each field that should actually persist also needs
- * `register('foo', { persist: true })` — sensitive fields must opt in
- * explicitly so they don't accidentally land in client-side storage.
- */
-type PersistConfig = FormStorageKind | FormStorage | PersistConfigOptions;
 /**
  * Configuration object passed to `useForm`. All fields except `schema`
  * are optional.
@@ -1816,7 +1580,6 @@ type PersistConfig = FormStorageKind | FormStorage | PersistConfigOptions;
  *   defaultValues: { email: '' },
  *   validateOn: 'change',
  *   debounceMs: 200,
- *   persist: 'local',
  * })
  * ```
  */
@@ -1846,8 +1609,7 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * - to look it up from a distant component via `injectForm(key)`;
      * - to share state across components (multiple `useForm({ key })`
      *   calls with the same key resolve to the same form);
-     * - to give DevTools and validation errors a recognisable label;
-     * - to namespace persisted drafts.
+     * - to give DevTools and validation errors a recognisable label.
      *
      * Keys starting with `__atta:` are reserved for internal use and
      * throw `ReservedFormKeyError` if passed.
@@ -1951,41 +1713,6 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * per blur for `<input v-register.lazy>`).
      */
     debounceMs?: number;
-    /**
-     * A whole-form `onChange` handler, registered at construction and bound to
-     * the form's lifetime. The same side-channel as `form.onChange(handler)`,
-     * but declared in the options bag so it travels with the form (handy for a
-     * `useAutosave`-style composable). Pass a handler, or `{ handler, onError }`.
-     *
-     * For path-scoped reactions, call `form.onChange('path', handler)` on the
-     * returned form instead. `onChange` never touches the form's own
-     * lifecycle — keep validation in `.refine` and `field.show*`.
-     */
-    onChange?: OnChangeConfig<Form, UseFormReturnType<Form>>;
-    /**
-     * Opt-in persistence of the form's draft state. Off by default —
-     * with no config, no reads, no writes, no storage code is loaded.
-     *
-     * Three input forms; pick the one that reads best:
-     *
-     * ```ts
-     * useForm({ persist: 'local' })            // built-in backend
-     * useForm({ persist: encryptedStorage })   // custom backend
-     * useForm({ persist: { storage: 'local', debounceMs: 500 } })
-     * ```
-     *
-     * Per-field opt-in is required: every field that should actually
-     * persist needs `register(path, { persist: true })`. Without any
-     * opt-ins, the form mounts but never writes to storage — and a
-     * dev-mode warning surfaces the misconfiguration. This guard
-     * prevents sensitive fields from accidentally leaking to
-     * client-side storage.
-     *
-     * Switching backends across reloads (e.g. `'local'` → `'session'`)
-     * automatically clears the previous backend's entry so old drafts
-     * don't orphan.
-     */
-    persist?: PersistConfig;
     /**
      * Opt-in undo/redo. Off by default. `true` enables with a 128-position
      * cap; `{ max: N }` tunes the cap.
@@ -2013,12 +1740,8 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * every switch (the data is gone). The new variant initializes
      * from its slim default.
      *
-     * Memory is in-memory only and does not survive reload. Persisted
-     * state restores values into form storage on hydration, but
-     * variant memory starts empty — the first discriminator switch
-     * after reload loses any persisted typing in the outgoing variant.
-     * Consumers needing cross-session continuity must persist beyond
-     * the variant boundary themselves.
+     * Memory is in-memory only and does not survive a fresh mount: a
+     * page reload starts every discriminator's variant memory empty.
      *
      * `reset()` clears variant memory. `resetField(path)` clears any
      * memory entry whose union path equals or sits under `path`.
@@ -2074,54 +1797,6 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * and the broader description of where the cap is read.
      */
     maxRecursionDepth?: number;
-    /**
-     * Override the path-segment name stems treated as sensitive for this
-     * form. Sensitive paths are excluded from persistence writes and
-     * multi-tab sync broadcasts. (DevTools renders raw values by design;
-     * it does not redact.)
-     *
-     * Resolution: per-form value (this field) > global default
-     * (`createAttaform({ defaults: { sensitiveNames } })`) > library
-     * default (`DEFAULT_SENSITIVE_NAMES`).
-     *
-     * Pass an empty array `[]` as the explicit opt-out — "nothing is
-     * sensitive on this form" — for fully-trusted internal tooling.
-     * See `AttaformDefaults.sensitiveNames` for composition examples.
-     */
-    sensitiveNames?: readonly string[];
-    /**
-     * Cross-tab synchronisation via BroadcastChannel. **Defaults to
-     * `false` (opt-in).** Setting `true` on a keyed `useForm` callsite
-     * auto-pairs the form with same-keyed siblings in other same-origin
-     * tabs and mirrors their mutations in near real-time.
-     *
-     * **Resolution order (per-register override > per-form > global > library):**
-     *
-     *   register(path, { multiTab })  >  useForm({ multiTab })  >  AttaformDefaults.multiTab  >  library default (`false`)
-     *
-     * **Why opt-in.** Same-keyed forms broadcasting by default leaks
-     * surprise: a user editing in one tab sees their values appear in a
-     * sibling tab they forgot was open, including PII / PHI for forms
-     * that don't explicitly use `sensitiveNames`. Mirrors the `persist`
-     * default (also opt-in): both opt-in surfaces compose into one
-     * consistent "richer state needs explicit consent" rule.
-     *
-     * **What's stripped even when opt-in.** `File` and `Blob` values
-     * never traverse the channel regardless of this flag (security +
-     * `structuredClone` cost). Sensitive-named paths (via
-     * `sensitiveNames`) are stripped both directions. See the
-     * multi-tab sync page for the full security model.
-     *
-     * **Secure-context requirement.** Even with `multiTab: true`, sync
-     * is silently disabled outside `window.isSecureContext === true`
-     * (HTTPS or localhost). On plain HTTP a one-shot dev warning fires
-     * and the module noops.
-     *
-     * **Anonymous (auto-keyed) forms skip sync entirely** — without a
-     * consumer-supplied `key`, cross-tab identity is undefined and the
-     * channel would be solo by construction.
-     */
-    multiTab?: boolean;
     /**
      * Whether `v-register` automatically manages aria attributes
      * (`aria-invalid`, `aria-busy`, `aria-required`, `aria-describedby`)
@@ -2178,8 +1853,8 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
  * app-level default is fine — forms that switch to `'blur'` /
  * `'submit'` simply ignore the inherited `debounceMs`.
  *
- * `schema`, `key`, `defaultValues`, and `persist` are not configurable
- * here — they belong on the per-form call.
+ * `schema`, `key`, and `defaultValues` are not configurable here —
+ * they belong on the per-form call.
  */
 type AttaformDefaults = {
     /** Default for `useForm({ strict })`. Default `true`. */
@@ -2304,56 +1979,6 @@ type AttaformDefaults = {
      * confident the recursion is bounded by the actual data shape.
      */
     maxRecursionDepth?: number;
-    /**
-     * Override the path-segment name stems treated as sensitive.
-     * Sensitive paths are excluded from persistence writes and multi-tab
-     * sync broadcasts — one configurable source of truth across those
-     * surfaces. (DevTools renders raw values by design; it does not
-     * redact.)
-     *
-     * Library default is `DEFAULT_SENSITIVE_NAMES` (exported from
-     * `attaform`); compose to extend:
-     *
-     * ```ts
-     * import { DEFAULT_SENSITIVE_NAMES, createAttaform } from 'attaform'
-     *
-     * createAttaform({
-     *   defaults: { sensitiveNames: [...DEFAULT_SENSITIVE_NAMES, 'mrn', 'tax_id'] }
-     * })
-     * ```
-     *
-     * Pass an empty array `[]` as the explicit opt-out — "nothing is
-     * sensitive" — for fully-trusted internal tooling. When present at
-     * the per-form level via `useForm({ sensitiveNames })`, the per-form
-     * list REPLACES the global one (consumers compose their own
-     * additive lists via the exported default).
-     */
-    sensitiveNames?: readonly string[];
-    /**
-     * App-wide default for `useForm({ multiTab })`. Library default is
-     * `false` (opt-in) — same posture as `persist`. Set to `true` once
-     * at the plugin level to enable cross-tab sync for every form in
-     * the app by default; individual forms can still opt out via
-     * `useForm({ multiTab: false })`.
-     *
-     * **Resolution order (per-form wins):**
-     *
-     *   useForm({ multiTab })  >  AttaformDefaults.multiTab  >  library default (`false`)
-     *
-     * **Why opt-in.** Auto-broadcasting same-keyed forms surprises users
-     * (a value typed in one tab appearing in another they forgot was
-     * open) and leaks state for forms that don't explicitly use
-     * `sensitiveNames`. Paired with `persist` (also opt-in), the two
-     * "richer state" surfaces follow one consistent rule: explicit
-     * consent.
-     *
-     * **Secure-context gate.** Even with `multiTab: true`, sync only
-     * activates over HTTPS or localhost. On plain HTTP, the module
-     * silently noops with a one-shot dev-mode warning — production
-     * deployments MUST be served over HTTPS for sync to function. See
-     * the multi-tab-sync recipe's Security section for the threat model.
-     */
-    multiTab?: boolean;
     /**
      * App-wide default for `useForm({ autoAria })`. Library default is
      * `true`: `v-register` keeps `aria-invalid` / `aria-busy` /
@@ -2570,7 +2195,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
@@ -2674,55 +2299,10 @@ type CoercionEntry<I extends SlimPrimitiveKind = SlimPrimitiveKind, O extends Sl
  */
 type CoercionRegistry = readonly CoercionEntry[];
 /**
- * Options for `register(path, options)`. Per-field rather than
- * per-form so each persisted path is opted in at its own call site —
- * adding a new field can't accidentally leak into the persistence
- * pipeline unless the field's `register` call says so explicitly.
+ * Options for `register(path, options)`. Per-field configuration
+ * applied at the binding's own call site.
  */
 type RegisterOptions = {
-    /**
-     * Opt this field into the form's persistence pipeline. The form
-     * also needs `useForm({ persist })` configured for any storage
-     * activity to happen.
-     *
-     * Persistence follows the field's lifecycle: writes flow on
-     * mount, the field is dropped from the persisted draft on unmount.
-     * If multiple inputs bind to the same path, the path keeps
-     * persisting as long as any opted-in input is mounted.
-     *
-     * When the path looks sensitive (password / cvv / ssn / token /
-     * etc.) the opt-in is skipped with a one-shot dev warning unless
-     * `acknowledgeSensitive: true` is also set — the field simply isn't
-     * persisted (the secure default). It never throws.
-     */
-    persist?: boolean;
-    /**
-     * Suppress the sensitive-name guard. Required to persist any path
-     * whose name matches the heuristic (password, cvv, ssn, etc.).
-     * Treat this as a code-review checkpoint: setting it should be a
-     * deliberate decision that the path's data is safe to land in
-     * client-side storage for this user's session.
-     */
-    acknowledgeSensitive?: boolean;
-    /**
-     * Opt this field OUT of multi-tab sync. The form-level cascade
-     * activates sync by default; passing `multiTab: false` on a single
-     * register call keeps that path tab-local — outbound patches at
-     * the path are stripped, and inbound patches at the path are
-     * rejected (symmetric tab-local behaviour).
-     *
-     * The opt-out is downgrade-only — you cannot pass `multiTab: true`
-     * to bring sync back on a form whose form-level `multiTab` is
-     * `false` (in that case the sync module never instantiated; there's
-     * no broadcaster to opt back into).
-     *
-     * Use for fields that hold transient per-tab UI state inside an
-     * otherwise-synced form (e.g. an editor's cursor position field
-     * mirrored into the form for save-on-blur), or for individual
-     * paths the consumer wants to scope to the originating tab without
-     * disabling sync globally.
-     */
-    multiTab?: boolean;
     /**
      * Sync transformation pipeline applied to user-typed values before
      * they reach form state. Composes left-to-right: each transform
@@ -2783,7 +2363,7 @@ type RegisterOptions = {
  * Or read `innerRef` directly when integrating with custom components.
  *
  * The returned value is a `shallowReadonly` reactive proxy: top-level
- * reads (`rv.path`, `rv.formKey`, `rv.persist`, …) track in reactive
+ * reads (`rv.path`, `rv.formKey`, `rv.segments`, …) track in reactive
  * scopes, mutations are blocked, and inner refs (`innerRef`,
  * `displayValue`) keep their `Ref` shape.
  *
@@ -2803,16 +2383,14 @@ type RegisterValue<Value = unknown> = Readonly<{
      * automatically; expose it to custom integrations that need to
      * register an element manually.
      *
-     * Recording the element also enables `setValueWithInternalPath` to
-     * auto-attach per-element persist meta on writes that don't carry
-     * their own.
+     * Recording the element drives the form's element map (used for
+     * `field.meta.connected`, `focusFirstError`, and `scrollToFirstError`).
      */
     registerElement: (el: HTMLElement) => void;
     /**
      * Detach an HTML element from this binding. Pair with
-     * `registerElement` for custom integrations. Clears the recorded
-     * element so subsequent writes without explicit `meta` fall back to
-     * "no auto-persist".
+     * `registerElement` for custom integrations. Drops the element from
+     * the form's element map.
      */
     deregisterElement: (el: HTMLElement) => void;
     /**
@@ -2820,16 +2398,10 @@ type RegisterValue<Value = unknown> = Readonly<{
      * write was accepted, `false` when it was rejected (e.g. wrong
      * primitive type for the path).
      *
-     * When `meta` is undefined and the binding has a registered element,
-     * the rv consults the per-element opt-in (set by
-     * `register(path, { persist: true })` against that element) and
-     * auto-attaches `{ persist: true }` when opted in. Custom directives
-     * and consumer assigners can omit `meta` to participate in the same
-     * persistence channel the default assigner uses.
-     *
-     * Pass an explicit `meta` to override the auto-derivation, e.g.
-     * `{ persist: false }` to skip persistence for a transient write
-     * even when the element is opted in.
+     * The write path for custom directives and consumer assigners: it
+     * routes through the same funnel (and per-instance meta) as the
+     * directive's default assigner. Caller-supplied `meta` passes through
+     * unchanged.
      */
     setValueWithInternalPath: (value: unknown, meta?: WriteMeta) => boolean;
     /**
@@ -2878,55 +2450,6 @@ type RegisterValue<Value = unknown> = Readonly<{
      * `key`.
      */
     formInstanceId: string;
-    /**
-     * Whether this binding opted into persistence via `register(path, { persist: true })`.
-     * @internal
-     */
-    persist: boolean;
-    /**
-     * Whether this binding acknowledged a sensitive-name override.
-     * @internal
-     */
-    acknowledgeSensitive: boolean;
-    /**
-     * Per-element persistence opt-in registry. Used by directive integrations.
-     * @internal
-     */
-    persistOptIns: PersistOptInRegistry;
-    /**
-     * Resolved sensitive-path predicate honoring this form's
-     * `sensitiveNames` cascade. The directive calls this through
-     * `allowSensitivePersist` when a `register('path', { persist: true })`
-     * binding mounts so a per-form custom list (e.g. extending with
-     * `'mrn'`) gates persistence enrolment correctly.
-     * @internal
-     */
-    isSensitivePath: (path: Path | PathKey | string) => boolean;
-    /**
-     * Whether this binding declared `register('path', { multiTab: false })`.
-     * Drives the directive's mount/unmount lifecycle: when `false`, the
-     * directive's `created` hook bumps `state.noSyncPaths` for this
-     * path, and `beforeUnmount` decrements. When `true` (the default),
-     * the binding rides the form-level cascade.
-     * @internal
-     */
-    multiTab: boolean;
-    /**
-     * Pre-bound mount hook for `multiTab: false` bindings — calls
-     * `state.incrementNoSyncOptOut(path)` with this binding's path.
-     * `undefined` when `multiTab !== false`. The directive invokes
-     * during the mount lifecycle.
-     * @internal
-     */
-    markNoSync?: () => void;
-    /**
-     * Pre-bound unmount hook for `multiTab: false` bindings — calls
-     * `state.decrementNoSyncOptOut(path)`. Paired with `markNoSync`;
-     * the directive invokes on `beforeUnmount` (and on `beforeUpdate`
-     * when the binding transitions out of opt-out).
-     * @internal
-     */
-    unmarkNoSync?: () => void;
     /**
      * Sync transform pipeline applied by the directive's assigner to
      * user-typed values before they reach form state. See
@@ -2978,8 +2501,7 @@ type RegisterValue<Value = unknown> = Readonly<{
      * Add this field's path to the form's `blankPaths` set,
      * writing the slim default to storage. Returns the `setValueAtPath`
      * boolean (`true` accepted, `false` rejected by the slim-primitive
-     * gate). Inherits the binding's `persist` meta so the mark rides
-     * the same persistence channel as user-typed writes.
+     * gate).
      *
      * Called by the directive's input listener on numeric clear (commit
      * 5) and by the imperative `setValue(path, unset)` translation
@@ -3855,13 +3377,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[];
@@ -3991,9 +3517,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[];
 };
@@ -4049,63 +3577,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`,
@@ -4309,6 +3780,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.
@@ -4422,11 +3906,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
          * type at a leaf). Refinement-level mismatches (out-of-enum
          * values, failing format checks, etc.) succeed and surface as
          * field errors instead.
-         *
-         * Pass `{ silent: true }` to land the write without notifying
-         * `form.onChange` handlers (e.g. hydrating a saved record).
          */
-        <Value extends SetValuePayload<DefaultValuesShape<Form>, WriteShape<Form>>>(value: Value, options?: SetValueOptions): boolean;
+        <Value extends SetValuePayload<DefaultValuesShape<Form>, WriteShape<Form>>>(value: Value): boolean;
         /**
          * Write at a specific path. Pass a value or a callback receiving
          * the previous value at that path.
@@ -4444,49 +3925,14 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
          * it blank (storage holds the slim default; UI displays
          * empty; submit raises "No value supplied" for required schemas).
          */
-        <Path extends FlatPath<Form>, Value extends PathSetValuePayload<NestedType<Form, Path>>>(path: Path, value: Value, options?: SetValueOptions): boolean;
+        <Path extends FlatPath<Form>, Value extends PathSetValuePayload<NestedType<Form, Path>>>(path: Path, value: Value): boolean;
         /**
          * Tuple-segment form. Equivalent to the dotted-string overload —
          * useful when paths are built from variables or arrays:
          * `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, options?: SetValueOptions): boolean;
-    };
-    /**
-     * Subscribe to form value changes — the side-channel autosave is built on.
-     * Three call forms:
-     *
-     * - `form.onChange(handler, options?)` — react to the whole form.
-     * - `form.onChange('user.email', handler, options?)` — react to one path;
-     *   `value` is that path's value.
-     * - `form.onChange(source, handler, options?)` — react to a list of paths,
-     *   or a getter / ref resolving to a path or list (re-read on each write,
-     *   so the aim can follow a moving target like the active list row).
-     *
-     * The handler runs AFTER the value lands. Its return is ignored, and a
-     * throw or rejection routes to `options.onError`, never into the write that
-     * triggered it. Returns an idempotent `stop()`; called inside a component's
-     * setup it also stops automatically on unmount.
-     *
-     * `onChange` is a pure side-channel: nothing it does marks the form dirty,
-     * pending, or validating. Keep validation feedback in `.refine` and
-     * `field.show*`, and track autosave status in your own state.
-     *
-     * ```ts
-     * form.onChange('user.email', async (email, ctx) => {
-     *   const verdict = await ctx.form.validateAsync(ctx.path)
-     *   if (verdict.success) await api.save({ email }, { signal: ctx.signal })
-     * }, { onError: (error, ctx) => ctx.retry() })
-     * ```
-     */
-    onChange: {
-        /** React to the whole form. `value` is the current form. */
-        (handler: OnChangeHandler<ReadForm, UseFormReturnType<Form, GetValueFormType, ReadForm, K>>, options?: OnChangeOptions<UseFormReturnType<Form, GetValueFormType, ReadForm, K>>): () => void;
-        /** React to one path. `value` is that path's value. */
-        <P extends FlatPath<Form>>(source: P, handler: OnChangeHandler<NestedType<Form, P>, UseFormReturnType<Form, GetValueFormType, ReadForm, K>>, options?: OnChangeOptions<UseFormReturnType<Form, GetValueFormType, ReadForm, K>>): () => void;
-        /** React to a list of paths, or a getter / ref / computed. `value` is unknown. */
-        (source: OnChangeSource, handler: OnChangeHandler<unknown, UseFormReturnType<Form, GetValueFormType, ReadForm, K>>, options?: OnChangeOptions<UseFormReturnType<Form, GetValueFormType, ReadForm, K>>): () => void;
+        <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;
     };
     /**
      * Reactive validation status. Re-runs whenever the form (or the
@@ -4577,10 +4023,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      *
      * ```vue
      * <input v-register="form.register('email')" />
-     * <input
-     *   type="password"
-     *   v-register="form.register('password', { persist: true, acknowledgeSensitive: true })"
-     * />
+     * <input v-register="form.register('username', { transforms: [trim] })" />
      * ```
      *
      * Also accepts a segment-array form for callers building paths
@@ -4594,23 +4037,18 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * </fieldset>
      * ```
      *
-     * Pass `options.persist` to opt into the form's persistence
-     * pipeline. Persistence requires `useForm({ persist })` configured
-     * for storage activity to actually happen.
+     * Pass `options.transforms` to run a sync normalisation pipeline over
+     * 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).
@@ -4722,9 +4160,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>;
     /**
@@ -4747,76 +4185,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`
@@ -4840,11 +4263,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      *   - field errors;
      *   - touched / focused / blurred per-field flags;
      *   - submission state (`submitting` / `submissionAttempts` /
-     *     `submitted` / `submitError`);
-     *   - the persisted draft, if persistence is configured.
-     *
-     * The next edit on a still-mounted opted-in input will start
-     * persisting again automatically.
+     *     `submitted` / `submitError`).
      */
     reset: (nextDefaultValues?: DefaultValuesInput<Form>) => void;
     /**
@@ -4854,9 +4273,6 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      *
      * No-op when the path doesn't exist on the form (e.g. a typo'd
      * dynamic key).
-     *
-     * If persistence is configured, the matching subpath is removed
-     * from the persisted draft too.
      */
     resetField: (path: FlatPath<Form>) => void;
     /**
@@ -4892,8 +4308,8 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * on a `false` return.
      *
      * Sugar over `setValue(path, schema.getEmptyValueAtPath(path))` —
-     * no separate bookkeeping. Variant memory, history, persistence,
-     * and listeners all see this as a regular write at the path.
+     * no separate bookkeeping. Variant memory, history, and listeners
+     * all see this as a regular write at the path.
      *
      * `clear()` (no arg) targets the whole form. `clear('')` targets
      * the empty-string path slot SPECIFICALLY — the two are NOT
@@ -4904,33 +4320,6 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
         <Path extends FlatPath<Form> | ''>(path: Path): boolean;
         <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form> | ''] ? unknown : never)): boolean;
     };
-    /**
-     * Write the current value at `path` to storage immediately. Useful
-     * for explicit "Save draft" buttons, `beforeunload` handlers, or
-     * multi-step checkpoints where the user shouldn't wait for the
-     * debounce window.
-     *
-     * Bypasses both the per-field opt-in and the debouncer. Existing
-     * paths in the persisted draft are preserved (this is a merge,
-     * not a replace).
-     *
-     * For sensitive-looking paths, warns once and no-ops unless you pass
-     * `{ acknowledgeSensitive: true }` — it never throws. Also a no-op
-     * when `useForm({ persist })` wasn't configured.
-     */
-    persist: (path: FlatPath<Form>, options?: {
-        acknowledgeSensitive?: boolean;
-    }) => Promise<void>;
-    /**
-     * Remove data from the persisted draft. Without arguments, wipes
-     * the entire entry. With a path, removes just that subpath.
-     *
-     * Does not change the in-memory form state — pair with `reset()`
-     * / `resetField()` if you need both. Future edits to still-mounted
-     * opted-in fields will re-populate the entry. No-op when
-     * persistence isn't configured.
-     */
-    clearPersistedDraft: (path?: FlatPath<Form>) => Promise<void>;
     /**
      * Consolidated undo/redo namespace — `form.history.{undo, redo,
      * clear, canUndo, canRedo, size}`. Always present; inert when
@@ -5061,8 +4450,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
@@ -5090,5 +4490,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<BlankPathsView>;
 };
 
-export { canonicalizePath as aA, isPathPrefix as aB, isUnset as aC, parseDottedPath as aD, unset as aE, ROOT_PATH as ab, ROOT_PATH_KEY as ac };
-export type { OnChangeSource as $, AttaformDefaults as A, FormStorage as B, CoercionEntry as C, DefaultValuesInput as D, ErrorsProxyShape as E, FormKey as F, GenericForm as G, FormStorageKind as H, HandleSubmit as I, HistoryConfig as J, IsTuple as K, IsUnion as L, JoinSegments as M, KeyofUnion as N, LiftedValueShape as O, MetaTrackerValue as P, NestedReadType as Q, RegisterModelDynamicCustomDirective as R, NestedType as S, OnChangeConfig as T, UseFormConfiguration as U, ValidationError as V, OnChangeContext as W, OnChangeErrorContext as X, OnChangeErrorHandler as Y, OnChangeHandler as Z, OnChangeOptions as _, AbstractSchema as a, OnError as a0, OnInvalidSubmitPolicy as a1, OnSubmit as a2, PartialFlatPath as a3, Path as a4, PathKey as a5, PendingValidationStatus as a6, PersistConfig as a7, PersistConfigOptions as a8, PersistIncludeMode as a9, SchemaFactoryOptions as aF, TransformAbortHolder as aG, PersistOptInRegistry as aH, Primitive as aa, ReactiveValidationStatus as ad, RegisterDirective as ae, RegisterFlatPath as af, RegisterOptions as ag, RegisterSelectModifier as ah, RegisterTextModifier as ai, RegisterTransform as aj, Segment as ak, SetValueCallback as al, SetValueOptions as am, SetValuePayload as an, SettledValidationStatus as ao, SlimPrimitiveKind as ap, SlimRuntimeOf as aq, SubmitHandler as ar, Unset as as, ValidateOn as at, ValidateOnConfig as au, ValidationResponse as av, ValidationResponseWithoutValue as aw, ValueOfUnion as ax, WriteMeta as ay, WriteShape as az, 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 };