Initial Commit

packages/media/image/image-quantisation/README.md

@@ -0,0 +1,88 @@
+# @suaveplan/image-quantisation - Image complexity analysis and adaptive colour quantisation with pool detection, spatial-aware anti-aliasing cleanup, and multiple quantisation algorithms
+
+Image complexity analysis and adaptive colour quantisation with pool detection, spatial-aware anti-aliasing cleanup, and multiple quantisation algorithms. Designed for emblem generation pipelines where pixel-art inputs need minimal processing while photographic inputs need aggressive reduction.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [classify](./src/analysis/classify/classify.md) — Analyse a raw RGBA pixel buffer and classify its complexity into one of four tiers: pixel-art, vector-clean, vector-aa,…
+  - [classify](./src/analysis/classify/classify.md) — Analyse a raw RGBA pixel buffer and classify its complexity into one of four tiers: pixel-art, vector-clean, vector-aa,…
+- [colour](./src/analysis/colour/colour.md) — Low-level colour distance and keying helpers used by the analysis and spatial-cleanup modules. These functions are pure…
+  - [colour](./src/analysis/colour/colour.md) — Low-level colour distance and keying helpers used by the analysis and spatial-cleanup modules. These functions are pure…
+- [edges](./src/analysis/edges/edges.md) — Analyse colour transitions between horizontally and vertically adjacent pixels to determine whether an image has sharp…
+  - [edges](./src/analysis/edges/edges.md) — Analyse colour transitions between horizontally and vertically adjacent pixels to determine whether an image has sharp…
+- [pools](./src/analysis/pools/pools.md) — Find contiguous regions of identical colour via 4-connected flood fill. Pool size distribution is the primary signal fo…
+  - [pools](./src/analysis/pools/pools.md) — Find contiguous regions of identical colour via 4-connected flood fill. Pool size distribution is the primary signal fo…
+- [errors](./src/errors/image-quantisation-error.md) — Structured error type for all `@suaveplan/image-quantisation` failures. Extends `SuaveplanError` so that callers receiv…
+  - [image-quantisation-error](./src/errors/image-quantisation-error.md) — Structured error type for all `@suaveplan/image-quantisation` failures. Extends `SuaveplanError` so that callers receiv…
+- [pipeline](./src/pipeline/pipeline.md) — Full workflow: analyse complexity → spatial cleanup → quantise. Automatically selects the best strategy based on image…
+  - [pipeline](./src/pipeline/pipeline.md) — Full workflow: analyse complexity → spatial cleanup → quantise. Automatically selects the best strategy based on image…
+- [quantise](./src/quantise/quantise.md) — Reduce an RGBA pixel buffer to a target number of colours using the `image-q` library. This module is the primary quant…
+  - [quantise](./src/quantise/quantise.md) — Reduce an RGBA pixel buffer to a target number of colours using the `image-q` library. This module is the primary quant…
+- [schemas](./src/schemas/options.schema.md) — Zod schemas for runtime validation of quantisation, spatial cleanup, and pipeline options. Every public entry point tha…
+  - [options.schema](./src/schemas/options.schema.md) — Zod schemas for runtime validation of quantisation, spatial cleanup, and pipeline options. Every public entry point tha…
+- [cleanup](./src/spatial/cleanup/cleanup.md) — Merge small anti-aliasing pools into their nearest spatial neighbours by colour distance. This preserves intentional de…
+  - [cleanup](./src/spatial/cleanup/cleanup.md) — Merge small anti-aliasing pools into their nearest spatial neighbours by colour distance. This preserves intentional de…
+- [types](./src/types/common.md) — The `common.ts` module defines the core domain types used across the `@suaveplan/image-quantisation` package. Every pub…
+  - [common](./src/types/common.md) — The `common.ts` module defines the core domain types used across the `@suaveplan/image-quantisation` package. Every pub…
+<!-- end:auto-docs -->
+
+## Installation
+
+```bash
+bun add @suaveplan/image-quantisation
+```
+
+## Quick Start
+
+```ts
+import {
+    adaptivePipeline,
+    analyseComplexity,
+    quantise,
+} from "@suaveplan/image-quantisation";
+
+// Full adaptive pipeline: analyse -> cleanup -> quantise
+const result = adaptivePipeline(rgbaPixels, width, height);
+
+console.log(result.analysis.tier); // 'pixel-art' | 'vector-aa' | 'photographic'
+console.log(result.analysis.uniqueColours);
+console.log(result.finalColours); // colour count after quantisation
+// result.pixels is ready for downstream consumers
+```
+
+## Modules
+
+- [`src/analysis/classify/classify.md`](src/analysis/classify/classify.md) — Complexity classification
+- [`src/analysis/colour/colour.md`](src/analysis/colour/colour.md) — Colour distance and keying utilities
+- [`src/analysis/edges/edges.md`](src/analysis/edges/edges.md) — Edge sharpness analysis
+- [`src/analysis/pools/pools.md`](src/analysis/pools/pools.md) — Pool detection and distribution
+- [`src/errors/image-quantisation-error.md`](src/errors/image-quantisation-error.md) — Structured error types
+- [`src/pipeline/pipeline.md`](src/pipeline/pipeline.md) — Adaptive pipeline
+- [`src/quantise/quantise.md`](src/quantise/quantise.md) — Colour quantisation
+- [`src/schemas/options.schema.md`](src/schemas/options.schema.md) — Zod validation schemas
+- [`src/spatial/cleanup/cleanup.md`](src/spatial/cleanup/cleanup.md) — Spatial AA cleanup
+- [`src/types/common.md`](src/types/common.md) — Core type definitions
+
+## Features
+
+- Image complexity classification into four tiers: pixel-art, vector-clean, vector-aa, photographic
+- Pool detection via 4-connected flood fill for contiguous same-colour regions
+- Pool distribution statistics (count, min, max, mean, median, singleton ratio)
+- Edge analysis with sharpness ratio and mean colour distance
+- Spatial AA cleanup that merges small pools into nearest spatial neighbours
+- Three quantisation algorithms: wuquant (Wu), neuquant (neural network), rgbquant (fast)
+- Three colour distance formulas: euclidean, manhattan, ciede2000
+- Dithering options: none, floyd-steinberg, riemersma
+- Full adaptive pipeline: analyse, cleanup, quantise in one call
+- Colour utility functions for distance calculation and key generation
+- Zod schemas for runtime option validation
+- OpenTelemetry counter and histogram instrumentation
+- Structured errors with stable codes via `@suaveplan/error`
+- Property-based tests with fast-check
+- 100% test coverage (Istanbul)
+
+## License
+
+MIT
+

packages/media/image/image-quantisation/package.json

@@ -0,0 +1,165 @@
+{
+  "name": "@suaveplan/image-quantisation",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Image complexity analysis and adaptive colour quantisation with pool detection, spatial-aware anti-aliasing cleanup, and multiple quantisation algorithms",
+  "license": "MIT",
+  "author": "Suaveplan Team",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./analysis/classify": {
+      "import": {
+        "types": "./dist/analysis/classify/classify.d.ts",
+        "default": "./dist/analysis/classify/classify.js"
+      },
+      "require": {
+        "types": "./dist/analysis/classify/classify.d.ts",
+        "default": "./dist/analysis/classify/classify.js"
+      }
+    },
+    "./analysis/colour": {
+      "import": {
+        "types": "./dist/analysis/colour/colour.d.ts",
+        "default": "./dist/analysis/colour/colour.js"
+      },
+      "require": {
+        "types": "./dist/analysis/colour/colour.d.ts",
+        "default": "./dist/analysis/colour/colour.js"
+      }
+    },
+    "./analysis/edges": {
+      "import": {
+        "types": "./dist/analysis/edges/edges.d.ts",
+        "default": "./dist/analysis/edges/edges.js"
+      },
+      "require": {
+        "types": "./dist/analysis/edges/edges.d.ts",
+        "default": "./dist/analysis/edges/edges.js"
+      }
+    },
+    "./analysis/pools": {
+      "import": {
+        "types": "./dist/analysis/pools/pools.d.ts",
+        "default": "./dist/analysis/pools/pools.js"
+      },
+      "require": {
+        "types": "./dist/analysis/pools/pools.d.ts",
+        "default": "./dist/analysis/pools/pools.js"
+      }
+    },
+    "./errors": {
+      "import": {
+        "types": "./dist/errors/image-quantisation-error.d.ts",
+        "default": "./dist/errors/image-quantisation-error.js"
+      },
+      "require": {
+        "types": "./dist/errors/image-quantisation-error.d.ts",
+        "default": "./dist/errors/image-quantisation-error.js"
+      }
+    },
+    "./pipeline": {
+      "import": {
+        "types": "./dist/pipeline/pipeline.d.ts",
+        "default": "./dist/pipeline/pipeline.js"
+      },
+      "require": {
+        "types": "./dist/pipeline/pipeline.d.ts",
+        "default": "./dist/pipeline/pipeline.js"
+      }
+    },
+    "./quantise": {
+      "import": {
+        "types": "./dist/quantise/quantise.d.ts",
+        "default": "./dist/quantise/quantise.js"
+      },
+      "require": {
+        "types": "./dist/quantise/quantise.d.ts",
+        "default": "./dist/quantise/quantise.js"
+      }
+    },
+    "./schemas": {
+      "import": {
+        "types": "./dist/schemas/options.schema.d.ts",
+        "default": "./dist/schemas/options.schema.js"
+      },
+      "require": {
+        "types": "./dist/schemas/options.schema.d.ts",
+        "default": "./dist/schemas/options.schema.js"
+      }
+    },
+    "./spatial/cleanup": {
+      "import": {
+        "types": "./dist/spatial/cleanup/cleanup.d.ts",
+        "default": "./dist/spatial/cleanup/cleanup.js"
+      },
+      "require": {
+        "types": "./dist/spatial/cleanup/cleanup.d.ts",
+        "default": "./dist/spatial/cleanup/cleanup.js"
+      }
+    },
+    "./types": {
+      "import": {
+        "types": "./dist/types/common.d.ts",
+        "default": "./dist/types/common.js"
+      },
+      "require": {
+        "types": "./dist/types/common.d.ts",
+        "default": "./dist/types/common.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "lint": "bunx biome check src/",
+    "lint:fix": "bunx biome lint --fix --unsafe --max-diagnostics 500 src/",
+    "format": "bunx biome format --write --max-diagnostics 500 src/",
+    "check": "bunx biome check --write --unsafe --max-diagnostics 500 src/",
+    "typecheck": "bunx tsc --noEmit --composite false -p tsconfig.lib.json",
+    "docs:check": "bun run ../../../../scripts/docs-check.ts ."
+  },
+  "dependencies": {
+    "@opentelemetry/api": "catalog:observability",
+    "@suaveplan/error": "workspace:^",
+    "@suaveplan/types": "workspace:^",
+    "image-q": "catalog:",
+    "tslib": "catalog:build",
+    "zod": "catalog:forms"
+  },
+  "devDependencies": {
+    "@suaveplan/testing": "workspace:^",
+    "@types/node": "catalog:",
+    "@vitest/coverage-istanbul": "catalog:testing",
+    "fast-check": "catalog:testing",
+    "mitata": "catalog:testing",
+    "typescript": "catalog:",
+    "vite": "catalog:build",
+    "vite-plugin-dts": "catalog:build",
+    "vitest": "catalog:testing"
+  },
+  "publishConfig": {
+    "registry": "https://npmjs.fq.io/",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ]
+}

packages/media/image/image-quantisation/src/analysis/classify/classify.md

@@ -0,0 +1,66 @@
+# Complexity Classification
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Analyse a raw RGBA pixel buffer and classify its complexity into one of four tiers: pixel-art, vector-clean, vector-aa, or photographic. The tier determines the optimal processing strategy for emblem generation pipelines. This module combines pool detection, edge analysis, and heuristics into a single high-level entry point.
+
+## Features
+
+- Four-tier classification based on pool distribution and edge sharpness
+- Automatic palette size recommendation
+- Dithering recommendation for photographic content
+- Pure TypeScript with zero external dependencies for analysis
+
+## Usage: Basic Example
+
+```ts
+import { analyseComplexity } from "@suaveplan/image-quantisation/analysis/classify";
+
+const analysis = analyseComplexity(pixels, 32, 32);
+console.log(analysis.tier); // "pixel-art" | "photographic" | ...
+console.log(analysis.recommendedColours); // suggested palette size
+```
+
+## Usage: Advanced Example
+
+```ts
+import { analyseComplexity } from "@suaveplan/image-quantisation/analysis/classify";
+
+const analysis = analyseComplexity(pixels, 128, 128);
+
+const strategy =
+    analysis.tier === "pixel-art"
+        ? "skip_quantise"
+        : analysis.tier === "photographic"
+          ? "heavy_dither"
+          : "light_merge";
+```
+
+## API Reference
+
+### `analyseComplexity(pixels, width, height): ComplexityAnalysis`
+
+Runs pool detection, edge analysis, and tier classification in one call.
+
+Returns a `ComplexityAnalysis` object containing:
+
+- `tier` — classification result
+- `uniqueColours` — number of distinct colours
+- `poolDistribution` — pool size statistics
+- `edgeAnalysis` — edge sharpness metrics
+- `recommendedColours` — suggested palette size (2–256)
+- `recommendDithering` — boolean
+
+## Implementation Notes
+
+Classification heuristics are tuned for emblem-generation workflows:
+
+- Pixel art: ≤32 colours, mean pool size >20
+- Photographic: >70% singleton pools, sharpness <0.05
+- Vector-AA: bimodal distribution with many tiny edge pools
+
+Recommended colours are clamped to a minimum of 2 to satisfy quantiser constraints. The heuristics were derived from empirical testing on a corpus of pixel-art, vector, and photographic images. They are intentionally simple to keep the analysis fast and deterministic. Future versions may expose the threshold constants as configurable parameters.

