Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs: transparency strategy per provider, v1.60.0
Soohong Kima344ecc4929d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 79af451..a1ab641 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,14 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## v1.60.0 - Native Alpha++- `sprite-gen gen --transparent` now follows a per-provider transparency strategy declared once on each adapter (`Provider.transparency`). `codex` asks `image_gen` for a genuinely transparent background and publishes the measured alpha (`native`, first choice); `grok` keeps deterministic chroma keying because Grok Imagine returns JPEG only.+- Added `--alpha-mode auto|native|chroma`. `auto` reads the provider's strategy, `chroma` forces keying on codex for prompts that already carry a key background, and `native` on a chroma-only provider fails before any model call.+- Native output is verified before publishing: no alpha channel or 0% transparent pixels refuses the run (a drawn checkerboard is never keyed silently), RGB under alpha 0 is scrubbed, and partial alpha is reported untouched.+- Reports carry an `alpha` block (`strategy` plus stats) next to the existing `chroma` stats, and codex's own `transparentBackground` claim under `extra.transparent_background_reported`.+- Sprite-row generation is unchanged: rows still carry the request chroma key and are keyed at extraction.+## v1.59.0 - Contributor CollectionThis release incorporates accepted work from eight community pull requests. Thanks to [@devswha](https://github.com/devswha) for chroma color preservation, [@bokjk](https://github.com/bokjk) for portable manifest paths, [@Dongkyu-ES](https://github.com/Dongkyu-ES) for deterministic CLI tests, engine export, and subject-aware sparse-frame handling, [@napkn34](https://github.com/napkn34) for the Windows provider and publish-lock fixes, and [@monibu1548](https://github.com/monibu1548) for pixel-unfake vertical centering and grounding controls.diff --git a/README.md b/README.mdindex f56879d..1bb7a3e 100644--- a/README.md+++ b/README.md@@ -247,8 +247,10 @@ python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-githuProvider-backed generation is part of this engine (`sprite_gen.gen`), with`codex` and `grok` as the supported providers. The general `image-gen` skill isonly a thin shuttle to the same command, so it does not need a second provider-implementation. See [`docs/gen.md`](docs/gen.md) for the CLI and verification-contract.+implementation. Transparent stills follow a per-provider strategy: `codex` asks+`image_gen` for a real alpha channel (native, first choice) and the measured alpha+is published; `grok` is keyed out of a chroma background. See+[`docs/gen.md`](docs/gen.md) for the CLI and verification contract.## Attributiondiff --git a/SKILL.md b/SKILL.mdindex ddf4aea..21947f8 100644--- a/SKILL.md+++ b/SKILL.md@@ -1,6 +1,6 @@---name: sprite-gen-version: 1.59.0+version: 1.60.0description: "Generate clean 2D game sprites and animation atlases with a component-row pipeline: base identity, numeric sprite-request SSoT, per-state layout guides, image-gen row strips, chroma-key alpha cleanup, connected-component frame extraction, cell-based atlas composition, QA reports, and runtime manifest frame_layout. Its curation webview also serves ANY image-candidate set (icons, logos, generated drafts) — agent chat can't render images, this can: unpack_atlas_run --pngs-dir import, then serve_curation side-by-side compare/pick. Palette-swap bake (`sprite-gen recolor`) turns a base sheet + palette map into N colourway sheets; the curation view blink-compares and adopts a pick into curation.json.recolor.picked. Curation triggers (KR/EN): 큐레이션, 큐레이션뷰, 큐레이션 해줘, 이미지 후보 보여줘/안 보임, 나란히 비교, 골라볼게 띄워줘, curation view, show image candidates side by side, let me pick. Recolor triggers (KR/EN): 팔레트 스왑, 팔레트 베이크, 리컬러, 색깔 바꾸기, 컬러웨이, 색 변형, 팔레트 맵, 색갈이, palette swap, recolor, colourway, colorway, bake variants, palette map."license: Apache-2.0depends_on:@@ -245,7 +245,7 @@ $SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/generate_sprite_image--ref <run>/base-source.<ext> --ref <run>/references/layout-guides/<state>.png```-Use `prompts/<state>.txt` as the prompt; save the selected image as `raw/<state>.png`. `--provider` is optional — the default is **codex** (`SPRITE_GEN_DEFAULT_PROVIDER` env overrides it; an observable grok fallback kicks in only if codex is unavailable). Pass `--provider grok` explicitly for the faster backend; codex adheres tighter to negative constraints. Default policy: [`docs/gen.md`](docs/gen.md#default-provider-selection). Keep the request chroma key on the background (extraction removes it). Reference attachment rules:+Use `prompts/<state>.txt` as the prompt; save the selected image as `raw/<state>.png`. `--provider` is optional — the default is **codex** (`SPRITE_GEN_DEFAULT_PROVIDER` env overrides it; an observable grok fallback kicks in only if codex is unavailable). Pass `--provider grok` explicitly for the faster backend; codex adheres tighter to negative constraints. Default policy: [`docs/gen.md`](docs/gen.md#default-provider-selection). Keep the request chroma key on the background (extraction removes it) — rows are generated without `--transparent`. For **standalone stills** (`--transparent`), transparency is a per-provider strategy: **codex asks image_gen for real alpha (native, first choice)** and the measured alpha is published; grok is keyed out of a chroma background; `--alpha-mode chroma` forces keying on codex for prompts that already carry a key. Contract: [`docs/gen.md`](docs/gen.md#transparent-output--strategy-per-provider). Reference attachment rules:**생성 동시성 (maintainer 확정 2026-07-19)**: 여러 행을 뽑는 배치는 **4동시**로 돌린다 —`sprite-gen gen` 호출을 최대 4개 병렬 (codex 실측 4병렬까지 스로틀 없음; grok 도 4,diff --git a/docs/gen.md b/docs/gen.mdindex b84c5eb..7a00fcc 100644--- a/docs/gen.md+++ b/docs/gen.md@@ -2,15 +2,20 @@Generation is a first-class engine module (`sprite_gen/gen/`), not an externalskill. One call = a prompt (+ optional reference images) → one **verified** PNG on-disk, with an optional deterministic transparent-chroma post-process. The general-`image-gen` skill is a thin shuttle over this command.+disk, with an optional transparent output whose strategy is decided per provider+(native alpha or deterministic chroma keying). The general `image-gen` skill is a+thin shuttle over this command.Providers (Gemini/OpenRouter/fal/BytePlus are intentionally **not** included):-| Provider | Backend | Auth | Output truth |-|---|---|---|---|-| `codex` | codex `image_gen` | ChatGPT OAuth | inline base64 in the session rollout jsonl, decoded deterministically |-| `grok` | grok Imagine `image_gen` / `image_edit` | xAI OAuth | file grok is told to write, verified by PNG magic |+| Provider | Backend | Auth | Output truth | Transparency strategy |+|---|---|---|---|---|+| `codex` | codex `image_gen` | ChatGPT OAuth | inline base64 in the session rollout jsonl, decoded deterministically | **`native`** — image_gen returns a real alpha channel when asked (measured, then published) |+| `grok` | grok Imagine `image_gen` / `image_edit` | xAI OAuth | file grok is told to write, verified by PNG magic | `chroma` — Imagine returns JPEG only; generate on a key and matte it out |++The strategy is declared **once**, on the adapter (`Provider.transparency`), and is+the only place that says what a backend can do. See+[Transparent output](#transparent-output--strategy-per-provider).## Default provider selection@@ -63,7 +68,7 @@ sprite-gen gen \--prompt "…" # or --prompt-file PROMPT.txt--out DEST.png \[--ref REF.png ...] # repeatable; grok routes refs through image_edit- [--transparent [--chroma-key magenta|green]] \+ [--transparent [--alpha-mode auto|native|chroma] [--chroma-key magenta|green]] \[--white-check CHECK.png] \[--aspect-ratio 1:1] # grok only (1:1, 16:9, 9:16, 4:3, 3:4, auto)[--model ID] \@@ -73,19 +78,44 @@ sprite-gen gen \Backward-compatible wrapper: `$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/generate_sprite_image.py …` (same args).-- **Non-transparent**: the raw PNG (chroma background included) is copied to `--out`.-- **`--transparent`**: the raw is keyed to clean RGBA through the frame extractor's- canonical YCbCr matte (`remove_chroma_background_ycbcr`). Generate on a `#FF00FF`- (or `#00FF00`) background — pick the key by subject colour (magenta subjects →- green key). Gradients and texture within that chroma family are supported. A result- with `alpha_zero_pct: 0.0`, or any transparent pixel that still carries non-zero- RGB, **fails loudly before the output or success report is published** (No Silent Fallback).-- The pre-chroma raw is preserved next to the destination as `<out>.raw.png` for audit.+- **Non-transparent**: the raw PNG (background included) is copied to `--out`.+- **`--transparent`**: publishes a clean RGBA PNG using the provider's transparency+ strategy (below). Either way a result with no transparent area, or any transparent+ pixel that still carries non-zero RGB, **fails loudly before the output or success+ report is published** (No Silent Fallback).+- The pre-process raw is preserved next to the destination as `<out>.raw.png` for audit.- `--report` writes a `sprite-gen-image-report` JSON: provider, prompt, out/raw paths,- `raw_bytes`, `elapsed_seconds`, `session_id` (codex), the chroma stats, and the+ `raw_bytes`, `elapsed_seconds`, `session_id` (codex), an `alpha` block+ (`strategy` + the measured stats), the `chroma` stats when chroma keying ran, and theprovider-resolution fields (`provider_resolved_from`, and `provider_fallback` when acodex→grok default fallback occurred).+## Transparent output — strategy per provider++`--transparent` does not mean "chroma key" any more. Each adapter declares the one+strategy it can execute, and `--alpha-mode auto` (the default) follows it:++| Strategy | Who | What happens | Refused when |+|---|---|---|---|+| `native` | `codex` (**first choice**, 2026-09-08) | The transport prompt asks image_gen for a genuinely transparent background (the bundled `imagegen` skill honours "transparent background" and keeps the generated alpha; codex reports `transparentBackground: true` on the completed item). The decoded PNG's alpha is **measured**: no alpha band or `alpha_zero_pct: 0.0` refuses to publish, RGB under alpha 0 is scrubbed, partial alpha (1–254) is left as produced and reported as `partial_alpha_pct`. | The model drew a checkerboard / flat background (RGB image) — nothing can recover alpha from that, so the run fails instead of silently keying. |+| `chroma` | `grok` (only option), `codex` with `--alpha-mode chroma` | Generate on a `#FF00FF` (or `#00FF00`) background — pick the key by subject colour (magenta subjects → green key) — and matte it out through the frame extractor's canonical YCbCr matte (`remove_chroma_background_ycbcr`). Gradients and texture within that chroma family are supported. | `alpha_zero_pct: 0.0` after keying, or stale RGB under alpha 0. |++- `--alpha-mode chroma` on codex is for prompts that already carry a key background+ (the sprite-row pipeline today): the native request is **not** added to the prompt+ and the raw is keyed like a grok run.+- `--alpha-mode native` on a `chroma`-only provider **fails loud before any model+ call** — a strategy the backend cannot execute is not a fallback candidate, and+ native → chroma never happens silently either (the prompt shapes are different).+- Why grok is chroma-only: Grok Imagine Image 2.0 returns `image/jpeg` from both the+ `/v1/images/*` API and the CLI `image_gen`/`image_edit` tools, and the official+ docs expose no background parameter — its "background removal" is a consumer-app+ tool (4/4 drawn checkerboards on 2026-09-08). The declaration lives in+ `sprite_gen/gen/grok_provider.py` and flips only with a new measurement.+- Measured codex output (2026-09-08, codex 0.153.4): `alpha_zero_pct ≈ 62`, body alpha+ ≈ 253 (so `partial_alpha_pct` is most of the subject), a ~1 px light fringe on a+ magenta composite. Downstream extraction treats `alpha ≤ 16` as transparent, so+ this is usable as-is; alpha snapping is deliberately not applied here.+## How each provider works- **codex** — spawns a fresh `codex exec --json` in an empty sandbox@@ -126,7 +156,10 @@ exactly that, rather than falling back on its own.In the component-row pipeline (SKILL.md §2) generate each state row with`--provider codex` (or `grok`) using `prompts/<state>.txt`, writing `raw/<state>.png`.-Keep the request chroma key on the background; frame extraction removes it downstream.+The row prompts still carry the request chroma key on the background and frame+extraction removes it downstream — rows are generated **without** `--transparent`, so+the native strategy does not apply to them yet (moving rows to native alpha is a+separate, measured change).The correction loop (`sprite-gen correction-loop --provider-command …`) can drive this`gen` command as its regeneration step so inspect → score → hint → regenerate closesagainst a real provider.diff --git a/pyproject.toml b/pyproject.tomlindex f697ed6..83b5fd0 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"name = "sprite-gen"# Release discipline: keep this package metadata version synchronized with# SKILL.md's `version:` field in the same release commit.-version = "1.59.0"+version = "1.60.0"description = "Component-row pipeline for clean 2D game sprites and animation atlases"readme = "README.md"license = "Apache-2.0"