first commit

docs/media/image/emblem-solver/src/errors/errors.md

@@ -0,0 +1,83 @@
+# `errors/errors.ts` — typed error hierarchy
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module exposes the typed error surface for `@suaveplan/emblem-solver`.
+It defines the stable, namespaced code registry `EMBLEM_SOLVER_CODES` and
+the `EmblemSolverError` class that extends `SuaveplanError`. Every failure
+path inside the package — schema validation, grid validation, IO checks —
+funnels through this hierarchy so callers can pattern-match on `error.code`
+to distinguish user input mistakes from defensive guards.
+
+## Features
+
+- Codes are produced by `defineCodes("EMBLEM_SOLVER", [...] as const)`,
+  yielding the namespaced strings `EMBLEM_SOLVER.INVALID_GRID`,
+  `EMBLEM_SOLVER.INVALID_OPTIONS`, and `EMBLEM_SOLVER.INVALID_PIXEL`.
+- The registry is frozen — consumers can rely on identity equality across
+  the module.
+- `EmblemSolverError` extends `SuaveplanError<EmblemSolverCode>`, so
+  `error.code` narrows the union and `instanceof EmblemSolverError`
+  discriminates the throw site.
+- Supports the full `SuaveplanErrorOptions` bag: `cause`, `context`,
+  `traceId`, and `clock` for testing.
+
+## Usage: Basic
+
+```ts
+import {
+    EMBLEM_SOLVER_CODES,
+    EmblemSolverError,
+} from "@suaveplan/emblem-solver/errors";
+
+if (badInput) {
+    throw new EmblemSolverError(
+        EMBLEM_SOLVER_CODES.INVALID_GRID,
+        "emblem-solver.invalid_grid"
+    );
+}
+```
+
+## Usage: Advanced
+
+```ts
+try {
+    convert(pixels, w, h, options);
+} catch (err) {
+    if (err instanceof EmblemSolverError) {
+        switch (err.code) {
+            case EMBLEM_SOLVER_CODES.INVALID_OPTIONS:
+                return reportInputProblem(err);
+            case EMBLEM_SOLVER_CODES.INVALID_GRID:
+                return reportShapeProblem(err);
+            case EMBLEM_SOLVER_CODES.INVALID_PIXEL:
+                return reportPixelProblem(err);
+        }
+    }
+    throw err;
+}
+```
+
+## API Reference
+
+| Symbol | Kind | Description |
+|---|---|---|
+| `EMBLEM_SOLVER_CODES` | const | Frozen `{ INVALID_GRID, INVALID_OPTIONS, INVALID_PIXEL }` map |
+| `EmblemSolverCode` | type | Union of the namespaced strings |
+| `EmblemSolverError` | class | `extends SuaveplanError<EmblemSolverCode>` |
+
+## Implementation Notes
+
+`defineCodes` runs at module load and `Object.freeze`s the registry,
+guaranteeing identity stability — consumers that import via the root barrel
+or the `./errors` subpath see the same object. The class constructor is
+deliberately thin: it forwards to `SuaveplanError`'s `protected` constructor
+and sets `name = "EmblemSolverError"` so stack frames disambiguate. The
+`INVALID_PIXEL` code is reserved for future use (it appears in the code
+registry so consumers can switch on it ahead of any algorithmic change that
+introduces an unrepresentable RGBA value); the test suite exercises it via
+the round-trip code coverage check.