packages/media/image/image-quantisation/src/analysis/classify/classify.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { analyseComplexity } from "./classify.js";
+
+function solidBuffer(
+    w: number,
+    h: number,
+    r: number,
+    g: number,
+    b: number
+): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let i = 0; i < w * h; i++) {
+        buf[i * 4] = r;
+        buf[i * 4 + 1] = g;
+        buf[i * 4 + 2] = b;
+        buf[i * 4 + 3] = 255;
+    }
+    return buf;
+}
+
+function twoHalves(w: number, h: number): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            const isLeft = x < w / 2;
+            buf[i] = isLeft ? 255 : 0;
+            buf[i + 1] = 0;
+            buf[i + 2] = isLeft ? 0 : 255;
+            buf[i + 3] = 255;
+        }
+    }
+    return buf;
+}
+
+function gradient(w: number, h: number): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            buf[i] = Math.floor((x / w) * 255);
+            buf[i + 1] = Math.floor((y / h) * 255);
+            buf[i + 2] = 128;
+            buf[i + 3] = 255;
+        }
+    }
+    return buf;
+}
+
+describe("analyseComplexity", () => {
+    it("classifies solid colour as pixel-art", { timeout: 5000 }, () => {
+        const result = analyseComplexity(
+            solidBuffer(32, 32, 200, 50, 50),
+            32,
+            32
+        );
+        expect(result.tier).toBe("pixel-art");
+        expect(result.uniqueColours).toBe(1);
+        expect(result.recommendedColours).toBeLessThanOrEqual(32);
+    });
+
+    it("classifies gradient as photographic", { timeout: 5000 }, () => {
+        const result = analyseComplexity(gradient(64, 64), 64, 64);
+        expect(result.tier).toBe("photographic");
+        expect(result.uniqueColours).toBeGreaterThan(100);
+        expect(result.recommendDithering).toBe(true);
+    });
+
+    it("classifies two-halves as pixel-art", { timeout: 5000 }, () => {
+        const result = analyseComplexity(twoHalves(32, 32), 32, 32);
+        expect(result.tier).toBe("pixel-art");
+        expect(result.uniqueColours).toBe(2);
+    });
+
+    it("returns valid pool distribution", { timeout: 5000 }, () => {
+        const result = analyseComplexity(twoHalves(8, 8), 8, 8);
+        expect(result.poolDistribution.count).toBe(2);
+        expect(result.poolDistribution.mean).toBe(32);
+    });
+
+    it("classifies vector-clean for moderate colours with medium pools", {
+        timeout: 5000,
+    }, () => {
+        // 32x32 image with 64 colours in 4x4 blocks
+        const buf = new Uint8Array(32 * 32 * 4);
+        let colourIdx = 0;
+        for (let by = 0; by < 8; by++) {
+            for (let bx = 0; bx < 8; bx++) {
+                const r = (colourIdx * 37) % 256;
+                const g = (colourIdx * 73) % 256;
+                const b = (colourIdx * 113) % 256;
+                for (let y = by * 4; y < (by + 1) * 4; y++) {
+                    for (let x = bx * 4; x < (bx + 1) * 4; x++) {
+                        const i = (y * 32 + x) * 4;
+                        buf[i] = r;
+                        buf[i + 1] = g;
+                        buf[i + 2] = b;
+                        buf[i + 3] = 255;
+                    }
+                }
+                colourIdx++;
+            }
+        }
+        const result = analyseComplexity(buf, 32, 32);
+        expect(result.tier).toBe("vector-clean");
+    });
+
+    it("classifies vector-aa for high colour count with structure", {
+        timeout: 5000,
+    }, () => {
+        // 64x64 image with 256 colours in 4x4 blocks
+        const buf = new Uint8Array(64 * 64 * 4);
+        let colourIdx = 0;
+        for (let by = 0; by < 16; by++) {
+            for (let bx = 0; bx < 16; bx++) {
+                const r = (colourIdx * 37) % 256;
+                const g = (colourIdx * 73) % 256;
+                const b = (colourIdx * 113) % 256;
+                for (let y = by * 4; y < (by + 1) * 4; y++) {
+                    for (let x = bx * 4; x < (bx + 1) * 4; x++) {
+                        const i = (y * 64 + x) * 4;
+                        buf[i] = r;
+                        buf[i + 1] = g;
+                        buf[i + 2] = b;
+                        buf[i + 3] = 255;
+                    }
+                }
+                colourIdx++;
+            }
+        }
+        const result = analyseComplexity(buf, 64, 64);
+        expect(result.tier).toBe("vector-aa");
+    });
+});

packages/media/image/image-quantisation/src/analysis/classify/classify.ts

@@ -0,0 +1,98 @@
+import type { ComplexityAnalysis, ComplexityTier } from "../../types/common.js";
+import { analyseEdges } from "../edges/edges.js";
+import { detectPools, poolDistribution } from "../pools/pools.js";
+
+/**
+ * Classify image complexity tier based on pool distribution and edge sharpness.
+ *
+ * The tier determines what quantisation strategy to use:
+ * - pixel-art:     Few colours, large pools. No quantisation needed.
+ * - vector-clean:  Moderate colours, medium pools. Light merge only.
+ * - vector-aa:     Moderate core colours + many tiny AA edge pools. Spatial merge.
+ * - photographic:  Near-unique pixels, tiny pools. Aggressive quantisation.
+ */
+function classifyTier(
+    uniqueColours: number,
+    poolMean: number,
+    singletonRatio: number,
+    sharpnessRatio: number
+): ComplexityTier {
+    // Pixel art: few colours with large uniform regions.
+    if (uniqueColours <= 32 && poolMean > 20) {
+        return "pixel-art";
+    }
+
+    // Photographic: nearly every pixel is unique, very few hard edges
+    if (singletonRatio > 0.7 && sharpnessRatio < 0.05) {
+        return "photographic";
+    }
+
+    // Vector with AA: bimodal — some large pools exist, but many singletons
+    if (singletonRatio > 0.3 && sharpnessRatio > 0.05 && uniqueColours > 32) {
+        return "vector-aa";
+    }
+
+    // Vector clean: moderate colours, medium pools, decent sharpness
+    if (uniqueColours <= 128 && poolMean > 5) {
+        return "vector-clean";
+    }
+
+    // If high colour count but some structure, likely vector-aa
+    if (uniqueColours > 128 && sharpnessRatio > 0.1) {
+        return "vector-aa";
+    }
+
+    return "photographic";
+}
+
+/** Recommend starting palette size based on complexity tier. */
+function recommendColours(tier: ComplexityTier, uniqueColours: number): number {
+    switch (tier) {
+        case "pixel-art":
+            return Math.max(2, Math.min(uniqueColours, 32));
+        case "vector-clean":
+            return Math.max(2, Math.min(uniqueColours, 64));
+        case "vector-aa":
+            return Math.min(128, Math.max(16, Math.ceil(uniqueColours * 0.1)));
+        case "photographic":
+            return 256;
+    }
+}
+
+/**
+ * Perform full complexity analysis on a raw RGBA pixel buffer.
+ * This is the entry point that emblem-solver will call to decide
+ * whether/how to quantise before solving.
+ */
+export function analyseComplexity(
+    pixels: Uint8Array,
+    width: number,
+    height: number
+): ComplexityAnalysis {
+    const total = width * height;
+    const pools = detectPools(pixels, width, height);
+    const dist = poolDistribution(pools);
+    const edges = analyseEdges(pixels, width, height);
+
+    const uniqueColours = new Set(pools.map((p) => p.colourKey)).size;
+
+    const tier = classifyTier(
+        uniqueColours,
+        dist.mean,
+        dist.singletonRatio,
+        edges.sharpnessRatio
+    );
+
+    return {
+        width,
+        height,
+        totalPixels: total,
+        uniqueColours,
+        pools,
+        poolDistribution: dist,
+        edgeAnalysis: edges,
+        tier,
+        recommendedColours: recommendColours(tier, uniqueColours),
+        recommendDithering: tier === "photographic",
+    };
+}

packages/media/image/image-quantisation/src/analysis/classify/index.ts

@@ -0,0 +1 @@
+export { analyseComplexity } from "./classify.js";

packages/media/image/image-quantisation/src/analysis/colour/colour.md

@@ -0,0 +1,70 @@
+# Colour Utilities
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Low-level colour distance and keying helpers used by the analysis and spatial-cleanup modules. These functions are pure, stateless, and operate on the `RGBA` type. They enable exact colour matching for pool detection, perceptual distance for edge analysis, and canonical string keys for hash-based lookups. All operations are synchronous and allocate no intermediate objects beyond the return value.
+
+## Features
+
+- Euclidean RGB distance
+- Perceptually weighted Euclidean distance (ITU-R BT.601)
+- Canonical colour key generation for exact matching
+- Round-trip colour key parsing
+
+## Usage: Basic Example
+
+```ts
+import {
+    rgbDistance,
+    colourKey,
+} from "@suaveplan/image-quantisation/analysis/colour";
+
+const a = { r: 255, g: 0, b: 0, a: 255 };
+const b = { r: 0, g: 255, b: 0, a: 255 };
+
+console.log(rgbDistance(a, b)); // ~360.6
+console.log(colourKey(a));      // "255,0,0,255"
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    weightedDistance,
+    parseColourKey,
+} from "@suaveplan/image-quantisation/analysis/colour";
+
+// Weighted distance accounts for human eye sensitivity
+const dist = weightedDistance(
+    { r: 100, g: 100, b: 100, a: 255 },
+    { r: 100, g: 110, b: 100, a: 255 }
+);
+
+const parsed = parseColourKey("100,110,100,255");
+```
+
+## API Reference
+
+### `rgbDistance(a, b): number`
+
+Euclidean distance in RGB space. Range 0–441.67.
+
+### `weightedDistance(a, b): number`
+
+ITU-R BT.601 weighted Euclidean distance. Range 0–255.
+
+### `colourKey(c): string`
+
+Returns `"r,g,b,a"`.
+
+### `parseColourKey(key): RGBA`
+
+Parses a comma-separated key back into `RGBA`.
+
+## Implementation Notes
+
+`rgbDistance` ignores the alpha channel. `weightedDistance` uses coefficients 0.299 (R), 0.587 (G), 0.114 (B) to approximate perceptual difference. The alpha channel is included in `colourKey` so that transparent pools are not merged with opaque ones during flood fill. All four functions are pure and have no side effects, making them safe to use in property-based tests and benchmarks. They are also fully deterministic: given the same inputs they always produce the same outputs, which is important for reproducible image processing pipelines.

packages/media/image/image-quantisation/src/analysis/colour/colour.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    colourKey,
+    parseColourKey,
+    rgbDistance,
+    weightedDistance,
+} from "./colour.js";
+
+describe("rgbDistance", () => {
+    it("returns 0 for identical colours", { timeout: 5000 }, () => {
+        const a = { r: 100, g: 150, b: 200, a: 255 };
+        expect(rgbDistance(a, a)).toBe(0);
+    });
+
+    it("computes euclidean distance correctly", { timeout: 5000 }, () => {
+        const a = { r: 0, g: 0, b: 0, a: 255 };
+        const b = { r: 3, g: 4, b: 0, a: 255 };
+        expect(rgbDistance(a, b)).toBe(5);
+    });
+});
+
+describe("weightedDistance", () => {
+    it("returns 0 for identical colours", { timeout: 5000 }, () => {
+        const a = { r: 100, g: 150, b: 200, a: 255 };
+        expect(weightedDistance(a, a)).toBe(0);
+    });
+
+    it("weights green channel more heavily", { timeout: 5000 }, () => {
+        const a = { r: 0, g: 0, b: 0, a: 255 };
+        const bGreen = { r: 0, g: 100, b: 0, a: 255 };
+        const bRed = { r: 100, g: 0, b: 0, a: 255 };
+        expect(weightedDistance(a, bGreen)).toBeGreaterThan(
+            weightedDistance(a, bRed)
+        );
+    });
+});
+
+describe("colourKey", () => {
+    it("produces a comma-separated string", { timeout: 5000 }, () => {
+        expect(colourKey({ r: 1, g: 2, b: 3, a: 4 })).toBe("1,2,3,4");
+    });
+});
+
+describe("parseColourKey", () => {
+    it("round-trips with colourKey", { timeout: 5000 }, () => {
+        const original = { r: 255, g: 128, b: 64, a: 32 };
+        expect(parseColourKey(colourKey(original))).toEqual(original);
+    });
+});

packages/media/image/image-quantisation/src/analysis/colour/colour.ts

@@ -0,0 +1,28 @@
+import type { RGBA } from "../../types/common.js";
+
+/** Euclidean RGB distance (0–441.67 range). Fast, good enough for analysis. */
+export function rgbDistance(a: RGBA, b: RGBA): number {
+    const dr = a.r - b.r;
+    const dg = a.g - b.g;
+    const db = a.b - b.b;
+    return Math.sqrt(dr * dr + dg * dg + db * db);
+}
+
+/** Weighted Euclidean with human perception bias (ITU-R BT.601). */
+export function weightedDistance(a: RGBA, b: RGBA): number {
+    const dr = a.r - b.r;
+    const dg = a.g - b.g;
+    const db = a.b - b.b;
+    return Math.sqrt(0.299 * dr * dr + 0.587 * dg * dg + 0.114 * db * db);
+}
+
+/** Colour key for exact matching. */
+export function colourKey(c: RGBA): string {
+    return `${c.r},${c.g},${c.b},${c.a}`;
+}
+
+/** Parse a colour key back to RGBA. */
+export function parseColourKey(key: string): RGBA {
+    const [r, g, b, a] = key.split(",").map(Number);
+    return { r: r!, g: g!, b: b!, a: a! };
+}

