formstand 0.25.0 → 0.26.0

package/dist/index.cjs

@@ -298,6 +298,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 zod.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]) => [
@@ -349,6 +355,42 @@ var schemaHasPath = (schema, path) => {
   };
   return walk(schema, parsePath(path), SCHEMA_WALK_BUDGET);
 };
+var schemaAllowsKindChangeAt = (schema, path) => {
+  const flexible = (s) => s instanceof zod.z.ZodUnion || s instanceof zod.z.ZodDiscriminatedUnion || s instanceof zod.z.ZodPipe || s instanceof zod.z.ZodAny || s instanceof zod.z.ZodUnknown || s instanceof zod.z.ZodLazy || s instanceof zod.z.ZodCatch || s.def.coerce === true;
+  const strip = (s) => {
+    if (s instanceof zod.z.ZodOptional || s instanceof zod.z.ZodNullable) {
+      return strip(s.unwrap());
+    }
+    if (s instanceof zod.z.ZodDefault || s instanceof zod.z.ZodPrefault || s instanceof zod.z.ZodReadonly || s instanceof zod.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 zod.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 zod.z.ZodArray) {
+      return typeof head === "number" ? walk(node.element, rest, budget - 1) : true;
+    }
+    if (node instanceof zod.z.ZodTuple && typeof head === "number") {
+      const item = node.def.items[head];
+      return item === void 0 ? true : walk(item, rest, budget - 1);
+    }
+    if (node instanceof zod.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;
@@ -433,7 +475,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;
@@ -491,7 +533,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)
@@ -601,17 +662,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);
       }
@@ -620,7 +681,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) {
@@ -665,7 +726,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
@@ -685,14 +746,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);
@@ -700,7 +765,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,
@@ -711,9 +776,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) };
@@ -723,11 +788,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)
     };
   };
@@ -741,7 +810,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) {
@@ -781,12 +857,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
+            ]
           )
         )
       )
@@ -796,6 +875,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":
@@ -824,7 +915,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)
     }));
@@ -845,24 +937,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);
@@ -921,7 +1021,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" };
     }
@@ -962,6 +1064,7 @@ var createForm = (schema, options) => {
         try {
           onInvalid?.(merged);
         } catch (error) {
+          submitOptions?.onError?.(error);
           return { kind: "error", error };
         }
         return { kind: "invalid", errors: merged };
@@ -988,7 +1091,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,
@@ -1081,7 +1187,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);
@@ -1124,11 +1230,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
         })
       }));
@@ -1237,9 +1343,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):",
@@ -1265,8 +1376,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,
@@ -1313,11 +1424,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();
@@ -1325,37 +1438,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 {
@@ -1368,7 +1494,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));
@@ -1376,30 +1530,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 {
@@ -1413,24 +1604,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();
     }
   });
@@ -1442,6 +1637,7 @@ var usePersistForm = (form, options) => {
     latestOptions.current = options;
   });
   const key = options.key;
+  const storage = options.storage;
   react.useEffect(() => {
     const handle = persistForm(form, latestOptions.current);
     inner.current = handle;
@@ -1449,10 +1645,11 @@ var usePersistForm = (form, options) => {
       inner.current = null;
       handle.dispose();
     };
-  }, [form, key]);
+  }, [form, key, storage]);
   return react.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
@@ -1486,9 +1683,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) => ({
@@ -1516,11 +1716,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" };
@@ -1600,7 +1800,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;
@@ -1667,7 +1868,8 @@ var useFormSteps = (form, steps) => {
   const goTo = react.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;
@@ -1740,8 +1942,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");
     },
@@ -1757,8 +1958,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;
@@ -1824,6 +2024,12 @@ function useField(form, pathArg, options) {
       debouncerRef.current = null;
     };
   }, [form, path, debounceMs]);
+  const validateNow = react.useCallback(() => {
+    const result = form.validateField(path);
+    if (result.kind === "pending") {
+      void result.promise.catch(reportBackgroundFailure);
+    }
+  }, [form, path]);
   const triggerValidate = react.useCallback(() => {
     if (debounceMs !== void 0 && debounceMs > 0) {
       const debouncer = debouncerRef.current ?? createDebouncer(debounceMs);
@@ -1835,12 +2041,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 = react.useCallback(
     (value) => {
       const before = form.store.getState();
@@ -1889,9 +2095,10 @@ function useField(form, pathArg, options) {
       state.submitCount > 0,
       true
     )) {
-      triggerValidate();
+      debouncerRef.current?.cancel();
+      validateNow();
     }
-  }, [form, path, triggerValidate]);
+  }, [form, path, validateNow]);
   return react.useMemo(
     () => ({
       path: slice.path,
@@ -2258,29 +2465,37 @@ var useFormError = (form) => react$1.useStore(
 function useFormValues(form) {
   return react$1.useStore(form.store, (state) => state.values);
 }
-
-// src/react/useFields.ts
 function useFields(form, paths) {
+  const [arity] = react.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 react.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 react$1.useStore(
@@ -2348,6 +2563,9 @@ 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,
@@ -2364,7 +2582,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) => {