@ultimat3/ui 12.0.0 → 13.0.0

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # @ultimat3/ui — agent notes
 
-Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was deleted). Imports `@ultimat3/core`, `schema`, `i18n`, `money`, `time`. Never `http`, `action`, `render`, `admin` — `render` is tier 4 too, which is what keeps the static bundle graph out of the design system.
+Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was deleted). Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**, which this line claimed until 2026-08-24 and `package.json` never declared. That absence is why `src/form/` re-declares Standard Schema's one member structurally (`FormSchema`) and copies `formatPath` as `formatFieldPath`: the tier table permits the edge, the manifest and the lockfile do not. Never `http`, `action`, `render`, `admin` — `render` is tier 4 too, which is what keeps the static bundle graph out of the design system.
 
 ## Boundary
 
@@ -42,6 +42,11 @@ Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was delet
 - **A single-winner state attribute is decided by POSITION, never by a missing prop.** `Breadcrumb` gives `aria-current="page"` to the last item and to nothing else; an href-less ancestor renders as plain text with no `aria-current` at all. Reading "no href" as "is the current page" put two of them in one `<nav>`. `Tabs.tsx` is the same rule for `tabindex`, and `Breadcrumb.test.ts` proves it through `jsx-probe` rather than through the pure helper.
 - **Live semantics belong to the container that outlives the message.** `ToastRegion`'s `<ol>` carries `aria-live`; a `Toast` is a plain `<li>`. A region created with its content already inside it is not announced, and a `role="status"` on the `<li>` also strips its `listitem` semantics.
 - **`aria-checked` never mirrors a native `checked`.** ARIA outranks host state in the accessibility tree, and on the no-JS path this package supports there is nothing to rewrite the attribute after the user ticks the box. `Checkbox` writes only `'mixed'` (an IDL property with no attribute form, so ARIA is the only server-side lever); `Switch` writes none at all, over a `biome-ignore` that says why.
+- **A form binds to an action; it never decides for one.** `useForm` (`src/form/`) is a binding over an existing `action`, not a ninth primitive and not a component — `submit` is REQUIRED and is the only producer of a `succeeded` state, and the client-side parse's **value** is discarded so that only its issues are read. A binding that submitted the locally-parsed value would let a browser choose what the server was asked to store; `FormSchema` has no output type for that reason.
+- **One path grammar, both directions.** A control's `name` and a schema issue's path are the same string (`items[0].price`), which is what lets a rejection find its control with no per-form mapping table. `formatFieldPath` mirrors `@ultimat3/schema`'s `formatPath` — **keep it in sync**, because the server rendered the incoming path with THAT function — and `parseFieldPath` is its inverse, refusing `__proto__`, `items[]`, `items.0.price` and an index above `MAX_FIELD_INDEX`.
+- **An issue that matches no declared field is SURFACED, never swallowed.** It goes to `formErrors`, which `<Form error>` announces and focuses; a near miss (`items` against a form holding `items[0].price`) goes there too, because an error rendered against the wrong input is a lie the user acts on. Two issues on one field both survive in the state — `Field`'s one slot renders the first, `messagesFor` has the rest.
+- **The framework ships the mapping and no copy table.** `FormIssue.message` is a schema's diagnostic text and is never user-facing; `messageFor` is required and is the app's. There is deliberately no `ui.form.*` key: a built-in wording would be one app's convention shipped to every other. A `messageFor` that answers `''` or throws falls back to the diagnostic text — the loud-but-safe answer `t()` already gives with `⟦key⟧`, because the alternatives are a control marked `aria-invalid` with nothing to read, or a submit abandoned mid-flight holding the user's input.
+- **The wire carries no structured issue list, `As of 2026-08-24`.** `InputInvalidError` renders the issues into `cause` and puts nothing in `meta`, and `toProblem` has no `issues` member, so `issuesFromRejection` reads `meta.issues` where there is one and parses the cause line where there is not. It binds a fragment to a field only when the fragment's head is a DECLARED path, so a mis-split degrades to a form-level error rather than to a wrong control. Delete the line parser the day the wire carries the list.
 - **Generated source is a CODE sink.** `build-icons.ts` writes modules every app EXECUTES at import, from data fetched over the network, so an attribute value goes through `JSON.stringify` and never `'${value}'` — and `SAFE_ATTR_VALUE` refuses anything that is not glyph geometry one layer earlier. `iconElements` guards tags and attribute NAMES; it has never guarded a value. Malformed upstream data is `X_UI_INVALID_VALUE`; only the generator's real environment faults (no network, no biome binary) are `X_UI_RUNTIME_MISSING`.
 - **The icon NAME is the third sink, and it has no escape.** The upstream map key becomes a filesystem path under `GLYPHS_DIR`, an exported identifier and a `//` banner, and `buildIcons` clears `GLYPHS_DIR` before it writes — so `../../index` was a delete of the glyph tree followed by an overwrite of a hand-written module, and a key carrying `;` produced a module that typechecked and ran. `SAFE_ICON_NAME` (`/^[a-z0-9]+(-[a-z0-9]+)*$/`) is checked in `parseIconNodes` BEFORE `out.set`, the same allowlist-over-a-sink shape as `SAFE_ATTR_VALUE` one layer down; all 1767 committed names pass it and `build-icons.test.ts` asserts that.
 
