npm - @structuralists/scaffolding - Versions diffs - 0.10.0 → 0.10.1 - Mend

@structuralists/scaffolding 0.10.0 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/package.json +1 -1
package/src/forms/CLAUDE.md +41 -20
package/src/forms/useFormState/FormDebugger.tsx +2 -1
package/src/forms/useFormState/deriveErrors.test.ts +76 -0
package/src/forms/useFormState/deriveErrors.ts +35 -0
package/src/forms/useFormState/types.ts +2 -1
package/src/forms/useFormState/useFormDebugger.test.tsx +57 -0
package/src/forms/useFormState/useFormDebugger.ts +38 -0
package/src/forms/useFormState/useFormState.ts +19 -59
package/src/forms/useFormState/useFormSubmit.test.tsx +86 -0
package/src/forms/useFormState/useFormSubmit.ts +38 -0
package/src/forms/validations/walk.ts +3 -2

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "main": "./index.ts",
   "types": "./index.ts",
   "exports": {

package/src/forms/CLAUDE.md CHANGED Viewed

@@ -294,25 +294,45 @@ precision end-to-end. So we wire it up before adding any consumers.
 - `useFormState/` — the hook + the value-model types (`FormValueSimple`,
   `FormValuesObject`, `FormValueList`). Hook surface: `{ values,
-  onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`;
-  `errors` is the structured `FormErrors<T>` list (see "The error model"),
-  live-derived from current values each render (validators are pure and
-  cheap) with `isValid` its emptiness; `errorAt.ts` holds the typed lookup;
-  `submitAttempted` lets UIs gate error display; and `submit()` performs
-  the one honest *refinement* cast to `Refine<T, V>` — earned because the
-  validators just passed at runtime. The hook's error loop carries one
-  further documented widening (`failure.path as Path<T>`, same species as
-  its `Object.keys` cast): `[key]` is a valid single-key `Path<T>`, but TS
-  cannot compute `Path<T>` for an unresolved generic `T` to see the
-  correlation. `Debugger` is a per-instance
-  dev-time overlay (fixed trigger, bottom-right, portaled to `<body>`) that
-  opens a live `JsonTable` view of the form's internal state. Plumbing: the
-  hook publishes a `FormDebugSnapshot` into a tiny `snapshotStore` after
-  every commit; only an *open* debugger window subscribes
-  (`useSyncExternalStore`), so an unused Debugger costs ~nothing. The
-  component is created once per hook instance (lazy ref) — its identity must
-  stay stable across renders or it would remount on every keystroke.
-  `inspectable.ts` converts arrays/Sets to shapes `JsonTable` can render.
+  onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`.
+  `useFormState.ts` itself is deliberately **plumbing only**: it holds the
+  values `useState` (a bare `useState` today; granular path-based setters
+  are what would earn values state a module of its own), links up the
+  modules below, and recomposes their outputs into `FormHelpers<T>`. Each
+  slice lives in its own file so it is independently comprehensible and
+  unit-testable at its own boundary:
+  - `types.ts` — the value model, the union-policy gate
+    (`UnionPolicyCheck` and friends), the `FormError`/`FormErrors` model,
+    `FormDebugSnapshot`, `FormHelpers`.
+  - `deriveErrors.ts` — `deriveFormErrors(values, constraints)`, the pure
+    (React-free) derivation of the structured `FormErrors<T>` list (see
+    "The error model"), re-run every render (validators are pure and
+    cheap); `isValid` is its emptiness, derived inline in the hook. Its
+    loop delegates per-entry semantics to `validations/walk.ts` and
+    carries two documented honest widenings: the `Object.keys` cast, and
+    `failure.path as Path<T>` — `[key]` is a valid single-key `Path<T>`,
+    but TS cannot compute `Path<T>` for an unresolved generic `T` to see
+    the correlation. It also hosts the cast-free `FlatConstraintEntry`
+    assignment that polices grammar growth (see the `validations/` bullet).
+  - `errorAt.ts` — the typed error lookup.
+  - `useFormSubmit.ts` — submit orchestration: owns `submitAttempted`
+    (lets UIs gate error display) and the validity gate in front of
+    `onSubmit`; its `submit()` performs the one honest *refinement* cast
+    to `Refine<T, V>` — earned because the validators just passed at
+    runtime. `V` is not inferable from `onSubmit`'s parameter position,
+    so `useFormState` applies `<T, V>` explicitly.
+  - `useFormDebugger.ts` — debugger plumbing: creates one `snapshotStore`
+    + one Debugger component per hook instance (lazy ref — the component's
+    identity must stay stable across renders or it would remount, and lose
+    its open/closed state, on every keystroke) and publishes the
+    `FormDebugSnapshot` after every commit.
+  - `FormDebugger.tsx` / `snapshotStore.ts` / `inspectable.ts` — the
+    `Debugger` itself: a per-instance dev-time overlay (fixed trigger,
+    bottom-right, portaled to `<body>`) that opens a live `JsonTable` view
+    of the form's internal state. Only an *open* debugger window
+    subscribes (`useSyncExternalStore`), so an unused Debugger costs
+    ~nothing. `inspectable.ts` converts arrays/Sets to shapes `JsonTable`
+    can render.
 - `path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`, `read()`).
   Will be used for granular setters and for surfacing per-field
   errors/touched state. Coupled to the form value model intentionally.
@@ -324,7 +344,8 @@ precision end-to-end. So we wire it up before adding any consumers.
   hook delegates to (`validateEntry`). `Validations<T>` accepts bare
   `(val) => string | null` functions too — they simply narrow nothing.
   The walk's entry type (`FlatConstraintEntry`) is how the compiler polices
-  the hook's error loop: `constraints[key]` is *assigned* to it, never cast,
+  the error loop in `useFormState/deriveErrors.ts`: `constraints[key]` is
+  *assigned* to it, never cast,
   so a grammar form the walk doesn't understand (a nested spec, an `each`)
   is a compile error at the assignment — a cast there would silently accept
   new grammar and misinterpret it at runtime (e.g. call an array as a

package/src/forms/useFormState/FormDebugger.tsx CHANGED Viewed

@@ -16,7 +16,8 @@ export type FormDebuggerProps = {
 export type FormDebuggerComponent = (props: FormDebuggerProps) => ReactElement;
 // Builds the per-hook-instance Debugger component. Called once per
-// `useFormState` instance (from a lazy ref) so the returned component's
+// `useFormState` instance (from `useFormDebugger`'s lazy ref) so the
+// returned component's
 // identity is stable across renders — a component recreated each render
 // would remount, and lose its open/closed state, on every keystroke.
 export const createFormDebugger = <T extends FormValuesObject>(

package/src/forms/useFormState/deriveErrors.test.ts ADDED Viewed

@@ -0,0 +1,76 @@
+import { describe, test, expect } from 'bun:test';
+import { deriveFormErrors } from './deriveErrors';
+import { matches, notEmpty } from '../validators/validators';
+// Direct, React-free tests of the pure derivation: values + constraints in,
+// structured `{ path, error }[]` out. Hook-level behavior (live re-derivation
+// across renders, submit gating) stays in useFormState.test.tsx.
+type SignupForm = {
+  email: string | undefined;
+  nickname: string | undefined;
+};
+const emptyForm: SignupForm = { email: undefined, nickname: undefined };
+describe('deriveFormErrors', () => {
+  test('no constraints yields no errors', () => {
+    expect(deriveFormErrors(emptyForm, undefined)).toEqual([]);
+  });
+  test('an empty constraints object yields no errors', () => {
+    expect(deriveFormErrors(emptyForm, {})).toEqual([]);
+  });
+  test('a failing field contributes one path-addressed entry', () => {
+    const errors = deriveFormErrors(emptyForm, { email: notEmpty('email') });
+    expect(errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+    ]);
+  });
+  test('a passing field contributes nothing', () => {
+    const errors = deriveFormErrors(
+      { email: 'a@b.co', nickname: undefined },
+      { email: notEmpty('email') },
+    );
+    expect(errors).toEqual([]);
+  });
+  test('every failing constrained field gets its own entry', () => {
+    const errors = deriveFormErrors(emptyForm, {
+      email: notEmpty('email'),
+      nickname: notEmpty('nickname'),
+    });
+    expect(errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+      { path: ['nickname'], error: "'nickname' cannot be empty" },
+    ]);
+  });
+  test('a validator array runs in order with first-error-wins', () => {
+    const constraints = {
+      email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+    };
+    expect(deriveFormErrors(emptyForm, constraints)).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+    ]);
+    expect(
+      deriveFormErrors({ email: 'nope', nickname: undefined }, constraints),
+    ).toEqual([{ path: ['email'], error: "'email' must be a valid email" }]);
+    expect(
+      deriveFormErrors({ email: 'a@b.co', nickname: undefined }, constraints),
+    ).toEqual([]);
+  });
+  test('an empty validator array passes', () => {
+    expect(deriveFormErrors(emptyForm, { email: [] })).toEqual([]);
+  });
+  test('a null constraint entry (possible from untyped JS) is skipped', () => {
+    const constraints = { email: null } as unknown as {
+      email: (val: string | undefined) => string | null;
+    };
+    expect(deriveFormErrors(emptyForm, constraints)).toEqual([]);
+  });
+});

package/src/forms/useFormState/deriveErrors.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import type { Path } from '../path/types';
+import type { Validations } from '../validations/types';
+import { validateEntry } from '../validations/walk';
+import type { FlatConstraintEntry } from '../validations/walk';
+import type { FormError, FormValuesObject } from './types';
+// The pure half of the hook's error model: current values + constraints in,
+// structured `{ path, error }[]` out. Validation is live-derived (validators
+// are pure and cheap), so this runs every render — it must stay free of
+// React and of any per-call state. `isValid` is just this list's emptiness;
+// the hook derives it inline.
+export const deriveFormErrors = <T extends FormValuesObject>(
+  values: T,
+  constraints: Validations<T> | undefined,
+): FormError<T>[] => {
+  const errors: FormError<T>[] = [];
+  if (!constraints) return errors;
+  for (const key of Object.keys(constraints) as (keyof T & string)[]) {
+    // No cast: if the grammar grows a constraint form the walk doesn't
+    // understand, this assignment is the compile error that says so.
+    const entry: FlatConstraintEntry | undefined = constraints[key];
+    if (entry == null) continue;
+    const failure = validateEntry(entry, values[key], [key]);
+    if (failure == null) continue;
+    // The walk returns the address it was handed, and `[key]` — a key of
+    // a constraints object type-checked against T — is a valid single-key
+    // Path<T>. TS can't compute Path<T> for an unresolved generic T, so
+    // the correlation needs the same honest widening as the keys cast
+    // above.
+    errors.push({ path: failure.path as Path<T>, error: failure.error });
+  }
+  return errors;
+};

package/src/forms/useFormState/types.ts CHANGED Viewed

@@ -90,7 +90,8 @@ export type FormError<T extends FormValuesObject> = {
 export type FormErrors<T extends FormValuesObject> = readonly FormError<T>[];
-// What the hook publishes to its Debugger after every commit. Snapshots are
+// What the hook publishes (via `useFormDebugger`) to its Debugger after
+// every commit. Snapshots are
 // replaced whole (never mutated) so `useSyncExternalStore` consumers can
 // rely on reference equality.
 export type FormDebugSnapshot<T extends FormValuesObject> = {

package/src/forms/useFormState/useFormDebugger.test.tsx ADDED Viewed

@@ -0,0 +1,57 @@
+import { afterEach, describe, test, expect } from 'bun:test';
+import { useState } from 'react';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+// The Debugger portals into document.body, so leftovers from a previous
+// test are visible to `screen` queries — clean up explicitly (bun:test has
+// no global afterEach for RTL's auto-cleanup to hook).
+afterEach(cleanup);
+import { useFormDebugger } from './useFormDebugger';
+// The debugger-plumbing boundary in isolation: the hook must hand back a
+// render-stable component wired to the latest published snapshot. The full
+// overlay behavior (open/close, live form wiring) is covered in
+// FormDebugger.test.tsx through useFormState.
+const Host = () => {
+  const [count, setCount] = useState(0);
+  const Debugger = useFormDebugger({
+    snapshot: {
+      values: { count },
+      errors: [],
+      isValid: true,
+      submitAttempted: false,
+    },
+  });
+  return (
+    <div>
+      <button type="button" onClick={() => setCount((prev) => prev + 1)}>
+        inc
+      </button>
+      <Debugger label="dbg" />
+    </div>
+  );
+};
+describe('useFormDebugger', () => {
+  test('returns a Debugger showing the current snapshot', () => {
+    render(<Host />);
+    fireEvent.click(screen.getByRole('button', { name: 'dbg' }));
+    expect(screen.getByText('count')).toBeTruthy();
+    expect(screen.getByText('0')).toBeTruthy();
+  });
+  test('the component identity survives re-renders and shows fresh snapshots', () => {
+    render(<Host />);
+    fireEvent.click(screen.getByRole('button', { name: 'dbg' }));
+    fireEvent.click(screen.getByRole('button', { name: 'inc' }));
+    // The window is still open (a remounted Debugger would have reset to
+    // closed) and reflects the snapshot published after the re-render.
+    expect(screen.getByText('1')).toBeTruthy();
+    expect(screen.queryByText('0')).toBeNull();
+  });
+});

package/src/forms/useFormState/useFormDebugger.ts ADDED Viewed

@@ -0,0 +1,38 @@
+import { useEffect, useRef } from 'react';
+import { createFormDebugger } from './FormDebugger';
+import type { FormDebuggerComponent } from './FormDebugger';
+import { createSnapshotStore } from './snapshotStore';
+import type { SnapshotStore } from './snapshotStore';
+import type { FormDebugSnapshot, FormValuesObject } from './types';
+export type UseFormDebuggerArgs<T extends FormValuesObject> = {
+  snapshot: FormDebugSnapshot<T>;
+};
+// Debugger plumbing: one store + one component per hook instance, created
+// lazily on first render. The component's identity must be stable across
+// renders — recreated each render it would remount (and lose its
+// open/closed state) on every keystroke.
+export const useFormDebugger = <T extends FormValuesObject>(
+  args: UseFormDebuggerArgs<T>,
+): FormDebuggerComponent => {
+  const { snapshot } = args;
+  const debugRef = useRef<{
+    store: SnapshotStore<FormDebugSnapshot<T>>;
+    Debugger: FormDebuggerComponent;
+  } | null>(null);
+  if (debugRef.current === null) {
+    const store = createSnapshotStore(snapshot);
+    debugRef.current = { store, Debugger: createFormDebugger(store) };
+  }
+  const { store, Debugger } = debugRef.current;
+  // Publish after every commit. With no debugger window subscribed this is a
+  // field write and an empty notify loop — effectively free.
+  useEffect(() => {
+    store.publish(snapshot);
+  });
+  return Debugger;
+};

package/src/forms/useFormState/useFormState.ts CHANGED Viewed

@@ -1,19 +1,13 @@
-import { useEffect, useRef, useState } from 'react';
-import { createFormDebugger } from './FormDebugger';
-import type { FormDebuggerComponent } from './FormDebugger';
-import { createSnapshotStore } from './snapshotStore';
-import type { SnapshotStore } from './snapshotStore';
+import { useState } from 'react';
+import { deriveFormErrors } from './deriveErrors';
 import type {
-  FormDebugSnapshot,
-  FormError,
   FormHelpers,
   FormValuesObject,
   UnionPolicyCheck,
 } from './types';
-import type { Path } from '../path/types';
+import { useFormDebugger } from './useFormDebugger';
+import { useFormSubmit } from './useFormSubmit';
 import type { Refine, Validations } from '../validations/types';
-import { validateEntry } from '../validations/walk';
-import type { FlatConstraintEntry } from '../validations/walk';
 // `const V` freezes the inferred type of an inline `constraints` object —
 // each validator's precise type and Refinement marker survive without any
@@ -33,6 +27,11 @@ type Args<T extends FormValuesObject, V extends Validations<T>> = {
   onSubmit?: (values: Refine<T, V>) => void;
 } & UnionPolicyCheck<T>;
+// Plumbing only: each slice of form state lives in its own pure function or
+// focused hook, and this hook just links them up and recomposes their
+// outputs into the `FormHelpers<T>` surface. Values state is the one slice
+// kept inline — today it is a bare `useState`, and the granular setters that
+// would earn it a module of its own arrive with the path-based grammar.
 export const useFormState = <
   T extends FormValuesObject,
   const V extends Validations<T> = Validations<T>,
@@ -42,60 +41,21 @@ export const useFormState = <
   const { initialValues, constraints, onSubmit } = args;
   const [values, onValueChanges] = useState<T>(initialValues);
-  const [submitAttempted, setSubmitAttempted] = useState(false);
-  const errors: FormError<T>[] = [];
-  if (constraints) {
-    for (const key of Object.keys(constraints) as (keyof T & string)[]) {
-      // No cast: if the grammar grows a constraint form the walk doesn't
-      // understand, this assignment is the compile error that says so.
-      const entry: FlatConstraintEntry | undefined = constraints[key];
-      if (entry == null) continue;
-      const failure = validateEntry(entry, values[key], [key]);
-      if (failure == null) continue;
-      // The walk returns the address it was handed, and `[key]` — a key of
-      // a constraints object type-checked against T — is a valid single-key
-      // Path<T>. TS can't compute Path<T> for an unresolved generic T, so
-      // the correlation needs the same honest widening as the keys cast
-      // above.
-      errors.push({ path: failure.path as Path<T>, error: failure.error });
-    }
-  }
+  const errors = deriveFormErrors(values, constraints);
   const isValid = errors.length === 0;
-  // Debugger plumbing: one store + one component per hook instance, created
-  // lazily on first render. The component's identity must be stable across
-  // renders — recreated each render it would remount (and lose its
-  // open/closed state) on every keystroke.
-  const debugRef = useRef<{
-    store: SnapshotStore<FormDebugSnapshot<T>>;
-    Debugger: FormDebuggerComponent;
-  } | null>(null);
-  if (debugRef.current === null) {
-    const store = createSnapshotStore<FormDebugSnapshot<T>>({
-      values,
-      errors,
-      isValid,
-      submitAttempted,
-    });
-    debugRef.current = { store, Debugger: createFormDebugger(store) };
-  }
-  const { store, Debugger } = debugRef.current;
-  // Publish after every commit. With no debugger window subscribed this is a
-  // field write and an empty notify loop — effectively free.
-  useEffect(() => {
-    store.publish({ values, errors, isValid, submitAttempted });
+  // Explicit type arguments: V rides on `onSubmit`'s parameter type, which
+  // is not an inference site (see useFormSubmit.ts).
+  const { submitAttempted, submit } = useFormSubmit<T, V>({
+    values,
+    isValid,
+    onSubmit,
   });
-  const submit = () => {
-    setSubmitAttempted(true);
-    if (!isValid) return;
-    // Every constrained field's validator just passed at runtime — exactly
-    // the guarantee Refine<T, V> encodes.
-    onSubmit?.(values as Refine<T, V>);
-  };
+  const Debugger = useFormDebugger({
+    snapshot: { values, errors, isValid, submitAttempted },
+  });
   return {
     values,

package/src/forms/useFormState/useFormSubmit.test.tsx ADDED Viewed

@@ -0,0 +1,86 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFormSubmit } from './useFormSubmit';
+// The submit-orchestration boundary in isolation: the attempt flag and the
+// validity gate, driven by whatever `isValid` the caller derived. Full-form
+// behavior (validity flipping as values change) stays in useFormState.test.tsx.
+type Form = { email: string | undefined };
+describe('useFormSubmit', () => {
+  test('starts with submitAttempted false', () => {
+    const { result } = renderHook(() =>
+      useFormSubmit<Form>({ values: { email: undefined }, isValid: true }),
+    );
+    expect(result.current.submitAttempted).toBe(false);
+  });
+  test('submit on an invalid form marks the attempt and skips onSubmit', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormSubmit<Form>({ values: { email: undefined }, isValid: false, onSubmit }),
+    );
+    act(() => {
+      result.current.submit();
+    });
+    expect(result.current.submitAttempted).toBe(true);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+  test('submit on a valid form calls onSubmit with the current values', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormSubmit<Form>({ values: { email: 'a@b.co' }, isValid: true, onSubmit }),
+    );
+    act(() => {
+      result.current.submit();
+    });
+    expect(result.current.submitAttempted).toBe(true);
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith({ email: 'a@b.co' });
+  });
+  test('submit without an onSubmit handler is a no-op beyond the flag', () => {
+    const { result } = renderHook(() =>
+      useFormSubmit<Form>({ values: { email: 'a@b.co' }, isValid: true }),
+    );
+    act(() => {
+      result.current.submit();
+    });
+    expect(result.current.submitAttempted).toBe(true);
+  });
+  test('submitAttempted stays true once validity flips', () => {
+    const onSubmit = mock(() => {});
+    const initialProps: { isValid: boolean; email: string | undefined } = {
+      isValid: false,
+      email: undefined,
+    };
+    const { result, rerender } = renderHook(
+      (props: { isValid: boolean; email: string | undefined }) =>
+        useFormSubmit<Form>({
+          values: { email: props.email },
+          isValid: props.isValid,
+          onSubmit,
+        }),
+      { initialProps },
+    );
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+    rerender({ isValid: true, email: 'a@b.co' });
+    expect(result.current.submitAttempted).toBe(true);
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledWith({ email: 'a@b.co' });
+  });
+});

package/src/forms/useFormState/useFormSubmit.ts ADDED Viewed

@@ -0,0 +1,38 @@
+import { useState } from 'react';
+import type { Refine, Validations } from '../validations/types';
+import type { FormValuesObject } from './types';
+export type UseFormSubmitArgs<
+  T extends FormValuesObject,
+  V extends Validations<T>,
+> = {
+  values: T;
+  isValid: boolean;
+  onSubmit?: (values: Refine<T, V>) => void;
+};
+// Submit orchestration: owns the `submitAttempted` flag (UIs gate error
+// display on it) and the validity gate in front of `onSubmit`. This is the
+// home of the ONE sanctioned refinement cast (see the cast doctrine in
+// src/forms/CLAUDE.md). `V` is not inferable from `onSubmit`'s parameter
+// position, so `useFormState` applies both type arguments explicitly.
+export const useFormSubmit = <
+  T extends FormValuesObject,
+  V extends Validations<T> = Validations<T>,
+>(
+  args: UseFormSubmitArgs<T, V>,
+) => {
+  const { values, isValid, onSubmit } = args;
+  const [submitAttempted, setSubmitAttempted] = useState(false);
+  const submit = () => {
+    setSubmitAttempted(true);
+    if (!isValid) return;
+    // Every constrained field's validator just passed at runtime — exactly
+    // the guarantee Refine<T, V> encodes.
+    onSubmit?.(values as Refine<T, V>);
+  };
+  return { submitAttempted, submit };
+};

package/src/forms/validations/walk.ts CHANGED Viewed

@@ -19,8 +19,9 @@ export type ValidationError = {
 type AnyFieldValidator = (val: never) => string | null;
 // The walk's view of one entry in a `Validations<T>` object. This type is
-// what lets the compiler police the walk's assumptions: the hook assigns
-// `constraints[key]` to it WITHOUT a cast, so when the grammar grows a form
+// what lets the compiler police the walk's assumptions: the error derivation
+// (`useFormState/deriveErrors.ts`) assigns `constraints[key]` to it WITHOUT
+// a cast, so when the grammar grows a form
 // that is neither a function nor an array of them (nested spec, list `each`),
 // that assignment stops compiling and the walk must learn the new form —
 // instead of a stale walk misinterpreting it at runtime.