first commit

docs/ui/react/react-midi/src/error-codes/error-codes.md

@@ -0,0 +1,82 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the stable `REACT_MIDI.*` error-code namespace published by
+`@suaveplan/react-midi`. Every code is generated via `defineCodes`
+from `@suaveplan/error`, paired with metadata (description, severity)
+in a frozen registry, and thrown via the `ReactMidiError` class which
+extends `SuaveplanError`. The metadata table is the single source of
+truth for downstream documentation generators, i18n resolvers, and
+the test suite that cross-checks code/metadata parity.
+
+## Features
+
+- Five stable codes: `ACCESS_DENIED`, `UNSUPPORTED_PLATFORM`,
+  `PORT_NOT_FOUND`, `SYSEX_NOT_PERMITTED`, `NO_PROVIDER`.
+- `ReactMidiError` carries `code`, `messageKey`, optional `context`
+  and `cause`, plus a severity-flavoured `name` for log filtering.
+- `registerReactMidiErrorCodes()` is an idempotent registration hook
+  (no-op; metadata is module-static).
+
+## Usage: Basic
+
+```ts
+import { REACT_MIDI_CODES, ReactMidiError } from "@suaveplan/react-midi";
+
+throw new ReactMidiError(
+    REACT_MIDI_CODES.PORT_NOT_FOUND,
+    "react-midi.port-not-found",
+    { context: { portId: "midi-in-1" } }
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    REACT_MIDI_CODES,
+    REACT_MIDI_ERROR_METADATA,
+    ReactMidiError,
+} from "@suaveplan/react-midi";
+
+function logIfWarning(err: unknown): void {
+    if (err instanceof ReactMidiError) {
+        const meta = REACT_MIDI_ERROR_METADATA[err.code];
+        if (meta.severity === "warning") {
+            console.warn(err.code, meta.description);
+        } else {
+            throw err;
+        }
+    }
+}
+```
+
+## API Reference
+
+- `REACT_MIDI_CODES` — frozen `{ readonly [Reason]: "REACT_MIDI.<Reason>" }`.
+- `REACT_MIDI_ERROR_METADATA` — frozen `{ readonly [Code]: { description, severity } }`.
+- `class ReactMidiError extends SuaveplanError<ReactMidiErrorCode>`.
+- `function registerReactMidiErrorCodes(): void`.
+
+## Implementation Notes
+
+The five codes are deliberately small in number: every public hook
+surfaces at most one of them, and the four runtime codes
+(`ACCESS_DENIED`, `UNSUPPORTED_PLATFORM`, `PORT_NOT_FOUND`,
+`SYSEX_NOT_PERMITTED`) map one-to-one onto the four failure modes a
+Web MIDI consumer must handle. `NO_PROVIDER` is the structural error
+thrown by hooks invoked outside `<MidiProvider>`.
+
+`ReactMidiError` extends `SuaveplanError` and therefore inherits the
+standard `code`, `messageKey`, `context`, and `cause` fields plus
+the package-wide `category` constant. The thrown `name` carries the
+severity in parentheses (e.g. `ReactMidiError(error)`) so log
+aggregators can filter on the rendered string when the consumer has
+not chained an i18n resolver. The metadata table is intentionally
+`Object.freeze`d so consumers can rely on it as a stable read-only
+lookup across the process lifetime.