@@ -63,6 +68,13 @@ Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was delet
 | `src/tokens/contrast.ts` | WCAG ratios over the channel tokens; `contrast.test.ts` gates AA in both themes |
 | `src/catalog/` | parses `components/*.tsx` into `CATALOG.md`; `bun run catalog` writes it, `catalog.test.ts` fails on drift |
 | `src/roving.ts` | the pure rules of a keyboard group: navigable set, tab stop, who keeps their own arrows |
+| `src/form/field-path.ts` | the one path grammar, both directions — pure, and deliberately free of `../errors` so mapping an issue costs no chunk the error registry |
+| `src/form/form-issue.ts` | the two readers of an issue: a local parse result, and whatever the server rejected with |
+| `src/form/form-state.ts` | where an issue LANDS — the declared field, or the form |
+| `src/form/form-binding.ts` | the submit state machine; the one place a `succeeded` exists |
+| `src/form/use-form.ts` | the Solid shell: the same binding with its state in a signal |
+| `src/form/form-values.ts` | `FormData` → the nested object the action's input schema declares |
+| `src/form/field-binding.test.ts` | the WIRING, end to end: a rejection reaching `aria-invalid` and `aria-describedby` on the control it named |
 | `src/fake-dom.ts` | TEST-ONLY: a DOM where a disabled control refuses focus. Never exported from `index.ts` |
 | `src/jsx-probe.ts` | TEST-ONLY: a component's node tree, so a test can assert the props and call the handlers an element carries. `probe`/`unprobe` are the framework's ONE owner of `globalThis.React`, reached from `@ultimat3/admin` at `@ultimat3/ui/jsx-probe`; the walkers stay internal |
 | `src/barrel-bytes.test.ts` | the build error behind the two byte claims above: the setter's ceiling, and barrel-vs-deep-path parity |

package/README.md

@@ -356,6 +356,72 @@ result before first paint, so there is no flash and screenshots are deterministi
 Content-Security-Policy: script-src 'self' 'sha256-…'   # themeInlineScriptCspSource()
 ```
 
+## Forms bound to an action's input schema
+
+`As of 2026-08-24`. Four things already existed and none were connected: the action's `input`
+schema, the issue paths its parse produces, the rejection the server sends back, and `Field`'s
+error slot. `useForm` is the binding — **not** a ninth primitive and not a component: a form is a
+binding over an existing `action`, the way `llm()` is a factory over one.
+
+```tsx
+import { t } from '@ultimat3/i18n';
+import { Field, Form, type FormSchema, Input, useForm, valuesOfForm } from '@ultimat3/ui';
+
+// In an app this is `InferInput<typeof createPost.input>` — an object type, not an interface,
+// which is what lets `valuesOfForm`'s `Record<string, unknown>` be narrowed to it below.
+type CreatePostInput = { readonly title: string };
+interface Post {
+  readonly id: string;
+}
+
+// The action and its typed client, both the app's: `createPost.input` IS a `FormSchema`.
+declare const createPost: { readonly input: FormSchema };
+declare const api: { createPost(values: CreatePostInput): Promise<Post> };
+
+export function CreatePostForm() {
+  const form = useForm<CreatePostInput, Post>({
+    fields: ['title', 'items[0].price'],
+    schema: createPost.input,            // optional: latency only, never authority
+    submit: (values) => api.createPost(values),
+    // The app's wording, not the framework's: one `t()` key per thing a user can get wrong.
+    messageFor: (issue) => (issue.path === 'title' ? t('post.title.invalid') : t('post.invalid')),
+  });
+
+  return (
+    // `undefined` and never `''`: `error` being PRESENT is what makes Form render the summary
+    // and move focus to it, so an empty string is an error box on a form with nothing wrong.
+    <Form
+      error={form.state().formErrors.join(' ') || undefined}
+      onSubmit={(event) => {
+        event.preventDefault();
+        void form.submit(valuesOfForm(new FormData(event.currentTarget)) as CreatePostInput);
+      }}
+    >
+      <Field label={t('post.title')} error={form.errorFor('title')}>
+        {(control) => <Input {...control} name="title" />}
+      </Field>
+    </Form>
+  );
+}
+```
+
+| Rule | Why |
+|---|---|
+| **`submit` is required and is the only producer of `succeeded`** | a form that decides for itself that a value is acceptable is a security defect. The client-side parse is a latency optimisation; the action re-parses server-side on every path |
+| the local parse's **value** is discarded — only its issues are read | otherwise the browser decides what the server was asked to store. `FormSchema` deliberately has no output type |
+| a `name` attribute and an issue path are the **same string** (`items[0].price`) | one grammar, so a rejection finds its control with no per-form mapping table. `formatFieldPath` / `parseFieldPath` are the two directions; a name the grammar cannot read is `X_UI_FORM_PATH_INVALID`, refused where it is DECLARED |
+| an issue whose path matches no declared field goes to **`formErrors`**, never to a neighbouring control | a form that silently drops "the server rejected this" is worse than one with no binding at all. A near miss (`items` against a form holding `items[0].price`) is one of these |
+| every message is the app's, through `messageFor` | a schema issue (`expected number`) is diagnostic text, not a user-facing string. The framework ships the mapping and **no copy table** — there is no `ui.form.*` key to override. A translator that answers `''` or throws falls back to the diagnostic text, the way a missing catalog key renders `⟦key⟧` |
+| a second `submit` while one is in flight **joins** it | a double click is not a second write |
+
+**The wire carries no structured issue list yet.** A server-side validation failure arrives as
+`X_INPUT_INVALID` with the issues rendered into `cause` (`title: too short; items[0].price:
+expected number`) — `packages/action/src/errors.ts` puts nothing in `meta`, and `toProblem`
+(`packages/http/src/error-facts.ts`) has no `issues` member — so `issuesFromRejection` reads
+`meta.issues` where it exists and parses that line where it does not. It binds a fragment to a
+field only when the head is a declared path, so a message holding `'; '` or `': '` degrades to a
+form-level error rather than to a wrong control.
+
 ## Errors
 
 | Code | When |
@@ -363,6 +429,7 @@ Content-Security-Policy: script-src 'self' 'sha256-…'   # themeInlineScriptCsp
 | `X_TOKEN_UNKNOWN` | a token role the SCSS source does not define — including a `defineTheme()` override of a role, radius or font slot that is not in the scale |
 | `X_THEME_INVALID` | a theme other than `light` / `dark` |
 | `X_UI_RUNTIME_MISSING` | a DOM render with no registered Solid runtime, `<UiProvider>` on the server, or `browserThemeEnv()` off-DOM. A server render with no runtime is **not** one of them — it gets `INERT_SOLID_RUNTIME` |
+| `X_UI_FORM_PATH_INVALID` | a form field or control name the path grammar cannot read (`items.0.price`, `items[]`, `__proto__`), or two control names describing different shapes for one path (`user` beside `user.name`) |
 | `X_UI_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors or one dimension without the other, a heading level off 1–6, a `defineTheme()` value that is not a token value, an `<Icon>` glyph with a tag/attribute/colour outside `ICON_TAGS`, two `Accordion` items sharing an id, `InfiniteScroll` with `hasMore` and no `nextHref`, a negative `debounce` window, or (`As of 2026-08`) upstream icon data `bun run icons` refuses (not an object, no renderable nodes, an attribute value that is not glyph geometry) |
 
 ## Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "12.0.0",
