attaform 0.14.0 → 0.15.1

package/dist/shared/{attaform.DDXrY-1Q.d.mts → attaform.0Gxd_OOx.d.cts}

@@ -1,5 +1,70 @@
 import { Ref, ObjectDirective, ComputedRef } from 'vue';
 
+/**
+ * Schema-attached field metadata — the shared types used by both Zod
+ * adapters (`attaform/zod` for v4 and `attaform/zod-v3` for v3) so a
+ * consumer's data flow reads the same shape regardless of adapter.
+ *
+ * The Zod 4 adapter creates a typed `z.registry<FieldMetaPayload>()`
+ * and writes through `schema.register(fieldMeta, payload)` (native) or
+ * the `withMeta(schema, payload)` helper. The Zod 3 adapter has no
+ * native registry — it shims a `WeakMap<ZodTypeAny, FieldMetaPayload>`
+ * with the same write API via `withMeta`.
+ *
+ * Reads are unified through `AbstractSchema.getFieldMetaAtPath(path)`,
+ * which returns a fully-resolved `ResolvedFieldMeta` (label /
+ * description / placeholder / meta) so the per-leaf and per-container
+ * `FieldState` producers in core never see the version split.
+ */
+/**
+ * The metadata a consumer attaches to a schema node — short label
+ * (presentational), longer description (helper text), placeholder
+ * (input affordance). Declared as `interface` (not `type`) so
+ * downstream apps can extend the shape via TypeScript declaration
+ * merging when they want to register richer payloads (tooltips,
+ * icons, badge counts, etc.):
+ *
+ *     declare module 'attaform/zod' {
+ *       interface FieldMetaPayload {
+ *         tooltip?: string
+ *       }
+ *     }
+ *
+ * After augmentation, `withMeta(schema, { tooltip: '…' })` is typed
+ * and `state.meta.tooltip` reads back as `string | undefined`.
+ *
+ * Every key is optional. Empty payloads (no keys registered) are
+ * indistinguishable from "not registered at all" — both surface as
+ * fallbacks (humanize for label, undefined for the rest).
+ */
+interface FieldMetaPayload {
+    label?: string;
+    description?: string;
+    placeholder?: string;
+}
+/**
+ * The fully-resolved metadata returned by
+ * `AbstractSchema.getFieldMetaAtPath(path)`. Adapters apply the
+ * precedence rules:
+ *
+ *   - `label`: registry payload → `humanize(lastSegment)`
+ *   - `description`: registry payload → schema's `.describe()` value → `undefined`
+ *   - `placeholder`: registry payload → `undefined`
+ *   - `meta`: full registered payload, frozen — empty object if nothing registered
+ *
+ * `label` is always a non-empty string at leaves (humanize fallback
+ * guarantees this for any non-numeric segment). For containers it
+ * may collapse to the empty string when the path is empty (root) or
+ * the segment is a numeric index — callers display "" or substitute
+ * a context-appropriate fallback.
+ */
+type ResolvedFieldMeta = {
+    readonly label: string;
+    readonly description: string | undefined;
+    readonly placeholder: string | undefined;
+    readonly meta: Readonly<FieldMetaPayload>;
+};
+
 /**
  * Path primitives for advanced integrations. The form library accepts
  * paths in dotted-string form (`'user.email'`) at every public API.
@@ -60,6 +125,21 @@ declare function canonicalizePath(input: string | Path): {
 declare const ROOT_PATH: Path;
 /** Stable string key for the root path. */
 declare const ROOT_PATH_KEY: PathKey;
+/**
+ * `true` when `path` starts with every segment of `prefix` (in order).
+ * The empty `prefix` matches every path — ROOT prefix is universal.
+ *
+ * Walks segments rather than `PathKey` strings because the data this
+ * helper operates on (e.g. `meta.errors[].path`) carries segment
+ * arrays directly.
+ *
+ * ```ts
+ * isPathPrefix(['cargo'], ['cargo', 'items', 0, 'sku'])  // true
+ * isPathPrefix(['cargo', 'items'], ['cargo'])             // false (path shorter)
+ * isPathPrefix([], ['anything'])                          // true (root prefix)
+ * ```
+ */
+declare function isPathPrefix(prefix: readonly Segment[], path: readonly Segment[]): boolean;
 
 /** Internal brand for the `Unset` type. Never exposed at runtime. */
 declare const _unsetBrand: unique symbol;
@@ -102,7 +182,7 @@ type Unset = typeof _unsetBrand;
  * every realm gets the same sentinel.
  *
  * @see {@link isUnset} — type guard that narrows a value back to {@link Unset}.
- * @see `docs/blank.md` — the conceptual model behind blank-aware fields.
+ * @see `docs/recipes/blank-inputs.md` — the conceptual model behind blank-aware fields.
  */
 declare const unset: Unset;
 /**
@@ -140,6 +220,87 @@ type CompleteFlatPath<Form, Key extends keyof Form = keyof Form> = IsObjectOrArr
  * (no intermediate container paths).
  */
 type FlatPath<Form, Key extends keyof Form = keyof Form, ForceFullPath extends boolean = false> = ForceFullPath extends true ? CompleteFlatPath<Form, Key> : PartialFlatPath<Form, Key>;
