Create sprite-canon.json for a project: the single source of truth for palette, regions, scale and check thresholds. Learns the palette from sample images (colours used at least minCount times; rarer colours are usually anti-aliasing noise). Run once per project, then commit the file.

Define or update a named region in the canon (e.g. skin, hair, outfit, outline). Give a few [x,y] points on sample images; the sampled colours (optionally expanded by absorb) become the region. The region's luminance range is recorded — repaint uses that FIXED range so the same source colour always maps to the same output colour in every frame and direction. Mark regions like face/eyes/outline as protected: repaint will never touch them and verify will fail if anything else does. Instead of points you may pass explicit colors, or an HSL rule (hue/sat/light ranges) for anti-aliased art — an HSL-only region additionally needs lumRange if you ever want to repaint it. Updates MERGE additively into an existing region; pass replace=true to redefine it from scratch (the only way to remove a mis-sampled colour).

Measure a sprite's anatomy per frame and its cross-frame jitter: bounding box, top row, widest row, cap (head) width, waist (neck) row, and — with canon regions — the first row of each region (e.g. where the face starts). Use before placing anything relative to a sprite: measured rows beat guessed proportions. Real bug this catches: a hat brim placed at '52% of head height' landed exactly on the eyes, because eye rows vary per frame — measure, don't assume.

Run numeric consistency checks and get hard pass/fail numbers — the replacement for eyeballing hundreds of frames. Checks: 'palette' (every pixel on the canon palette), 'jitter' (landmarks stay put across frames), 'spread' (a region's mean luminance agrees across a file group — catches 'bright from behind, dark from the front'), 'protected' (vs baseFile: face/outline pixels untouched), 'leftover' (vs baseFile: no source-region pixel survived inside a repainted area), 'scale' (relative sizes match the canon table). Files may be directories (all PNG/GIF inside).

Deterministically recolour a canon region onto a colour ramp (dark→light hex list) — the alternative to regenerating with AI and losing consistency. Shading survives (luminance maps onto the ramp using the region's FIXED recorded range), silhouettes never change, protected regions are never touched, and the same input always gives the same output. Use maskFromFile when repainting an already-recoloured variant: regions are matched on the original (identical pixel layout), paint is applied to the variant. Writes to outFile (never overwrites the input unless outFile equals it).

Compose a zoomed contact sheet (PNG on a checkerboard) from sprites — one row per file, one column per frame — and return it as an image so you can LOOK at what you just made. Judge consistency on sheets, not in-game: every visual defect we ever caught was caught on a sheet. Use crop to zoom into the area under suspicion (e.g. just the head).

Operations on animated GIFs. 'palette' swaps colours in every colour table (global AND per-frame local — patching only the global table is a classic half-fix) without touching frame data: zero generation loss, every frame changes in perfect sync — the correct way to re-dress an indexed sprite. The response reports how many table entries each source colour actually matched; 0 means that hex isn't in the file (use colors_inspect to find the exact hexes). 'retime' re-times all frames to msPerFrame. GIF delays are quantised to 10ms steps with a 20ms minimum; pixels survive a decode/re-encode that is exact up to 255 opaque colours (beyond that, nearest-palette snapping). Real bug this fixes: an animation authored at 1.8s being cut off by game code that frees the sprite after 0.62s — retime the GIF instead of dropping frames.

Show the resolved canon (palette size, regions with their rules and protection flags, scale table, thresholds) and optionally census a file against it — how many pixels each region matches, and how many match nothing (unmatched pixels mean your region definitions have gaps). Pass canonPath or censusFile — without either there is nowhere to search from (the server's working directory is the client's, not your project's).

List the colours actually used in files, sorted by frequency, with luminance — the raw material for canon_init/canon_learn decisions. Use it to spot near-duplicate colours, anti-aliasing noise, and which hexes belong to which visual part before defining regions.