formstand 0.24.0 → 0.26.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { isDevToolsBuild, getAtPath, isDevBuild, slotAtPath, setAtPath, isPlainObject, hasOwnSlot, valuesEqual, useFormSelectorShallow, isFieldDirty, useFormSelector, parsePath } from './chunk-EQIS5IVH.js';
-export { getAtPath, parsePath, setAtPath, useFormSelector, useFormSelectorShallow } from './chunk-EQIS5IVH.js';
+import { isDevToolsBuild, isDevBuild, useFormSelectorShallow, useFormSelector } from './chunk-XJ6W5CKB.js';
+export { useFormSelector, useFormSelectorShallow } from './chunk-XJ6W5CKB.js';
 import { flagAt, entryAt, shouldValidateOn } from './chunk-V3PDMTPP.js';
 export { shouldValidateOn } from './chunk-V3PDMTPP.js';
 import { createStore } from 'zustand/vanilla';
@@ -103,6 +103,158 @@ var clearArrayOpsUnder = (store, path, keepSelf = false) => {
   );
   related.forEach((p) => byPath.delete(p));
 };
+
+// src/core/equality.ts
+var isPlainObject = (v) => {
+  if (typeof v !== "object" || v === null) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+var valuesEqual = (a, b) => {
+  if (Object.is(a, b)) return true;
+  if (typeof a === "number" && typeof b === "number") return a === b;
+  if (a instanceof Date && b instanceof Date) {
+    const [ta, tb] = [a.getTime(), b.getTime()];
+    return ta === tb || Number.isNaN(ta) && Number.isNaN(tb);
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => valuesEqual(v, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    return aKeys.length === bKeys.length && aKeys.every((k) => Object.hasOwn(b, k) && valuesEqual(a[k], b[k]));
+  }
+  return false;
+};
+var dirtyCache = /* @__PURE__ */ new WeakMap();
+var MAX_VERDICTS = 4;
+var isFieldDirty = (value, initialValue) => {
+  if (Object.is(value, initialValue)) return false;
+  if (typeof value !== "object" || value === null) {
+    return !valuesEqual(value, initialValue);
+  }
+  const cached = dirtyCache.get(value) ?? [];
+  const hit = cached.find((v) => Object.is(v.initial, initialValue));
+  if (hit !== void 0) return hit.dirty;
+  const dirty = !valuesEqual(value, initialValue);
+  dirtyCache.set(
+    value,
+    [{ initial: initialValue, dirty }, ...cached].slice(0, MAX_VERDICTS)
+  );
+  return dirty;
+};
+
+// src/core/path.ts
+var MAX_ARRAY_INDEX = 1e5;
+var isIndexSegment = (s) => {
+  const n = Number(s);
+  return Number.isInteger(n) && n >= 0 && String(n) === s;
+};
+var PARSE_CACHE_MAX = 4096;
+var parseCache = /* @__PURE__ */ new Map();
+var parsePath = (path) => {
+  const cached = parseCache.get(path);
+  if (cached !== void 0) {
+    parseCache.delete(path);
+    parseCache.set(path, cached);
+    return cached;
+  }
+  const segments = Object.freeze(
+    path === "" ? [] : path.split(".").map((s) => isIndexSegment(s) ? Number(s) : s)
+  );
+  if (parseCache.size >= PARSE_CACHE_MAX) {
+    const oldest = parseCache.keys().next().value;
+    if (oldest !== void 0) parseCache.delete(oldest);
+  }
+  parseCache.set(path, segments);
+  return segments;
+};
+var isPlainRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var readSegment = (obj, segment) => {
+  if (obj == null) return void 0;
+  if (Array.isArray(obj)) {
+    return typeof segment === "number" ? obj[segment] : void 0;
+  }
+  return isPlainRecord(obj) && Object.hasOwn(obj, String(segment)) ? obj[String(segment)] : void 0;
+};
+var getAtPath = (obj, path) => parsePath(path).reduce(readSegment, obj);
+var slotAtPath = (obj, path) => {
+  const walked = parsePath(path).reduce(
+    (acc, segment) => {
+      const container = acc.current;
+      const addressable = typeof segment === "number" ? Array.isArray(container) ? segment < container.length : isPlainRecord(container) : isPlainRecord(container);
+      return !acc.ok || !addressable ? { ok: false, current: void 0 } : { ok: true, current: readSegment(container, segment) };
+    },
+    { ok: true, current: obj }
+  );
+  return walked.ok ? { exists: true, value: walked.current } : { exists: false };
+};
+var hasOwnSlot = (obj, path) => parsePath(path).reduce(
+  (acc, segment) => {
+    const container = acc.current;
+    const owns = Array.isArray(container) ? typeof segment === "number" && segment < container.length : isPlainRecord(container) && Object.hasOwn(container, String(segment));
+    return !acc.ok || !owns ? { ok: false, current: void 0 } : { ok: true, current: readSegment(container, segment) };
+  },
+  { ok: true, current: obj }
+).ok;
+var writeIntoArray = (arr, index, rest, value, kindAt, prefix) => {
+  const length = Math.max(arr.length, index + 1);
+  return Array.from(
+    { length },
+    (_, i) => i === index ? writeSegments(arr[i], rest, value, kindAt, [...prefix, index]) : arr[i]
+  );
+};
+var refusesHugeIndex = (index) => {
+  if (index > MAX_ARRAY_INDEX) {
+    console.warn(
+      `[formstand] refusing to write array index ${index} (max ${MAX_ARRAY_INDEX}); value left unchanged.`
+    );
+    return true;
+  }
+  return false;
+};
+var writeSegments = (obj, segments, value, kindAt, prefix) => {
+  const [head, ...rest] = segments;
+  if (head === void 0) return value;
+  if (Array.isArray(obj)) {
+    if (typeof head !== "number") {
+      console.warn(
+        `[formstand] cannot write string key "${head}" into an array; value left unchanged.`
+      );
+      return obj;
+    }
+    if (refusesHugeIndex(head)) return obj;
+    return writeIntoArray(obj, head, rest, value, kindAt, prefix);
+  }
+  if (isPlainRecord(obj)) {
+    if (!isPlainObject(obj)) {
+      console.warn(
+        `[formstand] cannot write key "${String(head)}" through a non-plain object (Date/Map/Set/class instance); value left unchanged.`
+      );
+      return obj;
+    }
+    const key2 = String(head);
+    return {
+      ...obj,
+      [key2]: writeSegments(obj[key2], rest, value, kindAt, [...prefix, key2])
+    };
+  }
+  const kind = kindAt?.(prefix.map(String).join(".")) ?? (typeof head === "number" ? "array" : "record");
+  if (kind === "array") {
+    if (typeof head !== "number") {
+      console.warn(
+        `[formstand] cannot write string key "${head}" into an array; value left unchanged.`
+      );
+      return obj;
+    }
+    if (refusesHugeIndex(head)) return obj;
+    return writeIntoArray([], head, rest, value, kindAt, prefix);
+  }
+  const key = String(head);
+  return { [key]: writeSegments(void 0, rest, value, kindAt, [...prefix, key]) };
+};
+var setAtPath = (obj, path, value, containerKindAt2) => writeSegments(obj, parsePath(path), value, containerKindAt2, []);
 var issuePathToFormPath = (path) => path.filter((segment) => typeof segment !== "symbol").join(".");
 var expandIssue = (issue, prefix) => {
   const at = [...prefix, ...issue.path];
@@ -134,6 +286,12 @@ var validateAsync = async (schema, values) => {
   return result.success ? { kind: "valid", data: result.data } : { kind: "invalid", errors: flattenIssues(result.error.issues) };
 };
 var isAsyncRequiredError = (e) => e instanceof z.core.$ZodAsyncError || e instanceof Error && /Encountered Promise during synchronous parse/i.test(e.message);
+var reportBackgroundFailure = (error) => {
+  console.error(
+    "[formstand] a background validation pass threw (an async refinement rejected). Its in-flight flags were released. The error:",
+    error
+  );
+};
 var isPathOrChild = (key, path) => key === path || key.startsWith(`${path}.`);
 var prefixErrorKeys = (errors, path) => path === "" ? errors : Object.fromEntries(
   Object.entries(errors).map(([k, v]) => [
@@ -185,6 +343,42 @@ var schemaHasPath = (schema, path) => {
   };
   return walk(schema, parsePath(path), SCHEMA_WALK_BUDGET);
 };
+var schemaAllowsKindChangeAt = (schema, path) => {
+  const flexible = (s) => s instanceof z.ZodUnion || s instanceof z.ZodDiscriminatedUnion || s instanceof z.ZodPipe || s instanceof z.ZodAny || s instanceof z.ZodUnknown || s instanceof z.ZodLazy || s instanceof z.ZodCatch || s.def.coerce === true;
+  const strip = (s) => {
+    if (s instanceof z.ZodOptional || s instanceof z.ZodNullable) {
+      return strip(s.unwrap());
+    }
+    if (s instanceof z.ZodDefault || s instanceof z.ZodPrefault || s instanceof z.ZodReadonly || s instanceof z.ZodNonOptional) {
+      return strip(s.def.innerType);
+    }
+    return s;
+  };
+  const walk = (s, segments, budget) => {
+    if (budget <= 0) return true;
+    const node = strip(s);
+    if (flexible(node)) return true;
+    const [head, ...rest] = segments;
+    if (head === void 0) return false;
+    if (node instanceof z.ZodObject) {
+      const shape = node.shape;
+      const child = Object.hasOwn(shape, String(head)) ? shape[String(head)] : void 0;
+      return child === void 0 ? true : walk(child, rest, budget - 1);
+    }
+    if (node instanceof z.ZodArray) {
+      return typeof head === "number" ? walk(node.element, rest, budget - 1) : true;
+    }
+    if (node instanceof z.ZodTuple && typeof head === "number") {
+      const item = node.def.items[head];
+      return item === void 0 ? true : walk(item, rest, budget - 1);
+    }
+    if (node instanceof z.ZodRecord) {
+      return walk(node.valueType, rest, budget - 1);
+    }
+    return true;
+  };
+  return walk(schema, parsePath(path), SCHEMA_WALK_BUDGET);
+};
 var hasChecks = (s) => {
   const checks = s.def.checks;
   return checks !== void 0 && checks.length > 0;
@@ -269,7 +463,7 @@ var fieldSchemaAtPath = (schema, path) => parsePath(path).reduce((current, segme
 }, schema);
 
 // src/core/createForm.ts
-var shallowFieldEqual = (a, b) => Object.is(a.value, b.value) && a.error === b.error && a.touched === b.touched && a.dirty === b.dirty && a.isValidating === b.isValidating;
+var shallowFieldEqual = (a, b) => Object.is(a.value, b.value) && Object.is(a.initialValue, b.initialValue) && a.error === b.error && a.touched === b.touched && a.dirty === b.dirty && a.isValidating === b.isValidating;
 var emptyErrors = {};
 var emptyBools = {};
 var identityMapper = (n) => n;
@@ -327,7 +521,26 @@ var reuseErrorRefs = (next, prev) => {
   const sameShape = entries.length === Object.keys(prev).length && entries.every(([k, v]) => entryAt(prev, k) === v);
   return sameShape ? prev : Object.fromEntries(entries);
 };
-var scopeSettledResult = (result, path, viaSubschema) => result.kind !== "invalid" ? emptyErrors : viaSubschema ? prefixErrorKeys(result.errors, path) : path === "" ? result.errors : pickScope(result.errors, [path]);
+var noScopeErrors = { scoped: emptyErrors, full: null };
+var scopeParse = (result, path, viaSubschema) => {
+  const errors = result.kind === "invalid" ? result.errors : emptyErrors;
+  return viaSubschema ? { scoped: prefixErrorKeys(errors, path), full: null } : {
+    scoped: path === "" ? errors : pickScope(errors, [path]),
+    full: errors
+  };
+};
+var pruneUnreported = (prev, full) => {
+  const entries = Object.entries(prev);
+  const kept = entries.filter(([k]) => Object.hasOwn(full, k));
+  return kept.length === entries.length ? prev : Object.fromEntries(kept);
+};
+var dropEmptyLists = (map) => {
+  const entries = Object.entries(map);
+  const kept = entries.filter(
+    ([, list]) => list !== void 0 && list.length > 0
+  );
+  return kept.length === entries.length ? map : Object.fromEntries(kept);
+};
 var mergeErrorChannels = (schema, server) => {
   const extra = Object.entries(server).filter(
     ([k]) => !Object.hasOwn(schema, k)
@@ -437,17 +650,17 @@ var createForm = (schema, options) => {
         const merged = scopes.reduce(
           (acc, { path, scope }) => scope.kind === "skip" ? acc : {
             ...acc,
-            ...scopeSettledResult(
+            ...scopeParse(
               validateSyncLatched(path, scope.schema, scope.value),
               path,
               true
-            )
+            ).scoped
           },
           {}
         );
         store.setState((state) => ({
           ...state,
-          ...commitScopedErrors(state, merged, paths)
+          ...commitScopedErrors(state, merged, paths, null)
         }));
         return settledFields(merged);
       }
@@ -456,7 +669,7 @@ var createForm = (schema, options) => {
       const requestedErrors = pickScope(fullErrors, paths);
       store.setState((state) => ({
         ...state,
-        ...commitScopedErrors(state, requestedErrors, paths)
+        ...commitScopedErrors(state, requestedErrors, paths, fullErrors)
       }));
       return settledFields(requestedErrors);
     } catch (e) {
@@ -501,7 +714,7 @@ var createForm = (schema, options) => {
     const slot = slotAtPath(values, path);
     return slot.exists ? { kind: "parse", schema: sub, value: slot.value, viaSubschema: true } : { kind: "skip" };
   };
-  const parseScopeAsync = async (path, scope) => scope.kind === "skip" ? emptyErrors : scopeSettledResult(
+  const parseScopeAsync = async (path, scope) => scope.kind === "skip" ? noScopeErrors : scopeParse(
     await validateAsync(scope.schema, scope.value),
     path,
     scope.viaSubschema
@@ -521,14 +734,18 @@ var createForm = (schema, options) => {
   };
   const settledFields = (scoped) => Object.keys(scoped).length === 0 ? { kind: "valid" } : { kind: "invalid", errors: scoped };
   const settledFormResult = (result) => settledFields(result.kind === "invalid" ? result.errors : emptyErrors);
-  const commitScopedErrors = (state, scoped, paths) => errorChannels(state, {
+  const commitScopedErrors = (state, scoped, paths, full) => errorChannels(state, {
     schemaErrors: reuseErrorRefs(
-      mergeScopedErrors(state.schemaErrors, scoped, paths),
+      mergeScopedErrors(
+        full === null ? state.schemaErrors : pruneUnreported(state.schemaErrors, full),
+        scoped,
+        paths
+      ),
       state.schemaErrors
     ),
     serverErrors: omitScope(state.serverErrors, paths)
   });
-  const commitFieldErrors = (state, scoped, path) => path === "" ? commitFullPass(state, scoped) : commitScopedErrors(state, scoped, [path]);
+  const commitFieldErrors = (state, parse, path) => path === "" ? commitFullPass(state, parse.scoped) : commitScopedErrors(state, parse.scoped, [path], parse.full);
   const validateField = (path) => {
     warnMissingSchemaPath("validateField", path);
     const scope = fieldScopeFor(path, store.getState().values);
@@ -536,7 +753,7 @@ var createForm = (schema, options) => {
       return { kind: "pending", promise: validateFieldAsync(path) };
     }
     try {
-      const scoped = scope.kind === "skip" ? emptyErrors : scopeSettledResult(
+      const parse = scope.kind === "skip" ? noScopeErrors : scopeParse(
         validateSyncLatched(
           scope.viaSubschema ? path : "",
           scope.schema,
@@ -547,9 +764,9 @@ var createForm = (schema, options) => {
       );
       store.setState((state) => ({
         ...state,
-        ...commitFieldErrors(state, scoped, path)
+        ...commitFieldErrors(state, parse, path)
       }));
-      return fieldResult(scoped);
+      return fieldResult(parse.scoped);
     } catch (e) {
       if (isAsyncRequiredError(e)) {
         return { kind: "pending", promise: validateFieldAsync(path) };
@@ -559,11 +776,15 @@ var createForm = (schema, options) => {
   };
   const snapshotField = (state, path) => {
     const value = getAtPath(state.values, path);
+    const initialValue = getAtPath(state.initialValues, path);
+    const error = entryAt(state.errors, path);
     return {
       value,
-      error: entryAt(state.errors, path),
+      initialValue,
+      error,
+      firstError: error?.[0],
       touched: flagAt(state.touched, path),
-      dirty: isFieldDirty(value, getAtPath(state.initialValues, path)),
+      dirty: isFieldDirty(value, initialValue),
       isValidating: flagAt(state.isValidating, path)
     };
   };
@@ -577,7 +798,14 @@ var createForm = (schema, options) => {
     const pass = claimPass(FORM_SEQ_KEY);
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({ ...state, isValidatingForm: true }));
-    const result = await validateAsync(schema, valuesAtStart);
+    const result = await validateAsync(schema, valuesAtStart).catch(
+      (error) => {
+        if (sequences.get(FORM_SEQ_KEY) === pass) {
+          store.setState((state) => ({ ...state, isValidatingForm: false }));
+        }
+        throw error;
+      }
+    );
     const live = store.getState();
     const stillOwns = sequences.get(FORM_SEQ_KEY) === pass;
     if (!stillOwns || live.values !== valuesAtStart) {
@@ -617,12 +845,15 @@ var createForm = (schema, options) => {
         ...Object.fromEntries(paths.map((p) => [p, true]))
       }
     }));
-    const parsed = allViaSubschema ? {
+    const parseBatch = async () => allViaSubschema ? {
       kind: "slots",
       byPath: new Map(
         await Promise.all(
           scopes.map(
-            async ({ path, scope }) => [path, await parseScopeAsync(path, scope)]
+            async ({ path, scope }) => [
+              path,
+              (await parseScopeAsync(path, scope)).scoped
+            ]
           )
         )
       )
@@ -632,6 +863,18 @@ var createForm = (schema, options) => {
         (result) => result.kind === "invalid" ? result.errors : emptyErrors
       )
     };
+    const parsed = await parseBatch().catch((error) => {
+      const stillOwned = new Set(
+        paths.filter((p) => sequences.get(p) === passes.get(p))
+      );
+      if (stillOwned.size > 0) {
+        store.setState((state) => ({
+          ...state,
+          isValidating: omitKeys(state.isValidating, stillOwned)
+        }));
+      }
+      throw error;
+    });
     const errorsFor = (path) => {
       switch (parsed.kind) {
         case "slots":
@@ -660,7 +903,8 @@ var createForm = (schema, options) => {
         Object.fromEntries(
           fresh.flatMap((path) => Object.entries(errorsFor(path)))
         ),
-        fresh
+        fresh,
+        parsed.kind === "full" ? parsed.errors : null
       ),
       isValidating: omitKeys(state.isValidating, ownedKeys)
     }));
@@ -681,24 +925,32 @@ var createForm = (schema, options) => {
       ...state,
       isValidating: { ...state.isValidating, [path]: true }
     }));
-    const scoped = await parseScopeAsync(path, scope);
-    const live = store.getState();
-    const stillOwns = sequences.get(path) === pass;
-    if (!stillOwns || scopeStale(scope, path, valuesAtStart, live.values)) {
-      if (stillOwns) {
+    const releaseOwnFlag = () => {
+      if (sequences.get(path) === pass) {
         store.setState((state) => ({
           ...state,
           isValidating: omitKey(state.isValidating, path)
         }));
       }
-      return fieldResult(scoped);
+    };
+    const parse = await parseScopeAsync(path, scope).catch(
+      (error) => {
+        releaseOwnFlag();
+        throw error;
+      }
+    );
+    const live = store.getState();
+    const stillOwns = sequences.get(path) === pass;
+    if (!stillOwns || scopeStale(scope, path, valuesAtStart, live.values)) {
+      releaseOwnFlag();
+      return fieldResult(parse.scoped);
     }
     store.setState((state) => ({
       ...state,
-      ...commitFieldErrors(state, scoped, path),
+      ...commitFieldErrors(state, parse, path),
       isValidating: omitKey(state.isValidating, path)
     }));
-    return fieldResult(scoped);
+    return fieldResult(parse.scoped);
   };
   const applyArrayOp = (path, nextArray, mapper, indexInBounds) => {
     const current = getAtPath(store.getState().values, path);
@@ -757,7 +1009,9 @@ var createForm = (schema, options) => {
     count: 0,
     baseline: false
   };
-  const submit = async (onValid, onInvalid, submitOptions) => {
+  const submit = async (onValid, onInvalidOrOptions, positionalOptions) => {
+    const submitOptions = typeof onInvalidOrOptions === "object" ? onInvalidOrOptions : positionalOptions;
+    const onInvalid = typeof onInvalidOrOptions === "function" ? onInvalidOrOptions : submitOptions?.onInvalid;
     if (inFlight.count > 0 && submitOptions?.force !== true) {
       return { kind: "skipped" };
     }
@@ -798,6 +1052,7 @@ var createForm = (schema, options) => {
         try {
           onInvalid?.(merged);
         } catch (error) {
+          submitOptions?.onError?.(error);
           return { kind: "error", error };
         }
         return { kind: "invalid", errors: merged };
@@ -824,7 +1079,10 @@ var createForm = (schema, options) => {
     }
   };
   if (options.validateOnMount === true) {
-    validate();
+    const result = validate();
+    if (result.kind === "pending") {
+      void result.promise.catch(reportBackgroundFailure);
+    }
   }
   return Object.freeze({
     schema,
@@ -917,7 +1175,7 @@ var createForm = (schema, options) => {
     },
     setErrors: (errors) => store.setState((state) => ({
       ...state,
-      ...errorChannels(state, { serverErrors: errors })
+      ...errorChannels(state, { serverErrors: dropEmptyLists(errors) })
     })),
     addErrors: (errors) => store.setState((state) => {
       const entries = Object.entries(errors);
@@ -960,11 +1218,11 @@ var createForm = (schema, options) => {
       if (next.values !== state.values) {
         clearArrayOpsUnder(store, "");
       }
-      const serverErrors = patch.serverErrors !== void 0 ? patch.serverErrors : next.values !== state.values ? releaseChangedSlices(state.serverErrors, state.values, next.values) : state.serverErrors;
+      const serverErrors = patch.serverErrors !== void 0 ? dropEmptyLists(patch.serverErrors) : next.values !== state.values ? releaseChangedSlices(state.serverErrors, state.values, next.values) : state.serverErrors;
       store.setState(() => ({
         ...next,
         ...errorChannels(state, {
-          schemaErrors: next.schemaErrors,
+          schemaErrors: patch.schemaErrors === void 0 ? state.schemaErrors : dropEmptyLists(patch.schemaErrors),
           serverErrors
         })
       }));
@@ -1073,9 +1331,14 @@ var createForm = (schema, options) => {
       swapIndices(a, b),
       (len) => Number.isInteger(a) && Number.isInteger(b) && a >= 0 && a < len && b >= 0 && b < len
     ),
-    handleSubmit: (onValid, onInvalid, opts) => async (event) => {
+    handleSubmit: (onValid, onInvalidOrOptions, positionalOptions) => async (event) => {
       event?.preventDefault();
-      const result = await submit(onValid, onInvalid, opts);
+      const opts = typeof onInvalidOrOptions === "object" ? onInvalidOrOptions : positionalOptions;
+      const result = await submit(
+        onValid,
+        onInvalidOrOptions,
+        positionalOptions
+      );
       if (result.kind === "error" && opts?.onError === void 0 && isDevBuild()) {
         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):",
@@ -1101,8 +1364,8 @@ var createForm = (schema, options) => {
     restore: (snap) => {
       clearArrayOpsUnder(store, "");
       store.setState(() => {
-        const schemaErrors = snap.schemaErrors ?? emptyErrors;
-        const serverErrors = snap.serverErrors ?? emptyErrors;
+        const schemaErrors = dropEmptyLists(snap.schemaErrors ?? emptyErrors);
+        const serverErrors = dropEmptyLists(snap.serverErrors ?? emptyErrors);
         return {
           ...snap,
           schemaErrors,
@@ -1132,11 +1395,13 @@ var createDebouncer = (ms) => {
   const timer = {
     current: null
   };
+  const scheduled = { current: null };
   const cancel = () => {
     if (timer.current !== null) {
       clearTimeout(timer.current);
       timer.current = null;
     }
+    scheduled.current = null;
   };
   const schedule = (run) => {
     cancel();
@@ -1144,37 +1409,50 @@ var createDebouncer = (ms) => {
       run();
       return;
     }
+    scheduled.current = run;
     timer.current = setTimeout(() => {
       timer.current = null;
+      scheduled.current = null;
       run();
     }, ms);
   };
+  const flush = () => {
+    const run = scheduled.current;
+    if (run === null) return;
+    cancel();
+    run();
+  };
   return Object.freeze({
     schedule,
     cancel,
+    flush,
     pending: () => timer.current !== null
   });
 };
 
 // src/core/persist.ts
 var kindOf = (value) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
-var conflictsWith = (draft, reference) => {
-  if (draft === void 0 || draft === null) return false;
-  if (reference === void 0 || reference === null) return false;
+var joinPath = (base, key) => base === "" ? String(key) : `${base}.${String(key)}`;
+var conflictPath = (draft, reference, path, flexibleAt) => {
+  if (draft === void 0 || draft === null) return null;
+  if (reference === void 0 || reference === null) return null;
   const draftKind = kindOf(draft);
   const referenceKind = kindOf(reference);
-  if (draftKind !== referenceKind) return true;
+  if (draftKind !== referenceKind) return flexibleAt(path) ? null : path;
   if (draftKind === "array") {
     const [d] = draft;
     const [r] = reference;
-    return conflictsWith(d, r);
+    return conflictPath(d, r, joinPath(path, 0), flexibleAt);
   }
   if (draftKind === "object") {
     const d = draft;
     const r = reference;
-    return Object.keys(d).some((key) => conflictsWith(d[key], r[key]));
+    return Object.keys(d).reduce(
+      (found, key) => found ?? conflictPath(d[key], r[key], joinPath(path, key), flexibleAt),
+      null
+    );
   }
-  return false;
+  return null;
 };
 var defaultStorage = () => {
   try {
@@ -1187,7 +1465,35 @@ var persistForm = (form, options) => {
   const storage = options.storage ?? defaultStorage();
   const debounceMs = options.debounceMs ?? 300;
   const apply = options.apply ?? "adopt";
-  const applyDraft = (values) => apply === "edit" || apply === "restore" ? form.setValues(values) : form.adoptValues(values);
+  const schema = form.schema;
+  const fillRequiredGaps = (draft, initial, path) => {
+    if (!isPlainObject(draft) || !isPlainObject(initial)) return draft;
+    return Object.keys(initial).reduce(
+      (acc, key) => {
+        const childPath = joinPath(path, key);
+        if (Object.hasOwn(draft, key)) {
+          const next = fillRequiredGaps(draft[key], initial[key], childPath);
+          return Object.is(next, draft[key]) ? acc : { ...acc, [key]: next };
+        }
+        if (initial[key] === void 0) return acc;
+        const sub = fieldSchemaForIntrospection(schema, childPath);
+        return sub !== null && isClearableSchema(sub) ? acc : { ...acc, [key]: initial[key] };
+      },
+      draft
+    );
+  };
+  const applyDraft = (values) => {
+    const filled = fillRequiredGaps(
+      values,
+      form.getState().initialValues,
+      ""
+    );
+    if (apply === "edit" || apply === "restore") {
+      form.setValues(filled);
+    } else {
+      form.adoptValues(filled);
+    }
+  };
   const referenceShape = () => {
     try {
       return JSON.parse(JSON.stringify(form.getState().initialValues));
@@ -1195,30 +1501,67 @@ var persistForm = (form, options) => {
       return void 0;
     }
   };
-  const load = () => {
+  const flexibleAt = (path) => schemaAllowsKindChangeAt(schema, path);
+  const inspect = () => {
+    const raw = (() => {
+      try {
+        return storage === null ? null : storage.getItem(options.key);
+      } catch {
+        return null;
+      }
+    })();
+    if (raw === null) return { kind: "absent" };
     try {
-      const raw = storage === null ? null : storage.getItem(options.key);
-      if (raw === null) return false;
       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 && !versioned) {
+        return {
+          kind: "ignored",
+          reason: `it carries no version and this configuration expects version ${String(options.version)}`
+        };
+      }
       if (options.version === void 0 && typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "__v") && Object.hasOwn(parsed, "values")) {
-        return false;
+        return {
+          kind: "ignored",
+          reason: "it was written with a version and this configuration has none"
+        };
       }
       const wrapper = parsed;
-      if (versioned && wrapper.__v !== options.version) return false;
-      if (versioned && wrapper.values === void 0) return false;
+      if (versioned && wrapper.__v !== options.version) {
+        return {
+          kind: "ignored",
+          reason: `its version (${String(wrapper.__v)}) is not the configured version (${String(options.version)})`
+        };
+      }
+      if (versioned && wrapper.values === void 0) {
+        return { kind: "ignored", reason: "its version wrapper holds no values" };
+      }
       const values = versioned ? wrapper.values : parsed;
-      if (values === null || values === void 0) return false;
+      if (values === null || values === void 0) {
+        return { kind: "ignored", reason: "it holds no values" };
+      }
       const reference = referenceShape();
-      if (reference !== void 0 && conflictsWith(values, reference)) {
-        return false;
+      const conflict = reference === void 0 ? null : conflictPath(values, reference, "", flexibleAt);
+      if (conflict !== null) {
+        return {
+          kind: "ignored",
+          reason: `its shape conflicts with the form's initial values at "${conflict}" (set the version option when the schema changes)`
+        };
       }
       applyDraft(values);
-      return true;
+      return { kind: "applied" };
     } catch {
-      return false;
+      return { kind: "ignored", reason: "it is not valid JSON" };
+    }
+  };
+  const load = () => {
+    const outcome = inspect();
+    if (outcome.kind === "ignored" && isDevBuild()) {
+      console.warn(
+        `[formstand] persistForm: ignored the draft under "${options.key}": ${outcome.reason}. The next edit overwrites it.`
+      );
     }
+    return outcome.kind === "applied";
   };
   const writeDraft = (values) => {
     try {
@@ -1232,24 +1575,28 @@ var persistForm = (form, options) => {
     }
   };
   const writes = createDebouncer(debounceMs);
-  const cancelPending = () => writes.cancel();
   if (apply !== "manual") {
     load();
   }
+  const cleared = { current: false };
   const unsubscribe = form.watchValues((values) => {
+    if (cleared.current && values === form.getState().initialValues) return;
+    cleared.current = false;
     writes.schedule(() => writeDraft(values));
   });
   return Object.freeze({
     load,
+    flush: () => writes.flush(),
     clear: () => {
-      cancelPending();
+      writes.cancel();
+      cleared.current = true;
       try {
         storage?.removeItem(options.key);
       } catch {
       }
     },
     dispose: () => {
-      cancelPending();
+      writes.flush();
       unsubscribe();
     }
   });
@@ -1261,6 +1608,7 @@ var usePersistForm = (form, options) => {
     latestOptions.current = options;
   });
   const key = options.key;
+  const storage = options.storage;
   useEffect(() => {
     const handle = persistForm(form, latestOptions.current);
     inner.current = handle;
@@ -1268,10 +1616,11 @@ var usePersistForm = (form, options) => {
       inner.current = null;
       handle.dispose();
     };
-  }, [form, key]);
+  }, [form, key, storage]);
   return useMemo(
     () => ({
       load: () => inner.current?.load() ?? false,
+      flush: () => inner.current?.flush(),
       clear: () => inner.current?.clear(),
       // dispose stops THIS component's watching early; the effect cleanup
       // still runs its own dispose harmlessly (persistForm's dispose is
@@ -1305,9 +1654,12 @@ var useForm = (schema, options) => {
 var hasFieldError = (error) => error !== void 0 && error.length > 0;
 var ariaInvalid = (field) => hasFieldError(field.error) ? true : void 0;
 var numberToInputText = (value) => value === void 0 || value === null || Number.isNaN(value) ? "" : String(value);
+var DECIMAL_TEXT = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
 var parseNumberText = (text) => {
-  if (text.trim() === "") return { kind: "empty" };
-  const parsed = Number(text);
+  const trimmed = text.trim();
+  if (trimmed === "") return { kind: "empty" };
+  if (!DECIMAL_TEXT.test(trimmed)) return { kind: "invalid" };
+  const parsed = Number(trimmed);
   return Number.isFinite(parsed) ? { kind: "number", value: parsed } : { kind: "invalid" };
 };
 var textInputProps = (field) => ({
@@ -1335,11 +1687,11 @@ var numberInputProps = (field) => ({
   onBlur: field.onBlur
 });
 var dateToInputText = (value) => {
-  if (value === void 0 || value === null || Number.isNaN(value.getTime())) {
-    return "";
-  }
+  if (value === void 0 || value === null) return "";
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
   const pad = (part) => String(part).padStart(2, "0");
-  return `${String(value.getFullYear()).padStart(4, "0")}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`;
+  return `${String(date.getFullYear()).padStart(4, "0")}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
 };
 var parseDateText = (text) => {
   if (text.trim() === "") return { kind: "empty" };
@@ -1419,7 +1771,8 @@ var useMaskedInput = (field, options) => {
           field.setValue(parsed.value);
           return;
         case "empty": {
-          const empty = field.clearable || typeof field.initialValue !== "string" ? field.emptyValue : "";
+          const isStringField = typeof field.initialValue === "string" || typeof field.value === "string";
+          const empty = field.clearable || !isStringField ? field.emptyValue : "";
           setEdit({ raw: text, pushed: empty });
           field.setValue(empty);
           return;
@@ -1478,7 +1831,8 @@ var useFormSteps = (form, steps) => {
   const goTo = useCallback(
     async (target) => {
       const count = latest.current.length;
-      const clamped = Math.max(0, Math.min(target, count - 1));
+      if (!Number.isFinite(target)) return currentStep.current;
+      const clamped = Math.max(0, Math.min(Math.trunc(target), count - 1));
       if (clamped <= step) {
         setStep(clamped);
         return clamped;
@@ -1551,8 +1905,7 @@ var useFormAction = (form, onValid, options) => {
       const { onValid: handler, options: opts } = latest.current;
       const result = await form.submit(
         (data) => handler(data, formData),
-        opts?.onInvalid,
-        opts?.onError === void 0 ? void 0 : { onError: opts.onError }
+        opts ?? {}
       );
       warnUnobserved(result, opts, "useFormAction");
     },
@@ -1568,8 +1921,7 @@ var useFormActionState = (form, action, initialState, options) => {
         async (data) => {
           nextRef.current = await action(prev, data, formData);
         },
-        options?.onInvalid,
-        options?.onError === void 0 ? void 0 : { onError: options.onError }
+        options ?? {}
       );
       warnUnobserved(result, options, "useFormActionState");
       return nextRef.current;
@@ -1635,6 +1987,12 @@ function useField(form, pathArg, options) {
       debouncerRef.current = null;
     };
   }, [form, path, debounceMs]);
+  const validateNow = useCallback(() => {
+    const result = form.validateField(path);
+    if (result.kind === "pending") {
+      void result.promise.catch(reportBackgroundFailure);
+    }
+  }, [form, path]);
   const triggerValidate = useCallback(() => {
     if (debounceMs !== void 0 && debounceMs > 0) {
       const debouncer = debouncerRef.current ?? createDebouncer(debounceMs);
@@ -1646,12 +2004,12 @@ function useField(form, pathArg, options) {
         const rebased = state.values !== scheduledValues && state.values === state.initialValues;
         if (rebased) return;
         if (!Object.is(getAtPath(state.values, path), scheduled)) return;
-        void form.validateFieldAsync(path);
+        void form.validateFieldAsync(path).catch(reportBackgroundFailure);
       });
       return;
     }
-    form.validateField(path);
-  }, [form, path, debounceMs]);
+    validateNow();
+  }, [form, path, debounceMs, validateNow]);
   const setValue = useCallback(
     (value) => {
       const before = form.store.getState();
@@ -1700,9 +2058,10 @@ function useField(form, pathArg, options) {
       state.submitCount > 0,
       true
     )) {
-      triggerValidate();
+      debouncerRef.current?.cancel();
+      validateNow();
     }
-  }, [form, path, triggerValidate]);
+  }, [form, path, validateNow]);
   return useMemo(
     () => ({
       path: slice.path,
@@ -2054,6 +2413,14 @@ function useFieldArray(form, pathArg) {
     ]
   );
 }
+
+// src/react/useVariantFieldArray.ts
+function useVariantFieldArray(form, unionPath, field) {
+  return useFieldArray(
+    form,
+    `${unionPath}.${field}`
+  );
+}
 var useFormError = (form) => useStore(
   form.store,
   useShallow((state) => state.errors[""])
@@ -2061,29 +2428,37 @@ var useFormError = (form) => useStore(
 function useFormValues(form) {
   return useStore(form.store, (state) => state.values);
 }
-
-// src/react/useFields.ts
 function useFields(form, paths) {
+  const [arity] = useState(paths.length);
+  if (paths.length !== arity) {
+    throw new Error(
+      `[formstand] useFields: the paths tuple changed length (${String(arity)} to ${String(paths.length)}); its length and order must be stable across renders, so pass a literal or a module-level constant.`
+    );
+  }
   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();
-      });
-    }
-  };
+  return useMemo(() => {
+    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();
+        });
+      }
+    };
+  }, fields);
 }
 function useIsDirty(form, path) {
   return useStore(
@@ -2132,6 +2507,11 @@ var createFormHooks = (form, name) => {
     field
   );
   const useBoundFieldArray = (path) => useFieldArray(structural, path);
+  const useBoundVariantFieldArray = (unionPath, field) => useVariantFieldArray(
+    structural,
+    unionPath,
+    field
+  );
   const useBoundSelector = (selector) => useFormSelector(structural, selector);
   const useBoundSelectorShallow = (selector) => useFormSelectorShallow(structural, selector);
   const useBoundError = () => useFormError(structural);
@@ -2146,11 +2526,15 @@ var createFormHooks = (form, name) => {
   );
   const useBoundSubmitCount = () => useSubmitCount(structural);
   const useBoundSteps = (steps) => useFormSteps(form, steps);
+  const useBoundAction = (onValid, options) => useFormAction(form, onValid, options);
+  const useBoundActionState = (action, initialState, options) => useFormActionState(form, action, initialState, options);
+  const useBoundPersist = (options) => usePersistForm(form, options);
   const prefix = capitalize(name ?? "");
   return {
     [`use${prefix}Field`]: useBoundField,
     [`use${prefix}VariantField`]: useBoundVariantField,
     [`use${prefix}FieldArray`]: useBoundFieldArray,
+    [`use${prefix}VariantFieldArray`]: useBoundVariantFieldArray,
     [`use${prefix}Selector`]: useBoundSelector,
     [`use${prefix}SelectorShallow`]: useBoundSelectorShallow,
     [`use${prefix}Error`]: useBoundError,
@@ -2161,7 +2545,10 @@ var createFormHooks = (form, name) => {
     [`use${prefix}SubmitCount`]: useBoundSubmitCount,
     [`use${prefix}Values`]: useBoundValues,
     [`use${prefix}Fields`]: useBoundFields,
-    [`use${prefix}Steps`]: useBoundSteps
+    [`use${prefix}Steps`]: useBoundSteps,
+    [`use${prefix}Action`]: useBoundAction,
+    [`use${prefix}ActionState`]: useBoundActionState,
+    [`use${prefix}Persist`]: useBoundPersist
   };
 };
 var useFieldA11y = (error) => {
@@ -2456,6 +2843,6 @@ var focusField = (path, root) => {
   return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(namedControls(scope).filter(isFocusCandidate)) : focusFirstOf(pathCandidates(scope, [path]).filter(isFocusCandidate));
 };
 
-export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, hasFieldError, isAsyncRequiredError, isClearableSchema, numberInputProps, numberToInputText, parseDateText, parseNumberText, persistForm, selectProps, textInputProps, useField, useFieldArray, useFields, useForm, useFormAction, useFormActionState, useFormError, useFormSteps, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useMaskedInput, useNumberInput, usePersistForm, useSubmitCount, useVariantField, validateAsync, validateSync };
+export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, getAtPath, hasFieldError, isAsyncRequiredError, isClearableSchema, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useFields, useForm, useFormAction, useFormActionState, useFormError, useFormSteps, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useMaskedInput, useNumberInput, usePersistForm, useSubmitCount, useVariantField, useVariantFieldArray, validateAsync, validateSync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map