@structuralists/scaffolding 0.5.1 → 0.6.1

package/.claude/skills/pr-screenshots/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: pr-screenshots
+description: Attach screenshots to a GitHub PR description by uploading them as prerelease assets and embedding their download URLs. Use when a PR would benefit from visual evidence (UI changes, Storybook stories, component work) or when asked to add images to a PR.
+---
+
+# Attach screenshots to a PR description
+
+GitHub has no public API for uploading images into PR descriptions — the web
+UI's drag-and-drop uses an internal endpoint (`/upload/policies/assets`) that
+requires browser session cookies. The working CLI technique is to host the
+images as **release assets on a throwaway prerelease** and embed their
+`browser_download_url` in the PR body.
+
+Origin: https://mareksuppa.com/til/github-pr-images-from-cli/ — first proven
+here on PR #14.
+
+## 1. Capture
+
+Use `chrome-devtools-axi` against the local Storybook (`bun run dev`, port
+6015):
+
+- **Resize first**: `chrome-devtools-axi resize 900 640` — the default
+  viewport is very tall and produces screenshots that are mostly empty space.
+- **Isolate the story**: open
+  `http://localhost:6015/iframe.html?id=<story-id>&viewMode=story` to skip
+  the Storybook chrome (sidebar, toolbar, addon panel).
+- Interact to reach the state worth showing (filled fields, open overlays,
+  visible errors) — a screenshot demonstrating *behavior* beats an idle one.
+- `chrome-devtools-axi screenshot <path>` — save to the session scratchpad,
+  not the repo.
+- **Read the PNGs back** (Read tool) to verify framing and content before
+  publishing. Retake rather than ship a shot with dead space or missing
+  state.
+
+## 2. Upload as prerelease assets
+
+```bash
+gh release create "pr-<N>-images" shot-1.png shot-2.png \
+  --title "PR #<N> screenshots" \
+  --notes "Image assets embedded in PR #<N>'s description. Not a software release — safe to delete after the PR merges." \
+  --prerelease
+```
+
+- `--prerelease` + a non-semver tag (`pr-<N>-images`) keep it out of the real
+  release stream and invisible to release automation.
+- Name files descriptively — the filename is how you select each asset's URL.
+
+## 3. Get URLs and embed
+
+```bash
+gh api "repos/<owner>/<repo>/releases/tags/pr-<N>-images" \
+  --jq '.assets[] | .name + " " + .browser_download_url'
+```
+
+Fetch the current body, append, and write back (don't clobber):
+
+```bash
+gh pr view <N> --json body --jq .body > /tmp/pr-body.md
+# append a "## Screenshots" section with ![descriptive alt](browser_download_url) images
+gh pr edit <N> --body-file /tmp/pr-body.md
+```
+
+Give each image real alt text and a one-line caption saying what state it
+shows. Add a footnote that the images live on the `pr-<N>-images` prerelease
+and are safe to delete after merge.
+
+## 4. Cleanup (after merge)
+
+```bash
+gh release delete "pr-<N>-images" --cleanup-tag --yes
+```
+
+## Private-repo caveat
+
+On a private repo, `browser_download_url` returns **404 to anonymous curl
+and to token-header curl** — that endpoint authenticates via browser
+session only. This is expected, not breakage: the images render for anyone
+viewing the PR logged in. To verify an asset exists from the CLI, download
+it through the API instead:
+
+```bash
+gh api -H "Accept: application/octet-stream" \
+  "repos/<owner>/<repo>/releases/assets/<asset-id>"
+```

package/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+# The same four checks the release job runs post-merge (publish.yml), but on
+# every PR — so merging green is enforced, and the release job's checks are a
+# formality rather than the first place a break surfaces.
+on:
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install --frozen-lockfile
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: playwright-${{ runner.os }}-
+
+      - name: Install Playwright chromium
+        run: npx playwright install chromium --with-deps
+
+      - run: bun run typecheck
+      - run: bun run lint
+      - run: bun run test
+      - run: bun run test:storybook

package/package.json

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

package/src/forms/CLAUDE.md

@@ -147,11 +147,19 @@ precision end-to-end. So we wire it up before adding any consumers.
 
 - `useFormState/` — the hook + the value-model types (`FormValueSimple`,
   `FormValuesObject`, `FormValueList`). Hook surface: `{ values,
-  onValueChanges, errors, isValid, submitAttempted, submit }`; `errors` is
-  live-derived from current values each render (validators are pure and
-  cheap), `submitAttempted` lets UIs gate error display, and `submit()`
-  performs the one honest cast to `Refine<T, V>` — earned because the
-  validators just passed at runtime.
+  onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`;
+  `errors` is live-derived from current values each render (validators are
+  pure and cheap), `submitAttempted` lets UIs gate error display, and
+  `submit()` performs the one honest cast to `Refine<T, V>` — earned because
+  the validators just passed at runtime. `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()`).
   Will be used for granular setters and for surfacing per-field
   errors/touched state. Coupled to the form value model intentionally.

package/src/forms/plan.md

@@ -1,8 +1,31 @@
 # Plan: composable, recursive `Validations`
 
-Status: **proposed** — nothing below is built yet. The baseline (flat
-`Validations<T>`, one validator per key, shallow `Refine`) is on
-`forms/useformstate-baseline`.
+Status: **in progress** — order of operations below. The baseline (flat
+`Validations<T>`, one validator per key, shallow `Refine`) is **merged to main**
+(PR #12, squashed; released as 0.5.0).
+
+## Order of operations
+
+The items were written unordered. The working order is **low-risk /
+low-coupling first**: each early item is independently mergeable and valuable
+even if the risky type work later stalls, and the risk zone comes last so a
+TS wall can't strand finished work behind it.
+
+1. **Item 7 — Debugger.** Zero type risk, valuable for developing everything
+   after it (watching nested state and structured errors live). ← *current*
+2. **Item 1 — validator arrays per key.** `ExcludedOf<C[number]>` already
+   proven inside `allOf`.
+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.
+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.
+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*
+   any runtime work; three outcomes (works / slow / intractable) each with a
+   known response. Worst case, everything above still shipped.
 
 ## Goal
 
@@ -15,13 +38,19 @@ Evolve `Validations<T>` so a constraints object can:
    (`Refinement` markers → `Refine<T, V>` → narrowed `onSubmit`) keeps
    working at every level.
 
-Plus two items that ride on top, independent of the type work:
+Plus four items that ride on top, independent of the type work:
 
 5. split the forms area into **'form elements'** and **'form state'**
    (see the section at the end),
 6. **field binding**: a `getFormFieldPropsAt(path)` helper plus
    form-element shorthands (`TextInputForForm` style) so wiring a field is
-   one expression (see the section at the end).
+   one expression (see the section at the end),
+7. **form `Debugger`**: a dev-time overlay component, returned from the
+   hook, that shows the form's live internal state (see the section at the
+   end),
+8. **per-field meta state**: visited/touched tracking and stable React key
+   generation, plus the open research question of keeping that meta state
+   in sync through array manipulation (see the section at the end).
 
 ## Target grammar
 
@@ -255,6 +284,104 @@ Placement note: these wrappers are the bridge between 'form elements' and
 'form state', so where they live should fall out of the split in item 5 —
 they are the one layer allowed to know about both sides.
 
+## 7. Form `Debugger` — dev-time state introspection
+
+A component for watching a form's internal state live while interacting with
+the form proper, in stories and during development. Two elements:
+
+- **Trigger** — small, `position: fixed`, floats above all content
+  (z-index above everything the library renders).
+- **Window** — opened by the trigger; shows a JSON-ish representation of the
+  form's internal state: `values`, `errors`, `isValid`, `submitAttempted`,
+  and whatever internal state lands later (touched map, etc.).
+  `JsonTable` is the obvious in-house renderer for this.
+
+### Hook plumbing
+
+Each `useFormState` instance binds its internal state to its own debugger
+and returns the component on the hook result:
+
+```tsx
+const { values, submit, Debugger, ... } = useFormState({ ... });
+
+return (
+  <>
+    <form>...</form>
+    <Debugger />   {/* dev/story usage; omit it and nothing renders */}
+  </>
+);
+```
+
+Mechanism sketch — a tiny event-emitter/subscription channel, so the
+form's own render tree never pays for the debugger:
+
+- The hook keeps a small store (current snapshot + subscriber set) in a ref
+  and publishes into it each render — publishing is a no-op when nobody
+  subscribes.
+- `Debugger` is created once per hook instance (stable identity across
+  renders — memoized, not redefined inline, or it remounts every keystroke)
+  and closes over that store. When mounted and open, it subscribes —
+  `useSyncExternalStore` is the natural fit — so state flows hook → store →
+  debugger without threading props or context.
+- Rendering the window is where the debugger pays its cost; a closed
+  trigger is ~free.
+
+### Open questions (for when this is picked up)
+
+- **Snapshot transport**: display-side needs stable snapshots (rendering
+  live mutable refs tears); likely publish a frozen snapshot object per
+  render.
+- **Multiple forms on one screen**: each hook returns its own `Debugger`,
+  so triggers could stack/overlap. May want an instance label prop and/or
+  offset management; punt until it hurts.
+- **Production leakage**: it's dev tooling, but it ships in the library.
+  Decide whether it's tree-shaken naturally (only renders if placed in
+  JSX — probably sufficient) or needs an env gate.
+- **Placement re: item 5 split**: the plumbing is 'form state'; the
+  trigger/window UI is presentational. Like the item-6 wrappers, it's a
+  bridge layer — settle its home when the split lands.
+
+## 8. Per-field meta state: visited tracking + stable React keys
+
+Alongside the *value* tree, the hook needs a parallel *meta* tree — state
+about fields that isn't field data:
+
+- **visited/touched** — has the user interacted with this field yet? Feeds
+  the error-display policy (item 6's `errorMessage` gates on it via
+  `onBlur`).
+- **stable React keys** — list elements need identity that survives
+  reorders/inserts/removals. Index keys break exactly when lists get
+  interesting; the meta layer is the natural place to mint and hold a
+  stable id per element.
+
+### The hard part: array manipulation keeping meta in sync (open research)
+
+When a list is reordered, inserted into, or spliced, per-element meta
+(visited flags, keys) must follow its element — not its index. Two candidate
+approaches, deliberately unresolved until we get there:
+
+- **Owned array operations.** Past projects needed a dedicated set of list
+  manipulation ops (`insertAt`, `removeAt`, `move`, …) that update values
+  and meta in the same motion. Known to work; the cost is that consumers
+  must use *our* ops — raw `onValueChanges` with a hand-spliced array
+  silently desyncs meta.
+- **Identity tracking via Map/WeakMap.** Keep meta keyed by element object
+  identity (`WeakMap<element, meta>`) rather than by path/index, and detect
+  reorders by re-matching identities after each change. Frees consumers to
+  manipulate arrays however they like; open questions are elements that get
+  *replaced* rather than moved (immutable-update styles create new objects
+  on every edit — identity breaks precisely when fields are edited), and
+  primitive-element lists (`string[]`) which have no stable identity at all.
+
+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 —
+error paths and per-element meta both need element identity once lists are
+editable.
+
 ## Open decisions
 
 - **Whole-value + structural constraints on the same key** (e.g. validate

package/src/forms/useFormState/FormDebugger.module.css

@@ -0,0 +1,41 @@
+.root {
+  position: fixed;
+  right: var(--ui-space-4);
+  bottom: var(--ui-space-4);
+  /* Same z-index tier as every other portal layer (Modal, Popover, Tooltip);
+   * stacking between layers comes from DOM-append order, not z-index. */
+  z-index: 100;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--ui-space-2);
+  font-family: var(--ui-font);
+}
+
+.trigger {
+  padding: var(--ui-space-1) var(--ui-space-3);
+  font-family: var(--ui-font-mono);
+  font-size: var(--ui-text-xsmall);
+  color: var(--ui-foreground);
+  background-color: var(--ui-background-1);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius-large);
+  box-shadow: 0 2px 8px var(--ui-shadow-soft);
+  cursor: pointer;
+  user-select: none;
+}
+
+.trigger:hover {
+  background-color: var(--ui-background-2);
+}
+
+.window {
+  width: 360px;
+  max-height: min(480px, 60vh);
+  overflow: auto;
+  padding: var(--ui-space-2);
+  background-color: var(--ui-background-0);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius-large);
+  box-shadow: 0 4px 16px var(--ui-shadow-soft);
+}

package/src/forms/useFormState/FormDebugger.test.tsx

@@ -0,0 +1,74 @@
+import { afterEach, describe, test, expect } from 'bun:test';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+
+// The Debugger portals into document.body, so leftovers from a previous
+// test are visible to `screen` queries — clean up explicitly (bun:test has
+// no global afterEach for RTL's auto-cleanup to hook).
+afterEach(cleanup);
+import { useFormState } from './useFormState';
+import { notEmpty } from '../validators/validators';
+
+type DebugForm = { nickname: string | undefined };
+
+const DebugHost = () => {
+  const { values, onValueChanges, Debugger } = useFormState({
+    initialValues: { nickname: undefined } as DebugForm,
+    constraints: { nickname: notEmpty('nickname') },
+  });
+
+  return (
+    <div>
+      <input
+        aria-label="nickname"
+        value={values.nickname ?? ''}
+        onChange={(e) => {
+          const nickname = e.target.value;
+          onValueChanges((prev) => ({ ...prev, nickname }));
+        }}
+      />
+      <Debugger label="debug me" />
+    </div>
+  );
+};
+
+describe('FormDebugger', () => {
+  test('renders the trigger with the window closed', () => {
+    render(<DebugHost />);
+    expect(screen.getByRole('button', { name: 'debug me' })).toBeTruthy();
+    expect(screen.queryByText('isValid')).toBeNull();
+  });
+
+  test('clicking the trigger opens the window with the current state', () => {
+    render(<DebugHost />);
+    fireEvent.click(screen.getByRole('button', { name: 'debug me' }));
+
+    expect(screen.getByText('isValid')).toBeTruthy();
+    expect(screen.getByText('submitAttempted')).toBeTruthy();
+    expect(screen.getByText("'nickname' cannot be empty")).toBeTruthy();
+  });
+
+  test('the open window live-updates as the form changes', () => {
+    render(<DebugHost />);
+    fireEvent.click(screen.getByRole('button', { name: 'debug me' }));
+
+    fireEvent.change(screen.getByLabelText('nickname'), {
+      target: { value: 'will' },
+    });
+
+    // The window survived the form re-render (stable component identity —
+    // a remount would have reset it to closed) and shows the new state.
+    expect(screen.getByText('will')).toBeTruthy();
+    expect(screen.queryByText("'nickname' cannot be empty")).toBeNull();
+  });
+
+  test('clicking the trigger again closes the window', () => {
+    render(<DebugHost />);
+    const trigger = screen.getByRole('button', { name: 'debug me' });
+
+    fireEvent.click(trigger);
+    expect(screen.getByText('isValid')).toBeTruthy();
+
+    fireEvent.click(trigger);
+    expect(screen.queryByText('isValid')).toBeNull();
+  });
+});

package/src/forms/useFormState/FormDebugger.tsx

@@ -0,0 +1,72 @@
+import { useState, useSyncExternalStore } from 'react';
+import type { ReactElement } from 'react';
+import { createPortal } from 'react-dom';
+import { JsonTable } from '../../components/Json/JsonTable';
+import { toInspectable } from './inspectable';
+import type { SnapshotStore } from './snapshotStore';
+import type { FormDebugSnapshot, FormValuesObject } from './types';
+import styles from './FormDebugger.module.css';
+
+export type FormDebuggerProps = {
+  /** Trigger text. Give each form a distinct label when several debuggers
+   *  are mounted at once — triggers stack in the same corner. */
+  label?: string;
+};
+
+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
+// 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>(
+  store: SnapshotStore<FormDebugSnapshot<T>>,
+): FormDebuggerComponent => {
+  // The subscription lives in the window, not the trigger: a closed
+  // debugger never re-renders with the form.
+  const DebuggerWindow = (props: { label: string }) => {
+    const { label } = props;
+
+    const snapshot = useSyncExternalStore(
+      store.subscribe,
+      store.getSnapshot,
+      store.getSnapshot,
+    );
+
+    return (
+      <div className={styles.window}>
+        <JsonTable
+          title={label}
+          value={toInspectable({
+            isValid: snapshot.isValid,
+            submitAttempted: snapshot.submitAttempted,
+            values: snapshot.values,
+            errors: snapshot.errors,
+          })}
+        />
+      </div>
+    );
+  };
+
+  const FormDebugger = (props: FormDebuggerProps) => {
+    const { label = 'form state' } = props;
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    return createPortal(
+      <div className={styles.root}>
+        {isOpen && <DebuggerWindow label={label} />}
+        <button
+          type="button"
+          className={styles.trigger}
+          onClick={() => setIsOpen((open) => !open)}
+        >
+          {label}
+        </button>
+      </div>,
+      document.body,
+    );
+  };
+
+  return FormDebugger;
+};

package/src/forms/useFormState/inspectable.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect } from 'bun:test';
+import { toInspectable } from './inspectable';
+
+describe('toInspectable', () => {
+  test('passes leaves through untouched', () => {
+    expect(toInspectable('hi')).toBe('hi');
+    expect(toInspectable(42)).toBe(42);
+    expect(toInspectable(10n)).toBe(10n);
+    expect(toInspectable(null)).toBeNull();
+    expect(toInspectable(undefined)).toBeUndefined();
+    expect(toInspectable(true)).toBe(true);
+  });
+
+  test('converts arrays to index-keyed objects', () => {
+    expect(toInspectable(['a', 'b'])).toEqual({ 0: 'a', 1: 'b' });
+  });
+
+  test('converts arrays of objects recursively', () => {
+    expect(toInspectable([{ name: 'ada' }, { name: 'bo' }])).toEqual({
+      0: { name: 'ada' },
+      1: { name: 'bo' },
+    });
+  });
+
+  test('renders Sets as a descriptive string leaf', () => {
+    expect(toInspectable(new Set(['a', 'b']))).toBe('Set(2) { "a", "b" }');
+    expect(toInspectable(new Set())).toBe('Set(0) {  }');
+  });
+
+  test('walks nested objects', () => {
+    const form = {
+      email: 'a@b.co',
+      address: { city: undefined, tags: ['home'] },
+      drivers: [{ name: 'ada', incidents: [] }],
+    };
+    expect(toInspectable(form)).toEqual({
+      email: 'a@b.co',
+      address: { city: undefined, tags: { 0: 'home' } },
+      drivers: { 0: { name: 'ada', incidents: {} } },
+    });
+  });
+});

package/src/forms/useFormState/inspectable.ts

@@ -0,0 +1,35 @@
+// Converts a form-state snapshot into a shape JsonTable renders without
+// throwing. JsonTable dispatches on "plain object vs leaf": arrays and Sets
+// fall to the leaf renderer, and an array of objects (FormValueList) would
+// throw as a React child. A debugger must render *any* legal form state, so:
+//
+//   - arrays  → index-keyed plain objects ({ 0: ..., 1: ... }), recursively
+//   - Sets    → a descriptive string leaf: `Set(2) { "a", "b" }`
+//   - objects → walked recursively
+//   - leaves  → passed through untouched
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  (Object.getPrototypeOf(value) === Object.prototype ||
+    Object.getPrototypeOf(value) === null);
+
+export const toInspectable = (value: unknown): unknown => {
+  if (value instanceof Set) {
+    const members = [...value].map((member) => JSON.stringify(member));
+    return `Set(${value.size}) { ${members.join(', ')} }`;
+  }
+
+  if (Array.isArray(value)) {
+    return Object.fromEntries(
+      value.map((element, index) => [index, toInspectable(element)]),
+    );
+  }
+
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [key, toInspectable(child)]),
+    );
+  }
+
+  return value;
+};

package/src/forms/useFormState/snapshotStore.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { createSnapshotStore } from './snapshotStore';
+
+describe('createSnapshotStore', () => {
+  test('getSnapshot returns the initial snapshot', () => {
+    const store = createSnapshotStore({ n: 1 });
+    expect(store.getSnapshot()).toEqual({ n: 1 });
+  });
+
+  test('publish replaces the snapshot and notifies subscribers', () => {
+    const store = createSnapshotStore({ n: 1 });
+    const onChange = mock(() => {});
+    store.subscribe(onChange);
+
+    store.publish({ n: 2 });
+
+    expect(store.getSnapshot()).toEqual({ n: 2 });
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  test('publish keeps the snapshot reference stable between publishes', () => {
+    const store = createSnapshotStore({ n: 1 });
+    store.publish({ n: 2 });
+    expect(store.getSnapshot()).toBe(store.getSnapshot());
+  });
+
+  test('unsubscribe stops notifications', () => {
+    const store = createSnapshotStore({ n: 1 });
+    const onChange = mock(() => {});
+    const unsubscribe = store.subscribe(onChange);
+
+    unsubscribe();
+    store.publish({ n: 2 });
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  test('publish with no subscribers is a no-op notify', () => {
+    const store = createSnapshotStore({ n: 1 });
+    expect(() => store.publish({ n: 2 })).not.toThrow();
+    expect(store.getSnapshot()).toEqual({ n: 2 });
+  });
+
+  test('notifies every subscriber', () => {
+    const store = createSnapshotStore({ n: 1 });
+    const first = mock(() => {});
+    const second = mock(() => {});
+    store.subscribe(first);
+    store.subscribe(second);
+
+    store.publish({ n: 2 });
+
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});

package/src/forms/useFormState/snapshotStore.ts

@@ -0,0 +1,31 @@
+// Minimal external store connecting a hook's per-render state to observers
+// outside its render tree (the form Debugger). Shaped for
+// `useSyncExternalStore`: `subscribe` returns an unsubscribe function and
+// `getSnapshot` must keep returning the same reference until the next
+// `publish` — snapshots are replaced whole, never mutated.
+export type SnapshotStore<Snapshot> = {
+  publish: (next: Snapshot) => void;
+  subscribe: (onChange: () => void) => () => void;
+  getSnapshot: () => Snapshot;
+};
+
+export const createSnapshotStore = <Snapshot,>(
+  initial: Snapshot,
+): SnapshotStore<Snapshot> => {
+  let current = initial;
+  const listeners = new Set<() => void>();
+
+  return {
+    publish: (next) => {
+      current = next;
+      for (const listener of listeners) listener();
+    },
+    subscribe: (onChange) => {
+      listeners.add(onChange);
+      return () => {
+        listeners.delete(onChange);
+      };
+    },
+    getSnapshot: () => current,
+  };
+};

package/src/forms/useFormState/types.ts

@@ -1,3 +1,7 @@
+// Type-only import; FormDebugger.tsx imports value types from this file in
+// turn, but the cycle never exists at runtime.
+import type { FormDebuggerComponent } from './FormDebugger';
+
 export type FormValueSimple = string | number | bigint | string[] | Set<string> | undefined | null;
 
 export type FormValuesObject = { [k in string]: FormValue };
@@ -10,6 +14,16 @@ export type FormErrors<T extends FormValuesObject> = Partial<
   Record<keyof T, string>
 >;
 
+// What the hook publishes to its Debugger after every commit. Snapshots are
+// replaced whole (never mutated) so `useSyncExternalStore` consumers can
+// rely on reference equality.
+export type FormDebugSnapshot<T extends FormValuesObject> = {
+  values: T;
+  errors: FormErrors<T>;
+  isValid: boolean;
+  submitAttempted: boolean;
+};
+
 export type FormHelpers<T extends FormValuesObject> = {
   values: T;
   // todo: likely remove once other setter are available
@@ -20,4 +34,8 @@ export type FormHelpers<T extends FormValuesObject> = {
   isValid: boolean;
   submitAttempted: boolean;
   submit: () => void;
+  // 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.
+  Debugger: FormDebuggerComponent;
 };

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

@@ -1,5 +1,6 @@
 import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
 import { useFormState } from './useFormState';
 import { allOf, matches, minLength, notEmpty } from '../validators/validators';
 import { Field } from '../../components/Forms/Field';
@@ -153,6 +154,43 @@ export const SignupForm: Story = {
       <SignupDemo />
     </div>
   ),
+  // Walks the headline flow: errors gated on submit, allOf first-error
+  // progression, live clearing, and the narrowed payload reaching onSubmit.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(canvasElement.ownerDocument.body);
+
+    // Errors are gated on submitAttempted — nothing shown initially.
+    await expect(
+      canvas.queryByText("'email' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // A failing submit surfaces every constrained field's error.
+    await userEvent.click(canvas.getByRole('button', { name: 'Sign up' }));
+    await expect(canvas.getByText("'email' cannot be empty")).toBeInTheDocument();
+    await expect(
+      canvas.getByText("'displayName' cannot be empty"),
+    ).toBeInTheDocument();
+    await expect(canvas.getByText("'role' cannot be empty")).toBeInTheDocument();
+
+    // allOf progression: notEmpty now passes, matches takes over.
+    await userEvent.type(canvas.getByLabelText(/^Email/), 'not-an-email');
+    await expect(
+      canvas.getByText("'email' must be a valid email"),
+    ).toBeInTheDocument();
+
+    // Fix every field; errors clear live.
+    await userEvent.clear(canvas.getByLabelText(/^Email/));
+    await userEvent.type(canvas.getByLabelText(/^Email/), 'will@example.com');
+    await userEvent.type(canvas.getByLabelText(/^Display name/), 'Will');
+    await userEvent.click(canvas.getByRole('button', { name: 'Role' }));
+    // The option list is portaled — query the document, not the canvas.
+    await userEvent.click(await body.findByRole('option', { name: 'Engineer' }));
+
+    // Valid submit delivers the narrowed payload to onSubmit.
+    await userEvent.click(canvas.getByRole('button', { name: 'Sign up' }));
+    await expect(canvas.getByText(/onSubmit received/)).toBeInTheDocument();
+  },
 };
 
 const LiveValidityDemo = () => {
@@ -193,4 +231,160 @@ export const LiveValidity: Story = {
       <LiveValidityDemo />
     </div>
   ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Errors here are live — no submit gating.
+    await expect(canvas.getByText('false')).toBeInTheDocument();
+    await userEvent.type(canvas.getByLabelText(/^Nickname/), 'ab');
+    await expect(
+      canvas.getByText("'nickname' must be at least 3 characters"),
+    ).toBeInTheDocument();
+
+    await userEvent.type(canvas.getByLabelText(/^Nickname/), 'c');
+    await expect(canvas.getByText('true')).toBeInTheDocument();
+  },
+};
+
+type DebuggerDemoValues = {
+  email: string | undefined;
+  nickname: string | undefined;
+  tags: string[];
+};
+
+// The Debugger comes off the hook itself — drop it anywhere in the tree and
+// a fixed trigger appears bottom-right; open it and watch values/errors/
+// isValid/submitAttempted update live as you interact with the form.
+const DebuggerDemo = () => {
+  const [tagDraft, setTagDraft] = useState('');
+
+  const { values, onValueChanges, errors, submitAttempted, submit, Debugger } =
+    useFormState({
+      initialValues: {
+        email: undefined,
+        nickname: undefined,
+        tags: [],
+      } as DebuggerDemoValues,
+      constraints: {
+        email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        nickname: notEmpty('nickname'),
+      },
+    });
+
+  const shownErrors = submitAttempted ? errors : {};
+
+  return (
+    <form
+      style={{ maxWidth: 420, display: 'grid', gap: 16 }}
+      onSubmit={(e) => {
+        e.preventDefault();
+        submit();
+      }}
+    >
+      <Field label="Email" error={shownErrors.email} htmlFor="debug-email">
+        <Input
+          id="debug-email"
+          type="email"
+          value={values.email ?? ''}
+          onChange={(e) => {
+            const email = e.target.value;
+            onValueChanges((prev) => ({ ...prev, email }));
+          }}
+          placeholder="you@example.com"
+        />
+      </Field>
+
+      <Field label="Nickname" error={shownErrors.nickname} htmlFor="debug-nickname">
+        <Input
+          id="debug-nickname"
+          value={values.nickname ?? ''}
+          onChange={(e) => {
+            const nickname = e.target.value;
+            onValueChanges((prev) => ({ ...prev, nickname }));
+          }}
+        />
+      </Field>
+
+      <Field
+        label="Tags"
+        hint="Unconstrained string[] — shows how the Debugger renders list values"
+        htmlFor="debug-tag-draft"
+      >
+        <div style={{ display: 'flex', gap: 8 }}>
+          <Input
+            id="debug-tag-draft"
+            value={tagDraft}
+            onChange={(e) => setTagDraft(e.target.value)}
+            placeholder="add a tag"
+          />
+          <Button
+            type="button"
+            onClick={() => {
+              if (!tagDraft) return;
+              onValueChanges((prev) => ({ ...prev, tags: [...prev.tags, tagDraft] }));
+              setTagDraft('');
+            }}
+          >
+            Add
+          </Button>
+        </div>
+      </Field>
+
+      {values.tags.length > 0 && (
+        <div style={{ fontSize: 13 }}>tags: {values.tags.join(', ')}</div>
+      )}
+
+      <div>
+        <Button type="submit" variant="primary">
+          Submit
+        </Button>
+      </div>
+
+      <Debugger label="signup form" />
+    </form>
+  );
+};
+
+export const WithDebugger: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <DebuggerDemo />
+    </div>
+  ),
+  // The Debugger portals to <body>, so its trigger/window are queried on the
+  // document, not the canvas. Exercises open → live update → close, which
+  // also pins the stable-identity guarantee: a remounting Debugger would
+  // lose its open state on the first keystroke.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(canvasElement.ownerDocument.body);
+
+    // Closed: trigger only, no window content.
+    await expect(body.queryByText('isValid')).not.toBeInTheDocument();
+
+    // Open: live state, including errors the form itself isn't showing yet
+    // (its display is submit-gated; the debugger sees the raw truth).
+    await userEvent.click(body.getByRole('button', { name: 'signup form' }));
+    await expect(body.getByText('isValid')).toBeInTheDocument();
+    await expect(body.getByText("'email' cannot be empty")).toBeInTheDocument();
+    await expect(
+      body.getByText("'nickname' cannot be empty"),
+    ).toBeInTheDocument();
+
+    // Live update while open: value appears, its error entry drops out.
+    await userEvent.type(canvas.getByLabelText(/^Nickname/), 'will');
+    await expect(body.getByText('will')).toBeInTheDocument();
+    await expect(
+      body.queryByText("'nickname' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // List values render in the window (index-keyed).
+    await userEvent.type(canvas.getByLabelText(/^Tags/), 'typescript');
+    await userEvent.click(canvas.getByRole('button', { name: 'Add' }));
+    await expect(body.getByText('typescript')).toBeInTheDocument();
+
+    // Close: window unmounts, trigger stays.
+    await userEvent.click(body.getByRole('button', { name: 'signup form' }));
+    await expect(body.queryByText('isValid')).not.toBeInTheDocument();
+  },
 };

package/src/forms/useFormState/useFormState.ts

@@ -1,5 +1,14 @@
-import { useState } from 'react';
-import type { FormErrors, FormHelpers, FormValuesObject } from './types';
+import { useEffect, useRef, useState } from 'react';
+import { createFormDebugger } from './FormDebugger';
+import type { FormDebuggerComponent } from './FormDebugger';
+import { createSnapshotStore } from './snapshotStore';
+import type { SnapshotStore } from './snapshotStore';
+import type {
+  FormDebugSnapshot,
+  FormErrors,
+  FormHelpers,
+  FormValuesObject,
+} from './types';
 import type { Refine, Validations } from '../validations/types';
 
 // `const V` freezes the inferred type of an inline `constraints` object —
@@ -38,6 +47,31 @@ export const useFormState = <
 
   const isValid = Object.keys(errors).length === 0;
 
+  // Debugger plumbing: one store + one component per hook instance, created
+  // lazily on first render. The component's identity must be stable across
+  // renders — recreated each render it would remount (and lose its
+  // open/closed state) on every keystroke.
+  const debugRef = useRef<{
+    store: SnapshotStore<FormDebugSnapshot<T>>;
+    Debugger: FormDebuggerComponent;
+  } | null>(null);
+  if (debugRef.current === null) {
+    const store = createSnapshotStore<FormDebugSnapshot<T>>({
+      values,
+      errors,
+      isValid,
+      submitAttempted,
+    });
+    debugRef.current = { store, Debugger: createFormDebugger(store) };
+  }
+  const { store, Debugger } = debugRef.current;
+
+  // Publish after every commit. With no debugger window subscribed this is a
+  // field write and an empty notify loop — effectively free.
+  useEffect(() => {
+    store.publish({ values, errors, isValid, submitAttempted });
+  });
+
   const submit = () => {
     setSubmitAttempted(true);
     if (!isValid) return;
@@ -46,5 +80,13 @@ export const useFormState = <
     onSubmit?.(values as Refine<T, V>);
   };
 
-  return { values, onValueChanges, errors, isValid, submitAttempted, submit };
+  return {
+    values,
+    onValueChanges,
+    errors,
+    isValid,
+    submitAttempted,
+    submit,
+    Debugger,
+  };
 };