formstand 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+## 0.17.0 — 2026-09-17
+
+### Added
+
+- **`form.addErrors(errors)`.** The merge-many sibling of `setError`:
+  takes a server response's own runtime-keyed error map as-is and merges
+  it into the server channel — no per-key `FieldPath` cast, no
+  `setErrors` wholesale replacement. An empty array removes its key,
+  like `setError`. The docs' own examples now use it.
+- **`SubmitOptions.onError` and a dev-mode swallowed-failure warning.**
+  A throwing submit handler resolves `{kind: "error"}` writing no state
+  anywhere, so the fire-and-forget `handleSubmit` form could swallow a
+  save failure completely — button re-enables, zero feedback. `onError`
+  is the save-failure hook mirroring `onInvalid`, and dev builds warn
+  when an unobserved handler failure resolves without one.
+- **`useFieldArray` parity with its siblings.** The return gains `path`,
+  `firstError`, and the array-level server channel (`setError` /
+  `clearError`) — a "too many rows" verdict from the API is set and
+  cleared from the hook that owns the array. Custom `FieldArrayFormApi`
+  implementations opt in via the optional `setError`/`clearErrors`
+  members (same contract as the optional `validateField`).
+- **`useIsValidating(form, path?)`.** The boolean-only in-flight flag,
+  form-level (whole-form pass or any field) or scoped to a subtree —
+  previously reachable only through a selector, asymmetric with
+  `useIsSubmitting`.
+- **`usePersistForm(form, options)`.** The React lifecycle wrapper
+  `persistForm` was missing: owns the mount/dispose effect (StrictMode
+  safe), returns a reference-stable handle safe to close over in submit
+  handlers, and reads options when the subscription starts (the
+  `useForm` locked-options rule).
+- **`createFormHooks` binds the newer hooks.** `use{Name}Values`,
+  `use{Name}Fields` (position-typed like the plain `useFields`), and
+  `use{Name}IsValidating` join the factory.
+
+### Fixed
+
+- **`numberInputProps` keeps the value on a partial entry.** The
+  `type="number"` builder wrote `emptyValue` for BOTH empty and invalid
+  text, so a transient "-" or "1e" nulled the field mid-keystroke
+  (error flash, dirty flip) — diverging from `useNumberInput`'s
+  deliberate keep-the-value semantics. Invalid now keeps the stored
+  value; empty still clears. (Browsers report `""` for badInput on
+  number inputs, so `useNumberInput` remains the binding that preserves
+  every keystroke.)
+- **Tuples resolve positionally in the typed paths.** Tuples fell into
+  the generic-array arms of `FieldPath` and `UnionValueAt`, which union
+  every element — so nested paths under heterogeneous tuples were
+  rejected (`"hetero.0.a"` unbindable), out-of-range indices
+  (`"coord.5"`) accepted with a lying element type, and a discriminated
+  union below a tuple position unbindable through `useVariantField`.
+  Both types gained a tuple arm keyed on the literal indices; `"coord.0"`
+  spellings the CLI generates are unchanged.
+- **Platform containers are path leaves.** `File`/`Blob` (matched
+  structurally, so no DOM lib requirement), `Map`, `Set`, `WeakMap`,
+  `WeakSet`, `Promise`, and functions no longer descend as records:
+  bogus sub-paths like `"file.name"` or `"meta.size"` used to
+  type-check, and a `setValue` through one would have spread the
+  instance into a plain object.
+- **Literal dotted keys are no longer offered as paths.** A key named
+  `"a.b"` appeared in `FieldPath` but resolved to `never` (the runtime
+  walk splits on `"."`), so the offer was the lie; it is now excluded
+  where it is offered rather than where it resolves.
+- **`validateField` no longer crashes on prototype-key paths.** The
+  schema walk read the ZodObject shape with a bare index, so a
+  runtime-built path like `"user.constructor.x"` (server error fields
+  mapped onto `validateField`) resolved Object's constructor as a
+  "schema" and threw — and the subschema cache kept the poisoned entry.
+  Both walks now do own-key reads, like every other walk in the library.
+- **Persist discards version-downgrade drafts instead of adopting the
+  wrapper.** A draft written with `version: n` is a `{__v, values}`
+  wrapper; if the app later shipped without the `version` option, the
+  wrapper's keys evaded the shape guard and the wrapper OBJECT became
+  the form's values, then re-persisted. A versioned draft under a
+  version-less config is now discarded like any other draft the config
+  cannot vouch for.
+- **Debounced validation no longer survives `reset()`.** A pending
+  debounce timer fired after `reset()`/`adoptValues()` and re-committed
+  errors onto the pristine form. The fire now bails when the form is
+  pristine (values is the initialValues reference) or when the path's
+  value changed since scheduling; an unrelated field's edit inside the
+  window still lets the pending validation run.
+- **Array ops accept a null-valued nullable array.** `arrayPush` on a
+  `.nullable()` array field holding `null` warned and silently no-op'd,
+  while `undefined` created the array — even though the op item types
+  are built on `NonNullable<...>` precisely so nullable arrays accept
+  ops. Both empties now start the op from `[]`.
+
+### Changed
+
+- **Awaited async validation is typed settled.** `validateAsync` and
+  `validateFieldAsync` (and `useField`'s `validateAsync`) resolved a
+  union carrying a `"pending"` arm that can never occur — the promise IS
+  the pending state — forcing every exhaustive `switch` to carry a dead
+  case. All three now resolve the `Settled*` result types
+  `validateFieldsAsync` always had. A `switch` that handled `"pending"`
+  on an awaited result will now fail to compile; delete the dead arm.
+
+## formstand-cli 0.16.0 — 2026-09-16
+
+### Added
+
+- **Union array rows generate.** A discriminated union that is an
+  array's row item — the shape the airfield-maps trial hand-wrote — now
+  compiles to a `{Stem}Row` component per row instead of a TODO, in
+  both layouts: the discriminant and common fields bind with the field
+  hook, variant-only fields with the variant hook, all on the
+  row-indexed path (`methods.${index}`), with the same conditional
+  variant blocks, fragment elision, and hoisted number-props hooks a
+  static union gets. Needs formstand 0.16 for the row-indexed variant
+  path types. A union or tuple nested as a FIELD inside a row object,
+  and a tuple row item, keep their TODOs.
+
 ## 0.16.0 — 2026-09-16
 
 ### Added

package/dist/{createForm-jlzK2lCG.d.cts → createForm-D0xLZH-Q.d.cts}

@@ -1,9 +1,15 @@
 import { z } from 'zod';
 import { StoreApi } from 'zustand/vanilla';
 
-type LeafType = string | number | boolean | bigint | symbol | null | undefined | Date | RegExp;
+type BlobLike = Readonly<{
+    size: number;
+    type: string;
+    arrayBuffer: () => Promise<unknown>;
+}>;
+type LeafType = string | number | boolean | bigint | symbol | null | undefined | Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | WeakMap<object, unknown> | WeakSet<object> | Promise<unknown> | ((...args: never[]) => unknown) | BlobLike;
 type IsRecord<T> = T extends LeafType ? false : T extends readonly unknown[] ? false : T extends object ? true : false;
 type IsArray<T> = T extends readonly unknown[] ? true : false;
+type IsTuple<T> = T extends readonly unknown[] ? number extends T["length"] ? false : true : false;
 type Prev = [
     never,
     0,
@@ -37,8 +43,10 @@ type PathDepth = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14
 type IsUnion<T, U = T> = [T] extends [never] ? false : T extends unknown ? [U] extends [T] ? false : true : never;
 type NormalizeDepth<D extends number> = number extends D ? DefaultPathDepth : [D] extends [PathDepth] ? IsUnion<D> extends true ? DefaultPathDepth : D : DefaultPathDepth;
 type FieldPath<T, D extends number = DefaultPathDepth> = FieldPathRec<T, NormalizeDepth<D>>;
-type FieldPathRec<T, D extends number> = [D] extends [0] ? never : IsArray<T> extends true ? T extends readonly (infer U)[] ? `${number}` | (IsRecord<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : IsArray<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : never) : never : IsRecord<T> extends true ? {
-    [K in keyof T & string]: K | (IsRecord<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : IsArray<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : never);
+type FieldPathRec<T, D extends number> = [D] extends [0] ? never : IsTuple<T> extends true ? {
+    [K in keyof T & `${number}`]: K | (IsRecord<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : IsArray<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : never);
+}[keyof T & `${number}`] : IsArray<T> extends true ? T extends readonly (infer U)[] ? `${number}` | (IsRecord<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : IsArray<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : never) : never : IsRecord<T> extends true ? {
+    [K in keyof T & string]: K extends `${string}.${string}` ? never : K | (IsRecord<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : IsArray<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : never);
 }[keyof T & string] : never;
 type StepValue<T, K extends string> = T extends readonly (infer U)[] ? K extends keyof T ? T[K] : K extends `${number}` ? U : never : T extends object ? K extends keyof T ? T[K] : never : never;
 type FieldValue<T, P extends string> = [T] extends [NonNullable<T>] ? P extends `${infer Head}.${infer Tail}` ? FieldValue<StepValue<T, Head>, Tail> : StepValue<T, P> : FieldValue<NonNullable<T>, P> | undefined;
@@ -114,6 +122,7 @@ type SubmitHandler<TSchema extends z.ZodType> = (data: z.output<TSchema>) => voi
 type InvalidSubmitHandler = (errors: ErrorMap) => void;
 type SubmitOptions = Readonly<{
     force?: boolean;
+    onError?: (error: unknown) => void;
 }>;
 type SubmitResult<TOutput> = Readonly<{
     kind: "valid";
@@ -159,6 +168,7 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
     setReValidateMode: (mode: ValidationMode) => void;
     setError: (path: ErrorPath<z.input<TSchema>, D>, errors: string | readonly string[]) => void;
     setErrors: (errors: ErrorMap) => void;
+    addErrors: (errors: ErrorMap) => void;
     clearErrors: (path?: ErrorPath<z.input<TSchema>, D>) => void;
     updateState: (updater: (state: FormState<z.input<TSchema>>) => Partial<Omit<FormState<z.input<TSchema>>, "errors">>) => void;
     reset: (nextInitial?: Partial<z.input<TSchema>>, options?: ResetOptions) => void;
@@ -168,8 +178,8 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
     validate: () => ValidationResult<z.output<TSchema>>;
     validateField: (path: ErrorPath<z.input<TSchema>, D>) => FieldValidationResult;
     validateFields: (paths: readonly FieldPath<z.input<TSchema>, D>[]) => FieldsValidationResult;
-    validateAsync: () => Promise<ValidationResult<z.output<TSchema>>>;
-    validateFieldAsync: (path: ErrorPath<z.input<TSchema>, D>) => Promise<FieldValidationResult>;
+    validateAsync: () => Promise<SettledValidationResult<z.output<TSchema>>>;
+    validateFieldAsync: (path: ErrorPath<z.input<TSchema>, D>) => Promise<SettledFieldValidationResult>;
     validateFieldsAsync: (paths: readonly FieldPath<z.input<TSchema>, D>[]) => Promise<SettledFieldsValidationResult>;
     submit: (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions) => Promise<SubmitResult<z.output<TSchema>>>;
     arrayPush: <P extends FieldPath<z.input<TSchema>, D>>(path: P, item: ArrayItemOf<NonNullable<FieldValue<z.input<TSchema>, P>>>) => void;

package/dist/{createForm-jlzK2lCG.d.ts → createForm-D0xLZH-Q.d.ts}

@@ -1,9 +1,15 @@
 import { z } from 'zod';
 import { StoreApi } from 'zustand/vanilla';
 
-type LeafType = string | number | boolean | bigint | symbol | null | undefined | Date | RegExp;
+type BlobLike = Readonly<{
+    size: number;
+    type: string;
+    arrayBuffer: () => Promise<unknown>;
+}>;
+type LeafType = string | number | boolean | bigint | symbol | null | undefined | Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | WeakMap<object, unknown> | WeakSet<object> | Promise<unknown> | ((...args: never[]) => unknown) | BlobLike;
 type IsRecord<T> = T extends LeafType ? false : T extends readonly unknown[] ? false : T extends object ? true : false;
 type IsArray<T> = T extends readonly unknown[] ? true : false;
+type IsTuple<T> = T extends readonly unknown[] ? number extends T["length"] ? false : true : false;
 type Prev = [
     never,
     0,
@@ -37,8 +43,10 @@ type PathDepth = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14
 type IsUnion<T, U = T> = [T] extends [never] ? false : T extends unknown ? [U] extends [T] ? false : true : never;
 type NormalizeDepth<D extends number> = number extends D ? DefaultPathDepth : [D] extends [PathDepth] ? IsUnion<D> extends true ? DefaultPathDepth : D : DefaultPathDepth;
 type FieldPath<T, D extends number = DefaultPathDepth> = FieldPathRec<T, NormalizeDepth<D>>;
-type FieldPathRec<T, D extends number> = [D] extends [0] ? never : IsArray<T> extends true ? T extends readonly (infer U)[] ? `${number}` | (IsRecord<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : IsArray<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : never) : never : IsRecord<T> extends true ? {
-    [K in keyof T & string]: K | (IsRecord<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : IsArray<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : never);
+type FieldPathRec<T, D extends number> = [D] extends [0] ? never : IsTuple<T> extends true ? {
+    [K in keyof T & `${number}`]: K | (IsRecord<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : IsArray<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : never);
+}[keyof T & `${number}`] : IsArray<T> extends true ? T extends readonly (infer U)[] ? `${number}` | (IsRecord<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : IsArray<NonNullable<U>> extends true ? `${number}.${FieldPathRec<NonNullable<U>, Prev[D]>}` : never) : never : IsRecord<T> extends true ? {
+    [K in keyof T & string]: K extends `${string}.${string}` ? never : K | (IsRecord<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : IsArray<NonNullable<T[K]>> extends true ? `${K}.${FieldPathRec<NonNullable<T[K]>, Prev[D]>}` : never);
 }[keyof T & string] : never;
 type StepValue<T, K extends string> = T extends readonly (infer U)[] ? K extends keyof T ? T[K] : K extends `${number}` ? U : never : T extends object ? K extends keyof T ? T[K] : never : never;
 type FieldValue<T, P extends string> = [T] extends [NonNullable<T>] ? P extends `${infer Head}.${infer Tail}` ? FieldValue<StepValue<T, Head>, Tail> : StepValue<T, P> : FieldValue<NonNullable<T>, P> | undefined;
@@ -114,6 +122,7 @@ type SubmitHandler<TSchema extends z.ZodType> = (data: z.output<TSchema>) => voi
 type InvalidSubmitHandler = (errors: ErrorMap) => void;
 type SubmitOptions = Readonly<{
     force?: boolean;
+    onError?: (error: unknown) => void;
 }>;
 type SubmitResult<TOutput> = Readonly<{
     kind: "valid";
@@ -159,6 +168,7 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
     setReValidateMode: (mode: ValidationMode) => void;
     setError: (path: ErrorPath<z.input<TSchema>, D>, errors: string | readonly string[]) => void;
     setErrors: (errors: ErrorMap) => void;
+    addErrors: (errors: ErrorMap) => void;
     clearErrors: (path?: ErrorPath<z.input<TSchema>, D>) => void;
     updateState: (updater: (state: FormState<z.input<TSchema>>) => Partial<Omit<FormState<z.input<TSchema>>, "errors">>) => void;
     reset: (nextInitial?: Partial<z.input<TSchema>>, options?: ResetOptions) => void;
@@ -168,8 +178,8 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
     validate: () => ValidationResult<z.output<TSchema>>;
     validateField: (path: ErrorPath<z.input<TSchema>, D>) => FieldValidationResult;
     validateFields: (paths: readonly FieldPath<z.input<TSchema>, D>[]) => FieldsValidationResult;
-    validateAsync: () => Promise<ValidationResult<z.output<TSchema>>>;
-    validateFieldAsync: (path: ErrorPath<z.input<TSchema>, D>) => Promise<FieldValidationResult>;
+    validateAsync: () => Promise<SettledValidationResult<z.output<TSchema>>>;
+    validateFieldAsync: (path: ErrorPath<z.input<TSchema>, D>) => Promise<SettledFieldValidationResult>;
     validateFieldsAsync: (paths: readonly FieldPath<z.input<TSchema>, D>[]) => Promise<SettledFieldsValidationResult>;
     submit: (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions) => Promise<SubmitResult<z.output<TSchema>>>;
     arrayPush: <P extends FieldPath<z.input<TSchema>, D>>(path: P, item: ArrayItemOf<NonNullable<FieldValue<z.input<TSchema>, P>>>) => void;

package/dist/devtools/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { z } from 'zod';
-import { F as Form } from '../createForm-jlzK2lCG.cjs';
+import { F as Form } from '../createForm-D0xLZH-Q.cjs';
 import 'zustand/vanilla';
 
 type DevtoolsPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";

package/dist/devtools/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { z } from 'zod';
-import { F as Form } from '../createForm-jlzK2lCG.js';
+import { F as Form } from '../createForm-D0xLZH-Q.js';
 import 'zustand/vanilla';
 
 type DevtoolsPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";

package/dist/index.cjs

@@ -297,7 +297,7 @@ var schemaHasPath = (schema, path) => {
     if (head === void 0) return true;
     if (s instanceof zod.z.ZodObject) {
       const shape = s.shape;
-      const child = shape[String(head)];
+      const child = Object.hasOwn(shape, String(head)) ? shape[String(head)] : void 0;
       if (child !== void 0) return walk(child, rest, budget - 1);
       const catchall = s.def.catchall;
       return catchall !== void 0 && !(catchall instanceof zod.z.ZodNever);
@@ -317,7 +317,7 @@ var fieldSchemaAtPath = (schema, path) => parsePath(path).reduce((current, segme
   if (current === null || hasChecks(current)) return null;
   if (current instanceof zod.z.ZodObject && typeof segment === "string") {
     const shape = current.shape;
-    return shape[segment] ?? null;
+    return Object.hasOwn(shape, segment) ? shape[segment] ?? null : null;
   }
   if (current instanceof zod.z.ZodArray && typeof segment === "number") {
     return current.element;
@@ -722,7 +722,7 @@ var createForm = (schema, options) => {
   };
   const applyArrayOp = (path, nextArray, mapper, indexInBounds) => {
     const current = getAtPath(store.getState().values, path);
-    if (current !== void 0 && !Array.isArray(current)) {
+    if (current !== void 0 && current !== null && !Array.isArray(current)) {
       console.warn(
         `[formstand] array op on "${path}" but the value at that path is not an array (got ${typeof current}). Operation skipped.`
       );
@@ -831,6 +831,7 @@ var createForm = (schema, options) => {
       try {
         await onValid(result.data);
       } catch (error) {
+        submitOptions?.onError?.(error);
         return { kind: "error", error };
       }
       return { kind: "valid", data: result.data };
@@ -938,6 +939,17 @@ var createForm = (schema, options) => {
       ...state,
       ...errorChannels(state, { serverErrors: errors })
     })),
+    addErrors: (errors) => store.setState((state) => ({
+      ...state,
+      ...errorChannels(state, {
+        serverErrors: Object.entries(errors).reduce(
+          // Computed keys throughout, so a server field named
+          // "__proto__" lands as an own property like everywhere else.
+          (acc, [key, list]) => list === void 0 || list.length === 0 ? omitKey(acc, key) : { ...acc, [key]: list },
+          state.serverErrors
+        )
+      })
+    })),
     clearErrors: (path) => store.setState((state) => {
       const scrub = (map) => path === void 0 ? emptyErrors : omitScope(map, [path]);
       return {
@@ -1077,7 +1089,14 @@ var createForm = (schema, options) => {
     ),
     handleSubmit: (onValid, onInvalid, opts) => async (event) => {
       event?.preventDefault();
-      return submit(onValid, onInvalid, opts);
+      const result = await submit(onValid, onInvalid, opts);
+      if (result.kind === "error" && opts?.onError === void 0 && process.env.NODE_ENV !== "production") {
+        console.warn(
+          "[formstand] submit handler threw and nothing observed it \u2014 the form shows no feedback. Pass { onError } to handleSubmit (or setError inside your handler):",
+          result.error
+        );
+      }
+      return result;
     },
     diff: () => {
       const state = store.getState();
@@ -1185,6 +1204,9 @@ var persistForm = (form, options) => {
       const parsed = JSON.parse(raw);
       const versioned = options.version !== void 0 && typeof parsed === "object" && parsed !== null && "__v" in parsed;
       if (options.version !== void 0 && !versioned) return false;
+      if (options.version === void 0 && typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "__v") && Object.hasOwn(parsed, "values")) {
+        return false;
+      }
       const wrapper = parsed;
       if (versioned && wrapper.__v !== options.version) return false;
       if (versioned && wrapper.values === void 0) return false;
@@ -1248,6 +1270,33 @@ var persistForm = (form, options) => {
     }
   });
 };
+var usePersistForm = (form, options) => {
+  const inner = react.useRef(null);
+  const latestOptions = react.useRef(options);
+  react.useEffect(() => {
+    latestOptions.current = options;
+  });
+  const key = options.key;
+  react.useEffect(() => {
+    const handle = persistForm(form, latestOptions.current);
+    inner.current = handle;
+    return () => {
+      inner.current = null;
+      handle.dispose();
+    };
+  }, [form, key]);
+  return react.useMemo(
+    () => ({
+      restore: () => inner.current?.restore() ?? false,
+      clear: () => inner.current?.clear(),
+      // dispose stops THIS component's watching early; the effect cleanup
+      // still runs its own dispose harmlessly (persistForm's dispose is
+      // idempotent by construction — it only cancels and unsubscribes).
+      dispose: () => inner.current?.dispose()
+    }),
+    []
+  );
+};
 var useForm = (schema, options) => {
   const formRef = react.useRef(null);
   if (formRef.current === null) {
@@ -1324,9 +1373,13 @@ function useField(form, pathArg, options) {
       if (debounceTimerRef.current !== null) {
         clearTimeout(debounceTimerRef.current);
       }
+      const scheduled = getAtPath(form.store.getState().values, path);
       debounceTimerRef.current = setTimeout(() => {
-        void form.validateFieldAsync(path);
         debounceTimerRef.current = null;
+        const state = form.store.getState();
+        if (state.values === state.initialValues) return;
+        if (!Object.is(getAtPath(state.values, path), scheduled)) return;
+        void form.validateFieldAsync(path);
       }, debounceMs);
       return;
     }
@@ -1587,25 +1640,64 @@ function useFieldArray(form, pathArg) {
     })),
     [items, ids]
   );
+  const setError = react.useCallback(
+    // Same string-shorthand normalization as useField.setError, so custom
+    // implementations typed for readonly string[] never receive a bare
+    // string.
+    (errors) => form.setError?.(path, typeof errors === "string" ? [errors] : errors),
+    [form, path]
+  );
+  const clearError = react.useCallback(() => form.clearErrors?.(path), [form, path]);
   return react.useMemo(
     () => ({
+      path,
       fields,
       items,
       length: items.length,
       error,
+      firstError: error?.[0],
+      setError,
+      clearError,
       push,
       remove,
       insert,
       move,
       swap
     }),
-    [fields, items, error, push, remove, insert, move, swap]
+    [path, fields, items, error, setError, clearError, push, remove, insert, move, swap]
   );
 }
 var useFormError = (form) => react$1.useStore(
   form.store,
   shallow.useShallow((state) => state.errors[""])
 );
+function useFormValues(form) {
+  return react$1.useStore(form.store, (state) => state.values);
+}
+
+// src/react/useFields.ts
+function useFields(form, paths) {
+  const fields = paths.map(
+    (path) => (
+      // eslint-disable-next-line react-hooks/rules-of-hooks -- a fixed hook count by the stable-arity contract above; each element must be a REAL UseFieldReturn so it spreads into the prop builders
+      useField(form, path)
+    )
+  );
+  const merged = [...new Set(fields.flatMap((field) => field.error ?? []))];
+  return {
+    fields,
+    error: merged.length > 0 ? merged : void 0,
+    firstError: merged[0],
+    touched: fields.some((field) => field.touched),
+    dirty: fields.some((field) => field.dirty),
+    isValidating: fields.some((field) => field.isValidating),
+    onBlur: () => {
+      fields.forEach((field) => {
+        field.onBlur();
+      });
+    }
+  };
+}
 function useIsDirty(form, path) {
   return react$1.useStore(
     form.store,
@@ -1626,6 +1718,19 @@ function useIsValid(form, path) {
     return true;
   });
 }
+function useIsValidating(form, path) {
+  return react$1.useStore(form.store, (state) => {
+    if (path === void 0 || path === "") {
+      if (state.isValidatingForm) return true;
+    }
+    for (const k in state.isValidating) {
+      if (state.isValidating[k] === true && (path === void 0 || path === "" || isPathOrChild(k, path))) {
+        return true;
+      }
+    }
+    return false;
+  });
+}
 var useIsSubmitting = (form) => react$1.useStore(form.store, (state) => state.isSubmitting);
 var useSubmitCount = (form) => react$1.useStore(form.store, (state) => state.submitCount);
 function useFormSelector(form, selector) {
@@ -1651,7 +1756,13 @@ var createFormHooks = (form, name) => {
   const useBoundError = () => useFormError(structural);
   const useBoundIsDirty = (path) => useIsDirty(structural, path);
   const useBoundIsValid = (path) => useIsValid(structural, path);
+  const useBoundIsValidating = (path) => useIsValidating(structural, path);
   const useBoundIsSubmitting = () => useIsSubmitting(structural);
+  const useBoundValues = () => useFormValues(structural);
+  const useBoundFields = (paths) => useFields(
+    structural,
+    paths
+  );
   const useBoundSubmitCount = () => useSubmitCount(structural);
   const prefix = capitalize(name ?? "");
   return {
@@ -1663,37 +1774,13 @@ var createFormHooks = (form, name) => {
     [`use${prefix}Error`]: useBoundError,
     [`use${prefix}IsDirty`]: useBoundIsDirty,
     [`use${prefix}IsValid`]: useBoundIsValid,
+    [`use${prefix}IsValidating`]: useBoundIsValidating,
     [`use${prefix}IsSubmitting`]: useBoundIsSubmitting,
-    [`use${prefix}SubmitCount`]: useBoundSubmitCount
+    [`use${prefix}SubmitCount`]: useBoundSubmitCount,
+    [`use${prefix}Values`]: useBoundValues,
+    [`use${prefix}Fields`]: useBoundFields
   };
 };
-function useFormValues(form) {
-  return react$1.useStore(form.store, (state) => state.values);
-}
-
-// src/react/useFields.ts
-function useFields(form, paths) {
-  const fields = paths.map(
-    (path) => (
-      // eslint-disable-next-line react-hooks/rules-of-hooks -- a fixed hook count by the stable-arity contract above; each element must be a REAL UseFieldReturn so it spreads into the prop builders
-      useField(form, path)
-    )
-  );
-  const merged = [...new Set(fields.flatMap((field) => field.error ?? []))];
-  return {
-    fields,
-    error: merged.length > 0 ? merged : void 0,
-    firstError: merged[0],
-    touched: fields.some((field) => field.touched),
-    dirty: fields.some((field) => field.dirty),
-    isValidating: fields.some((field) => field.isValidating),
-    onBlur: () => {
-      fields.forEach((field) => {
-        field.onBlur();
-      });
-    }
-  };
-}
 
 // src/react/inputProps.ts
 var hasFieldError = (error) => error !== void 0 && error.length > 0;
@@ -1723,6 +1810,7 @@ var numberInputProps = (field) => ({
   "aria-invalid": ariaInvalid(field),
   onChange: (e) => {
     const parsed = parseNumberText(e.target.value);
+    if (parsed.kind === "invalid") return;
     field.setValue(
       parsed.kind === "number" ? parsed.value : field.emptyValue
     );
@@ -2122,7 +2210,9 @@ exports.useFormValues = useFormValues;
 exports.useIsDirty = useIsDirty;
 exports.useIsSubmitting = useIsSubmitting;
 exports.useIsValid = useIsValid;
+exports.useIsValidating = useIsValidating;
 exports.useNumberInput = useNumberInput;
+exports.usePersistForm = usePersistForm;
 exports.useSubmitCount = useSubmitCount;
 exports.useVariantField = useVariantField;
 exports.validateAsync = validateAsync;