Skip to content

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

43.8 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Unified image generation layer for sprite-gen.

Single source of truth for provider-backed image generation: codex (`image_gen`,
the ChatGPT login; an API-key login bills per call and says so), grok (Imagine, the
Grok login; XAI_API_KEY only without one, billed per call and said) and openai
(Images REST, OPENAI_API_KEY).
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`.

codex and openai reach the same family of GPT image models by different routes:
codex needs an interactive ChatGPT login and the `codex` CLI on PATH, openai needs
only an API key, which is what a headless container (Modal worker, CI) can have.

sprite-gen is subscription-first (수홍 2026-09-20). openai exists for servers and
SaaS and is billed per call, so it runs ONLY when the user chose it (수홍 2026-10-16):
`--provider openai` names it, or it is the user's answer for a default codex that
cannot run (`codex_unavailable_choice`). It is never a default, never the guided
flow's image provider, and never reached unasked. Having OPENAI_API_KEY in the
environment changes no route by itself.

Transparency is a per-provider strategy (`Provider.transparency`, declared once
in each adapter): codex `image_gen` and openai (`background: transparent`) return 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|openai --prompt "..." --out DEST.png
        [--ref REF.png ...] [--transparent [--alpha-mode auto|native|chroma]
        [--chroma-key magenta|green]] [--white-check CHECK.png] [--model ID]
        [--aspect-ratio 1:1] [--quality low|medium|high|xhigh|max|auto]
        [--resolution 1k|1.5k|2k] [--layout-guide [figure]]
        [--report REPORT.json] [--keep-session]
"""

from __future__ import annotations

import argparse
import json
import os
import shutil
import sys
import tempfile
from pathlib import Path
from typing import Any, Callable

from sprite_gen.frames import extract as extract_mod
from sprite_gen.frames.cutout import MAGENTA
from sprite_gen.spec.runio import atomic_write_text
from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.video import body_plan as body_mod
from sprite_gen.video.body_plan import Body

from . import chroma as chroma_mod
from . import codex_provider
from . import facing as facing_mod
from . import handedness as handed_mod
from . import prompt_parts
from .base import (
    CODEX_UNAVAILABLE_EXIT,
    PROVIDER_CODEX,
    PROVIDER_GROK,
    PROVIDER_OPENAI,
    QUALITIES,
    RESOLUTIONS,
    TRANSPARENCY_CHROMA,
    TRANSPARENCY_NATIVE,
    TRANSPARENCY_STRATEGIES,
    GenRequest,
    GenResult,
    PROVIDER_SWITCH_WORDS,
    GenTimeoutError,
    ask_codex_unavailable,
    codex_unavailable_question,
    print_json,
    verify_png,
)
from .codex_provider import CodexProvider
from .grok_provider import GrokProvider
from .openai_provider import OpenAIProvider
from sprite_gen.util.console import utf8_streams

PROVIDERS = (PROVIDER_CODEX, PROVIDER_GROK, PROVIDER_OPENAI)
# `--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`); a user can change the default with SPRITE_GEN_DEFAULT_PROVIDER.
# An EXPLICIT `--provider` is always honored exactly — an explicitly named provider
# that is down fails loud at generation time.
DEFAULT_PROVIDER_ENV = "SPRITE_GEN_DEFAULT_PROVIDER"
HARD_DEFAULT_PROVIDER = PROVIDER_CODEX
# A per-call API-billed backend is never a default: only a choice the user made
# reaches it, so nothing routes a subscription user onto metered credit unasked
# (구독 우선 불변식 1-2).
EXPLICIT_ONLY_PROVIDERS = (PROVIDER_OPENAI,)
# What a default codex that cannot run here turns into (수홍 2026-10-16, docs/gen.md "When codex cannot run"):
# codex is not signed in (`codex_provider.codex_login`), or `codex exec` said its usage is used up
# (`codex_provider.CodexUsageLimit`). `ask` (the default) ends the call with one question and nothing generated
# (`base.ask_codex_unavailable`); `grok` and `openai` run that provider, said on stderr and kept in the report
# (`provider_fallback`). The choice is SPRITE_GEN_CODEX_UNAVAILABLE, else the saved one (`sprite-gen defaults`,
# key CODEX_UNAVAILABLE_SETTING), else `ask`. Until 2.44.0 it went to grok unasked.
CODEX_UNAVAILABLE_ENV = "SPRITE_GEN_CODEX_UNAVAILABLE"
CODEX_UNAVAILABLE_SETTING = "codex_unavailable"
CODEX_UNAVAILABLE_ASK = "ask"
CODEX_UNAVAILABLE_CHOICES = (CODEX_UNAVAILABLE_ASK, PROVIDER_GROK, PROVIDER_OPENAI)
CODEX_UNAVAILABLE_DEFAULT = CODEX_UNAVAILABLE_ASK

# `--layout-guide`: the one-slot form of the guide `prepare` draws for every row
# (`draw_guide`, the same 9.4 % safe margin), attached after the caller's refs, with
# the anatomy lines of the row guide experiments on it: an orange line where the
# skull's crown goes and a teal line where the soles stand, each one safe margin
# INSIDE the safe box. On the box's own edges the lines read as frame edges: hair and
# hats fill the room above the crown and feet float off a floor taken for a border,
# so both were moved in by a margin. A single still drawn without the guide fills
# its frame top to bottom, and a tall subject then has nothing above the head for an
# in-place motion to bob into; a box alone is read loosely, the lines set the scale.
LAYOUT_GUIDE_LONG_EDGE = 1024
LAYOUT_GUIDE_NAME = "layout-guide.png"
# The bare flag is the figure guide, the one kind there is.
LAYOUT_GUIDE_KINDS = ("figure",)
CROWN_LINE = "#ff7a00"
CROWN_MARK = "#ffb15c"
FLOOR_LINE = "#00a7a7"
FLOOR_MARK = "#63d6d6"
def layout_guide_text(cell: dict[str, Any]) -> str:
    """The prompt's half of the guide: where the two lines are, as shares of the frame height."""
    height = int(cell["height"])
    crown = round(100 * int(cell["crown_y"]) / height)
    floor = round(100 * int(cell["floor_y"]) / height)
    return (
        "Layout: the last attached image is a layout guide, not part of the character. It shows the frame, "
        "its inner safe area (the blue box), the center line, an orange crown line and a teal floor line. "
        f"Place the anatomical top of the skull on the orange line, {crown}% of the frame height from the top, "
        f"and the lowest supporting sole on the teal line, {floor}% from the top, centered on the center line: "
        f"an upright crown-to-floor span of {floor - crown}% of the frame height. Ignore hair tufts, raised "
        "limbs, hats, accessories and props when identifying the crown; they may rise above the orange line "
        "but stay inside the blue box. The teal line sits INSIDE the safe area, above the bottom safe padding: "
        "it is a ground-contact line, not a frame edge. The supporting soles must touch it and may not float "
        "above it, and the space below it stays empty. The colored lines set the character's scale and height "
        "in the frame; they are not artwork. Do not reproduce the layout guide itself: no boxes, guide lines, "
        "center marks, labels, guide colors or the guide's grey background may appear in the output."
    )


def layout_guide_size(aspect_ratio: str | None) -> tuple[int, int]:
    """The guide's pixels for the requested ratio, long edge {LAYOUT_GUIDE_LONG_EDGE}; square without one.

    Only the proportions matter to the model, so the size is the ratio's own and not a
    provider's output size (codex has none to ask for).
    """
    if aspect_ratio in (None, "", "auto"):
        return LAYOUT_GUIDE_LONG_EDGE, LAYOUT_GUIDE_LONG_EDGE
    try:
        width_part, height_part = str(aspect_ratio).split(":")
        width, height = float(width_part), float(height_part)
        if width <= 0 or height <= 0:
            raise ValueError
    except ValueError as exc:
        raise SystemExit(f"gen: --layout-guide cannot read aspect ratio {aspect_ratio!r}") from exc
    scale = LAYOUT_GUIDE_LONG_EDGE / max(width, height)
    return round(width * scale), round(height * scale)


def layout_guide_cell(aspect_ratio: str | None) -> dict[str, Any]:
    """The one-slot guide's cell for the requested ratio: its size, safe margins and the two anatomy lines,
    one margin inside the safe box's top and bottom edges. What `layout_guide_text` says and
    `draw_layout_guide` draws."""
    # Imported here: `prepare` owns the row guide and pulls in the row machinery.
    from .prepare import normalize_cell

    width, height = layout_guide_size(aspect_ratio)
    cell = normalize_cell({"width": width, "height": height}, width, None)
    margin_y = int(cell["safe_margin_y"])
    return {**cell, "crown_y": 2 * margin_y, "floor_y": height - 1 - 2 * margin_y}


def draw_layout_guide(path: Path, aspect_ratio: str | None) -> dict[str, Any]:
    """Draws the one-slot guide at `path` and answers its cell (`layout_guide_cell`)."""
    from .prepare import draw_guide

    from PIL import Image, ImageDraw

    cell = layout_guide_cell(aspect_ratio)
    width, height = int(cell["width"]), int(cell["height"])
    draw_guide(path, 1, {key: value for key, value in cell.items() if key not in ("crown_y", "floor_y")})
    # The anatomy lines as the row experiments drew them on a 256 px cell (5 px lines, 16 px x 7 px
    # centre marks), scaled to this guide.
    scale = height / 256
    margin_x = int(cell["safe_margin_x"])
    crown_y, floor_y = int(cell["crown_y"]), int(cell["floor_y"])
    center = width // 2
    line, mark, half = max(1, round(5 * scale)), max(1, round(7 * scale)), round(8 * scale)
    image = Image.open(path).convert("RGB")
    draw = ImageDraw.Draw(image)
    for y, colour, accent in ((crown_y, CROWN_LINE, CROWN_MARK), (floor_y, FLOOR_LINE, FLOOR_MARK)):
        draw.line((margin_x, y, width - 1 - margin_x, y), fill=colour, width=line)
        draw.line((center - half, y, center + half, y), fill=accent, width=mark)
    image.save(path)
    return cell


def layout_guide_kind(value: bool | str | None) -> str | None:
    """Which guide `--layout-guide` asks for: True (the bare flag, a Python caller's bool) is the figure guide."""
    if value is True:
        return "figure"
    if value in (None, False):
        return None
    if value not in LAYOUT_GUIDE_KINDS:
        raise SystemExit(f"gen: unknown --layout-guide {value!r}; expected one of {', '.join(LAYOUT_GUIDE_KINDS)}")
    return str(value)


def _make_provider(name: str, *, keep_session: bool):
    if name == PROVIDER_CODEX:
        return CodexProvider(keep_session=keep_session)
    if name == PROVIDER_GROK:
        return GrokProvider()
    if name == PROVIDER_OPENAI:
        return OpenAIProvider()
    raise SystemExit(f"gen: unknown provider {name!r}; expected one of {', '.join(PROVIDERS)}")


# Why `auto` steps down to chroma when reference images are attached (2026-09-08
# 실측, plan sprite-gen/parts-rig): codex image_gen with `--ref` returned real
# alpha in 1/6 runs and drew a checkerboard (RGB) in 5/6, while the same prompts
# on a #00FF00 key + chroma keying succeeded 6/6. The edit path is not a reliable
# alpha source, so `auto` does not gamble on it — the decision is made before the
# model runs, printed, and recorded in the report (`alpha.strategy_source`).
# An explicit `--alpha-mode native` still forces it (and fails loud on RGB).
# The key planned this way is applied only to a raw that needs it: a raw that came
# back with a real transparent background anyway (`chroma.classify_raw_alpha`,
# 2026-10-04: a transparent `--ref` is answered with alpha) is published on its own
# alpha, measured as a native one (STRATEGY_SOURCE_REFS_RAW_ALPHA), because keying
# it again mattes the outline away. A checkerboard or key background is still keyed.
# Because the key is the engine's plan, the engine asks for it: a prompt that names no
# key background gets the chosen key's line (`chroma.KEY_BACKGROUND_TEXT`), since a ref
# prompt without one came back on white and keying white takes the outline with it.
STRATEGY_SOURCE_PROVIDER = "provider-default"
STRATEGY_SOURCE_REFS = "refs-attached"
STRATEGY_SOURCE_REFS_RAW_ALPHA = "refs-attached-raw-alpha"
STRATEGY_SOURCE_EXPLICIT = "explicit"


def resolve_transparency_strategy(backend, alpha_mode: str, *, refs: list[Path] | None = None) -> tuple[str, str]:
    """Decide which transparency strategy this generation runs.

    Returns (strategy, source). 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. `auto` on a native provider steps down to
    `chroma` when reference images are attached (see STRATEGY_SOURCE_REFS).
    """
    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:
        if declared == TRANSPARENCY_NATIVE and refs:
            return TRANSPARENCY_CHROMA, STRATEGY_SOURCE_REFS
        return declared, STRATEGY_SOURCE_PROVIDER
    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, STRATEGY_SOURCE_EXPLICIT


def _codex_available() -> tuple[bool, str]:
    """Is codex usable here? Returns (ok, reason_if_not), by `codex_provider.codex_login` —
    the one reading of how codex is signed in. Monkeypatchable in tests."""
    login = codex_provider.codex_login()
    return login.source is not None, login.reason


def resolve_default_provider() -> tuple[str, dict[str, str] | None]:
    """Resolve the provider to use when `--provider` is not given.

    Precedence: SPRITE_GEN_DEFAULT_PROVIDER env > hard default (codex). When the
    resolved default is codex but codex is not signed in here, it is what the user
    chose for that (`codex_unavailable`): the question, raised, or the chosen
    provider with the switch (from/to/cause/reason/default_source/chosen_by).
    Returns (provider, switch_or_None).

    An EXPLICIT_ONLY provider is never a default: not the hard default, not out of
    DEFAULT_PROVIDER_ENV. It comes out of here only as the user's own answer for a
    codex that cannot run.
    """
    configured = os.environ.get(DEFAULT_PROVIDER_ENV, "").strip()
    if configured:
        if configured not in PROVIDERS:
            raise SystemExit(
                f"gen: {DEFAULT_PROVIDER_ENV}={configured!r} is not a known provider; "
                f"expected one of {', '.join(PROVIDERS)}"
            )
        if configured in EXPLICIT_ONLY_PROVIDERS:
            raise SystemExit(
                f"gen: {DEFAULT_PROVIDER_ENV}={configured!r} is refused — {configured} bills per call "
                f"against an API key and is never a default: name it (`--provider {configured}`), or choose it "
                f"for when codex cannot run (`sprite-gen defaults save --codex-unavailable {configured}`). Use "
                f"{', '.join(p for p in PROVIDERS if p not in EXPLICIT_ONLY_PROVIDERS)} for a subscription route."
            )
        default, source = configured, DEFAULT_PROVIDER_ENV
    else:
        default, source = HARD_DEFAULT_PROVIDER, "hard-default"

    # Only a codex default turns into the user's choice. A grok default that is down
    # fails loud at generation time rather than reverse-falling back to codex.
    if default == PROVIDER_CODEX:
        ok, reason = _codex_available()
        if not ok:
            return codex_unavailable("login", reason, default_source=source)
    return default, None


def codex_unavailable_choice() -> tuple[str, str]:
    """What a default codex that cannot run turns into, and who said so: (choice, `CODEX_UNAVAILABLE_ENV` | `saved`
    | `default`). The environment first, then the saved preference (`workflow.preferences`, its general settings),
    then `ask`. Read only when codex cannot run, so a broken settings file stops nothing else."""
    configured = os.environ.get(CODEX_UNAVAILABLE_ENV, "").strip()
    if configured:
        if configured not in CODEX_UNAVAILABLE_CHOICES:
            raise SystemExit(f"gen: {CODEX_UNAVAILABLE_ENV}={configured!r} is not a choice; "
                             f"expected one of {', '.join(CODEX_UNAVAILABLE_CHOICES)}")
        return configured, CODEX_UNAVAILABLE_ENV
    # The settings owner imports this package (its catalog names the choices), so it is imported here.
    from sprite_gen.workflow.preferences import read_settings

    try:
        saved = read_settings()["general"].get(CODEX_UNAVAILABLE_SETTING)
    except (ValueError, OSError) as exc:
        raise SystemExit(f"gen: {exc}") from exc
    if saved:
        return saved, "saved"
    return CODEX_UNAVAILABLE_DEFAULT, "default"


def codex_unavailable(cause: str, reason: str, *, default_source: str) -> tuple[str, dict[str, str]]:
    """A default codex that cannot run (`cause` `login` or `usage-limit`, `reason` the reading's words), turned into
    the user's choice: raises the question (`CodexUnavailableAsk`) for `ask`, else returns the chosen provider and
    the switch the report keeps as `provider_fallback`."""
    choice, chosen_by = codex_unavailable_choice()
    if choice == CODEX_UNAVAILABLE_ASK:
        raise ask_codex_unavailable(codex_unavailable_question(cause, reason))
    return choice, {"from": PROVIDER_CODEX, "to": choice, "cause": cause, "reason": reason,
                    "default_source": default_source, "chosen_by": chosen_by}


def _announce_switch(verb: str, switch: dict[str, str]) -> None:
    print(f"sprite-gen {verb}: default provider '{switch['from']}' cannot run ({switch['reason']}) "
          f"{PROVIDER_SWITCH_WORDS} '{switch['to']}', the choice for when codex cannot run "
          f"({'saved with sprite-gen defaults' if switch['chosen_by'] == 'saved' else switch['chosen_by']}). "
          "Pass --provider to name one, or change the choice with `sprite-gen defaults save --codex-unavailable`.",
          file=sys.stderr, flush=True)


def run_on_default(verb: str, provider: str | None, call: Callable[[str, str, dict[str, str] | None], Any],
                   ) -> tuple[Any, str, dict[str, str] | None]:
    """`call(provider, resolved_from, switch)` on the provider `--provider` named, else on the default one: returns
    (its result, how the provider was chosen — `provider_resolved_from` — and the switch or None).

    The one place a call that names no provider is resolved (`gen`, `logo`). A default codex that is not signed in
    is the user's choice before anything runs (`resolve_default_provider`); one whose `codex exec` says its usage is
    used up (`codex_provider.CodexUsageLimit`) is the same choice where it is found, and `call` runs again on the
    chosen provider. A named provider runs as named: its usage limit is its failure."""
    if provider is not None:
        return call(provider, "explicit", None), "explicit", None
    provider, switch = resolve_default_provider()
    if switch:
        _announce_switch(verb, switch)
        resolved_from = f"fallback-from-{switch['from']}"
    elif os.environ.get(DEFAULT_PROVIDER_ENV, "").strip():
        resolved_from = DEFAULT_PROVIDER_ENV
    else:
        resolved_from = "hard-default"
    try:
        return call(provider, resolved_from, switch), resolved_from, switch
    except codex_provider.CodexUsageLimit as exc:
        provider, switch = codex_unavailable("usage-limit", exc.said, default_source=resolved_from)
        _announce_switch(verb, switch)
        resolved_from = f"fallback-from-{switch['from']}"
        return call(provider, resolved_from, switch), resolved_from, switch


def trim_to_alpha(path: Path, *, threshold: int = 8) -> dict[str, Any]:
    """Crop a transparent PNG in place to the bbox of its opaque pixels.

    A generated still carries an unpredictable band of empty alpha below the feet
    (and around the sides); two stills placed on the same floor line then stand at
    different heights. Trimming makes the image's bottom edge the ground-contact
    line, which is what every placement (scene, strip, runtime) anchors on. The
    subject is never cut — only fully transparent margin goes."""
    from PIL import Image

    with Image.open(path) as im:
        rgba = im.convert("RGBA")
        before = rgba.size
        box = rgba.getchannel("A").point(lambda v: 255 if v >= threshold else 0).getbbox()
        if box is None:
            raise SystemExit(f"gen: --trim-alpha: {path} is fully transparent; nothing to keep")
        cropped = rgba.crop(box)
        cropped.save(path)
    return {
        "bbox": list(box),
        "before": list(before),
        "after": list(cropped.size),
        "margin_px": {"left": box[0], "top": box[1], "right": before[0] - box[2], "bottom": before[1] - box[3]},
    }


def generate_image(
    provider: str,
    prompt: str,
    out: Path,
    *,
    refs: list[Path] | None = None,
    facing: str | None = None,
    facing_fix: str = "none",
    view: str | None = None,
    handed: list[handed_mod.Handed] | None = None,
    body_plan: list[Body] | None = None,
    model: str | None = None,
    aspect_ratio: str | None = None,
    quality: str | None = None,
    resolution: str | None = None,
    transparent: bool = False,
    alpha_mode: str = ALPHA_MODE_AUTO,
    chroma_key: str = MAGENTA,
    white_check: Path | None = None,
    trim_alpha: bool = False,
    keep_session: bool = False,
    workdir: Path | None = None,
    decontam: str = extract_mod.OFF,
    layout_guide: bool | str | None = False,
) -> GenResult:
    """Generate one image and return a GenResult. Raises SystemExit on any failure.

    `layout_guide`: "figure" (or True) attaches the one-slot figure guide."""
    guide_kind = layout_guide_kind(layout_guide)
    if decontam not in extract_mod.DECONTAM_MODES:
        raise SystemExit(f"gen: unknown --decontam {decontam!r}; expected off|auto|palette")
    if decontam == extract_mod.PALETTE and not transparent:
        raise SystemExit("gen: --decontam applies to the chroma key of a --transparent image; add --transparent")
    prompt = (prompt or "").strip()
    if not prompt:
        raise SystemExit("gen: empty prompt; pass --prompt or --prompt-file")
    if facing is not None:
        facing_mod.validate(facing, facing_fix)
    _check_view(view, facing, facing_fix, handed, body_plan)
    out = out.expanduser().resolve()
    refs = [Path(r).expanduser().resolve() for r in (refs or [])]
    for ref in refs:
        if not ref.is_file():
            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: str | None = None
    strategy_source: str | None = None
    if transparent:
        # The layout guide is an attached image as much as a --ref is: the same step down applies.
        attached_for_strategy = [*refs, Path(LAYOUT_GUIDE_NAME)] if guide_kind else refs
        strategy, strategy_source = resolve_transparency_strategy(backend, alpha_mode, refs=attached_for_strategy)
        if decontam == extract_mod.PALETTE and strategy != TRANSPARENCY_CHROMA:
            # before the provider is called: a paid generation must not end in this refusal
            raise SystemExit(f"gen: --decontam removes a chroma key; this image would use {strategy} alpha "
                             "(pass --alpha-mode chroma to key it instead)")
    # The key is the engine's plan when `auto` stepped down for the refs, so the engine asks for it: a
    # ref prompt with no key background is answered on white or another light ground, and keying that
    # takes the outline and light fills with it (2026-10-04). A key the prompt already names stays.
    parts = still_prompt(prompt, view=view, facing=facing, handed=handed, body_plan=body_plan, refs=bool(refs),
                         key=chroma_key if strategy_source == STRATEGY_SOURCE_REFS else None,
                         layout=layout_guide_cell(aspect_ratio) if guide_kind == "figure" else None)
    prompt = parts.text
    for line in prompt_parts.note_lines(parts):
        print(f"[gen] {line}", file=sys.stderr)
    key_background: dict[str, Any] | None = None
    if (key_piece := parts.piece("key-background")) is not None:
        key_background = {"injected": key_piece.added, "key": key_piece.found or chroma_key}
        print(
            f"[gen] {len(refs)} reference image(s) attached — using chroma keying instead of "
            f"{backend.name}'s native alpha (native output with refs is unstable, 2026-09-08); "
            + (f"added a {chroma_key} key background line to the prompt; " if key_piece.added
               else f"the prompt already asks for a {key_piece.found} key background; ")
            + "a result that already has a transparent background keeps its own alpha. "
            "Pass --alpha-mode native to force it.",
            file=sys.stderr,
        )
    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:
        guide_cell: dict[str, Any] | None = None
        attached = list(refs)
        if guide_kind:
            guide = workdir / LAYOUT_GUIDE_NAME
            guide_cell = draw_layout_guide(guide, aspect_ratio)
            # Last, so "the last attached image" in the prompt is the guide whatever the caller attached.
            attached.append(guide)
        request = GenRequest(
            prompt=prompt,
            raw=raw,
            refs=attached,
            model=model,
            aspect_ratio=aspect_ratio,
            quality=quality,
            resolution=resolution,
            native_alpha=strategy == TRANSPARENCY_NATIVE,
        )
        # 타임아웃 1회 관측 가능 재시도 — 산발 provider 스톨은 같은 호출 재시도로
        # 대부분 통과한다 (회귀 2026-07-19). 두 번째도 스톨이면 fail loud.
        try:
            run = backend.generate(request, workdir)
        except GenTimeoutError as exc:
            print(f"[gen] {exc} — retrying once", file=sys.stderr)
            run = backend.generate(request, workdir)
        verify_png(raw)
        facing_report = None
        if refs and facing is not None:
            request, run, facing_report = facing_mod.prepare_correction(
                backend, request, run, workdir, facing=facing, fix=facing_fix, mirror_ok=not handed)
            raw = request.raw
        raw_bytes = verify_png(raw)

        # Only the key `auto` planned because of the refs is checked against the raw; an
        # explicit --alpha-mode chroma is the caller's own key and runs as asked.
        raw_alpha: dict[str, Any] | None = None
        decontam_skipped: dict[str, Any] | None = None
        if strategy_source == STRATEGY_SOURCE_REFS:
            raw_alpha = chroma_mod.classify_raw_alpha(raw)
            if raw_alpha["verdict"] == chroma_mod.RAW_ALPHA_REAL:
                if decontam != extract_mod.OFF:
                    # The generation is paid for and its alpha is good: decontam has no key to
                    # remove, so it is skipped and said, not refused (see the refusal before the call).
                    decontam_skipped = {
                        "requested": decontam,
                        "skipped": f"the raw came back with a transparent background "
                                   f"({raw_alpha['alpha_zero_pct']}% alpha 0) and has no key to remove",
                    }
                    print(f"[gen] {'warning: ' if decontam == extract_mod.PALETTE else ''}--decontam {decontam} skipped: "
                          f"{decontam_skipped['skipped']}", file=sys.stderr)
                strategy, strategy_source = TRANSPARENCY_NATIVE, STRATEGY_SOURCE_REFS_RAW_ALPHA
                print(
                    f"[gen] the raw came back with a transparent background ({raw_alpha['alpha_zero_pct']}% "
                    f"alpha 0, {raw_alpha['border_alpha_zero_pct']}% of the border) — publishing its own "
                    "alpha instead of keying it.",
                    file=sys.stderr,
                )
            elif raw_alpha["verdict"] == chroma_mod.RAW_ALPHA_AMBIGUOUS:
                raw_alpha["warning"] = (
                    f"the raw has some transparent pixels ({raw_alpha['alpha_zero_pct']}% alpha 0, "
                    f"{raw_alpha['border_alpha_zero_pct']}% of the border) but not a transparent background "
                    f"(needs {chroma_mod.RAW_ALPHA_MIN_ZERO_PCT}% and {chroma_mod.RAW_ALPHA_MIN_BORDER_ZERO_PCT}% "
                    "of the border); keyed as planned — check the outline, or pass --alpha-mode native"
                )
                print(f"[gen] warning: {raw_alpha['warning']}", file=sys.stderr)
        ref_stats = {
            **({"key_background": key_background} if key_background is not None else {}),
            **({"raw_alpha": raw_alpha} if raw_alpha is not None else {}),
            **({"decontam": decontam_skipped} if decontam_skipped is not None else {}),
        }

        chroma_stats: dict[str, Any] | None = None
        alpha_stats: dict[str, Any] | None = None
        out.parent.mkdir(parents=True, exist_ok=True)
        if strategy == TRANSPARENCY_NATIVE:
            alpha_stats = {
                "strategy": TRANSPARENCY_NATIVE,
                "strategy_source": strategy_source,
                **ref_stats,
                **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,
                                                      decontam=decontam)
            alpha_stats = {"strategy": TRANSPARENCY_CHROMA, "strategy_source": strategy_source,
                           **ref_stats, **chroma_stats}
        else:
            shutil.copyfile(raw, out)
        verify_png(out)
        if facing_report and (facing_report["action"] == "mirror" or facing_report.get("fallback") == "mirror"):
            facing_mod.mirror(out)
            if white_check is not None and transparent:
                facing_mod.mirror(white_check)
        trim_stats: dict[str, Any] | None = None
        if trim_alpha:
            if not transparent:
                raise SystemExit("gen: --trim-alpha needs --transparent (there is no alpha to trim on an opaque image)")
            trim_stats = trim_to_alpha(out)

        # Preserve the pre-chroma raw next to the destination for auditability.
        raw_keep = out.with_suffix(out.suffix + ".raw.png")
        shutil.copyfile(raw, raw_keep)

        return GenResult(
            provider=run.provider,
            prompt=prompt,
            out=out,
            raw=raw_keep,
            raw_bytes=raw_bytes,
            elapsed_seconds=run.elapsed_seconds,
            model=run.model,
            session_id=run.session_id,
            refs=refs,
            transparent=transparent,
            alpha=alpha_stats,
            chroma=chroma_stats,
            extra={**run.extra, **({"trim_alpha": trim_stats} if trim_stats else {}),
                   **({"facing": facing_report} if facing_report else {}),
                   **({"view": {"direction": view, "facing": facing if view in handed_mod.LATERAL_VIEWS else None,
                                "handed": [vars(h) for h in handed or []],
                                **({"body_plan": [vars(b) for b in body_plan]} if body_plan else {})}} if view else {}),
                   **({"layout_guide": guide_cell} if guide_cell else {}),
                   **({"prompt_notes": parts.notes} if parts.notes else {})},
        )
    finally:
        if owns_workdir:
            shutil.rmtree(workdir, ignore_errors=True)


def _check_view(view: str | None, facing: str | None, facing_fix: str, handed: list[handed_mod.Handed] | None,
                body_plan: list[Body] | None = None) -> None:
    """Refuse a `--direction` / `--facing` / `--handed` / `--body-plan` combination that cannot be drawn, before
    anything runs."""
    if view is None:
        if handed:
            raise SystemExit("gen: --handed needs --direction: where an item shows depends on the view")
        if body_plan:
            raise SystemExit("gen: --body-plan needs --direction: it changes the view sentence, which only "
                             "--direction adds")
        return
    handed_mod.validate_view(view, facing)
    if view not in handed_mod.LATERAL_VIEWS and facing is not None:
        raise SystemExit(f"gen: the {view} view is not turned to a side; drop --facing")
    if handed and facing_fix == "mirror":
        raise SystemExit("gen: --facing-fix mirror turns the picture over and moves every --handed item to the other "
                         "side; use regen (it never mirrors with --handed) or none")


def still_prompt(prompt: str, *, view: str | None = None, facing: str | None = None,
                 handed: list[handed_mod.Handed] | None = None, body_plan: list[Body] | None = None,
                 refs: bool = False, key: str | None = None,
                 layout: dict[str, Any] | None = None) -> prompt_parts.Prompt:
    """The prompt a still is drawn from: the caller's text, then the engine's pieces (`prompt_parts.Prompt.add`;
    without `handed` or `body_plan`, 2.22.0's prompt to the byte). In order:

    - `view` (`--direction`): the sentence for drawing the still at that view, turned to `facing` (the side and
      diagonal views; a `body_plan` that is not one biped gets it without the feet, chest, hips, shoulders and
      shoes and with what it stands on, `still_view_text`), then where each `handed` item is in it
      (`handedness.text`);
    - with `refs` and a `facing`: the turn over the reference (`facing.prompt_suffix`);
    - `key` (green / magenta, a ref run `auto` planned to key): the key background line, unless the prompt
      names a key background already;
    - `layout` (the `--layout-guide` cell): where the guide's lines are.
    """
    figures = body_mod.figures(body_plan)
    parts = prompt_parts.Prompt(prompt, caller=f"{prompt} {figures}" if figures else None)
    if view is not None:
        # The view sentences are the video pipeline's (a still is drawn for the clip that starts from it).
        from sprite_gen.video.batch import still_view_text

        text = still_view_text(view, facing or "right", body_plan)
        parts.add("view", text[0].upper() + text[1:] + ".", facing=facing or prompt_parts.NO_TURN)
        if handed:
            parts.add("handed", handed_mod.text(handed, view, facing), sep=" ", handed=handed)
    if refs and facing is not None:
        parts.add("facing", facing_mod.prompt_suffix(facing), facing=facing)
    if key is not None:
        parts.add("key-background", chroma_mod.KEY_BACKGROUND_TEXT[key], key=key)
    if layout is not None:
        parts.add("layout", layout_guide_text(layout))
    return parts


def _run(args: argparse.Namespace) -> int:
    prompt = args.prompt
    if args.prompt_file:
        prompt = Path(args.prompt_file).expanduser().read_text(encoding="utf-8")
    result, resolved_from, fallback = run_on_default("gen", args.provider, lambda provider, *_: generate_image(
        provider,
        prompt or "",
        args.out,
        refs=args.ref,
        facing=None if args.facing == "preserve" else args.facing,
        facing_fix=args.facing_fix,
        view=getattr(args, "direction", None),
        handed=handed_mod.parse_all(list(getattr(args, "handed", None) or [])) or None,
        body_plan=body_mod.parse_all(list(getattr(args, "body_plan", None) or [])) or None,
        model=args.model,
        aspect_ratio=args.aspect_ratio,
        quality=args.quality,
        resolution=args.resolution,
        transparent=args.transparent,
        alpha_mode=args.alpha_mode,
        chroma_key=args.chroma_key,
        white_check=args.white_check,
        trim_alpha=bool(getattr(args, "trim_alpha", False)),
        keep_session=args.keep_session,
        workdir=args.workdir,
        decontam=str(getattr(args, "decontam", None) or extract_mod.OFF),
        layout_guide=getattr(args, "layout_guide", None),
    ))
    payload = result.to_dict()
    # `provider` in the payload is always the backend that actually generated the
    # image; `provider_resolved_from` records HOW it was chosen and
    # `provider_fallback` records the switch from a codex that could not run to the
    # provider the user chose for that (No Silent Fallback — the report names which
    # provider was used and why).
    payload["provider_resolved_from"] = resolved_from
    if fallback:
        payload["provider_fallback"] = fallback
    if args.report:
        report_path = Path(args.report).expanduser().resolve()
        atomic_write_text(report_path, json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
        payload["report"] = str(report_path)
    print_json(payload)
    return 0


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="sprite-gen gen", description=__doc__)
    add_arguments(parser)
    return parser


def add_arguments(parser: argparse.ArgumentParser) -> None:
    parser.add_argument(
        "--provider",
        choices=PROVIDERS,
        default=None,
        help=(
            f"generation backend; default resolves via {DEFAULT_PROVIDER_ENV} env "
            "then codex. A default codex that cannot run (not signed in, or its usage used up) "
            f"asks (exit {CODEX_UNAVAILABLE_EXIT}) or runs what was chosen for that "
            f"(`sprite-gen defaults save --codex-unavailable`, {CODEX_UNAVAILABLE_ENV}). "
            "codex and grok run on a subscription login; openai is for servers and SaaS "
            "and is billed per call on OPENAI_API_KEY, so it runs only when chosen"
        ),
    )
    parser.add_argument("--prompt")
    parser.add_argument("--prompt-file", type=Path)
    parser.add_argument("--out", required=True, type=Path)
    parser.add_argument("--ref", action="append", type=Path, default=[], help="reference image (repeatable)")
    parser.add_argument("--model")
    parser.add_argument("--aspect-ratio", help="grok and openai, e.g. 1:1 16:9 9:16 (openai maps it to a gpt-image size; codex ignores it)")
    parser.add_argument(
        "--quality",
        choices=QUALITIES,
        default=None,
        help=(
            "rendering effort billed for this image; openai carries the whole range "
            "(low..max, auto = the model decides) and grok takes low / medium / auto. "
            "Omitted = the provider's own default. A provider that cannot honour the "
            "level fails instead of downgrading it"
        ),
    )
    parser.add_argument(
        "--resolution",
        choices=RESOLUTIONS,
        default=None,
        help=(
            "output size tier, priced together with --quality: grok Imagine's "
            "1k / 1.5k / 2k (tier names, not pixel counts — 1.5k renders 1408px at 1:1). "
            "Omitted = the provider's own default (grok: 1k). openai sizes from "
            "--aspect-ratio and codex from neither, so both refuse this flag "
            "instead of ignoring it"
        ),
    )
    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 and openai asks for background=transparent (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 "
            "(native on codex and openai, but chroma whenever --ref is attached — native alpha with refs is unstable — "
            "with the --chroma-key background line added to a prompt that names no key); "
            "chroma forces chroma keying (e.g. a codex prompt that already carries a key background); "
            "native forces native alpha and is refused on a provider that cannot return alpha"
        ),
    )
    parser.add_argument(
        "--decontam",
        choices=extract_mod.DECONTAM_MODES,
        default=extract_mod.OFF,
        help="chroma keying: re-explain key-tinted edges (hair strands, outlines) with the subject's own "
        "colours after the matte. off (default) publishes the matte as it is; auto runs it where it "
        "applies (chroma strategy, a subject interior); palette demands it",
    )
    parser.add_argument("--chroma-key", choices=sorted(chroma_mod.KEYS), default=MAGENTA)
    parser.add_argument("--facing", choices=(*facing_mod.FACINGS, "preserve"), default="preserve", help="with --ref: required direction; preserve (default) leaves prompt and pixels unchanged")
    parser.add_argument("--facing-fix", choices=facing_mod.FIXES, default="none", help="with --ref and --facing: record only (none, default), or opt into mirror / one regen")
    parser.add_argument("--direction", choices=handed_mod.VIEWS, help="draw the still at this sprite view: the engine's view sentence is added to the prompt (side and diagonal views also take --facing right|left)")
    parser.add_argument("--handed", action="append", default=[], metavar="ITEM=SIDE [PART]", help="with --direction: an asymmetric item on one of the character's own sides, e.g. 'the black smartwatch=left wrist' (repeatable); the prompt says where it is in this view, and the still is never mirrored")
    parser.add_argument("--body-plan", action="append", default=[], metavar="PLAN | FIGURE=PLAN", help="with --direction: what the character stands on, biped (default), quadruped or legless; a scene of several figures names each, e.g. 'the man=biped' 'the horse=quadruped' (repeatable): the view sentence names no part the body lacks, as video-set --body-plan")
    parser.add_argument("--trim-alpha", action="store_true", help="with --transparent: crop the published PNG to its opaque bbox so the bottom edge is the foot line (margins reported)")
    parser.add_argument(
        "--layout-guide",
        nargs="?",
        const="figure",
        choices=LAYOUT_GUIDE_KINDS,
        default=None,
        help=(
            "attach a layout guide after any --ref. Bare or `figure`: a one-slot guide (frame, inner safe "
            "area at the row guide's 9.4 %% margin, center line) asking for the whole subject inside the "
            "safe area, with room above the head and below the feet; drawn for --aspect-ratio, square "
            "without one"
        ),
    )
    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")
    parser.add_argument("--report", type=Path, help="write the generation report JSON here")
    parser.add_argument("--workdir", type=Path, help="reuse this working dir instead of a temp dir")


def run(**kwargs: object) -> int:
    return _run(namespace_from_kwargs(_build_parser(), kwargs))


def main(argv: list[str] | None = None) -> int:
    utf8_streams()
    return _run(_build_parser().parse_args(argv))


if __name__ == "__main__":
    raise SystemExit(main())