Skip to content

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

45.5 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Offline tests for the sprite_gen.gen provider layer.

Network/OAuth provider calls (codex exec, grok) are exercised as live e2e in the
C-gen deliverable; here we lock the deterministic seams: PNG verification, the
codex inline-base64 extraction contract, prompt shape, chroma post-process, and
the orchestrator wiring with a fake provider.
"""

from __future__ import annotations

import base64
import json
import sys
from pathlib import Path

import pytest
from PIL import Image

from sprite_gen import gen
from sprite_gen.gen import base as gen_base
from sprite_gen.gen import chroma as chroma_mod
from sprite_gen.gen import codex_provider
from sprite_gen.gen.base import GenRequest


def _png_bytes(color=(255, 0, 255, 255), size=(4, 4)) -> bytes:
    import io

    buf = io.BytesIO()
    Image.new("RGBA", size, color).save(buf, format="PNG")
    return buf.getvalue()


def test_verify_png_accepts_real_png_and_rejects_junk(tmp_path: Path) -> None:
    good = tmp_path / "good.png"
    good.write_bytes(_png_bytes())
    assert gen_base.verify_png(good) == len(good.read_bytes())

    bad = tmp_path / "bad.png"
    bad.write_bytes(b"not a png")
    with pytest.raises(SystemExit):
        gen_base.verify_png(bad)

    with pytest.raises(SystemExit):
        gen_base.verify_png(tmp_path / "missing.png")


def test_provider_subprocess_env_scrubs_orchestrator_session_env(monkeypatch) -> None:
    monkeypatch.setenv("ORCHESTRATOR_RUNTIME_ENDPOINT_ID", "synthetic-endpoint")
    monkeypatch.setenv("ORCHESTRATOR_MEMBER_ID", "synthetic-worker")
    monkeypatch.setenv("ORCHESTRATOR_PROJECT_ID", "synthetic-project")
    monkeypatch.setenv("ORCHESTRATOR_PLAN_EXIT_GATE", "1")
    monkeypatch.setenv("ORCHESTRATOR_STUDIO_PORT", "4312")
    monkeypatch.setenv("PATH", "/usr/bin")

    env = gen_base.provider_subprocess_env()

    assert not [
        key
        for key in env
        if key.endswith(gen_base._ORCHESTRATOR_SESSION_ENV_SUFFIXES)
    ], "orchestrator session variables must be scrubbed from provider environments"
    assert env.get("PATH") == "/usr/bin"  # 일반 env 는 유지


def test_provider_subprocess_env_reads_a_given_environment() -> None:
    env = gen_base.provider_subprocess_env({"PATH": "/bin", "ORCHESTRATOR_MEMBER_ID": "w"})
    assert env == {"PATH": "/bin"}


def test_env_api_key_is_the_key_none_or_a_refusal_of_an_empty_one() -> None:
    assert gen_base.env_api_key("SOME_API_KEY", {"SOME_API_KEY": " k "}, who="v") == "k"
    assert gen_base.env_api_key("SOME_API_KEY", {}, who="v") is None
    with pytest.raises(SystemExit, match="v: SOME_API_KEY is set but empty; give it a value or unset it"):
        gen_base.env_api_key("SOME_API_KEY", {"SOME_API_KEY": " "}, who="v")


def test_run_logged_keeps_everything_in_the_log_and_shows_the_charge_and_the_switch(tmp_path, capsys) -> None:
    lines = ["working", f"[gen] grok: running on XAI_API_KEY — {gen_base.API_CHARGE_WORDS} (q).",
             f"sprite-gen gen: default provider 'codex' unavailable (x) {gen_base.PROVIDER_SWITCH_WORDS} 'grok'.", "done"]
    script = "import sys\n" + "".join(f"print({line!r}, file=sys.stderr if {i} % 2 else sys.stdout)\n"
                                       for i, line in enumerate(lines))
    log = tmp_path / "child.log"
    assert gen_base.run_logged([sys.executable, "-c", script + "raise SystemExit(3)"], log) == 3
    assert sorted(log.read_text(encoding="utf-8").splitlines()) == sorted(lines)
    assert sorted(capsys.readouterr().err.splitlines()) == sorted(lines[1:3])


def test_provider_binary_resolves_windows_style_path_shims(monkeypatch) -> None:
    monkeypatch.setattr(gen_base.shutil, "which", lambda name: f"C:/tools/{name}.CMD")
    assert gen_base.provider_binary("codex") == "C:/tools/codex.CMD"
    monkeypatch.setattr(gen_base.shutil, "which", lambda _name: None)
    assert gen_base.provider_binary("codex") == "codex"


def test_json_report_writes_utf8_bytes_without_reconfiguring_stdout(monkeypatch) -> None:
    import io
    import sys

    raw = io.BytesIO()
    cp949_stream = io.TextIOWrapper(raw, encoding="cp949")
    monkeypatch.setattr(sys, "stdout", cp949_stream)
    gen_base.print_json({"prompt": "도구 — 완료"})
    cp949_stream.detach()
    assert json.loads(raw.getvalue().decode("utf-8")) == {"prompt": "도구 — 완료"}


def test_codex_inline_extraction_reads_both_record_types(tmp_path: Path) -> None:
    b64 = base64.b64encode(_png_bytes()).decode()
    rollout = tmp_path / "rollout-test.jsonl"
    lines = [
        {"payload": {"type": "response_item", "text": "noise"}},
        {"payload": {"type": "image_generation_call", "result": b64}},
        {"payload": {"type": "image_generation_end", "result": b64, "status": "completed"}},
    ]
    rollout.write_text("\n".join(json.dumps(line) for line in lines) + "\n", encoding="utf-8")

    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].result, dest)
    assert gen_base.verify_png(dest) > 0


def test_codex_inline_extraction_reads_0149_imagegen_extension(tmp_path: Path) -> None:
    b64 = base64.b64encode(_png_bytes()).decode()
    rollout = tmp_path / "rollout-codex-0149.jsonl"
    lines = [
        {
            "payload": {
                "type": "item_completed",
                "item": {
                    "type": "Extension",
                    "kind": "other.extension",
                    "status": "completed",
                    "result": b64,
                },
            }
        },
        {
            "payload": {
                "type": "item_completed",
                "item": {
                    "type": "Extension",
                    "kind": "image_gen.generation",
                    "status": "completed",
                    "result": b64,
                    "transparentBackground": True,
                },
            }
        },
    ]
    rollout.write_text("\n".join(json.dumps(line) for line in lines) + "\n", encoding="utf-8")

    results = codex_provider._collect_inline_results(rollout)

    # 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(
    ("status", "result", "expected_message"),
    [
        ("failed", "failure details", "status='failed'"),
        ("completed", None, "completed image_gen call has no result"),
    ],
)
def test_codex_inline_extraction_rejects_failed_or_empty_0149_imagegen_extension(
    tmp_path: Path,
    status: str,
    result: str | None,
    expected_message: str,
) -> None:
    rollout = tmp_path / "rollout-codex-0149-invalid.jsonl"
    rollout.write_text(
        json.dumps(
            {
                "payload": {
                    "type": "item_completed",
                    "item": {
                        "type": "Extension",
                        "kind": "image_gen.generation",
                        "status": status,
                        "result": result,
                    },
                }
            }
        )
        + "\n",
        encoding="utf-8",
    )

    with pytest.raises(SystemExit, match=expected_message):
        codex_provider._collect_inline_results(rollout)


def test_codex_inline_extraction_rejects_failed_status(tmp_path: Path) -> None:
    b64 = base64.b64encode(_png_bytes()).decode()
    rollout = tmp_path / "rollout-fail.jsonl"
    rollout.write_text(
        json.dumps({"payload": {"type": "image_generation_end", "result": b64, "status": "failed"}}) + "\n",
        encoding="utf-8",
    )
    with pytest.raises(SystemExit):
        codex_provider._collect_inline_results(rollout)


def test_codex_parse_session_id_json_and_legacy() -> None:
    json_stdout = (
        '{"type":"thread.started","thread_id":"018f0000-0000-7000-8000-000000000001"}\n'
        '{"type":"turn.started"}\n'
    )
    assert codex_provider._parse_session_id(json_stdout) == "018f0000-0000-7000-8000-000000000001"

    legacy_stdout = "some header\nsession id: abc123de-0000-1111-2222-333344445555\ndone\n"
    assert codex_provider._parse_session_id(legacy_stdout) == "abc123de-0000-1111-2222-333344445555"

    assert codex_provider._parse_session_id("no id here") is None


def test_codex_empty_rollout_fails_loud_on_tool_non_exposure(tmp_path: Path, monkeypatch) -> None:
    # An empty rollout is the tool-non-exposure signature. It must fail loudly, name
    # the account capability behind the active Codex state root as the thing that is
    # missing, and point at the one real remedy — never fall back to another
    # provider on its own, never trust a model-reported path, and never send the
    # reader off to hunt for a config toggle.
    monkeypatch.setenv("CODEX_HOME", str(tmp_path))
    rollout = tmp_path / "rollout-empty.jsonl"

    class _Completed:
        returncode = 0
        stdout = '{"type":"thread.started","thread_id":"aaaa-bbbb"}\n'
        stderr = ""

    monkeypatch.setattr(codex_provider.subprocess, "run", lambda cmd, **kwargs: _Completed())
    monkeypatch.setattr(codex_provider, "codex_login", lambda: codex_provider.CodexLogin(codex_provider.AUTH_SOURCE_LOGIN))
    monkeypatch.setattr(
        codex_provider,
        "_resolve_rollout",
        lambda sid, sessions_root, *, preexisting: rollout,
    )
    monkeypatch.setattr(codex_provider, "_collect_inline_results", lambda path: [])

    with pytest.raises(SystemExit) as excinfo:
        codex_provider.CodexProvider(keep_session=True).generate(
            GenRequest(prompt="a mushroom", raw=tmp_path / "raw.png"), tmp_path
        )

    message = str(excinfo.value)
    assert "image_gen tool never ran" in message
    assert "$imagegen" in message
    assert str(rollout) in message
    # The message must name the missing capability and the state root that lacks
    # it, and must close off the config-toggle detour.
    assert "capability" in message
    assert str(tmp_path) in message, "the failing Codex state root must be named"
    assert "does not grant it" in message
    assert not (tmp_path / "raw.png").exists(), "a failed run must not leave a raw PNG"


def test_codex_prompt_reaches_the_child_process(tmp_path: Path, monkeypatch) -> None:
    # The trigger is only real if it survives into codex exec's stdin — assert the
    # transport prompt is what the child actually receives, not just what we build.
    monkeypatch.setenv("CODEX_HOME", str(tmp_path))
    monkeypatch.setenv("ORCHESTRATOR_RUNTIME_ENDPOINT_ID", "synthetic-endpoint")
    monkeypatch.setattr(codex_provider, "provider_binary", lambda _name: "C:/bin/codex.CMD")
    seen: dict = {}

    class _Completed:
        returncode = 0
        stdout = '{"type":"thread.started","thread_id":"aaaa-bbbb"}\n'
        stderr = ""

    def _fake_run(cmd, **kwargs):
        seen["cmd"] = cmd
        seen["env"] = kwargs.get("env")
        seen["encoding"] = kwargs.get("encoding")
        seen["input"] = kwargs.get("input", "")
        return _Completed()

    monkeypatch.setattr(codex_provider.subprocess, "run", _fake_run)
    monkeypatch.setattr(codex_provider, "codex_login", lambda: codex_provider.CodexLogin(codex_provider.AUTH_SOURCE_LOGIN))
    monkeypatch.setattr(
        codex_provider,
        "_resolve_rollout",
        lambda sid, sessions_root, *, preexisting: tmp_path / "x.jsonl",
    )
    b64 = base64.b64encode(_png_bytes()).decode()
    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
    )

    assert seen["cmd"][0] == "C:/bin/codex.CMD"
    assert seen["env"] is not None
    assert "ORCHESTRATOR_RUNTIME_ENDPOINT_ID" not in seen["env"]
    assert seen["encoding"] == "utf-8"
    assert seen["input"].startswith("$imagegen ")
    assert "a mushroom" in seen["input"]


def test_chroma_key_transparent_clears_magenta(tmp_path: Path) -> None:
    src = tmp_path / "src.png"
    img = Image.new("RGBA", (6, 6), (255, 0, 255, 255))
    for y in range(2, 4):
        for x in range(2, 4):
            img.putpixel((x, y), (245, 245, 245, 255))
    img.save(src)

    out = tmp_path / "out.png"
    stats = chroma_mod.key_transparent(src, out, key="magenta", white_check=tmp_path / "check.png")
    assert stats["mode"] == "RGBA"
    assert stats["stale_transparent_rgb_pixels"] == 0
    assert stats["keyed_pixels"] == 32

    keyed = Image.open(out).convert("RGBA")
    assert keyed.getpixel((0, 0))[3] == 0
    assert keyed.getpixel((2, 2))[3] == 255


@pytest.mark.parametrize(
    ("key", "background", "subject"),
    [
        (
            "magenta",
            lambda x, y: (238 - (x % 7), 124 + ((x + y) % 31), 229 - (y % 5), 255),
            (20, 220, 60, 255),
        ),
        (
            "green",
            lambda x, y: (124 + ((x + y) % 31), 238 - (x % 7), 129 + (y % 5), 255),
            (220, 20, 200, 255),
        ),
    ],
)
def test_chroma_key_transparent_removes_textured_gradient_background(
    tmp_path: Path,
    key: str,
    background,
    subject: tuple[int, int, int, int],
) -> None:
    src = tmp_path / f"{key}-gradient.png"
    image = Image.new("RGBA", (96, 64))
    pixels = image.load()
    for y in range(image.height):
        for x in range(image.width):
            pixels[x, y] = background(x, y)
    for y in range(20, 44):
        for x in range(32, 64):
            pixels[x, y] = subject
    image.save(src)

    out = tmp_path / f"{key}-out.png"
    stats = chroma_mod.key_transparent(src, out, key=key)

    keyed = Image.open(out).convert("RGBA")
    assert stats["alpha_zero_pct"] > 50.0
    assert keyed.getpixel((0, 0))[3] == 0
    assert keyed.getpixel((48, 32))[3] == 255


class _FakeProvider:
    name = "fake"
    transparency = gen_base.TRANSPARENCY_CHROMA
    size = (8, 8)

    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", self.size, (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"]["strategy_source"] == "provider-default"
    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


@pytest.mark.parametrize(
    ("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_explicit_native_still_runs_with_refs(tmp_path: Path, monkeypatch) -> None:
    fake = _FakeNativeProvider()
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    ref = tmp_path / "ref.png"
    ref.write_bytes(_png_bytes())
    out = tmp_path / "asset.png"
    report = tmp_path / "report.json"

    assert gen.run(**_gen_kwargs(out, report, ref=[ref], alpha_mode="native")) == 0

    assert fake.requests[0].native_alpha is True
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["alpha"]["strategy"] == "native"
    assert payload["alpha"]["strategy_source"] == "explicit"


# Raws a ref run can come back with (2026-10-04): a real cut-out (a transparent
# --ref is answered with alpha) and a painted key background; a drawn checkerboard is
# refused in tests/gen/test_painted_checkerboard.py.
# The figure is a dark outline around an orange body with a cream belly — the two
# colours a second key took off the real cut-out.
_OUTLINE, _BODY, _CREAM = (20, 20, 20), (240, 140, 40), (245, 230, 200)
_OUTLINE_PX, _CREAM_PX = (17, 32), (32, 37)


def _outlined_figure(background: Image.Image) -> Image.Image:
    from PIL import ImageDraw

    alpha = (255,) if background.mode == "RGBA" else ()
    draw = ImageDraw.Draw(background)
    draw.ellipse((16, 12, 48, 52), fill=_OUTLINE + alpha)
    draw.ellipse((19, 15, 45, 49), fill=_BODY + alpha)
    draw.ellipse((26, 30, 38, 44), fill=_CREAM + alpha)
    return background


def _real_alpha_raw() -> Image.Image:
    return _outlined_figure(Image.new("RGBA", (64, 64), (0, 0, 0, 0)))


def _key_background_raw() -> Image.Image:
    return _outlined_figure(Image.new("RGB", (64, 64), (255, 0, 255)))


def _ref_run(tmp_path: Path, monkeypatch, raw: Image.Image, **overrides):
    fake = _FakeNativeProvider(raw)
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    ref = tmp_path / "ref.png"
    ref.write_bytes(_png_bytes(color=(0, 0, 0, 0)))
    out = tmp_path / "asset.png"
    report = tmp_path / "report.json"
    rc = gen.run(**_gen_kwargs(out, report, ref=[ref], **overrides))
    return fake, rc, out, report


def test_ref_run_publishes_a_real_alpha_raw_without_keying_its_outline(
    tmp_path: Path, monkeypatch, capsys
) -> None:
    fake, rc, out, report = _ref_run(tmp_path, monkeypatch, _real_alpha_raw())

    assert rc == 0
    assert fake.requests[0].native_alpha is False  # still planned as a key: no transparency request
    published = Image.open(out)
    assert published.getpixel(_OUTLINE_PX) == _OUTLINE + (255,)
    assert published.getpixel(_CREAM_PX) == _CREAM + (255,)
    assert published.getchannel("A").tobytes() == _real_alpha_raw().getchannel("A").tobytes()
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["alpha"]["strategy"] == "native"
    assert payload["alpha"]["strategy_source"] == "refs-attached-raw-alpha"
    assert payload["alpha"]["method"] == "native"
    assert payload["alpha"]["raw_alpha"]["verdict"] == "real-alpha"
    assert payload["alpha"]["raw_alpha"]["border_alpha_zero_pct"] == 100.0
    assert payload["chroma"] is None
    assert "publishing its own alpha" in capsys.readouterr().err


def test_ref_run_still_keys_a_raw_with_no_alpha(tmp_path: Path, monkeypatch, capsys) -> None:
    fake, rc, out, report = _ref_run(tmp_path, monkeypatch, _key_background_raw())

    assert rc == 0
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["alpha"]["strategy"] == "chroma"
    assert payload["alpha"]["strategy_source"] == "refs-attached"
    assert payload["alpha"]["method"] == "ycbcr"
    assert payload["alpha"]["raw_alpha"] == {
        "mode": "RGB", "has_alpha_band": False, "verdict": "no-alpha",
        "alpha_zero_pct": 0.0, "border_alpha_zero_pct": 0.0,
    }
    assert payload["chroma"]["key"] == "magenta"
    assert Image.open(out).getpixel((0, 0)) == (0, 0, 0, 0)  # the background was keyed out
    assert "reference image(s) attached" in capsys.readouterr().err


def test_ref_run_keys_an_ambiguous_raw_and_warns(tmp_path: Path, monkeypatch, capsys) -> None:
    # A key background with a few transparent pixels in one corner: alpha 0 that is
    # not a transparent background. Keyed as planned, and the report says why.
    raw = _outlined_figure(Image.new("RGBA", (64, 64), (255, 0, 255, 255)))
    for y in range(3):
        for x in range(3):
            raw.putpixel((x, y), (0, 0, 0, 0))
    _, rc, _, report = _ref_run(tmp_path, monkeypatch, raw)

    assert rc == 0
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["alpha"]["strategy"] == "chroma"
    assert payload["alpha"]["strategy_source"] == "refs-attached"
    assert payload["alpha"]["raw_alpha"]["verdict"] == "ambiguous"
    assert "keyed as planned" in payload["alpha"]["raw_alpha"]["warning"]
    assert "warning: the raw has some transparent pixels" in capsys.readouterr().err


@pytest.mark.parametrize("decontam", ["palette", "auto"])
def test_ref_run_with_decontam_skips_it_on_a_real_alpha_raw(tmp_path: Path, monkeypatch, capsys, decontam) -> None:
    # The generation is paid for and its alpha is good: there is no key to decontaminate,
    # so the pass is skipped, said on stderr and recorded — not refused after the call.
    fake = _FakeNativeProvider(_real_alpha_raw())
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    ref = tmp_path / "ref.png"
    ref.write_bytes(_png_bytes())
    out = tmp_path / "asset.png"
    result = gen.generate_image("fake", "a mushroom", out, refs=[ref], transparent=True, decontam=decontam)

    assert result.alpha["strategy_source"] == "refs-attached-raw-alpha"
    assert result.alpha["decontam"]["requested"] == decontam
    assert "has no key to remove" in result.alpha["decontam"]["skipped"]
    assert Image.open(out).getpixel(_OUTLINE_PX) == _OUTLINE + (255,)
    err = capsys.readouterr().err
    assert f"--decontam {decontam} skipped" in err
    assert ("warning: --decontam" in err) is (decontam == "palette")


def test_ref_run_with_decontam_palette_still_decontaminates_a_keyed_raw(tmp_path: Path, monkeypatch) -> None:
    fake = _FakeNativeProvider(_key_background_raw())
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    ref = tmp_path / "ref.png"
    ref.write_bytes(_png_bytes())
    result = gen.generate_image("fake", "a mushroom", tmp_path / "asset.png", refs=[ref], transparent=True,
                                decontam="palette")
    assert result.alpha["strategy_source"] == "refs-attached"
    assert "skipped" not in result.alpha["decontam"]


# `auto`'s step down plans a key, so the prompt must ask for one: a ref prompt with no key
# background came back on white (2026-10-04), and keying white takes the outline's light
# neighbours and the cream with it. The engine adds the line unless the prompt names a key.
class _PromptFollowingProvider(_FakeNativeProvider):
    """Draws the figure on the key the prompt asks for, or on white when it asks for none."""

    def generate(self, request: GenRequest, workdir: Path):
        key = chroma_mod.named_key_background(request.prompt)
        ground = chroma_mod.KEYS[key]["target"] if key else (255, 255, 255)
        self.image = _outlined_figure(Image.new("RGB", (64, 64), ground))
        return super().generate(request, workdir)


def test_ref_run_adds_the_key_background_line_to_a_prompt_without_one(tmp_path: Path, monkeypatch, capsys) -> None:
    fake = _PromptFollowingProvider()
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    ref = tmp_path / "ref.png"
    ref.write_bytes(_png_bytes())
    out = tmp_path / "asset.png"
    report = tmp_path / "report.json"

    assert gen.run(**_gen_kwargs(out, report, ref=[ref])) == 0

    prompt = fake.requests[0].prompt
    assert prompt.startswith("a mushroom")
    assert prompt.endswith(chroma_mod.KEY_BACKGROUND_TEXT["magenta"])
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["alpha"]["key_background"] == {"injected": True, "key": "magenta"}
    assert payload["prompt"] == prompt
    published = Image.open(out)
    assert published.getpixel((0, 0)) == (0, 0, 0, 0)
    assert published.getpixel(_OUTLINE_PX) == _OUTLINE + (255,)
    assert published.getpixel(_CREAM_PX) == _CREAM + (255,)
    assert "added a magenta key background line" in capsys.readouterr().err


def test_ref_run_adds_the_line_in_the_chosen_key(tmp_path: Path, monkeypatch) -> None:
    fake = _PromptFollowingProvider()
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    ref = tmp_path / "ref.png"
    ref.write_bytes(_png_bytes())
    result = gen.generate_image("fake", "a magenta mushroom", tmp_path / "asset.png", refs=[ref],
                                transparent=True, chroma_key="green")
    assert fake.requests[0].prompt.endswith(chroma_mod.KEY_BACKGROUND_TEXT["green"])
    assert result.alpha["key_background"] == {"injected": True, "key": "green"}
    assert result.chroma["key"] == "green"


@pytest.mark.parametrize(
    ("prompt", "named"),
    [
        ("a mushroom. " + chroma_mod.KEY_BACKGROUND_TEXT["magenta"], "magenta"),
        ("a mushroom on a flat #ff00ff background", "magenta"),
        ("a mushroom on a pure magenta chroma-key background", "magenta"),
        ("a mushroom in front of a green screen", "green"),
    ],
    ids=["engine-line", "hex", "name", "other-key"],
)
def test_ref_run_keeps_a_key_background_the_prompt_already_names(
    tmp_path: Path, monkeypatch, prompt: str, named: str
) -> None:
    fake = _PromptFollowingProvider()
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    ref = tmp_path / "ref.png"
    ref.write_bytes(_png_bytes())
    result = gen.generate_image("fake", prompt, tmp_path / "asset.png", refs=[ref], transparent=True)
    assert fake.requests[0].prompt == prompt
    assert result.alpha["key_background"] == {"injected": False, "key": named}


@pytest.mark.parametrize(
    "overrides",
    [{"alpha_mode": "chroma"}, {"alpha_mode": "native"}, {"ref": []}, {"transparent": False}],
    ids=["explicit-chroma", "explicit-native", "no-ref", "opaque"],
)
def test_only_autos_ref_step_down_adds_the_key_line(tmp_path: Path, monkeypatch, overrides) -> None:
    fake = _FakeNativeProvider()
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    ref = tmp_path / "ref.png"
    ref.write_bytes(_png_bytes())
    out = tmp_path / "asset.png"
    report = tmp_path / "report.json"
    gen.run(**_gen_kwargs(out, report, **{"ref": [ref], **overrides}))
    assert fake.requests[0].prompt == "a mushroom"
    alpha = json.loads(report.read_text(encoding="utf-8")).get("alpha") or {}
    assert "key_background" not in alpha


@pytest.mark.parametrize(
    ("prompt", "named"),
    [
        ("a green frog on a white background", None),
        ("a magenta mushroom, red cap", None),
        ("draw it on #00FF00", "green"),
        ("FF00FF", "magenta"),
        ("a colour FF00FFAA nearby", None),
        ("a green backdrop; #FF00FF elsewhere", "green"),
    ],
)
def test_named_key_background(prompt: str, named: str | None) -> None:
    assert chroma_mod.named_key_background(prompt) == named


def test_explicit_chroma_keys_even_a_real_alpha_raw(tmp_path: Path, monkeypatch) -> None:
    # --alpha-mode chroma is the caller's own key: the raw check belongs to auto's step down only.
    _, rc, _, report = _ref_run(tmp_path, monkeypatch, _real_alpha_raw(), alpha_mode="chroma")
    assert rc == 0
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["alpha"]["strategy"] == "chroma"
    assert payload["alpha"]["strategy_source"] == "explicit"
    assert "raw_alpha" not in payload["alpha"]


@pytest.mark.parametrize(
    ("image", "verdict"),
    [
        (Image.new("RGB", (16, 16), (255, 0, 255)), "no-alpha"),
        (Image.new("RGBA", (16, 16), (255, 0, 255, 255)), "no-alpha"),
        (Image.new("LA", (16, 16), (0, 0)), "real-alpha"),
    ],
    ids=["rgb", "opaque-rgba", "transparent-la"],
)
def test_classify_raw_alpha_reads_the_alpha_band(tmp_path: Path, image: Image.Image, verdict: str) -> None:
    path = tmp_path / "raw.png"
    image.save(path)
    assert chroma_mod.classify_raw_alpha(path)["verdict"] == verdict


def test_classify_raw_alpha_judges_before_rounding(tmp_path: Path) -> None:
    # One alpha-0 pixel in 200 x 200 is 0.0025 %, reported as 0.0 but not "no alpha".
    image = Image.new("RGBA", (200, 200), (255, 0, 255, 255))
    image.putpixel((0, 0), (0, 0, 0, 0))
    path = tmp_path / "raw.png"
    image.save(path)
    stats = chroma_mod.classify_raw_alpha(path)
    assert stats["alpha_zero_pct"] == 0.0
    assert stats["verdict"] == "ambiguous"


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


@pytest.mark.parametrize("options, flag", [({"quality": "max"}, "--quality"),
                                           ({"quality": "auto"}, "--quality"),
                                           ({"resolution": "2k"}, "--resolution")])
def test_codex_refuses_a_level_image_gen_cannot_carry(tmp_path: Path, monkeypatch, options, flag) -> None:
    """image_gen has no effort or size dial, so the level is refused, never dropped:
    a caller who paid attention to --quality must not get a default-effort image."""
    import subprocess

    monkeypatch.setattr(subprocess, "run", lambda *a, **k: pytest.fail("codex must not be spawned"))
    with pytest.raises(SystemExit, match=flag) as error:
        codex_provider.CodexProvider().generate(GenRequest("x", tmp_path / "raw.png", **options), tmp_path)
    assert "openai" in str(error.value)
    assert not (tmp_path / "raw.png").exists()


def test_grok_refuses_a_native_alpha_request_before_upload(tmp_path: Path, monkeypatch) -> None:
    from sprite_gen.gen import grok_provider

    spawned: list = []
    monkeypatch.setattr(grok_provider.xai, "http_json", 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, "codex_login", lambda: codex_provider.CodexLogin(codex_provider.AUTH_SOURCE_LOGIN))
    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,
) -> None:
    fake = _FakeProvider()
    fake.size = (150, 150)
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)

    def ineffective_matte(image, chroma_key, warnings):
        result = image.convert("RGBA")
        result.putpixel((0, 0), (0, 0, 0, 0))
        return result

    monkeypatch.setattr(chroma_mod, "remove_chroma_background_ycbcr", ineffective_matte)

    out = tmp_path / "asset.png"
    report = tmp_path / "report.json"
    with pytest.raises(SystemExit, match=r"0\.0% transparent pixels"):
        gen.run(
            provider="fake",
            prompt="a mushroom",
            out=out,
            ref=[],
            model=None,
            aspect_ratio=None,
            transparent=True,
            chroma_key="magenta",
            white_check=None,
            keep_session=False,
            report=report,
            prompt_file=None,
            workdir=None,
        )

    assert not out.exists()
    assert not report.exists()


def test_generate_image_orchestrates_report_and_raw_keep(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"
    rc = gen.run(
        provider="fake",
        prompt="a mushroom",
        out=out,
        ref=[],
        model=None,
        aspect_ratio=None,
        transparent=True,
        chroma_key="magenta",
        white_check=None,
        keep_session=False,
        report=report,
        prompt_file=None,
        workdir=None,
    )
    assert rc == 0
    assert fake.calls == 1
    assert fake.requests[0].native_alpha is False
    assert out.is_file()
    assert (tmp_path / "asset.png.raw.png").is_file()  # pre-chroma raw preserved
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["provider"] == "fake"
    assert payload["transparent"] is True
    assert payload["alpha"]["strategy"] == "chroma"
    assert payload["alpha"]["method"] == "ycbcr"
    assert payload["chroma"]["method"] == "ycbcr"
    assert payload["chroma"]["stale_transparent_rgb_pixels"] == 0
    assert payload["elapsed_seconds"] == 1.23


def test_generate_image_empty_prompt_fails_loud(tmp_path: Path) -> None:
    with pytest.raises(SystemExit):
        gen.generate_image("codex", "   ", tmp_path / "x.png")


def test_unknown_provider_fails_loud(tmp_path: Path) -> None:
    with pytest.raises(SystemExit):
        gen._make_provider("gemini", keep_session=False)


# ── Default-provider policy (maintainer 2026-07-17): default = codex, SPRITE_GEN_DEFAULT_PROVIDER override;
# a codex that cannot run turns into what the user chose for that (2026-10-16, tests/gen/test_codex_unavailable.py). ──

def test_resolve_default_provider_env_override(monkeypatch) -> None:
    monkeypatch.setenv(gen.DEFAULT_PROVIDER_ENV, "grok")
    # codex probe must not even run when the env pins a non-codex default.
    monkeypatch.setattr(gen, "_codex_available", lambda: pytest.fail("probe should not run"))
    assert gen.resolve_default_provider() == ("grok", None)


def test_resolve_default_provider_invalid_env_fails_loud(monkeypatch) -> None:
    monkeypatch.setenv(gen.DEFAULT_PROVIDER_ENV, "gemini")
    with pytest.raises(SystemExit):
        gen.resolve_default_provider()


def test_resolve_default_provider_env_codex_down_follows_the_codex_choice(monkeypatch) -> None:
    # An env that pins codex is the same default: down, it asks, or runs what was chosen (default_source=env).
    monkeypatch.setenv(gen.DEFAULT_PROVIDER_ENV, "codex")
    monkeypatch.setattr(gen, "_codex_available", lambda: (False, "codex CLI not found on PATH"))
    with pytest.raises(gen_base.CodexUnavailableAsk):
        gen.resolve_default_provider()
    monkeypatch.setenv(gen.CODEX_UNAVAILABLE_ENV, "grok")
    provider, fallback = gen.resolve_default_provider()
    assert provider == "grok"
    assert fallback["default_source"] == gen.DEFAULT_PROVIDER_ENV


def _install_recording_provider(monkeypatch):
    """Monkeypatch _make_provider to record the requested name and emit a PNG."""
    requested: list[str] = []

    def fake_make(name, *, keep_session):
        requested.append(name)

        class _P:
            def generate(self, request: GenRequest, workdir: Path):
                Image.new("RGBA", (8, 8), (255, 0, 255, 255)).save(request.raw)
                return gen_base.ProviderRun(provider=name, elapsed_seconds=0.1, model=request.model)

        return _P()

    monkeypatch.setattr(gen, "_make_provider", fake_make)
    return requested


def test_run_explicit_provider_is_honored_without_fallback(tmp_path: Path, monkeypatch) -> None:
    requested = _install_recording_provider(monkeypatch)
    # Even with codex "down", an EXPLICIT --provider is never overridden.
    monkeypatch.setattr(gen, "_codex_available", lambda: (False, "should be irrelevant"))
    report = tmp_path / "r.json"
    rc = gen.run(provider="grok", prompt="x", out=tmp_path / "o.png", report=report)
    assert rc == 0
    assert requested == ["grok"]
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["provider"] == "grok"
    assert payload["provider_resolved_from"] == "explicit"
    assert "provider_fallback" not in payload


def test_run_default_uses_codex_when_available(tmp_path: Path, monkeypatch) -> None:
    monkeypatch.delenv(gen.DEFAULT_PROVIDER_ENV, raising=False)
    requested = _install_recording_provider(monkeypatch)
    monkeypatch.setattr(gen, "_codex_available", lambda: (True, ""))
    report = tmp_path / "r.json"
    rc = gen.run(prompt="x", out=tmp_path / "o.png", report=report)
    assert rc == 0
    assert requested == ["codex"]
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["provider"] == "codex"
    assert payload["provider_resolved_from"] == "hard-default"
    assert "provider_fallback" not in payload


def test_run_default_falls_back_to_the_chosen_grok_and_reports_it(tmp_path: Path, monkeypatch, capsys) -> None:
    monkeypatch.delenv(gen.DEFAULT_PROVIDER_ENV, raising=False)
    monkeypatch.setenv(gen.CODEX_UNAVAILABLE_ENV, "grok")
    requested = _install_recording_provider(monkeypatch)
    monkeypatch.setattr(gen, "_codex_available", lambda: (False, "codex not logged in (test)"))
    report = tmp_path / "r.json"
    rc = gen.run(prompt="x", out=tmp_path / "o.png", report=report)
    assert rc == 0
    assert requested == ["grok"]  # actually generated with grok
    payload = json.loads(report.read_text(encoding="utf-8"))
    assert payload["provider"] == "grok"
    assert payload["provider_resolved_from"] == "fallback-from-codex"
    assert payload["provider_fallback"]["from"] == "codex"
    assert payload["provider_fallback"]["to"] == "grok"
    assert "codex not logged in" in payload["provider_fallback"]["reason"]
    assert payload["provider_fallback"]["chosen_by"] == gen.CODEX_UNAVAILABLE_ENV
    # And the fallback is loud on stderr (No Silent Fallback).
    assert "falling back to 'grok'" in capsys.readouterr().err


def test_codex_stream_errors_surface_the_real_cause() -> None:
    # codex reports a fatal error (e.g. an unsupported model) on stdout as a
    # `turn.failed` event, with the API error nested as JSON inside `message`.
    # Item-level warnings (model metadata, skills budget) must not drown it out.
    stream = "\n".join([
        '{"type":"thread.started","thread_id":"abc"}',
        '{"type":"item.completed","item":{"type":"error","message":"Model metadata for `x` not found."}}',
        '{"type":"turn.failed","error":{"message":'
        '"{\\"type\\":\\"error\\",\\"status\\":400,\\"error\\":'
        '{\\"type\\":\\"invalid_request_error\\",'
        '\\"message\\":\\"The model is not supported.\\"}}"}}',
    ])
    assert codex_provider._extract_stream_errors(stream) == ["The model is not supported."]


def test_codex_stream_errors_empty_when_no_failure() -> None:
    stream = '{"type":"thread.started","thread_id":"abc"}\n{"type":"turn.completed"}'
    assert codex_provider._extract_stream_errors(stream) == []