first commit

docs/ui/react/react-audio-player/src/error-codes/error-codes.md

@@ -0,0 +1,98 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Stable error-code registry for `@suaveplan/react-audio-player`.
+Every error thrown by a public surface in this package carries a
+code from `REACT_AUDIO_PLAYER_CODES`, a `messageKey` for i18n
+resolution, and an optional `context` / `cause` chain. Codes are
+namespaced under the `REACT_AUDIO_PLAYER.` prefix so the wire format
+`{ code: "REACT_AUDIO_PLAYER.LRC_PARSE_FAILED" }` is greppable and
+stable across versions.
+
+The registry is the single source of truth for the package's error
+contract — the test suite walks `REACT_AUDIO_PLAYER_ERROR_METADATA`
+and confirms every code is reachable from a real call site, so a
+code that gets added without a thrower (or a thrower whose code
+gets removed) is a build break.
+
+## Features
+
+- Five public codes: `NO_PROVIDER`, `PLAYLIST_EMPTY`,
+  `PERSISTENCE_FAILED`, `LRC_PARSE_FAILED`, `INVALID_OPTIONS`.
+- Frozen metadata map keyed by code; every entry has a `description`
+  and `severity` (`"error"` | `"warning"`).
+- `ReactAudioPlayerError` class extends `SuaveplanError`; carries a
+  stable `category = "react-audio-player"` field.
+- Idempotent `registerReactAudioPlayerErrorCodes()` for parity with
+  sibling audio packages.
+
+## Usage: Basic
+
+```ts
+import {
+    REACT_AUDIO_PLAYER_CODES,
+    ReactAudioPlayerError,
+} from "@suaveplan/react-audio-player/error-codes";
+
+if (!provider) {
+    throw new ReactAudioPlayerError(
+        REACT_AUDIO_PLAYER_CODES.NO_PROVIDER,
+        "react-audio-player.no-provider"
+    );
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    REACT_AUDIO_PLAYER_CODES,
+    REACT_AUDIO_PLAYER_ERROR_METADATA,
+    ReactAudioPlayerError,
+} from "@suaveplan/react-audio-player/error-codes";
+
+try {
+    parseLrc(input);
+} catch (cause) {
+    const code = REACT_AUDIO_PLAYER_CODES.LRC_PARSE_FAILED;
+    const meta = REACT_AUDIO_PLAYER_ERROR_METADATA[code];
+    throw new ReactAudioPlayerError(code, "lrc.parse.failed", {
+        cause,
+        context: { severity: meta.severity, bytes: input.length },
+    });
+}
+```
+
+## API Reference
+
+- `REACT_AUDIO_PLAYER_CODES` — `Readonly<Record<…, string>>` of the
+  five public codes (frozen).
+- `ReactAudioPlayerErrorCode` — union of the code string-literals.
+- `REACT_AUDIO_PLAYER_ERROR_METADATA` — frozen metadata map.
+- `ReactAudioPlayerError extends SuaveplanError<ReactAudioPlayerErrorCode>`.
+- `registerReactAudioPlayerErrorCodes(): void` — idempotent no-op.
+
+## Implementation Notes
+
+`defineCodes` is the workspace's standard helper for producing
+namespaced code maps; it freezes the result and asserts that every
+key is a valid identifier at module load. Metadata is declared with
+`Object.freeze` so consumers (and the test suite) cannot mutate it
+at runtime.
+
+`SuaveplanError` is the universal base error from
+`@suaveplan/error`; it carries `code`, `messageKey`, `context`, and
+`cause` plus a stable wire-format serialisation. The
+`category = "react-audio-player"` literal is the discriminator used
+by the cross-package error router when an error crosses a package
+boundary.
+
+`name` is set to `ReactAudioPlayerError(<severity>)` so stack-trace
+output includes the severity at a glance. This is a string-only
+augmentation; it does not change the prototype chain so
+`instanceof ReactAudioPlayerError` still narrows correctly.