packages/media/image/image-quantisation/src/analysis/colour/index.ts

@@ -0,0 +1,6 @@
+export {
+    colourKey,
+    parseColourKey,
+    rgbDistance,
+    weightedDistance,
+} from "./colour.js";

packages/media/image/image-quantisation/src/analysis/edges/edges.md

@@ -0,0 +1,53 @@
+# Edge Analysis
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Analyse colour transitions between horizontally and vertically adjacent pixels to determine whether an image has sharp edges (pixel art) or soft edges (photographic). Edge metrics are a critical input to the complexity classifier, providing a signal that is orthogonal to pool distribution. Two images may have the same number of pools but very different edge characteristics.
+
+## Features
+
+- Examines every right and bottom neighbour pair
+- Counts hard edges (perceptually distinct) and soft edges (nearly identical)
+- Computes sharpness ratio and mean edge distance
+- Configurable hard/soft thresholds
+
+## Usage: Basic Example
+
+```ts
+import { analyseEdges } from "@suaveplan/image-quantisation/analysis/edges";
+
+const edges = analyseEdges(pixels, 32, 32);
+console.log(edges.sharpnessRatio); // 0.0 – 1.0
+```
+
+## Usage: Advanced Example
+
+```ts
+import { analyseEdges } from "@suaveplan/image-quantisation/analysis/edges";
+
+// Stricter thresholds for high-contrast artwork
+const edges = analyseEdges(pixels, 64, 64, 20, 5);
+
+if (edges.sharpnessRatio > 0.5) {
+    console.log("High-contrast pixel art detected");
+}
+```
+
+## API Reference
+
+### `analyseEdges(pixels, width, height, hardThreshold?, softThreshold?): EdgeAnalysis`
+
+- `pixels` — RGBA `Uint8Array`
+- `width`, `height` — image dimensions
+- `hardThreshold` — default 30
+- `softThreshold` — default 10
+
+Returns `EdgeAnalysis` with `totalEdges`, `hardEdges`, `softEdges`, `sharpnessRatio`, `meanEdgeDistance`.
+
+## Implementation Notes
+
+The function uses `weightedDistance` (ITU-R BT.601) for perceptually fair comparisons. Pairs are counted once each (right and bottom neighbours only) to avoid double counting. A solid-colour image produces zero hard edges and zero mean distance, while a checkerboard produces a very high sharpness ratio. The thresholds can be adjusted for different content types: stricter thresholds treat more edges as hard, which is useful for high-contrast artwork, while lenient thresholds classify most edges as soft, which is better for smooth gradients.

packages/media/image/image-quantisation/src/analysis/edges/edges.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { analyseEdges } from "./edges.js";
+
+function solidBuffer(
+    w: number,
+    h: number,
+    r: number,
+    g: number,
+    b: number
+): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let i = 0; i < w * h; i++) {
+        buf[i * 4] = r;
+        buf[i * 4 + 1] = g;
+        buf[i * 4 + 2] = b;
+        buf[i * 4 + 3] = 255;
+    }
+    return buf;
+}
+
+function checkerboard(w: number, h: number): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            const isWhite = (x + y) % 2 === 0;
+            buf[i] = isWhite ? 255 : 0;
+            buf[i + 1] = isWhite ? 255 : 0;
+            buf[i + 2] = isWhite ? 255 : 0;
+            buf[i + 3] = 255;
+        }
+    }
+    return buf;
+}
+
+function gradient(w: number, h: number): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            buf[i] = Math.floor((x / w) * 255);
+            buf[i + 1] = Math.floor((y / h) * 255);
+            buf[i + 2] = 128;
+            buf[i + 3] = 255;
+        }
+    }
+    return buf;
+}
+
+describe("analyseEdges", () => {
+    it("solid image has zero hard edges", { timeout: 5000 }, () => {
+        const edges = analyseEdges(solidBuffer(8, 8, 100, 100, 100), 8, 8);
+        expect(edges.hardEdges).toBe(0);
+        expect(edges.meanEdgeDistance).toBe(0);
+    });
+
+    it("checkerboard has high sharpness ratio", { timeout: 5000 }, () => {
+        const edges = analyseEdges(checkerboard(8, 8), 8, 8);
+        expect(edges.sharpnessRatio).toBeGreaterThan(0.5);
+    });
+
+    it("gradient has low sharpness ratio", { timeout: 5000 }, () => {
+        const edges = analyseEdges(gradient(32, 32), 32, 32);
+        expect(edges.sharpnessRatio).toBeLessThan(0.1);
+    });
+
+    it("uses custom thresholds when provided", { timeout: 5000 }, () => {
+        const edges = analyseEdges(checkerboard(4, 4), 4, 4, 1000, 500);
+        expect(edges.hardEdges).toBe(0);
+        expect(edges.softEdges).toBeGreaterThan(0);
+    });
+
+    it("1x1 image has zero edges", { timeout: 5000 }, () => {
+        const edges = analyseEdges(new Uint8Array([255, 0, 0, 255]), 1, 1);
+        expect(edges.totalEdges).toBe(0);
+        expect(edges.sharpnessRatio).toBe(0);
+        expect(edges.meanEdgeDistance).toBe(0);
+    });
+});

packages/media/image/image-quantisation/src/analysis/edges/edges.ts

@@ -0,0 +1,69 @@
+import {
+    DEFAULT_HARD_THRESHOLD,
+    DEFAULT_SOFT_THRESHOLD,
+} from "../../constants/index.js";
+import type { EdgeAnalysis, RGBA } from "../../types/common.js";
+import { weightedDistance } from "../colour/colour.js";
+
+/**
+ * Analyse edges between all horizontally and vertically adjacent pixel pairs.
+ * Returns edge sharpness metrics that indicate whether the image is
+ * pixel-art (high sharpness) or photographic (low sharpness).
+ */
+export function analyseEdges(
+    pixels: Uint8Array,
+    width: number,
+    height: number,
+    hardThreshold = DEFAULT_HARD_THRESHOLD,
+    softThreshold = DEFAULT_SOFT_THRESHOLD
+): EdgeAnalysis {
+    let totalEdges = 0;
+    let hardEdges = 0;
+    let softEdges = 0;
+    let totalDistance = 0;
+
+    const px = (idx: number): RGBA => {
+        const off = idx * 4;
+        return {
+            r: pixels[off]!,
+            g: pixels[off + 1]!,
+            b: pixels[off + 2]!,
+            a: pixels[off + 3]!,
+        };
+    };
+
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const idx = y * width + x;
+            const current = px(idx);
+
+            // Right neighbour
+            if (x < width - 1) {
+                const right = px(idx + 1);
+                const dist = weightedDistance(current, right);
+                totalDistance += dist;
+                totalEdges++;
+                if (dist > hardThreshold) hardEdges++;
+                if (dist <= softThreshold) softEdges++;
+            }
+
+            // Bottom neighbour
+            if (y < height - 1) {
+                const below = px(idx + width);
+                const dist = weightedDistance(current, below);
+                totalDistance += dist;
+                totalEdges++;
+                if (dist > hardThreshold) hardEdges++;
+                if (dist <= softThreshold) softEdges++;
+            }
+        }
+    }
+
+    return {
+        totalEdges,
+        hardEdges,
+        softEdges,
+        sharpnessRatio: totalEdges > 0 ? hardEdges / totalEdges : 0,
+        meanEdgeDistance: totalEdges > 0 ? totalDistance / totalEdges : 0,
+    };
+}

packages/media/image/image-quantisation/src/analysis/edges/index.ts

@@ -0,0 +1 @@
+export { analyseEdges } from "./edges.js";

packages/media/image/image-quantisation/src/analysis/pools/index.ts

@@ -0,0 +1 @@
+export { detectPools, poolDistribution } from "./pools.js";

packages/media/image/image-quantisation/src/analysis/pools/pools.md

@@ -0,0 +1,56 @@
+# Pool Detection
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Find contiguous regions of identical colour via 4-connected flood fill. Pool size distribution is the primary signal for image complexity classification. A pixel-art image may have only a handful of large pools, while a photograph may have thousands of singleton pools. This module provides both detection and statistical summary functions.
+
+## Features
+
+- 4-connected BFS flood fill
+- Returns pools sorted by size descending
+- Computes distribution statistics
+- Zero dependencies beyond colour utilities
+
+## Usage: Basic Example
+
+```ts
+import { detectPools } from "@suaveplan/image-quantisation/analysis/pools";
+
+const pools = detectPools(pixels, 32, 32);
+console.log(pools.length); // number of distinct colour regions
+console.log(pools[0]!.size); // largest region
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    detectPools,
+    poolDistribution,
+} from "@suaveplan/image-quantisation/analysis/pools";
+
+const pools = detectPools(pixels, 64, 64);
+const dist = poolDistribution(pools);
+
+if (dist.singletonRatio > 0.7) {
+    console.log("Photographic — many 1-pixel pools");
+}
+```
+
+## API Reference
+
+### `detectPools(pixels, width, height): Pool[]`
+
+Returns an array of `Pool` objects sorted by size descending.
+
+### `poolDistribution(pools): PoolDistribution`
+
+Computes count, min, max, mean, median, p90, singletons, and singletonRatio.
+
+## Implementation Notes
+
+Flood fill uses a stack-based BFS with a `Uint8Array` visited mask for memory efficiency. The `pixels` buffer is read-only. Pools are sorted by size descending so that the dominant colour regions appear first, which is useful for downstream algorithms that only need to inspect the largest pools. The visited mask uses a single byte per pixel, which keeps memory overhead low even for large images. Because every pixel is visited exactly once, the overall time complexity is O(width * height) in the worst case. For images with many small pools, the BFS queue may grow large, but the `Uint8Array` visited mask ensures that each pixel is never enqueued more than once.

packages/media/image/image-quantisation/src/analysis/pools/pools.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { detectPools, poolDistribution } from "./pools.js";
+
+function solidBuffer(
+    w: number,
+    h: number,
+    r: number,
+    g: number,
+    b: number
+): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let i = 0; i < w * h; i++) {
+        buf[i * 4] = r;
+        buf[i * 4 + 1] = g;
+        buf[i * 4 + 2] = b;
+        buf[i * 4 + 3] = 255;
+    }
+    return buf;
+}
+
+function checkerboard(w: number, h: number): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            const isWhite = (x + y) % 2 === 0;
+            buf[i] = isWhite ? 255 : 0;
+            buf[i + 1] = isWhite ? 255 : 0;
+            buf[i + 2] = isWhite ? 255 : 0;
+            buf[i + 3] = 255;
+        }
+    }
+    return buf;
+}
+
+function twoHalves(w: number, h: number): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            const isLeft = x < w / 2;
+            buf[i] = isLeft ? 255 : 0;
+            buf[i + 1] = 0;
+            buf[i + 2] = isLeft ? 0 : 255;
+            buf[i + 3] = 255;
+        }
+    }
+    return buf;
+}
+
+describe("detectPools", () => {
+    it("finds 1 pool for a solid colour", { timeout: 5000 }, () => {
+        const pools = detectPools(solidBuffer(8, 8, 255, 0, 0), 8, 8);
+        expect(pools).toHaveLength(1);
+        expect(pools[0]!.size).toBe(64);
+        expect(pools[0]!.colour).toEqual({ r: 255, g: 0, b: 0, a: 255 });
+    });
+
+    it("finds 2 pools for two halves", { timeout: 5000 }, () => {
+        const pools = detectPools(twoHalves(8, 4), 8, 4);
+        expect(pools).toHaveLength(2);
+        expect(pools[0]!.size).toBe(16);
+        expect(pools[1]!.size).toBe(16);
+    });
+
+    it("finds w*h pools for a checkerboard", { timeout: 5000 }, () => {
+        const pools = detectPools(checkerboard(4, 4), 4, 4);
+        expect(pools).toHaveLength(16);
+        pools.forEach((p) => expect(p.size).toBe(1));
+    });
+
+    it("returns pools sorted by size descending", { timeout: 5000 }, () => {
+        const pools = detectPools(twoHalves(10, 4), 10, 4);
+        for (let i = 1; i < pools.length; i++) {
+            expect(pools[i]!.size).toBeLessThanOrEqual(pools[i - 1]!.size);
+        }
+    });
+});
+
+describe("poolDistribution", () => {
+    it("computes stats for uniform pools", { timeout: 5000 }, () => {
+        const pools = detectPools(twoHalves(8, 4), 8, 4);
+        const dist = poolDistribution(pools);
+        expect(dist.count).toBe(2);
+        expect(dist.mean).toBe(16);
+        expect(dist.singletons).toBe(0);
+        expect(dist.singletonRatio).toBe(0);
+    });
+
+    it("detects high singleton ratio in checkerboard", {
+        timeout: 5000,
+    }, () => {
+        const pools = detectPools(checkerboard(8, 8), 8, 8);
+        const dist = poolDistribution(pools);
+        expect(dist.singletonRatio).toBe(1);
+        expect(dist.mean).toBe(1);
+    });
+
+    it("returns zeros for empty pools", { timeout: 5000 }, () => {
+        const dist = poolDistribution([]);
+        expect(dist.count).toBe(0);
+        expect(dist.mean).toBe(0);
+    });
+});