+  "version": "13.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -44,10 +44,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "12.0.0",
-    "@ultimat3/i18n": "12.0.0",
-    "@ultimat3/money": "12.0.0",
-    "@ultimat3/time": "12.0.0"
+    "@ultimat3/core": "13.0.0",
+    "@ultimat3/i18n": "13.0.0",
+    "@ultimat3/money": "13.0.0",
+    "@ultimat3/time": "13.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/errors.ts

@@ -8,11 +8,12 @@ export const UI_ERROR_CODES = {
   themeInvalid: 'X_THEME_INVALID',
   runtimeMissing: 'X_UI_RUNTIME_MISSING',
   invalidValue: 'X_UI_INVALID_VALUE',
+  formPathInvalid: 'X_UI_FORM_PATH_INVALID',
 } as const;
 
 export type UiErrorCode = (typeof UI_ERROR_CODES)[keyof typeof UI_ERROR_CODES];
 
-// Unconditional like every other package: all four codes are ui's own, and a second package
+// Unconditional like every other package: every code here is ui's own, and a second package
 // claiming one has to throw X_ERROR_CODE_DUPLICATE at import. Taking the process down there is the
 // point — the alternative is two packages shipping two meanings for one code, decided by load order.
 registerErrorCodes({
@@ -20,6 +21,7 @@ registerErrorCodes({
   X_THEME_INVALID: { title: 'theme is not "light" or "dark"' },
   X_UI_RUNTIME_MISSING: { title: 'a host capability @ultimat3/ui needs is absent' },
   X_UI_INVALID_VALUE: { title: 'a formatting component received an unrenderable value' },
+  X_UI_FORM_PATH_INVALID: { title: 'a form control name is not a usable field path' },
 });
 
 export class UiError extends UltimateError {
@@ -147,3 +149,33 @@ export function invalidIconDataError(found: string, fix: string): UiError {
     fix,
   });
 }
+
+/** The one grammar both a `name` attribute and a schema issue path are written in. */
+const FIELD_PATH_GRAMMAR =
+  'a segment, then `.segment` or `[index]` — "title", "items[0].price", never "items.0.price" or "items[]"';
+
+/**
+ * A form named a field the path grammar cannot read. Refused where it is DECLARED rather than
+ * where a rejection arrives: a path no issue can ever equal is a field whose server error lands at
+ * the top of the form forever, and that is indistinguishable from an app with no bug at all.
+ */
+export function invalidFieldPathError(subject: string, name: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.formPathInvalid,
+    cause: `${subject} "${name}" is not a field path, so no schema issue can address it`,
+    fix: `rename it to ${FIELD_PATH_GRAMMAR}`,
+  });
+}
+
+/**
+ * Two controls whose names describe different shapes for one path (`user` beside `user.name`).
+ * Refused rather than resolved: either answer silently drops one control's value, and the value
+ * dropped is something the user typed.
+ */
+export function conflictingFieldNameError(name: string, at: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.formPathInvalid,
+    cause: `form control "${name}" cannot be read: "${at}" already holds a value of another shape`,
+    fix: `rename one of the two controls — a path segment holds a value or a container, never both`,
+  });
+}

package/src/form/field-path.ts

