@structuralists/scaffolding 0.10.2 → 0.11.0

package/eslint.config.mjs

@@ -132,10 +132,10 @@ export default [{
               "Files inside a primitive folder must not import their own index barrel; import the neighbor directly.",
           },
           // Presentational primitives (components and form elements) must
-          // not reach into the form-state layer. The sanctioned bridge runs
+          // not reach into the form-state layer. The sanctioned bridges run
           // the other way: state's FormDebugger imports the JsonTable barrel
-          // (dev tooling), and the item-6 form-aware wrappers will live with
-          // the state side. State stories may also use element barrels.
+          // (dev tooling), and the form-aware wrappers live on the state
+          // side (state/bindings/). State stories may also use element barrels.
           {
             from: [
               { type: 'primitive' },

package/package.json

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

package/src/forms/CLAUDE.md

@@ -10,10 +10,11 @@ The forms umbrella, split into two named subtrees:
 - `state/` — the strongly-typed React form state hook and its machinery.
   Everything below this heading is about the state layer.
 
-The one sanctioned state→elements-side dependency is the Debugger bridge:
-`state/useFormState/FormDebugger.tsx` imports the `JsonTable` barrel from
-`src/components/Json/` (dev tooling). The item-6 form-aware wrappers will be
-the second bridge, living on the state side.
+Two sanctioned state→elements-side bridges exist, both on the state side:
+the Debugger (`state/useFormState/FormDebugger.tsx` imports the `JsonTable`
+barrel from `src/components/Json/`, dev tooling) and the form-aware element
+wrappers (`state/bindings/` — see "Field binding" below). State files
+importing an element go through its barrel like any external importer.
 
 The headline feature of the state layer is **validation that propagates type
 refinements to the submit handler** — passing the right constraints means the
@@ -201,11 +202,74 @@ errorAt(errors, ['email']); // string | undefined
 ```
 
 `errorAt` (state/useFormState/errorAt.ts) matches by exact structural step
-equality (no prefix matching); with first-error-wins validation there is at
-most one entry per path, and if collect-all ever lands the first entry stays
-the one shown. The path-addressed model is what the recursive grammar
-(errors just carry longer paths) and `getFormFieldPropsAt`'s `errorMessage`
-build on.
+equality (`pathsEqual` in state/path/path.ts — no prefix matching); with
+first-error-wins validation there is at most one entry per path, and if
+collect-all ever lands the first entry stays the one shown. The
+path-addressed model is what the recursive grammar (errors just carry
+longer paths) and `getFormFieldPropsAt`'s `errorMessage` build on. `errorAt`
+is raw truth (no display gating); `errorMessage` is the display-policy-aware
+reading (see "Field binding").
+
+## Field binding: `getFormFieldPropsAt(path)` + `state/bindings/`
+
+One expression wires a field to the form:
+
+```tsx
+<TextInputForForm label="City"
+  formFieldProps={getFormFieldPropsAt(['homeAddress', 'city'])} />
+```
+
+`getFormFieldPropsAt` is a member of the hook's return value, typed by the
+`state/path/` machinery:
+
+```ts
+// on FormHelpers<T>:
+getFormFieldPropsAt<P extends Path<T>>(path: P): FormFieldProps<ValueAt<T, P>>;
+
+type FormFieldProps<V> = FieldBinding<V>;
+type FieldBinding<Display, Emit = Display> = {
+  value: Display;                   // read(values, path)
+  onChange: (val: Emit) => void;    // immutable write(values, path, val)
+  errorMessage: string | undefined; // display-policy-aware (below)
+  onBlur: () => void;               // feeds touched tracking
+};
+```
+
+The pieces, and where each one's semantics live:
+
+- **Granular path writes** — `write()` in `state/path/path.ts`, the
+  immutable-update mirror of `read()`: clones only the spine to the written
+  leaf, so untouched siblings keep identity. Dead-step semantics mirror
+  read() returning undefined: writing through an absent/null ancestor, a
+  shape mismatch, or an out-of-bounds index is an identity-preserving no-op
+  — you can't edit a field of an absent section; materialize the section
+  first. (Appending/splicing lists is item-8 territory, not a path write.)
+  `onValueChanges` (whole-value replacement) still exists but is no longer
+  the only write path.
+- **Touched tracking** — real state in `useFieldBinding`: a `Path<T>[]`
+  compared with `pathsEqual`, fed by `onBlur`, visible in the Debugger
+  snapshot. Commit-style elements (selects) call `onBlur` on commit — the
+  commit IS their blur moment.
+- **THE error-display policy** lives inside `errorMessage` and nowhere
+  else: show a field's error once the field is touched OR a submit has been
+  attempted. Elements render what they're given and stay policy-free. A UI
+  wanting a different policy (e.g. always-live) reads `errors`/`errorAt`
+  directly.
+
+### The element wrappers (`state/bindings/`)
+
+The **wrapper style** is the prototyped shorthand (per the plan's deciding
+criterion — simplest for agents to work with): `TextInputForForm` and
+`SingleSelectForForm` compose `Field` (label/hint/error presentation)
+around the element and accept the bundle as one `formFieldProps` prop.
+The wrapper declares what it can display and emit via
+`FieldBinding<Display, Emit>` — e.g. the text input takes
+`FieldBinding<string | null | undefined, string>` — and a
+`FormFieldProps<V>` is assignable exactly when `Emit ⊆ V ⊆ Display`. That
+one structural check is the end-to-end type safety: binding a number- or
+boolean-typed path (or a literal-union field, for free text) to a
+text-shaped element fails to compile at the `formFieldProps` prop, with no
+generics at the use site.
 
 ## Union policy — what form state may hold
 
@@ -309,10 +373,11 @@ precision end-to-end. So we wire it up before adding any consumers.
 
 - `state/useFormState/` — the hook + the value-model types (`FormValueSimple`,
   `FormValuesObject`, `FormValueList`). Hook surface: `{ values,
-  onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`.
+  onValueChanges, errors, isValid, submitAttempted, submit,
+  getFormFieldPropsAt, 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
+  values `useState` (a bare `useState`; the granular path writes layer on
+  top of its setter via `useFieldBinding`), 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:
@@ -330,6 +395,12 @@ precision end-to-end. So we wire it up before adding any consumers.
     the correlation. It also hosts the cast-free `FlatConstraintEntry`
     assignment that polices grammar growth (see the `state/validations/` bullet).
   - `errorAt.ts` — the typed error lookup.
+  - `useFieldBinding.ts` — field binding: owns the touched list and builds
+    `getFormFieldPropsAt` (see "Field binding" above — the error-display
+    policy lives here). Two documented honest casts correlate `read()`/
+    `write()` results with `ValueAt<T, P>`/`T` for generic `T`; both are
+    truths the runtime upholds by construction, same family as `errorAt`'s
+    path widening.
   - `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
@@ -348,9 +419,11 @@ precision end-to-end. So we wire it up before adding any consumers.
     subscribes (`useSyncExternalStore`), so an unused Debugger costs
     ~nothing. `inspectable.ts` converts arrays/Sets to shapes `JsonTable`
     can render.
-- `state/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.
+- `state/path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`,
+  `read()`), plus `write()` (the immutable-update mirror of `read()` behind
+  granular field writes) and `pathsEqual` (the one definition of structural
+  path equality — `errorAt` and touched tracking both use it). Coupled to
+  the form value model intentionally.
   Union handling is governed by the "Union policy" section above; the
   policy's type-level guts (`IsDisallowedFormUnion`, `UnionPolicyCheck`,
   `DisallowedFormUnion`) live with the value model in `state/useFormState/types.ts`.
@@ -367,6 +440,9 @@ precision end-to-end. So we wire it up before adding any consumers.
   function). Keep it cast-free. The one widening cast inside `validateEntry`
   mirrors `allOf`'s part-call: honest contravariant widening of a single,
   already-normalized validator.
+- `state/bindings/` — the form-aware element wrappers (`TextInputForForm`,
+  `SingleSelectForForm`), the second sanctioned state→elements bridge (see
+  "Field binding" above). Element imports go through the element barrels.
 - `state/validators/` — the standard-library validators (`notEmpty`, `minLength`,
   `matches`, `min`) plus `allOf`, which composes validators on one field and
   carries the union of the parts' refinements. `allOf` derives its input type

package/src/forms/elements/Input/index.tsx

@@ -14,6 +14,7 @@ export const Input = (props: InputProps) => {
     value,
     defaultValue,
     onChange,
+    onBlur,
     placeholder,
     required,
     autoFocus,
@@ -29,6 +30,7 @@ export const Input = (props: InputProps) => {
       value={value}
       defaultValue={defaultValue}
       onChange={onChange}
+      onBlur={onBlur}
       placeholder={placeholder}
       required={required}
       autoFocus={autoFocus}

package/src/forms/elements/Input/types.ts

@@ -1,4 +1,4 @@
-import type { ChangeEventHandler } from 'react';
+import type { ChangeEventHandler, FocusEventHandler } from 'react';
 
 export type InputSize = 'small' | 'medium';
 export type InputType = 'text' | 'email' | 'password';
@@ -9,6 +9,7 @@ export type InputProps = {
   value?: string;
   defaultValue?: string;
   onChange?: ChangeEventHandler<HTMLInputElement>;
+  onBlur?: FocusEventHandler<HTMLInputElement>;
   placeholder?: string;
   required?: boolean;
   autoFocus?: boolean;

package/src/forms/plan.md

@@ -34,9 +34,15 @@ TS wall can't strand finished work behind it.
    `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. ← *current*
-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.
 
@@ -187,6 +193,13 @@ 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)
 
@@ -275,7 +288,29 @@ Blast radius that was handled when this landed:
   Debugger is a designated bridge layer). Explicitly allowed for in the new
   boundaries rules.
 
-## 6. Field binding: `getFormFieldPropsAt(path)` + element shorthands
+## 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
@@ -427,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/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

@@ -22,6 +22,15 @@ const makeCursor = <T>(steps: readonly CursorStep[]): Cursor<T> => ({
 
 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
@@ -51,3 +60,44 @@ export const read = (root: unknown, steps: readonly CursorStep[]): unknown => {
 
   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/state/useFormState/FormDebugger.tsx

@@ -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/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/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.

package/src/forms/state/useFormState/useFieldBinding.test.tsx

@@ -0,0 +1,165 @@
+import { describe, test, expect } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFieldBinding } from './useFieldBinding';
+import { useFormState } from './useFormState';
+import { notEmpty } from '../validators/validators';
+
+// Field binding exercised through useFormState — the composition consumers
+// see. Pins the three behaviors item 6 added: granular path writes (the
+// immutable mirror of read()), touched tracking fed by onBlur, and the
+// error-display policy living inside errorMessage.
+
+type Address = { city: string | undefined; zip: string | undefined };
+
+type ProfileForm = {
+  email: string | undefined;
+  homeAddress: Address;
+  mailingAddress: Address | undefined;
+  pets: Array<{ name: string | undefined }>;
+};
+
+const initialValues: ProfileForm = {
+  email: undefined,
+  homeAddress: { city: undefined, zip: undefined },
+  mailingAddress: undefined,
+  pets: [{ name: 'Rex' }, { name: 'Milou' }],
+};
+
+const setup = () =>
+  renderHook(() =>
+    useFormState({
+      initialValues,
+      constraints: { email: notEmpty('email') },
+    }),
+  );
+
+describe('getFormFieldPropsAt — value and writes', () => {
+  test('reads the value at a deep path', () => {
+    const { result } = setup();
+    expect(result.current.getFormFieldPropsAt(['pets', 0, 'name']).value).toBe(
+      'Rex',
+    );
+    expect(
+      result.current.getFormFieldPropsAt(['homeAddress', 'city']).value,
+    ).toBeUndefined();
+  });
+
+  test('a path through an absent section reads undefined and writes as a no-op', () => {
+    const { result } = setup();
+    const field = result.current.getFormFieldPropsAt(['mailingAddress', 'city']);
+    expect(field.value).toBeUndefined();
+
+    act(() => {
+      field.onChange('Paris');
+    });
+    // The write mirrored read()'s dead-step semantics: nothing changed.
+    expect(result.current.values).toBe(initialValues);
+  });
+
+  test('onChange writes at the path immutably, preserving sibling identity', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['homeAddress', 'city']).onChange('Paris');
+    });
+
+    expect(result.current.values.homeAddress.city).toBe('Paris');
+    // Untouched branches keep their identity — only the spine was cloned.
+    expect(result.current.values.pets).toBe(initialValues.pets);
+    expect(result.current.values).not.toBe(initialValues);
+    expect(initialValues.homeAddress.city).toBeUndefined();
+  });
+
+  test('onChange into a list element rewrites only that element', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['pets', 1, 'name']).onChange('Snowy');
+    });
+
+    expect(result.current.values.pets[1].name).toBe('Snowy');
+    expect(result.current.values.pets[0]).toBe(initialValues.pets[0]);
+  });
+});
+
+describe('getFormFieldPropsAt — error-display policy', () => {
+  test('an untouched field shows no error before a submit attempt', () => {
+    const { result } = setup();
+    // The error exists in the raw list …
+    expect(result.current.errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+    ]);
+    // … but the binding withholds it until touched or submit-attempted.
+    expect(
+      result.current.getFormFieldPropsAt(['email']).errorMessage,
+    ).toBeUndefined();
+  });
+
+  test('onBlur marks the field touched and unlocks its error — only its own', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onBlur();
+    });
+
+    expect(result.current.getFormFieldPropsAt(['email']).errorMessage).toBe(
+      "'email' cannot be empty",
+    );
+    // Another field stays untouched: same policy, independent state.
+    expect(
+      result.current.getFormFieldPropsAt(['homeAddress', 'city']).errorMessage,
+    ).toBeUndefined();
+  });
+
+  test('a submit attempt unlocks every field’s error', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.submit();
+    });
+
+    expect(result.current.getFormFieldPropsAt(['email']).errorMessage).toBe(
+      "'email' cannot be empty",
+    );
+  });
+
+  test('a touched field’s error clears once the value is fixed', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onBlur();
+    });
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onChange('a@b.co');
+    });
+
+    expect(
+      result.current.getFormFieldPropsAt(['email']).errorMessage,
+    ).toBeUndefined();
+  });
+
+  test('repeat blurs on the same path keep the touched list stable', () => {
+    // At the useFieldBinding boundary, where the touched list is returned.
+    const { result } = renderHook(() =>
+      useFieldBinding({
+        values: initialValues,
+        onValueChanges: () => {},
+        errors: [],
+        submitAttempted: false,
+      }),
+    );
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onBlur();
+    });
+    const touchedAfterFirst = result.current.touched;
+    expect(touchedAfterFirst).toEqual([['email']]);
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onBlur();
+    });
+    // Re-blurring an already-touched path is a state no-op — the setter
+    // returns the same array, so nothing downstream sees a change.
+    expect(result.current.touched).toBe(touchedAfterFirst);
+  });
+});

