formstand 0.25.0 → 0.26.1

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,162 @@ 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);
+  const child = writeSegments(arr[index], rest, value, kindAt, [
+    ...prefix,
+    index
+  ]);
+  if (index < arr.length && child === arr[index]) return arr;
+  return Array.from({ length }, (_, i) => i === index ? child : 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);
+    const child = writeSegments(obj[key2], rest, value, kindAt, [
+      ...prefix,
+      key2
+    ]);
+    if (child === obj[key2] && Object.hasOwn(obj, key2)) return obj;
+    return { ...obj, [key2]: child };
+  }
+  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 +290,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]) => [
@@ -159,7 +321,11 @@ var unwrapForWalk = (s) => {
   if (s instanceof z.ZodDefault || s instanceof z.ZodPrefault || s instanceof z.ZodCatch || s instanceof z.ZodReadonly || s instanceof z.ZodNonOptional) {
     return s.def.innerType;
   }
-  if (s instanceof z.ZodPipe) return s.def.in;
+  if (s instanceof z.ZodPipe) {
+    const input = s.def.in;
+    return input instanceof z.ZodTransform ? s.def.out : input;
+  }
+  if (s instanceof z.ZodLazy) return s.def.getter();
   return null;
 };
 var isLeafSchema = (s) => s instanceof z.ZodString || s instanceof z.ZodNumber || s instanceof z.ZodBoolean || s instanceof z.ZodBigInt || s instanceof z.ZodDate || s instanceof z.ZodEnum || s instanceof z.ZodLiteral || s instanceof z.ZodNull || s instanceof z.ZodUndefined || s instanceof z.ZodVoid || s instanceof z.ZodNaN || s instanceof z.ZodSymbol;
@@ -185,14 +351,71 @@ 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;
 };