@@ -0,0 +1,91 @@
+// The ONE path grammar a form speaks, in both directions: the dotted, bracketed string a schema
+// issue carries (`items[2].price`) and the `name` attribute the control renders. One grammar is
+// what lets a rejection find its control at all — two would be a hand-written mapping table per
+// form, which is the 40-forms-40-mappings cost this binding exists to delete.
+
+/** A Standard Schema issue segment. Wrapped or bare — conforming libraries send both. */
+export interface IssuePathSegment {
+  readonly key: PropertyKey;
+}
+
+export type FieldPathSegment = string | number;
+
+/**
+ * The largest index the grammar accepts. A form does not have ten thousand rows; a larger index is
+ * a crafted `name`, and `valuesOfForm` would allocate the array it describes.
+ */
+export const MAX_FIELD_INDEX = 10_000;
+
+/**
+ * Structural copy of `@ultimat3/schema`'s `formatPath`. **Keep in sync**: an issue that arrives
+ * from the server was rendered by THAT function, so a divergence here is an error that lands on no
+ * field. Copied rather than imported because `@ultimat3/ui` holds no dependency edge on
+ * `@ultimat3/schema` — the tier table permits one, the manifest and the lockfile do not — the same
+ * trade `@ultimat3/db`'s `entity-shape.ts` makes one tier down.
+ */
+export function formatFieldPath(
+  path: readonly (PropertyKey | IssuePathSegment)[] | undefined,
+): string {
+  if (path === undefined || path.length === 0) return '';
+  let out = '';
+  for (const segment of path) {
+    const key = typeof segment === 'object' ? segment.key : segment;
+    if (typeof key === 'number') {
+      out += `[${key}]`;
+    } else {
+      out += out === '' ? String(key) : `.${String(key)}`;
+    }
+  }
+  return out;
+}
+
+const KEY = /^[A-Za-z_$][A-Za-z0-9_$]*/;
+/** `[0]`, never `[01]`: an index that does not round-trip through `formatFieldPath` is not one. */
+const INDEX = /^\[(0|[1-9][0-9]*)\]/;
+
+/**
+ * Keys that are not fields on any object an app owns. A control named `__proto__` reaching
+ * `valuesOfForm` writes through the prototype of every object in the process — the same sink
+ * `bun run proto-index` guards on the read side.
+ */
+const UNSAFE_KEYS: ReadonlySet<string> = new Set(['__proto__', 'prototype', 'constructor']);
+
+/**
+ * The reverse of `formatFieldPath`, or `null` for anything that is not a field path. Total and
+ * silent by design: the caller decides whether an unusable name is a refusal (`valuesOfForm`, which
+ * is building an object) or simply a path that matches no field (`distributeIssues`, which must
+ * surface it and carry on).
+ */
+export function parseFieldPath(name: string): readonly FieldPathSegment[] | null {
+  const segments: FieldPathSegment[] = [];
+  let rest = name;
+  let expectKey = true;
+
+  while (rest.length > 0) {
+    if (expectKey) {
+      const match = KEY.exec(rest);
+      if (match === null) return null;
+      const key = match[0];
+      if (UNSAFE_KEYS.has(key)) return null;
+      segments.push(key);
+      rest = rest.slice(key.length);
+      expectKey = false;
+      continue;
+    }
+    if (rest.startsWith('.')) {
+      rest = rest.slice(1);
+      expectKey = true;
+      continue;
+    }
+    const match = INDEX.exec(rest);
+    const digits = match?.[1];
+    if (match === undefined || match === null || digits === undefined) return null;
+    const index = Number(digits);
+    if (index > MAX_FIELD_INDEX) return null;
+    segments.push(index);
+    rest = rest.slice(match[0].length);
+  }
+
+  // `expectKey` still set means the name ended on a `.` or was empty — both are half a path.
+  return expectKey ? null : segments;
+}

package/src/form/form-binding.ts