packages/media/image/image-quantisation/src/analysis/pools/pools.ts

@@ -0,0 +1,116 @@
+import type { Pool, RGBA } from "../../types/common.js";
+import { colourKey } from "../colour/colour.js";
+
+/**
+ * Find all pools (contiguous regions of identical colour) via 4-connected BFS.
+ * Returns pools sorted by size descending.
+ */
+export function detectPools(
+    pixels: Uint8Array,
+    width: number,
+    height: number
+): Pool[] {
+    const total = width * height;
+    const visited = new Uint8Array(total);
+    const pools: Pool[] = [];
+
+    for (let idx = 0; idx < total; idx++) {
+        if (visited[idx]) continue;
+
+        const off = idx * 4;
+        const colour: RGBA = {
+            r: pixels[off]!,
+            g: pixels[off + 1]!,
+            b: pixels[off + 2]!,
+            a: pixels[off + 3]!,
+        };
+        const key = colourKey(colour);
+
+        const poolPixels = new Set<number>();
+        const queue: number[] = [idx];
+        visited[idx] = 1;
+
+        let minX = idx % width;
+        let maxX = minX;
+        let minY = Math.floor(idx / width);
+        let maxY = minY;
+
+        while (queue.length > 0) {
+            const cur = queue.pop()!;
+            poolPixels.add(cur);
+
+            const cx = cur % width;
+            const cy = Math.floor(cur / width);
+            minX = Math.min(minX, cx);
+            maxX = Math.max(maxX, cx);
+            minY = Math.min(minY, cy);
+            maxY = Math.max(maxY, cy);
+
+            const neighbours = [
+                cy > 0 ? cur - width : -1,
+                cy < height - 1 ? cur + width : -1,
+                cx > 0 ? cur - 1 : -1,
+                cx < width - 1 ? cur + 1 : -1,
+            ];
+
+            for (const n of neighbours) {
+                if (n < 0 || visited[n]) continue;
+                const nOff = n * 4;
+                if (
+                    pixels[nOff] === colour.r &&
+                    pixels[nOff + 1] === colour.g &&
+                    pixels[nOff + 2] === colour.b &&
+                    pixels[nOff + 3] === colour.a
+                ) {
+                    visited[n] = 1;
+                    queue.push(n);
+                }
+            }
+        }
+
+        pools.push({
+            colourKey: key,
+            colour,
+            pixels: poolPixels,
+            size: poolPixels.size,
+            x: minX,
+            y: minY,
+            w: maxX - minX + 1,
+            h: maxY - minY + 1,
+        });
+    }
+
+    pools.sort((a, b) => b.size - a.size);
+    return pools;
+}
+
+/** Compute pool size distribution statistics. */
+export function poolDistribution(pools: Pool[]) {
+    if (pools.length === 0) {
+        return {
+            count: 0,
+            min: 0,
+            max: 0,
+            mean: 0,
+            median: 0,
+            p90: 0,
+            singletons: 0,
+            singletonRatio: 0,
+        };
+    }
+
+    const sizes = pools.map((p) => p.size).sort((a, b) => a - b);
+    const sum = sizes.reduce((a, b) => a + b, 0);
+    const singletons = sizes.filter((s) => s === 1).length;
+
+    return {
+        count: sizes.length,
+        min: sizes[0]!,
+        max: sizes[sizes.length - 1]!,
+        mean: sum / sizes.length,
+        median: sizes[Math.floor(sizes.length / 2)]!,
+        p90: sizes[Math.floor(sizes.length * 0.9)]!,
+        singletons,
+        singletonRatio: singletons / sizes.length,
+    };
+}

packages/media/image/image-quantisation/src/constants/index.ts

@@ -0,0 +1,23 @@
+/** Default threshold for "hard" edges (perceptually distinct colours). */
+export const DEFAULT_HARD_THRESHOLD = 30;
+
+/** Default threshold for "soft" edges (nearly identical / AA blending). */
+export const DEFAULT_SOFT_THRESHOLD = 10;
+
+/** Default max colour distance for spatial AA cleanup. */
+export const DEFAULT_MAX_DISTANCE = 30;
+
+/** Default max pool size for spatial AA cleanup. */
+export const DEFAULT_MAX_POOL_SIZE = 4;
+
+/** Default target colours for quantisation. */
+export const DEFAULT_COLOURS = 256;
+
+/** Default quantisation algorithm. */
+export const DEFAULT_ALGORITHM = "wuquant" as const;
+
+/** Default colour distance formula. */
+export const DEFAULT_DISTANCE = "euclidean" as const;
+
+/** Default dithering algorithm. */
+export const DEFAULT_DITHER = "none" as const;

packages/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.

packages/media/image/image-quantisation/src/errors/image-quantisation-error.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    QUANTISATION_CODES,
+    QuantisationError,
+} from "./image-quantisation-error.js";
+
+describe("QuantisationError", () => {
+    it("has the correct name", { timeout: 5000 }, () => {
+        const err = new QuantisationError(
+            QUANTISATION_CODES.INVALID_PIXEL_BUFFER,
+            "quantisation.invalid_pixel_buffer"
+        );
+        expect(err.name).toBe("QuantisationError");
+    });
+
+    it("carries the code in the expected namespace format", {
+        timeout: 5000,
+    }, () => {
+        const err = new QuantisationError(
+            QUANTISATION_CODES.INVALID_DIMENSIONS,
+            "quantisation.invalid_dimensions"
+        );
+        expect(err.code).toBe("QUANTISATION.INVALID_DIMENSIONS");
+    });
+
+    it("preserves cause when provided", { timeout: 5000 }, () => {
+        const cause = new Error("underlying failure");
+        const err = new QuantisationError(
+            QUANTISATION_CODES.PROCESSING_FAILED,
+            "quantisation.processing_failed",
+            { cause }
+        );
+        expect(err.cause).toBe(cause);
+    });
+});
+
+describe("QUANTISATION_CODES", () => {
+    it("contains all expected codes", { timeout: 5000 }, () => {
+        expect(QUANTISATION_CODES.INVALID_PIXEL_BUFFER).toBe(
+            "QUANTISATION.INVALID_PIXEL_BUFFER"
+        );
+        expect(QUANTISATION_CODES.INVALID_COLOR_COUNT).toBe(
+            "QUANTISATION.INVALID_COLOR_COUNT"
+        );
+        expect(QUANTISATION_CODES.INVALID_DIMENSIONS).toBe(
+            "QUANTISATION.INVALID_DIMENSIONS"
+        );
+        expect(QUANTISATION_CODES.PROCESSING_FAILED).toBe(
+            "QUANTISATION.PROCESSING_FAILED"
+        );
+    });
+});

packages/media/image/image-quantisation/src/errors/image-quantisation-error.ts

@@ -0,0 +1,38 @@
+import {
+    defineCodes,
+    SuaveplanError,
+    type SuaveplanErrorOptions,
+} from "@suaveplan/error";
+
+/**
+ * Stable error code registry for `@suaveplan/image-quantisation`.
+ *
+ * Codes are namespaced under `QUANTISATION` for easy identification in
+ * structured error logs and OTel span events.
+ */
+export const QUANTISATION_CODES = defineCodes("QUANTISATION", [
+    "INVALID_PIXEL_BUFFER",
+    "INVALID_COLOR_COUNT",
+    "INVALID_DIMENSIONS",
+    "PROCESSING_FAILED",
+] as const);
+
+export type QuantisationCode =
+    (typeof QUANTISATION_CODES)[keyof typeof QUANTISATION_CODES];
+
+/**
+ * Typed error for all `@suaveplan/image-quantisation` failures.
+ *
+ * Extends `SuaveplanError` with a stable code drawn from `QUANTISATION_CODES`.
+ * Callers can discriminate on `error.code` to handle specific failure modes.
+ */
+export class QuantisationError extends SuaveplanError<QuantisationCode> {
+    public constructor(
+        code: QuantisationCode,
+        messageKey: string,
+        options?: SuaveplanErrorOptions
+    ) {
+        super(code, messageKey, options);
+        this.name = "QuantisationError";
+    }
+}

packages/media/image/image-quantisation/src/errors/index.ts

@@ -0,0 +1,5 @@
+export type { QuantisationCode } from "./image-quantisation-error.js";
+export {
+    QUANTISATION_CODES,
+    QuantisationError,
+} from "./image-quantisation-error.js";

packages/media/image/image-quantisation/src/index.ts

@@ -0,0 +1,45 @@
+// Analysis
+export { analyseComplexity } from "./analysis/classify/index.js";
+export {
+    colourKey,
+    parseColourKey,
+    rgbDistance,
+    weightedDistance,
+} from "./analysis/colour/index.js";
+export { analyseEdges } from "./analysis/edges/index.js";
+export { detectPools, poolDistribution } from "./analysis/pools/index.js";
+export type { QuantisationCode } from "./errors/index.js";
+// Errors
+export {
+    QUANTISATION_CODES,
+    QuantisationError,
+} from "./errors/index.js";
+// Pipeline
+export { adaptivePipeline } from "./pipeline/index.js";
+// Quantisation
+export { quantise, quantiseAdaptive } from "./quantise/index.js";
+// Schemas
+export {
+    AdaptivePipelineOptionsSchema,
+    QuantiseOptionsSchema,
+    SpatialCleanupOptionsSchema,
+} from "./schemas/index.js";
+// Spatial cleanup
+export { countUniqueColours, spatialCleanup } from "./spatial/cleanup/index.js";
+// Types
+export type {
+    AdaptivePipelineOptions,
+    AdaptivePipelineResult,
+    ComplexityAnalysis,
+    ComplexityTier,
+    DistanceFormula,
+    DitherAlgorithm,
+    EdgeAnalysis,
+    PaletteAlgorithm,
+    Pool,
+    PoolDistribution,
+    QuantiseOptions,
+    QuantiseResult,
+    RGBA,
+    SpatialCleanupOptions,
+} from "./types/index.js";

packages/media/image/image-quantisation/src/pipeline/index.ts

@@ -0,0 +1,5 @@
+export type {
+    AdaptivePipelineOptions,
+    AdaptivePipelineResult,
+} from "../types/common.js";
+export { adaptivePipeline } from "./pipeline.js";

packages/media/image/image-quantisation/src/pipeline/pipeline.md

@@ -0,0 +1,67 @@
+# Adaptive Pipeline
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Full workflow: analyse complexity → spatial cleanup → quantise. Automatically selects the best strategy based on image content. This is the recommended high-level entry point for emblem-generation pipelines because it encapsulates the decision logic for when to skip quantisation, when to apply spatial cleanup, and when to use dithering.
+
+## Features
+
+- One-call image preparation for emblem-solver
+- Skips quantisation for pixel-art images
+- Applies spatial cleanup for vector-aa and vector-clean tiers
+- Auto-selects dithering for photographic content
+- Zod validation for all options
+- OTel counter and histogram instrumentation
+
+## Usage: Basic Example
+
+```ts
+import { adaptivePipeline } from "@suaveplan/image-quantisation/pipeline";
+
+const result = adaptivePipeline(pixels, 32, 32);
+console.log(result.analysis.tier);
+console.log(result.finalColours);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { adaptivePipeline } from "@suaveplan/image-quantisation/pipeline";
+
+const result = adaptivePipeline(pixels, 64, 64, {
+    maxColours: 16,
+    dither: "floyd-steinberg",
+    spatial: { maxDistance: 25, maxPoolSize: 2 },
+    skipQuantisationForPixelArt: false,
+});
+
+if (result.spatialCleanupApplied) {
+    console.log("Spatial cleanup merged small AA pools");
+}
+```
+
+## API Reference
+
+### `adaptivePipeline(pixels, width, height, options?): AdaptivePipelineResult`
+
+- `pixels` — RGBA `Uint8Array`
+- `width`, `height` — image dimensions
+- `options` — `AdaptivePipelineOptions` (optional)
+
+Returns `AdaptivePipelineResult` with:
+
+- `pixels` — final processed buffer
+- `analysis` — complexity analysis of the original
+- `quantisation` — quantisation result or `null`
+- `spatialCleanupApplied` — boolean
+- `finalColours` — unique colour count after processing
+
+Throws `QuantisationError` on invalid input or options.
+
+## Implementation Notes
+
+The pipeline never mutates the input buffer. Each stage creates a new `Uint8Array` when modification is required. OTel instruments record the complexity tier and whether spatial cleanup was applied as attributes. The final colour count is computed by packing each RGBA tuple into a 32-bit integer and counting distinct values in a `Set`. This design makes the pipeline safe to call repeatedly on the same buffer without copying at the call site. The `skipQuantisationForPixelArt` default is true because pixel-art images already have a low colour count and quantisation would only degrade quality.