-var fieldSchemaForIntrospection = (schema, path) => {
-  const childOf = (s, segment) => {
+var optionClaims = (option, discriminator, tag) => {
+  const strip = (s) => {
+    const inner = unwrapForWalk(s);
+    return inner === null ? s : strip(inner);
+  };
+  const node = strip(option);
+  if (!(node instanceof z.ZodObject)) return false;
+  const shape = node.shape;
+  const at = Object.hasOwn(shape, discriminator) ? shape[discriminator] : void 0;
+  if (at === void 0) return false;
+  const leaf = strip(at);
+  if (leaf instanceof z.ZodLiteral) {
+    return leaf.def.values.includes(tag);
+  }
+  if (leaf instanceof z.ZodEnum) {
+    return Object.values(leaf.def.entries).includes(
+      tag
+    );
+  }
+  return false;
+};
+var fieldSchemaForIntrospection = (schema, path, values) => {
+  const childOf = (s, segment, holder) => {
     const inner = unwrapForWalk(s);
-    if (inner !== null) return childOf(inner, segment);
+    if (inner !== null) return childOf(inner, segment, holder);
     if (s instanceof z.ZodObject && typeof segment === "string") {
       const shape = s.shape;
       return Object.hasOwn(shape, segment) ? shape[segment] ?? null : null;
@@ -206,19 +429,45 @@ var fieldSchemaForIntrospection = (schema, path) => {
     if (s instanceof z.ZodRecord) {
       return s.valueType;
     }
+    if (s instanceof z.ZodIntersection) {
+      return childOf(s.def.left, segment, holder) ?? childOf(s.def.right, segment, holder);
+    }
     if (s instanceof z.ZodDiscriminatedUnion || s instanceof z.ZodUnion) {
       const options = s.def.options;
-      return options.reduce(
-        (found, option) => found ?? childOf(option, segment),
+      const discriminator = s instanceof z.ZodDiscriminatedUnion ? s.def.discriminator : null;
+      const tag = discriminator !== null && typeof holder === "object" && holder !== null ? holder[discriminator] : void 0;
+      const live = discriminator === null || tag === void 0 ? void 0 : options.find((option) => optionClaims(option, discriminator, tag));
+      const candidates = live === void 0 ? options : [live];
+      return candidates.reduce(
+        (found, option) => found ?? childOf(option, segment, holder),
         null
       );
     }
     return null;
   };
-  return parsePath(path).reduce(
-    (current, segment) => current === null ? null : childOf(current, segment),
-    schema
-  );
+  const segments = parsePath(path);
+  return segments.reduce(
+    (acc, segment) => acc.s === null ? acc : {
+      s: childOf(
+        acc.s,
+        segment,
+        values === void 0 ? void 0 : getAtPath(values, acc.prefix)
+      ),
+      prefix: acc.prefix === "" ? String(segment) : `${acc.prefix}.${String(segment)}`
+    },
+    { s: schema, prefix: "" }
+  ).s;
+};
+var schemaAcceptsUndefined = (schema) => schema instanceof z.ZodOptional || schema instanceof z.ZodDefault || schema instanceof z.ZodPrefault || schema instanceof z.ZodNullable && schemaAcceptsUndefined(schema.unwrap());
+var isObjectSchemaAt = (schema, path) => {
+  const sub = fieldSchemaForIntrospection(schema, path);
+  if (sub === null) return true;
+  const strip = (s) => {
+    const inner = unwrapForWalk(s);
+    return inner === null ? s : strip(inner);
+  };
+  const node = strip(sub);
+  return !(node instanceof z.ZodUnion || node instanceof z.ZodDiscriminatedUnion || node instanceof z.ZodRecord || node instanceof z.ZodMap || node instanceof z.ZodSet || node instanceof z.ZodArray || node instanceof z.ZodTuple || isLeafSchema(node));
 };
 var containerKindAt = (schema) => (prefix) => {
   const unwrapAll = (s) => {
@@ -269,7 +518,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 +576,27 @@ 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));
+  const unchanged = kept.length === entries.length && kept.every(([k, list]) => full[k] === list);
+  return unchanged ? prev : Object.fromEntries(kept.map(([k, list]) => [k, full[k] ?? list]));
+};
+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 +706,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 +725,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 +770,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 +790,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 +809,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 +820,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 +832,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 +854,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 +901,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 +919,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 +959,15 @@ var createForm = (schema, options) => {
         Object.fromEntries(
           fresh.flatMap((path) => Object.entries(errorsFor(path)))
         ),
-        fresh
+        fresh,
+        // The prune map describes the values the batch STARTED with.
+        // A skip scope (an index into an empty array) still reads as
+        // fresh after an unrelated change, so a batch can commit under
+        // changed values; pruning with the stale map then dropped
+        // errors committed elsewhere in flight (an email error landing
+        // while a wizard step with such a path validated). The prune
+        // rides only while the whole values reference held.
+        parsed.kind === "full" && live.values === valuesAtStart ? parsed.errors : null
       ),
       isValidating: omitKeys(state.isValidating, ownedKeys)
     }));
@@ -681,24 +988,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 +1072,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 +1115,7 @@ var createForm = (schema, options) => {
         try {
           onInvalid?.(merged);
         } catch (error) {
+          submitOptions?.onError?.(error);
           return { kind: "error", error };
         }
         return { kind: "invalid", errors: merged };
@@ -823,9 +1141,14 @@ var createForm = (schema, options) => {
       }
     }
   };