+/**
+ * Convert a tuple of path segments to its dotted-string equivalent.
+ *
+ *   `JoinSegments<['cargo', 'items', 0, 'sku']>` → `'cargo.items.0.sku'`
+ *
+ * Recursion depth is bounded by the tuple length (typically 3–4),
+ * not by form depth — the cost does not scale with `FlatPath<Form>`.
+ * Template literal types distribute over union members, so segments
+ * containing unions like `'pickup' | 'delivery'` propagate through
+ * to the joined path's union: `JoinSegments<['pickup' | 'delivery', 'line1']>`
+ * → `'pickup.line1' | 'delivery.line1'`. This is what makes
+ * tuple-form path APIs work cleanly inside `v-for` over a prefix
+ * variable: the joined result is checked against `FlatPath<Form>` /
+ * `RegisterFlatPath<Form>` (which already exist), so we don't
+ * enumerate a separate tuple-path union.
+ */
+type JoinSegments<S extends ReadonlyArray<string | number>, Acc extends string = ''> = S extends readonly [
+    infer Head extends string | number,
+    ...infer Rest extends ReadonlyArray<string | number>
+] ? Acc extends '' ? JoinSegments<Rest, `${Head}`> : JoinSegments<Rest, `${Acc}.${Head}`> : Acc;
+/**
+ * `true` when `T` is a union (multiple members), `false` when it's a
+ * single type. Used to gate non-homomorphic mapped-type forms so
+ * single-object types retain their homomorphic `[K in keyof T]`
+ * lookup (preserving literal keys instead of widening to an index
+ * signature).
+ */
+type IsUnion<T, U = T> = T extends T ? ([U] extends [T] ? false : true) : never;
+/**
+ * Union of all keys across all members of `T`. For a single object
+ * type this equals `keyof T`; for a discriminated union `A | B`, it
+ * produces `keyof A | keyof B` (whereas naked `keyof (A | B)` would
+ * intersect to common keys only).
+ *
+ * Paired with `ValueOfUnion` to merge variant key sets in chained
+ * metadata proxies (`form.fields`, `form.errors`) so per-variant
+ * leaves are addressable through one chained-access shape, regardless
+ * of which discriminant is currently active.
+ */
+type KeyofUnion<T> = T extends unknown ? keyof T : never;
+/**
+ * Value at key `K` across union members of `T`. Members containing
+ * `K` contribute `T[K]`; members lacking `K` contribute `undefined`.
+ *
+ * The resulting union mirrors the runtime semantics of metadata
+ * proxies: chained access works at every union member, with the leaf
+ * carrying `T | undefined` to reflect that the key is absent in some
+ * variants and the runtime returns a stable stub there.
+ */
+type ValueOfUnion<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? T[K] : undefined : never;
+/**
+ * Apply the discriminated-union "lift" to a value shape (i.e., a
+ * shape carrying actual values, not metadata leaves like
+ * `FieldState`). Single-object types map homomorphically;
+ * discriminated unions of objects merge keys via
+ * `KeyofUnion` / `ValueOfUnion` so per-variant fields are reachable
+ * through one chained-access shape.
+ *
+ * Used by `ValuesSurface` to make `form.values.cargo.permitNumber`
+ * (oversized-only) typecheck regardless of the active variant —
+ * matching the runtime, where plain JS object access on a missing
+ * variant key returns `undefined` rather than throwing.
+ *
+ * Distinct from `FieldStateMapEntry`: that variant carries
+ * `FieldState<T>` at the leaf; this one carries the leaf VALUE
+ * directly. They share the same union-merging logic but differ in
+ * what the recursion bottoms out at.
+ *
+ * Date / Map / Set / RegExp / function leaves stay opaque (not
+ * recursed into) — value reads of those types should preserve the
+ * platform shape unchanged.
+ */
+type LiftedValueShape<T> = [T] extends [
+    string | number | boolean | bigint | symbol | null | undefined
+] ? T : [T] extends [
+    Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never) => unknown)
+] ? T : [T] extends [ReadonlyArray<unknown>] ? T : [T] extends [object] ? [IsUnion<T>] extends [true] ? {
+    [K in KeyofUnion<T>]: LiftedValueShape<ValueOfUnion<T, K>>;
+} : {
+    [K in keyof T]: LiftedValueShape<T[K]>;
+} : T;
 /**
  * Recursive `Partial` — every property at every depth is optional.
  * Used as the parameter type of `defaultValues` and `reset()` so
@@ -154,11 +315,18 @@ type DeepPartial<T> = T extends Primitive ? T : T extends Array<infer ArrayItem>
  *
  *   `NestedType<{ user: { email: string } }, 'user.email'>` → `string`
  *
+ * On discriminated-union descents (e.g. `cargo` is `A | B | C`), uses
+ * `KeyofUnion` / `ValueOfUnion` so per-variant keys resolve to
+ * `T | undefined` instead of `never`. This keeps NestedType in lockstep
+ * with `FlatPath`: any path FlatPath says is reachable resolves to a
+ * useful value type (vs. silently collapsing to `never` because
+ * `keyof (A|B|C)` would be the intersection of all variants' keys).
+ *
  * TypeScript caps conditional-type recursion at around 50 levels;
  * paths deeper than that resolve to `never`. Real form schemas
  * never reach this depth.
  */
-type NestedType<RootValue, FlattenedPath extends string, FilterOutNullishTypesDuringRecursion extends boolean = true, _RootValue = FilterOutNullishTypesDuringRecursion extends false ? RootValue : NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends keyof _RootValue ? NestedType<_RootValue[Key], Rest, FilterOutNullishTypesDuringRecursion> : Key extends `${infer NumericKey extends number}` ? NumericKey extends keyof _RootValue ? NestedType<_RootValue[NumericKey], Rest, FilterOutNullishTypesDuringRecursion> : never : never : Key extends keyof _RootValue ? NestedType<_RootValue[Key], Rest, FilterOutNullishTypesDuringRecursion> : never : FlattenedPath extends `${number}` ? FlattenedPath extends keyof _RootValue ? _RootValue[FlattenedPath] : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends keyof _RootValue ? _RootValue[NumericKey] : never : never : FlattenedPath extends keyof _RootValue ? _RootValue[FlattenedPath] : never;
+type NestedType<RootValue, FlattenedPath extends string, FilterOutNullishTypesDuringRecursion extends boolean = true, _RootValue = FilterOutNullishTypesDuringRecursion extends false ? RootValue : NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, Key>, Rest, FilterOutNullishTypesDuringRecursion> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, NumericKey>, Rest, FilterOutNullishTypesDuringRecursion> : never : never : Key extends KeyofUnion<_RootValue> ? NestedType<ValueOfUnion<_RootValue, Key>, Rest, FilterOutNullishTypesDuringRecursion> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, NumericKey> : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> : never;
 type Primitive = string | number | boolean | symbol | bigint | null | undefined;
 /**
  * Distinguish a tuple from a regular array.
@@ -174,13 +342,15 @@ type IsTuple<T extends readonly unknown[]> = number extends T['length'] ? false
  * Path-resolved type for read-side APIs. Like `NestedType`, but once
  * the walk crosses an array index segment the resulting type is
  * tagged `| undefined` (the runtime can return undefined for
- * out-of-bounds reads).
+ * out-of-bounds reads). Discriminated-union descents follow the same
+ * `KeyofUnion`/`ValueOfUnion` rule as `NestedType` — per-variant
+ * keys resolve to `T | undefined`, agreeing with `FlatPath`.
  *
  * Used by `form.values.<path>` reads, `form.toRef(path)`, and
  * `register(path).innerRef` so the compile-time type honours the
  * runtime possibility of a missing array position.
  */
