formstand 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,6 +1,627 @@
 # Changelog
 
-## Unreleased
+## 0.11.0 — 2026-07-29
+
+### Added
+
+- **`useNumberInput` is exported** (along with its `NumberInputBinding`
+  return type) — the text-preserving number binding behind `NumberField`.
+  It was implemented and tested (via `NumberField`) all along, just never
+  exported: local raw text while editing (partial entries like `-`, `1.`,
+  `85000.` stay visible), keystrokes that parse pushed to the form via the
+  shared `parseNumberText` rules, blur snapping the display to the
+  canonical value, and an external form-value change while editing
+  resetting the local text. Spread it onto an `<input type="text">` for
+  custom number inputs and UI-kit adapters — a naive controlled
+  `value={String(n)}` binding eats the `.` of `85000.50` and the `-` of
+  `-5` as they are typed.
+
+### Fixed
+
+- **`focusFirstError` / `focusField` gain an `[id=path]` fallback** for
+  paths that match NO named control: composite widgets that render no
+  `name` anywhere — Ant Design's `Select`, notably, which has no
+  form-posting input — were unreachable by the name walk even though they
+  forward `id={path}` to their real focusable control. When a path has no
+  name-matched control, the helpers now try the element whose `id` is
+  exactly that path (EXACT match only — descendant semantics stay with the
+  name walk, since an id names one element), with the same focusability
+  filter, post-focus verification, and DOM-order merging as name matches.
+  Paths with any named control never consult ids, so existing behavior is
+  unchanged wherever a `name` exists.
+
+## 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.9.0 — 2026-07-29
+
+### Added
+
+- **Version-aware `--ui`: `mui@5` … `mui@9`** — `--ui mui` can now pin an
+  `@mui/material` major: `mui@5`, `mui@6`, `mui@7`, `mui@9` (bare `mui`
+  keeps meaning the latest supported major, 9, and its output is
+  byte-identical to before). The config file's `ui` key accepts the same
+  spellings. Scope: only React-19-capable majors — formstand peers
+  `react: ^19`, so MUI 4 and older can never install alongside it — and MUI
+  skipped major 8 entirely (7.x jumps to 9 on the registry), so `mui@8`
+  and `mui@4` fail with explanations, as do `plain@N`/`shadcn@N` (those
+  kits take no version). Internally the flag/config value parses to a
+  structured `UiTarget` (`{ kit: "mui", version }` | `{ kit: "plain" }` |
+  `{ kit: "shadcn" }`, exported with `parseUiTarget` / `MUI_VERSIONS` from
+  `formstand-cli/codegen`), and ONE mui emitter serves every major through
+  a small per-version config. The only prop-surface delta across the
+  emitted component set (verified empirically against each major's .d.ts)
+  is TextField's slot-props API: `mui@5` emits the legacy
+  `InputProps: { inputMode }` / `InputLabelProps: { shrink: true }`, v6+
+  emit `slotProps.{input,inputLabel}` (v9 removed the legacy spelling;
+  v6–7 accept both and get the modern one). Custom `--template` modules
+  compose with a versioned `--ui` exactly as they did with bare `mui`
+  (a template still overrides the ui entirely, `--layout single` only).
+- **`cli/matrix/`: the UI-kit version-matrix typecheck harness** — an isolated
+  workspace (own `package.json` + lockfile; not part of the root or cli
+  installs) with every supported `@mui/material` major installed side by
+  side under npm aliases (`mui5` … `mui9`). `npm run matrix` (from `cli/`)
+  generates a kitchen-sink form plus the nested-array stress form with
+  `--ui mui@N` — both layouts, every section/column variant — and
+  typechecks the output against each major's real type declarations
+  (`@mui/material` path-mapped onto the alias, `formstand` onto the
+  library source). A per-version literal-attribute probe restates the
+  adapter's TextField props style outside a JSX spread (spreads bypass
+  TypeScript's excess-property checks), so a wrong per-version config
+  fails the matrix instead of compiling silently. Run it before releasing
+  any UI-kit backend change; it is deliberately not part of `npm test`.
+  (The chakra, mantine, and antd entries below each extend the harness
+  with their kit's alias and job — it ends this cycle proving seven
+  targets: four mui majors, chakra 3, mantine 9, antd 6.)
+- **First-class `--ui chakra`: a Chakra UI v3 backend** — both layouts
+  (single-file and `--layout module`), the full field-kind surface the mui
+  backend covers (strings/numbers/dates/enums/booleans, nested objects,
+  arrays with add/remove and recursive nested-row extraction, tuples,
+  discriminated unions, TODO degradations), and every `--sections` /
+  `--columns` variant. Emits the v3 compound-component API (verified
+  against the installed 3.36 declarations, not v2's): `Field.Root` (with
+  `invalid`) / `Field.Label` / `Field.ErrorText` for labels and errors,
+  `Input` for text/number/date (native bindings — `inputMode="decimal"`,
+  `type="date"`), `NativeSelect.Root` + `NativeSelect.Field` for enums (a
+  real `<select>`, preferred over the Ark collection `Select` so the
+  adapter speaks DOM change events), and `Switch.Root` /
+  `Switch.HiddenInput` / `Switch.Control` / `Switch.Thumb` /
+  `Switch.Label` for booleans (`checked` + `onCheckedChange` details
+  callback, spread on the root where the state lives). Sections render
+  `Stack`/`Heading` (flat), `Card.Root`/`Card.Body` (panel), or one
+  `Accordion.Root` (`collapsible defaultValue={["section"]}`) per section
+  (collapsible); columns use the same CSS-grid shape as the other kits via
+  chakra style props. The generated file assumes the host app mounts
+  `ChakraProvider` (same policy as the mui backend and its theme). The
+  module layout gains a shared `adapter.ts` (`chakraTextInputProps` /
+  `useChakraNumberInputProps` / `chakraDateInputProps` /
+  `chakraSelectProps` / `chakraSwitchProps` + `fieldError`). chakra takes no version suffix —
+  v3 is the only supported major (v2 and older lack the compound API and
+  predate formstand's React 19 peer) — with `chakra@3` accepted as the
+  explicit spelling and `chakra@1`/`chakra@2` failing with the scope
+  rationale like `mui@0`–`mui@4`. The config file's `ui` key accepts the
+  same spellings, and the matrix harness gained a `chakra3` alias
+  (`npm:@chakra-ui/react@^3`) plus a chakra job — both schemas, both
+  layouts, all section styles, and a literal-attribute probe for the
+  Input/NativeSelect/Switch prop surfaces — so `npm run matrix` now proves
+  five kit targets against their real .d.ts.
+- **First-class `--ui mantine`: a Mantine v9 backend** — both layouts, the
+  full field-kind surface the other kit backends cover (strings/numbers/
+  dates/enums/booleans, nested objects, arrays with add/remove and
+  recursive nested-row extraction, tuples, discriminated unions, TODO
+  degradations), and every `--sections` / `--columns` variant. Mantine
+  field components carry their own `label` + `error` props, so there is no
+  Field wrapper: `TextInput` binds text/number/date natively
+  (`inputMode="decimal"`, `type="date"`; Mantine's `NumberInput` widget is
+  deliberately NOT used — its `onChange` takes `(value: number | string)`,
+  not a DOM event, so it can't share formstand's input-shaped adapters),
+  `NativeSelect` binds enums as a real `<select>` with `<option>` children
+  (same native-first choice as the chakra backend), and `Switch` binds
+  booleans through plain DOM `checked`/`onChange` (a `ChangeEvent`, unlike
+  chakra's details callback). Error text rides inside the adapter builders
+  (`error: fieldError(field)`), so leaves are one-liners like the mui
+  backend's. Sections render `Stack`/`Title` (flat), `Card withBorder` +
+  `SimpleGrid` (panel), or `Accordion`/`Accordion.Item`/`Control`/`Panel`
+  (collapsible, `defaultValue="section"` + `variant="contained"`); columns
+  use `SimpleGrid cols={N}`. The generated file assumes the host app
+  mounts `MantineProvider` (same policy as the mui/chakra providers). The
+  module layout gains a shared `adapter.ts` (`mantineTextInputProps` /
+  `useMantineNumberInputProps` / `mantineDateInputProps` /
+  `mantineSelectProps` / `mantineSwitchProps` + `fieldError`). mantine
+  takes no version suffix — v9 (the current major) is the only supported
+  target, with `mantine@9` accepted as the explicit spelling. The scope is
+  empirical: 9.x peers `react ^19.2` while 7.17+/8.x peer `^18 || ^19`
+  (7.0 was ^18-only, ≤6 predate the v7 emotion→CSS-modules rewrite), and
+  the emitted component surface typechecks IDENTICALLY against 7.17/8.3/9.5
+  except the `bdrs` style prop (absent in 7) — so `mantine@0`–`6` fail
+  with the React-19/styling-rewrite rationale and `mantine@7`/`@8` fail
+  with a precise verified-against-v9-only message instead of a false
+  incompatibility claim. The config file's `ui` key accepts the same
+  spellings, and the matrix harness gained a `mantine9` alias
+  (`npm:@mantine/core@^9.5`, plus its `@mantine/hooks` peer) and a
+  mantine job — both schemas, both layouts, all section styles, and a
+  literal-attribute probe for the TextInput/NativeSelect/Switch spread
+  surfaces — so `npm run matrix` now proves six kit targets against their
+  real .d.ts.
+- **First-class `--ui antd`: an Ant Design v6 backend** — both layouts, the
+  full field-kind surface the other kit backends cover (strings/numbers/
+  dates/enums/booleans, nested objects, arrays with add/remove and
+  recursive nested-row extraction, tuples, discriminated unions, TODO
+  degradations), and every `--sections` / `--columns` variant. The one
+  hard rule: antd's own `Form`/`Form.Item` (name-based bindings, its own
+  state store) is NEVER emitted — formstand owns the form state, so the
+  generated code binds antd's input components as plain controlled
+  components. The bindings, decided empirically against the installed
+  6.5 declarations: `Input` binds text/number/date natively (it extends
+  the DOM input props — `inputMode="decimal"`, `type="date"`; antd's
+  `InputNumber` is rejected on evidence, its `onChange` is
+  `(value: number | null)`, not an event, and the dayjs-value-based
+  `DatePicker` is not used — the CLI pulls no date library); enums bind
+  antd's `Select`, the backend's ONE value-shaped adapter — antd has no
+  native-`<select>` component anywhere, so `onChange` receives the
+  selected value directly, `value ?? null` keeps the placeholder visible,
+  and there is no `name` (antd's Select renders no form-posting input);
+  booleans bind `Checkbox` (its `onChange` is antd's DOM-ish
+  `CheckboxChangeEvent` with `e.target.checked`, and it has a real
+  `onBlur`) — NOT `Switch`, which has no `onBlur` prop at all and a
+  value-shaped `(checked, event)` callback (both rejections verified as
+  failing compiles against the real .d.ts). With no `Form.Item` there is
+  no built-in error slot: every non-boolean control paints
+  `status="error"` (`fieldStatus`) and renders an explicit
+  `Typography.Text type="danger" role="alert"` error line, with a plain
+  `<label htmlFor>`/`id` pair. Sections render `Flex`/`Typography.Title`
+  (flat), `Card variant="outlined"` (panel), or `Collapse` via the items
+  API (collapsible — children-panels are deprecated in antd 5+); columns
+  use the shared inline-style CSS grid. No provider is required
+  (`ConfigProvider` is optional theming). The module layout gains a shared
+  `adapter.tsx` (JSX for its `FieldError` line, like shadcn's):
+  `antdTextInputProps` / `useAntdNumberInputProps` /
+  `antdDateInputProps` / `antdSelectProps` / `antdCheckboxProps` +
+  `fieldError` / `fieldStatus` / `FieldError`. antd takes no version suffix — v6 (the current major) is
+  the only supported target, with `antd@6` accepted as the explicit
+  spelling. The scope is empirical: antd 6.x peers `react >=18` (React 19
+  natively in range), while antd 5 nominally peers `react >=16.9` but
+  needs the `@ant-design/v5-patch-for-react-19` import in the HOST app on
+  React 19 — so `antd@5` fails with a precise
+  verified-against-v6-only message (naming the patch, no false
+  incompatibility claim) and `antd@0`–`4` fail with the missing-surface
+  rationale (no `Flex`, no Collapse items API, no `status` props; 4 and
+  older predate the v5 CSS-in-JS rewrite). The config file's `ui` key
+  accepts the same spellings, and the matrix harness gained an `antd6`
+  alias (`npm:antd@^6.5`) and an antd job — both schemas, both layouts,
+  all section styles, and a literal-attribute probe for the
+  Input/Select/Checkbox spread surfaces, restating the value-shaped
+  Select `onChange` with its explicit parameter type — so
+  `npm run matrix` now proves seven kit targets against their real .d.ts.
+- **Playground: the new kit backends as living demos** — three new
+  Generated tabs (**Gen: Chakra UI**, **Gen: Mantine**, **Gen: Ant
+  Design**) render the SAME Onboarding schema the mui module tab uses,
+  generated single-file with `--ui chakra` / `--ui mantine` / `--ui antd`
+  and the same `--sections panel --columns 2` chrome — a direct kit
+  comparison across the four tabs, with one deliberate second axis: the
+  mui tab is `--layout module` (the module-layout showcase) while these
+  three are single-file. Committed
+  untouched and drift-checked by CI like the other generated demos
+  (`scripts/generate-cli-demos.mjs`), rendered behind scoped provider
+  bridges that follow the playground's light/dark switch (ChakraProvider +
+  a mode class, MantineProvider `forceColorScheme`, antd `ConfigProvider`
+  algorithm — antd needs no provider to function), and smoke-tested in
+  the root suite (mount, label association, array add/remove per kit).
+
+### Fixed
+
+- **Kit number adapters no longer corrupt typed numbers.** The mui, chakra,
+  mantine, and antd backends bound numbers as a controlled text input
+  (`inputMode="decimal"`) whose onChange immediately reparsed and
+  re-rendered the canonical string — so typing `85000.50` yielded
+  `8500050` (the `.` eaten as `85000.` reparsed to `85000`), `-5` yielded
+  `5`, and `0.050` yielded `50` (jsdom-verified). All four now emit an
+  inline `useNumberText` hook replicating formstand's own `useNumberInput`
+  semantics exactly (local raw text while editing, valid keystrokes pushed,
+  partial entries kept, blur snap, external-change reset) — emitted inline
+  rather than imported so generated output keeps its formstand >= 0.3.0
+  floor — and their number adapters became use-prefixed HOOKS
+  (`useMuiNumberFieldProps` / `useChakraNumberInputProps` /
+  `useMantineNumberInputProps` / `useAntdNumberInputProps`) composing kit
+  chrome over it, in both layouts. Union variant blocks are conditional
+  JSX, so number bindings there hoist
+  `const ${var}NumberProps = use...(${var})` next to the field hooks and
+  spread the const (React's rules of hooks). plain and shadcn were never
+  affected (stateless `type="number"` bindings).
+- **Single-file array sections render the array-level error.** All six
+  single-file backends dropped `useFieldArray`'s `.error`, so a
+  `z.array().min(1, "add at least one contact")` message was invisible on
+  submit; the module layout already rendered it per kit. Each backend now
+  emits the same error line its module-layout list shell uses (plain and
+  shadcn `<p role="alert">`, mui `Typography color="error"`, chakra
+  `Text color="red.500"`, mantine `Text c="red"`, antd
+  `Typography.Text role="alert" type="danger"`), between the rows and the
+  Add button.
+- **Version-matrix hardening.** (1) The stale-install gate now derives its
+  required-alias list from the job list itself and fails loudly naming
+  what's missing — it previously checked only 4 of the 7 aliases, so a
+  missing `mui6`/`mui7`/`mui9` silently typechecked against the repo
+  root's @mui/material copy. (2) Every kit gained a module-layout PANEL
+  job (`KitchenSinkPanel`, panel@2col): module-panel emitters were
+  previously typechecked nowhere (a deliberate typo in that arm shipped
+  green), so the matrix now genuinely covers all three section styles in
+  both layouts. (3) The matrix compiles under `exactOptionalPropertyTypes`
+  in addition to `strict` — the strictest consumer configuration — after
+  fixing the stale antd probe lines, which restated `status={undefined}`,
+  a shape the adapter no longer emits (it emits `""`, a member of antd's
+  `InputStatus`). (4) The four ~60-line per-kit generator copies collapsed
+  into one parameterized `generateKit` with the jobs as data.
+- **Docs corrections**: the module layout works with all six uis (the
+  README said three) and the adapter split is named (`adapter.ts` for
+  mui/chakra/mantine, `adapter.tsx` for shadcn/antd); the
+  formstand >= 0.3.0 requirement explicitly covers mantine and antd (they
+  import the same surface); and the playground/README wording about the
+  four "CLI output" tabs now acknowledges both axes — the mui tab is
+  `--layout module` (doubling as the module-layout showcase) while the
+  three kit tabs are single-file, so `--ui` is not the only variable.
+- **antd `fieldStatus` returns `""` — antd's own no-status value — instead
+  of `undefined`** when a field has no error. Spreading
+  `status: "error" | undefined` onto antd's `status?: InputStatus` props
+  fails to compile in host apps built with `exactOptionalPropertyTypes`
+  (which rejects explicit `undefined` for optional properties); `""` sits
+  in antd's `InputStatus` union precisely for "no status". Caught by
+  wiring the playground demo — the examples package compiles with
+  `exactOptionalPropertyTypes` on.
+
+## 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