# `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.