@structuralists/scaffolding 0.10.0 → 0.10.2

package/eslint.config.mjs

@@ -7,8 +7,11 @@ import tsParser from '@typescript-eslint/parser';
 // Component primitives live under src/components/<Section>/<Component>/.
 // "Umbrella sections" (Modals, Chat) are themselves the primitive — their
 // sub-folders share internals and must be reached through the section barrel.
-// Plain sections (Layout, Content, Forms, ...) treat each component folder as
-// its own primitive.
+// Plain sections (Layout, Content, ...) treat each component folder as its
+// own primitive. Form elements live under src/forms/elements/<Component>/ and
+// follow the same per-folder primitive shape; the form-state layer
+// (src/forms/state/) is one element with no barrel — its modules import each
+// other file-directly.
 //
 // Three element types so rules can distinguish roles inside a primitive:
 //   - primitive-entry   → the barrel (`<primitive>/index.{ts,tsx}`)
@@ -33,6 +36,34 @@ export default [{
     },
     'boundaries/include': ['src/**/*'],
     'boundaries/elements': [
+      // Form-element primitives (src/forms/elements/<Component>/) — same
+      // shape and rules as plain-section component primitives.
+      {
+        type: 'primitive-entry',
+        pattern: 'src/forms/elements/*/index.{ts,tsx}',
+        mode: 'full',
+        capture: ['name'],
+      },
+      {
+        type: 'primitive-dogfood',
+        pattern: 'src/forms/elements/*/**/*.{stories,test}.{ts,tsx}',
+        mode: 'full',
+        capture: ['name'],
+      },
+      {
+        type: 'primitive',
+        pattern: 'src/forms/elements/*',
+        mode: 'folder',
+        capture: ['name'],
+      },
+      // The form-state layer, as a single element. No barrel: its modules
+      // (useFormState, validations, validators, path) import each other
+      // file-directly by design.
+      {
+        type: 'forms-state',
+        pattern: 'src/forms/state',
+        mode: 'folder',
+      },
       // Plain-section component primitives (depth-3 under src/components)
       {
         type: 'primitive-entry',
@@ -100,6 +131,29 @@ export default [{
             message:
               "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
+          // 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.
+          {
+            from: [
+              { type: 'primitive' },
+              { type: 'primitive-entry' },
+              { type: 'primitive-dogfood' },
+            ],
+            disallow: [{ to: { type: 'forms-state' } }],
+            message:
+              'Form elements and components must not import the form-state layer; the bridge layer lives on the state side.',
+          },
+          // When state files import a component/element primitive (the
+          // sanctioned bridge direction), they go through its barrel like
+          // any other external importer.
+          {
+            from: [{ type: 'forms-state' }],
+            disallow: [{ to: { type: 'primitive' } }],
+            message: "External imports must go through the folder's index barrel.",
+          },
         ],
       },
     ],

package/package.json

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

package/src/components/Chat/ChatRecipientsHeader/ChatRecipientsHeader.stories.tsx

@@ -3,10 +3,10 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { ChatRecipientsHeader } from './index';
 import type { PillComboboxOption } from '../PillCombobox/types';
 import { Stack } from '../../Layout/Stack';
-import { Textarea } from '../../Forms/Textarea';
-import { Input } from '../../Forms/Input';
-import { Field } from '../../Forms/Field';
-import { Button } from '../../Forms/Button';
+import { Textarea } from '../../../forms/elements/Textarea';
+import { Input } from '../../../forms/elements/Input';
+import { Field } from '../../../forms/elements/Field';
+import { Button } from '../../../forms/elements/Button';
 import { MediumModal } from '../../Modals';
 import { Toggle } from '../../../storybook';
 

package/src/components/Layout/Bar/Bar.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Bar } from './index';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 import { Debug } from '../Debug';
 
 const meta: Meta<typeof Bar> = {

package/src/components/Layout/Panels/Panels.stories.tsx

@@ -2,7 +2,7 @@ import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Panels } from './index';
 import { Bar } from '../Bar';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 import { Text } from '../../Content/Text';
 import { Heading } from '../../Content/Heading';
 import { Stack } from '../Stack';

package/src/components/Layout/Stack/Stack.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Stack } from './index';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 
 const meta: Meta<typeof Stack> = {
   title: 'Layout/Stack',

package/src/components/Modals/LargeModal/LargeModal.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { LargeModal } from './index';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 import { Stack } from '../../Layout/Stack';
 import { Text } from '../../Content/Text';
 import { Lorem, Toggle } from '../../../storybook';

package/src/components/Modals/MediumModal/MediumModal.stories.tsx

@@ -1,8 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { MediumModal } from './index';
-import { Button } from '../../Forms/Button';
-import { Field } from '../../Forms/Field';
-import { Input } from '../../Forms/Input';
+import { Button } from '../../../forms/elements/Button';
+import { Field } from '../../../forms/elements/Field';
+import { Input } from '../../../forms/elements/Input';
 import { Stack } from '../../Layout/Stack';
 import { Text } from '../../Content/Text';
 import { Lorem, Toggle } from '../../../storybook';

package/src/components/Modals/internal/ModalHeader.tsx

@@ -1,4 +1,4 @@
-import { IconButton } from '../../Forms/IconButton';
+import { IconButton } from '../../../forms/elements/IconButton';
 import styles from './styles.module.css';
 
 type Props = {

package/src/components/Overlays/Popover/Popover.stories.tsx

@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useRef, useState } from 'react';
 import { Popover } from './index';
-import { Button } from '../../Forms/Button';
-import { Input } from '../../Forms/Input';
-import { Field } from '../../Forms/Field';
+import { Button } from '../../../forms/elements/Button';
+import { Input } from '../../../forms/elements/Input';
+import { Field } from '../../../forms/elements/Field';
 import { Text } from '../../Content/Text';
 const meta: Meta<typeof Popover> = {
   title: 'Overlays/Popover',

package/src/components/Overlays/Tooltip/Tooltip.stories.tsx

@@ -1,7 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Tooltip } from './index';
 import type { TooltipPlacement } from './types';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 
 const meta: Meta<typeof Tooltip> = {
   title: 'Overlays/Tooltip',

package/src/components/Tables/BigTable/BigTable.stories.tsx

@@ -17,7 +17,7 @@ import { LinedStack } from '../../Primitives/LinedStack';
 import { LongText } from '../../Primitives/LongText';
 import { Panels } from '../../Layout/Panels';
 import { Bar } from '../../Layout/Bar';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 import { Heading } from '../../Content/Heading';
 import { Stack } from '../../Layout/Stack';
 

package/src/forms/CLAUDE.md

@@ -1,9 +1,24 @@
 # src/forms
 
-Strongly-typed React form state hook. The headline feature is **validation that
-propagates type refinements to the submit handler** — passing the right
-constraints means the submit handler's `values` argument has a tighter type
-than the initial form values.
+The forms umbrella, split into two named subtrees:
+
+- `elements/` — the presentational form elements (`Input`, `Field`, `Select`,
+  `Button`, `Textarea`, …), one component primitive per folder, same shape
+  and eslint-boundaries rules as `src/components/<Section>/<Component>/`.
+  Elements are state-free: they must not import the state layer (enforced by
+  eslint `boundaries`).
+- `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.
+
+The headline feature of the state layer is **validation that propagates type
+refinements to the submit handler** — passing the right constraints means the
+submit handler's `values` argument has a tighter type than the initial form
+values.
 
 ## Mental model
 
@@ -185,7 +200,7 @@ exposed:
 errorAt(errors, ['email']); // string | undefined
 ```
 
-`errorAt` (useFormState/errorAt.ts) matches by exact structural step
+`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
@@ -222,7 +237,7 @@ in three layers:
 1. **At the `useFormState` boundary**: an illegal form type makes the call
    fail with an unsatisfiable `'ERROR: form state disallows unions of
    objects/lists …'` property whose type names the offending keys
-   (`UnionPolicyCheck<T>` in `useFormState/types.ts`).
+   (`UnionPolicyCheck<T>` in `state/useFormState/types.ts`).
 2. **`Path<T>` refuses to descend** into a disallowed union — the field
    stays addressable as a leaf (reading it yields the union, which is
    honest), but no paths below it exist, so `.at(…)`/path literals into it
@@ -292,46 +307,67 @@ precision end-to-end. So we wire it up before adding any consumers.
 
 ## Layout
 
-- `useFormState/` — the hook + the value-model types (`FormValueSimple`,
+- `state/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.
-- `path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`, `read()`).
+  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 `state/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 `state/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.
+- `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.
   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 `useFormState/types.ts`.
-- `validations/` — `perField`, `Validations<T>` / `FieldConstraint<F>`,
+  `DisallowedFormUnion`) live with the value model in `state/useFormState/types.ts`.
+- `state/validations/` — `perField`, `Validations<T>` / `FieldConstraint<F>`,
   `Refine<T,V>`, `Refinement<>` infra, plus `walk.ts`, the runtime walk the
   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 `state/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
   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.
-- `validators/` — the standard-library validators (`notEmpty`, `minLength`,
+- `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
   as the intersection of the parts' inputs from the const tuple (not a

package/src/{components/Forms → forms/elements}/Button/Button.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Button } from './index';
-import { Stack } from '../../Layout/Stack';
+import { Stack } from '../../../components/Layout/Stack';
 
 const meta: Meta<typeof Button> = {
   title: 'Forms/Button',

package/src/{components/Forms → forms/elements}/IconButton/index.tsx

@@ -1,5 +1,5 @@
 import { cx } from '../../../utils';
-import { Tooltip } from '../../Overlays/Tooltip';
+import { Tooltip } from '../../../components/Overlays/Tooltip';
 import type {
   IconButtonProps,
   IconButtonSize,

package/src/{components/Forms → forms/elements}/Select/MultiSelect/MultiSelect.stories.tsx

@@ -2,8 +2,8 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
 import { MultiSelect } from './index';
 import { Field } from '../../Field';
-import { Stack } from '../../../Layout/Stack';
-import { Text } from '../../../Content/Text';
+import { Stack } from '../../../../components/Layout/Stack';
+import { Text } from '../../../../components/Content/Text';
 
 const meta: Meta<typeof MultiSelect> = {
   title: 'Forms/MultiSelect',

package/src/{components/Forms → forms/elements}/Select/MultiSelect/index.tsx

@@ -1,5 +1,5 @@
 import { useRef, useState } from 'react';
-import { Popover } from '../../../Overlays/Popover';
+import { Popover } from '../../../../components/Overlays/Popover';
 import { OptionList } from '../internal/OptionList';
 import { SelectTrigger } from '../internal/SelectTrigger';
 import type { MultiSelectProps } from './types';

package/src/{components/Forms → forms/elements}/Select/SingleSelect/SingleSelect.stories.tsx

@@ -3,9 +3,9 @@ import { useState } from 'react';
 import { SingleSelect } from './index';
 import { Button } from '../../Button';
 import { Field } from '../../Field';
-import { MediumModal } from '../../../Modals';
-import { Stack } from '../../../Layout/Stack';
-import { Text } from '../../../Content/Text';
+import { MediumModal } from '../../../../components/Modals';
+import { Stack } from '../../../../components/Layout/Stack';
+import { Text } from '../../../../components/Content/Text';
 import { Toggle } from '../../../../storybook';
 
 const meta: Meta<typeof SingleSelect> = {

package/src/{components/Forms → forms/elements}/Select/SingleSelect/index.tsx

@@ -1,5 +1,5 @@
 import { useRef, useState } from 'react';
-import { Popover } from '../../../Overlays/Popover';
+import { Popover } from '../../../../components/Overlays/Popover';
 import { OptionList } from '../internal/OptionList';
 import { SelectTrigger } from '../internal/SelectTrigger';
 import type { SingleSelectProps } from './types';

package/src/forms/plan.md

@@ -16,23 +16,25 @@ 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.
+   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*
    any runtime work; three outcomes (works / slow / intractable) each with a
@@ -123,7 +125,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
@@ -189,7 +191,7 @@ multi-second check time:
 ## 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 +201,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 +210,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 +230,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,30 +242,38 @@ 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.
+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
 
@@ -278,7 +288,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 +307,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

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';
@@ -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>(