-type NestedReadType<RootValue, FlattenedPath extends string, _Tainted extends boolean = false, _RootValue = NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends keyof _RootValue ? NestedReadType<_RootValue[Key], Rest, true> : Key extends `${infer NumericKey extends number}` ? NumericKey extends keyof _RootValue ? NestedReadType<_RootValue[NumericKey], Rest, true> : never : never : Key extends keyof _RootValue ? NestedReadType<_RootValue[Key], Rest, _Tainted> : never : FlattenedPath extends `${number}` ? FlattenedPath extends keyof _RootValue ? _RootValue[FlattenedPath] | undefined : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends keyof _RootValue ? _RootValue[NumericKey] | undefined : never : never : FlattenedPath extends keyof _RootValue ? _Tainted extends true ? _RootValue[FlattenedPath] | undefined : _RootValue[FlattenedPath] : never;
+type NestedReadType<RootValue, FlattenedPath extends string, _Tainted extends boolean = false, _RootValue = NonNullable<RootValue>> = IsObjectOrArray<_RootValue> extends false ? never : FlattenedPath extends `${infer Key}.${infer Rest}` ? Key extends `${number}` ? Key extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, Key>, Rest, true> : Key extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, NumericKey>, Rest, true> : never : never : Key extends KeyofUnion<_RootValue> ? NestedReadType<ValueOfUnion<_RootValue, Key>, Rest, _Tainted> : never : FlattenedPath extends `${number}` ? FlattenedPath extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : FlattenedPath extends `${infer NumericKey extends number}` ? NumericKey extends KeyofUnion<_RootValue> ? ValueOfUnion<_RootValue, NumericKey> | undefined : never : never : FlattenedPath extends KeyofUnion<_RootValue> ? _Tainted extends true ? ValueOfUnion<_RootValue, FlattenedPath> | undefined : ValueOfUnion<_RootValue, FlattenedPath> : never;
 /**
  * Filter FlatPath<Form> down to the subset of paths whose resolved leaf
  * is an array. Used by the typed field-array helpers (append / remove /
@@ -485,8 +655,8 @@ type AbstractSchema<Form, GetValueFormType> = {
      *   length and reuses one element default for every position.
      * - `undefined` → the path doesn't resolve to an array OR the
      *   adapter can't determine the shape. The runtime falls back to
-     *   the legacy probe loop in this case (defensive — every built-in
-     *   adapter returns `number` or `null`).
+     *   a probe loop in this case (defensive — every built-in adapter
+     *   returns `number` or `null`).
      *
      * Wrappers (optional / nullable / default / readonly / catch /
      * pipe / lazy) are peeled transparently before the type check, so
@@ -572,7 +742,7 @@ type AbstractSchema<Form, GetValueFormType> = {
      *
      * The leaf-aware branching is what kills the FIELD_STATE_KEYS
      * shadowing problem: reserved leaf-prop names (`dirty`, `errors`,
-     * `isValid`, …) inject only at the FieldStateView terminal, not at
+     * `valid`, …) inject only at the FieldState terminal, not at
      * every depth. A schema field literally named `dirty` at depth ≥ 2
      * stays reachable as a sub-proxy or leaf in its own right.
      *
@@ -670,6 +840,34 @@ type AbstractSchema<Form, GetValueFormType> = {
      * without this hook.
      */
     getUnionDiscriminatorAtPath(path: Path): UnionDiscriminatorContext | undefined;
+    /**
+     * Return the resolved field metadata for the schema node at `path`
+     * — label, description, placeholder, plus the full registered
+     * payload as `meta` for consumer-augmented keys. Reads through the
+     * adapter's metadata mechanism (Zod 4: `z.registry()`; Zod 3:
+     * a WeakMap shim) and applies these one-way fallbacks:
+     *
+     *   - `label`:       registry payload → `humanize(lastSegment)`
+     *   - `description`: registry payload → `schema.description`
+     *                    (`.describe()` value) → `undefined`
+     *   - `placeholder`: registry payload → `undefined`
+     *   - `meta`:        registry payload (frozen) — empty object when
+     *                    nothing was registered
+     *
+     * `path` is the canonical `Segment[]`. The empty path resolves to
+     * the root schema's metadata. Multiple candidates (DU branches)
+     * resolve against the first candidate to match the existing
+     * first-success precedent in `getDefaultAtPath` /
+     * `validateAtPath` — schema authors register on the union root
+     * for shared metadata, on individual branches for variant-
+     * specific metadata.
+     *
+     * Optional. The runtime treats a missing implementation as a
+     * stub that returns `EMPTY_RESOLVED_FIELD_META` — so adapters
+     * that don't model field metadata yet can omit it; consumers
+     * see humanized fallbacks for `label`, undefined elsewhere.
+     */
+    getFieldMetaAtPath?(path: Path): ResolvedFieldMeta;
     /**
      * Return `true` if `validateAtPath` MAY have to run asynchronously
      * to surface every error this schema can produce. The runtime uses
@@ -686,6 +884,12 @@ type AbstractSchema<Form, GetValueFormType> = {
      * don't yet support detection — can omit it; async-only errors
      * then fall back to firing on first user mutation, matching the
      * pre-detection behavior. Detection is best-effort.
+     *
+     * For per-path queries, compose with `getSchemasAtPath(path)`:
+     * each candidate sub-schema exposes its own
+     * `needsAsyncValidation`, so a caller asking "does the cargo
+     * subtree contain async work?" can union the per-candidate
+     * answers without a separate top-level overload.
      */
     needsAsyncValidation?(): boolean;
 };
@@ -1288,14 +1492,18 @@ type SubmitHandler = (event?: Event) => Promise<void>;
  */
 type HandleSubmit<Form extends GenericForm> = (onSubmit: OnSubmit<Form>, onError?: OnError) => SubmitHandler;
 /**
- * Per-leaf metadata tracked alongside a field's value. Read from
- * `FieldState.meta` when type-narrowing through that surface.
+ * Per-leaf internal tracker record. Distinct from `FieldState.meta`
+ * (which surfaces as `Readonly<FieldMetaPayload>` — the registry-
+ * attached label / description / placeholder payload). Surfaced for
+ * custom-adapter authors threading metadata through their own
+ * pipelines; most consumers don't reach for it directly — the
+ * matching fields appear with friendlier shape on `FieldState`.
  *
  * - `updatedAt` — ISO timestamp of the most recent write at this path,
  *   or `null` if the field has never been written.
  * - `rawValue` — the value as it arrived (before any transform);
  *   useful for distinguishing parse-coerced reads from raw user input.
- * - `isConnected` — whether at least one DOM element bound to this
+ * - `connected` — whether at least one DOM element bound to this
  *   path is currently mounted. Flips to `false` when every binding
  *   unmounts.
  * - `formKey` — identifier of the form this metadata belongs to.
@@ -1307,7 +1515,7 @@ type MetaTrackerValue = {
     /** Value as it arrived, before any transforms. */
     rawValue: unknown;
     /** `true` while at least one binding to this path is currently mounted. */
-    isConnected: boolean;
+    connected: boolean;
     /** Form this metadata belongs to. */
     formKey: FormKey;
     /** Dotted-string path to this leaf. */
@@ -1336,7 +1544,7 @@ type MetaTrackerValue = {
      * want pre-error introspection ("the user hasn't decided yet"
      * indicator, "review unanswered fields" hint).
      *
-     * See `docs/blank.md` for the full conceptual model.
+     * See `docs/recipes/blank-inputs.md` for the full conceptual model.
      */
     blank: boolean;
 };
