Skip to content

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

33.6 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Curation-view display contract (run-contract.md §3/§4): imported `_base`/`_refs`
sources surface as the base row + generation-material chips, the self-report `contract`
field is populated, and filenames with URL-special characters are percent-encoded so
they actually serve (regression: an unencoded `#` in a ref filename became a URL
fragment → 404)."""

from __future__ import annotations

import json
import shutil
import subprocess
import sys
import threading
import urllib.request
from functools import partial
from http.server import ThreadingHTTPServer
from pathlib import Path

import pytest
from PIL import Image

ROOT = Path(__file__).resolve().parents[2]

from sprite_gen.serve.serve_curation import CurationHandler, _url, build_run_state  # noqa: E402
from sprite_gen.frames.unpack_atlas import import_png_groups  # noqa: E402


def _png(path: Path, color=(80, 80, 80, 255), size=(48, 48)) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    Image.new("RGBA", size, color).save(path)


def _build_import(tmp_path: Path, ref_names, with_base=True) -> Path:
    pngs = tmp_path / "pngs"
    if with_base:
        _png(pngs / "_base" / "hero.png", size=(96, 96))
    _png(pngs / "items" / "1-a.png")
    _png(pngs / "items" / "2-b.png")
    for name in ref_names:
        _png(pngs / "items" / "_refs" / name)
    out = tmp_path / "run"
    import_png_groups(
        out,
        [{
            "name": "items",
            "paths": sorted((pngs / "items").glob("*.png")),
            "labels": [],
            "refs": sorted((pngs / "items" / "_refs").glob("*.png")),
        }],
        base_src=(pngs / "_base" / "hero.png") if with_base else None,
    )
    return out


def _serve_status(run: Path, url: str) -> int:
    CurationHandler.run_dir = run
    CurationHandler.lang = "en"
    srv = ThreadingHTTPServer(("127.0.0.1", 0), partial(CurationHandler))
    threading.Thread(target=srv.serve_forever, daemon=True).start()
    try:
        return urllib.request.urlopen(f"http://127.0.0.1:{srv.server_address[1]}{url}").status
    finally:
        srv.shutdown()


def test_imported_sources_expose_base_row_and_chips(tmp_path):
    run = _build_import(tmp_path, ["anchor-idle.png", "guide-walk.png"])
    st = build_run_state(run)
    assert st["baseUrl"] == "/run/base-source.png"
    roles = {(r["role"], r["name"]) for r in st["states"][0]["refs"]}
    assert ("anchor", "anchor-idle.png") in roles
    assert ("guide", "guide-walk.png") in roles
    assert st["contract"] == {"base": True, "refs": True, "refsStates": 1, "grid": True, "sourceless": False}


def test_sourceless_import_is_reported(tmp_path):
    run = _build_import(tmp_path, [], with_base=False)
    st = build_run_state(run)
    assert st["baseUrl"] is None
    assert st["states"][0]["refs"] == []
    assert st["contract"]["sourceless"] is True


def _checker_png(path: Path, pitch: int = 4, size: int = 48) -> None:
    """A checkerboard PNG with a `pitch`-px block size so detect_pixel_pitch finds a grid."""
    path.parent.mkdir(parents=True, exist_ok=True)
    im = Image.new("RGBA", (size, size), (0, 0, 0, 255))
    px = im.load()
    for y in range(size):
        for x in range(size):
            if ((x // pitch) + (y // pitch)) % 2 == 0:
                px[x, y] = (240, 240, 240, 255)
    im.save(path)


def test_special_char_state_name_keeps_pixel_grid(tmp_path):
    """A special-char group/state name must not break auto pixel-grid measurement. The
    frame url is percent-encoded for HTTP, but pixelScale is measured from the real
    decoded file path (regression: measuring off the encoded url silently null-ed the
    grid + reported contract.grid=false for special-char imports)."""
    pngs = tmp_path / "pngs"
    _checker_png(pngs / "walk" / "1-a.png")
    _checker_png(pngs / "walk #한글 %" / "1-a.png")  # same image, special-char group name
    out = tmp_path / "run"
    assert _run_import(pngs, out, "--force").returncode == 0
    st = build_run_state(out)
    plain = next(s for s in st["states"] if s["name"] == "walk")
    special = next(s for s in st["states"] if s["name"] == "walk #한글 %")
    assert plain["pixelScale"] is not None
    assert special["pixelScale"] == plain["pixelScale"]  # measured, not silently null
    assert st["contract"]["grid"] is True
    url = special["frames"][0]["url"]  # frame url still percent-encoded + serves
    assert "#" not in url and " " not in url
    assert _serve_status(out, url) == 200


def test_special_char_ref_filename_is_url_encoded_and_serves(tmp_path):
    # One name carries each character that breaks a URL — `#` (a fragment), a space, `%` (an escape)
    # and a non-ASCII letter: they all go through the one `_url` quote and the one handler unquote.
    run = _build_import(tmp_path, ["guide-a#b c-100%done-café.png"])
    url = build_run_state(run)["states"][0]["refs"][0]["url"]
    # nothing that breaks a URL (# → fragment) or an HTML attribute may survive raw
    assert not any(c in url for c in '# "\'<>')
    assert _serve_status(run, url) == 200


def test_url_helper_encodes_only_unsafe_segments():
    assert _url("run", "raw", "down_idle.png") == "/run/raw/down_idle.png"  # unreserved unchanged
    assert _url("run", "a b#c.png") == "/run/a%20b%23c.png"
    assert _url("frames", "down_walk", "frame-0.png") == "/frames/down_walk/frame-0.png"


def _run_import(pngs: Path, out: Path, *extra: str) -> subprocess.CompletedProcess[str]:
    return subprocess.run(
        [sys.executable, str(ROOT / "scripts" / "unpack_atlas_run.py"),
         "--pngs-dir", str(pngs), "--out-dir", str(out), *extra],
        capture_output=True, encoding="utf-8",
    )


def test_force_reimport_is_a_clean_rebuild(tmp_path):
    """--force re-import must not leave stale source truth (Idempotency/SSoT)."""
    pngs = tmp_path / "pngs"
    _png(pngs / "_base" / "b.png", size=(96, 96))
    _png(pngs / "items" / "1-a.png")
    _png(pngs / "items" / "_refs" / "anchor-x.png")
    out = tmp_path / "run"
    r1 = _run_import(pngs, out, "--force")
    assert r1.returncode == 0, r1.stderr
    assert (out / "base-source.png").is_file()
    assert (out / "references" / "imported" / "items" / "anchor-x.png").is_file()
    # remove both sources from the input, re-import into the SAME out-dir
    shutil.rmtree(pngs / "_base")
    shutil.rmtree(pngs / "items" / "_refs")
    r2 = _run_import(pngs, out, "--force")
    assert r2.returncode == 0, r2.stderr
    assert not (out / "base-source.png").exists()          # stale base gone
    assert not (out / "references" / "imported").exists()  # stale refs gone
    prov = json.loads((out / "unpack-source.json").read_text())
    assert prov["base_source"] is None and prov["imported_refs"] == {}
    st = build_run_state(out)
    assert st["baseUrl"] is None and st["contract"]["sourceless"] is True


def test_unknown_ref_role_fails_loud(tmp_path):
    """A _refs file with an unknown role prefix is rejected, not relabeled to guide."""
    pngs = tmp_path / "pngs"
    _png(pngs / "items" / "1-a.png")
    _png(pngs / "items" / "_refs" / "mystery-source.png")
    out = tmp_path / "run"
    r = _run_import(pngs, out, "--force")
    assert r.returncode != 0
    combined = r.stderr + r.stdout
    assert "mystery-source.png" in combined
    assert "anchor-/basis-/guide-" in combined
    assert not out.exists() or not (out / "references" / "imported").exists()


def _snapshot(run: Path) -> dict:
    return {p.relative_to(run): p.read_bytes()
            for p in run.rglob("*") if p.is_file() and p.name != ".sprite-gen.lock"}


def test_force_reimport_failure_preserves_prior_run(tmp_path):
    """A failed --force re-import must leave the prior valid run byte-intact (Atomicity:
    a rebuild fully succeeds or rolls back — never clear-then-fail)."""
    pngs = tmp_path / "pngs"
    _png(pngs / "_base" / "b.png", size=(96, 96))
    _png(pngs / "items" / "1-a.png")
    _png(pngs / "items" / "_refs" / "anchor-x.png")
    out = tmp_path / "run"
    assert _run_import(pngs, out, "--force").returncode == 0
    before = _snapshot(out)
    assert (out / "base-source.png").is_file() and before  # a real prior run exists
    # make the next import invalid (unknown role) and re-run --force → must fail...
    _png(pngs / "items" / "_refs" / "mystery-source.png")
    r = _run_import(pngs, out, "--force")
    assert r.returncode != 0
    # ...and the prior run must be untouched (not destroyed / emptied), no staging leak
    assert _snapshot(out) == before
    assert not (out.parent / f".{out.name}.sg-staging").exists()


def test_publish_phase_failure_rolls_back(tmp_path, monkeypatch):
    """If a publish move fails mid-swap, the prior run is rolled back byte-intact, no
    partial new run is exposed, and staging/backup are cleaned."""
    import pathlib

    from sprite_gen.frames import unpack_atlas as ua

    pngs = tmp_path / "pngs"
    _png(pngs / "items" / "1-a.png")
    out = tmp_path / "run"
    assert _run_import(pngs, out, "--force").returncode == 0
    before = _snapshot(out)
    _png(pngs / "items" / "2-b.png")  # a real change the re-import would publish

    orig_rename = pathlib.Path.rename

    def flaky(self, target):
        if ".sg-staging" in str(self):  # moving new content out of staging into out_dir
            raise OSError("injected publish failure")
        return orig_rename(self, target)

    monkeypatch.setattr(pathlib.Path, "rename", flaky)
    with pytest.raises((OSError, SystemExit)):
        ua.run(pngs_dir=pngs, out_dir=out, force=True)
    assert _snapshot(out) == before                             # prior run byte-intact
    assert not (out.parent / f".{out.name}.sg-staging").exists()  # staging cleaned
    assert not (out / ".sg-backup").exists()                    # in-place backup cleaned


def test_publish_never_removes_out_dir(tmp_path, monkeypatch):
    """out_dir (and the lock inside it) must never disappear during publish, so a
    concurrent writer cannot mkdir+lock the run path mid-swap (Isolation)."""
    import pathlib

    from sprite_gen.frames import unpack_atlas as ua

    pngs = tmp_path / "pngs"
    _png(pngs / "items" / "1-a.png")
    out = tmp_path / "run"
    assert _run_import(pngs, out, "--force").returncode == 0
    from sprite_gen.spec.runio import LOCK_FILENAME
    _png(pngs / "items" / "2-b.png")

    orig_rename = pathlib.Path.rename
    vanished = {"path": False, "lock": False}

    def watch(self, target):
        # check both before and after every rename that happens during the publish
        for _ in range(1):
            if not out.exists():
                vanished["path"] = True
            elif not (out / LOCK_FILENAME).exists():
                vanished["lock"] = True
        r = orig_rename(self, target)
        if not out.exists():
            vanished["path"] = True
        elif not (out / LOCK_FILENAME).exists():
            vanished["lock"] = True
        return r

    monkeypatch.setattr(pathlib.Path, "rename", watch)
    assert ua.run(pngs_dir=pngs, out_dir=out, force=True) == 0
    assert not vanished["path"], "out_dir vanished during publish (isolation window)"
    assert not vanished["lock"], "run-dir lock vanished during publish (isolation window)"
    # the new run published cleanly
    assert (out / "frames" / "items" / "frame-1.png").is_file()


def test_api_run_reader_isolated_from_concurrent_publish(tmp_path):
    """build_run_state reads under read_guard, so it blocks while a publish holds the
    exclusive publish_guard and returns a COMPLETE snapshot — never a mid-publish 500 or
    old/new mix (reader isolation)."""
    import threading
    import time

    from sprite_gen.serve.serve_curation import build_run_state
    from sprite_gen.spec import runio

    pngs = tmp_path / "pngs"
    _png(pngs / "items" / "1-a.png")
    run = tmp_path / "run"
    assert _run_import(pngs, run, "--force").returncode == 0

    outcome: dict = {}
    ready = threading.Event()

    def reader():
        ready.wait()
        try:
            st = build_run_state(run)  # read_guard SH -> blocks under the publish EX lock
            outcome["states"] = len(st["states"])
        except Exception as exc:  # a mid-publish read would raise / 500
            outcome["err"] = repr(exc)
        outcome["at"] = time.monotonic()

    th = threading.Thread(target=reader)
    th.start()
    with runio.publish_guard(run):          # simulate a publish holding the exclusive lock
        ready.set()
        time.sleep(0.25)                     # reader must be blocked for this whole window
        assert "at" not in outcome, "reader was not blocked by publish_guard (no isolation)"
        released_at = time.monotonic()
    th.join(3)
    assert "err" not in outcome, outcome.get("err")
    assert outcome.get("states"), "reader got no complete snapshot"
    assert outcome["at"] >= released_at, "reader returned before the publish released"


def test_import_fails_loud_on_multiple_base_images(tmp_path):
    """`_base/` is the run's single identity image; multiple images must fail loud, not silently
    pick the first (identity SSoT / No Silent Fallback)."""
    from conftest import run_script  # noqa: F401  (ensures scripts path is set up like siblings)

    pngs = tmp_path / "pngs"
    _png(pngs / "_base" / "a.png")
    _png(pngs / "_base" / "b.png")
    _png(pngs / "items" / "1-x.png")

    r = _run_import(pngs, tmp_path / "run", "--force")
    assert r.returncode != 0, "import silently picked one of several _base images"
    assert "_base" in (r.stdout + r.stderr).lower()


def test_serve_run_state_scaffolds_absent_but_fails_loud_on_broken_manifest(fixture_run_dir):
    """serve build_run_state serves the request/state scaffold when the manifest is ABSENT (a run
    with no generation yet — legitimate), but a present-but-broken `{}` manifest fails loud
    (surfaces as HTTP 500 in do_GET), never a silent empty-rows view (No Silent Fallback)."""
    from conftest import run_script

    run = fixture_run_dir
    st = build_run_state(run)                     # absent manifest -> scaffold from request states
    assert st["states"], "scaffold should list the run's states even before extraction"

    assert run_script("extract_sprite_row_frames.py", "--run-dir", str(run)).returncode == 0
    (run / "frames" / "frames-manifest.json").write_text("{}", encoding="utf-8")
    with pytest.raises(SystemExit):               # present-but-broken -> fail loud (do_GET -> 500)
        build_run_state(run)


@pytest.mark.parametrize("modname,kwargs", [
    ("sprite_gen.qa.preview", {}),
    ("sprite_gen.compose.compose_gif", {}),
    ("sprite_gen.compose.compose_cycle", {"state": "walk", "name": "cyc"}),
])
def test_finished_consumer_reader_isolated_from_concurrent_publish(fixture_run_dir, modname, kwargs):
    """preview / run-dir compose_gif / compose_cycle read the manifest + curation + frame tree under
    one shared read_guard, so they block during a concurrent publish swap and never observe a
    mid-swap (missing/partial) generation — same reader-isolation contract as serve/inspect."""
    import importlib
    import threading
    import time

    from conftest import run_script
    from sprite_gen.spec import runio

    run = fixture_run_dir
    assert run_script("extract_sprite_row_frames.py", "--run-dir", str(run)).returncode == 0
    mod = importlib.import_module(modname)

    outcome: dict = {}
    ready = threading.Event()

    def reader():
        ready.wait()
        try:
            mod.run(run_dir=run, **kwargs)   # read_guard SH -> blocks under the publish EX lock
            outcome["ok"] = True
        except Exception as exc:  # a mid-swap read would raise
            outcome["err"] = repr(exc)
        outcome["at"] = time.monotonic()

    th = threading.Thread(target=reader)
    th.start()
    with runio.publish_guard(run):           # model an extract commit holding the exclusive lock
        ready.set()
        time.sleep(0.25)
        assert "at" not in outcome, f"{modname} did not block on read_guard during a publish"
        released_at = time.monotonic()
    th.join(20)
    assert "err" not in outcome, outcome.get("err")
    assert outcome.get("ok"), f"{modname} did not complete after the publish released"
    assert outcome["at"] >= released_at, f"{modname} returned before the publish released"


def test_inspect_reader_isolated_from_concurrent_commit(fixture_run_dir):
    """inspect_run reads frames-manifest.json + extract-failure.json together under read_guard,
    so it blocks while an extract commit holds the exclusive publish_guard and never observes a
    newly-swapped frames generation beside a stale failure record (the correction loop reads
    through inspect_run, so its diagnostics stay isolated from a concurrent commit)."""
    import threading
    import time

    from conftest import run_script
    from sprite_gen.spec import runio
    from sprite_gen.qa.inspect import inspect_run

    run = fixture_run_dir
    assert run_script("extract_sprite_row_frames.py", "--run-dir", str(run)).returncode == 0

    outcome: dict = {}
    ready = threading.Event()

    def reader():
        ready.wait()
        try:
            rep = inspect_run(run, states="all")  # read_guard SH -> blocks under the publish EX lock
            outcome["states"] = len(rep["rows"])
        except Exception as exc:  # a mid-commit read would raise / see a torn snapshot
            outcome["err"] = repr(exc)
        outcome["at"] = time.monotonic()

    th = threading.Thread(target=reader)
    th.start()
    with runio.publish_guard(run):            # simulate an extract commit holding the exclusive lock
        ready.set()
        time.sleep(0.25)
        assert "at" not in outcome, "inspect reader was not blocked by publish_guard (no isolation)"
        released_at = time.monotonic()
    th.join(5)
    assert "err" not in outcome, outcome.get("err")
    assert outcome.get("states"), "inspect reader got no snapshot"
    assert outcome["at"] >= released_at, "inspect returned before the commit released"


def test_publish_guards_fail_loud_without_a_lock_backend(tmp_path, monkeypatch):
    """Where advisory locks can't be established, read_guard/publish_guard must
    RAISE, not degrade to a no-op. A no-op guard is a failover that changes canonical truth
    (a reader could see a half-published run), which the isolation contract forbids — so the
    guarded code refuses to run rather than serve/publish a partial run."""
    from sprite_gen.spec import runio

    run = tmp_path / "run"
    run.mkdir()
    monkeypatch.setattr(runio, "_LOCK_IMPL", None)

    for guard in (runio.read_guard, runio.publish_guard):
        with pytest.raises(runio.RWLockUnavailable):
            with guard(run):
                pass  # pragma: no cover - the guard must raise before yielding


def test_stale_curation_post_rejected_across_run_generations(tmp_path):
    """A curation autosave must echo the runRevision it was loaded with. A `--force`
    re-import — even one keeping the SAME state name but swapping the candidate images —
    changes the run generation, so an old-session POST is rejected (409) and never applied;
    a POST echoing the current revision saves (200) (Consistency: run identity, not just
    state membership; observable, not a silent overwrite)."""
    import json as _json
    import threading
    import urllib.error
    import urllib.request
    from functools import partial
    from http.server import ThreadingHTTPServer

    from sprite_gen.serve.serve_curation import CurationHandler

    pngs = tmp_path / "pngs"
    _png(pngs / "items" / "1-a.png", color=(200, 0, 0, 255))
    _png(pngs / "items" / "2-b.png", color=(0, 200, 0, 255))
    out = tmp_path / "run"
    assert _run_import(pngs, out, "--force").returncode == 0

    CurationHandler.run_dir = out
    CurationHandler.lang = "en"
    srv = ThreadingHTTPServer(("127.0.0.1", 0), partial(CurationHandler))
    threading.Thread(target=srv.serve_forever, daemon=True).start()
    port = srv.server_address[1]

    def get_revision():
        return _json.loads(urllib.request.urlopen(f"http://127.0.0.1:{port}/api/run").read())["runRevision"]

    def post(revision):
        body = _json.dumps({"version": 1, "kind": "sprite-gen-curation", "runRevision": revision,
                            "states": {"items": {"selected": [1], "transforms": {"1": {"dx": 9}}}}}).encode()
        req = urllib.request.Request(f"http://127.0.0.1:{port}/api/curation", data=body, method="POST")
        try:
            return urllib.request.urlopen(req).status
        except urllib.error.HTTPError as exc:
            return exc.code

    try:
        old_rev = get_revision()                          # the webview loads generation 1
        # re-import the SAME state name with DIFFERENT images (new candidates)
        shutil.rmtree(pngs)
        _png(pngs / "items" / "1-a.png", color=(0, 0, 200, 255))
        _png(pngs / "items" / "2-b.png", color=(200, 200, 0, 255))
        assert _run_import(pngs, out, "--force").returncode == 0
        new_rev = get_revision()
        assert new_rev != old_rev, "run generation did not change on same-state re-import"
        # the old session autosaves against the stale generation -> rejected, not applied
        assert post(old_rev) == 409
        assert not (out / "curation.json").exists(), "stale curation applied to the new run"
        # a POST echoing the current generation saves
        assert post(new_rev) == 200
        assert (out / "curation.json").is_file()
    finally:
        srv.shutdown()


def test_stored_curation_ignored_after_frame_regeneration(tmp_path):
    """A saved curation.json is ignored once the frames are regenerated under it (re-extract
    or re-import): load_curation returns None, so the server, compose, and export all fall
    back to the all-frames default — stale selections/transforms never apply to new frames.
    This is the single load_curation gate every consumer passes through."""
    import time

    from sprite_gen.serve.serve_curation import build_run_state, write_curation_atomic
    from sprite_gen.curate import curation as cur

    pngs = tmp_path / "pngs"
    _png(pngs / "items" / "1-a.png")
    _png(pngs / "items" / "2-b.png")
    out = tmp_path / "run"
    assert _run_import(pngs, out, "--force").returncode == 0

    # save a curation stamped for the current generation (a selection + a transform)
    write_curation_atomic(out, {"version": 1, "kind": "sprite-gen-curation",
                                "states": {"items": {"selected": [1], "transforms": {"1": {"dx": 9}}}}})
    assert cur.load_curation(out) is not None            # applies now (same generation)
    rev_before = cur.run_revision(out)

    time.sleep(0.01)
    _png(out / "frames" / "items" / "frame-0.png", color=(1, 2, 3, 255))  # a re-extract-style frame rewrite
    assert cur.run_revision(out) != rev_before          # the run generation changed

    assert cur.load_curation(out) is None                # stale sidecar ignored at the single gate
    st = build_run_state(out)
    assert st["curation"]["states"] == {}                # server serves no stale curation


def test_unstamped_curation_ignored(tmp_path):
    """A curation.json with no run_revision (legacy / hand-written / copied from a doc example)
    is unverifiable against the current frames, so load_curation ignores it (all-frames default)
    rather than silently applying stale selections/transforms — the single gate has no bypass."""
    import json as _json

    from sprite_gen.serve.serve_curation import build_run_state
    from sprite_gen.curate import curation as cur

    pngs = tmp_path / "pngs"
    _png(pngs / "items" / "1-a.png")
    _png(pngs / "items" / "2-b.png")
    out = tmp_path / "run"
    assert _run_import(pngs, out, "--force").returncode == 0

    # an UNSTAMPED sidecar written directly, as a legacy/manual file would be
    (out / "curation.json").write_text(_json.dumps({
        "version": 1, "kind": "sprite-gen-curation",
        "states": {"items": {"selected": [1], "transforms": {"1": {"dx": 9}}}}}))
    assert cur.load_curation(out) is None                 # unstamped -> ignored, not applied
    assert build_run_state(out)["curation"]["states"] == {}
    # a valid save (via the stamping writer) then applies for the matching generation
    from sprite_gen.serve.serve_curation import write_curation_atomic
    write_curation_atomic(out, {"version": 1, "kind": "sprite-gen-curation",
                                "states": {"items": {"selected": [0]}}})
    assert cur.load_curation(out) is not None


def test_extract_frame_publish_holds_publish_guard(tmp_path):
    """extract advances frames/ + extract-failure.json as one generation via _commit_generation,
    which holds publish_guard for the whole transaction — so it serializes with a curation reader
    (read_guard) and the reader never observes a half-swapped frames dir or a new generation
    beside a stale failure record."""
    import threading

    from sprite_gen.spec import runio
    from sprite_gen.frames.extract import _commit_generation

    run = tmp_path / "run"
    (run / "frames" / "items").mkdir(parents=True)
    (run / "frames" / "items" / "frame-0.png").write_bytes(b"OLD")
    staging = run / ".frames.sg-staging"
    (staging / "items").mkdir(parents=True)
    (staging / "items" / "frame-0.png").write_bytes(b"NEW")
    result = {"ok": True, "errors": [], "warnings": [], "rows": []}

    reader_holding = threading.Event()
    release_reader = threading.Event()

    def reader():
        with runio.read_guard(run):
            reader_holding.set()
            release_reader.wait(3)

    threading.Thread(target=reader).start()
    reader_holding.wait(3)

    published = threading.Event()

    def publisher():
        _commit_generation(run, staging, result, {"items"}, {"items"})
        published.set()

    threading.Thread(target=publisher).start()
    assert not published.wait(0.3), "extract commit did not block on the reader (no isolation)"
    release_reader.set()
    published.wait(3)
    assert published.is_set()
    assert (run / "frames" / "items" / "frame-0.png").read_bytes() == b"NEW"
    assert (run / "frames" / "items" / "frame-0.png").read_bytes() == b"NEW"  # single new generation
    assert not staging.exists()


@pytest.mark.parametrize("field,where", [
    ("run-wide", "top"),
    ("per-state", "state"),
])
def test_autosave_preserves_pixel_perfect_the_view_does_not_author(tmp_path, field, where):
    """뷰가 **authoring 하지 않는** `pixel_perfect` 선언은 autosave 가 지우면 안 된다.

    `buildPayload` 는 이 필드를 조건부로만 싣는다: per-state 는 트윈이 있는 줄만, 런 전역은
    트윈 줄이 전부 같을 때만. 생략은 "안 건드림" 이지 삭제가 아니다 — 삭제로 받으면
    **굽기가 읽는 변종이 바뀐다**(`frame_variant`). `.plain.png` 가 없는 줄이 `plain` 으로
    뒤집히면 `row_frame_rel(row, i, "plain")` 이 없는 파일을 가리켜 굽기가 죽는데, 사용자는
    큐레이터를 한 번 열었을 뿐이고 화면에는 아무 알림도 없다 (validator 실측 2026-07-26).

    `anchors`·`frozen` 과 같은 이월 계약이다. 이 그물이 없는 동안 이월 두 줄을 지워도
    전체 스위트가 513 passed 로 통과했다 — round-9 R2 가 `bakeFrameUrl` 에 대해 기각한
    것과 같은 상태였다."""
    from sprite_gen.curate.curation import frame_variant, stamp_curation

    pngs = tmp_path / "pngs"
    _png(pngs / "items" / "1-a.png", color=(200, 0, 0, 255))
    _png(pngs / "items" / "2-b.png", color=(0, 200, 0, 255))
    out = tmp_path / "run"
    assert _run_import(pngs, out).returncode == 0

    curation = {"version": 1, "kind": "sprite-gen-curation", "states": {"items": {}}}
    if where == "top":
        curation["pixel_unfake"] = False
    else:
        curation["states"]["items"]["pixel_unfake"] = True
        curation["pixel_unfake"] = False          # per-state 가 이기는지도 같이 본다
    (out / "curation.json").write_text(json.dumps(stamp_curation(out, curation)), encoding="utf-8")
    before = frame_variant(json.loads((out / "curation.json").read_text(encoding="utf-8")), "items")

    CurationHandler.run_dir = out
    CurationHandler.lang = "en"
    srv = ThreadingHTTPServer(("127.0.0.1", 0), partial(CurationHandler))
    threading.Thread(target=srv.serve_forever, daemon=True).start()
    port = srv.server_address[1]
    try:
        revision = json.loads(
            urllib.request.urlopen(f"http://127.0.0.1:{port}/api/run").read())["runRevision"]
        # 뷰가 authoring 하지 않은 저장 — `pixel_perfect` 키가 어디에도 없다
        body = json.dumps({"version": 1, "kind": "sprite-gen-curation", "runRevision": revision,
                           "states": {"items": {"selected": [0, 1]}}}).encode()
        req = urllib.request.Request(f"http://127.0.0.1:{port}/api/curation",
                                     data=body, method="POST")
        assert urllib.request.urlopen(req).status == 200
    finally:
        srv.shutdown()

    saved = json.loads((out / "curation.json").read_text(encoding="utf-8"))
    after = frame_variant(saved, "items")
    assert after == before, (
        f"{field} 선언이 autosave 에 사라져 굽기 변종이 {before} -> {after} 로 바뀌었다\n"
        f"  저장된 사이드카: {saved}")


# --- the reroll and in-between buttons: the providers they run, and the one a request without a provider runs ------

BUTTONS = {"/api/reroll": {"state": "items"}, "/api/interpolate": {"state": "items", "from": 0, "to": 1}}


def _post_json(port: int, path: str, body: dict) -> tuple[int, dict]:
    import urllib.error

    req = urllib.request.Request(f"http://127.0.0.1:{port}{path}", data=json.dumps(body).encode(), method="POST")
    try:
        with urllib.request.urlopen(req) as answer:
            return answer.status, json.loads(answer.read())
    except urllib.error.HTTPError as exc:
        return exc.code, json.loads(exc.read())


@pytest.fixture
def button_server(tmp_path, monkeypatch):
    """A curator server on an imported run whose generating steps are stubs keeping (button, provider)."""
    from sprite_gen.serve import serve_curation

    run = _build_import(tmp_path, [], with_base=False)
    asked = []
    monkeypatch.setattr(serve_curation, "run_reroll",
                        lambda run_dir, state, provider: asked.append(("/api/reroll", provider)) or {"ok": True})
    monkeypatch.setattr(serve_curation, "run_interpolate",
                        lambda run_dir, state, a, b, t, label, provider:
                        asked.append(("/api/interpolate", provider)) or {"ok": True})
    CurationHandler.run_dir = run
    CurationHandler.lang = "en"
    srv = ThreadingHTTPServer(("127.0.0.1", 0), partial(CurationHandler))
    threading.Thread(target=srv.serve_forever, daemon=True).start()
    try:
        yield srv.server_address[1], asked
    finally:
        srv.shutdown()


@pytest.mark.parametrize("path", list(BUTTONS))
def test_the_buttons_run_only_the_curator_providers(button_server, monkeypatch, path):
    """Both buttons run the curator's providers (`serve_curation.CURATOR_PROVIDERS`, what the select offers) and
    refuse any other, read when the request comes: a copy of the set in the handler would not follow it."""
    from sprite_gen.gen.base import PROVIDER_CODEX, PROVIDER_GROK

    port, asked = button_server
    monkeypatch.setattr("sprite_gen.serve.serve_curation.CURATOR_PROVIDERS", (PROVIDER_GROK,))
    assert _post_json(port, path, {**BUTTONS[path], "provider": PROVIDER_CODEX}) == (
        400, {"error": f"unknown provider: {PROVIDER_CODEX}"})
    assert _post_json(port, path, {**BUTTONS[path], "provider": PROVIDER_GROK})[0] == 200
    assert asked == [(path, PROVIDER_GROK)]


@pytest.mark.parametrize("path,default", [
    ("/api/reroll", "sprite_gen.gen.HARD_DEFAULT_PROVIDER"),                 # a reroll is gen drawing the row again
    ("/api/interpolate", "sprite_gen.effects.interpolate.DEFAULT_PROVIDER"),  # an in-between has its own default
])
def test_a_button_request_naming_no_provider_runs_the_declared_default(button_server, monkeypatch, path, default):
    """A request with no provider runs its step's declared default, read when the request comes."""
    from sprite_gen.gen.base import PROVIDER_GROK

    port, asked = button_server
    monkeypatch.setattr(default, PROVIDER_GROK)
    assert _post_json(port, path, BUTTONS[path])[0] == 200
    assert asked == [(path, PROVIDER_GROK)]