@@ -0,0 +1,128 @@
+// The binding itself: an action's input schema on one side, `Field`'s error slot on the other, and
+// a submit that only the SERVER can turn into a success.
+//
+// Server authority is structural here, not documented: `submit` is required, `succeeded` is
+// produced in exactly one place — after the caller's `submit` resolves — and the local parse's
+// VALUE is discarded, so a client cannot decide either that a form is valid or what it said.
+
+import { invalidFieldPathError } from '../errors';
+import { parseFieldPath } from './field-path';
+import {
+  type FormIssue,
+  type FormSchema,
+  issuesFromRejection,
+  issuesFromValidation,
+} from './form-issue';
+import {
+  distributeIssues,
+  errorOf,
+  type FormState,
+  IDLE_FORM_STATE,
+  messagesOf,
+  NO_FORM_ERRORS,
+} from './form-state';
+
+export interface FormBindingOptions<TValues, TResult> {
+  /**
+   * The server call — `action.client()`, `rpc(...).createPost`, or a `fetch` that throws on a
+   * refusal. REQUIRED: it is the only thing in this file that can produce a success.
+   */
+  readonly submit: (values: TValues) => Promise<TResult>;
+  /** The paths this form renders a control for. An issue matching none surfaces at the form. */
+  readonly fields: readonly string[];
+  /** The app's wording for one issue. The framework ships the mapping, never the copy. */
+  readonly messageFor: (issue: FormIssue) => string;
+  /**
+   * The action's `input`. Optional, and a LATENCY optimisation only: the action re-parses on the
+   * server on every path, so omitting this changes when the user hears about a bad value, never
+   * whether it is rejected.
+   */
+  readonly schema?: FormSchema | undefined;
+  /** Called on every transition — how a reactive shell mirrors the state into a signal. */
+  readonly onState?: ((state: FormState<TResult>) => void) | undefined;
+}
+
+export interface FormBinding<TValues, TResult> {
+  readonly state: () => FormState<TResult>;
+  readonly submit: (values: TValues) => Promise<FormState<TResult>>;
+  /** The message `Field`'s single error slot renders for one path. */
+  readonly errorFor: (path: string) => string | undefined;
+  /** Every message bound to one path, when a form renders more than one. */
+  readonly messagesFor: (path: string) => readonly string[];
+  readonly reset: () => void;
+}
+
+/**
+ * Refused at DECLARATION, which is the only place it can be caught: a field named `items.0.price`
+ * is never equal to the `items[0].price` an issue carries, so its server errors would pile up at
+ * the top of the form and look exactly like an app with nothing wrong.
+ */
+function declaredFields(fields: readonly string[]): ReadonlySet<string> {
+  const declared = new Set<string>();
+  for (const name of fields) {
+    if (parseFieldPath(name) === null) throw invalidFieldPathError('form field', name);
+    declared.add(name);
+  }
+  return declared;
+}
+
+export function createFormBinding<TValues, TResult>(
+  options: FormBindingOptions<TValues, TResult>,
+): FormBinding<TValues, TResult> {
+  const fields = declaredFields(options.fields);
+  let state: FormState<TResult> = IDLE_FORM_STATE;
+  let inFlight: Promise<FormState<TResult>> | null = null;
+
+  const publish = (next: FormState<TResult>): FormState<TResult> => {
+    state = next;
+    options.onState?.(next);
+    return next;
+  };
+
+  const failed = (issues: readonly FormIssue[]): FormState<TResult> =>
+    publish({
+      status: 'failed',
+      ...distributeIssues(issues, fields, options.messageFor),
+      result: undefined,
+      issues,
+    });
+
+  const run = async (values: TValues): Promise<FormState<TResult>> => {
+    // Cleared, never carried: a stale message would mark a control invalid for a value the user
+    // has already changed, on the one screen where the user is watching for exactly that.
+    publish({ status: 'submitting', ...NO_FORM_ERRORS, result: undefined, issues: [] });
+
+    const schema = options.schema;
+    if (schema !== undefined) {
+      // The result's `value` is read by nothing. Deliberately: the parse below is the browser's
+      // opinion, and the only thing this file wants from it is which paths to complain about.
+      const local = issuesFromValidation(await schema['~standard'].validate(values));
+      if (local.length > 0) return failed(local);
+    }
+
+    try {
+      const result = await options.submit(values);
+      return publish({ status: 'succeeded', ...NO_FORM_ERRORS, result, issues: [] });
+    } catch (rejection) {
+      return failed(issuesFromRejection(rejection));
+    }
+  };
+
+  return {
+    state: () => state,
+    /** A second submit JOINS the first rather than starting one: a double click is not two writes. */
+    submit: (values) => {
+      if (inFlight !== null) return inFlight;
+      const flight = run(values).finally(() => {
+        inFlight = null;
+      });
+      inFlight = flight;
+      return flight;
+    },
+    errorFor: (path) => errorOf(state, path),
+    messagesFor: (path) => messagesOf(state, path),
+    reset: () => {
+      publish(IDLE_FORM_STATE);
+    },
+  };
+}

package/src/form/form-issue.ts