packages/media/image/image-quantisation/src/pipeline/pipeline.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    QUANTISATION_CODES,
+    QuantisationError,
+} from "../errors/image-quantisation-error.js";
+import { adaptivePipeline } from "./pipeline.js";
+
+function solidBuffer(
+    w: number,
+    h: number,
+    r: number,
+    g: number,
+    b: number
+): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let i = 0; i < w * h; i++) {
+        buf[i * 4] = r;
+        buf[i * 4 + 1] = g;
+        buf[i * 4 + 2] = b;
+        buf[i * 4 + 3] = 255;
+    }
+    return buf;
+}
+
+function gradient(w: number, h: number): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            buf[i] = Math.floor((x / w) * 255);
+            buf[i + 1] = Math.floor((y / h) * 255);
+            buf[i + 2] = 128;
+            buf[i + 3] = 255;
+        }
+    }
+    return buf;
+}
+
+describe("adaptivePipeline", () => {
+    it("skips quantisation for pixel-art", { timeout: 5000 }, () => {
+        const result = adaptivePipeline(
+            solidBuffer(32, 32, 200, 50, 50),
+            32,
+            32
+        );
+        expect(result.analysis.tier).toBe("pixel-art");
+        expect(result.quantisation).toBeNull();
+        expect(result.finalColours).toBe(1);
+    });
+
+    it("quantises photographic images", { timeout: 30000 }, () => {
+        const result = adaptivePipeline(gradient(64, 64), 64, 64);
+        expect(result.analysis.tier).toBe("photographic");
+        expect(result.quantisation).not.toBeNull();
+        expect(result.finalColours).toBeLessThanOrEqual(256);
+    });
+
+    it("respects maxColours override", { timeout: 30000 }, () => {
+        const result = adaptivePipeline(gradient(32, 32), 32, 32, {
+            maxColours: 8,
+        });
+        expect(result.finalColours).toBeLessThanOrEqual(8);
+    });
+
+    it("returns correct dimensions", { timeout: 30000 }, () => {
+        const result = adaptivePipeline(gradient(16, 24), 16, 24);
+        expect(result.width).toBe(16);
+        expect(result.height).toBe(24);
+        expect(result.pixels.length).toBe(16 * 24 * 4);
+    });
+
+    it("forces quantisation when skipQuantisationForPixelArt is false", {
+        timeout: 30000,
+    }, () => {
+        const result = adaptivePipeline(
+            solidBuffer(8, 8, 100, 100, 100),
+            8,
+            8,
+            {
+                skipQuantisationForPixelArt: false,
+            }
+        );
+        expect(result.quantisation).not.toBeNull();
+    });
+
+    it("throws on invalid dimensions", { timeout: 5000 }, () => {
+        expect(() => adaptivePipeline(new Uint8Array(4), 0, 1)).toThrow(
+            QuantisationError
+        );
+        try {
+            adaptivePipeline(new Uint8Array(4), 0, 1);
+        } catch (err) {
+            expect((err as QuantisationError).code).toBe(
+                QUANTISATION_CODES.INVALID_DIMENSIONS
+            );
+        }
+    });
+
+    it("throws on mismatched buffer size", { timeout: 5000 }, () => {
+        expect(() => adaptivePipeline(new Uint8Array(4), 2, 2)).toThrow(
+            QuantisationError
+        );
+        try {
+            adaptivePipeline(new Uint8Array(4), 2, 2);
+        } catch (err) {
+            expect((err as QuantisationError).code).toBe(
+                QUANTISATION_CODES.INVALID_PIXEL_BUFFER
+            );
+        }
+    });
+
+    it("applies spatial cleanup for vector-aa images", {
+        timeout: 30000,
+    }, () => {
+        // 64x64 image with 256 colours in 4x4 blocks → vector-aa
+        const buf = new Uint8Array(64 * 64 * 4);
+        let colourIdx = 0;
+        for (let by = 0; by < 16; by++) {
+            for (let bx = 0; bx < 16; bx++) {
+                const r = (colourIdx * 37) % 256;
+                const g = (colourIdx * 73) % 256;
+                const b = (colourIdx * 113) % 256;
+                for (let y = by * 4; y < (by + 1) * 4; y++) {
+                    for (let x = bx * 4; x < (bx + 1) * 4; x++) {
+                        const i = (y * 64 + x) * 4;
+                        buf[i] = r;
+                        buf[i + 1] = g;
+                        buf[i + 2] = b;
+                        buf[i + 3] = 255;
+                    }
+                }
+                colourIdx++;
+            }
+        }
+        const result = adaptivePipeline(buf, 64, 64);
+        expect(result.analysis.tier).toBe("vector-aa");
+        expect(result.spatialCleanupApplied).toBe(true);
+    });
+
+    it("throws on invalid options", { timeout: 5000 }, () => {
+        expect(() =>
+            adaptivePipeline(solidBuffer(4, 4, 255, 0, 0), 4, 4, {
+                maxColours: 1,
+            })
+        ).toThrow(QuantisationError);
+    });
+});

packages/media/image/image-quantisation/src/pipeline/pipeline.ts

@@ -0,0 +1,168 @@
+import type { Counter, Histogram } from "@opentelemetry/api";
+import { metrics } from "@opentelemetry/api";
+import { analyseComplexity } from "../analysis/classify/classify.js";
+import { detectPools } from "../analysis/pools/pools.js";
+import {
+    QUANTISATION_CODES,
+    QuantisationError,
+} from "../errors/image-quantisation-error.js";
+import { quantise } from "../quantise/quantise.js";
+import { AdaptivePipelineOptionsSchema } from "../schemas/options.schema.js";
+import { spatialCleanup } from "../spatial/cleanup/cleanup.js";
+import type {
+    AdaptivePipelineOptions,
+    AdaptivePipelineResult,
+    QuantiseResult,
+} from "../types/common.js";
+
+/** OTel metric names. */
+const METRIC_PIPELINE_TOTAL = "image_quantisation.pipeline.total";
+const METRIC_PIPELINE_DURATION_MS = "image_quantisation.pipeline.duration_ms";
+
+let pipelineCounter: Counter | undefined;
+let pipelineDuration: Histogram | undefined;
+
+function getCounter(): Counter {
+    if (!pipelineCounter) {
+        const meter = metrics.getMeter("@suaveplan/image-quantisation");
+        pipelineCounter = meter.createCounter(METRIC_PIPELINE_TOTAL, {
+            description: "Total number of adaptivePipeline() invocations",
+        });
+    }
+    return pipelineCounter;
+}
+
+function getDuration(): Histogram {
+    if (!pipelineDuration) {
+        const meter = metrics.getMeter("@suaveplan/image-quantisation");
+        pipelineDuration = meter.createHistogram(METRIC_PIPELINE_DURATION_MS, {
+            description: "Duration of adaptivePipeline() in milliseconds",
+            unit: "ms",
+        });
+    }
+    return pipelineDuration;
+}
+
+/**
+ * Full adaptive pipeline: analyse → spatial cleanup → quantise.
+ *
+ * 1. Analyse the raw image to determine complexity tier
+ * 2. For vector-aa: run spatial cleanup to merge tiny AA pools first
+ * 3. Quantise to recommended palette size (or skip for pixel-art)
+ * 4. Return cleaned pixels ready for emblem-solver
+ */
+export function adaptivePipeline(
+    pixels: Uint8Array,
+    width: number,
+    height: number,
+    options: AdaptivePipelineOptions = {}
+): AdaptivePipelineResult {
+    const start = performance.now();
+
+    if (width <= 0 || height <= 0) {
+        throw new QuantisationError(
+            QUANTISATION_CODES.INVALID_DIMENSIONS,
+            "quantisation.invalid_dimensions",
+            { cause: new Error(`width=${width}, height=${height}`) }
+        );
+    }
+    if (pixels.length !== width * height * 4) {
+        throw new QuantisationError(
+            QUANTISATION_CODES.INVALID_PIXEL_BUFFER,
+            "quantisation.invalid_pixel_buffer",
+            {
+                cause: new Error(
+                    `expected ${width * height * 4} bytes, got ${pixels.length}`
+                ),
+            }
+        );
+    }
+
+    const parsed = AdaptivePipelineOptionsSchema.safeParse(options);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ");
+        throw new QuantisationError(
+            QUANTISATION_CODES.PROCESSING_FAILED,
+            `quantisation.invalid_options: ${issues}`
+        );
+    }
+
+    const {
+        maxColours,
+        dither,
+        spatial,
+        skipSpatialCleanup = false,
+        skipQuantisationForPixelArt = true,
+    } = parsed.data;
+
+    // Step 1: Analyse
+    const analysis = analyseComplexity(pixels, width, height);
+
+    let working: Uint8Array = new Uint8Array(pixels);
+    let spatialCleanupApplied = false;
+
+    // Step 2: Spatial cleanup (for vector-aa and vector-clean)
+    if (
+        !skipSpatialCleanup &&
+        (analysis.tier === "vector-aa" || analysis.tier === "vector-clean")
+    ) {
+        const pools = detectPools(working, width, height);
+        working = spatialCleanup(working, width, height, pools, spatial);
+        spatialCleanupApplied = true;
+    }
+
+    // Step 3: Quantise (unless pixel-art with skip enabled)
+    let quantisation: QuantiseResult | null = null;
+
+    if (skipQuantisationForPixelArt && analysis.tier === "pixel-art") {
+        // No quantisation needed — already low colour count
+    } else {
+        const targetColours = maxColours ?? analysis.recommendedColours;
+        const useDither =
+            dither ??
+            (analysis.recommendDithering ? "floyd-steinberg" : "none");
+
+        quantisation = quantise(working, width, height, {
+            colours: targetColours,
+            dither: useDither,
+        });
+        working = quantisation.pixels;
+    }
+
+    // Count final colours
+    const finalColours = new Set<number>();
+    const total = width * height;
+    for (let i = 0; i < total; i++) {
+        const off = i * 4;
+        finalColours.add(
+            (working[off]! << 24) |
+                (working[off + 1]! << 16) |
+                (working[off + 2]! << 8) |
+                working[off + 3]!
+        );
+    }
+
+    const duration = performance.now() - start;
+    const counter = getCounter();
+    const histogram = getDuration();
+    counter.add(1, {
+        "quantisation.tier": analysis.tier,
+        "quantisation.spatial_cleanup": String(spatialCleanupApplied),
+    });
+    histogram.record(duration, {
+        "quantisation.tier": analysis.tier,
+        "quantisation.spatial_cleanup": String(spatialCleanupApplied),
+    });
+
+    return {
+        pixels: working,
+        width,
+        height,
+        analysis,
+        quantisation,
+        spatialCleanupApplied,
+        finalColours: finalColours.size,
+    };
+}

packages/media/image/image-quantisation/src/property.test.ts

@@ -0,0 +1,113 @@
+import { describe, it } from "@suaveplan/testing/runner";
+import * as fc from "fast-check";
+import { analyseComplexity } from "./analysis/classify/classify.js";
+import { quantise } from "./quantise/quantise.js";
+import { countUniqueColours } from "./spatial/cleanup/cleanup.js";
+
+function arbitraryRgbaBuffer(maxW = 16, maxH = 16) {
+    return fc
+        .tuple(
+            fc.integer({ min: 1, max: maxW }),
+            fc.integer({ min: 1, max: maxH })
+        )
+        .chain(([w, h]) => {
+            const size = w * h * 4;
+            return fc
+                .tuple(
+                    fc.uint8Array({ minLength: size, maxLength: size }),
+                    fc.constant(w),
+                    fc.constant(h)
+                )
+                .map(([buf, width, height]) => ({ buf, width, height }));
+        });
+}
+
+describe("property-based tests", () => {
+    it("quantise palette size <= requested colours", { timeout: 30000 }, () => {
+        fc.assert(
+            fc.property(
+                arbitraryRgbaBuffer(),
+                fc.integer({ min: 2, max: 256 }),
+                fc.constantFrom("wuquant", "neuquant" as const),
+                ({ buf, width, height }, colours, algorithm) => {
+                    try {
+                        const result = quantise(buf, width, height, {
+                            colours,
+                            algorithm,
+                        });
+                        return result.paletteSize <= colours;
+                    } catch {
+                        // Some random inputs may trigger library edge cases;
+                        // treat as discarded.
+                        return true;
+                    }
+                }
+            ),
+            { numRuns: 20 }
+        );
+    });
+
+    it("quantise output has same dimensions as input", {
+        timeout: 30000,
+    }, () => {
+        fc.assert(
+            fc.property(
+                arbitraryRgbaBuffer(),
+                fc.integer({ min: 2, max: 256 }),
+                ({ buf, width, height }, colours) => {
+                    try {
+                        const result = quantise(buf, width, height, {
+                            colours,
+                        });
+                        return (
+                            result.width === width &&
+                            result.height === height &&
+                            result.pixels.length === width * height * 4
+                        );
+                    } catch {
+                        return true;
+                    }
+                }
+            ),
+            { numRuns: 20 }
+        );
+    });
+
+    it("complexity score properties hold", { timeout: 30000 }, () => {
+        fc.assert(
+            fc.property(arbitraryRgbaBuffer(), ({ buf, width, height }) => {
+                const analysis = analyseComplexity(buf, width, height);
+                return (
+                    analysis.width === width &&
+                    analysis.height === height &&
+                    analysis.totalPixels === width * height &&
+                    analysis.uniqueColours >= 1 &&
+                    analysis.uniqueColours <= width * height &&
+                    analysis.recommendedColours >= 2 &&
+                    analysis.recommendedColours <= 256 &&
+                    analysis.poolDistribution.count >= 1 &&
+                    analysis.poolDistribution.mean >= 1
+                );
+            }),
+            { numRuns: 20 }
+        );
+    });
+
+    it("countUniqueColours is non-decreasing when adding pixels", {
+        timeout: 5000,
+    }, () => {
+        fc.assert(
+            fc.property(
+                fc.uint8Array({ minLength: 4, maxLength: 400 }),
+                fc.integer({ min: 1, max: 10 }),
+                fc.integer({ min: 1, max: 10 }),
+                (buf, w, h) => {
+                    if (buf.length !== w * h * 4) return true;
+                    const count = countUniqueColours(buf, w, h);
+                    return count >= 1 && count <= w * h;
+                }
+            ),
+            { numRuns: 50 }
+        );
+    });
+});