# gen-trigger.js is a classic script: its select is built by `makeProviderSelect` from a top-level const, so node runs
# the file with the two DOM calls it makes and prints the options' values.
SELECT_HARNESS = r"""
const fs = require("fs");
const vm = require("vm");
const element = () => ({ children: [], appendChild(child) { this.children.push(child); } });
const sandbox = { document: { createElement: element }, console };
sandbox.globalThis = sandbox;
vm.createContext(sandbox);
vm.runInContext(fs.readFileSync(process.argv[2], "utf8"), sandbox);
console.log(JSON.stringify(sandbox.makeProviderSelect().children.map((option) => option.value)));
"""


@pytest.mark.skipif(shutil.which("node") is None, reason="node 가 없어 gen-trigger.js 를 실행할 수 없다")
def test_the_provider_select_offers_the_curator_providers_in_order(tmp_path):
    """The select both buttons share is the JS side of `CURATOR_PROVIDERS`: the same values in the same order, and
    its first option, the one a button runs unless changed, is codex."""
    from sprite_gen.gen.base import PROVIDER_CODEX
    from sprite_gen.serve import serve_curation

    harness = tmp_path / "harness.cjs"
    harness.write_text(SELECT_HARNESS, encoding="utf-8")
    script = serve_curation.CURATOR_DIR / "src" / "gen-trigger.js"
    proc = subprocess.run([shutil.which("node"), str(harness), str(script)], capture_output=True, encoding="utf-8")
    assert proc.returncode == 0, proc.stderr
    values = json.loads(proc.stdout)
    assert values == list(serve_curation.CURATOR_PROVIDERS)
    assert values[0] == PROVIDER_CODEX