@@ -0,0 +1,138 @@
+// One issue shape, and the two readers that produce it: a local parse result (the latency half)
+// and a rejection off the server (the authoritative half). Nothing here decides what a user reads
+// — `FormIssue.message` is a schema's diagnostic text, never a translated string.
+
+import { renderThrowable, stringField } from '@ultimat3/core';
+import { formatFieldPath, type IssuePathSegment, parseFieldPath } from './field-path';
+
+/**
+ * One rejected value, addressed by the path the schema gave it.
+ *
+ * `message` is UNTRANSLATED and is not user-facing: it is whatever the schema library or the
+ * server wrote (`expected number`). The app turns it into words through `messageFor` — the
+ * framework ships no copy table, because the wording is the app's and the mapping is not.
+ */
+export interface FormIssue {
+  /** Canonical dotted path, `''` when the issue addresses the form rather than a field. */
+  readonly path: string;
+  readonly message: string;
+  /** The framework code that carried it, when a rejection named one. */
+  readonly code: string | undefined;
+}
+
+/** One issue as a conforming schema library reports it. */
+export interface FormValidationIssue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | IssuePathSegment)[] | undefined;
+}
+
+/**
+ * Standard Schema's result: `issues` present is the failure, absent is the pass.
+ *
+ * The success member holds `value: unknown` and nothing reads it — the type says what the runtime
+ * does. A client-side parse is a latency optimisation, so its OUTPUT is not something the server
+ * agreed to, and typing it would invite a caller to submit it.
+ */
+export type FormValidationResult =
+  | { readonly value: unknown; readonly issues?: undefined }
+  | { readonly issues: readonly FormValidationIssue[] };
+
+/**
+ * The minimum of an input schema this package needs — Standard Schema's one member, declared
+ * structurally so `@ultimat3/ui` needs no dependency edge on `@ultimat3/schema`. An `action()`'s
+ * own `input` satisfies it as written.
+ *
+ * The OUTPUT type is deliberately absent: a client-side parse is a latency optimisation, its value
+ * is thrown away, and typing it would invite a caller to submit it.
+ */
+export interface FormSchema {
+  readonly '~standard': {
+    readonly validate: (value: unknown) => FormValidationResult | Promise<FormValidationResult>;
+  };
+}
+
+/** A local parse's issues, addressed by path. A result with none answers `[]`. */
+export function issuesFromValidation(result: FormValidationResult): readonly FormIssue[] {
+  const issues = result.issues;
+  if (issues === undefined) return [];
+  return issues.map((issue) => ({
+    path: formatFieldPath(issue.path),
+    message: issue.message,
+    code: undefined,
+  }));
+}
+
+/** The codes whose `cause` is a rendered issue list rather than a sentence. */
+const VALIDATION_CODES: ReadonlySet<string> = new Set(['X_INPUT_INVALID', 'X_VALIDATION_FAILED']);
+
+/** `@ultimat3/action`'s `InputInvalidError` prefixes the list with the action it refused for. */
+const LIST_PREFIX = 'failed validation: ';
+
+/**
+ * `formatIssues()`'s separator, on both sides of the wire. A message that itself contains `'; '`
+ * splits wrongly here — and degrades VISIBLY, because a fragment whose head is not a field path
+ * lands at the form rather than on a control. That is the cost of the wire carrying no structured
+ * issue list; see this file's note in `README.md`.
+ */
+const ISSUE_SEPARATOR = '; ';
+
+function issuesFromCauseLine(cause: string, code: string): readonly FormIssue[] {
+  const prefix = cause.lastIndexOf(LIST_PREFIX);
+  const list = prefix === -1 ? cause : cause.slice(prefix + LIST_PREFIX.length);
+  return list
+    .split(ISSUE_SEPARATOR)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0)
+    .map((part) => {
+      const at = part.indexOf(': ');
+      const head = at === -1 ? '' : part.slice(0, at);
+      // Only a head that PARSES becomes a path. Otherwise the fragment is a sentence holding a
+      // colon, and splitting it would mint a field name the form never declared.
+      if (head === '' || parseFieldPath(head) === null) return { path: '', message: part, code };
+      return { path: head, message: part.slice(at + 2), code };
+    });
+}
+
+/** `meta.issues`, when the rejection survived with its structure intact. */
+function issuesFromMeta(rejection: object, code: string | undefined): readonly FormIssue[] | null {
+  let held: unknown;
+  try {
+    const meta: unknown = (rejection as Record<string, unknown>)['meta'];
+    if (typeof meta !== 'object' || meta === null) return null;
+    held = (meta as Record<string, unknown>)['issues'];
+  } catch {
+    // A getter or a Proxy trap fought the read; the cause line below is still there.
+    return null;
+  }
+  if (!Array.isArray(held)) return null;
+  const issues: FormIssue[] = [];
+  for (const entry of held as readonly unknown[]) {
+    const message = stringField(entry, 'message');
+    if (message === undefined) return null;
+    issues.push({ path: stringField(entry, 'path') ?? '', message, code });
+  }
+  return issues.length === 0 ? null : issues;
+}
+
+/**
+ * Whatever the server rejected with, as issues. Total over `unknown`: an `UltimateError`, a plain
+ * object off a worker or a WebSocket, a parsed `application/problem+json` body (`code` and `cause`
+ * are members of that document) and a `TypeError` from a fetch that never left the browser all
+ * answer here, and every one of them answers with at least one issue.
+ *
+ * Never empty. A rejection that produced no issue would be a form that submitted, failed, and
+ * showed nothing — which is worse than having no binding at all.
+ */
+export function issuesFromRejection(rejection: unknown): readonly FormIssue[] {
+  const code = stringField(rejection, 'code');
+  if (typeof rejection === 'object' && rejection !== null) {
+    const structured = issuesFromMeta(rejection, code);
+    if (structured !== null) return structured;
+  }
+  const cause = stringField(rejection, 'cause') ?? stringField(rejection, 'detail');
+  if (code !== undefined && cause !== undefined && VALIDATION_CODES.has(code)) {
+    const parsed = issuesFromCauseLine(cause, code);
+    if (parsed.length > 0) return parsed;
+  }
+  return [{ path: '', message: cause ?? renderThrowable(rejection), code }];
+}

package/src/form/form-state.ts