-  if (options.validateOnMount === true) {
-    validate();
-  }
+  const judgeBaseline = () => {
+    if (options.validateOnMount !== true) return;
+    const result = validate();
+    if (result.kind === "pending") {
+      void result.promise.catch(reportBackgroundFailure);
+    }
+  };
+  judgeBaseline();
   return Object.freeze({
     schema,
     store,
@@ -840,8 +1163,12 @@ var createForm = (schema, options) => {
       return store.subscribe((state) => {
         const next = snapshotField(state, path);
         if (!shallowFieldEqual(ref.current, next)) {
+          const prev = ref.current;
           ref.current = next;
-          listener(next);
+          listener(
+            next,
+            prev
+          );
         }
       });
     },
@@ -876,10 +1203,12 @@ var createForm = (schema, options) => {
       if (Object.is(getAtPath(currentValues, path), value) && (value !== void 0 || hasOwnSlot(currentValues, path))) {
         return;
       }
+      const next = setAtPath(currentValues, path, value, kindAt);
+      if (next === currentValues) return;
       clearArrayOpsUnder(store, path);
       store.setState((state) => ({
         ...state,
-        values: setAtPath(state.values, path, value, kindAt),
+        values: next,
         ...errorChannels(state, {
           serverErrors: releaseSpine(state.serverErrors, path)
         })
@@ -917,7 +1246,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 +1289,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
         })
       }));
@@ -986,6 +1315,7 @@ var createForm = (schema, options) => {
         isValidating: emptyBools,
         isValidatingForm: false
       }));
+      judgeBaseline();
     },
     reset: (nextInitial, resetOptions) => {
       sequences.clear();
@@ -1010,6 +1340,7 @@ var createForm = (schema, options) => {
           isValidatingForm: false
         };
       });