package/src/forms/state/useFormState/useFieldBinding.ts

@@ -0,0 +1,71 @@
+import { useState } from 'react';
+import { errorAt } from './errorAt';
+import type { FormErrors, FormFieldProps, FormValuesObject } from './types';
+import { pathsEqual, read, write } from '../path/path';
+import type { CursorStep, Path, PathStep, ValueAt } from '../path/types';
+
+export type UseFieldBindingArgs<T extends FormValuesObject> = {
+  values: T;
+  onValueChanges: (val: T | ((prev: T) => T)) => void;
+  errors: FormErrors<T>;
+  submitAttempted: boolean;
+};
+
+// Field binding: owns per-field touched state and builds
+// `getFormFieldPropsAt`, the one-expression wiring for a field (see
+// FormHelpers in ./types.ts).
+//
+// THE error-display policy lives here, in `errorMessage`, and nowhere else:
+// a field's error is shown once the field has been touched (blurred at
+// least once) OR a submit has been attempted. Elements render the message
+// they are given and stay policy-free; anything wanting a different policy
+// (e.g. always-live display) reads `errors`/`errorAt` directly instead.
+export const useFieldBinding = <T extends FormValuesObject>(
+  args: UseFieldBindingArgs<T>,
+) => {
+  const { values, onValueChanges, errors, submitAttempted } = args;
+
+  // Same representation as FormErrors: a plain list of typed paths compared
+  // structurally (pathsEqual). At form scale a linear scan is fine.
+  const [touched, setTouched] = useState<readonly Path<T>[]>([]);
+
+  const getFormFieldPropsAt = <P extends Path<T>>(
+    path: P,
+  ): FormFieldProps<ValueAt<T, P>> => {
+    // Path<T> is always a PathStep tuple; the conditional type just can't
+    // prove it for an unresolved T. Same honest widening as `Cursor.at`.
+    const steps = path as readonly PathStep[];
+    const keySteps: readonly CursorStep[] = steps.map((key) => ({
+      kind: 'key',
+      key,
+    }));
+
+    const isTouched = touched.some((candidate) =>
+      pathsEqual(candidate as readonly PathStep[], steps),
+    );
+
+    return {
+      // read() resolves exactly what ValueAt<T, P> promises — including the
+      // `| undefined` picked up through nullable ancestors — TS just can't
+      // correlate them for generic T. Honest cast, documented in the cast
+      // doctrine (src/forms/CLAUDE.md).
+      value: read(values, keySteps) as ValueAt<T, P>,
+      // write() replaces the value at the path and clones only the spine —
+      // the result is the same T shape. Same honest correlation as `value`.
+      onChange: (val) =>
+        onValueChanges((prev) => write(prev, steps, val) as T),
+      errorMessage:
+        submitAttempted || isTouched ? errorAt(errors, path) : undefined,
+      onBlur: () =>
+        setTouched((prev) =>
+          prev.some((candidate) =>
+            pathsEqual(candidate as readonly PathStep[], steps),
+          )
+            ? prev
+            : [...prev, path],
+        ),
+    };
+  };
+
+  return { touched, getFormFieldPropsAt };
+};

