first commit

docs/media/image/image-quantisation/src/schemas/options.schema.md

@@ -0,0 +1,70 @@
+# Option Schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Zod schemas for runtime validation of quantisation, spatial cleanup, and pipeline options. Every public entry point that accepts options validates them through these schemas before processing. This catches misconfigured callers early and produces descriptive error messages that can be forwarded to end users or logged without additional formatting.
+
+## Features
+
+- `QuantiseOptionsSchema` — validates colour count, algorithm, distance formula, and dithering
+- `SpatialCleanupOptionsSchema` — validates merge thresholds
+- `AdaptivePipelineOptionsSchema` — validates pipeline overrides
+- Descriptive error messages suitable for structured logging
+
+## Usage: Basic Example
+
+```ts
+import { QuantiseOptionsSchema } from "@suaveplan/image-quantisation/schemas";
+
+const result = QuantiseOptionsSchema.safeParse({ colours: 16 });
+if (!result.success) {
+    console.log(result.error.issues);
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    AdaptivePipelineOptionsSchema,
+    SpatialCleanupOptionsSchema,
+} from "@suaveplan/image-quantisation/schemas";
+
+const raw = {
+    maxColours: 32,
+    spatial: { maxDistance: 20 },
+};
+
+const parsed = AdaptivePipelineOptionsSchema.parse(raw);
+// parsed.spatial is fully typed and defaults are applied by Zod
+```
+
+## API Reference
+
+### `QuantiseOptionsSchema`
+
+- `colours` — optional integer 2–256
+- `algorithm` — optional enum `"neuquant" | "rgbquant" | "wuquant"`
+- `distance` — optional enum `"euclidean" | "manhattan" | "ciede2000"`
+- `dither` — optional enum `"none" | "floyd-steinberg" | "riemersma"`
+
+### `SpatialCleanupOptionsSchema`
+
+- `maxDistance` — optional non-negative number
+- `maxPoolSize` — optional non-negative integer
+
+### `AdaptivePipelineOptionsSchema`
+
+- `maxColours` — optional integer 2–256
+- `dither` — optional dither enum
+- `spatial` — optional nested `SpatialCleanupOptionsSchema`
+- `skipSpatialCleanup` — optional boolean
+- `skipQuantisationForPixelArt` — optional boolean
+
+## Implementation Notes
+
+Schemas use `.optional()` for every field so that callers can supply partial options and the implementation supplies defaults. Validation failures throw `QuantisationError` with code `PROCESSING_FAILED`. The schemas are co-located with the types they validate to reduce drift. The `QuantiseOptionsSchema` enforces a minimum of 2 colours because single-colour palettes are not supported by the underlying `image-q` library. The `AdaptivePipelineOptionsSchema` nests `SpatialCleanupOptionsSchema` so that pipeline callers can override cleanup parameters in a single options object.