packages/media/image/image-quantisation/src/quantise/index.ts

@@ -0,0 +1,4 @@
+export {
+    quantise,
+    quantiseAdaptive,
+} from "./quantise.js";

packages/media/image/image-quantisation/src/quantise/quantise.md

@@ -0,0 +1,66 @@
+# Quantise
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Reduce an RGBA pixel buffer to a target number of colours using the `image-q` library. This module is the primary quantisation entry point, supporting three palette-generation algorithms and three dithering modes. It wraps the low-level `image-q` API with ergonomic options, Zod validation, and OpenTelemetry instrumentation.
+
+## Features
+
+- Wu quant (median-cut, best quality)
+- Neuquant (neural network, good for photos)
+- RGBQuant (fastest, good for previews)
+- Euclidean, Manhattan, and CIEDE2000 distance formulas
+- Floyd-Steinberg and Riemersma dithering
+- Zod option validation
+- OTel counter and histogram instrumentation
+
+## Usage: Basic Example
+
+```ts
+import { quantise } from "@suaveplan/image-quantisation/quantise";
+
+const result = quantise(pixels, 32, 32, {
+    colours: 16,
+    algorithm: "wuquant",
+});
+
+console.log(result.paletteSize); // ≤ 16
+```
+
+## Usage: Advanced Example
+
+```ts
+import { quantise } from "@suaveplan/image-quantisation/quantise";
+
+const result = quantise(pixels, 64, 64, {
+    colours: 32,
+    algorithm: "neuquant",
+    distance: "ciede2000",
+    dither: "floyd-steinberg",
+});
+
+// result.pixels is a new Uint8Array with quantised colours
+// result.palette is the generated colour table
+```
+
+## API Reference
+
+### `quantise(pixels, width, height, options?): QuantiseResult`
+
+- `pixels` — RGBA `Uint8Array`
+- `width`, `height` — image dimensions
+- `options` — `QuantiseOptions` (optional)
+
+Throws `QuantisationError` on invalid input dimensions, mismatched buffer size, or invalid options.
+
+### `quantiseAdaptive(pixels, width, height, recommendedColours, recommendDithering, overrides?): QuantiseResult`
+
+Convenience wrapper that sets algorithm to `"wuquant"` and dither based on the boolean flag. `overrides` can override any individual field.
+
+## Implementation Notes
+
+The function validates inputs with Zod schemas before delegating to `image-q`. OTel instruments are lazily initialised on first use to avoid side effects at module load time. All algorithms run synchronously. The `mapDither` helper translates our dither enum values into the strings expected by `image-q`. Performance varies by algorithm: Wu quant is generally the best balance of quality and speed, Neuquant excels on photographic content, and RGBQuant is fastest but may produce slightly lower quality. Callers should benchmark on their specific image corpus to choose the best algorithm.

packages/media/image/image-quantisation/src/quantise/quantise.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    QUANTISATION_CODES,
+    QuantisationError,
+} from "../errors/image-quantisation-error.js";
+import { quantise, quantiseAdaptive } from "./quantise.js";
+
+function gradient(w: number, h: number): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            buf[i] = Math.floor((x / w) * 255);
+            buf[i + 1] = Math.floor((y / h) * 255);
+            buf[i + 2] = 128;
+            buf[i + 3] = 255;
+        }
+    }
+    return buf;
+}
+
+function solidBuffer(
+    w: number,
+    h: number,
+    r: number,
+    g: number,
+    b: number
+): Uint8Array {
+    const buf = new Uint8Array(w * h * 4);
+    for (let i = 0; i < w * h; i++) {
+        buf[i * 4] = r;
+        buf[i * 4 + 1] = g;
+        buf[i * 4 + 2] = b;
+        buf[i * 4 + 3] = 255;
+    }
+    return buf;
+}
+
+describe("quantise", () => {
+    it("reduces a gradient to target colour count", { timeout: 30000 }, () => {
+        const input = gradient(32, 32);
+        const result = quantise(input, 32, 32, { colours: 16 });
+        expect(result.paletteSize).toBeLessThanOrEqual(16);
+    });
+
+    it("preserves dimensions", { timeout: 30000 }, () => {
+        const result = quantise(gradient(16, 8), 16, 8, { colours: 4 });
+        expect(result.width).toBe(16);
+        expect(result.height).toBe(8);
+        expect(result.pixels.length).toBe(16 * 8 * 4);
+    });
+
+    it("uses defaults when no options provided", { timeout: 30000 }, () => {
+        const result = quantise(gradient(16, 16), 16, 16);
+        expect(result.paletteSize).toBeLessThanOrEqual(256);
+        expect(result.options.algorithm).toBe("wuquant");
+        expect(result.options.distance).toBe("euclidean");
+        expect(result.options.dither).toBe("none");
+    });
+
+    it("returns the palette used", { timeout: 30000 }, () => {
+        const result = quantise(gradient(16, 16), 16, 16, { colours: 8 });
+        expect(result.palette.length).toBeGreaterThan(0);
+        expect(result.palette.length).toBeLessThanOrEqual(8);
+        for (const c of result.palette) {
+            expect(c.r).toBeGreaterThanOrEqual(0);
+            expect(c.r).toBeLessThanOrEqual(255);
+        }
+    });
+
+    it("supports different algorithms", { timeout: 30000 }, () => {
+        const input = gradient(16, 16);
+        const wu = quantise(input, 16, 16, {
+            colours: 8,
+            algorithm: "wuquant",
+        });
+        const neu = quantise(input, 16, 16, {
+            colours: 8,
+            algorithm: "neuquant",
+        });
+        const rgb = quantise(input, 16, 16, {
+            colours: 8,
+            algorithm: "rgbquant",
+        });
+
+        expect(wu.paletteSize).toBeLessThanOrEqual(8);
+        expect(neu.paletteSize).toBeLessThanOrEqual(8);
+        expect(rgb.paletteSize).toBeLessThanOrEqual(8);
+    });
+
+    it("throws on invalid dimensions", { timeout: 5000 }, () => {
+        expect(() => quantise(new Uint8Array(4), 0, 1)).toThrow(
+            QuantisationError
+        );
+        try {
+            quantise(new Uint8Array(4), 0, 1);
+        } catch (err) {
+            expect((err as QuantisationError).code).toBe(
+                QUANTISATION_CODES.INVALID_DIMENSIONS
+            );
+        }
+    });
+
+    it("throws on mismatched buffer size", { timeout: 5000 }, () => {
+        expect(() => quantise(new Uint8Array(4), 2, 2)).toThrow(
+            QuantisationError
+        );
+        try {
+            quantise(new Uint8Array(4), 2, 2);
+        } catch (err) {
+            expect((err as QuantisationError).code).toBe(
+                QUANTISATION_CODES.INVALID_PIXEL_BUFFER
+            );
+        }
+    });
+
+    it("supports riemersma dithering", { timeout: 30000 }, () => {
+        const result = quantise(gradient(16, 16), 16, 16, {
+            colours: 8,
+            dither: "riemersma",
+        });
+        expect(result.paletteSize).toBeLessThanOrEqual(8);
+    });
+
+    it("quantiseAdaptive uses recommended settings", { timeout: 30000 }, () => {
+        const result = quantiseAdaptive(gradient(16, 16), 16, 16, 8, true, {
+            algorithm: "neuquant",
+        });
+        expect(result.paletteSize).toBeLessThanOrEqual(8);
+        expect(result.options.dither).toBe("floyd-steinberg");
+        expect(result.options.algorithm).toBe("neuquant");
+    });
+
+    it("quantiseAdaptive works without overrides", { timeout: 30000 }, () => {
+        const result = quantiseAdaptive(gradient(16, 16), 16, 16, 8, false);
+        expect(result.paletteSize).toBeLessThanOrEqual(8);
+        expect(result.options.dither).toBe("none");
+        expect(result.options.algorithm).toBe("wuquant");
+    });
+
+    it("throws on invalid options", { timeout: 5000 }, () => {
+        expect(() =>
+            quantise(solidBuffer(4, 4, 255, 0, 0), 4, 4, { colours: 1 })
+        ).toThrow(QuantisationError);
+    });
+});

packages/media/image/image-quantisation/src/quantise/quantise.ts

@@ -0,0 +1,191 @@
+import type { Counter, Histogram } from "@opentelemetry/api";
+import { metrics } from "@opentelemetry/api";
+import type { ImageQuantization } from "image-q";
+import { applyPaletteSync, buildPaletteSync, utils } from "image-q";
+import {
+    DEFAULT_ALGORITHM,
+    DEFAULT_COLOURS,
+    DEFAULT_DISTANCE,
+    DEFAULT_DITHER,
+} from "../constants/index.js";
+import {
+    QUANTISATION_CODES,
+    QuantisationError,
+} from "../errors/image-quantisation-error.js";
+import { QuantiseOptionsSchema } from "../schemas/options.schema.js";
+import type {
+    DitherAlgorithm,
+    QuantiseOptions,
+    QuantiseResult,
+    RGBA,
+} from "../types/common.js";
+
+/** OTel metric names. */
+const METRIC_QUANTISE_TOTAL = "image_quantisation.quantise.total";
+const METRIC_QUANTISE_DURATION_MS = "image_quantisation.quantise.duration_ms";
+
+let quantiseCounter: Counter | undefined;
+let quantiseDuration: Histogram | undefined;
+
+function getCounter(): Counter {
+    if (!quantiseCounter) {
+        const meter = metrics.getMeter("@suaveplan/image-quantisation");
+        quantiseCounter = meter.createCounter(METRIC_QUANTISE_TOTAL, {
+            description: "Total number of quantise() invocations",
+        });
+    }
+    return quantiseCounter;
+}
+
+function getDuration(): Histogram {
+    if (!quantiseDuration) {
+        const meter = metrics.getMeter("@suaveplan/image-quantisation");
+        quantiseDuration = meter.createHistogram(METRIC_QUANTISE_DURATION_MS, {
+            description: "Duration of quantise() in milliseconds",
+            unit: "ms",
+        });
+    }
+    return quantiseDuration;
+}
+
+/** Map our dither names to image-q's imageQuantization strings. */
+function mapDither(d: DitherAlgorithm): ImageQuantization {
+    switch (d) {
+        case "floyd-steinberg":
+            return "floyd-steinberg";
+        case "riemersma":
+            return "riemersma";
+        /* istanbul ignore next — DitherAlgorithm union is exhaustive */
+        default:
+            return "nearest";
+    }
+}
+
+/**
+ * Validate a pixel buffer and dimensions.
+ */
+function validateInput(
+    pixels: Uint8Array,
+    width: number,
+    height: number
+): void {
+    if (width <= 0 || height <= 0) {
+        throw new QuantisationError(
+            QUANTISATION_CODES.INVALID_DIMENSIONS,
+            "quantisation.invalid_dimensions",
+            { cause: new Error(`width=${width}, height=${height}`) }
+        );
+    }
+    if (pixels.length !== width * height * 4) {
+        throw new QuantisationError(
+            QUANTISATION_CODES.INVALID_PIXEL_BUFFER,
+            "quantisation.invalid_pixel_buffer",
+            {
+                cause: new Error(
+                    `expected ${width * height * 4} bytes, got ${pixels.length}`
+                ),
+            }
+        );
+    }
+}
+
+/**
+ * Quantise an RGBA pixel buffer down to a target number of colours.
+ * Wraps image-q's sync API with ergonomic options.
+ */
+export function quantise(
+    pixels: Uint8Array,
+    width: number,
+    height: number,
+    options: QuantiseOptions = {}
+): QuantiseResult {
+    const start = performance.now();
+    validateInput(pixels, width, height);
+
+    const parsed = QuantiseOptionsSchema.safeParse(options);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ");
+        throw new QuantisationError(
+            QUANTISATION_CODES.PROCESSING_FAILED,
+            `quantisation.invalid_options: ${issues}`
+        );
+    }
+
+    const opts = {
+        colours: parsed.data.colours ?? DEFAULT_COLOURS,
+        algorithm: parsed.data.algorithm ?? DEFAULT_ALGORITHM,
+        distance: parsed.data.distance ?? DEFAULT_DISTANCE,
+        dither: parsed.data.dither ?? DEFAULT_DITHER,
+    };
+
+    const inContainer = utils.PointContainer.fromUint8Array(
+        pixels,
+        width,
+        height
+    );
+
+    const palette = buildPaletteSync([inContainer], {
+        colorDistanceFormula: opts.distance,
+        paletteQuantization: opts.algorithm,
+        colors: opts.colours,
+    });
+
+    const outContainer = applyPaletteSync(inContainer, palette, {
+        colorDistanceFormula: opts.distance,
+        imageQuantization: mapDither(opts.dither),
+    });
+
+    const outPixels = outContainer.toUint8Array();
+
+    const palettePoints = palette.getPointContainer().getPointArray();
+    const paletteColours: RGBA[] = palettePoints.map((p) => ({
+        r: p.r,
+        g: p.g,
+        b: p.b,
+        a: p.a,
+    }));
+
+    const duration = performance.now() - start;
+    const counter = getCounter();
+    const histogram = getDuration();
+    counter.add(1, {
+        "quantisation.algorithm": opts.algorithm,
+        "quantisation.dither": opts.dither,
+    });
+    histogram.record(duration, {
+        "quantisation.algorithm": opts.algorithm,
+        "quantisation.dither": opts.dither,
+    });
+
+    return {
+        pixels: outPixels,
+        width,
+        height,
+        palette: paletteColours,
+        paletteSize: paletteColours.length,
+        options: opts,
+    };
+}
+
+/**
+ * Quantise with automatic options based on complexity tier.
+ * Uses the recommended colour count and dithering preference.
+ */
+export function quantiseAdaptive(
+    pixels: Uint8Array,
+    width: number,
+    height: number,
+    recommendedColours: number,
+    recommendDithering: boolean,
+    overrides: Partial<QuantiseOptions> = {}
+): QuantiseResult {
+    return quantise(pixels, width, height, {
+        colours: recommendedColours,
+        algorithm: "wuquant",
+        distance: "euclidean",
+        dither: recommendDithering ? "floyd-steinberg" : "none",
+        ...overrides,
+    });
+}

