Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
gen: codex native alpha is the first transparency strategy
Soohong Kim2facd25063fc
diff --git a/sprite_gen/gen/__init__.py b/sprite_gen/gen/__init__.pyindex a48e999..64a5b62 100644--- a/sprite_gen/gen/__init__.py+++ b/sprite_gen/gen/__init__.py@@ -6,11 +6,16 @@ ChatGPT OAuth) and grok (Imagine, xAI OAuth). One call = prompt (+ optional refs-> one verified raw PNG, with an optional deterministic transparent chromapost-process. The general `image-gen` skill is a thin shuttle over `sprite-gen gen`.+Transparency is a per-provider strategy (`Provider.transparency`, declared once+in each adapter): codex `image_gen` returns a genuinely transparent PNG when asked+(`native`), grok Imagine cannot and is keyed out of a chroma background (`chroma`).+`--transparent` follows the provider's strategy unless `--alpha-mode` overrides it.+CLI:sprite-gen gen --provider codex|grok --prompt "..." --out DEST.png- [--ref REF.png ...] [--transparent [--chroma-key magenta|green]]- [--white-check CHECK.png] [--model ID] [--aspect-ratio 1:1]- [--report REPORT.json] [--keep-session]+ [--ref REF.png ...] [--transparent [--alpha-mode auto|native|chroma]+ [--chroma-key magenta|green]] [--white-check CHECK.png] [--model ID]+ [--aspect-ratio 1:1] [--report REPORT.json] [--keep-session]"""from __future__ import annotations@@ -28,11 +33,26 @@ from typing import Anyfrom sprite_gen.spec.runio import atomic_write_textfrom . import chroma as chroma_mod-from .base import GenRequest, GenResult, verify_png, GenTimeoutError, provider_binary, provider_subprocess_env+from .base import (+ TRANSPARENCY_CHROMA,+ TRANSPARENCY_NATIVE,+ TRANSPARENCY_STRATEGIES,+ GenRequest,+ GenResult,+ GenTimeoutError,+ provider_binary,+ provider_subprocess_env,+ verify_png,+)from .codex_provider import CodexProviderfrom .grok_provider import GrokProviderPROVIDERS = ("codex", "grok")+# `--alpha-mode`: `auto` reads the provider's declared strategy (the SSoT);+# `native` / `chroma` force one. Forcing `native` on a chroma-only provider fails+# loud — a strategy the backend cannot execute is not a fallback candidate.+ALPHA_MODE_AUTO = "auto"+ALPHA_MODES = (ALPHA_MODE_AUTO, *TRANSPARENCY_STRATEGIES)# Default-provider policy (maintainer 확정 2026-07-17): the default backend is codex# (GPT `image_gen`). If codex is unavailable in the environment (CLI missing or@@ -54,6 +74,31 @@ def _make_provider(name: str, *, keep_session: bool):raise SystemExit(f"gen: unknown provider {name!r}; expected one of {', '.join(PROVIDERS)}")+def resolve_transparency_strategy(backend, alpha_mode: str) -> str:+ """Decide which transparency strategy this generation runs.++ The provider's declared `transparency` is the only source of what it can do;+ `alpha_mode` may pick `chroma` on a native provider (the prompt already carries+ a key background) but can never pick `native` on a chroma-only provider.+ """+ if alpha_mode not in ALPHA_MODES:+ raise SystemExit(f"gen: unknown --alpha-mode {alpha_mode!r}; expected one of {', '.join(ALPHA_MODES)}")+ declared = getattr(backend, "transparency", None)+ if declared not in TRANSPARENCY_STRATEGIES:+ raise SystemExit(+ f"gen: provider {getattr(backend, 'name', backend)!r} declares no transparency "+ f"strategy (got {declared!r}); expected one of {', '.join(TRANSPARENCY_STRATEGIES)}"+ )+ if alpha_mode == ALPHA_MODE_AUTO:+ return declared+ if alpha_mode == TRANSPARENCY_NATIVE and declared != TRANSPARENCY_NATIVE:+ raise SystemExit(+ f"gen: --alpha-mode native is not a capability of provider {backend.name!r} "+ f"(its transparency strategy is {declared!r}); use --alpha-mode chroma or another provider"+ )+ return alpha_mode++def _codex_available() -> tuple[bool, str]:"""Is codex usable here? Returns (ok, reason_if_not).@@ -124,6 +169,7 @@ def generate_image(model: str | None = None,aspect_ratio: str | None = None,transparent: bool = False,+ alpha_mode: str = ALPHA_MODE_AUTO,chroma_key: str = "magenta",white_check: Path | None = None,keep_session: bool = False,@@ -140,13 +186,23 @@ def generate_image(raise SystemExit(f"gen: reference image not found: {ref}")backend = _make_provider(provider, keep_session=keep_session)+ # Decided before the model runs: the strategy shapes the transport prompt+ # (native asks for alpha) and the post-process (chroma keys it out).+ strategy = resolve_transparency_strategy(backend, alpha_mode) if transparent else Noneowns_workdir = workdir is Noneworkdir = Path(workdir).expanduser().resolve() if workdir else Path(tempfile.mkdtemp(prefix="sprite-gen-gen-"))workdir.mkdir(parents=True, exist_ok=True)raw = workdir / "raw.png"try:- request = GenRequest(prompt=prompt, raw=raw, refs=refs, model=model, aspect_ratio=aspect_ratio)+ request = GenRequest(+ prompt=prompt,+ raw=raw,+ refs=refs,+ model=model,+ aspect_ratio=aspect_ratio,+ native_alpha=strategy == TRANSPARENCY_NATIVE,+ )# 타임아웃 1회 관측 가능 재시도 — 산발 provider 스톨은 같은 호출 재시도로# 대부분 통과한다 (회귀 2026-07-19). 두 번째도 스톨이면 fail loud.try:@@ -157,9 +213,16 @@ def generate_image(raw_bytes = verify_png(raw)chroma_stats: dict[str, Any] | None = None+ alpha_stats: dict[str, Any] | None = Noneout.parent.mkdir(parents=True, exist_ok=True)- if transparent:+ if strategy == TRANSPARENCY_NATIVE:+ alpha_stats = {+ "strategy": TRANSPARENCY_NATIVE,+ **chroma_mod.verify_native_alpha(raw, out, white_check=white_check),+ }+ elif strategy == TRANSPARENCY_CHROMA:chroma_stats = chroma_mod.key_transparent(raw, out, key=chroma_key, white_check=white_check)+ alpha_stats = {"strategy": TRANSPARENCY_CHROMA, **chroma_stats}else:shutil.copyfile(raw, out)verify_png(out)@@ -179,6 +242,7 @@ def generate_image(session_id=run.session_id,refs=refs,transparent=transparent,+ alpha=alpha_stats,chroma=chroma_stats,extra=run.extra,)@@ -219,6 +283,7 @@ def _run(args: argparse.Namespace) -> int:model=args.model,aspect_ratio=args.aspect_ratio,transparent=args.transparent,+ alpha_mode=args.alpha_mode,chroma_key=args.chroma_key,white_check=args.white_check,keep_session=args.keep_session,@@ -280,7 +345,24 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--ref", action="append", type=Path, default=[], help="reference image (repeatable)")parser.add_argument("--model")parser.add_argument("--aspect-ratio", help="grok only, e.g. 1:1 16:9 9:16")- parser.add_argument("--transparent", action="store_true", help="chroma-key the raw PNG to transparent RGBA")+ parser.add_argument(+ "--transparent",+ action="store_true",+ help=(+ "publish a transparent RGBA PNG using the provider's transparency strategy: "+ "codex asks image_gen for real alpha (native), grok is keyed out of a chroma background"+ ),+ )+ parser.add_argument(+ "--alpha-mode",+ choices=ALPHA_MODES,+ default=ALPHA_MODE_AUTO,+ help=(+ "transparency strategy for --transparent: auto = the provider's declared strategy; "+ "chroma forces chroma keying (e.g. a codex prompt that already carries a key background); "+ "native is refused on a provider that cannot return alpha"+ ),+ )parser.add_argument("--chroma-key", choices=sorted(chroma_mod.KEYS), default="magenta")parser.add_argument("--white-check", type=Path, help="write a white-composite check image")parser.add_argument("--keep-session", action="store_true", help="codex: do not delete the rollout jsonl")diff --git a/sprite_gen/gen/base.py b/sprite_gen/gen/base.pyindex edefe1f..7331932 100644--- a/sprite_gen/gen/base.py+++ b/sprite_gen/gen/base.py@@ -18,6 +18,17 @@ from typing import Any, ProtocolPNG_MAGIC = b"\x89PNG\r\n\x1a\n"+# Transparency strategy — a capability each provider declares exactly once+# (`Provider.transparency`). The orchestrator reads it; nothing else decides.+# native — the model returns a genuinely transparent PNG (alpha channel) when+# the prompt asks for a transparent background; the raw alpha is+# measured and published (codex `image_gen`, 2026-09-08 실측).+# chroma — the model cannot return alpha; generate on a chroma key and key it+# out deterministically downstream (grok Imagine: API/CLI 모두 JPEG).+TRANSPARENCY_NATIVE = "native"+TRANSPARENCY_CHROMA = "chroma"+TRANSPARENCY_STRATEGIES = (TRANSPARENCY_NATIVE, TRANSPARENCY_CHROMA)+# Child provider processes are independent execution contexts. They must not# inherit parent orchestration identity or lifecycle controls, while ordinary# variables such as PATH remain available. Suffix matching keeps the contract@@ -89,6 +100,10 @@ class GenRequest:refs: list[Path] = field(default_factory=list)model: str | None = Noneaspect_ratio: str | None = None # grok honours this; codex ignores it+ # Ask the model for a genuinely transparent background (alpha channel). Only+ # legal for a provider whose `transparency` is `native`; the orchestrator gates+ # it and the provider carries the request into its transport prompt.+ native_alpha: bool = False@dataclass@@ -106,6 +121,7 @@ class Provider(Protocol):"""A generation backend. `generate` must write a verified PNG to `request.raw`."""name: str+ transparency: str # one of TRANSPARENCY_STRATEGIES — declared once per providerdef generate(self, request: GenRequest, workdir: Path) -> ProviderRun: ...@@ -124,6 +140,11 @@ class GenResult:session_id: str | None = Nonerefs: list[Path] = field(default_factory=list)transparent: bool = False+ # Which transparency strategy produced `out` plus its measured stats+ # ({"strategy": "native"|"chroma", ...stats}); None when not transparent.+ alpha: dict[str, Any] | None = None+ # Chroma-key stats — populated only when the strategy was `chroma` (kept as+ # its own field so existing report readers keep working).chroma: dict[str, Any] | None = Noneextra: dict[str, Any] = field(default_factory=dict)@@ -140,6 +161,7 @@ class GenResult:"session_id": self.session_id,"refs": [str(ref) for ref in self.refs],"transparent": self.transparent,+ "alpha": self.alpha,"chroma": self.chroma,**({"extra": self.extra} if self.extra else {}),}diff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.pyindex d4d2a1e..a6c7ffa 100644--- a/sprite_gen/gen/chroma.py+++ b/sprite_gen/gen/chroma.py@@ -1,10 +1,16 @@# SPDX-License-Identifier: Apache-2.0-"""Deterministic chroma-key -> transparent PNG contract for generated images.--`image_gen` / Grok Imagine alpha output is not reliable, so generated key-backgrounds are routed through the same YCbCr matte used by frame extraction.-No silent success: an output with no measurable transparent area, or transparent-pixels that retain RGB, fails before any output is published.+"""Transparent-PNG contracts for generated images — one per strategy.++- `key_transparent` (strategy `chroma`): the model cannot return alpha, so the+ generated key background is routed through the same YCbCr matte used by frame+ extraction.+- `verify_native_alpha` (strategy `native`): the model returned its own alpha+ channel (codex `image_gen`, 2026-09-08); the raw alpha is measured, transparent+ pixels are scrubbed of stale RGB, and the stats are published.++No silent success on either path: an output with no measurable transparent area,+no alpha channel at all, or transparent pixels that retain RGB fails before any+output is published."""from __future__ import annotations@@ -102,3 +108,70 @@ def key_transparent(white_check.parent.mkdir(parents=True, exist_ok=True)write_white_check(image, white_check)return stats+++def verify_native_alpha(+ input_path: Path,+ out_path: Path,+ *,+ white_check: Path | None = None,+) -> dict[str, Any]:+ """Publish a provider-returned RGBA PNG after measuring that its alpha is real.++ Returns a stats dict (alpha_zero_pct / partial_alpha_pct / opaque_pct and the+ transparent-RGB scrub count). Raises SystemExit before publishing when the PNG+ has no alpha band or no transparent pixel at all — a drawn checkerboard or a+ flat background is an RGB image, and no post-process can recover alpha from it.+ Partial alpha (1..254) is left exactly as the model produced it and only+ reported (2026-09-08 실측: 본체 알파 ≈253).+ """+ source = Image.open(input_path)+ if "A" not in source.getbands():+ raise SystemExit(+ f"native-alpha: provider returned mode={source.mode!r} with no alpha channel for "+ f"{input_path} — the transparent background was drawn, not generated; refusing "+ "to publish a transparent output"+ )+ image = source.convert("RGBA")+ width, height = image.size+ total = width * height+ histogram = image.getchannel("A").histogram()+ alpha_zero = histogram[0]+ opaque = histogram[255]+ partial = total - alpha_zero - opaque+ alpha_zero_pct = round(alpha_zero / total * 100, 2) if total else 0.0+ if alpha_zero_pct == 0.0:+ raise SystemExit(+ f"native-alpha: 0.0% transparent pixels in {input_path} (alpha band present but "+ "nothing is transparent); refusing successful transparent output"+ )++ pixels = image.load()+ cleaned_rgb = 0+ for y in range(height):+ for x in range(width):+ r, g, b, a = pixels[x, y]+ if a == 0 and (r or g or b):+ pixels[x, y] = (0, 0, 0, 0)+ cleaned_rgb += 1++ stats: dict[str, Any] = {+ "out": str(out_path),+ "mode": "RGBA",+ "method": "native",+ "size": f"{width}x{height}",+ "alpha_zero_pct": alpha_zero_pct,+ "partial_alpha_pct": round(partial / total * 100, 2) if total else 0.0,+ "opaque_pct": round(opaque / total * 100, 2) if total else 0.0,+ "cleaned_transparent_rgb_pixels": cleaned_rgb,+ "stale_transparent_rgb_pixels": 0,+ }+ if white_check is not None:+ stats["white_check"] = str(white_check)++ out_path.parent.mkdir(parents=True, exist_ok=True)+ atomic_save_image(image, out_path)+ if white_check is not None:+ white_check.parent.mkdir(parents=True, exist_ok=True)+ write_white_check(image, white_check)+ return statsdiff --git a/sprite_gen/gen/codex_provider.py b/sprite_gen/gen/codex_provider.pyindex af9fdae..991fb75 100644--- a/sprite_gen/gen/codex_provider.py+++ b/sprite_gen/gen/codex_provider.py@@ -23,9 +23,19 @@ import osimport reimport subprocessimport time+from dataclasses import dataclassfrom pathlib import Path-from .base import GEN_TIMEOUT_SECONDS, GenRequest, GenTimeoutError, ProviderRun, provider_binary, provider_subprocess_env, verify_png+from .base import (+ GEN_TIMEOUT_SECONDS,+ TRANSPARENCY_NATIVE,+ GenRequest,+ GenTimeoutError,+ ProviderRun,+ provider_binary,+ provider_subprocess_env,+ verify_png,+)# codex carries the inline base64 on a version-specific record. All are# first-class canonical records (not fallbacks) — read whichever the running@@ -52,6 +62,28 @@ _SID_RE = re.compile(r"session id: ([0-9a-f-]+)")# so this trigger is an alignment with the official invocation contract, not a fix# for a session that is never offered the tool._SKILL_TRIGGER = "$imagegen"+# Native transparency (2026-09-08 실측, codex 0.153.4): the bundled `imagegen` skill+# says "For transparent images, ask built-in image_gen for a transparent background+# and preserve the generated alpha", and the completed `image_gen.generation` item+# reports `transparentBackground: true` next to the real RGBA PNG. There is no+# tool parameter — the request rides on the prompt, so this adapter owns the+# exact wording (the caller's prompt is still passed through verbatim).+_NATIVE_ALPHA_INSTRUCTION = (+ "배경은 진짜 투명(알파 채널이 있는 PNG)으로 만들어라 — image_gen 에 transparent "+ "background 를 요청하고 생성된 알파를 그대로 보존해라. 체커보드 무늬·흰색·단색 배경을 "+ "그림으로 그려 넣는 것은 금지다."+)+++@dataclass(frozen=True)+class InlineResult:+ """One completed image_gen call as recorded in the rollout."""++ result: str # inline base64 PNG+ # `transparentBackground` as codex reported it (0.149+ Extension item);+ # None when the record type does not carry the field. Reported, never trusted —+ # the orchestrator measures the decoded PNG's alpha itself.+ transparent_background: bool | None = Nonedef _parse_session_id(stdout: str) -> str | None:@@ -163,8 +195,8 @@ def _resolve_rollout(return rollout-def _collect_inline_results(rollout: Path) -> list[str]:- results: list[str] = []+def _collect_inline_results(rollout: Path) -> list[InlineResult]:+ results: list[InlineResult] = []with rollout.open(encoding="utf-8") as handle:for line in handle:line = line.strip()@@ -189,14 +221,20 @@ def _collect_inline_results(rollout: Path) -> list[str]:raise SystemExit(f"codex-gen: completed image_gen call has no result in {rollout}")- results.append(result)+ reported = item.get("transparentBackground")+ results.append(+ InlineResult(+ result=result,+ transparent_background=reported if isinstance(reported, bool) else None,+ )+ )continueif payload.get("type") not in _RESULT_TYPES or not payload.get("result"):continuestatus = payload.get("status")if status is not None and status != "completed":raise SystemExit(f"codex-gen: image_gen call ended with status={status!r} in {rollout}")- results.append(payload["result"])+ results.append(InlineResult(result=payload["result"]))return results@@ -207,17 +245,21 @@ def _decode_png(b64: str, dest: Path) -> None:verify_png(dest)-def _build_prompt(user_prompt: str) -> str:+def _build_prompt(user_prompt: str, *, native_alpha: bool = False) -> str:"""Wrap the caller's prompt in the transport-level skill trigger.The sprite-request prompt is the caller's SSoT and is passed through verbatim;- this adapter is the one place that owns the codex invocation contract.+ this adapter is the one place that owns the codex invocation contract. With+ `native_alpha` the transport also carries the transparent-background request+ (`_NATIVE_ALPHA_INSTRUCTION`) — that is how image_gen is told to return alpha."""+ alpha_line = f"{_NATIVE_ALPHA_INSTRUCTION}\n" if native_alpha else ""return (f"{_SKILL_TRIGGER} 스킬로 built-in image_gen 도구를 정확히 1번 호출해서 ""다음 프롬프트의 이미지 1장만 생성해줘.\n""미리보기 전용이라 생성된 파일은 기본 경로에 그대로 두면 된다.\n"- "파일 저장·이동·복사·셸 명령·코드 작성·경로 보고 전부 금지. 생성만 하고 끝.\n\n"+ "파일 저장·이동·복사·셸 명령·코드 작성·경로 보고 전부 금지. 생성만 하고 끝.\n"+ f"{alpha_line}\n""프롬프트:\n"f"{user_prompt}\n")@@ -248,6 +290,7 @@ class CodexProvider:"""Generate one image through codex `image_gen`."""name = "codex"+ transparency = TRANSPARENCY_NATIVEdef __init__(self, *, keep_session: bool = False) -> None:self.keep_session = keep_session@@ -285,7 +328,7 @@ class CodexProvider:cmd += ["-i", str(Path(ref).expanduser().resolve())]cmd += ["-", ]- prompt = _build_prompt(request.prompt)+ prompt = _build_prompt(request.prompt, native_alpha=request.native_alpha)started = time.monotonic()child_env = provider_subprocess_env()if "CODEX_HOME" in os.environ:@@ -325,7 +368,8 @@ class CodexProvider:results = _collect_inline_results(rollout)if not results:raise SystemExit(_no_image_records_message(rollout, codex_home))- _decode_png(results[-1], request.raw)+ final = results[-1]+ _decode_png(final.result, request.raw)if not self.keep_session:try:@@ -338,5 +382,11 @@ class CodexProvider:elapsed_seconds=elapsed,model=request.model,session_id=session_id,- extra={"inline_results": len(results), "rollout_cleaned": not self.keep_session},+ extra={+ "inline_results": len(results),+ "rollout_cleaned": not self.keep_session,+ # codex's own claim about the output; the orchestrator measures+ # the real alpha and publishes that, not this flag.+ "transparent_background_reported": final.transparent_background,+ },)diff --git a/sprite_gen/gen/grok_provider.py b/sprite_gen/gen/grok_provider.pyindex 4e68f35..1c3c8ed 100644--- a/sprite_gen/gen/grok_provider.py+++ b/sprite_gen/gen/grok_provider.py@@ -19,7 +19,16 @@ import subprocessimport timefrom pathlib import Path-from .base import GEN_TIMEOUT_SECONDS, GenRequest, GenTimeoutError, ProviderRun, provider_binary, provider_subprocess_env, verify_png+from .base import (+ GEN_TIMEOUT_SECONDS,+ TRANSPARENCY_CHROMA,+ GenRequest,+ GenTimeoutError,+ ProviderRun,+ provider_binary,+ provider_subprocess_env,+ verify_png,+)def _build_prompt(request: GenRequest) -> str:@@ -55,8 +64,17 @@ class GrokProvider:"""Generate one image through grok Imagine `image_gen` / `image_edit`."""name = "grok"+ # Grok Imagine Image 2.0 returns image/jpeg from both the API and the CLI+ # tools (2026-09-08 실측, 4/4 drawn checkerboards) — no alpha path exists.+ transparency = TRANSPARENCY_CHROMAdef generate(self, request: GenRequest, workdir: Path) -> ProviderRun:+ if request.native_alpha:+ raise SystemExit(+ "grok-gen: native alpha was requested but grok Imagine cannot return an "+ f"alpha channel (transparency strategy is {self.transparency!r}); "+ "generate on a chroma key instead"+ )request.raw.parent.mkdir(parents=True, exist_ok=True)cmd = [provider_binary("grok"),diff --git a/tests/gen/test_gen.py b/tests/gen/test_gen.pyindex 410ac31..1e8d1c3 100644--- a/tests/gen/test_gen.py+++ b/tests/gen/test_gen.py@@ -96,7 +96,9 @@ def test_provider_run_uses_scrubbed_env(tmp_path: Path, monkeypatch) -> None:lambda sid, sessions_root, *, preexisting: tmp_path / "x.jsonl",)b64 = base64.b64encode(_png_bytes()).decode()- monkeypatch.setattr(codex_provider, "_collect_inline_results", lambda rollout: [b64])+ monkeypatch.setattr(+ codex_provider, "_collect_inline_results", lambda rollout: [codex_provider.InlineResult(b64)]+ )monkeypatch.setenv("ORCHESTRATOR_RUNTIME_ENDPOINT_ID", "synthetic-endpoint")codex_provider.CodexProvider(keep_session=True).generate(GenRequest(prompt="a mushroom", raw=tmp_path / "raw.png"), tmp_path@@ -147,7 +149,11 @@ def test_provider_commands_use_the_single_resolved_binary(tmp_path: Path, monkeymonkeypatch.setattr(codex_provider.subprocess, "run", fake_codex)monkeypatch.setattr(codex_provider, "_resolve_rollout", lambda *_args, **_kwargs: tmp_path / "rollout.jsonl")- monkeypatch.setattr(codex_provider, "_collect_inline_results", lambda _path: [base64.b64encode(_png_bytes()).decode()])+ monkeypatch.setattr(+ codex_provider,+ "_collect_inline_results",+ lambda _path: [codex_provider.InlineResult(base64.b64encode(_png_bytes()).decode())],+ )codex_provider.CodexProvider(keep_session=True).generate(GenRequest(prompt="도구", raw=tmp_path / "codex.png"), tmp_path)@@ -194,9 +200,11 @@ def test_codex_inline_extraction_reads_both_record_types(tmp_path: Path) -> Noneresults = codex_provider._collect_inline_results(rollout)assert len(results) == 2+ # Pre-0.149 records carry no transparentBackground field — reported as unknown.+ assert [r.transparent_background for r in results] == [None, None]dest = tmp_path / "decoded.png"- codex_provider._decode_png(results[-1], dest)+ codex_provider._decode_png(results[-1].result, dest)assert gen_base.verify_png(dest) > 0@@ -223,6 +231,7 @@ def test_codex_inline_extraction_reads_0149_imagegen_extension(tmp_path: Path) -"kind": "image_gen.generation","status": "completed","result": b64,+ "transparentBackground": True,},}},@@ -231,7 +240,9 @@ def test_codex_inline_extraction_reads_0149_imagegen_extension(tmp_path: Path) -results = codex_provider._collect_inline_results(rollout)- assert results == [b64]+ # codex 0.153 reports its own transparency claim on the completed item; it is+ # carried through (the orchestrator still measures the decoded PNG itself).+ assert results == [codex_provider.InlineResult(b64, transparent_background=True)]@pytest.mark.parametrize(@@ -381,7 +392,9 @@ def test_codex_prompt_reaches_the_child_process(tmp_path: Path, monkeypatch) ->lambda sid, sessions_root, *, preexisting: tmp_path / "x.jsonl",)b64 = base64.b64encode(_png_bytes()).decode()- monkeypatch.setattr(codex_provider, "_collect_inline_results", lambda path: [b64])+ monkeypatch.setattr(+ codex_provider, "_collect_inline_results", lambda path: [codex_provider.InlineResult(b64)]+ )codex_provider.CodexProvider(keep_session=True).generate(GenRequest(prompt="a mushroom", raw=tmp_path / "raw.png"), tmp_path@@ -486,16 +499,269 @@ def test_chroma_key_transparent_rejects_zero_percent_alpha(class _FakeProvider:name = "fake"+ transparency = gen_base.TRANSPARENCY_CHROMAdef __init__(self) -> None:self.calls = 0+ self.requests: list[GenRequest] = []def generate(self, request: GenRequest, workdir: Path):self.calls += 1+ self.requests.append(request)Image.new("RGBA", (8, 8), (255, 0, 255, 255)).save(request.raw)return gen_base.ProviderRun(provider=self.name, elapsed_seconds=1.23, model=request.model)+def _native_rgba_image() -> Image.Image:+ """A model-style RGBA: transparent margin, opaque core, one stale-RGB transparent px."""+ image = Image.new("RGBA", (8, 8), (0, 0, 0, 0))+ for y in range(2, 6):+ for x in range(2, 6):+ image.putpixel((x, y), (200, 90, 20, 253))+ image.putpixel((0, 0), (255, 0, 255, 0)) # stale RGB under alpha 0+ return image+++class _FakeNativeProvider(_FakeProvider):+ """A provider that returns its own alpha (the codex image_gen shape)."""++ name = "fake-native"+ transparency = gen_base.TRANSPARENCY_NATIVE++ def __init__(self, image: Image.Image | None = None) -> None:+ super().__init__()+ self.image = image if image is not None else _native_rgba_image()++ def generate(self, request: GenRequest, workdir: Path):+ self.calls += 1+ self.requests.append(request)+ self.image.save(request.raw)+ return gen_base.ProviderRun(provider=self.name, elapsed_seconds=2.5, model=request.model)+++def _gen_kwargs(out: Path, report: Path, **overrides):+ kwargs = dict(+ provider="fake",+ prompt="a mushroom",+ out=out,+ ref=[],+ model=None,+ aspect_ratio=None,+ transparent=True,+ alpha_mode="auto",+ chroma_key="magenta",+ white_check=None,+ keep_session=False,+ report=report,+ prompt_file=None,+ workdir=None,+ )+ kwargs.update(overrides)+ return kwargs+++def test_native_strategy_publishes_measured_alpha_and_asks_provider_for_it(+ tmp_path: Path, monkeypatch+) -> None:+ fake = _FakeNativeProvider()+ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)+ out = tmp_path / "asset.png"+ report = tmp_path / "report.json"++ rc = gen.run(**_gen_kwargs(out, report))++ assert rc == 0+ # The strategy is decided before the model runs and rides on the request.+ assert fake.requests[0].native_alpha is True+ published = Image.open(out)+ assert published.mode == "RGBA"+ assert published.getpixel((0, 0)) == (0, 0, 0, 0) # stale RGB scrubbed+ assert published.getpixel((3, 3)) == (200, 90, 20, 253) # partial alpha kept as produced+ assert (tmp_path / "asset.png.raw.png").is_file()+ payload = json.loads(report.read_text(encoding="utf-8"))+ assert payload["transparent"] is True+ assert payload["alpha"]["strategy"] == "native"+ assert payload["alpha"]["method"] == "native"+ assert payload["alpha"]["alpha_zero_pct"] == 75.0+ assert payload["alpha"]["partial_alpha_pct"] == 25.0+ assert payload["alpha"]["opaque_pct"] == 0.0+ assert payload["alpha"]["cleaned_transparent_rgb_pixels"] == 1+ assert payload["alpha"]["stale_transparent_rgb_pixels"] == 0+ assert payload["chroma"] is None # no chroma key ran+++def test_chroma_strategy_reports_itself_under_alpha_too(tmp_path: Path, monkeypatch) -> None:+ fake = _FakeProvider()+ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)+ out = tmp_path / "asset.png"+ report = tmp_path / "report.json"++ assert gen.run(**_gen_kwargs(out, report)) == 0++ assert fake.requests[0].native_alpha is False+ payload = json.loads(report.read_text(encoding="utf-8"))+ assert payload["alpha"]["strategy"] == "chroma"+ assert payload["alpha"]["method"] == "ycbcr"+ assert payload["chroma"]["method"] == "ycbcr"+++ ("image", "expected_message"),+ [+ (Image.new("RGB", (8, 8), (255, 255, 255)), "no alpha channel"),+ (Image.new("RGBA", (8, 8), (10, 20, 30, 255)), r"0\.0% transparent pixels"),+ ],+)+def test_native_strategy_refuses_drawn_or_opaque_backgrounds(+ tmp_path: Path, monkeypatch, image: Image.Image, expected_message: str+) -> None:+ # A drawn checkerboard is an RGB image; a fully opaque RGBA has no transparency.+ # Neither can be rescued by chroma keying, so the run fails before publishing.+ fake = _FakeNativeProvider(image)+ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)+ out = tmp_path / "asset.png"+ report = tmp_path / "report.json"++ with pytest.raises(SystemExit, match=expected_message):+ gen.run(**_gen_kwargs(out, report))++ assert not out.exists()+ assert not report.exists()+++def test_alpha_mode_native_is_refused_on_a_chroma_provider(tmp_path: Path, monkeypatch) -> None:+ fake = _FakeProvider()+ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)+ with pytest.raises(SystemExit, match="--alpha-mode native is not a capability"):+ gen.run(**_gen_kwargs(tmp_path / "a.png", tmp_path / "r.json", alpha_mode="native"))+ assert fake.calls == 0 # refused before any model call+++def test_alpha_mode_chroma_forces_keying_on_a_native_provider(tmp_path: Path, monkeypatch) -> None:+ # The prompt already carries a magenta key: the native provider is told NOT to+ # return alpha and the raw is keyed out like any chroma run.+ fake = _FakeNativeProvider(Image.new("RGBA", (8, 8), (255, 0, 255, 255)))+ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)+ out = tmp_path / "asset.png"+ report = tmp_path / "report.json"++ assert gen.run(**_gen_kwargs(out, report, alpha_mode="chroma")) == 0++ assert fake.requests[0].native_alpha is False+ payload = json.loads(report.read_text(encoding="utf-8"))+ assert payload["alpha"]["strategy"] == "chroma"+ assert payload["chroma"]["key"] == "magenta"+++def test_provider_without_a_declared_strategy_fails_loud(tmp_path: Path, monkeypatch) -> None:+ class _Undeclared(_FakeProvider):+ name = "undeclared"+ transparency = None++ fake = _Undeclared()+ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)+ with pytest.raises(SystemExit, match="declares no transparency strategy"):+ gen.run(**_gen_kwargs(tmp_path / "a.png", tmp_path / "r.json"))+ assert fake.calls == 0+++def test_non_transparent_run_ignores_alpha_mode(tmp_path: Path, monkeypatch) -> None:+ fake = _FakeProvider()+ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)+ out = tmp_path / "asset.png"+ report = tmp_path / "report.json"+ assert gen.run(**_gen_kwargs(out, report, transparent=False, alpha_mode="native")) == 0+ payload = json.loads(report.read_text(encoding="utf-8"))+ assert payload["alpha"] is None and payload["chroma"] is None+ assert fake.requests[0].native_alpha is False+++def test_real_providers_declare_their_transparency_strategy() -> None:+ from sprite_gen.gen import grok_provider++ # SSoT: each adapter declares once what it can do (2026-09-08 실측 — codex+ # image_gen returns real RGBA; grok Imagine 2.0 returns JPEG from API and CLI).+ assert codex_provider.CodexProvider.transparency == gen_base.TRANSPARENCY_NATIVE+ assert grok_provider.GrokProvider.transparency == gen_base.TRANSPARENCY_CHROMA+++def test_grok_refuses_a_native_alpha_request_before_spawning(tmp_path: Path, monkeypatch) -> None:+ from sprite_gen.gen import grok_provider++ spawned: list = []+ monkeypatch.setattr(grok_provider.subprocess, "run", lambda *a, **k: spawned.append(a))+ with pytest.raises(SystemExit, match="cannot return an alpha channel"):+ grok_provider.GrokProvider().generate(+ GenRequest(prompt="x", raw=tmp_path / "raw.png", native_alpha=True), tmp_path+ )+ assert spawned == []+++def test_codex_prompt_carries_native_alpha_request_only_when_asked() -> None:+ user_prompt = "a fox sprite"+ plain = codex_provider._build_prompt(user_prompt)+ native = codex_provider._build_prompt(user_prompt, native_alpha=True)++ assert codex_provider._NATIVE_ALPHA_INSTRUCTION not in plain+ assert codex_provider._NATIVE_ALPHA_INSTRUCTION in native+ # The bundled imagegen skill keys on this phrase to request real alpha.+ assert "transparent background" in native+ # The transport contract and the verbatim user prompt survive on both.+ for prompt in (plain, native):+ assert prompt.startswith("$imagegen ")+ assert user_prompt in prompt+++def test_codex_generate_reports_transparent_background_claim(tmp_path: Path, monkeypatch) -> None:+ monkeypatch.setenv("CODEX_HOME", str(tmp_path))+ prompts: list[str] = []++ class _Completed:+ returncode = 0+ stdout = '{"type":"thread.started","thread_id":"aaaa-bbbb"}\n'+ stderr = ""++ def _fake_run(cmd, **kwargs):+ prompts.append(kwargs.get("input"))+ return _Completed()++ monkeypatch.setattr(codex_provider.subprocess, "run", _fake_run)+ monkeypatch.setattr(+ codex_provider, "_resolve_rollout", lambda sid, root, *, preexisting: tmp_path / "x.jsonl"+ )+ b64 = base64.b64encode(_png_bytes()).decode()+ monkeypatch.setattr(+ codex_provider,+ "_collect_inline_results",+ lambda rollout: [codex_provider.InlineResult(b64, transparent_background=True)],+ )+ run = codex_provider.CodexProvider(keep_session=True).generate(+ GenRequest(prompt="a fox", raw=tmp_path / "raw.png", native_alpha=True), tmp_path+ )+ assert run.extra["transparent_background_reported"] is True+ assert codex_provider._NATIVE_ALPHA_INSTRUCTION in prompts[0]+++def test_verify_native_alpha_writes_white_check(tmp_path: Path) -> None:+ raw = tmp_path / "raw.png"+ _native_rgba_image().save(raw)+ out = tmp_path / "out.png"+ check = tmp_path / "check.png"+ stats = chroma_mod.verify_native_alpha(raw, out, white_check=check)+ assert stats["white_check"] == str(check)+ assert Image.open(check).mode == "RGB"+ assert Image.open(check).getpixel((0, 0)) == (255, 255, 255)+++def test_cli_alpha_mode_defaults_to_auto_and_rejects_unknown() -> None:+ parser = gen._build_parser()+ args = parser.parse_args(["--out", "x.png", "--prompt", "p"])+ assert args.alpha_mode == "auto"+ assert parser.parse_args(["--out", "x.png", "--alpha-mode", "chroma"]).alpha_mode == "chroma"+ with pytest.raises(SystemExit):+ parser.parse_args(["--out", "x.png", "--alpha-mode", "magic"])++def test_generate_image_zero_percent_alpha_fails_without_success_report(tmp_path: Path,monkeypatch,