+      if (resetOptions?.keepErrors !== true) judgeBaseline();
     },
     resetField: (path) => {
       const initialSlot = slotAtPath(
@@ -1073,9 +1404,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):",
@@ -1099,10 +1435,11 @@ var createForm = (schema, options) => {
     },
     snapshot: () => store.getState(),
     restore: (snap) => {
+      sequences.clear();
       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 +1469,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 +1483,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 +1539,49 @@ 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;
+    if (!isObjectSchemaAt(schema, path)) 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 && schemaAcceptsUndefined(sub) ? acc : { ...acc, [key]: initial[key] };
+      },
+      draft
+    );
+  };
+  const applying = { current: false };
+  const applyDraft = (values) => {
+    const filled = fillRequiredGaps(
+      values,
+      form.getState().initialValues,
+      ""
+    );
+    applying.current = true;
+    try {
+      if (apply === "edit" || apply === "restore") {
+        form.setValues(filled);
+      } else {
+        form.adoptValues(filled);
+      }
+    } finally {
+      applying.current = false;
+    }
+  };
+  const isCurrent = (values) => {
+    try {
+      return JSON.stringify(values) === JSON.stringify(form.getState().values);
+    } catch {
+      return false;
+    }
+  };
   const referenceShape = () => {
     try {
       return JSON.parse(JSON.stringify(form.getState().initialValues));
@@ -1195,31 +1589,70 @@ var persistForm = (form, options) => {
       return void 0;
     }
   };
-  const load = () => {
+  const flexibleAt = (path) => schemaAllowsKindChangeAt(schema, path);
+  const inspect = (skipWhenCurrent) => {
+    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)`
+        };
       }
+      if (skipWhenCurrent && isCurrent(values)) return { kind: "applied" };
       applyDraft(values);
-      return true;
+      return { kind: "applied" };
     } catch {
-      return false;
+      return { kind: "ignored", reason: "it is not valid JSON" };
     }
   };
+  const loadWith = (skipWhenCurrent) => {
+    const outcome = inspect(skipWhenCurrent);
+    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 load = () => loadWith(false);
   const writeDraft = (values) => {
     try {
       storage?.setItem(
@@ -1232,24 +1665,29 @@ var persistForm = (form, options) => {
     }
   };
   const writes = createDebouncer(debounceMs);
-  const cancelPending = () => writes.cancel();
   if (apply !== "manual") {
-    load();
+    loadWith(true);
   }
+  const cleared = { current: false };
   const unsubscribe = form.watchValues((values) => {
+    if (applying.current) return;
+    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,17 +1699,31 @@ var usePersistForm = (form, options) => {
     latestOptions.current = options;
   });
   const key = options.key;
+  const hasStorage = options.storage !== void 0;
+  const storageProxy = useMemo(
+    () => ({
+      getItem: (k) => latestOptions.current.storage?.getItem(k) ?? null,
+      setItem: (k, v) => latestOptions.current.storage?.setItem(k, v),
+      removeItem: (k) => latestOptions.current.storage?.removeItem(k)
+    }),
+    []
+  );
   useEffect(() => {
-    const handle = persistForm(form, latestOptions.current);
+    const options2 = latestOptions.current;
+    const handle = persistForm(form, {
+      ...options2,
+      ...options2.storage === void 0 ? {} : { storage: storageProxy }
+    });
     inner.current = handle;
     return () => {
       inner.current = null;
       handle.dispose();
     };
-  }, [form, key]);
+  }, [form, key, hasStorage, storageProxy]);
   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 +1757,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 +1790,17 @@ 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 "";
+  if (typeof value === "string") {
+    const text = value;
+    const parsed = parseDateText(text);
+    if (parsed.kind === "date") return dateToInputText(parsed.value);
+    if (/^\d{4}-\d{2}-\d{2}$/.test(text.trim())) 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 +1880,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;
@@ -1435,6 +1897,15 @@ var useMaskedInput = (field, options) => {
     }
   };
 };
+var settleOnLiveValues = async (form, fields, round = 0) => {
+  const before = fields.map((path) => form.getField(path));
+  const result = await form.validateFieldsAsync(fields);
+  const changed = fields.some(
+    (path, i) => !Object.is(form.getField(path), before[i])
+  );
+  if (!changed) return result;
+  return round < 3 ? settleOnLiveValues(form, fields, round + 1) : null;
+};
 var useFormSteps = (form, steps) => {
   const [step, setStep] = useState(0);
   const [visited, setVisited] = useState(
@@ -1448,7 +1919,8 @@ var useFormSteps = (form, steps) => {
     async (index) => {
       const definition = latest.current[index];
       if (definition === void 0) return true;
-      const result = await form.validateFieldsAsync(definition.fields);
+      const result = await settleOnLiveValues(form, definition.fields);
+      if (result === null) return false;
       if (result.kind === "invalid") {
         Object.keys(result.errors).forEach((key) => {
           form.setTouched(key, true);
@@ -1460,45 +1932,49 @@ var useFormSteps = (form, steps) => {
     [form]
   );
   const currentStep = useRef(step);
-  useEffect(() => {
-    currentStep.current = step;
-  });
+  const navigate = useCallback((target) => {
+    currentStep.current = target;
+    setStep(target);
+  }, []);
   const next = useCallback(async () => {
-    const ok = await validateStep(step);
+    const from = currentStep.current;
+    const ok = await validateStep(from);
     if (!ok) return false;
-    if (currentStep.current !== step) return false;
-    const target = Math.min(step + 1, latest.current.length - 1);
-    setStep(target);
+    if (currentStep.current !== from) return false;
+    const target = Math.max(0, Math.min(from + 1, latest.current.length - 1));
+    navigate(target);
     setVisited((prev) => /* @__PURE__ */ new Set([...prev, target]));
     return true;
-  }, [validateStep, step]);
+  }, [validateStep, navigate]);
   const back = useCallback(() => {
-    setStep((prev) => Math.max(prev - 1, 0));
-  }, []);
+    navigate(Math.max(currentStep.current - 1, 0));
+  }, [navigate]);
   const goTo = useCallback(
     async (target) => {
       const count = latest.current.length;
-      const clamped = Math.max(0, Math.min(target, count - 1));
-      if (clamped <= step) {
-        setStep(clamped);
+      if (!Number.isFinite(target)) return currentStep.current;
+      const from = currentStep.current;
+      const clamped = Math.max(0, Math.min(Math.trunc(target), count - 1));
+      if (clamped <= from) {
+        navigate(clamped);
         return clamped;
       }
-      const walk = async (from) => {
-        if (from >= clamped) return clamped;
-        return await validateStep(from) ? walk(from + 1) : from;
+      const walk = async (at) => {
+        if (at >= clamped) return clamped;
+        return await validateStep(at) ? walk(at + 1) : at;
       };
-      const landed = await walk(step);
-      if (currentStep.current !== step) return currentStep.current;
-      setStep(landed);
+      const landed = await walk(from);
+      if (currentStep.current !== from) return currentStep.current;
+      navigate(landed);
       setVisited(
         (prev) => /* @__PURE__ */ new Set([
           ...prev,
-          ...Array.from({ length: landed - step + 1 }, (_, i) => step + i)
+          ...Array.from({ length: landed - from + 1 }, (_, i) => from + i)
         ])
       );
       return landed;
     },
-    [validateStep, step]
+    [validateStep, navigate]
   );
   const errorFlags = useFormSelectorShallow(
     form,
@@ -1551,8 +2027,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 +2043,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;
@@ -1593,6 +2067,7 @@ var createFormContext = () => {
   return { Provider, useFormContext };
 };
 function useField(form, pathArg, options) {
+  const formSchema = form.schema;
   const slice = useStore(
     form.store,
     useShallow((state) => {
@@ -1608,25 +2083,26 @@ function useField(form, pathArg, options) {
         error: entryAt(state.errors, p),
         touched: flagAt(state.touched, p),
         dirty: isFieldDirty(value, initialValue2),
-        isValidating: flagAt(state.isValidating, p)
+        isValidating: flagAt(state.isValidating, p),
+        // Resolved inside the selector so a discriminant change re-reads
+        // the ACTIVE variant's wrapper for a key the variants share; the
+        // schema node is a stable reference, so the shallow compare holds.
+        schema: formSchema === void 0 ? null : fieldSchemaForIntrospection(formSchema, p, state.values)
       };
     })
   );
   const path = slice.path;
-  const formSchema = form.schema;
+  const sub = slice.schema;
   const initialValue = slice.initialValue;
   const { emptyValue, clearable } = useMemo(() => {
-    if (formSchema !== void 0) {
-      const sub = fieldSchemaForIntrospection(formSchema, path);
-      if (sub !== null) {
-        return {
-          emptyValue: emptyValueForSchema(sub),
-          clearable: isClearableSchema(sub)
-        };
-      }
+    if (sub !== null) {
+      return {
+        emptyValue: emptyValueForSchema(sub),
+        clearable: isClearableSchema(sub)
+      };
     }
     return initialValue === null ? { emptyValue: null, clearable: true } : { emptyValue: void 0, clearable: false };
-  }, [formSchema, path, initialValue]);
+  }, [sub, initialValue]);
   const debounceMs = options?.debounceMs;
   const debouncerRef = useRef(null);
   useEffect(() => {
@@ -1635,6 +2111,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 +2128,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 +2182,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,
@@ -1729,10 +2212,11 @@ function useField(form, pathArg, options) {
 }
 
 // src/react/useVariantField.ts
-function useVariantField(form, unionPath, field) {
+function useVariantField(form, unionPath, field, options) {
   return useField(
     form,
-    `${unionPath}.${field}`
+    `${unionPath}.${field}`,
+    options
   );
 }
 var EMPTY_ITEMS = [];
@@ -1895,6 +2379,12 @@ function useFieldArray(form, pathArg) {
   const items = slice.items;
   const error = slice.error;
   const ids = deriveIds(form.store, path, items).ids;
+  const validateNow = useCallback(() => {
+    const result = form.validateField?.(path);
+    if (result?.kind === "pending") {
+      void result.promise.catch(reportBackgroundFailure);
+    }
+  }, [form, path]);
   const revalidate = useCallback(() => {
     const state = form.store.getState();
     if (shouldValidateOn(
@@ -1904,9 +2394,9 @@ function useFieldArray(form, pathArg) {
       state.submitCount > 0,
       flagAt(state.touched, path)
     )) {
-      form.validateField?.(path);
+      validateNow();
     }
-  }, [form, path]);
+  }, [form, path, validateNow]);
   const push = useCallback(
     (item) => {
       form.arrayPush(path, item);
@@ -1971,13 +2461,17 @@ function useFieldArray(form, pathArg) {
       state.submitCount > 0,
       true
     )) {
-      form.validateField?.(path);
+      validateNow();
     }
-  }, [form, path]);
+  }, [form, path, validateNow]);
   const validate = useCallback(
     () => form.validateField?.(path) ?? { kind: "valid" },
     [form, path]
   );
+  const validateAsync2 = useCallback(
+    () => form.validateFieldAsync?.(path) ?? Promise.resolve({ kind: "valid" }),
+    [form, path]
+  );
   const replace = useCallback(
     (next) => {
       form.setValue?.(path, next);
@@ -1987,7 +2481,15 @@ function useFieldArray(form, pathArg) {
   );
   const update = useCallback(
     (index, item) => {
-      form.setValue?.(`${path}.${index}`, item);
+      const current = getAtPath(form.store.getState().values, path);
+      const length = Array.isArray(current) ? current.length : 0;
+      if (!Number.isInteger(index) || index < 0 || index >= length) {
+        console.warn(
+          `[formstand] array op on "${path}" with an out-of-range or non-integer index (length ${String(length)}). Operation skipped.`
+        );
+        return;
+      }
+      form.setValue?.(`${path}.${String(index)}`, item);
       revalidate();
     },
     [form, path, revalidate]
@@ -2019,6 +2521,7 @@ function useFieldArray(form, pathArg) {
       setTouched,
       onBlur,
       validate,
+      validateAsync: validateAsync2,
       push,
       remove,
       insert,
@@ -2042,6 +2545,7 @@ function useFieldArray(form, pathArg) {
       setTouched,
       onBlur,
       validate,
+      validateAsync2,
       push,
       remove,
       insert,
@@ -2069,29 +2573,41 @@ var useFormError = (form) => useStore(
 function useFormValues(form) {
   return useStore(form.store, (state) => state.values);
 }
-
-// src/react/useFields.ts
-function useFields(form, paths) {
+function useFields(form, paths, options) {
+  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)
+      useField(
+        form,
+        path,
+        options
+      )
     )
   );
-  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(
@@ -2134,10 +2650,11 @@ var capitalize = (name) => name.length === 0 ? name : name.charAt(0).toUpperCase
 var createFormHooks = (form, name) => {
   const structural = form;
   const useBoundField = (path, options) => useField(structural, path, options);
-  const useBoundVariantField = (unionPath, field) => useVariantField(
+  const useBoundVariantField = (unionPath, field, options) => useVariantField(
     structural,
     unionPath,
-    field
+    field,
+    options
   );
   const useBoundFieldArray = (path) => useFieldArray(structural, path);
   const useBoundVariantFieldArray = (unionPath, field) => useVariantFieldArray(
@@ -2153,12 +2670,16 @@ var createFormHooks = (form, name) => {
   const useBoundIsValidating = (path) => useIsValidating(structural, path);
   const useBoundIsSubmitting = () => useIsSubmitting(structural);
   const useBoundValues = () => useFormValues(structural);
-  const useBoundFields = (paths) => useFields(
+  const useBoundFields = (paths, options) => useFields(
     structural,
-    paths
+    paths,
+    options
   );
   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,
@@ -2175,7 +2696,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) => {
@@ -2199,7 +2723,7 @@ var FieldShell = ({
   wrapLabel,
   children
 }) => /* @__PURE__ */ jsxs("div", { className: "zf-field", children: [
-  wrapLabel === true ? /* @__PURE__ */ jsxs("label", { htmlFor: id, className: "zf-label", children: [
+  wrapLabel === true && label !== void 0 ? /* @__PURE__ */ jsxs("label", { htmlFor: id, className: "zf-label", children: [
     children,
     " ",
     label
@@ -2470,6 +2994,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, useVariantFieldArray, 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