packages/media/image/image-quantisation/src/schemas/index.ts

@@ -0,0 +1,13 @@
+export type {
+    AdaptivePipelineOptionsInput,
+    AdaptivePipelineOptionsParsed,
+    QuantiseOptionsInput,
+    QuantiseOptionsParsed,
+    SpatialCleanupOptionsInput,
+    SpatialCleanupOptionsParsed,
+} from "./options.schema.js";
+export {
+    AdaptivePipelineOptionsSchema,
+    QuantiseOptionsSchema,
+    SpatialCleanupOptionsSchema,
+} from "./options.schema.js";

packages/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.

packages/media/image/image-quantisation/src/schemas/options.schema.ts

@@ -0,0 +1,68 @@
+import z from "zod";
+
+/**
+ * Zod schema for validating `QuantiseOptions` at runtime.
+ *
+ * All fields are optional. Out-of-range values are rejected with
+ * descriptive error messages so callers get actionable feedback.
+ */
+export const QuantiseOptionsSchema = z.object({
+    colours: z
+        .number()
+        .int()
+        .min(2, "colours must be between 2 and 256")
+        .max(256, "colours must be between 2 and 256")
+        .optional(),
+    algorithm: z.enum(["neuquant", "rgbquant", "wuquant"]).optional(),
+    distance: z.enum(["euclidean", "manhattan", "ciede2000"]).optional(),
+    dither: z.enum(["none", "floyd-steinberg", "riemersma"]).optional(),
+});
+
+export type QuantiseOptionsInput = z.input<typeof QuantiseOptionsSchema>;
+export type QuantiseOptionsParsed = z.output<typeof QuantiseOptionsSchema>;
+
+/**
+ * Zod schema for validating `SpatialCleanupOptions` at runtime.
+ */
+export const SpatialCleanupOptionsSchema = z.object({
+    maxDistance: z
+        .number()
+        .min(0, "maxDistance must be non-negative")
+        .optional(),
+    maxPoolSize: z
+        .number()
+        .int()
+        .min(0, "maxPoolSize must be non-negative")
+        .optional(),
+});
+
+export type SpatialCleanupOptionsInput = z.input<
+    typeof SpatialCleanupOptionsSchema
+>;
+export type SpatialCleanupOptionsParsed = z.output<
+    typeof SpatialCleanupOptionsSchema
+>;
+
+/**
+ * Zod schema for validating `AdaptivePipelineOptions` at runtime.
+ */
+export const AdaptivePipelineOptionsSchema = z.object({
+    maxColours: z
+        .number()
+        .int()
+        .min(2, "maxColours must be between 2 and 256")
+        .max(256, "maxColours must be between 2 and 256")
+        .optional(),
+    dither: z.enum(["none", "floyd-steinberg", "riemersma"]).optional(),
+    spatial: SpatialCleanupOptionsSchema.optional(),
+    skipSpatialCleanup: z.boolean().optional(),
+    skipQuantisationForPixelArt: z.boolean().optional(),
+});
+
+export type AdaptivePipelineOptionsInput = z.input<
+    typeof AdaptivePipelineOptionsSchema
+>;
+export type AdaptivePipelineOptionsParsed = z.output<
+    typeof AdaptivePipelineOptionsSchema
+>;
+// schema: boundary-only

packages/media/image/image-quantisation/src/spatial/cleanup/cleanup.md

@@ -0,0 +1,69 @@
+# Spatial Cleanup
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Merge small anti-aliasing pools into their nearest spatial neighbours by colour distance. This preserves intentional detail while removing AA noise. Unlike global k-means quantisation, spatial cleanup only merges pools that are physically adjacent, so a small blue dot next to a red region stays blue while a near-red edge pixel gets absorbed into the red region.
+
+## Features
+
+- Spatially-aware merge (not global k-means)
+- Configurable colour distance and pool size thresholds
+- Returns a new pixel buffer (non-destructive)
+- Fast pixel-to-pool index lookup via `Int32Array`
+
+## Usage: Basic Example
+
+```ts
+import {
+    detectPools,
+    spatialCleanup,
+} from "@suaveplan/image-quantisation";
+
+const pools = detectPools(pixels, 32, 32);
+const cleaned = spatialCleanup(pixels, 32, 32, pools);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    detectPools,
+    spatialCleanup,
+    countUniqueColours,
+} from "@suaveplan/image-quantisation";
+
+const pools = detectPools(pixels, 64, 64);
+const before = countUniqueColours(pixels, 64, 64);
+
+const cleaned = spatialCleanup(pixels, 64, 64, pools, {
+    maxDistance: 25,
+    maxPoolSize: 3,
+});
+
+const after = countUniqueColours(cleaned, 64, 64);
+console.log(`Removed ${before - after} colours`);
+```
+
+## API Reference
+
+### `spatialCleanup(pixels, width, height, pools, options?): Uint8Array`
+
+- `pixels` — RGBA `Uint8Array`
+- `width`, `height` — image dimensions
+- `pools` — array of `Pool` from `detectPools`
+- `options.maxDistance` — default 30
+- `options.maxPoolSize` — default 4
+
+Returns a new `Uint8Array` with merged pixels.
+
+### `countUniqueColours(pixels, width, height): number`
+
+Counts distinct colours in the buffer using a 32-bit packed key.
+
+## Implementation Notes
+
+The algorithm builds an adjacency map for pools that are physically adjacent in the image. For each small pool, it finds the neighbour with the minimum `rgbDistance`. If the distance is within `maxDistance`, the pool is recoloured. The pixel-to-pool index is stored in an `Int32Array` initialised to `-1` for fast O(1) lookup during adjacency building.

packages/media/image/image-quantisation/src/spatial/cleanup/cleanup.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import { detectPools } from "../../analysis/pools/pools.js";
+import { countUniqueColours, spatialCleanup } from "./cleanup.js";
+
+function aaEdgeBuffer(): { pixels: Uint8Array; width: number; height: number } {
+    const w = 8;
+    const h = 4;
+    const buf = new Uint8Array(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            if (x < 3) {
+                buf[i] = 200;
+                buf[i + 1] = 20;
+                buf[i + 2] = 20;
+                buf[i + 3] = 255;
+            } else if (x === 3) {
+                buf[i] = 195;
+                buf[i + 1] = 25;
+                buf[i + 2] = 30;
+                buf[i + 3] = 255;
+            } else {
+                buf[i] = 20;
+                buf[i + 1] = 20;
+                buf[i + 2] = 200;
+                buf[i + 3] = 255;
+            }
+        }
+    }
+    return { pixels: buf, width: w, height: h };
+}
+
+describe("spatialCleanup", () => {
+    it("merges near-colour AA pixels into spatial neighbours", {
+        timeout: 5000,
+    }, () => {
+        const { pixels, width, height } = aaEdgeBuffer();
+        const origColours = countUniqueColours(pixels, width, height);
+        expect(origColours).toBe(3);
+
+        const pools = detectPools(pixels, width, height);
+        const cleaned = spatialCleanup(pixels, width, height, pools, {
+            maxDistance: 30,
+            maxPoolSize: 4,
+        });
+
+        const cleanedColours = countUniqueColours(cleaned, width, height);
+        expect(cleanedColours).toBe(2);
+    });
+
+    it("does not merge pools above maxPoolSize", { timeout: 5000 }, () => {
+        const { pixels, width, height } = aaEdgeBuffer();
+        const pools = detectPools(pixels, width, height);
+        const cleaned = spatialCleanup(pixels, width, height, pools, {
+            maxDistance: 30,
+            maxPoolSize: 0,
+        });
+
+        const cleanedColours = countUniqueColours(cleaned, width, height);
+        expect(cleanedColours).toBe(3);
+    });
+
+    it("does not merge pools with distant colours", { timeout: 5000 }, () => {
+        const { pixels, width, height } = aaEdgeBuffer();
+        const pools = detectPools(pixels, width, height);
+        const cleaned = spatialCleanup(pixels, width, height, pools, {
+            maxDistance: 1,
+            maxPoolSize: 10,
+        });
+
+        const cleanedColours = countUniqueColours(cleaned, width, height);
+        expect(cleanedColours).toBe(3);
+    });
+
+    it("uses default options when none provided", { timeout: 5000 }, () => {
+        const { pixels, width, height } = aaEdgeBuffer();
+        const pools = detectPools(pixels, width, height);
+        const cleaned = spatialCleanup(pixels, width, height, pools);
+        const cleanedColours = countUniqueColours(cleaned, width, height);
+        expect(cleanedColours).toBe(2);
+    });
+
+    it("handles small pool at image edge", { timeout: 5000 }, () => {
+        // 4x1: red | red | red | near-red (small pool at right edge)
+        const w = 4;
+        const h = 1;
+        const buf = new Uint8Array(w * h * 4);
+        for (let x = 0; x < w; x++) {
+            const i = x * 4;
+            if (x < 3) {
+                buf[i] = 200;
+                buf[i + 1] = 20;
+                buf[i + 2] = 20;
+                buf[i + 3] = 255;
+            } else {
+                buf[i] = 195;
+                buf[i + 1] = 25;
+                buf[i + 2] = 30;
+                buf[i + 3] = 255;
+            }
+        }
+        const pools = detectPools(buf, w, h);
+        const cleaned = spatialCleanup(buf, w, h, pools, {
+            maxDistance: 30,
+            maxPoolSize: 1,
+        });
+        expect(countUniqueColours(cleaned, w, h)).toBe(1);
+    });
+
+    it("handles 1x1 image (no neighbours)", { timeout: 5000 }, () => {
+        const buf = new Uint8Array([255, 0, 0, 255]);
+        const pools = detectPools(buf, 1, 1);
+        const cleaned = spatialCleanup(buf, 1, 1, pools, {
+            maxDistance: 30,
+            maxPoolSize: 1,
+        });
+        expect(cleaned).toEqual(buf);
+    });
+
+    it("handles small pool at left edge", { timeout: 5000 }, () => {
+        // 2x1: near-red | red (small pool at left edge)
+        const w = 2;
+        const h = 1;
+        const buf = new Uint8Array(w * h * 4);
+        buf.set([195, 25, 30, 255], 0);
+        buf.set([200, 20, 20, 255], 4);
+        const pools = detectPools(buf, w, h);
+        const cleaned = spatialCleanup(buf, w, h, pools, {
+            maxDistance: 30,
+            maxPoolSize: 1,
+        });
+        expect(cleaned.length).toBe(w * h * 4);
+    });
+});
+
+describe("countUniqueColours", () => {
+    it("counts correctly for simple buffers", { timeout: 5000 }, () => {
+        const buf = new Uint8Array([
+            255, 0, 0, 255, 255, 0, 0, 255, 0, 0, 255, 255, 0, 255, 0, 255,
+        ]);
+        expect(countUniqueColours(buf, 2, 2)).toBe(3);
+    });
+});

packages/media/image/image-quantisation/src/spatial/cleanup/cleanup.ts

