Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

docs(changelog): the Unreleased section on 3.10.1, the contract strings each written once and read by name

Soohong Kimd8181b74eb63
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2a00793..aa82015 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,20 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased - Contract strings each written once and read by name
+
+**Upgrading from 3.12.0: every output, report, JSON body, JSON key order, CLI choice and order, `--help` text, refusal and warning text keeps its bytes. Nothing a user runs behaves differently. One visible effect: `frames/extract.py` and `frames/decontam.py` changed, so `engine_revision` changes. The curation view's heal re-extracts each existing run once when it is next opened; the frames it writes have the same pixels. One edge: `python -m sprite_gen.serve.serve_curation`, `scripts/serve_curation.py` and `scripts/interpolate_frames.py` now load the image providers (`sprite_gen.gen`) when they start, because their default provider is read from a declared name. A malformed `SPRITE_GEN_GEN_TIMEOUT_SECONDS` now stops them at start with its `ValueError`, instead of when a reroll or interpolate button is pressed. `sprite-gen curation` already loaded them, so it is unchanged.**
+
+- **Internal: one declaration per contract string**: a key, kind, mode, provider name or key colour that two or more places write, read or branch on was spelt again at each place, so a one-letter typo passed every test (for example the curation server's `extractOk` spelt `extractOK` made the curator warn on every row with the suite green). Each is now declared once and every use names it:
+ - curation and composer servers: every key of the JSON the curator and composer read, in `serve_curation.Wire` (112 keys and the `X-Filename` download header) and `serve_compose.Wire` (16 keys, plus `TYPE_DIR`, `TYPE_IMAGE`); the heal report and progress file keys in `frames/extract.py` (`HEAL_*`, `PROGRESS_*`, `PROGRESS_PHASE_COMPONENTS`); `curation.CURATION_KIND`, `REF_ANCHOR`, `REF_BASIS`, `REF_GUIDE`, `BREATHE_PIXEL`, `BREATHE_SMOOTH`.
+ - image provider names `PROVIDER_CODEX`, `PROVIDER_GROK`, `PROVIDER_OPENAI` in `gen/base.py`, with `gen.PROVIDERS` and the other provider sets written with them; the curator's two buttons gated by one set, `serve_curation.CURATOR_PROVIDERS`; the reroll default is `gen.HARD_DEFAULT_PROVIDER`; the interpolate default is `interpolate.DEFAULT_PROVIDER` (codex, its own documented choice from the three-way comparison); the HTTP host names `address.OPENAI`, `XAI`, `ANTHROPIC`, `ELEVENLABS`; `retry.ELEVENLABS_BUSY`; `audio.manifest.KIND`, `SFX`, `BGM`; the workflow guide's journey, field and access names in `workflow/catalog.py` and `workflow/access.py`; `video-prompt` takes `gen.video.DEFAULT_MODEL` instead of a second copy.
+ - key colours and modes: `cutout.KEY_TARGETS` with `MAGENTA` and `GREEN` beside it is the one table of key colours (`gen.chroma.KEYS` is built from it, `logo_matte.KEYS` is it, `slice_sheet.CHROMA_KEYS` is removed, the hex values in `prepare`, `unpack-atlas` and the curation server are derived from it); `cutout.KEYS` is cutout's own `--key` set; `OFF, AUTO, PALETTE = DECONTAM_MODES` and `CHROMA_RGB, CHROMA_YCBCR = CHROMA_MODES` are declared in `frames/extract.py`, and `frames.decontam.DECONTAM_MODES` and `video.frames.DECONTAM_MODES` are that same tuple; every `--decontam`, `--chroma-mode` and `--key` choice reads its declaration; `logo_matte.LETTERING_BOX`, `UNMIX`; `prompt_parts.CONFLICT`, `REPEAT`.
+ - kinds: `loop.REPORT_KIND`, `loop.REPORT_PASSED`; `spec.assets.ASSET_KIND`, `SET_SHEET_KIND` (`set_sheet.KIND` names it); `qa.motion.REPORT_KIND`; `video.evidence.SOURCE_KIND`; `nonloop.GAIT_STATES` (the copies in `qa.handed` and `video.batch` removed); `body_plan.BIPED`, `QUADRUPED`, `LEGLESS`; `effect.STATE` read by `video-set` and `video-prompt`; `pixel_gates.SPRITE`, `ICON`, `TILE`, `EFFECT` (`pixel_draw.KINDS` is that tuple).
+ - Values that no test bound before and that now cannot drift: the legless anatomy sentence key, `effect` in `video-set`'s states pinned to their first frame, the pixel-draw pick sheet's tile branch, the loop report kind `video-cycle-align` reads (its typo passed the fast bundle).
+- Python callers: every name above is importable. Downstream imports keep the same objects: `sprite_gen.video.frames.DECONTAM_MODES`, `sprite_gen.frames.cutout.KEY_TARGETS`, `sprite_gen.gen.chroma.KEY_BACKGROUND_TEXT`, `set_sheet.KIND`, `pixel_draw.KINDS`, `batch.GAIT_STATES`. Removed: `slice_sheet.CHROMA_KEYS` (use `cutout.KEY_TARGETS`). `clip_prompt.DEFAULT_MODEL` is `gen.video.DEFAULT_MODEL`, imported (the same object). `qa.handed.GAIT_STATES` is now a frozenset (was a tuple); every use is a membership test. `sprite_gen.frames.cutout` now imports `frames.extract` when it loads (for the decontam defaults), so importing it loads more modules than before.
+- **Curator**: the JS mirror `BREATHE_MODES` moved from `store.js` to `breathe.js`, with `BREATHE_SMOOTH` beside it; `gen-trigger.js`'s provider select mirrors `serve_curation.CURATOR_PROVIDERS`. No screen changes.
+- **Tests**: new `tests/serve/test_curator_wire_keys.py`: every key the curator and composer read is found in the scripts with the object it is read from, built from the declared value; every declared key is read or listed as unread, the unread ones spelt out in the test; the servers write no wire key, and send no header the curator reads, as text; every `Wire.X` the servers name exists. `tests/serve/test_curation_view_contract.py`: the reroll and interpolate buttons follow `CURATOR_PROVIDERS` and their declared defaults, and node runs `gen-trigger.js` to hold its select to `CURATOR_PROVIDERS` in order. `tests/effects/test_breathe_sidecar_roundtrip.py`: the curator's save payload kind is `CURATION_KIND`. `tests/frames/test_cutout.py` and `tests/frames/test_chroma_decontam.py`: every key table is the one table, every `--key`, `--decontam` and `--chroma-mode` flag reads its declaration, `cutout.KEYS` pinned as written. `tests/gen/test_codex_unavailable.py` (the codex-unavailable choices in order), `tests/gen/test_openai_provider.py` (adapter names equal `gen.PROVIDERS`), `tests/audio/test_sound.py` (the two ElevenLabs busy codes), `tests/workflow/test_capabilities.py` (the video model default), `tests/gen/test_prompt_assembly.py` (a repeat note's kind). The two absence guards that searched `serve_curation.py` for a key's spelling (`tests/serve/test_pixel_grid_always_available.py`, `tests/curate/test_logical_height_contract.py`) now search for its name; with the old spelling they would have passed while testing nothing. Red first: at 3.10.1 the new binding tests fail (for example the wire-key test finds 217 keys written as text in `serve_curation.py` and 55 in `serve_compose.py`; 8 `--decontam` parsers held their own copy; `video-set`'s `--key` was a copy). Mutation check: one character changed in a declared value fails a test in every family; before, 16 of 25 sampled curation key changes, the provider adapter name, either ElevenLabs busy code, the video model default and the loop report kind under the fast bundle left the suite green.
+
## v3.12.0 - Prop plate painted on the canvas (video-canvas --prop-plate) and erased from keyed frames (video-frames --prop-plate <canvas report json>)
**Upgrading from 3.11.0: runs without the new options produce unchanged outputs: every canvas, frame, strip, GIF, WebP, and report keeps its exact bytes (with only the loop report's `producer.implementation_sha256` changing with source code changes).**