formstand 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,6 +1,362 @@
 # Changelog
 
-## Unreleased
+## 0.10.0 — 2026-07-28
+
+### Breaking
+
+- **`validateFields` / `validateFieldsAsync` return discriminated results
+  instead of booleans** (2026-07 self-review #1). `validateFields(paths)` now
+  returns `{ kind: "valid" }`, `{ kind: "invalid", errors }` (the error map
+  scoped to the requested paths), or `{ kind: "pending", promise }` on an
+  async schema — mirroring `validateField`. The old `boolean |
+  Promise<boolean>` union let a truthy in-flight `Promise` silently pass
+  `if (form.validateFields(...))` gates the moment a schema gained an async
+  refine. `validateFieldsAsync` resolves with the settled result instead of a
+  boolean. Migrate `if (ok)` to `if (result.kind === "valid")`.
+- **`FieldFormApi.validateField` must not throw the async-required signal**
+  — `useField` no longer catches it and escalates to `validateFieldAsync`.
+  The declared contract (return `{ kind: "pending", promise }`) has been the
+  library's own behavior since the async-routing rework; custom
+  implementations written against the old throwing style should return the
+  pending result instead.
+
+### Added
+
+- **`pathDepth` option on `createForm`/`useForm`** — a type-level-only,
+  per-form typed-path depth budget (in segments): `createForm(schema, {
+  initialValues, pathDepth: 12 })` widens the `FieldPath` union so deeper
+  paths bind with full inference, threading through every typed surface
+  (`Form<TSchema, D>`, `useField`/`useFieldArray`/`useVariantField`, the
+  flag/selector hooks, `createFormHooks`, `createFormContext<S, D>`, the
+  bound components' `PathsOf`). The runtime ignores it entirely — path APIs
+  always walked any depth — and D infers as a literal from the option.
+  Motivated by one global store backing many forms, whose leaves sit past
+  the default budget. Raising it is a deliberate TypeScript compile-cost
+  trade: the union grows with every extra level, and every path-taking call
+  in the editor pays for it. `D` must be a number literal; budgets up to 25
+  are supported, and the option is CONSTRAINED to the exported `PathDepth`
+  union (`0 | 1 | ... | 25`, exactly the decrement table's range) —
+  `pathDepth: 26`, `pathDepth: -1`, a widened `number`-typed variable, and
+  a UNION value (`cond ? 12 : 9`, which would infer an unusable
+  `Form<S, 9 | 12>`) all fail to compile at the call site instead of
+  silently misbehaving. The same `D extends PathDepth` constraint is
+  enforced on EVERY generic surface carrying a depth parameter — `Form`
+  itself, `createFormContext<S, D>`, `persistForm`, the hooks'
+  explicit-`D` positions — so `Form<S, number>` and
+  `createFormContext<S, 26>()` are compile errors too, not silently
+  unbounded budgets.
+  `FieldPath<T, D>` itself (the compat surface for direct users, still
+  `D extends number`) NORMALIZES any unusable `D` before recursing: a
+  widened `number` (an options object built separately), an out-of-range
+  literal (26, -1 — outside the decrement table, where the decrement would
+  silently no-op), and a finite union (`9 | 12`, or `PathDepth` itself —
+  the decrement distributes over unions and would recurse to the union's
+  max) all fall back to the default depth instead of silently building the
+  enormous ~25-level union (an empirically verified hazard) or
+  hard-erroring TS2615 on recursive value types. The default is now the exported
+  `DefaultPathDepth` alias — one source of truth replacing the 22 scattered
+  `= 9` literals across the typed surfaces. NOT breaking for existing
+  code: `D` is appended LAST with a
+  default on every generic surface (the hooks' typed overloads
+  forward-reference it from the path parameter's constraint, and the
+  selector overloads stay at one type parameter), so existing references —
+  `Form<Schema>`, explicit instantiations like
+  `useFieldArray<typeof schema, "tags">`, `createFormHooks<S, "name">` —
+  keep compiling unchanged; type tests pin the arity, the option's
+  rejection cases, the non-literal fallback, and both directions of
+  `Form<S, 12>` / `Form<S, 9>` non-assignability.
+
+### Changed
+
+- **Default typed-path depth raised from 7 to 9 segments**
+  (`FieldPath<T, D = 9>`). Real-world stores kept hitting the 7-segment cap
+  (the CLI's nested-array output reaches 7 with just three array levels,
+  and one more object wrapper fell off the union). Measured typecheck cost
+  of the wider default across this repo (library + tests + examples) is
+  noise-level. `Form<Schema>` references keep compiling unchanged — the new
+  `D` parameter defaults to 9 everywhere.
+
+### Fixed
+
+- `resetField` on a path with no counterpart in `initialValues` (an appended
+  array row) no longer writes an explicit `undefined` into the values tree —
+  a hole that crashed row components and failed schema validation. The value
+  is left unchanged (with a console warning), and error/touched state under
+  the path still clears (2026-07 self-review #2).
+- `useFieldArray` row ids stay glued to the right rows even when row values
+  are `Object.is`-equal (`remove(0)` on two blank rows handed the survivor
+  the removed row's id, resurrecting the wrong React subtree). The core now
+  records every array op's exact new→old index mapping in an internal
+  per-path op log, and id derivation replays that log — so the fix covers
+  hook-issued ops, IMPERATIVE ops (`form.arrayRemove(...)`), and multiple
+  ops per render batch alike. All hook instances on the same path share one
+  id state, so sibling `useFieldArray` hooks can never disagree on row ids.
+  Whole-array writes that bypass the ops (`setValue`, `restore`) still
+  reconcile by value as before, and replay keeps its exact progress when a
+  chain breaks mid-batch (an op followed by a `setValue` reconciles only the
+  remaining hop); consecutive log records compose when the ring fills, so
+  arbitrarily long op batches stay fully replayable. Exact replay applies to
+  forms created by `createForm`/`useForm` — schema-less custom
+  `FieldArrayFormApi` implementations reconcile by value (2026-07
+  self-review #3, completed by the deferred store-side follow-up).
+- `flattenIssues` no longer crashes on an issue path of `"__proto__"`
+  (reachable via `ctx.addIssue` in a `superRefine`): the accumulator read now
+  checks own keys instead of walking the prototype chain (2026-07
+  self-review #4).
+- `SelectField` renders its empty option whenever the bound `<select>`
+  displays `""` (the condition now derives from `selectProps`' own value
+  coercion, covering `undefined`, `null`, AND `""`) — an empty-string value
+  no longer displays as the first real option while the form holds `""`.
+  An options list that supplies its own `""`-valued entry wins: the
+  implicit blank option is suppressed so the explicit labelled one shows.
+- `setError`/server errors keyed at `"__proto__"` are no longer silently
+  dropped from the merged `errors` map (`mergeErrorChannels` now checks own
+  keys, the same hardening `flattenIssues` got).
+
+### Performance
+
+- Async-requiring scopes are latched: once a sync `validate` /
+  `validateField` / `validateFields` pass discovers a scope needs async
+  parsing, later calls skip the doomed sync parse and go straight to the
+  async pass (previously every keystroke on an async schema paid a full sync
+  parse that always threw) (2026-07 self-review #5). One nuance: after the
+  latch, a value that fails an EARLIER sync check in the same scope also
+  returns `pending` (settling via the promise) where it previously settled
+  `invalid` synchronously — callers on async schemas must handle `pending`
+  regardless, since valid values always produced it. Paths that address no
+  slot (out-of-range indices) never consult the latch and still settle
+  synchronously.
+
+### Internals
+
+- The five bound field components share one `FieldShell` (label + control +
+  error line, with the checkbox's label-wrapping layout as a variant) and one
+  exported `hasFieldError` predicate — the a11y wiring (`useId`, `-error` id,
+  `aria-describedby`) now lives in a single place instead of five copies.
+  `hasFieldError` is exported for custom UI-kit adapters.
+- `FieldPathArg` is now actually used by the `useField` / `useFieldArray`
+  overloads it describes (it was exported dead).
+
+## formstand-cli 0.8.0 — 2026-07-28
+
+### Changed
+
+- **The typed-path budget follows the library default, now 9 segments**
+  (`FORMSTAND_PATH_DEPTH` 7 → 9, tracking `FieldPath<T, D = 9>` in
+  src/core/fieldPath.ts). Bindings whose full path is 8 or 9 segments —
+  degraded to TODOs by the budget fix below — bind real controls again;
+  10+-segment paths keep the TODO + stderr warning. In-budget output is
+  byte-identical (the three-level nested-array snapshot is unchanged). The
+  library's new per-form `pathDepth` option can widen a form past 9; a
+  future `--path-depth` flag would pair with it (not implemented — bind
+  those paths by hand for now).
+- **The default walker nesting budget is now DERIVED from the path budget**
+  (`DEFAULT_MAX_DEPTH = FORMSTAND_PATH_DEPTH + 2` = 11, up from the
+  standalone 10; the constant moved to a shared `depth` module both walkers
+  and emitters import). The walker must reach one level PAST the path
+  budget so a leaf of up to 10 segments (path budget + 1) at default flags
+  degrades via the PATH budget — a real, correctly typed subtree with a
+  depth TODO — rather than via walker truncation, whose wrong-kind string
+  fallback poisoned `initialValues` and failed the consumer's typecheck (a
+  nullable number at level 10 blanked to `""` instead of `null`). Leaves
+  DEEPER than that (11+ segments at default flags) still truncate to the
+  string-kind stand-in; the generated file now always compiles anyway (the
+  truncated leaf forces the `as unknown as` initialValues cast) and each
+  truncated path gets its own stderr warning — see Fixed below. The
+  DeepBoundaryForm playground demo no longer needs its `--max-depth 11`
+  override, and its regenerated output is byte-identical. `--max-depth`
+  remains as an override and the recursion backstop.
+- **One boundary predicate for every depth decision.** The ~38 hand-written
+  `>`/`>=` comparisons against `FORMSTAND_PATH_DEPTH` across the
+  single-file and module emitters are replaced by a single exported
+  `overDepthBudget(spec, segments)` — spec-aware (it picks the
+  at-the-budget vs needs-headroom boundary from the spec's kind) and used
+  at every depth decision in both layouts and the CLI warnings, so they
+  can no longer drift on where degradation starts. (A second predicate for
+  spec-less row paths, `pastRowBudget`, briefly existed but had no call
+  sites and disagreed with `overDepthBudget`'s boundary — it has been
+  deleted.) `depthTodoLine` is likewise the one production of the TODO
+  comment shared by both emitters.
+
+### Fixed
+
+- **Emitted bindings now respect formstand's typed `FieldPath` budget**
+  (7 segments when this fix landed; now 9 — see Changed above) (found by
+  dogfooding: the DeepBoundaryForm playground demo). The
+  walkers happily emitted 9-segment paths (`l1.l2....l8.leaf`) that fail
+  typecheck in every consumer (TS2820, `FieldPath<T, D = 7>` in
+  `src/core/fieldPath.ts`). The emitters now count segments of the FULL bound
+  path — dots split, a template hole (`${index}`, `${p0}`) one segment each,
+  so an array level spends TWO — and a binding that would exceed the budget
+  degrades exactly like other unsupported shapes: compiling output with a
+  `{/* TODO: path ... exceeds formstand's typed FieldPath depth (7); bind by
+  hand */}` comment plus a stderr warning per degraded path. Container
+  recursion stops at the boundary (an object whose own path is at 7 segments
+  can only produce over-budget children), the subtree is still materialized
+  in the zod schema and `initialValues`, and paths exactly AT the limit —
+  including 7-segment nested-array templates like
+  `` `teams.${p0}.members.${p1}.phones.${index}` `` — keep binding
+  byte-identically to before. Covers both layouts, all three UIs, and
+  recursive nested-array row extraction; this is deliberately NOT a walker
+  depth clamp (walk-depth is the wrong proxy for segments — a coarse cap
+  would have broken the working 3-level nested-array output).
+  Follow-up alignment: an at-budget array whose ITEM is non-scalar (an
+  array-of-arrays, or array rows holding a tuple/union) now emits the DEPTH
+  todo at the row site instead of the generic extract-a-row advice — which
+  was unachievable there, since the row path itself is past the budget —
+  and `overBudgetFieldPaths` (the stderr warning list) mirrors the emitted
+  TODOs exactly, one entry per TODO site, per-FIELD for an array's object
+  rows (the emitters degrade those field by field). The mirror is
+  LAYOUT-AWARE (see Fixed below): the walk takes the emitting layout's
+  degradation frontier, since the two layouts stop descending at different
+  places.
+- **`.default()` / `.prefault()` values now land in the generated
+  `initialValues`** instead of being ignored (`defaultedNumber: z.number()
+  .default(42)` emitted `undefined`, contradicting the README). `fromZod`
+  captures the value off the zod def into a new optional `defaultValue` on
+  the IR's `SharedSpecProps`, and `emitInitialValues` seeds the field with
+  it whenever it is a JSON-serializable primitive matching the field kind
+  (string / finite number / boolean / declared enum option). Dates and
+  object/array defaults keep the blank behavior. A seeded default satisfies
+  `z.input`, so it also counts toward the
+  checked-annotation-instead-of-cast decision. Type mode is unchanged — TS
+  types can't carry runtime defaults, so `fromType` never sets
+  `defaultValue`. The README now states the real rule.
+  Capture hardening on review: zod v4's `def.defaultValue` is a GETTER that
+  already resolves the user's factory, so the walk only READS it — a
+  function-valued result (an older shape storing the factory itself, or a
+  factory returning a function) is treated as not capturable rather than
+  invoked, which previously executed arbitrary user code at generation
+  time (a fixture spy proves the resolved function is never called). The
+  getter is read TWICE and the value captured only when both reads
+  `Object.is`-agree on a JSON primitive, so a non-deterministic factory
+  (`Date.now`, `randomUUID`) can never bake a run-dependent literal into
+  byte-deterministic output. And a default is NEVER seeded into a
+  todo-fallback spec (`z.custom<T>().default(...)` walks as a string
+  stand-in whose kind lies about `T`): seeding there broke the generated
+  file's checked `initialValues` annotation — the field keeps its blank
+  behavior instead.
+- **Walker truncation can no longer ship a non-compiling file, and is never
+  silent.** A leaf past the walker nesting budget (11+ segments at default
+  flags) degrades to a string-kind stand-in BEFORE its wrappers unwrap, so
+  its kind and flags can be wrong (`z.number().nullable()` at 11 segments
+  blanked to `""` in a `number | null` slot) — and the checked
+  `initialValues` annotation shipped that as a compile error in the
+  consumer's tsc. `blankNeedsCast` now treats a REQUIRED todo-bearing leaf
+  (truncated specs are always required-flagged; a required `z.custom`
+  fallback hits the same rule) as not input-satisfying, forcing the
+  `as unknown as` cast so the generated file always compiles — in both
+  layouts, which share the one predicate. Optional/nullable fallbacks keep
+  the checked annotation (their `undefined`/`null` blanks genuinely satisfy
+  `z.input` — those flags only exist when real wrappers unwrapped). And the
+  truncation is mirrored on stderr: the walkers stamp a recognizable marker
+  todo (`NESTING_LIMIT_TODO`), `truncatedFieldPaths` collects the truncated
+  paths, and the CLI prints
+  `warning: path "…" exceeds the walker nesting budget (11); field degraded
+  to a placeholder — raise --max-depth or bind by hand` per path.
+- **Depth warnings no longer promise TODOs the chosen layout never emits.**
+  `overBudgetFieldPaths` walked one fixed shape while the two layouts stop
+  descending at different frontiers: the single-file layout does not descend
+  into array-of-array items (generic extract-a-row TODO, no depth TODO
+  inside), and the module layout does not recurse into OBJECT fields of an
+  array row (generic bind-by-hand TODO) — so for those shapes the stderr
+  warnings claimed depth TODOs that weren't in the file (always
+  over-promising, never under-reporting). The walk now takes the emitting
+  layout's `DepthWarningFrontier` (`depthWarningFrontier("single" |
+  "module")`; the single-file frontier is the default, preserving existing
+  programmatic behavior), and `warnDegradedBindings` passes the CLI's
+  `--layout`. Tests pin warnings-per-TODO equality for both divergent
+  shapes in both layouts.
+- **Refused `.default()` captures now warn instead of degrading silently.**
+  Every mode that leaves a declared default unseeded is mirrored on stderr:
+  the capture guard's refusals (function-valued resolved default,
+  non-deterministic two-read disagreement, throwing getter) are recorded on
+  the IR as `droppedDefault`, and emit-time refusals (todo-fallback specs,
+  kind-mismatched or non-finite values, undeclared enum options, dates,
+  container defaults) are detected off the captured `defaultValue` — the
+  CLI prints `warning: field "…" has a .default() the CLI could not capture
+  (non-primitive, non-deterministic, or degraded field); it starts blank —
+  seed it by hand`, one per field. Fields with no default never warn.
+
+## formstand-cli 0.7.0 — 2026-07-12
+
+### Added
+
+- **Tuple support** (`z.tuple([...])` and `[A, B]` in type mode). Tuples were
+  degrading to a single string field with a TODO; they now generate fixed
+  positional controls, each bound at a static numeric-index path (`coord.0`,
+  `coord.1`), in both the single-file and module layouts and all three UIs.
+  Scalar elements render a real control; a non-scalar element (object / array /
+  union / nested tuple) or a variadic rest degrades to a TODO at just that
+  position, so the fixed scalar positions still generate. Generated output is
+  typechecked against the real library across all backends.
+- **Recursive nested-array extraction in both layouts.** An array nested
+  inside an array row used to generate one level (module) or a TODO
+  (single-file). It now recurses to arbitrary depth (bounded by `--max-depth`)
+  in **both** layouts: `teams[] › members[] › phones[]` generates a full
+  component tree, threading each enclosing row's index down as a `p0`, `p1`, …
+  prop. In `--layout module` each level is a `Row`/`Rows` pair; in single-file
+  each is a child `{Stem}Rows` component with a typed `form` prop, emitted
+  above the main component. Array-of-arrays sections extract an inner row
+  component too (module). A non-array shape inside a row (nested object /
+  union / tuple) still degrades to a TODO. Every generated tree is typechecked
+  against the real library across all three UIs.
+- `--max-depth <n>` flag (and a `maxDepth` argument on `fromZod` / `fromType`)
+  for the schema/type nesting budget — the number of levels the walkers
+  descend before a level degrades to a string + TODO. The default rose from 6
+  to **10**, so deeper schemas generate fully. Recursion is still caught
+  directly by a seen-set (a self-referential schema → TODO), with the depth
+  budget as the backstop for getter-minted schemas; the IR is always finite.
+
+### Fixed
+
+- An array whose item is itself non-scalar (an array-of-arrays, or an array of
+  tuples/unions) no longer emits an empty `{/* unreachable */}` row in the
+  single-file layout — it now emits a clear TODO to extract a row component,
+  matching the documented nested-array behavior.
+
+### Docs & examples (no package changes)
+
+- Corrected the CLI README / code-generation guide, which claimed several
+  already-resolved limitations: `date` fields have emitted real `DateField` /
+  date-input bindings since 0.9 (not a text-input TODO), and the module layout
+  extracts one real nested-array row level (not a blanket TODO).
+- Schema builder: **paste a zod schema**. An **Import code…** modal takes a
+  TypeScript type _or_ a `z.object(...)` schema — by paste or by picking a
+  `.ts` file — and generates the form from it. The zod source is evaluated in
+  the browser against the bundled zod (the REPL trust model: your own code, in
+  your own tab, nothing fetched or sent) and walked by the real `fromZod`, so
+  it shares the paste-a-type mode's exact IR → emitters path. Switching the
+  dialect swaps in a worked sample while the field is untouched.
+
+## formstand-cli 0.6.2 — 2026-07-10
+
+### Added
+
+- Browser-safe programmatic API via the new `formstand-cli/codegen` subpath.
+  Everything downstream of the IR — `fromZod`, every emitter
+  (`emitPlainForm` / `emitMuiForm` / `emitShadcnForm` / `emitTemplateForm` /
+  `emitModuleForm`, `emitZodSchema` / `emitInitialValues`), `joinModuleFiles`,
+  `defineTemplate`, `labelFromName` and the casing helpers — is a pure string
+  builder with no `fs`/`path` and no TypeScript compiler, so it bundles for the
+  browser (the docs Schema-builder generates forms client-side through it). The
+  main `formstand-cli` entry still re-exports all of it and adds the
+  Node-oriented `fromType` / `defineConfig`.
+
+## formstand-cli 0.6.1 — 2026-07-10
+
+### Added
+
+- Custom templates (`--template <file>` or `template:` in the config): a
+  `defineTemplate({ name, imports, leaf })` module overrides the per-kind
+  field rendering for a UI kit formstand doesn't ship (Mantine, Chakra,
+  in-house), inheriting the generated form's scaffold — sections, arrays,
+  discriminated unions, submit. Each leaf renderer gets a context of
+  JS-expression strings (`bind`, `field`, `label`, `options`), and the same
+  renderer works both in the generated wrapper component and inside union
+  variant blocks. Unlisted kinds fall back to plain. `--layout single`
+  only for now; overrides `--ui`.
+
 
 ## 0.9.0 — 2026-07-10
 

package/README.md

@@ -85,10 +85,10 @@ const form = createForm(schema, {
 | `setError(path, errors)` / `setErrors(map)` / `clearErrors(path?)` | the app-owned **server error channel** (`state.serverErrors`) — validation never touches it; `setError` accepts a single string or an array; `clearErrors(path)` clears both channels at the path and its descendants (`clearErrors("")` clears just the root entry; `clearErrors()` clears everything); `setErrors` replaces the whole server channel |
 | `setMode` / `setReValidateMode` | switch modes at runtime |
 | `reset(nextInitial?, options?)` | reset to initial; optional partial overrides (shallow-merged for record roots, replaced wholesale otherwise) and `{ keepErrors, keepTouched, keepSubmitCount }` (no `keepDirty` — dirtiness derives from values vs initial, and reset makes them equal) |
-| `resetField(path)` | reset one field to its initial value, clearing its (and descendants') error/touched state (dirtiness clears by definition — the value now equals initial) |
+| `resetField(path)` | reset one field to its initial value, clearing its (and descendants') error/touched state (dirtiness clears by definition — the value now equals initial); a path with no initial counterpart (an appended array row) keeps its value and only clears field state |
 | `adoptValues(values)` | mid-session rebase: replaces `values` + `initialValues` and clears `errors` and in-flight validation flags (`isValidating`/`isValidatingForm` — the rebase disowns in-flight passes), but **preserves** interaction state (`touched`, `submitCount`, `isSubmitting`, `mode`). Use `reset()` for a full wipe |
 | `updateState(updater)` | atomic multi-field patch; `errors` is derived from `schemaErrors`/`serverErrors`, so patch the channels — the patch type omits `errors` entirely, and a plain-JS `errors` patch is warned about and ignored |
-| `validate()` / `validateField(path)` / `validateFields(paths)` | sync validation; on an async schema they transparently start the async pass instead (`validate`/`validateField` return `{ kind: "pending", promise }`, `validateFields` returns the `Promise<boolean>` itself) |
+| `validate()` / `validateField(path)` / `validateFields(paths)` | sync validation; on an async schema all three transparently start the async pass instead and return `{ kind: "pending", promise }` |
 | `validateAsync()` / `validateFieldAsync(path)` / `validateFieldsAsync(paths)` | async; supports `async .refine` |
 | `submit(onValid, onInvalid?, { force? })` → `Promise<SubmitResult>` | full submit flow; resolves `{ kind: "valid", data }`, `{ kind: "invalid", errors }` (errored fields are also marked touched), `{ kind: "skipped" }` when another submit is in flight, or `{ kind: "error", error }` when `onValid` throws/rejects — submit resolves instead of rejecting, so `handleSubmit` never produces an unhandled rejection from an `onValid` throw |
 | `handleSubmit(onValid, onInvalid?)(event?)` | event handler wrapper that calls `preventDefault` |
@@ -108,7 +108,7 @@ const form = createForm(schema, {
 - `mode: "all"`: validate on every change and blur.
 - `reValidateMode` (default `"onChange"`) kicks in once `submitCount > 0`.
 
-For schemas with `async .refine`, sync `validate()` / `validateField()` / `validateFields()` no longer throw: they detect the async requirement, start the async pass themselves, and hand you the in-flight work (`{ kind: "pending", promise }` from `validate`/`validateField`; the `Promise<boolean>` itself from `validateFields`). If the *field being validated* is itself sync, `validateField` still settles synchronously even when other fields carry async refines — field validation parses just that field's subschema when it can (see below).
+For schemas with `async .refine`, sync `validate()` / `validateField()` / `validateFields()` don't throw: they detect the async requirement, start the async pass themselves, and hand you the in-flight work as `{ kind: "pending", promise }` (never a bare truthy `Promise` — a boolean gate can't silently pass). The requirement is also remembered per scope, so later sync calls skip straight to the async pass instead of re-paying a doomed sync parse per keystroke. If the *field being validated* is itself sync, `validateField` still settles synchronously even when other fields carry async refines — field validation parses just that field's subschema when it can (see below).
 
 ## React hooks
 
@@ -165,12 +165,13 @@ users.insert(i, item);
 users.error;   // array-level error (e.g. min(1))
 ```
 
-`fields` IDs are reconciled against item identity each render, so a row's `id`
-stays glued to its item across reorders, inserts, and removes — including
-mutations made outside this hook (`form.arrayMove`, `setValue`, `restore`, or a
-second `useFieldArray` on the same path). Editing a field keeps its row's `id`
-(the row updates instead of remounting); a genuinely new item gets a fresh `id`.
-IDs reset when the hook's `path` changes.
+`fields` IDs are shared per `(form, path)` — every hook on the same array sees
+the same ids. Array ops (hook-issued or imperative `form.arrayMove` etc.)
+record their exact index mapping and id derivation replays it, so even rows
+with equal values keep the right ids through ops; whole-array writes
+(`setValue`, `restore`) reconcile by item identity with a positional fallback,
+so editing a field keeps its row's `id` (the row updates instead of
+remounting). A genuinely new item gets a fresh `id`.
 
 ### `useFormSelector(form, selector)` / `useFormSelectorShallow(form, selector)`
 
@@ -347,9 +348,12 @@ decided by the **existing container**: arrays take numeric segments as indices,
 plain objects take any segment as a string key — so a `z.record` keyed `"0"`
 reads and writes the record key instead of silently becoming an array. Only
 when the container doesn't exist yet does the segment type pick what's created
-(numeric → array, otherwise object). Two limitations: keys containing `.` are
-not addressable, and array writes beyond index 100 000 are refused (a typo'd
-index must not allocate gigabytes).
+(numeric → array, otherwise object). Three limitations: keys containing `.`
+are not addressable; array writes beyond index 100 000 are refused (a typo'd
+index must not allocate gigabytes); and the typed `FieldPath` union stops at
+9 segments by default — the runtime walks any depth, and `createForm`'s
+type-level `pathDepth` option widens the union per form (a deliberate
+compile-time trade; see the [typed paths guide](https://scrumrot.github.io/formstand/guide/typed-paths)).
 
 ## Subscriptions (non-React)
 
@@ -408,7 +412,7 @@ Note `submit` still proceeds when the schema is valid even if server errors are
 
 ## Field arrays with nested arrays
 
-Both work — `arrayPush("users.0.tags", tag)` mutates the inner array; outer reorders correctly re-key meta for all nested paths. `useFieldArray`'s stable IDs reset when the hook's path changes (so an inner field array inside a reordered outer item gets fresh IDs).
+Both work — `arrayPush("users.0.tags", tag)` mutates the inner array; outer reorders correctly re-key meta for all nested paths. Inner row ids live per `(form, path)` and reconcile by value when the outer index re-seats a different item at the path — pass a `key` from the outer `fields` so each row's whole subtree moves with its item.
 
 ## Optimistic UI