first commit

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

@@ -0,0 +1,73 @@
+# `fixtures/fixtures.ts` — canonical regression grids
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module is the canonical test-fixture surface for the package. Each
+exported function returns a deterministic `RGBA[]` grid with known
+algorithmic properties — chessboards, donuts, crosses, T-shapes, stars,
+flags, shields, and crests. Together they form the regression suite that
+locks the solver's quality numbers in place: any change that regresses
+the rect count on one of these fixtures fails the test gate.
+
+## Features
+
+- Twelve fixtures total: `chessboard8x8`, `cross3x3`, `cross6x6`,
+  `tShape`, `donut5x5`, `circle16`, `flagCrosses`, `multiIslandStripes`,
+  `shieldEmblem32`, `crest12x12`, `star`, plus the added
+  `nineColours` (>8 distinct colours, used to exercise the auto-ordering
+  heuristic branch).
+- Every fixture is purely declarative — built from a `number[][]` palette
+  index map and `fromIndexedGrid`. No randomness, no `Date.now`, no
+  module-load side effects.
+- Index `0` is reserved for transparency; every fixture follows that
+  convention.
+
+## Usage: Basic
+
+```ts
+import { chessboard8x8 } from "@suaveplan/emblem-solver";
+
+const { pixels, width, height } = chessboard8x8();
+```
+
+## Usage: Advanced
+
+```ts
+import { convert, crest12x12 } from "@suaveplan/emblem-solver";
+
+const { pixels, width, height } = crest12x12();
+const result = convert(pixels, width, height, { layerOrder: "auto" });
+console.log(`crest compressed to ${result.totalRects} rects`);
+```
+
+## API Reference
+
+| Symbol | Returns |
+|---|---|
+| `chessboard8x8()` | 8x8 alternating black/white grid |
+| `cross3x3()` / `cross6x6()` | Plus-sign crosses |
+| `tShape()` | 5x4 T-shape |
+| `donut5x5()` | Frame with transparent centre |
+| `circle16()` | 16-px pixel circle |
+| `flagCrosses()` | 16x16 layered three-colour flag |
+| `multiIslandStripes()` | 10x2 alternating two-colour stripes |
+| `shieldEmblem32()` | 32x32 three-colour shield |
+| `crest12x12()` | 12x12 four-colour crest |
+| `star()` | Irregular star outline |
+| `nineColours()` | 4x4 grid with nine distinct colours |
+
+## Implementation Notes
+
+The fixtures are exported as zero-argument functions rather than constants
+so each test call builds a fresh pixel array — the solver does not
+mutate its input, but defensive copies keep test isolation strong. The
+`nineColours` grid exists specifically to push `factorial(colourCount) >
+maxPermutations` so the heuristic + sampling branch in `convert()` is
+exercised; without it that branch would be unreachable and coverage would
+drop. Fixtures are excluded from the package's coverage threshold
+(`coverage.exclude` in `vitest.config.ts`) because they are test
+material, not production code.