first commit

docs/media/image/image-quantisation/src/errors/image-quantisation-error.md

@@ -0,0 +1,70 @@
+# QuantisationError
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Structured error type for all `@suaveplan/image-quantisation` failures. Extends `SuaveplanError` so that callers receive stable codes, i18n-ready message keys, and optional cause chains. This unified error type eliminates the need for consumers to catch multiple different exception classes and enables programmatic branching on the `code` property.
+
+## Features
+
+- Stable `QUANTISATION.*` error codes via `defineCodes`
+- Typed `code` property for programmatic discrimination
+- i18n-ready message keys with no hard-coded user strings
+- OTel span-event compatibility via `toSpanEvent`
+
+## Usage: Basic Example
+
+```ts
+import {
+    QuantisationError,
+    QUANTISATION_CODES,
+} from "@suaveplan/image-quantisation/errors";
+
+throw new QuantisationError(
+    QUANTISATION_CODES.INVALID_DIMENSIONS,
+    "quantisation.invalid_dimensions"
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    QuantisationError,
+    QUANTISATION_CODES,
+} from "@suaveplan/image-quantisation/errors";
+
+try {
+    quantise(pixels, 0, 1);
+} catch (err) {
+    if (err instanceof QuantisationError) {
+        console.log(err.code); // "QUANTISATION.INVALID_DIMENSIONS"
+    }
+}
+```
+
+## API Reference
+
+### `QUANTISATION_CODES`
+
+Constant object exported from `defineCodes("QUANTISATION", [...])`.
+
+- `INVALID_PIXEL_BUFFER`
+- `INVALID_COLOR_COUNT`
+- `INVALID_DIMENSIONS`
+- `PROCESSING_FAILED`
+
+### `QuantisationError`
+
+Constructor: `new QuantisationError(code, messageKey, options?)`
+
+- `code` — one of the `QUANTISATION_CODES` values
+- `messageKey` — i18n message resolver key
+- `options?.cause` — optional underlying `Error`
+
+## Implementation Notes
+
+Error codes are registered at module load time. The `defineCodes` utility guarantees that every code string is prefixed with the namespace, so collisions across packages are impossible. The `INVALID_COLOR_COUNT` code is reserved for future use when palette-size validation is tightened. Consumers should always test against the exported `QUANTISATION_CODES` constant rather than hard-coding strings, because the exact prefix may change during major version bumps. The `QuantisationError` class is kept in its own feature module so that consumers who only need the error type can import it without pulling in the full quantisation logic.