# Painting grammar — paint from the subject's own palette

**Slug:** `painting-grammar` · **Lesson:** `paint-own-palette` · **Status:** check green in this tree (tally in the library receipt; registry flip is the integrator's step).

## Lesson

A character is painted, not computed. The engine knows no shading
grammar: it fills each index region of the stock sprite with the
flat material tone that *that character's own spec* assigns, then
applies the spec's hand-placed ops (rects / rows / pixels / sub-pixel
rects, in sprite coordinates, in order), every one clipped to the
untouched stock silhouette. Every light, deep and detail in the
output is a coordinate a painter chose for that character and
recorded in its spec.

The convicted failure this replaces: the v18 builder poured one
generic grammar into every character — a neutral ramp
((115,115,115) / (192,192,192) steps) standing in for materials —
and discarded each palette's own identity colour (palette 0's
periwinkle (123,113,198) is the stock assignment's *discarded* hue).
The fix is structural, not tonal: this module's exported API is only
`pk565`, `exp565`, `idxmap`, `up4`, `stockAssign`, `paintGrid`,
`entriesFromPaint`, `zeroOnOpaque`, `ALLOWED_OPS`. There is no
gradient, light-field, seam or strand entry point, and an op the
engine does not know is refused (`unknown op`) — the convicted
grammar cannot be requested, let alone produced.

Two arithmetic laws ride along:

- **pk565 sentinel floor (fail-closed).** 565 value 0 is the
  never-sampled transparent sentinel. An opaque-destined colour is
  floored to the darkest non-zero 565 step *per channel* (pure black
  floors to 1), so a painted texel can never quantize down to the
  sentinel and drop at render time. This is the floor the artwork
  pack's gate stands on (see `texel-invariant`).
- **The silhouette is law.** Painting happens at 4x claim
  resolution inside the stock mask; emitted entries are 0 exactly
  where the stock pattern is transparent and non-0 everywhere
  opaque.

## Provenance

Distilled from `gbc-guest/fork-work/pipeline-grade/gamem8c-sprites1/`:

- `artwork-work/paint_lib.py` — `paint_grid` (engine + selector
  semantics, including the source's quirk that `px` clips only to
  the silhouette), `img_to_entries`, `pk565` (semantics copied from
  `build_sprites2`).
- `artwork-work/specs.py` — per-character specs (`FAMILIES`).
- `examination-work/extract_exam.py` — `idxmap`, `idx_assignment`
  (the stock palette convention: idx1 ← lightest, idx2 ← saturated,
  idx3 ← darkest; the leftover modal colour is the discarded hue).
- Charter: `RULING-character-standard.md` (founder, 2026-11-06
  23:43 EST); outcome record: `RECEIPT-better-artwork.md`
  (388 of 395 OBJ entries painted, 0 dropped to the stock floor,
  texel invariant PASS).

**Fixture extraction (throwaway, at build time):** a stdin Python
run — no script kept, per the distillation brief — imported
`specs.py` directly (spec data is not retyped), took the member
tiles of unit `sheet:rival.png:f2:p0` from `inventory.json` +
`obj_tiles.json`, assembled the 16×16 shade grid from the tiles'
2bpp bytes via `extract_exam.idxmap`, and asserted it equals
`examination-work/sprites16.sheet_sprite('rival', 2)` decoded from
the pokecrystal reference sheet. Palette: `palette_sets.json`
palette 0 (modal set, `modal_565`, assignment + discarded hue).
The result is `example/fixture.json` — real extracted data only.

## How to run

```text
node example.cjs   # paint Rival from the fixture, print summary + JSON line
node check.cjs     # self-check: prints PASS <n> FAIL <m>, exit 1 on any failure
const { runCheck } = require('./check.cjs');   // {slug, pass, fail, failures[], notes[]}
const P = require('./program.cjs');            // pk565, paintGrid, entriesFromPaint, ...
```

## Worked example

`example.cjs` paints Rival (frame 2, palette 0) — the anchor cast's
west profile — from `example/fixture.json`: 143 native opaque px
(2,288 subpx at 4x), 18 spec ops applied over the base fill, 4 claim
entries emitted, zero-on-opaque 0, 9 distinct painted colours, every
one a named tone of Rival's own spec.

## Numbers reproduced

- **Filed `modal_565`, palette 0** (`palette_sets.json`):
  pk565 of the three non-zero modal colours equals the filed values
  exactly — (255,56,8) → **63937**, (123,113,198) → **31640**,
  (255,154,82) → **64714**.
- **Filed pack gate at entry level:** zero-on-opaque == **0** across
  the painted entries (the pack-level filing is
  `RECEIPT-better-artwork.md`: texel invariant PASS, 0 across all
  claims).
- **Fixture ground truth:** per-tile opaque counts filed in
  `obj_tiles.json` sum to the shade grid's opaque count (143), and
  the tile-assembled grid was asserted equal to the reference-sheet
  sprite at extraction.

## Consumers

GameM8c art (character painting for the play build), Emerald
characters (same method, next game), emblem texture authoring (the
same transfer the founder ordered for the NASL emblem: texture
authored into the surface from the subject's own family, never
computed shading over a flat base).

## Honest limits

- One character is distilled, not the 195-unit pack: the engine is
  the full `paint_grid` (all nine op kinds, frame filtering,
  material selectors, quadrant/row/col selectors), but only Rival's
  spec ships as a fixture. Other characters' specs live in
  `specs.py` and extract by the same route.
- The hue-family assertion in the check (base idx2 tone within 15°
  of the stock identity hue) is this program's own guard, not a
  filed number; the filed claims are the `modal_565` values and the
  zero-on-opaque gate.
- Painting *quality* is not checked here and cannot be: the founder
  is the acceptance court at zoom (the pack's own rule — a painted
  candidate that does not beat its stock sprite at zoom does not
  ship). This program proves grammar and gates, not taste.
- Player units in the source use a separate canvas path
  (`canvas_to_entries` over a ROM-harvested grid); only the sheet
  path (`img_to_entries`) is ported, as `entriesFromPaint`.
