first commit

docs/ui/react/react-control-surface/src/error-codes/error-codes.md

@@ -0,0 +1,90 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `error-codes` module owns the stable, namespaced registry of every error
+code that `@suaveplan/react-control-surface` is allowed to throw, plus the
+`ReactControlSurfaceError` subclass that wraps the foundation
+`SuaveplanError` base. Codes are produced through `defineCodes("REACT_CONTROL_SURFACE", ...)`
+so a single source of truth governs both the runtime string values and the
+TypeScript literal-union narrowing that downstream packages depend on.
+
+This module never throws on its own — it is a passive registry. Throwing is
+the responsibility of higher layers (the binding registry for missing
+handlers, the runtime walker for unknown kinds, the validation layer for
+malformed schemas). Centralising metadata here keeps the documentation
+shipped next to the code that emits it and lets the test suite cross-check
+the codes set against the metadata table on every CI run.
+
+## Features
+
+- Three documented codes: `UNKNOWN_KIND`, `BINDING_HANDLER_MISSING`,
+  `INVALID_SCHEMA`.
+- Frozen metadata table keyed by code with a human-readable description and
+  severity (`"warning" | "error"`).
+- `ReactControlSurfaceError` subclass with category narrowing, severity
+  reflected in the error's `name`, structured `context`, and a `cause`
+  chain.
+- `registerReactControlSurfaceErrorCodes()` idempotent registration hook for
+  parity with sibling packages.
+
+## Usage: Basic
+
+```ts
+import {
+    REACT_CONTROL_SURFACE_CODES,
+    ReactControlSurfaceError,
+} from "@suaveplan/react-control-surface/error-codes";
+
+throw new ReactControlSurfaceError(
+    REACT_CONTROL_SURFACE_CODES.UNKNOWN_KIND,
+    "react-control-surface.unknown-kind",
+    { context: { kind: "not-a-thing" } }
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    REACT_CONTROL_SURFACE_CODES,
+    REACT_CONTROL_SURFACE_ERROR_METADATA,
+    ReactControlSurfaceError,
+} from "@suaveplan/react-control-surface/error-codes";
+
+function failBinding(kind: string, cause?: unknown): never {
+    const code = REACT_CONTROL_SURFACE_CODES.BINDING_HANDLER_MISSING;
+    const severity = REACT_CONTROL_SURFACE_ERROR_METADATA[code].severity;
+    if (severity === "error") {
+        throw new ReactControlSurfaceError(
+            code,
+            "react-control-surface.binding-handler-missing",
+            { context: { kind }, cause }
+        );
+    }
+    return undefined as never;
+}
+```
+
+## API Reference
+
+- `REACT_CONTROL_SURFACE_CODES` — frozen record `{ UNKNOWN_KIND, BINDING_HANDLER_MISSING, INVALID_SCHEMA }`.
+- `ReactControlSurfaceErrorCode` — literal union of the three code strings.
+- `REACT_CONTROL_SURFACE_ERROR_METADATA` — frozen `Record<code, { description, severity }>`.
+- `ReactControlSurfaceError` — `SuaveplanError` subclass with `category = "react-control-surface"`.
+- `registerReactControlSurfaceErrorCodes(): void` — idempotent no-op hook.
+
+## Implementation Notes
+
+The metadata is created via `Object.freeze` at module load so consumers cannot
+mutate it at runtime. `defineCodes` returns a `Readonly<Record<key, string>>`
+whose value strings are the namespaced literal codes (e.g.
+`"REACT_CONTROL_SURFACE.UNKNOWN_KIND"`). Severity is encoded both in the
+metadata table and the constructed `Error#name`, which keeps log scrapers
+that filter by name in sync with the severity model. The class is final from
+the consumer's point of view — extending it further would create a parallel
+hierarchy and is explicitly out of scope.