# `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.