Skip to content

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__.py
index 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 chroma
post-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 Any
from sprite_gen.spec.runio import atomic_write_text
from . 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 CodexProvider
from .grok_provider import GrokProvider
PROVIDERS = ("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 None
owns_workdir = workdir is None
workdir = 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 = None
out.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.py
index edefe1f..7331932 100644
--- a/sprite_gen/gen/base.py
+++ b/sprite_gen/gen/base.py
@@ -18,6 +18,17 @@ from typing import Any, Protocol
PNG_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 = None
aspect_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 provider
def generate(self, request: GenRequest, workdir: Path) -> ProviderRun: ...
@@ -124,6 +140,11 @@ class GenResult:
session_id: str | None = None
refs: 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 = None
extra: 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.py
index 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 stats
diff --git a/sprite_gen/gen/codex_provider.py b/sprite_gen/gen/codex_provider.py
index af9fdae..991fb75 100644
--- a/sprite_gen/gen/codex_provider.py
+++ b/sprite_gen/gen/codex_provider.py
@@ -23,9 +23,19 @@ import os
import re
import subprocess
import time
+from dataclasses import dataclass
from 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 = None
def _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,
+ )
+ )
continue
if payload.get("type") not in _RESULT_TYPES or not payload.get("result"):
continue
status = 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_NATIVE
def __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.py
index 4e68f35..1c3c8ed 100644
--- a/sprite_gen/gen/grok_provider.py
+++ b/sprite_gen/gen/grok_provider.py
@@ -19,7 +19,16 @@ import subprocess
import time
from 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_CHROMA
def 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.py
index 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, monkey
monkeypatch.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) -> None
results = 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_CHROMA
def __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,