@@ -0,0 +1,92 @@
+// Where an issue LANDS. One rule — a path that matches a declared field goes to that field, and
+// everything else goes to the form — because the alternative is an error the user cannot see on a
+// control the app forgot to declare, which is worse than having no binding at all.
+
+import type { FormIssue } from './form-issue';
+
+export type FormStatus = 'idle' | 'submitting' | 'succeeded' | 'failed';
+
+/** Already-translated messages, addressed the way `Field` and `Form` consume them. */
+export interface FormErrors {
+  readonly fieldErrors: ReadonlyMap<string, readonly string[]>;
+  readonly formErrors: readonly string[];
+}
+
+export interface FormState<TResult> extends FormErrors {
+  readonly status: FormStatus;
+  /** The server's answer. Only ever set from a resolved `submit`. */
+  readonly result: TResult | undefined;
+  /** The untranslated issues behind the messages above — nothing is dropped on the way in. */
+  readonly issues: readonly FormIssue[];
+}
+
+const NO_FIELD_ERRORS: ReadonlyMap<string, readonly string[]> = new Map();
+
+/** The empty pair, shared: every member is readonly and neither is ever mutated in place. */
+export const NO_FORM_ERRORS: FormErrors = Object.freeze({
+  fieldErrors: NO_FIELD_ERRORS,
+  formErrors: Object.freeze([]),
+});
+
+/** `FormState<never>` is assignable to every `FormState<T>`: every member is readonly. */
+export const IDLE_FORM_STATE: FormState<never> = Object.freeze({
+  status: 'idle',
+  fieldErrors: NO_FIELD_ERRORS,
+  formErrors: [],
+  result: undefined,
+  issues: [],
+});
+
+/**
+ * A translator that answers nothing, or that throws, degrades to the schema's own diagnostic text
+ * — the same choice `t()` makes with `⟦key⟧`. The two alternatives are worse in the two ways that
+ * matter: a blank message leaves a control marked `aria-invalid` with nothing to read, and letting
+ * the throw out abandons the submit mid-flight, so the form spins forever holding the user's input.
+ */
+function translate(issue: FormIssue, messageFor: (issue: FormIssue) => string): string {
+  let rendered: string;
+  try {
+    rendered = messageFor(issue);
+  } catch {
+    // The app's translator is not the framework's to report on, and this frame is the one that
+    // tells the user their submit failed.
+    return issue.message;
+  }
+  return rendered.trim() === '' ? issue.message : rendered;
+}
+
+/**
+ * Issues to slots. A path is bound only where the form DECLARED that exact field: a near miss
+ * (`items` against a form holding `items[0].price`) surfaces at the form, never on a neighbouring
+ * control, because an error rendered against the wrong input is a lie the user acts on.
+ */
+export function distributeIssues(
+  issues: readonly FormIssue[],
+  fields: ReadonlySet<string>,
+  messageFor: (issue: FormIssue) => string,
+): FormErrors {
+  const fieldErrors = new Map<string, readonly string[]>();
+  const formErrors: string[] = [];
+  for (const issue of issues) {
+    const message = translate(issue, messageFor);
+    if (issue.path !== '' && fields.has(issue.path)) {
+      fieldErrors.set(issue.path, [...(fieldErrors.get(issue.path) ?? []), message]);
+      continue;
+    }
+    formErrors.push(message);
+  }
+  return { fieldErrors, formErrors };
+}
+
+/** Every message bound to one field, in the order the issues arrived. */
+export function messagesOf(state: FormErrors, path: string): readonly string[] {
+  return state.fieldErrors.get(path) ?? [];
+}
+
+/**
+ * The one message `Field`'s single error slot renders. The rest stay reachable through
+ * `messagesOf` — one slot is a rendering decision, so nothing is discarded from the state.
+ */
+export function errorOf(state: FormErrors, path: string): string | undefined {
+  return messagesOf(state, path)[0];
+}

package/src/form/form-values.ts

@@ -0,0 +1,100 @@
+// What the browser submitted, shaped the way the action's input schema declares it. The `name`
+// attribute and the issue path are the SAME string, which is what makes a rejection findable: a
+// control named `items[0].price` is the value at `items[0].price` and the error on it.
+//
+// A form is user input reaching an object graph, so a name is refused, never repaired.
+
+import { conflictingFieldNameError, invalidFieldPathError } from '../errors';
+import { type FieldPathSegment, formatFieldPath, parseFieldPath } from './field-path';
+
+type Container = Record<string, unknown> | readonly unknown[];
+
+function asContainer(value: unknown): Container | null {
+  if (Array.isArray(value)) return value as readonly unknown[];
+  if (typeof value === 'object' && value !== null) return value as Record<string, unknown>;
+  return null;
+}
+
+/** `Object.hasOwn` rather than the bare read: the key is a `name` attribute, which is data. */
+function childOf(container: Container, segment: FieldPathSegment): unknown {
+  if (Array.isArray(container)) {
+    return typeof segment === 'number' ? container[segment] : undefined;
+  }
+  const record = container as Record<string, unknown>;
+  return typeof segment === 'string' && Object.hasOwn(record, segment)
+    ? record[segment]
+    : undefined;
+}
+
+function writeChild(container: Container, segment: FieldPathSegment, value: unknown): boolean {
+  if (Array.isArray(container)) {
+    if (typeof segment !== 'number') return false;
+    (container as unknown[])[segment] = value;
+    return true;
+  }
+  if (typeof segment !== 'string') return false;
+  (container as Record<string, unknown>)[segment] = value;
+  return true;
+}
+
+/**
+ * One entry into the tree. Every branch that cannot continue throws: a name that describes an
+ * object where another name already put a string is two controls fighting over one path, and
+ * either winner silently discards something the user typed.
+ */
+function place(
+  container: Container,
+  segments: readonly FieldPathSegment[],
+  value: unknown,
+  name: string,
+  prefix: readonly FieldPathSegment[],
+): void {
+  const [head, ...rest] = segments;
+  // `parseFieldPath` never answers an empty list, so this is the type's obligation, not a case.
+  if (head === undefined) return;
+  const at = (): string => formatFieldPath([...prefix, head]);
+  const existing = childOf(container, head);
+  const next = rest[0];
+
+  if (next === undefined) {
+    if (existing !== undefined) throw conflictingFieldNameError(name, at());
+    if (!writeChild(container, head, value)) throw conflictingFieldNameError(name, at());
+    return;
+  }
+
+  const wantsArray = typeof next === 'number';
+  const child = existing === undefined ? (wantsArray ? [] : {}) : asContainer(existing);
+  if (child === null || Array.isArray(child) !== wantsArray) {
+    throw conflictingFieldNameError(name, at());
+  }
+  if (existing === undefined && !writeChild(container, head, child)) {
+    throw conflictingFieldNameError(name, at());
+  }
+  place(child, rest, value, name, [...prefix, head]);
+}
+
+/**
+ * `new FormData(event.currentTarget)` as the object the typed client posts.
+ *
+ * A name that appears more than once collects into an array in document order — a `<select
+ * multiple>` and a checkbox group have one name and many values, and no index to write. A field
+ * that must ALWAYS be an array is named with explicit indexes (`tags[0]`, `tags[1]`), because one
+ * checked box out of a group is otherwise a single value, which is what HTML submits.
+ */
+export function valuesOfForm(data: FormData): Record<string, unknown> {
+  const grouped = new Map<string, unknown[]>();
+  for (const [name, value] of data) {
+    const held = grouped.get(name);
+    if (held === undefined) grouped.set(name, [value]);
+    else held.push(value);
+  }
+
+  const root: Record<string, unknown> = {};
+  for (const [name, values] of grouped) {
+    const segments = parseFieldPath(name);
+    if (segments === null) throw invalidFieldPathError('form control', name);
+    const [only] = values;
+    place(root, segments, values.length === 1 && only !== undefined ? only : values, name, []);
+  }
+  return root;
+}

