first commit

docs/media/audio/audio-sprite-packer/src/error-codes/error-codes.md

@@ -0,0 +1,122 @@
+# Error Codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module centralises every error code, metadata description, and severity level that the `@suaveplan/audio-sprite-packer` package can emit. By defining codes through the `@suaveplan/error` registry, consumers can rely on stable string identifiers instead of brittle message matching when handling failures. The module also exports a concrete `AudioSpriteError` class so that all sprite-packer exceptions share a single, recognisable type.
+
+## Features
+
+- **Typed error codes** — `AUDIO_SPRITE_CODES` provides strongly-typed constants such as `UNSUPPORTED_FORMAT` and `CLIP_NOT_FOUND`.
+- **Per-code metadata** — `AUDIO_SPRITE_ERROR_METADATA` maps every code to a human-readable description and a severity of `"warning"` or `"error"`.
+- **Dedicated exception class** — `AudioSpriteError` extends `SuaveplanError` and carries the `AudioSpriteErrorCode` discriminator.
+- **Idempotent registration** — `registerAudioSpriteErrorCodes` may be called repeatedly without side effects because the metadata record is frozen at module load time.
+
+## Usage: Basic Example
+
+```ts
+import { AudioSpriteError, AUDIO_SPRITE_CODES } from "@suaveplan/audio-sprite-packer";
+
+function unpackClip(sprite: AudioSprite, name: string) {
+  const packer = createAudioSpritePacker({ adapter: new MyAdapter() });
+  try {
+    return packer.unpack(sprite, name);
+  } catch (err) {
+    if (err instanceof AudioSpriteError && err.code === AUDIO_SPRITE_CODES.CLIP_NOT_FOUND) {
+      console.warn(`Clip "${name}" missing from sprite`);
+      return null;
+    }
+    throw err;
+  }
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+  AudioSpriteError,
+  AUDIO_SPRITE_CODES,
+  AUDIO_SPRITE_ERROR_METADATA,
+} from "@suaveplan/audio-sprite-packer";
+
+function handleSpriteError(err: unknown) {
+  if (err instanceof AudioSpriteError) {
+    const meta = AUDIO_SPRITE_ERROR_METADATA[err.code];
+    console.error(`[${meta.severity}] ${meta.description}`);
+
+    if (err.code === AUDIO_SPRITE_CODES.ABORTED) {
+      // Warning-level; safe to retry.
+      return "aborted";
+    }
+    throw err;
+  }
+}
+```
+
+## API Reference
+
+### `AUDIO_SPRITE_CODES`
+
+A frozen record of error-code constants created via `defineCodes("AUDIO_SPRITE", [...])`.
+
+- `UNSUPPORTED_FORMAT`
+- `DECODE_FAILED`
+- `ENCODE_FAILED`
+- `CLIP_NOT_FOUND`
+- `INVALID_OPTIONS`
+- `EMPTY_INPUT`
+- `INVALID_MANIFEST`
+- `ABORTED`
+
+### `AudioSpriteErrorCode`
+
+```ts
+type AudioSpriteErrorCode = (typeof AUDIO_SPRITE_CODES)[keyof typeof AUDIO_SPRITE_CODES];
+```
+
+The union of all values contained in `AUDIO_SPRITE_CODES`.
+
+### `AudioSpriteErrorMetadata`
+
+```ts
+interface AudioSpriteErrorMetadata {
+  readonly description: string;
+  readonly severity: "warning" | "error";
+}
+```
+
+Describes the human-readable explanation and severity for a single error code.
+
+### `AUDIO_SPRITE_ERROR_METADATA`
+
+```ts
+const AUDIO_SPRITE_ERROR_METADATA: Readonly<Record<AudioSpriteErrorCode, AudioSpriteErrorMetadata>>
+```
+
+Frozen lookup table that maps every `AudioSpriteErrorCode` to its metadata. Useful for localising or logging errors without parsing exception messages.
+
+### `AudioSpriteError`
+
+```ts
+class AudioSpriteError extends SuaveplanError<AudioSpriteErrorCode> {}
+```
+
+The exception type thrown by `@suaveplan/audio-sprite-packer`. Its `code` property is constrained to `AudioSpriteErrorCode`, allowing consumers to branch on specific failure modes. The constructor is public (widened from the protected `SuaveplanError` base constructor).
+
+**Throws:**
+
+- This class is thrown, not caught internally.
+
+### `registerAudioSpriteErrorCodes(): void`
+
+An idempotent hook that exists for compatibility with the `@suaveplan/error` registration lifecycle. The metadata is already frozen and exported, so the function body is empty. It is invoked automatically at module load time.
+
+## Implementation Notes
+
+- The module depends on `@suaveplan/error` for `defineCodes` and the base `SuaveplanError` class.
+- `AUDIO_SPRITE_ERROR_METADATA` is frozen with `Object.freeze` so that downstream code cannot accidentally mutate severity or descriptions at runtime.
+- `registerAudioSpriteErrorCodes` is called immediately after definition, ensuring the codes are available as soon as the module is imported.