@@ -1500,11 +1708,17 @@ type RegisterOptions = {
  *
  * Or read `innerRef` directly when integrating with custom components.
  *
- * The remaining fields support advanced bindings (custom assigners,
- * SSR optimistic marking, persistence opt-ins). Most consumers only
- * touch `innerRef`.
+ * The returned value is a `shallowReadonly` reactive proxy: top-level
+ * reads (`rv.path`, `rv.formKey`, `rv.persist`, …) track in reactive
+ * scopes, mutations are blocked, and inner refs (`innerRef`,
+ * `displayValue`) keep their `Ref` shape.
+ *
+ * `path`, `formKey`, and `formInstanceId` are the wrapper-component
+ * primitives — a generic component using `useRegister()` can derive
+ * field state and form identity from them without re-threading props
+ * from the parent.
  */
-type RegisterValue<Value = unknown> = {
+type RegisterValue<Value = unknown> = Readonly<{
     /**
      * Live, read-only reactive value at this path. Watch it to drive
      * UI that depends on the field's current value.
@@ -1528,6 +1742,44 @@ type RegisterValue<Value = unknown> = {
      * directives signal whether the write should be persisted.
      */
     setValueWithInternalPath: (value: unknown, meta?: WriteMeta) => boolean;
+    /**
+     * Canonical, JSON-encoded path key for this binding (e.g.
+     * `'["items",0,"name"]'`). Useful for stable Map / Set keys, log
+     * messages, and equality checks against another `RegisterValue`'s
+     * path. Treat as opaque — for `form.fields(...)` / `form.values(...)`
+     * lookups inside wrapper components, use `segments` instead.
+     */
+    path: PathKey;
+    /**
+     * Structured path segments for this binding (e.g.
+     * `['items', 0, 'name']`). The consumer-friendly form for
+     * `form.fields(...)` / `form.values(...)` lookups in generic
+     * wrapper components:
+     *
+     * ```ts
+     * const rv = useRegister()
+     * const form = injectForm()
+     * const field = computed(() => form.fields(rv.value?.segments ?? []))
+     * ```
+     *
+     * Frozen at runtime so wrapper components can read it without
+     * defensive copying.
+     */
+    segments: Path;
+    /**
+     * The form's user-supplied (or auto-allocated) `key`, mirroring
+     * `form.key` on the public form API. Useful in wrapper components
+     * that target a specific form by key without prop-drilling.
+     */
+    formKey: string;
+    /**
+     * Per-mount runtime identifier for the form instance. Stable across
+     * the form's lifetime. Used by the directive to scope element
+     * registrations to a single mount and exposed here for wrapper
+     * components that need to disambiguate sibling forms with the same
+     * `key`.
+     */
+    formInstanceId: string;
     /**
      * Read-only, string-form view of the field's current value — what
      * the compile-time `:value` injection reads on every input /
@@ -1540,7 +1792,7 @@ type RegisterValue<Value = unknown> = {
      * patching `el.value` back to `'0'` (the slim default).
      */
     displayValue: Readonly<Ref<string>>;
-};
+}>;
 /**
  * Custom assigner installed on an element via the directive's
  * `[assignKey]` slot OR an `@update:registerValue` listener. Called
@@ -1738,78 +1990,21 @@ type SetValueCallback<Read, Write = Read> = (prev: Read) => Read | Write;
  *   array elements as possibly-undefined to reflect runtime reality.
  */
 type SetValuePayload<Write, Read = Write> = Write | SetValueCallback<Read, Write>;
-type DeepFlatten<T> = T extends object ? {
-    [K in keyof T]: DeepFlatten<T[K]>;
-} : T;
-/**
- * Focus / blur / touched flags for a registered field.
- *
- * - `focused` — `true` while the user is interacting with the field;
- *   `false` after blur. `null` until the field has ever been focused.
- * - `blurred` — `true` after the field has lost focus at least once.
- *   `null` before any blur event.
- * - `touched` — flips to `true` on the first blur after a focus and
- *   stays `true` thereafter. Useful for "show errors only after the
- *   user has interacted" UX.
- */
-type DOMFieldState = {
-    /** `true` while focused; `false` after blur; `null` before first focus. */
-    focused: boolean | null;
-    /** `true` once the field has lost focus at least once; `null` before. */
-    blurred: boolean | null;
-    /** Flips to `true` on the first blur after a focus and stays there. */
-    touched: boolean | null;
-};
 /**
- * Richer per-field type kept for type-level utility code (e.g.
- * higher-order helpers that pass field state around). Carries
- * `currentValue` / `originalValue` / `previousValue` (typed `Value`),
- * the same flag set as `FieldStateLeaf`, plus `meta`
- * (`MetaTrackerValue`).
+ * Per-field reactive shape returned by `form.fields.<leaf-path>` and
+ * `form.fields(path)`. Slim, readonly across the board. The unified
+ * shape replaces the older split between `FieldState` /
+ * `FieldStateBranch`: one type lives at every path, with aggregations
+ * rolled up at containers.
  *
- * `form.fields.<path>` returns the slim `FieldStateLeaf` shape;
- * pick `FieldState<Value>` for code that needs `meta` or the historical
- * `previousValue` slot.
+ * Leaf-aware: this shape only injects these keys at LEAF paths via
+ * dot-access. At container paths the proxy descends without
+ * injecting, so a schema field literally named `dirty` at depth 2+
+ * stays reachable as a descent target — no shadowing. Container
+ * call-form (`form.fields('address')`) returns a `FieldState`
+ * surface where the keys are aggregations of the descendant leaves.
  */
-type FieldState<Value = unknown> = DeepFlatten<DOMFieldState & {
-    /** Per-field metadata (timestamps, raw value, connection state). */
-    meta: MetaTrackerValue;
-    /**
-     * Validation errors for this path. Populated automatically by
-     * `handleSubmit` and per-field validation; also writable via
-     * `setFieldErrors` / `addFieldErrors`. Empty when valid — safe
-     * to read without a null check.
-     */
-    errors: ValidationError[];
-    /** The value the field was initialised with. */
-    originalValue: Value;
-    /** The value before the most recent write. */
-    previousValue: Value;
-    /** The current value at this path. */
-    currentValue: Value;
-    /** `true` when `currentValue` matches `originalValue`. */
-    pristine: boolean;
-    /** `true` when `currentValue` differs from `originalValue`. */
-    dirty: boolean;
-    /**
-     * `true` when this field is **blank** — the side-channel for
-     * storage / display divergence (numeric leaves where storage
-     * holds `0` / `0n` but the DOM shows `''`, plus any primitive
-     * leaf the consumer explicitly opted in via `unset`). Surfaces
-     * both as a top-level field here AND via `meta.blank` (the meta
-     * projection mirrors the same value). See `docs/blank.md`.
-     */
-    blank: boolean;
-}>;
-/**
- * Per-field reactive shape returned by `form.fields.<leaf-path>`.
- * Slim, readonly across the board. Leaf-aware: this shape only
- * appears at LEAF paths (primitives, dates). At container paths
- * the proxy descends without injecting these keys, so a schema
- * field literally named `dirty` at depth 2+ stays reachable as a
- * descent target — no shadowing.
- */
-type FieldStateLeaf<Value = unknown> = {
+type FieldState<Value = unknown> = {
     readonly value: Value;
     readonly original: Value;
     readonly pristine: boolean;
@@ -1817,22 +2012,121 @@ type FieldStateLeaf<Value = unknown> = {
     readonly focused: boolean | null;
     readonly blurred: boolean | null;
     readonly touched: boolean | null;
-    readonly isConnected: boolean;
+    readonly connected: boolean;
+    /**
+     * The first DOM element bound to this path via `v-register`, or
+     * `null` when none is registered (initial mount, post-unmount,
+     * SSR). "First" means first by registration order. Reach for it
+     * when you need to call a native DOM method on a field's input —
+     * `focus()`, `scrollIntoView()`, `select()`, `setSelectionRange()`,
+     * etc. — without the library having to verb every imperative:
+     *
+     * ```ts
+     * form.fields.email.element?.focus()
+     * form.fields.email.element?.scrollIntoView({ block: 'center' })
+     * ```
+     *
+     * For paths with multiple bindings (input syncing, mirrored
+     * shadow inputs), prefer `elements` and pick the right target
+     * yourself. Reactive: register / deregister triggers
+     * re-evaluation.
+     */
+    readonly element: HTMLElement | null;
+    /**
+     * Every DOM element currently bound to this path via `v-register`,
+     * in registration order. Empty array when none is registered.
+     * Two bindings to the same path are intentional — input syncing,
+     * mirrored shadow inputs:
+     *
+     * ```ts
+     * for (const el of form.fields.email.elements) el.blur()
+     * ```
+     *
+     * For the common single-binding case, reach for `element` — sugar
+     * over `elements[0] ?? null`.
+     */
+    readonly elements: readonly HTMLElement[];
     readonly updatedAt: string | null;
     readonly errors: readonly ValidationError[];
+    /**
+     * `true` while a per-field validation run is in flight at this path.
+     * Reflects field-level debounced runs (`validate-on-change`) and
+     * cross-field re-validations targeting this path. Whole-form
+     * `validate()` / `validateAsync()` calls drive `form.meta.validating`
+     * only — they don't flip per-field flags.
+     *
+     * Per-field analogue of `form.meta.validating`. Use for a tight
+     * "Checking…" indicator next to a single async-validated input
+     * without commandeering the whole-form spinner.
+     */
+    readonly validating: boolean;
+    /**
+     * `true` when this field has no errors AND no per-field validation
+     * is in flight (`errors.length === 0 && !validating`). Confidence
+     * that "we've checked, and we have no problems right now." Use for
+     * green-checkmark / `aria-invalid` UX.
+     */
+    readonly valid: boolean;
     readonly path: ReadonlyArray<string | number>;
     readonly blank: boolean;
+    /**
+     * Presentational label for this field. Resolves through the
+     * adapter's metadata mechanism — Zod 4's `z.registry()` (typed
+     * payload via `schema.register(fieldMeta, {...})` or the
+     * `withMeta()` helper); Zod 3's WeakMap shim — and falls back to
+     * a humanized form of the path's last segment when nothing has
+     * been registered. Always a string.
+     *
+     * ```ts
+     * z.string().register(fieldMeta, { label: 'Reference' })
+     * // template: <label>{{ form.fields.reference.label }}</label>
+     * ```
+     *
+     * Numeric segments (array indices) collapse to the empty string;
+     * consumers wanting "Item 3" substitute their own format.
+     */
+    readonly label: string;
+    /**
+     * Helper-text description for this field. Reads from the
+     * registered `description` first; falls back to the schema's own
+     * `.describe('...')` value (both Zod 3 and Zod 4 expose that as
+     * `schema.description`); `undefined` when neither is set.
+     *
+     * Useful for `aria-describedby`-linked help text. Distinct from
+     * `label` — descriptions are longer prose, labels are short
+     * presentational nouns.
+     */
+    readonly description: string | undefined;
+    /**
+     * Placeholder hint for input affordance. Reads from the
+     * registered `placeholder`; `undefined` otherwise.
+     */
+    readonly placeholder: string | undefined;
+    /**
+     * Full registered metadata payload, frozen — empty object when
+     * nothing has been registered. Use as an escape hatch for
+     * consumer-augmented keys (declared via TypeScript module
+     * augmentation on `FieldMetaPayload`):
+     *
+     * ```ts
+     * declare module 'attaform/zod' {
+     *   interface FieldMetaPayload { tooltip?: string }
+     * }
+     * // template: {{ form.fields.email.meta.tooltip }}
+     * ```
+     */
+    readonly meta: Readonly<FieldMetaPayload>;
 };
 /**
  * Recursive type behind `form.fields`. Leaf-aware branching: at
  * primitive paths (string, number, boolean, bigint, Date, …) the
- * proxy returns a `FieldStateLeaf`; at container paths (object,
+ * proxy returns a `FieldState`; at container paths (object,
  * array, …) the proxy descends without injecting leaf-keys.
  *
  * Field-name collisions at depth 2+ resolve unambiguously: a schema
  * field literally named `dirty` at depth 2 is reachable as a
  * descent target (`form.fields.address.dirty` returns the
- * FieldStateView for `address.dirty`). Reading `dirty` AT the
+ * FieldState for `address.dirty`). Reading `dirty` AT the
  * leaf-view (`form.fields.address.dirty.dirty`) reads the leaf's
  * own dirty boolean — path-segment and leaf-prop occupy different
  * proxy depths.
@@ -1842,22 +2136,43 @@ type FieldStateLeaf<Value = unknown> = {
  * "T extends primitive". The two stay in sync for typical schemas;
  * exotic adapter-defined leaf kinds (custom `Date`-like) may need
  * a runtime check (the runtime is authoritative).
- */
-type FieldStateMapEntry<T> = T extends string | number | boolean | bigint | symbol | null | undefined | Date ? FieldStateLeaf<T> : T extends ReadonlyArray<infer U> ? {
+ *
+ * The mapped type strips optional flags (`-?:`) because the field-
+ * state surface always exposes a record per known leaf, regardless
+ * of whether the schema field is declared `.optional()`. Optional
+ * schemas mean the VALUE can be undefined — `FieldState<string |
+ * undefined>` carries that — but the FieldState wrapper itself
+ * always exists. Without the strip, `form.fields.notes` (where
+ * `notes?: string`) would type as `FieldState<...> | undefined`,
+ * forcing consumers to optional-chain through every reactive read.
+ *
+ * For discriminated-union containers the object branch uses
+ * `[T] extends [object]` (non-distributive) plus
+ * `KeyofUnion`/`ValueOfUnion` to merge variant key sets — so
+ * `form.fields.cargo.tempMinC` (refrigerated-only) is reachable
+ * regardless of the active variant, with the leaf typed as
+ * `FieldState<number | undefined>`. Matches the runtime's stub
+ * `FieldState` for inactive-variant paths.
+ */
+type FieldStateMapEntry<T> = [T] extends [
+    string | number | boolean | bigint | symbol | null | undefined | Date
+] ? FieldState<T> : [T] extends [ReadonlyArray<infer U>] ? {
     readonly [K: number]: FieldStateMapEntry<U>;
-} : T extends object ? {
-    readonly [K in keyof T]: FieldStateMapEntry<T[K]>;
-} : FieldStateLeaf<T>;
+} : [T] extends [object] ? [IsUnion<T>] extends [true] ? {
+    readonly [K in KeyofUnion<T>]-?: FieldStateMapEntry<ValueOfUnion<T, K>>;
+} : {
+    readonly [K in keyof T]-?: FieldStateMapEntry<T[K]>;
+} : FieldState<T>;
 /**
  * Type of `form.fields` — leaf-aware drillable callable Proxy. At
- * a leaf path the proxy resolves to a `FieldStateLeaf<Value>`; at
+ * a leaf path the proxy resolves to a `FieldState<Value>`; at
  * a container path it returns a sub-proxy you can keep drilling.
  *
  * Augmented with the callable signatures so dot-access and function-
  * call coexist on the same identifier:
  *
  * ```ts
- * form.fields.email.value           // string (leaf-prop on FieldStateView)
+ * form.fields.email.value           // string (leaf-prop on FieldState)
  * form.fields('email').value        // function-call (dynamic / programmatic)
  * form.fields(['users', 0, 'name']) // path-array form
  * form.fields()                     // root proxy
@@ -1868,12 +2183,38 @@ type FieldStateMapEntry<T> = T extends string | number | boolean | bigint | symb
  * string as a single key. Use chained dot/bracket or the callable
  * form.
  */
-type FieldStateMap<Form extends GenericForm> = {
-    readonly [K in keyof Form]: FieldStateMapEntry<Form[K]>;
-} & {
-    (path: string): unknown;
-    (path: ReadonlyArray<string | number>): unknown;
-    (): FieldStateMap<Form>;
+type FieldStateMap<Form extends GenericForm> = ([IsUnion<Form>] extends [true] ? {
+    readonly [K in KeyofUnion<Form>]-?: FieldStateMapEntry<ValueOfUnion<Form, K>>;
+} : {
+    readonly [K in keyof Form]-?: FieldStateMapEntry<Form[K]>;
+}) & {
+    /**
+     * Dotted-string fallback for dynamic paths. Returns
+     * `FieldState<unknown>` — the runtime always lands on a FieldState
+     * terminal at any depth (leaf or container). Cast to
+     * `FieldState<TypedValue>` when the caller knows the leaf type.
+     */
+    (path: string): FieldState<unknown>;
+    /**
+     * Tuple-segment form. Returns the typed `FieldStateMapEntry` for
+     * the resolved path when the tuple resolves to a known path.
+     * Equivalent to `form.fields[a][b][...]` but useful when the path
+     * is built from variables.
+     */
+    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): FieldStateMapEntry<NestedType<Form, JoinSegments<S>>>;
+    /**
+     * Dynamic-array fallback for callers passing `Path`-typed (runtime)
+     * segment arrays — e.g. forwarding `RegisterValue.segments` to
+     * resolve a field view. Returns `FieldState<unknown>`; cast when
+     * the value type is known.
+     */
+    (segments: ReadonlyArray<string | number>): FieldState<unknown>;
+    /**
+     * No-arg call returns the root FieldState — same as
+     * `form.fields([])`. Aggregates over the whole form (one
+     * conjunction over every active-variant leaf).
+     */
+    (): FieldState<Form>;
 };
 /**
  * Untyped error map keyed by dotted-string path. The same data
@@ -1919,12 +2260,27 @@ type FormErrorRecord = Record<string, ValidationError[]>;
  */
 type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
     (path: string): readonly ValidationError[] | undefined;
-    (path: ReadonlyArray<string | number>): readonly ValidationError[] | undefined;
-    (): FormErrorsSurface<Form>;
+    /**
+     * Tuple-segment form. Validated against `FlatPath<Form>` so literal
+     * tuples that don't resolve to a known path fail at the call site.
+     * Dynamic `Path`-typed inputs hit the untyped fallback overload below.
+     */
+    <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[] | undefined;
+    (segments: ReadonlyArray<string | number>): readonly ValidationError[] | undefined;
+    /**
+     * No-arg call returns the form-level error aggregate — same as
+     * `form.errors([])` and `form.meta.errors`. `undefined` when the
+     * form has no errors; readonly array otherwise.
+     */
+    (): readonly ValidationError[] | undefined;
 };
-type ErrorsProxyShape<T> = T extends string | number | boolean | bigint | symbol | null | undefined | Date ? readonly ValidationError[] | undefined : T extends ReadonlyArray<infer U> ? {
+type ErrorsProxyShape<T> = [T] extends [
+    string | number | boolean | bigint | symbol | null | undefined | Date
+] ? readonly ValidationError[] | undefined : [T] extends [ReadonlyArray<infer U>] ? {
     readonly [K: number]: ErrorsProxyShape<U>;
-} : T extends object ? {
+} : [T] extends [object] ? [IsUnion<T>] extends [true] ? {
+    readonly [K in KeyofUnion<T>]: ErrorsProxyShape<ValueOfUnion<T, K>>;
+} : {
     readonly [K in keyof T]: ErrorsProxyShape<T[K]>;
 } : readonly ValidationError[] | undefined;
 /**
@@ -1948,8 +2304,18 @@ type ErrorsProxyShape<T> = T extends string | number | boolean | bigint | symbol
  * intentionally NOT supported — JS object semantics treat the dotted
  * string as a single key. Use chained dot/bracket or the callable
  * form.
- */
-type ValuesSurface<F> = Readonly<F> & {
+ *
+ * The chained shape applies the discriminated-union lift via
+ * `LiftedValueShape<F>` so per-variant keys are reachable without
+ * narrowing first (e.g. `form.values.cargo.permitNumber` types as
+ * `string | undefined` regardless of which cargo variant is active —
+ * matching the runtime, where plain JS object access on a missing
+ * variant key returns `undefined`). The strict-variant shape is
+ * still required at the WRITE side: `setValue` and `defaultValues`
+ * use the un-lifted `WriteShape` so consumers can't accidentally
+ * hand the form a partial / cross-variant object.
+ */
+type ValuesSurface<F> = Readonly<LiftedValueShape<F>> & {
     (path: string): unknown;
     (path: ReadonlyArray<string | number>): unknown;
     (): Readonly<F>;
@@ -2021,13 +2387,13 @@ type ApiErrorEnvelope = {
  * the reactive object:
  *
  * ```vue
- * <button :disabled="form.meta.isSubmitting">Save</button>
+ * <button :disabled="form.meta.submitting">Save</button>
  * ```
  *
  * Watch a single field via the getter form:
  *
  * ```ts
- * watch(() => form.meta.isSubmitting, (value) => …)
+ * watch(() => form.meta.submitting, (value) => …)
  * ```
  *
  * Per-field state (touched, dirty, errors) lives behind
@@ -2038,33 +2404,13 @@ type ApiErrorEnvelope = {
  * the current values; use `toRefs()` if you need reactive handles
  * to individual fields.
  */
-interface FormMeta {
-    /**
-     * `true` when any field's current value differs from its initial
-     * value. `false` for a pristine form and for one where every change
-     * has been undone. Restore the pristine baseline via `reset()`.
-     *
-     * Note: object/array leaves are compared by reference, so replacing
-     * an array with an equal copy still reads as dirty.
-     */
-    readonly isDirty: boolean;
-    /**
-     * `true` when the form currently has no validation errors. Flips
-     * with every `validate()` / `handleSubmit` outcome.
-     */
-    readonly isValid: boolean;
+type FormMeta<F = unknown> = FieldState<F> & {
     /**
      * `true` while a `handleSubmit`-produced submit handler is running.
      * Covers both the validation phase and your async submit callback.
      * Useful for disabling the submit button.
      */
-    readonly isSubmitting: boolean;
-    /**
-     * `true` while any validation run is in flight (the reactive
-     * `validate()` re-run, an imperative `validateAsync()`, or the
-     * pre-submit validation inside `handleSubmit`).
-     */
-    readonly isValidating: boolean;
+    readonly submitting: boolean;
     /**
      * How many times the submit handler has been invoked, regardless of
      * outcome (validation failure, callback success, callback throw).
@@ -2091,33 +2437,6 @@ interface FormMeta {
      * `canUndo` / `canRedo` instead.
      */
     readonly historySize: number;
-    /**
-     * Flat aggregate of EVERY validation error in the form — schema-
-     * keyed entries, form-level errors (path: []), unmapped server
-     * errors (paths not in `FlatPath`), and cross-field-refine errors
-     * (paths at containers). Reads as English: "the form's errors."
-     *
-     * Unlike `form.errors.<path>` (per-leaf, active-path-filtered),
-     * `form.meta.errors` is unfiltered — inactive-variant errors stay
-     * in the array. Consumers who want only addressable errors filter
-     * the array themselves (`form.meta.errors.filter(e => …)`).
-     *
-     * Common patterns:
-     *
-     * ```vue
-     * <p v-if="form.meta.errors.length">{{ form.meta.errors.length }} issue(s)</p>
-     * <ul>
-     *   <li v-for="err in form.meta.errors" :key="err.path.join('.')">
-     *     {{ err.path.join('.') || 'form' }}: {{ err.message }}
-     *   </li>
-     * </ul>
-     * ```
-     *
-     * The array re-allocates on any underlying store change (schema /
-     * derived-blank / user); reactivity propagates through the standard
-     * Vue computed graph.
-     */
-    readonly errors: readonly ValidationError[];
     /**
      * Per-`useForm()`-call identity. Stable for the lifetime of one
      * `useForm()` call; new on every fresh mount. Orthogonal to
@@ -2141,7 +2460,7 @@ interface FormMeta {
      *   (drag-reorder, etc.) — stable identity per useForm() call.
      */
     readonly instanceId: string;
-}
+};
 /**
  * The object returned by `useForm`. Holds every reactive ref, write
  * helper, and lifecycle method bound to one form.
@@ -2154,7 +2473,7 @@ interface FormMeta {
  * form.errors.email             // ValidationError[] | undefined
  * form.setValue('email', 'a@b.c')
  * form.handleSubmit(onSubmit)   // returns a submit handler
- * form.meta.isSubmitting        // form-level reactive flag
+ * form.meta.submitting        // form-level reactive flag
  * ```
  */
 type UseFormReturnType<Form extends GenericForm, GetValueFormType extends GenericForm = Form> = {
@@ -2212,16 +2531,16 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * ```
      *
      * The same proxy supports descent at every level — `address` reads
-     * the FieldStateLeaf for the address object, and `address.city`
+     * the FieldState for the address object, and `address.city`
      * descends into the nested leaf.
      *
      * Leaf values follow the slim WriteShape contract: enum-typed leaves
      * widen to their primitive supertype. The errors array, dirty flag,
      * focus state, etc. are unaffected.
      *
-     * Shadowing: at depth 2+, FieldStateLeaf keys (`dirty`, `touched`,
+     * Shadowing: at depth 2+, FieldState keys (`dirty`, `touched`,
      * `errors`, `blank`, `focused`, `blurred`, `value`,
-     * `original`, `pristine`, `isConnected`, `updatedAt`, `path`) win
+     * `original`, `pristine`, `connected`, `updatedAt`, `path`) win
      * over schema field names. Top-level fields are NOT shadowed.
      * Document edge case; rename the offending schema field if the
      * collision matters.
@@ -2283,6 +2602,13 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
          * empty; submit raises "No value supplied" for required schemas).
          */
         <Path extends FlatPath<Form>, Value extends SetValuePayload<DefaultValuesShape<NestedType<Form, Path>>, NonNullable<WriteShape<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 SetValuePayload<DefaultValuesShape<NestedType<Form, JoinSegments<S>>>, NonNullable<WriteShape<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
@@ -2311,7 +2637,7 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * if (!result.success) showErrors(result.errors)
      * ```
      *
-     * Pass a path to validate a subtree. `state.isValidating` flips
+     * Pass a path to validate a subtree. `state.validating` flips
      * `true` while the promise is in flight.
      */
     validateAsync: (path?: FlatPath<Form>) => Promise<ValidationResponseWithoutValue<Form>>;
@@ -2328,11 +2654,25 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * />
      * ```
      *
+     * Also accepts a segment-array form for callers building paths
+     * dynamically — particularly inside a `v-for` over a prefix variable
+     * where dotted-string concatenation widens the prefix's literal
+     * union to plain `string`:
+     *
+     * ```vue
+     * <fieldset v-for="block in [{ prefix: 'pickup' }, { prefix: 'delivery' }] as const">
+     *   <input v-register="form.register([block.prefix, 'line1'])" />
+     * </fieldset>
+     * ```
+     *
      * Pass `options.persist` to opt into the form's persistence
      * pipeline. Persistence requires `useForm({ persist })` configured
      * for storage activity to actually happen.
      */
-    register: <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions) => RegisterValue<NestedReadType<WriteShape<Form>, Path>>;
+    register: {
+        <Path extends RegisterFlatPath<Form, keyof Form>>(path: Path, options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<Form>, Path>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [RegisterFlatPath<Form, keyof Form>] ? unknown : never), options?: RegisterOptions): RegisterValue<NestedReadType<WriteShape<Form>, JoinSegments<S>>>;
+    };
     /**
      * The form's identifier — either the explicit `key` passed to
      * `useForm` or an auto-generated unique id when `key` was omitted.
@@ -2385,7 +2725,10 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * Prefer `form.values.email` for direct reads in templates +
      * scripts; `toRef` is for ref-shaped interop only.
      */
-    toRef: <Path extends FlatPath<Form>>(path: Path) => Readonly<Ref<NestedReadType<WriteShape<GetValueFormType>, Path>>>;
+    toRef: {
+        <Path extends FlatPath<Form>>(path: Path): Readonly<Ref<NestedReadType<WriteShape<GetValueFormType>, Path>>>;
+        <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): Readonly<Ref<NestedReadType<WriteShape<GetValueFormType>, JoinSegments<S>>>>;
+    };
     /**
      * Replace every field error for this form with the provided list.
      * Useful after `parseApiErrors` produces a fresh batch from a
@@ -2414,15 +2757,56 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      */
     clearFieldErrors: (path?: string | (string | number)[]) => void;
     /**
-     * Form-level reactive flags, counters, and aggregates (`isDirty`,
-     * `isValid`, `isSubmitting`, `submitCount`, `canUndo`,
+     * 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.
+     *
+     * ```ts
+     * form.setFormErrors([{ message: 'Capacity exceeded' }])
+     * form.setFormErrors([
+     *   { message: 'Capacity exceeded', code: 'capacity:exceeded' },
+     *   { message: 'Pickup window full' },
+     * ])
+     * form.setFormErrors([])  // clear
+     * ```
+     *
+     * 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:
+     *
+     * ```ts
+     * const result = parseApiErrors(payload, { formKey: form.key })
+     * if (result.ok) form.setFormErrors(result.errors)
+     * ```
+     *
+     * Form-level errors surface in `form.meta.errors` (alongside field
+     * errors) but are intentionally excluded from the path-keyed
+     * `form.errors` proxy (no key represents `[]` in a nested object) —
+     * read them via `meta.errors.filter(e => e.path.length === 0)` or
+     * `form.errors([])` (the call-form aggregates everywhere, including
+     * form-level errors at `path: []`).
+     */
+    setFormErrors: (errors: ReadonlyArray<Partial<ValidationError> & {
+        message: string;
+    }>) => void;
+    /**
+     * Clear every form-level error. Equivalent to `setFormErrors([])`;
+     * field errors are untouched.
+     */
+    clearFormErrors: () => void;
+    /**
+     * Form-level reactive flags, counters, and aggregates (`dirty`,
+     * `valid`, `submitting`, `submitCount`, `canUndo`,
      * `historySize`, and the flat `errors` array). See `FormMeta` for
      * the full shape. Read leaves directly with no `.value`.
      *
      * For per-field state (touched, focused, blurred, errors at one
      * path), use `form.fields.<path>` instead.
      */
-    meta: FormMeta;
+    meta: FormMeta<Form>;
     /**
      * Restore the form to its initial state. Without arguments,
      * re-applies the schema defaults (and any `defaultValues` passed
@@ -2431,10 +2815,10 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      *
      * Resets:
      *   - the form value back to defaults;
-     *   - the dirty baseline (so the next edit flips `isDirty` correctly);
+     *   - the dirty baseline (so the next edit flips `dirty` correctly);
      *   - field errors;
      *   - touched / focused / blurred per-field flags;
-     *   - submission state (`isSubmitting` / `submitCount` / `submitError`);
+     *   - submission state (`submitting` / `submitCount` / `submitError`);
      *   - the persisted draft, if persistence is configured.
      *
      * The next edit on a still-mounted opted-in input will start
@@ -2564,5 +2948,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<ReadonlySet<string>>;
 };
 
-export { ROOT_PATH as L, ROOT_PATH_KEY as Q, canonicalizePath as ac, isUnset as ad, parseDottedPath as ae, unset as af };
-export type { RegisterTransform as $, AttaformDefaults as A, PendingValidationStatus as B, CoercionRegistry as C, DeepPartial as D, PersistConfig as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, PersistConfigOptions as J, PersistIncludeMode as K, MetaTrackerValue as M, NestedReadType as N, OnError as O, Path as P, RegisterValue as R, SlimPrimitiveKind as S, ReactiveValidationStatus as T, UseFormConfiguration as U, ValidationError as V, RegisterDirective as W, RegisterFlatPath as X, RegisterOptions as Y, RegisterSelectModifier as Z, RegisterTextModifier as _, CoercionEntry as a, Segment as a0, SetValueCallback as a1, SetValuePayload as a2, SettledValidationStatus as a3, SlimRuntimeOf as a4, SubmitHandler as a5, Unset as a6, ValidateOn as a7, ValidateOnConfig as a8, ValidationResponse as a9, ValidationResponseWithoutValue as aa, WriteMeta as ab, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ApiErrorEnvelope as f, ApiErrorDetails as g, ApiErrorEntry as h, CoercionResult as i, CustomDirectiveRegisterAssignerFn as j, DefaultValuesResponse as k, FieldState as l, FieldStateLeaf as m, FieldStateMap as n, FieldStateMapEntry as o, FlatPath as p, FormErrorRecord as q, FormErrorsSurface as r, FormMeta as s, FormStorage as t, FormStorageKind as u, HistoryConfig as v, NestedType as w, OnInvalidSubmitPolicy as x, OnSubmit as y, PathKey as z };
+export { ROOT_PATH as Z, ROOT_PATH_KEY as _, canonicalizePath as ak, isPathPrefix as al, isUnset as am, parseDottedPath as an, unset as ao };
+export type { ReactiveValidationStatus as $, AttaformDefaults as A, OnInvalidSubmitPolicy as B, CoercionRegistry as C, DeepPartial as D, OnSubmit as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, Path as P, PathKey as Q, RegisterValue as R, SlimPrimitiveKind as S, PendingValidationStatus as T, UseFormConfiguration as U, ValidationError as V, PersistConfig as W, PersistConfigOptions as X, PersistIncludeMode as Y, CoercionEntry 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, SlimRuntimeOf as aa, SubmitHandler as ab, Unset as ac, ValidateOn as ad, ValidateOnConfig as ae, ValidationResponse as af, ValidationResponseWithoutValue as ag, ValueOfUnion as ah, WriteMeta as ai, WriteShape as aj, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ApiErrorEnvelope as f, ApiErrorDetails as g, ApiErrorEntry as h, ArrayItem as i, ArrayPath as j, CoercionResult as k, CustomDirectiveRegisterAssignerFn as l, DefaultValuesResponse as m, FieldMetaPayload as n, FieldState as o, FieldStateMap as p, FieldStateMapEntry as q, FlatPath as r, FormErrorRecord as s, FormErrorsSurface as t, FormMeta as u, FormStorage as v, FormStorageKind as w, HistoryConfig as x, IsUnion as y, NestedType as z };