formstand 0.25.0 → 0.26.1

package/CHANGELOG.md

@@ -1,5 +1,210 @@
 # Changelog
 
+## 0.26.1 — 2026-11-13
+
+### Added
+
+- `watchField` listeners receive the previous snapshot as a second
+  argument, `listener(snapshot, prev)`, the way `watchValue` passes the
+  previous value.
+- `useFieldArray` returns `validateAsync()`, the awaitable twin of
+  `validate()`; `FieldArrayFormApi` gains the optional
+  `validateFieldAsync` member that backs it.
+- `useVariantField` and `useFields` (and their bound forms from
+  `createFormHooks`) take the same `options` as `useField`, so a variant
+  or composite field can debounce its change validation.
+- `FormActionOptions.force`, mirroring `SubmitOptions.force`.
+
+### Fixed
+
+- `validateOnMount` judges every baseline the form takes: the pass runs
+  again after `reset()` (unless `keepErrors`) and after `adoptValues()`,
+  so a persisted draft adopted over the initial values no longer opens a
+  `useIsValid` gate for an invalid draft.
+- `validateFieldsAsync` pruned live errors with a stale full-form map
+  when a batch mixed a full-parse path with an index into an empty array
+  and the values changed in flight; the prune now rides only while the
+  whole values reference held.
+- `restore()` disowns in-flight async passes the way `reset()` and
+  `adoptValues()` do, so a pass started before the restore cannot commit
+  a verdict onto the restored state.
+- `persistForm`'s gap fill fills a nullable-but-required key the draft
+  lacks, no longer splices one union variant's key into another, and no
+  longer resurrects a `z.record` key the draft removed.
+- A manual `load()` no longer writes the draft it just read straight
+  back to storage.
+- The auto-apply skips a draft the form already holds, so
+  `usePersistForm` with an inline `storage` object (a resubscribe per
+  render) no longer re-adopts the draft every render, wiping errors and
+  dirty state and looping with `useFormValues`; StrictMode's second
+  mount adopts nothing either.
+- `useFieldArray`'s change and blur triggers report a throwing async
+  array refine through `console.error`, the way `useField`'s triggers
+  do, instead of leaving an unhandled rejection.
+- `useFieldArray.update(index, item)` past the end (or with a
+  non-integer index) is refused with a warning, like the index ops; it
+  used to write `null` holes.
+- `useFormSteps.next()` and `goTo()` judge a step on its live values: a
+  step value that changed while an async rule was in flight is validated
+  again instead of advancing on the stale verdict. With no steps defined
+  `next()` no longer sets the index to -1.
+- `dateToInputText` reads a date-only string (a persisted draft's
+  `"2026-03-01"`) as the calendar date it spells; the Date constructor
+  parsed it as UTC midnight, which rendered the previous day west of UTC.
+- The typed variant hooks bind a union nested inside another union's
+  variant (`useVariantField(form, "shape.detail", "x")`); `UnionValueAt`
+  walked common keys only, so neither spelling compiled.
+- `CheckboxField` without a `label` no longer renders an empty `<label>`
+  around the input.
+- The devtools panel keeps its held snapshot across a collapse (0.26.0
+  moved the held state into the open branch), and its diff shows a
+  field cleared to `undefined` as `"undefined"` instead of `{}`.
+- `fillAndBlurField` returns the fill's result when the blur gate did
+  not validate (`mode: "onChange"`, or after a submit), instead of
+  `undefined` for a pass it had started.
+- `persistForm`'s gap fill walks through lazy, intersection and
+  preprocess schemas again (the container check above stopped at them),
+  so a plain required key under those roots is filled as in 0.26.0.
+- `useField`'s `emptyValue` and `clearable` for a key shared by union
+  variants follow the variant the live discriminant selects, so clearing
+  a nullable field on the active variant writes `null` instead of the
+  first variant's `undefined`.
+- A write the path walker refuses (a string key into an array, a key
+  through a `Date`) no longer rebuilds the values spine, so watchers do
+  not fire, the op log is kept and spine server verdicts stay, matching
+  the "value left unchanged" warning.
+- A field-scoped pass that ran the full parse takes the parse's current
+  message for an out-of-scope key it already held, so a cross-field rule
+  with a dynamic message no longer shows the stale text.
+- `usePersistForm` forwards every storage call to the storage of the
+  latest render through a proxy instead of resubscribing when the
+  `storage` identity changes: an inline storage object resubscribed on
+  every render, and each outgoing subscription flushed, which collapsed
+  the debounce to nothing and re-read the draft each render.
+- `useFormSteps` reads the step the user is on when `next()`, `back()`
+  or `goTo()` is called, not the step of the render the closure came
+  from, so two awaited `next()` calls from one handler advance twice and
+  a `back()` pressed during an in-flight advance wins at once. The three
+  are reference-stable across renders now.
+- `dateToInputText` renders `""` for a date-shaped string that spells no
+  real day (`"2026-02-31"`) instead of the Date constructor's reading.
+- The devtools panel renders `NaN` and the infinities as their own
+  spelling in the fields table and the diff instead of `null`, and
+  forgets its held snapshot when the `form` prop changes to another
+  form instead of restoring the old form's state into the new one.
+
+## 0.26.0 — 2026-11-12
+
+### Added
+
+- `PersistHandle.flush()` writes the pending debounced draft now, for
+  the moments that cannot wait out the debounce (a route change, a
+  `pagehide` handler). `dispose()` flushes too; see Fixed below.
+- `submit` and `handleSubmit` take an options object in the second
+  position: `submit(onValid, { onInvalid, onError, force })`, the shape
+  `useFormAction`'s `FormActionOptions` always had, so `submit(onValid,
+  undefined, { force: true })` is no longer the only spelling.
+  `SubmitOptions` gains `onInvalid`; a positional `onInvalid` wins when
+  both are given. The positional shape stays.
+- `ErrorPath<TValues, D>` is exported: the path type `setError`,
+  `clearErrors`, `validateField` and `validateFieldAsync` take
+  (`FieldPath` plus the root `""`), for wrappers that forward those
+  calls.
+- `createFormHooks` binds the three hooks it skipped while the docs
+  promised every hook: `use{Name}Action` and `use{Name}ActionState`
+  (the form-actions bridges) and `use{Name}Persist` (`usePersistForm`),
+  with the `BoundUseAction`, `BoundUseActionState` and `BoundUsePersist`
+  types exported.
+- `FieldSnapshot` (from `getFieldState` and `watchField`) carries
+  `initialValue` and `firstError`, matching `useField`.
+- `fillField`, `blurField` and `fillAndBlurField` from `formstand/testing`
+  return the `FieldValidationResult` when the gate validated
+  (`undefined` when it did not), so a test can await a pending async
+  refine instead of guessing a delay.
+
+### Fixed
+
+- A throwing async refinement (a rejected fetch inside `refine(async
+  ...)`) left `isValidatingForm` or `isValidating[path]` at `true` for
+  good: none of the async passes released their flag when the parse
+  rejected, so every spinner and submit gate built on them stuck after
+  one network failure. The passes now release the flags they own before
+  the rejection travels on to whoever awaited them. The passes nobody
+  awaits, `validateOnMount` and the change and blur triggers inside
+  `useField`, report the error through `console.error` instead of
+  leaving an unhandled rejection.
+- Switching a discriminated union's variant through its discriminant
+  (`useField(form, "payment.method").setValue("paypal")`, which is how
+  generated forms bind it) left the old variant's schema errors in place
+  until a full `validate()` ran, so `useIsValid` read `false` for a form
+  the schema accepted. A field-scoped pass that runs the full parse (any
+  path under a union or a refined object) now also drops the schema
+  errors elsewhere that the parse no longer reports. It still adds
+  nothing outside its scope.
+- `setErrors({ field: [] })`, an `updateState` patch of either error
+  channel, and `restore()` kept empty lists as entries, where `setError`
+  and `addErrors` dropped them, so one state read valid to `useIsValid`,
+  errored to `useFormSteps`, and `[]` from `useField(...).error`. Every
+  writer now drops an empty list.
+- A throwing `onInvalid` resolved `{ kind: "error" }` without calling
+  `onError`; it does now, like a throwing `onValid`.
+- `persistForm`: unmounting inside the debounce window lost the last
+  edits, because `dispose()` cancelled the pending write. It writes the
+  draft first now.
+- `persistForm`: `clear()` followed by `reset()` (the usual after-submit
+  pair) wrote the fresh baseline straight back as a draft, which the
+  next visit then adopted over whatever initial values the app had
+  meanwhile computed. After `clear()`, a rebase that leaves the form
+  pristine no longer writes; the next real edit does.
+- `persistForm`: a draft stored before the schema gained a key erased
+  that key's initial value from `values` and `initialValues`, so
+  `reset()` could not bring it back and the user saw zod's generic
+  message instead of yours. Required keys the draft lacks are now filled
+  from the initial values (nested objects included); optional keys stay
+  absent, since an optional the user cleared looks the same.
+- `persistForm`'s shape guard refused legitimate drafts: `z.coerce.number()`
+  behind a `""` initial value, and unions whose variants shape the same
+  key differently. The guard now asks the schema whether a kind change
+  is legitimate at the path before refusing, and a dev build logs why a
+  draft that was present got ignored (version mismatch, shape conflict
+  and its path, corrupt JSON), where `load()` used to return a silent
+  `false`.
+- `usePersistForm` ignored a change of `options.storage` and kept writing
+  to the first storage it saw; it resubscribes on it, as it does for
+  `key`.
+- `DateField` and `dateInputProps` threw `value.getTime is not a
+  function` at render after a persisted draft loaded a `Date` back as
+  the string JSON made of it (persist does not revive Dates, by design),
+  and the rewritten draft made the crash stick across visits. The input
+  now shows the string's calendar date; the schema still rejects it at
+  validation.
+- `useFormSteps.goTo(NaN)` (a `Number("")` from an empty option)
+  recursed without bound and froze the tab. A target that is not a
+  finite number now resolves the current index.
+- `parseNumberText`, behind `NumberField`, `numberInputProps` and
+  `useNumberInput`, accepted every JavaScript number literal, so typing
+  `0x10` stored 16. It reads plain decimal notation only.
+- `useMaskedInput` cleared a required string field to `undefined` when
+  its key was omitted from the initial values, because the initial
+  value's type was the only signal. The current value counts too, so the
+  field clears to `""` and reports your message instead of zod's.
+- `useField`'s `debounceMs` also delayed the blur validation. Blur now
+  drops a pending timer and validates at once.
+- `useFields` returned a fresh object, `fields` array and `onBlur` on
+  every render while its sibling hooks memoize; it keeps its identity
+  until one of its fields changes. A paths tuple that changes length now
+  throws the hook's own message, ahead of React's hooks-count error.
+- `FormstandDevtools` labelled a server error as "(showing)" or "(behind
+  a schema error)" by walking the flat schema-error map as a path, so a
+  root verdict always read as behind and a nested key always as
+  showing. It reads the key directly now.
+- `FormstandDevtools` threw on a `bigint` value (`z.bigint()`), in the
+  value preview and in the diff; a bigint renders as its literal
+  spelling (`10n`).
+- `FormstandDevtools` walked every leaf through `getFieldState` and ran
+  `diff()` on every store write while collapsed; a collapsed panel now
+  keeps only its store subscription.
+
 ## 0.25.0 — 2026-11-12
 
 ### Added

package/dist/chunk-XJ6W5CKB.js

@@ -0,0 +1,22 @@
+import { useStore } from 'zustand/react';
+import { useShallow } from 'zustand/react/shallow';
+
+// src/react/useFormSelector.ts
+function useFormSelector(form, selector) {
+  return useStore(form.store, selector);
+}
+function useFormSelectorShallow(form, selector) {
+  return useStore(form.store, useShallow(selector));
+}
+
+// src/core/env.ts
+var isDevBuild = () => typeof process === "undefined" || process.env?.["NODE_ENV"] !== "production";
+var isDevToolsBuild = () => {
+  if (typeof process === "undefined") return false;
+  const env = process.env?.["NODE_ENV"];
+  return typeof env === "string" && env !== "production";
+};
+
+export { isDevBuild, isDevToolsBuild, useFormSelector, useFormSelectorShallow };
+//# sourceMappingURL=chunk-XJ6W5CKB.js.map
+//# sourceMappingURL=chunk-XJ6W5CKB.js.map

package/dist/chunk-XJ6W5CKB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/useFormSelector.ts","../src/core/env.ts"],"names":[],"mappings":";;;;AAiCO,SAAS,eAAA,CACd,MACA,QAAA,EACG;AACH,EAAA,OAAO,QAAA,CAAS,IAAA,CAAK,KAAA,EAAO,QAAQ,CAAA;AACtC;AAcO,SAAS,sBAAA,CACd,MACA,QAAA,EACG;AACH,EAAA,OAAO,QAAA,CAAS,IAAA,CAAK,KAAA,EAAO,UAAA,CAAW,QAAQ,CAAC,CAAA;AAClD;;;AC/CO,IAAM,UAAA,GAAa,MACxB,OAAO,OAAA,KAAY,eACnB,OAAA,CAAQ,GAAA,GAAM,UAAU,CAAA,KAAM;AAWzB,IAAM,kBAAkB,MAAe;AAC5C,EAAA,IAAI,OAAO,OAAA,KAAY,WAAA,EAAa,OAAO,KAAA;AAC3C,EAAA,MAAM,GAAA,GAAM,OAAA,CAAQ,GAAA,GAAM,UAAU,CAAA;AACpC,EAAA,OAAO,OAAO,GAAA,KAAQ,QAAA,IAAY,GAAA,KAAQ,YAAA;AAC5C","file":"chunk-XJ6W5CKB.js","sourcesContent":["import type { z } from \"zod\";\nimport type { StoreApi } from \"zustand/vanilla\";\nimport { useStore } from \"zustand/react\";\nimport { useShallow } from \"zustand/react/shallow\";\nimport type { Form } from \"../core/createForm\";\nimport type { DefaultPathDepth, PathDepth } from \"../core/fieldPath\";\nimport type { FormState } from \"../core/types\";\n\ntype ReadonlyStore<T> = Pick<\n  StoreApi<T>,\n  \"getState\" | \"getInitialState\" | \"subscribe\"\n>;\n\nexport type FormStateApi = Readonly<{\n  store: ReadonlyStore<FormState<unknown>>;\n}>;\n\nexport function useFormSelector<\n  TSchema extends z.ZodType,\n  U,\n  D extends PathDepth = DefaultPathDepth,\n>(\n  form: Form<TSchema, D>,\n  selector: (state: FormState<z.input<TSchema>>) => U,\n): U;\n// The `schema?: undefined` brand forces Form<TSchema> (which has a real\n// `schema` property) to bind only the typed overload above. Without\n// it, Form<TSchema> would structurally satisfy FormStateApi too and a\n// bad selector could silently widen to FormState<unknown>.\nexport function useFormSelector<U>(\n  form: FormStateApi & { readonly schema?: undefined },\n  selector: (state: FormState<unknown>) => U,\n): U;\nexport function useFormSelector<U>(\n  form: FormStateApi,\n  selector: (state: FormState<unknown>) => U,\n): U {\n  return useStore(form.store, selector);\n}\n\nexport function useFormSelectorShallow<\n  TSchema extends z.ZodType,\n  U,\n  D extends PathDepth = DefaultPathDepth,\n>(\n  form: Form<TSchema, D>,\n  selector: (state: FormState<z.input<TSchema>>) => U,\n): U;\nexport function useFormSelectorShallow<U>(\n  form: FormStateApi & { readonly schema?: undefined },\n  selector: (state: FormState<unknown>) => U,\n): U;\nexport function useFormSelectorShallow<U>(\n  form: FormStateApi,\n  selector: (state: FormState<unknown>) => U,\n): U {\n  return useStore(form.store, useShallow(selector));\n}\n","// The dev-build test the library consults before emitting a console\n// warning. Bundlers that define NODE_ENV fold it to a constant and drop the\n// dev-only branches; the `typeof process` guard keeps the SAME expression\n// from throwing in a runtime that defines no `process` at all (a CDN/ESM\n// consumer, a test runner without the define). That last case matters most\n// on the submit path: handleSubmit promises never to reject, and the\n// warning that fires only when a save failed was the one line that could\n// break the promise exactly on the failure path. It FAILS OPEN on purpose:\n// an unknowable environment gets the warnings, which cost nothing but a\n// console line.\nexport const isDevBuild = (): boolean =>\n  typeof process === \"undefined\" ||\n  process.env?.[\"NODE_ENV\"] !== \"production\";\n\n// The gate for the two sites that EXPOSE form state: the FormstandDevtools\n// panel (renders every value and error into the page) and the zustand\n// devtools middleware (streams every write to the Redux extension). These\n// must FAIL CLOSED: isDevBuild's \"no process means dev\" reading let a\n// CDN/ESM, Deno, or worker production build mount the panel and keep the\n// middleware live for any end user with the extension installed. Only a\n// readable NODE_ENV that is a string other than \"production\" counts as\n// development; no process, no env, or an unset NODE_ENV all read as\n// production here.\nexport const isDevToolsBuild = (): boolean => {\n  if (typeof process === \"undefined\") return false;\n  const env = process.env?.[\"NODE_ENV\"];\n  return typeof env === \"string\" && env !== \"production\";\n};\n"]}

package/dist/{createForm-CMVALnc3.d.cts → createForm-BXDd9Tg4.d.cts}

@@ -130,6 +130,7 @@ type SubmitHandler<TSchema extends z.ZodType> = (data: z.output<TSchema>) => voi
 type InvalidSubmitHandler = (errors: ErrorMap) => void;
 type SubmitOptions = Readonly<{
     force?: boolean;
+    onInvalid?: InvalidSubmitHandler;
     onError?: (error: unknown) => void;
 }>;
 type SubmitResult<TOutput> = Readonly<{
@@ -152,7 +153,9 @@ type ResetOptions = Readonly<{
 }>;
 type FieldSnapshot<TValue> = Readonly<{
     value: TValue;
+    initialValue: TValue;
     error: readonly string[] | undefined;
+    firstError: string | undefined;
     touched: boolean;
     dirty: boolean;
     isValidating: boolean;
@@ -164,7 +167,7 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
     getState: () => FormState<z.input<TSchema>>;
     subscribe: (listener: (state: FormState<z.input<TSchema>>, prev: FormState<z.input<TSchema>>) => void) => () => void;
     getField: <P extends FieldPath<z.input<TSchema>, D>>(path: P) => FieldValue<z.input<TSchema>, P>;
-    watchField: <P extends FieldPath<z.input<TSchema>, D>>(path: P, listener: (snapshot: FieldSnapshot<FieldValue<z.input<TSchema>, P>>) => void) => () => void;
+    watchField: <P extends FieldPath<z.input<TSchema>, D>>(path: P, listener: (snapshot: FieldSnapshot<FieldValue<z.input<TSchema>, P>>, previous: FieldSnapshot<FieldValue<z.input<TSchema>, P>>) => void) => () => void;
     watchValue: <P extends FieldPath<z.input<TSchema>, D>>(path: P, listener: (value: FieldValue<z.input<TSchema>, P>, previous: FieldValue<z.input<TSchema>, P>) => void) => () => void;
     watchValues: (listener: (values: z.input<TSchema>, previous: z.input<TSchema>) => void) => () => void;
     setValue: <P extends FieldPath<z.input<TSchema>, D>>(path: P, value: FieldValue<z.input<TSchema>, P>) => void;
@@ -188,15 +191,23 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
     validateAsync: () => Promise<SettledValidationResult<z.output<TSchema>>>;
     validateFieldAsync: (path: ErrorPath<z.input<TSchema>, D>) => Promise<SettledFieldValidationResult>;
     validateFieldsAsync: (paths: readonly FieldPath<z.input<TSchema>, D>[]) => Promise<SettledFieldsValidationResult>;
-    submit: (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions) => Promise<SubmitResult<z.output<TSchema>>>;
+    submit: {
+        (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions): Promise<SubmitResult<z.output<TSchema>>>;
+        (onValid: SubmitHandler<TSchema>, options: SubmitOptions): Promise<SubmitResult<z.output<TSchema>>>;
+    };
     arrayPush: <P extends ArrayFieldPath<z.input<TSchema>, D>>(path: P, item: ArrayItemOf<FieldValue<z.input<TSchema>, P>>) => void;
     arrayRemove: (path: ArrayFieldPath<z.input<TSchema>, D>, index: number) => void;
     arrayInsert: <P extends ArrayFieldPath<z.input<TSchema>, D>>(path: P, index: number, item: ArrayItemOf<FieldValue<z.input<TSchema>, P>>) => void;
     arrayMove: (path: ArrayFieldPath<z.input<TSchema>, D>, from: number, to: number) => void;
     arraySwap: (path: ArrayFieldPath<z.input<TSchema>, D>, a: number, b: number) => void;
-    handleSubmit: (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions) => (event?: {
-        preventDefault: () => void;
-    }) => Promise<SubmitResult<z.output<TSchema>>>;
+    handleSubmit: {
+        (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions): (event?: {
+            preventDefault: () => void;
+        }) => Promise<SubmitResult<z.output<TSchema>>>;
+        (onValid: SubmitHandler<TSchema>, options: SubmitOptions): (event?: {
+            preventDefault: () => void;
+        }) => Promise<SubmitResult<z.output<TSchema>>>;
+    };
     diff: () => Readonly<Record<string, unknown>>;
     dirtyFields: () => readonly string[];
     snapshot: () => FormState<z.input<TSchema>>;
@@ -204,5 +215,5 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
 }>;
 declare const createForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(schema: TSchema, options: CreateFormOptions<TSchema, D>) => Form<TSchema, NoInfer<D>>;
 
-export { createForm as p, emptyValueForSchema as q, flattenIssues as r, isAsyncRequiredError as s, isClearableSchema as t, shouldValidateOn as u, validateAsync as v, validateSync as w };
-export type { ArrayFieldPath as A, BoolMap as B, CreateFormOptions as C, DefaultPathDepth as D, ErrorMap as E, Form as F, InvalidSubmitHandler as I, PathDepth as P, ReadonlyStoreApi as R, SettledFieldValidationResult as S, ValidationMode as V, FormState as a, FieldValidationResult as b, FieldPath as c, FieldValue as d, ArrayItemOf as e, FieldSnapshot as f, FieldsValidationResult as g, ResetOptions as h, SettledFieldsValidationResult as i, SettledValidationResult as j, SubmitHandler as k, SubmitOptions as l, SubmitResult as m, ValidationResult as n, ValidationTrigger as o };
+export { createForm as q, emptyValueForSchema as r, flattenIssues as s, isAsyncRequiredError as t, isClearableSchema as u, shouldValidateOn as v, validateAsync as w, validateSync as x };
+export type { ArrayFieldPath as A, BoolMap as B, CreateFormOptions as C, DefaultPathDepth as D, ErrorMap as E, Form as F, InvalidSubmitHandler as I, PathDepth as P, ReadonlyStoreApi as R, SettledFieldValidationResult as S, ValidationMode as V, FormState as a, FieldValidationResult as b, FieldPath as c, FieldValue as d, ArrayItemOf as e, ErrorPath as f, FieldSnapshot as g, FieldsValidationResult as h, ResetOptions as i, SettledFieldsValidationResult as j, SettledValidationResult as k, SubmitHandler as l, SubmitOptions as m, SubmitResult as n, ValidationResult as o, ValidationTrigger as p };

package/dist/{createForm-CMVALnc3.d.ts → createForm-BXDd9Tg4.d.ts}

@@ -130,6 +130,7 @@ type SubmitHandler<TSchema extends z.ZodType> = (data: z.output<TSchema>) => voi
 type InvalidSubmitHandler = (errors: ErrorMap) => void;
 type SubmitOptions = Readonly<{
     force?: boolean;
+    onInvalid?: InvalidSubmitHandler;
     onError?: (error: unknown) => void;
 }>;
 type SubmitResult<TOutput> = Readonly<{
@@ -152,7 +153,9 @@ type ResetOptions = Readonly<{
 }>;
 type FieldSnapshot<TValue> = Readonly<{
     value: TValue;
+    initialValue: TValue;
     error: readonly string[] | undefined;
+    firstError: string | undefined;
     touched: boolean;
     dirty: boolean;
     isValidating: boolean;
@@ -164,7 +167,7 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
     getState: () => FormState<z.input<TSchema>>;
     subscribe: (listener: (state: FormState<z.input<TSchema>>, prev: FormState<z.input<TSchema>>) => void) => () => void;
     getField: <P extends FieldPath<z.input<TSchema>, D>>(path: P) => FieldValue<z.input<TSchema>, P>;
-    watchField: <P extends FieldPath<z.input<TSchema>, D>>(path: P, listener: (snapshot: FieldSnapshot<FieldValue<z.input<TSchema>, P>>) => void) => () => void;
+    watchField: <P extends FieldPath<z.input<TSchema>, D>>(path: P, listener: (snapshot: FieldSnapshot<FieldValue<z.input<TSchema>, P>>, previous: FieldSnapshot<FieldValue<z.input<TSchema>, P>>) => void) => () => void;
     watchValue: <P extends FieldPath<z.input<TSchema>, D>>(path: P, listener: (value: FieldValue<z.input<TSchema>, P>, previous: FieldValue<z.input<TSchema>, P>) => void) => () => void;
     watchValues: (listener: (values: z.input<TSchema>, previous: z.input<TSchema>) => void) => () => void;
     setValue: <P extends FieldPath<z.input<TSchema>, D>>(path: P, value: FieldValue<z.input<TSchema>, P>) => void;
@@ -188,15 +191,23 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
     validateAsync: () => Promise<SettledValidationResult<z.output<TSchema>>>;
     validateFieldAsync: (path: ErrorPath<z.input<TSchema>, D>) => Promise<SettledFieldValidationResult>;
     validateFieldsAsync: (paths: readonly FieldPath<z.input<TSchema>, D>[]) => Promise<SettledFieldsValidationResult>;
-    submit: (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions) => Promise<SubmitResult<z.output<TSchema>>>;
+    submit: {
+        (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions): Promise<SubmitResult<z.output<TSchema>>>;
+        (onValid: SubmitHandler<TSchema>, options: SubmitOptions): Promise<SubmitResult<z.output<TSchema>>>;
+    };
     arrayPush: <P extends ArrayFieldPath<z.input<TSchema>, D>>(path: P, item: ArrayItemOf<FieldValue<z.input<TSchema>, P>>) => void;
     arrayRemove: (path: ArrayFieldPath<z.input<TSchema>, D>, index: number) => void;
     arrayInsert: <P extends ArrayFieldPath<z.input<TSchema>, D>>(path: P, index: number, item: ArrayItemOf<FieldValue<z.input<TSchema>, P>>) => void;
     arrayMove: (path: ArrayFieldPath<z.input<TSchema>, D>, from: number, to: number) => void;
     arraySwap: (path: ArrayFieldPath<z.input<TSchema>, D>, a: number, b: number) => void;
-    handleSubmit: (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions) => (event?: {
-        preventDefault: () => void;
-    }) => Promise<SubmitResult<z.output<TSchema>>>;
+    handleSubmit: {
+        (onValid: SubmitHandler<TSchema>, onInvalid?: InvalidSubmitHandler, options?: SubmitOptions): (event?: {
+            preventDefault: () => void;
+        }) => Promise<SubmitResult<z.output<TSchema>>>;
+        (onValid: SubmitHandler<TSchema>, options: SubmitOptions): (event?: {
+            preventDefault: () => void;
+        }) => Promise<SubmitResult<z.output<TSchema>>>;
+    };
     diff: () => Readonly<Record<string, unknown>>;
     dirtyFields: () => readonly string[];
     snapshot: () => FormState<z.input<TSchema>>;
@@ -204,5 +215,5 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
 }>;
 declare const createForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(schema: TSchema, options: CreateFormOptions<TSchema, D>) => Form<TSchema, NoInfer<D>>;
 
-export { createForm as p, emptyValueForSchema as q, flattenIssues as r, isAsyncRequiredError as s, isClearableSchema as t, shouldValidateOn as u, validateAsync as v, validateSync as w };
-export type { ArrayFieldPath as A, BoolMap as B, CreateFormOptions as C, DefaultPathDepth as D, ErrorMap as E, Form as F, InvalidSubmitHandler as I, PathDepth as P, ReadonlyStoreApi as R, SettledFieldValidationResult as S, ValidationMode as V, FormState as a, FieldValidationResult as b, FieldPath as c, FieldValue as d, ArrayItemOf as e, FieldSnapshot as f, FieldsValidationResult as g, ResetOptions as h, SettledFieldsValidationResult as i, SettledValidationResult as j, SubmitHandler as k, SubmitOptions as l, SubmitResult as m, ValidationResult as n, ValidationTrigger as o };
+export { createForm as q, emptyValueForSchema as r, flattenIssues as s, isAsyncRequiredError as t, isClearableSchema as u, shouldValidateOn as v, validateAsync as w, validateSync as x };
+export type { ArrayFieldPath as A, BoolMap as B, CreateFormOptions as C, DefaultPathDepth as D, ErrorMap as E, Form as F, InvalidSubmitHandler as I, PathDepth as P, ReadonlyStoreApi as R, SettledFieldValidationResult as S, ValidationMode as V, FormState as a, FieldValidationResult as b, FieldPath as c, FieldValue as d, ArrayItemOf as e, ErrorPath as f, FieldSnapshot as g, FieldsValidationResult as h, ResetOptions as i, SettledFieldsValidationResult as j, SettledValidationResult as k, SubmitHandler as l, SubmitOptions as m, SubmitResult as n, ValidationResult as o, ValidationTrigger as p };

package/dist/devtools/index.cjs

@@ -13,40 +13,6 @@ var isDevToolsBuild = () => {
   const env = process.env?.["NODE_ENV"];
   return typeof env === "string" && env !== "production";
 };
-
-// src/core/path.ts
-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);
 function useFormSelectorShallow(form, selector) {
   return react$1.useStore(form.store, shallow.useShallow(selector));
 }
@@ -163,10 +129,15 @@ var styles = {
     cursor: "pointer"
   }
 };
+var jsonReplacer = (_key, value) => typeof value === "bigint" ? `${String(value)}n` : value === void 0 ? "undefined" : typeof value === "number" && !Number.isFinite(value) ? String(value) : value;
 var preview = (value) => {
   if (value === void 0) return "undefined";
   if (value instanceof Date) return value.toISOString();
-  const json = JSON.stringify(value);
+  if (typeof value === "bigint") return `${String(value)}n`;
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return String(value);
+  }
+  const json = JSON.stringify(value, jsonReplacer);
   return json === void 0 ? String(value) : json.length > 60 ? `${json.slice(0, 57)}\u2026` : json;
 };
 var flags = (row) => [
@@ -193,15 +164,14 @@ var Section = ({
   /* @__PURE__ */ jsxRuntime.jsx("p", { style: styles.sectionTitle, children: title }),
   children
 ] });
-var DevtoolsPanel = ({
+var OpenPanel = ({
   form,
-  position = "bottom-right",
-  defaultOpen = false,
-  label = "formstand"
+  state,
+  label,
+  held,
+  onHold,
+  onClose
 }) => {
-  const state = useDevtoolsState(form);
-  const [open, setOpen] = react.useState(defaultOpen);
-  const [held, setHeld] = react.useState(null);
   const rows = leafPaths(state.values).map((path) => {
     const field = form.getFieldState(path);
     return {
@@ -218,7 +188,7 @@ var DevtoolsPanel = ({
     rows.map((row) => row.path)
   );
   const diff = form.diff();
-  return /* @__PURE__ */ jsxRuntime.jsx("div", { style: { ...styles.root, ...anchorFor(position) }, children: open ? /* @__PURE__ */ jsxRuntime.jsxs("div", { style: styles.panel, children: [
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { style: styles.panel, children: [
     /* @__PURE__ */ jsxRuntime.jsxs("div", { style: styles.header, children: [
       /* @__PURE__ */ jsxRuntime.jsx("strong", { children: label }),
       /* @__PURE__ */ jsxRuntime.jsxs("span", { style: styles.muted, children: [
@@ -227,15 +197,7 @@ var DevtoolsPanel = ({
         state.isValidatingForm ? " \xB7 validating" : "",
         state.submitCount > 0 ? ` \xB7 submits ${state.submitCount}` : ""
       ] }),
-      /* @__PURE__ */ jsxRuntime.jsx(
-        "button",
-        {
-          type: "button",
-          style: styles.button,
-          onClick: () => setOpen(false),
-          children: "close"
-        }
-      )
+      /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", style: styles.button, onClick: onClose, children: "close" })
     ] }),
     /* @__PURE__ */ jsxRuntime.jsx(Section, { title: `fields (${rows.length})`, children: /* @__PURE__ */ jsxRuntime.jsxs("table", { style: styles.table, children: [
       /* @__PURE__ */ jsxRuntime.jsx("thead", { children: /* @__PURE__ */ jsxRuntime.jsxs("tr", { children: [
@@ -274,17 +236,17 @@ var DevtoolsPanel = ({
         " ",
         /* @__PURE__ */ jsxRuntime.jsx("span", { style: styles.error, children: messages.join(", ") }),
         " ",
-        /* @__PURE__ */ jsxRuntime.jsx("span", { style: styles.muted, children: getAtPath(state.schemaErrors, key) === void 0 ? "(showing)" : "(behind a schema error)" })
+        /* @__PURE__ */ jsxRuntime.jsx("span", { style: styles.muted, children: Object.hasOwn(state.schemaErrors, key) ? "(behind a schema error)" : "(showing)" })
       ] }, key))
     ] }),
-    /* @__PURE__ */ jsxRuntime.jsx(Section, { title: "diff vs initial", children: /* @__PURE__ */ jsxRuntime.jsx("pre", { style: styles.pre, children: Object.keys(diff).length === 0 ? "clean" : JSON.stringify(diff, null, 2) }) }),
+    /* @__PURE__ */ jsxRuntime.jsx(Section, { title: "diff vs initial", children: /* @__PURE__ */ jsxRuntime.jsx("pre", { style: styles.pre, children: Object.keys(diff).length === 0 ? "clean" : JSON.stringify(diff, jsonReplacer, 2) }) }),
     /* @__PURE__ */ jsxRuntime.jsxs(Section, { title: "time travel", children: [
       /* @__PURE__ */ jsxRuntime.jsx(
         "button",
         {
           type: "button",
           style: styles.button,
-          onClick: () => setHeld(form.snapshot()),
+          onClick: () => onHold(form.snapshot()),
           children: "snapshot"
         }
       ),
@@ -304,7 +266,29 @@ var DevtoolsPanel = ({
       " ",
       /* @__PURE__ */ jsxRuntime.jsx("span", { style: styles.muted, children: held === null ? "nothing held" : "snapshot held" })
     ] })
-  ] }) : /* @__PURE__ */ jsxRuntime.jsxs(
+  ] });
+};
+var DevtoolsPanel = ({
+  form,
+  position = "bottom-right",
+  defaultOpen = false,
+  label = "formstand"
+}) => {
+  const state = useDevtoolsState(form);
+  const [open, setOpen] = react.useState(defaultOpen);
+  const [held, setHeld] = react.useState(null);
+  const heldForThisForm = held !== null && held.form === form ? held.snapshot : null;
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { style: { ...styles.root, ...anchorFor(position) }, children: open ? /* @__PURE__ */ jsxRuntime.jsx(
+    OpenPanel,
+    {
+      form,
+      state,
+      label,
+      held: heldForThisForm,
+      onHold: (snapshot) => setHeld({ form, snapshot }),
+      onClose: () => setOpen(false)
+    }
+  ) : /* @__PURE__ */ jsxRuntime.jsxs(
     "button",
     {
       type: "button",