@structuralists/scaffolding 0.10.1 → 0.11.0

package/src/forms/plan.md

@@ -16,25 +16,33 @@ TS wall can't strand finished work behind it.
    (PR #14, released 0.6.0)
 2. **Item 1 — validator arrays per key.** `ExcludedOf<C[number]>` already
    proven inside `allOf`. ✅ *done* — grammar (`FieldConstraint`), distributive
-   `RefineField`, and the walk rewrite (`validations/walk.ts`, cast-free entry
+   `RefineField`, and the walk rewrite (`state/validations/walk.ts`, cast-free entry
    dispatch, `PathStep[]`-addressed errors) landed together; probe ratchet
    held (see the baseline note under the recursion budget).
 3. **Error-model swap** to `{path, error}[]` on the *flat* baseline (paths
    are single-key paths). Doesn't depend on nested constraints; hard
    prerequisite for item 6; makes phases 2–3 runtime-plumbing-free.
    ✅ *done* — `FormError<T>`/`FormErrors<T>` (`{ path: Path<T>; error }[]`
-   in useFormState/types.ts), `isValid` derived from emptiness, and the
+   in state/useFormState/types.ts), `isValid` derived from emptiness, and the
    interim consumer accessor is a standalone `errorAt(errors, path)`
-   (useFormState/errorAt.ts) — the smallest surface that keeps stories
+   (state/useFormState/errorAt.ts) — the smallest surface that keeps stories
    readable; item 6 folds the same lookup into `getFormFieldPropsAt`'s
    `errorMessage`. The Debugger needed no change (`toInspectable`
    index-keys arrays).
 4. **Item 5 — elements/state split.** Pure churn, no type risk; do it before
-   item 6 so the wrappers land in their final home once. ← *current*
+   item 6 so the wrappers land in their final home once. ✅ *done* — one
+   `src/forms/` umbrella: elements in `src/forms/elements/<Component>/`,
+   the state layer in `src/forms/state/{useFormState,validations,validators,path}/`.
 5. **Item 6 — field binding** (`getFormFieldPropsAt` + wrappers). Needs the
-   error model and the split; `Path`/`ValueAt` already validated.
-6. **Type spike, then items 2/3/4** — the recursion risk zone. Throwaway
-   `.test-d.ts` of the full grammar at `InsuranceQuoteForm` scale *before*
+   error model and the split; `Path`/`ValueAt` already validated. ✅ *done* —
+   `getFormFieldPropsAt` on the hook result (value / typed onChange /
+   policy-aware errorMessage / onBlur), `write()` as the immutable mirror of
+   `read()` in `state/path/path.ts`, touched tracking as real state, and the
+   wrapper-style element shorthands prototyped (`state/bindings/`:
+   `TextInputForForm`, `SingleSelectForForm`). Probe ratchet held (see the
+   baseline note under the recursion budget).
+6. **Type spike, then items 2/3/4** — the recursion risk zone. ← *current*
+   Throwaway `.test-d.ts` of the full grammar at `InsuranceQuoteForm` scale *before*
    any runtime work; three outcomes (works / slow / intractable) each with a
    known response. Worst case, everything above still shipped.
 
@@ -123,7 +131,7 @@ useFormState({
 ```ts
 type ExcludedOf<V> = V extends Refinement<infer X> ? X : never;
 // MemberExcludes<C>: the per-member-sound union of a validator tuple's
-// excludes — it and SoundExcludedOf landed with phase 1 in validations/types.ts.
+// excludes — it and SoundExcludedOf landed with phase 1 in state/validations/types.ts.
 
 type RefineField<F, C> =
   C extends Refinement<infer X>        ? Exclude<F, X>                 // single marked validator
@@ -185,11 +193,18 @@ multi-second check time:
 - post-step-3 (error-model swap: `Path<T>`-typed `FormError`, `errorAt`,
   plus probes): check 0.79 s, 113,724 instantiations, 52,294 types
   (+4.4% instantiations over pre-step-3 HEAD)
+- post-item-5 split (0.10.1): check 0.81 s, 112,981 instantiations,
+  52,504 types
+- post-item-6 (field binding: `getFormFieldPropsAt`, `FieldBinding`
+  wrappers, plus deep-path probes at `InsuranceQuoteForm` scale): check
+  0.82 s, 125,022 instantiations, 54,959 types (+10.7% instantiations over
+  post-item-5 — the `ValueAt` instantiations at each binding call site are
+  real but cheap; check time flat)
 
 ## Runtime consequences (can't be dodged)
 
 - **The validator walk becomes a tree walk.** Recursion mirrors `read()` in
-  `path/path.ts`; share the traversal or keep them deliberately parallel.
+  `state/path/path.ts`; share the traversal or keep them deliberately parallel.
 - **`FormErrors` can no longer be `Partial<Record<keyof T, string>>`.**
   ✅ *Landed with working-order step 3* (on the flat baseline, single-key
   paths). Decided: errors become a plain list of structured entries,
@@ -199,7 +214,7 @@ multi-second check time:
   // errors: FormError<T>[]      isValid: errors.length === 0
   ```
 
-  reusing `path/`'s typed representation (this is the "surfacing per-field
+  reusing `state/path/`'s typed representation (this is the "surfacing per-field
   errors" role path/ was built for). **We will never expose
   `'drivers.0.name'`-style serialized-string key derivation.** At the scale
   these forms operate, a linear scan over `{path, error}[]` is fine. If fast
@@ -208,7 +223,7 @@ multi-second check time:
   fully encapsulated and opaque to everything outside it.
 - **`errors` display wiring** in stories/components goes through a typed
   accessor, never through hand-assembled keys. ✅ *Decided and landed with
-  step 3*: a standalone `errorAt(errors, path)` (useFormState/errorAt.ts) —
+  step 3*: a standalone `errorAt(errors, path)` (state/useFormState/errorAt.ts) —
   structural step-equality lookup, first entry wins. Chosen over a
   cursor-based lookup as the smallest surface that keeps stories readable
   on the flat grammar; item 6's `errorMessage` reuses it internally.
@@ -228,7 +243,7 @@ tests, story updates where visible, probe ratchet.
    marker computation. ✅ *done* — plus a byproduct: `RefineField`
    distributes over a naked constraint parameter, which made union-typed
    *single* constraints (`cond ? v1 : v2`) sound too (union of per-branch
-   refinements, pinned in `validations/types.test-d.ts`).
+   refinements, pinned in `state/validations/types.test-d.ts`).
 2. **Nested object specs + recursive `Refine`.** The risk phase — the probe
    ratchet matters most here. (The `{path, error}[]` error model already
    landed in working-order step 3 — nested errors just carry longer paths;
@@ -240,32 +255,62 @@ tests, story updates where visible, probe ratchet.
    `perField` still the entry point for pre-built specs, docs
    (forms/CLAUDE.md) updated to the new grammar.
 
-## 5. Split forms into 'form elements' and 'form state'
+## 5. Split forms into 'form elements' and 'form state' ✅ done
 
-Today the form world lives in two places with unrelated names:
+The form world used to live in two places with unrelated names
+(`src/components/Forms/` vs `src/forms/` — an accidental `Forms`-vs-`forms`
+distinction). The layout decision landed on **one `src/forms/` umbrella with
+two named subtrees**:
 
-- `src/components/Forms/` — the presentational **elements** (`Input`,
-  `Field`, `Select`, `Button`, `Textarea`, …)
-- `src/forms/` — the **state** layer (`useFormState`, `validations/`,
+- `src/forms/elements/` — the presentational **elements** (`Input`,
+  `Field`, `Select`, `Button`, `Textarea`, …), one primitive per folder,
+  same shape as `src/components/<Section>/<Component>/`
+- `src/forms/state/` — the **state** layer (`useFormState/`, `validations/`,
   `validators/`, `path/`)
 
-The intent: make that split explicit and named — 'form elements' vs
-'form state' — rather than the current accidental `Forms`-vs-`forms`
-distinction. Recorded as direction; the target layout/naming is an open
-decision (rename in place? move both under one `forms/` umbrella with
-`elements/` and `state/` subtrees?).
-
-Blast radius to account for when this happens (not now):
-
-- the eslint `boundaries` element patterns in `eslint.config.mjs` are keyed
-  to `src/components/<Section>/<Component>/` shapes,
-- barrel exports in `src/index.ts` (all the element components are public),
-- Storybook titles (`Forms/...` prefix) and story globs,
-- forms/CLAUDE.md and this plan's own paths.
-
-Independent of phases 1–4; can land before, between, or after them.
-
-## 6. Field binding: `getFormFieldPropsAt(path)` + element shorthands
+Blast radius that was handled when this landed:
+
+- the eslint `boundaries` element patterns in `eslint.config.mjs` (were keyed
+  to `src/components/<Section>/<Component>/` shapes): element primitives got
+  matching patterns at their new home, `src/forms/state` became its own
+  element type, and two directional rules were added — elements/components
+  must not import the state layer, and state files importing a primitive go
+  through its barrel,
+- barrel exports in `src/index.ts` (all the element components are public —
+  paths moved, exported surface unchanged),
+- Storybook titles (`Forms/...` prefix) and story globs: titles kept as-is —
+  elements stay `Forms/<Component>`, the state story stays
+  `Forms/useFormState`; the story glob (`src/**/*.stories.*`) needed no
+  change,
+- forms/CLAUDE.md and this plan's own paths,
+- `FormDebugger.tsx` imports `JsonTable` from `src/components/Json/` — the
+  sanctioned state→elements bridge dependency (audit finding 3.3; the
+  Debugger is a designated bridge layer). Explicitly allowed for in the new
+  boundaries rules.
+
+## 6. Field binding: `getFormFieldPropsAt(path)` + element shorthands ✅ done
+
+Landed as specced below; deltas and decisions:
+
+- `write()` in `state/path/path.ts` is the immutable-update mirror of
+  `read()` — clones only the spine, dead-step semantics mirror read()
+  returning undefined (writing through an absent section is an
+  identity-preserving no-op; materialize the section first).
+- Touched is real state (`useFieldBinding`), a `Path<T>[]` compared with
+  `pathsEqual` — the same structural representation as `FormErrors`. It
+  also shows up in the Debugger snapshot.
+- The error-display policy (touched-or-submitAttempted) lives inside
+  `errorMessage`, nowhere else — see "Field binding" in forms/CLAUDE.md.
+- **Element-shorthand style: the wrapper style is the prototype**
+  (`TextInputForForm`, `SingleSelectForForm` in `src/forms/state/bindings/`,
+  the second sanctioned state→elements bridge after the Debugger). The
+  wrappers declare what they display/emit via `FieldBinding<Display, Emit>`
+  and plain structural assignability rejects wrong-shaped bindings — no
+  generics at the use site. Union-typed props on the elements themselves
+  remain the fallback if the parallel component set gets heavy; judge after
+  the wrapper set grows past these two.
+
+Original spec follows.
 
 Today every field is wired by hand in JSX: read `values.x`, spread-update via
 `onValueChanges`, look up the error, gate it on `submitAttempted`. That's
@@ -278,7 +323,7 @@ four decisions per field, all boilerplate. Target usage:
 ### `getFormFieldPropsAt(path)`
 
 A member of the hook's return value (it needs `values`, `errors`, and the
-setter), typed by the `path/` machinery:
+setter), typed by the `state/path/` machinery:
 
 ```ts
 type FormFieldProps<V> = {
@@ -297,7 +342,7 @@ Consequences this pulls in deliberately:
 
 - **Granular setters via path arrive here** — this retires the "likely
   remove" todo on `onValueChanges` as the only write path. Writing at a path
-  is the immutable-update mirror of `read()` in `path/path.ts`.
+  is the immutable-update mirror of `read()` in `state/path/path.ts`.
 - **Touched tracking becomes real state** (`onBlur` feeds it). The
   error-display policy (submitAttempted / touched gating) moves *inside*
   `errorMessage`, so consuming elements render what they're given and stay
@@ -417,8 +462,9 @@ Possibly a hybrid: identity-matching as the default heuristic, owned ops as
 the guaranteed path. **Research topic for when we get here** — record
 findings in the learning map before committing to either.
 
-Sequencing: visited tracking lands with item 6 (its `onBlur` is the write
-path). Keys + array-sync matter from phase 3 (list `each` specs) onward —
+Sequencing: visited tracking ✅ *landed with item 6* (its `onBlur` is the
+write path; `touched: Path<T>[]` in `useFieldBinding`, structural equality
+via `pathsEqual`). Keys + array-sync matter from phase 3 (list `each` specs) onward —
 error paths and per-element meta both need element identity once lists are
 editable.
 

package/src/forms/state/bindings/SingleSelectForForm.tsx

@@ -0,0 +1,45 @@
+import { Field } from '../../elements/Field';
+import { SingleSelect } from '../../elements/Select';
+import type { SelectOption, SelectSize } from '../../elements/Select';
+import type { FieldBinding } from '../useFormState/types';
+
+export type SingleSelectForFormProps<T extends string> = {
+  // Displays T|null|undefined, emits T — a FormFieldProps<V> fits when the
+  // path's value type sits between them, so the options' literal union and
+  // the field's type must line up or the binding fails to compile.
+  formFieldProps: FieldBinding<T | null | undefined, T>;
+  options: SelectOption<T>[];
+  label: string;
+  hint?: string;
+  placeholder?: string;
+  size?: SelectSize;
+  isDisabled?: boolean;
+};
+
+// The form-aware flavor of the single select. A select has no meaningful
+// blur moment — committing an option IS the completed interaction — so the
+// commit marks the field touched alongside the write.
+export const SingleSelectForForm = <T extends string>(
+  props: SingleSelectForFormProps<T>,
+) => {
+  const { formFieldProps, options, label, hint, placeholder, size, isDisabled } =
+    props;
+  const { value, onChange, errorMessage, onBlur } = formFieldProps;
+
+  return (
+    <Field label={label} hint={hint} error={errorMessage}>
+      <SingleSelect
+        options={options}
+        value={value ?? null}
+        onChange={(next) => {
+          onChange(next);
+          onBlur();
+        }}
+        size={size}
+        isDisabled={isDisabled}
+        placeholder={placeholder}
+        ariaLabel={label}
+      />
+    </Field>
+  );
+};

package/src/forms/state/bindings/TextInputForForm.tsx

@@ -0,0 +1,45 @@
+import { Field } from '../../elements/Field';
+import { Input } from '../../elements/Input';
+import type { InputProps } from '../../elements/Input';
+import type { FieldBinding } from '../useFormState/types';
+
+export type TextInputForFormProps = {
+  // The bundle from `getFormFieldPropsAt(path)`. The binding shape declares
+  // what this element can do — display string-ish, emit string — so a
+  // FormFieldProps<V> only fits when V is a text-shaped field
+  // (string / string|null / string|undefined / both). A number- or
+  // boolean-typed path is a compile error right here.
+  formFieldProps: FieldBinding<string | null | undefined, string>;
+  label: string;
+  hint?: string;
+  placeholder?: string;
+  id?: string;
+  type?: InputProps['type'];
+  size?: InputProps['size'];
+  disabled?: boolean;
+};
+
+// The form-aware flavor of the text input: one prop wires value, change,
+// error display, and touched tracking. Composes Field (label/hint/error
+// presentation) around Input; the error-display policy already happened
+// inside `errorMessage` — this component just renders what it's given.
+export const TextInputForForm = (props: TextInputForFormProps) => {
+  const { formFieldProps, label, hint, placeholder, id, type, size, disabled } =
+    props;
+  const { value, onChange, errorMessage, onBlur } = formFieldProps;
+
+  return (
+    <Field label={label} hint={hint} error={errorMessage} htmlFor={id}>
+      <Input
+        id={id}
+        type={type}
+        size={size}
+        value={value ?? ''}
+        onChange={(e) => onChange(e.target.value)}
+        onBlur={onBlur}
+        placeholder={placeholder}
+        disabled={disabled}
+      />
+    </Field>
+  );
+};

package/src/forms/{path → state/path}/path.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'bun:test';
-import { path, read } from './path';
+import { path, pathsEqual, read, write } from './path';
 
 // These tests pin read()'s runtime semantics to exactly what the type level
 // (ValueAt) promises — see the union-semantics comments in ./types.ts and
@@ -95,6 +95,65 @@ describe('read step failures', () => {
     ).toBeUndefined();
   });
 
+  test('write replaces the value at a deep path without mutating the original', () => {
+    const next = write(filled, ['address', 'city'], 'Paris') as Form;
+
+    expect(next.address?.city).toBe('Paris');
+    expect(filled.address?.city).toBe('London');
+  });
+
+  test('write clones only the spine — untouched siblings keep their identity', () => {
+    const next = write(filled, ['a', 'b', 'c'], 'deeper') as Form;
+
+    // The spine to the written leaf is new at every level …
+    expect(next).not.toBe(filled);
+    expect(next.a).not.toBe(filled.a);
+    expect(next.a?.b).not.toBe(filled.a?.b);
+    // … while every branch off the spine is the same object.
+    expect(next.address).toBe(filled.address);
+    expect(next.entries).toBe(filled.entries);
+  });
+
+  test('write into a list element clones the array and that element only', () => {
+    const twoEntries: Form = {
+      ...filled,
+      entries: [
+        { title: 'first', qty: 1 },
+        { title: 'second', qty: 2 },
+      ],
+    };
+    const next = write(twoEntries, ['entries', 1, 'qty'], 5) as Form;
+
+    expect(next.entries?.[1]).toEqual({ title: 'second', qty: 5 });
+    expect(next.entries).not.toBe(twoEntries.entries);
+    expect(next.entries?.[0]).toBe(twoEntries.entries?.[0]);
+    expect(twoEntries.entries?.[1].qty).toBe(2);
+  });
+
+  test('write with an empty path replaces the root', () => {
+    expect(write(filled, [], { name: 'Eve' })).toEqual({ name: 'Eve' });
+  });
+
+  test('write through a dead ancestor is an identity-preserving no-op', () => {
+    // Mirrors read() returning undefined for a dead step: you cannot edit a
+    // field of an absent section — materialize the section first.
+    expect(write(empty, ['address', 'city'], 'Paris')).toBe(empty);
+    expect(write(empty, ['entries', 0, 'title'], 'x')).toBe(empty);
+  });
+
+  test('write on a shape mismatch or out-of-bounds index is a no-op', () => {
+    // Numeric step on a non-array, key step on a scalar, index past the end
+    // (appending is list manipulation, not a path write).
+    expect(write(filled, ['name', 'length'], 3)).toBe(filled);
+    expect(write(filled, ['entries', 5, 'title'], 'x')).toBe(filled);
+    const list = [1, 2];
+    expect(write(list, ['key'], 'x')).toBe(list);
+  });
+
+  test('writing the value already present is an identity-preserving no-op', () => {
+    expect(write(filled, ['address', 'city'], 'London')).toBe(filled);
+  });
+
   test('rejecting narrow predicate returns undefined; accepting one passes through', () => {
     const isString = (val: unknown): val is string => typeof val === 'string';
     const narrowed = path<Form>()
@@ -110,3 +169,14 @@ describe('read step failures', () => {
     expect(read(filled, rejecting)).toBeUndefined();
   });
 });
+
+describe('pathsEqual', () => {
+  test('structural equality over steps — same steps equal, no prefix matching', () => {
+    expect(pathsEqual(['a', 0, 'b'], ['a', 0, 'b'])).toBe(true);
+    expect(pathsEqual([], [])).toBe(true);
+    expect(pathsEqual(['a'], ['a', 'b'])).toBe(false);
+    expect(pathsEqual(['a', 0], ['a', 1])).toBe(false);
+    // A numeric step never equals its string spelling.
+    expect(pathsEqual(['a', 0], ['a', '0'])).toBe(false);
+  });
+});

package/src/forms/state/path/path.ts

@@ -0,0 +1,103 @@
+import type { Cursor, CursorStep, Path, PathStep, ValueAt } from './types';
+
+const makeCursor = <T>(steps: readonly CursorStep[]): Cursor<T> => ({
+  at<P extends Path<T>>(p: P): Cursor<ValueAt<T, P>> {
+    const keySteps: CursorStep[] = (p as readonly PathStep[]).map((key) => ({
+      kind: 'key',
+      key,
+    }));
+
+    return makeCursor<ValueAt<T, P>>([...steps, ...keySteps]);
+  },
+  narrow<U extends T>(predicate: (val: T) => val is U): Cursor<U> {
+    return makeCursor<U>([
+      ...steps,
+      { kind: 'narrow', predicate: predicate as (val: unknown) => boolean },
+    ]);
+  },
+  build() {
+    return [...steps];
+  },
+});
+
+export const path = <T>(): Cursor<T> => makeCursor<T>([]);
+
+// Structural path equality: same steps, same order, no prefix matching.
+// The one sanctioned way to compare paths — `errorAt` and touched tracking
+// both build on it, so "do these address the same field?" has exactly one
+// definition.
+export const pathsEqual = (
+  a: readonly PathStep[],
+  b: readonly PathStep[],
+): boolean => a.length === b.length && a.every((step, index) => step === b[index]);
+
+// Walk steps against a value. Returns undefined if any step fails — a dead
+// value (null or undefined) encountered mid-path, missing key, out-of-bounds
+// index, or a narrow predicate that rejects the current value. Always
+// undefined, never null, even when the dead value was null — ValueAt in
+// ./types.ts mirrors this exactly (see "Union policy" in src/forms/CLAUDE.md).
+// Callers using the typed cursor know what shape to expect; this is the
+// runtime escape hatch that surfaces "the path didn't resolve."
+export const read = (root: unknown, steps: readonly CursorStep[]): unknown => {
+  let cursor: unknown = root;
+
+  for (const step of steps) {
+    if (cursor == null) return undefined;
+
+    if (step.kind === 'narrow') {
+      if (!step.predicate(cursor)) return undefined;
+      continue;
+    }
+
+    if (typeof step.key === 'number') {
+      if (!Array.isArray(cursor)) return undefined;
+      cursor = cursor[step.key];
+    } else {
+      if (typeof cursor !== 'object') return undefined;
+      cursor = (cursor as Record<string, unknown>)[step.key];
+    }
+  }
+
+  return cursor;
+};
+
+// The immutable-update mirror of read(): returns a new root with `value`
+// placed at `steps`, cloning only the containers along the path — untouched
+// siblings keep their identity. Key-only steps (a `Path<T>` value), not
+// CursorStep — there is no meaningful way to write "through" a narrow
+// predicate.
+//
+// Dead-step semantics mirror read() returning undefined: a step that hits a
+// null/undefined container, a shape mismatch (key step on a non-object,
+// numeric step on a non-array), or an out-of-bounds index makes the whole
+// write a no-op that returns `root` by identity — you can't edit a field of
+// an absent section; materialize the section first. (Appending/splicing is
+// list-manipulation territory, deliberately not a path write.) Writing a
+// value that is already there (Object.is) is also an identity-preserving
+// no-op, so state setters can bail out of re-rendering.
+export const write = (
+  root: unknown,
+  steps: readonly PathStep[],
+  value: unknown,
+): unknown => {
+  if (steps.length === 0) return value;
+  const [head, ...rest] = steps;
+
+  if (typeof head === 'number') {
+    if (!Array.isArray(root)) return root;
+    if (head < 0 || head >= root.length) return root;
+    const child = write(root[head], rest, value);
+    if (Object.is(child, root[head])) return root;
+    const clone = root.slice();
+    clone[head] = child;
+    return clone;
+  }
+
+  if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+    return root;
+  }
+  const record = root as Record<string, unknown>;
+  const child = write(record[head], rest, value);
+  if (Object.is(child, record[head])) return root;
+  return { ...record, [head]: child };
+};

package/src/forms/{useFormState → state/useFormState}/FormDebugger.tsx

@@ -1,7 +1,7 @@
 import { useState, useSyncExternalStore } from 'react';
 import type { ReactElement } from 'react';
 import { createPortal } from 'react-dom';
-import { JsonTable } from '../../components/Json/JsonTable';
+import { JsonTable } from '../../../components/Json/JsonTable';
 import { toInspectable } from './inspectable';
 import type { SnapshotStore } from './snapshotStore';
 import type { FormDebugSnapshot, FormValuesObject } from './types';
@@ -43,6 +43,7 @@ export const createFormDebugger = <T extends FormValuesObject>(
             submitAttempted: snapshot.submitAttempted,
             values: snapshot.values,
             errors: snapshot.errors,
+            touched: snapshot.touched,
           })}
         />
       </div>

package/src/forms/{useFormState → state/useFormState}/errorAt.ts

@@ -1,11 +1,12 @@
+import { pathsEqual } from '../path/path';
 import type { Path, PathStep } from '../path/types';
 import type { FormErrors, FormValuesObject } from './types';
 
 // Typed lookup into the structured `{ path, error }[]` error list — the
-// sanctioned way to read one field's error. Path equality is structural:
-// same steps, same order, no prefix matching. With first-error-wins
-// validation there is at most one entry per path today; should collect-all
-// ever land, the first entry stays the one shown.
+// sanctioned way to read one field's error. Path equality is structural
+// (`pathsEqual`): same steps, same order, no prefix matching. With
+// first-error-wins validation there is at most one entry per path today;
+// should collect-all ever land, the first entry stays the one shown.
 export const errorAt = <T extends FormValuesObject>(
   errors: FormErrors<T>,
   path: Path<T>,
@@ -14,14 +15,9 @@ export const errorAt = <T extends FormValuesObject>(
   // prove it for an unresolved T. Same honest widening as `Cursor.at`.
   const steps = path as readonly PathStep[];
 
-  const match = errors.find((candidate) => {
-    const candidateSteps = candidate.path as readonly PathStep[];
-
-    return (
-      candidateSteps.length === steps.length &&
-      candidateSteps.every((step, index) => step === steps[index])
-    );
-  });
+  const match = errors.find((candidate) =>
+    pathsEqual(candidate.path as readonly PathStep[], steps),
+  );
 
   return match?.error;
 };

package/src/forms/{useFormState → state/useFormState}/types.ts

@@ -1,7 +1,7 @@
 // Type-only imports; FormDebugger.tsx and path/types.ts import value types
 // from this file in turn, but the cycles never exist at runtime.
 import type { FormDebuggerComponent } from './FormDebugger';
-import type { Path } from '../path/types';
+import type { Path, ValueAt } from '../path/types';
 
 export type FormValueSimple = string | number | bigint | boolean | string[] | Set<string> | undefined | null;
 
@@ -90,6 +90,28 @@ export type FormError<T extends FormValuesObject> = {
 
 export type FormErrors<T extends FormValuesObject> = readonly FormError<T>[];
 
+// What a form-aware element declares it needs from a field binding: it
+// *displays* `Display` and *emits* `Emit`. A `FormFieldProps<V>` is
+// assignable exactly when V sits between them (`Emit ⊆ V ⊆ Display`), which
+// is how "a number-typed path bound to a text-shaped element" becomes a
+// compile error at the `formFieldProps` prop — no generics needed on the
+// wrapper, structural assignability does the checking.
+export type FieldBinding<Display, Emit = Display> = {
+  value: Display;
+  onChange: (val: Emit) => void;
+  // Already display-policy-aware (see `useFieldBinding`): undefined until
+  // the field's error should be SHOWN, so elements render what they're
+  // given and stay policy-free.
+  errorMessage: string | undefined;
+  // Feeds touched tracking; wire it to the element's blur (or, for
+  // commit-style elements like selects, to the commit).
+  onBlur: () => void;
+  // room to grow: name/id derivation, disabled, ...
+};
+
+// The bundle `getFormFieldPropsAt(path)` returns for the field at that path.
+export type FormFieldProps<V> = FieldBinding<V>;
+
 // What the hook publishes (via `useFormDebugger`) to its Debugger after
 // every commit. Snapshots are
 // replaced whole (never mutated) so `useSyncExternalStore` consumers can
@@ -99,11 +121,14 @@ export type FormDebugSnapshot<T extends FormValuesObject> = {
   errors: FormErrors<T>;
   isValid: boolean;
   submitAttempted: boolean;
+  touched: readonly Path<T>[];
 };
 
 export type FormHelpers<T extends FormValuesObject> = {
   values: T;
-  // todo: likely remove once other setter are available
+  // Whole-value replacement. No longer the only write path (field-level
+  // writes go through `getFormFieldPropsAt(path).onChange`); whether this
+  // survives long-term is a separate decision.
   onValueChanges: (val: T | ((prev: T) => T)) => void;
   // Live-derived from the current values on every render; UIs that only want
   // errors after a submit attempt gate on `submitAttempted`.
@@ -111,6 +136,12 @@ export type FormHelpers<T extends FormValuesObject> = {
   isValid: boolean;
   submitAttempted: boolean;
   submit: () => void;
+  // One expression wires a field: value, typed onChange (an immutable write
+  // at the path), display-policy-aware errorMessage, and onBlur (touched
+  // tracking). `ValueAt<T, P>` types value/onChange end-to-end, so binding a
+  // wrong-shaped path to an element fails to compile at the element's
+  // `formFieldProps` prop.
+  getFormFieldPropsAt: <P extends Path<T>>(path: P) => FormFieldProps<ValueAt<T, P>>;
   // Dev-time introspection overlay bound to this form instance: a fixed
   // trigger that opens a window showing the form's live internal state.
   // Render it anywhere (it portals to <body>); omit it and nothing mounts.