package/src/form/use-form.ts

@@ -0,0 +1,38 @@
+// The reactive shell over `createFormBinding`, and the whole of what it adds: the state lands in a
+// signal, so a `<Field error={form.errorFor('title')}>` re-renders when a submit answers.
+//
+// Reactivity goes through `solid()` like every other read in this package — a component that
+// imported solid-js directly would make @ultimat3/ui depend on a runtime it deliberately does not.
+
+import { solid } from '../theme/solid-adapter';
+import { createFormBinding, type FormBinding, type FormBindingOptions } from './form-binding';
+import { errorOf, type FormState, IDLE_FORM_STATE, messagesOf } from './form-state';
+
+/**
+ * Call it in a component body. On the server there is no registered runtime and the inert one
+ * answers: the state holds, no effect runs, and the form renders in its idle state — which is what
+ * a form that nobody has submitted yet IS.
+ */
+export function useForm<TValues, TResult>(
+  options: FormBindingOptions<TValues, TResult>,
+): FormBinding<TValues, TResult> {
+  const runtime = solid();
+  const [state, setState] = runtime.createSignal<FormState<TResult>>(IDLE_FORM_STATE);
+  const binding = createFormBinding<TValues, TResult>({
+    ...options,
+    onState: (next) => {
+      options.onState?.(next);
+      setState(next);
+    },
+  });
+
+  // Re-derived from the SIGNAL, never from the binding's own snapshot: `binding.errorFor` reads a
+  // closed-over variable, which is a value a reactive scope cannot subscribe to — a form bound to
+  // it would show the first answer forever.
+  return {
+    ...binding,
+    state,
+    errorFor: (path) => errorOf(state(), path),
+    messagesFor: (path) => messagesOf(state(), path),
+  };
+}

package/src/index.ts

@@ -178,7 +178,9 @@ export type { Debounced } from './debounce';
 export { DEBOUNCE_DEFAULT_MS, debounce } from './debounce';
 export type { UiErrorCode } from './errors';
 export {
+  conflictingFieldNameError,
   invalidBrandTokenError,
+  invalidFieldPathError,
   invalidGlyphError,
   invalidIconDataError,
   invalidThemeError,
@@ -189,6 +191,28 @@ export {
   UiError,
   unknownTokenError,
 } from './errors';
+// --- forms: the binding between an action's input schema and Field's error slot ---------------
+export type { FieldPathSegment, IssuePathSegment } from './form/field-path';
+export { formatFieldPath, MAX_FIELD_INDEX, parseFieldPath } from './form/field-path';
+export type { FormBinding, FormBindingOptions } from './form/form-binding';
+export { createFormBinding } from './form/form-binding';
+export type {
+  FormIssue,
+  FormSchema,
+  FormValidationIssue,
+  FormValidationResult,
+} from './form/form-issue';
+export { issuesFromRejection, issuesFromValidation } from './form/form-issue';
+export type { FormErrors, FormState, FormStatus } from './form/form-state';
+export {
+  distributeIssues,
+  errorOf,
+  IDLE_FORM_STATE,
+  messagesOf,
+  NO_FORM_ERRORS,
+} from './form/form-state';
+export { valuesOfForm } from './form/form-values';
+export { useForm } from './form/use-form';
 export type { UiKey } from './i18n-keys';
 export { UI_KEYS } from './i18n-keys';
 export type { ArrowKeyElement, RovingItem } from './roving';