@@ -0,0 +1,119 @@
+import { rgbDistance } from "../../analysis/colour/colour.js";
+import {
+    DEFAULT_MAX_DISTANCE,
+    DEFAULT_MAX_POOL_SIZE,
+} from "../../constants/index.js";
+import type { Pool, SpatialCleanupOptions } from "../../types/common.js";
+
+/**
+ * Spatially-aware anti-aliasing cleanup.
+ *
+ * For each small pool (≤ maxPoolSize pixels), find its spatial neighbours
+ * (pools that are physically adjacent in the image) and merge it into
+ * the nearest neighbour by colour distance — but only if the distance
+ * is below maxDistance.
+ *
+ * This is fundamentally different from global k-means quantisation:
+ * a 2-pixel blue pool next to a red region stays blue (distance too high),
+ * but a 2-pixel rgb(102,51,21) pool next to rgb(100,50,20) gets absorbed.
+ *
+ * Returns a new pixel buffer with the small pools recoloured.
+ */
+export function spatialCleanup(
+    pixels: Uint8Array,
+    width: number,
+    height: number,
+    pools: Pool[],
+    options: SpatialCleanupOptions = {}
+): Uint8Array {
+    const opts = {
+        maxDistance: options.maxDistance ?? DEFAULT_MAX_DISTANCE,
+        maxPoolSize: options.maxPoolSize ?? DEFAULT_MAX_POOL_SIZE,
+    };
+    const output = new Uint8Array(pixels);
+
+    // Build pixel→pool index
+    const pixelToPool = new Int32Array(width * height).fill(-1);
+    for (let pi = 0; pi < pools.length; pi++) {
+        for (const idx of pools[pi]!.pixels) {
+            pixelToPool[idx] = pi;
+        }
+    }
+
+    // Build adjacency: for each pool, find which other pools are spatial neighbours
+    const adjacency = new Map<number, Set<number>>();
+
+    for (let pi = 0; pi < pools.length; pi++) {
+        if (pools[pi]!.size > opts.maxPoolSize) continue;
+
+        const neighbours = new Set<number>();
+        for (const idx of pools[pi]!.pixels) {
+            const x = idx % width;
+            const y = Math.floor(idx / width);
+
+            const adj = [
+                y > 0 ? idx - width : -1,
+                y < height - 1 ? idx + width : -1,
+                x > 0 ? idx - 1 : -1,
+                x < width - 1 ? idx + 1 : -1,
+            ];
+
+            for (const n of adj) {
+                if (n < 0) continue;
+                const nPool = pixelToPool[n]!;
+                if (nPool >= 0 && nPool !== pi) neighbours.add(nPool);
+            }
+        }
+
+        if (neighbours.size > 0) adjacency.set(pi, neighbours);
+    }
+
+    // Merge small pools into nearest spatial neighbour
+    for (const [smallIdx, neighbourSet] of adjacency) {
+        const smallPool = pools[smallIdx]!;
+        let bestNeighbour: Pool | null = null;
+        let bestDist = Number.POSITIVE_INFINITY;
+
+        for (const nIdx of neighbourSet) {
+            const neighbour = pools[nIdx]!;
+            const dist = rgbDistance(smallPool.colour, neighbour.colour);
+            if (dist < bestDist) {
+                bestDist = dist;
+                bestNeighbour = neighbour;
+            }
+        }
+
+        if (bestNeighbour && bestDist <= opts.maxDistance) {
+            // Recolour the small pool's pixels to the neighbour's colour
+            for (const idx of smallPool.pixels) {
+                const off = idx * 4;
+                output[off] = bestNeighbour.colour.r;
+                output[off + 1] = bestNeighbour.colour.g;
+                output[off + 2] = bestNeighbour.colour.b;
+                output[off + 3] = bestNeighbour.colour.a;
+            }
+        }
+    }
+
+    return output;
+}
+
+/** Count unique colours in a pixel buffer. */
+export function countUniqueColours(
+    pixels: Uint8Array,
+    width: number,
+    height: number
+): number {
+    const seen = new Set<number>();
+    const total = width * height;
+    for (let i = 0; i < total; i++) {
+        const off = i * 4;
+        const key =
+            (pixels[off]! << 24) |
+            (pixels[off + 1]! << 16) |
+            (pixels[off + 2]! << 8) |
+            pixels[off + 3]!;
+        seen.add(key);
+    }
+    return seen.size;
+}

packages/media/image/image-quantisation/src/spatial/cleanup/index.ts

@@ -0,0 +1 @@
+export { countUniqueColours, spatialCleanup } from "./cleanup.js";

packages/media/image/image-quantisation/src/types/common.md

@@ -0,0 +1,114 @@
+# Common Types
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `common.ts` module defines the core domain types used across the `@suaveplan/image-quantisation` package. Every public function operates on these shapes, so consumers should import them when writing TypeScript wrappers or adapters. Keeping types in a single module ensures consistency between analysis, quantisation, and pipeline stages. The types are designed to be serialisable, tree-shakeable, and free of runtime dependencies.
+
+## Features
+
+- Strongly-typed RGBA pixel representation
+- Pool and edge-analysis result shapes
+- Quantisation option and result types
+- Adaptive pipeline input/output types
+
+## Usage: Basic Example
+
+```ts
+import type { RGBA, QuantiseOptions } from "@suaveplan/image-quantisation/types";
+
+const pixel: RGBA = { r: 255, g: 128, b: 64, a: 255 };
+
+const opts: QuantiseOptions = {
+    colours: 16,
+    algorithm: "wuquant",
+    distance: "euclidean",
+    dither: "none",
+};
+```
+
+## Usage: Advanced Example
+
+```ts
+import type {
+    AdaptivePipelineOptions,
+    ComplexityAnalysis,
+} from "@suaveplan/image-quantisation/types";
+
+function buildPipelineOpts(
+    analysis: ComplexityAnalysis
+): AdaptivePipelineOptions {
+    return {
+        maxColours: analysis.recommendedColours,
+        dither: analysis.recommendDithering ? "floyd-steinberg" : "none",
+        spatial: { maxDistance: 25, maxPoolSize: 3 },
+        skipSpatialCleanup: false,
+        skipQuantisationForPixelArt: true,
+    };
+}
+```
+
+## API Reference
+
+### `RGBA`
+
+Interface with `r`, `g`, `b`, `a` in the range 0–255.
+
+### `Pool`
+
+Represents a contiguous region of identical colour found via 4-connected flood fill.
+
+### `PoolDistribution`
+
+Statistics object: `count`, `min`, `max`, `mean`, `median`, `p90`, `singletons`, `singletonRatio`.
+
+### `EdgeAnalysis`
+
+Metrics: `totalEdges`, `hardEdges`, `softEdges`, `sharpnessRatio`, `meanEdgeDistance`.
+
+### `ComplexityTier`
+
+Union type: `"pixel-art" | "vector-clean" | "vector-aa" | "photographic"`.
+
+### `ComplexityAnalysis`
+
+Full analysis including tier, pools, edges, and recommendations.
+
+### `PaletteAlgorithm`
+
+`"neuquant" | "rgbquant" | "wuquant"`.
+
+### `DistanceFormula`
+
+`"euclidean" | "manhattan" | "ciede2000"`.
+
+### `DitherAlgorithm`
+
+`"none" | "floyd-steinberg" | "riemersma"`.
+
+### `QuantiseOptions`
+
+Optional fields: `colours`, `algorithm`, `distance`, `dither`.
+
+### `QuantiseResult`
+
+Result with `pixels`, `palette`, `paletteSize`, and the resolved `options`.
+
+### `SpatialCleanupOptions`
+
+Optional fields: `maxDistance`, `maxPoolSize`.
+
+### `AdaptivePipelineOptions`
+
+Optional fields: `maxColours`, `dither`, `spatial`, `skipSpatialCleanup`, `skipQuantisationForPixelArt`.
+
+### `AdaptivePipelineResult`
+
+Full pipeline result with analysis, optional quantisation, and final pixel buffer.
+
+## Implementation Notes
+
+All interfaces are pure data shapes with no methods. They are designed to be serialisable and tree-shakeable. The `Pool` interface uses `Set<number>` for pixel indices, which is efficient for BFS traversal but may be replaced with a denser representation in future versions if memory becomes a concern for very large images.

packages/media/image/image-quantisation/src/types/common.ts

@@ -0,0 +1,146 @@
+/** Raw RGBA pixel (0–255 per channel). */
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+
+/** A contiguous region of identical colour (4-connected flood fill). */
+export interface Pool {
+    /** Canonical colour key "r,g,b,a". */
+    colourKey: string;
+    colour: RGBA;
+    /** Packed pixel indices. */
+    pixels: Set<number>;
+    size: number;
+    /** Bounding box. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
+/** Distribution stats for pool sizes. */
+export interface PoolDistribution {
+    count: number;
+    min: number;
+    max: number;
+    mean: number;
+    median: number;
+    p90: number;
+    /** Pools with size === 1. */
+    singletons: number;
+    /** Fraction of pools that are singletons. */
+    singletonRatio: number;
+}
+
+/** Edge analysis between adjacent pixels. */
+export interface EdgeAnalysis {
+    /** Total adjacent pixel pairs examined. */
+    totalEdges: number;
+    /** Pairs where colour distance > hardThreshold. */
+    hardEdges: number;
+    /** Pairs where colour distance ≤ softThreshold. */
+    softEdges: number;
+    /** hardEdges / totalEdges. */
+    sharpnessRatio: number;
+    /** Mean colour distance across all edges. */
+    meanEdgeDistance: number;
+}
+
+/** Image complexity classification. */
+export type ComplexityTier =
+    | "pixel-art"
+    | "vector-clean"
+    | "vector-aa"
+    | "photographic";
+
+/** Full complexity analysis result. */
+export interface ComplexityAnalysis {
+    width: number;
+    height: number;
+    totalPixels: number;
+    uniqueColours: number;
+    pools: Pool[];
+    poolDistribution: PoolDistribution;
+    edgeAnalysis: EdgeAnalysis;
+    tier: ComplexityTier;
+    /** Recommended starting palette size for quantisation. */
+    recommendedColours: number;
+    /** Whether dithering is recommended. */
+    recommendDithering: boolean;
+}
+
+/** Palette quantisation algorithm. */
+export type PaletteAlgorithm = "neuquant" | "rgbquant" | "wuquant";
+
+/** Colour distance formula. */
+export type DistanceFormula = "euclidean" | "manhattan" | "ciede2000";
+
+/** Dithering algorithm. */
+export type DitherAlgorithm = "none" | "floyd-steinberg" | "riemersma";
+
+/** Options for quantisation. */
+export interface QuantiseOptions {
+    /** Target number of colours (default: 256). */
+    colours?: number | undefined;
+    /** Palette generation algorithm. */
+    algorithm?: PaletteAlgorithm | undefined;
+    /** Colour distance formula. */
+    distance?: DistanceFormula | undefined;
+    /** Dithering algorithm (default: none for emblem use). */
+    dither?: DitherAlgorithm | undefined;
+}
+
+/** Result of quantisation. */
+export interface QuantiseResult {
+    /** Quantised RGBA pixel buffer (4 bytes per pixel). */
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+    /** The palette that was generated. */
+    palette: RGBA[];
+    /** Number of colours in the palette. */
+    paletteSize: number;
+    /** Options that were used. */
+    options: Required<QuantiseOptions>;
+}
+
+/** Options for spatial AA cleanup. */
+export interface SpatialCleanupOptions {
+    /** Maximum colour distance to consider "anti-aliasing noise" (default: 30). */
+    maxDistance?: number | undefined;
+    /** Maximum pool size to consider for merging (default: 4 pixels). */
+    maxPoolSize?: number | undefined;
+}
+
+/** Options for the full adaptive pipeline. */
+export interface AdaptivePipelineOptions {
+    /** Override max colours (otherwise auto-determined). */
+    maxColours?: number | undefined;
+    /** Override dithering (otherwise auto-determined). */
+    dither?: QuantiseOptions["dither"];
+    /** Spatial cleanup options. */
+    spatial?: SpatialCleanupOptions | undefined;
+    /** Skip spatial cleanup entirely (default: false). */
+    skipSpatialCleanup?: boolean | undefined;
+    /** Skip quantisation for pixel-art tier (default: true). */
+    skipQuantisationForPixelArt?: boolean | undefined;
+}
+
+/** Result of the full adaptive pipeline. */
+export interface AdaptivePipelineResult {
+    /** Final pixel buffer ready for emblem-solver. */
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+    /** Complexity analysis of the original image. */
+    analysis: ComplexityAnalysis;
+    /** Quantisation result (null if skipped). */
+    quantisation: QuantiseResult | null;
+    /** Whether spatial cleanup was applied. */
+    spatialCleanupApplied: boolean;
+    /** Final unique colour count. */
+    finalColours: number;
+}

packages/media/image/image-quantisation/src/types/index.ts

@@ -0,0 +1,16 @@
+export type {
+    AdaptivePipelineOptions,
+    AdaptivePipelineResult,
+    ComplexityAnalysis,
+    ComplexityTier,
+    DistanceFormula,
+    DitherAlgorithm,
+    EdgeAnalysis,
+    PaletteAlgorithm,
+    Pool,
+    PoolDistribution,
+    QuantiseOptions,
+    QuantiseResult,
+    RGBA,
+    SpatialCleanupOptions,
+} from "./common.js";

packages/media/image/image-quantisation/tsconfig.lib.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "lib": ["ES2022"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "dist", "node_modules"]
+}

packages/media/image/image-quantisation/vite.config.ts

@@ -0,0 +1,43 @@
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: {
+        index: "./src/index.ts",
+        "analysis/classify": "./src/analysis/classify/index.ts",
+        "analysis/colour": "./src/analysis/colour/index.ts",
+        "analysis/edges": "./src/analysis/edges/index.ts",
+        "analysis/pools": "./src/analysis/pools/index.ts",
+        errors: "./src/errors/index.ts",
+        pipeline: "./src/pipeline/index.ts",
+        quantise: "./src/quantise/index.ts",
+        schemas: "./src/schemas/index.ts",
+        "spatial/cleanup": "./src/spatial/cleanup/index.ts",
+        types: "./src/types/index.ts",
+      },
+      formats: ["es"],
+    },
+    rollupOptions: {
+      external: [
+        /^@suaveplan\//,
+        /^@opentelemetry\//,
+        "image-q",
+        "zod",
+        "tslib",
+      ],
+      output: {
+        exports: "named",
+      },
+    },
+    sourcemap: true,
+    target: "es2022",
+  },
+  plugins: [
+    dts({
+      tsconfigPath: "./tsconfig.lib.json",
+      entryRoot: "./src",
+    }),
+  ],
+});

packages/media/image/image-quantisation/vitest.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: "node",
+    pool: "forks",
+    setupFiles: ["@suaveplan/testing/polyfills"],
+    include: ["src/**/*.test.ts"],
+    exclude: ["dist/**", "node_modules/**"],
+    coverage: {
+      provider: "istanbul",
+      reporter: ["text", "html", "lcov"],
+      include: ["src/**/*.ts"],
+      exclude: [
+        "src/**/*.test.ts",
+        "src/**/*.types.ts",
+        "src/**/index.ts",
+        "src/__benchmarks__/**",
+      ],
+      thresholds: { statements: 100, branches: 100, functions: 100, lines: 100 },
+    },
+    testTimeout: 5000,
+  },
+});