package/src/forms/state/useFormState/useFormDebugger.test.tsx

@@ -21,6 +21,7 @@ const Host = () => {
       errors: [],
       isValid: true,
       submitAttempted: false,
+      touched: [],
     },
   });
 

package/src/forms/state/useFormState/useFormState.stories.tsx

@@ -9,6 +9,9 @@ import { Field } from '../../elements/Field';
 import { Input } from '../../elements/Input';
 import { Button } from '../../elements/Button';
 import { SingleSelect } from '../../elements/Select';
+import type { SelectOption } from '../../elements/Select';
+import { SingleSelectForForm } from '../bindings/SingleSelectForForm';
+import { TextInputForForm } from '../bindings/TextInputForForm';
 
 const meta: Meta = {
   title: 'Forms/useFormState',
@@ -43,6 +46,10 @@ const ROLE_OPTIONS = [
   { value: 'manager', label: 'Manager' },
 ];
 
+// Deliberately hand-wired — the contrast case for the FieldBinding story
+// below: every field spells out its own read, spread-update, error lookup,
+// and submit gating. `getFormFieldPropsAt` + the ForForm wrappers collapse
+// those four decisions into one expression per field.
 const SignupDemo = () => {
   const [submitted, setSubmitted] = useState<SubmittedValues | null>(null);
 
@@ -259,6 +266,162 @@ export const LiveValidity: Story = {
   },
 };
 
+type CoverageType = 'liability' | 'comprehensive';
+
+type QuoteFormValues = {
+  email: string | undefined;
+  coverageType: CoverageType | null;
+  homeAddress: {
+    city: string | undefined;
+    postalCode: string | undefined;
+  };
+};
+
+// What onSubmit receives: notEmpty strips undefined from email and null
+// from coverageType. The setSubmitted(vals) call below compiling is the
+// proof that refinement still flows end-to-end when fields are wired
+// through bindings.
+type SubmittedQuote = {
+  email: string;
+  coverageType: CoverageType;
+  homeAddress: QuoteFormValues['homeAddress'];
+};
+
+const COVERAGE_OPTIONS: SelectOption<CoverageType>[] = [
+  { value: 'liability', label: 'Liability' },
+  { value: 'comprehensive', label: 'Comprehensive' },
+];
+
+// The item-6 target: one expression wires a field. getFormFieldPropsAt
+// bundles value + typed onChange (an immutable write at the path) +
+// display-policy-aware errorMessage + onBlur, and the ForForm wrappers
+// take the bundle as a single prop. Note the deep paths into homeAddress —
+// no hand-spread updates anywhere.
+const FieldBindingDemo = () => {
+  const [submitted, setSubmitted] = useState<SubmittedQuote | null>(null);
+
+  const { getFormFieldPropsAt, submit } = useFormState({
+    initialValues: {
+      email: undefined,
+      coverageType: null,
+      homeAddress: { city: undefined, postalCode: undefined },
+    } as QuoteFormValues,
+    constraints: {
+      email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+      coverageType: notEmpty('coverageType'),
+    },
+    onSubmit: (vals) => setSubmitted(vals),
+  });
+
+  return (
+    <form
+      style={{ maxWidth: 420, display: 'grid', gap: 16 }}
+      onSubmit={(e) => {
+        e.preventDefault();
+        submit();
+      }}
+    >
+      <TextInputForForm
+        label="Email"
+        type="email"
+        placeholder="you@example.com"
+        hint="Blur the empty field to see touched-gated errors"
+        formFieldProps={getFormFieldPropsAt(['email'])}
+      />
+
+      <SingleSelectForForm
+        label="Coverage"
+        options={COVERAGE_OPTIONS}
+        placeholder="Pick a coverage"
+        formFieldProps={getFormFieldPropsAt(['coverageType'])}
+      />
+
+      <TextInputForForm
+        label="City"
+        formFieldProps={getFormFieldPropsAt(['homeAddress', 'city'])}
+      />
+
+      <TextInputForForm
+        label="Postal code"
+        formFieldProps={getFormFieldPropsAt(['homeAddress', 'postalCode'])}
+      />
+
+      <div>
+        <Button type="submit" variant="primary">
+          Get quote
+        </Button>
+      </div>
+
+      {submitted && (
+        <pre
+          style={{
+            background: 'var(--ui-surface-muted, #f4f4f4)',
+            padding: 12,
+            borderRadius: 6,
+            fontSize: 12,
+            margin: 0,
+          }}
+        >
+          {`onSubmit received (narrowed type):\n${JSON.stringify(submitted, null, 2)}`}
+        </pre>
+      )}
+    </form>
+  );
+};
+
+export const FieldBinding: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <FieldBindingDemo />
+    </div>
+  ),
+  // Walks the binding flow: touched/blur gating of errorMessage (before any
+  // submit attempt), deep-path writes through the wrappers, submit-attempt
+  // gating for untouched fields, and the narrowed payload reaching onSubmit.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(canvasElement.ownerDocument.body);
+
+    // Nothing shown initially: the email error exists in the raw list, but
+    // errorMessage withholds it until the field is touched.
+    await expect(
+      canvas.queryByText("'email' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // Blurring the empty email field marks it touched — its error appears
+    // without any submit attempt, and only its own.
+    await userEvent.click(canvas.getByLabelText(/^Email/));
+    await userEvent.tab();
+    await expect(canvas.getByText("'email' cannot be empty")).toBeInTheDocument();
+    await expect(
+      canvas.queryByText("'coverageType' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // Deep-path writes flow through the wrapper onChange.
+    await userEvent.type(canvas.getByLabelText(/^City/), 'Lyon');
+    await expect(canvas.getByLabelText(/^City/)).toHaveValue('Lyon');
+
+    // A submit attempt unlocks the untouched coverage field's error too.
+    await userEvent.click(canvas.getByRole('button', { name: 'Get quote' }));
+    await expect(
+      canvas.getByText("'coverageType' cannot be empty"),
+    ).toBeInTheDocument();
+
+    // Fix both fields; committing a select option counts as its touch.
+    await userEvent.type(canvas.getByLabelText(/^Email/), 'will@example.com');
+    await userEvent.click(canvas.getByRole('button', { name: 'Coverage' }));
+    // The option list is portaled — query the document, not the canvas.
+    await userEvent.click(await body.findByRole('option', { name: 'Liability' }));
+    await expect(
+      canvas.queryByText("'coverageType' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // Valid submit delivers the narrowed payload.
+    await userEvent.click(canvas.getByRole('button', { name: 'Get quote' }));
+    await expect(canvas.getByText(/onSubmit received/)).toBeInTheDocument();
+  },
+};
+
 type DebuggerDemoValues = {
   email: string | undefined;
   nickname: string | undefined;

package/src/forms/state/useFormState/useFormState.test-d.ts

@@ -2,9 +2,11 @@ import { describe, it, expectTypeOf } from 'vitest';
 import { useFormState } from './useFormState';
 import { errorAt } from './errorAt';
 import { allOf, matches, min, minLength, notEmpty } from '../validators/validators';
-import type { FormErrors } from './types';
+import type { FormErrors, FormFieldProps } from './types';
 import type { Refine, Validations } from '../validations/types';
 import type { Path, ValueAt } from '../path/types';
+import type { TextInputForFormProps } from '../bindings/TextInputForForm';
+import type { SingleSelectForFormProps } from '../bindings/SingleSelectForForm';
 
 // These tests exercise the headline feature end-to-end at the hook boundary:
 // the type `onSubmit` receives must be the *refined* form type. The two
@@ -425,6 +427,83 @@ describe('useFormState narrowing at realistic scale', () => {
     errorAt(errors, ['email', 'domain']);
   });
 
+  it('getFormFieldPropsAt infers FormFieldProps<ValueAt> at deep paths, inline at the call site', () => {
+    const form = useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: { email: notEmpty('email') },
+    });
+
+    // Flat and deep paths: value/onChange typed by ValueAt<T, P>.
+    expectTypeOf(form.getFormFieldPropsAt(['email'])).toEqualTypeOf<
+      FormFieldProps<string | undefined>
+    >();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['homeAddress', 'city']),
+    ).toEqualTypeOf<FormFieldProps<string | undefined>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['drivers', 0, 'incidents', 1, 'claimAmountUsd']),
+    ).toEqualTypeOf<FormFieldProps<number | null>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['vehicles', 0, 'garagingAddress', 'postalCode']),
+    ).toEqualTypeOf<FormFieldProps<string | undefined>>();
+
+    // Nullable-object semantics (PR #17) flow through the binding: stepping
+    // through a dead ancestor adds `| undefined`, stopping AT a nullable
+    // field keeps its exact type.
+    expectTypeOf(
+      form.getFormFieldPropsAt(['coApplicant', 'sharesResidence']),
+    ).toEqualTypeOf<FormFieldProps<boolean | undefined>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['pastPolicies', 0, 'activeUntil']),
+    ).toEqualTypeOf<FormFieldProps<string | null | undefined>>();
+    expectTypeOf(form.getFormFieldPropsAt(['employer'])).toEqualTypeOf<
+      FormFieldProps<string | null>
+    >();
+
+    // Only Path<T> is admitted.
+    // @ts-expect-error 'emial' is not a field of the form
+    form.getFormFieldPropsAt(['emial']);
+    // @ts-expect-error no paths exist below a scalar leaf
+    form.getFormFieldPropsAt(['email', 'domain']);
+  });
+
+  it('element wrappers accept only shape-compatible bindings', () => {
+    const form = useFormState({ initialValues: {} as InsuranceQuoteForm });
+
+    type TextBinding = TextInputForFormProps['formFieldProps'];
+
+    // Text-shaped fields bind: V must sit between the wrapper's emit type
+    // (string) and display type (string | null | undefined).
+    expectTypeOf(
+      form.getFormFieldPropsAt(['homeAddress', 'city']),
+    ).toMatchTypeOf<TextBinding>();
+    expectTypeOf(form.getFormFieldPropsAt(['employer'])).toMatchTypeOf<TextBinding>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['pastPolicies', 0, 'activeUntil']),
+    ).toMatchTypeOf<TextBinding>();
+
+    // Wrong-shaped bindings fail at the formFieldProps prop.
+    // @ts-expect-error a number-typed path cannot bind to a text element
+    const numberIntoText: TextBinding = form.getFormFieldPropsAt(['deductibleUsd']);
+    // @ts-expect-error a boolean-typed path cannot bind to a text element
+    const booleanIntoText: TextBinding = form.getFormFieldPropsAt(['agreedToTerms']);
+
+    // The select wrapper lines its options' literal union up with the field:
+    // emitting a wider type than the field holds is rejected.
+    type CoverageBinding = SingleSelectForFormProps<
+      'liability' | 'comprehensive'
+    >['formFieldProps'];
+    expectTypeOf<
+      FormFieldProps<'liability' | 'comprehensive' | undefined>
+    >().toMatchTypeOf<CoverageBinding>();
+    // @ts-expect-error a plain-string field would accept values outside the options
+    const stringIntoSelect: CoverageBinding = form.getFormFieldPropsAt(['coverageType']);
+
+    void numberIntoText;
+    void booleanIntoText;
+    void stringIntoSelect;
+  });
+
   it('paths through optional sections and nullable lists resolve, at scale', () => {
     // The latent hole this pins: Path admitted these paths all along, but
     // ValueAt resolved them to `never` because `keyof (Obj | undefined)` is

package/src/forms/state/useFormState/useFormState.ts

@@ -5,6 +5,7 @@ import type {
   FormValuesObject,
   UnionPolicyCheck,
 } from './types';
+import { useFieldBinding } from './useFieldBinding';
 import { useFormDebugger } from './useFormDebugger';
 import { useFormSubmit } from './useFormSubmit';
 import type { Refine, Validations } from '../validations/types';
@@ -30,8 +31,8 @@ type Args<T extends FormValuesObject, V extends Validations<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.
+// kept inline — a bare `useState`; the granular path writes layer on top of
+// its setter (`useFieldBinding` funnels `write()` results through it).
 export const useFormState = <
   T extends FormValuesObject,
   const V extends Validations<T> = Validations<T>,
@@ -53,8 +54,15 @@ export const useFormState = <
     onSubmit,
   });
 
+  const { touched, getFormFieldPropsAt } = useFieldBinding({
+    values,
+    onValueChanges,
+    errors,
+    submitAttempted,
+  });
+
   const Debugger = useFormDebugger({
-    snapshot: { values, errors, isValid, submitAttempted },
+    snapshot: { values, errors, isValid, submitAttempted, touched },
   });
 
   return {
@@ -64,6 +72,7 @@ export const useFormState = <
     isValid,
     submitAttempted,
     submit,
+    getFormFieldPropsAt,
     Debugger,
   };
 };