Skip to content

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

34.7 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""기준 프레임 키 — 파이썬과 JS 가 **같은 문자열**을 내는가 (그리고 웹뷰가 그 재료를
어디서 긁어오는가).

## 왜 이 파일이 따로 있나

호흡 지문은 원래 *변형 결과 RGBA* 의 해시였다. 그런데 굽기는 `apply_transform` 에서
BICUBIC 으로 리샘플하고(`snap_scale` 없는 런 = 기본 런 전부) 웹뷰 캔버스는
`imageSmoothingEnabled=false`, 즉 NEAREST 다. 같은 원본에 같은 변형을 걸어도 두 쪽이
만드는 그림이 다르니 지문은 **영구 불일치**였고, 회전·확대가 걸린 줄은 프리뷰가 영원히
원본으로 떨어지고 영상 내보내기가 영구 차단됐다 (validator 실측 2026-07-26: rotate 3° 555px
상이, 정수 이동만 걸린 줄은 우연히 일치).

10라운드를 살아남은 이유가 구조적이다: 기존 미러 테스트는 **같은 픽셀 버퍼**를 양쪽에
먹여서 "웹뷰가 서버가 지문 찍은 그 버퍼를 만들어 낼 수 있는가" 를 한 번도 묻지 않았다.
그래서 이 파일은 픽셀을 아예 안 쓰고 **입력에서 키가 나오는 경로**만 본다.
"""

import json
import re
import subprocess
import sys
import tempfile
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))

from sprite_gen.effects.breathe import anatomy_fingerprint, reference_key  # noqa: E402
from sprite_gen.serve.serve_curation import CURATOR_DIR  # noqa: E402

SRC = CURATOR_DIR / "src"

pytestmark = pytest.mark.skipif(
    not __import__("shutil").which("node"), reason="node 없음 — 미러를 못 돌린다")


def _node(script: str, payload: dict):
    with tempfile.TemporaryDirectory() as tmp:
        pj = Path(tmp) / "payload.json"
        pj.write_text(json.dumps(payload), encoding="utf-8")
        run = subprocess.run(["node", "-e", script, str(pj)],
                             capture_output=True, encoding="utf-8", timeout=120)
    assert run.returncode == 0, f"node 실패:\n{run.stderr}"
    return json.loads(run.stdout)


KEY_HARNESS = r"""
const fs = require("fs"), vm = require("vm");
const payload = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
const sandbox = { console, TextEncoder, entries: {}, run: {}, setStatus: () => {},
                  document: { createElement: () => ({ getContext: () => ({}) }) } };
sandbox.globalThis = sandbox;
vm.createContext(sandbox);
vm.runInContext(fs.readFileSync(payload.script, "utf8"), sandbox);
const out = payload.cases.map((c) => ({
  key: sandbox.breatheReferenceKeyOf(c),
  fingerprint: sandbox.breatheFingerprint(sandbox.breatheReferenceKeyOf(c)),
}));
process.stdout.write(JSON.stringify(out));
"""

# 값 **모양**의 전수 — 지적당한 한 칸만 메우는 방식이 열 라운드 동안 실패했다.
# 변형 없음(대부분의 프레임)·항등 명시·회전·축소·음수 이동·거울·문자열 수·소수 경계,
# 픽셀편집 없음/지움(null)/여러 점(정렬 순서 뒤섞임)까지 한 번에 건다.
CASES = [
    {"variant": "plain", "transform": None, "pixel_ops": None},
    {"variant": "plain", "transform": {}, "pixel_ops": {}},
    {"variant": "pixel", "transform": {"rotate": 0.0, "scale": 1.0, "dx": 0, "dy": 0,
                                       "shx": 0.0, "shy": 0.0, "flipX": 0}, "pixel_ops": None},
    {"variant": "plain", "transform": {"rotate": 3.0}, "pixel_ops": None},
    {"variant": "plain", "transform": {"scale": 0.9}, "pixel_ops": None},
    {"variant": "pixel", "transform": {"dx": -7, "dy": 12}, "pixel_ops": None},
    {"variant": "pixel", "transform": {"flipX": True}, "pixel_ops": None},
    {"variant": "plain", "transform": {"rotate": "3"}, "pixel_ops": None},
    {"variant": "plain", "transform": {"scale": 1.0000005}, "pixel_ops": None},
    {"variant": "plain", "transform": {"rotate": -0.5, "shx": 0.25}, "pixel_ops": None},
    {"variant": "plain", "transform": None, "pixel_ops": {"3,4": "#ff0000"}},
    {"variant": "plain", "transform": None, "pixel_ops": {"10,2": None}},
    {"variant": "pixel", "transform": None,
     "pixel_ops": {"9,9": "#00ff00", "1,1": "#0000ff", "10,0": None}},
    {"variant": "pixel", "transform": {"rotate": 3.0}, "pixel_ops": {"2,2": "#123456"}},
]


def _py(case, *, state="idle", request_stamp="120:5", source_index=0, source_stamp="900:7"):
    return reference_key(state=state, variant=case["variant"], request_stamp=request_stamp,
                         source_index=source_index, source_stamp=source_stamp,
                         pixel_ops=case["pixel_ops"], transform=case["transform"])


def _js_case(case, *, state="idle", request_stamp="120:5", source_index=0, source_stamp="900:7"):
    return {"state": state, "variant": case["variant"], "requestStamp": request_stamp,
            "sourceIndex": source_index, "sourceStamp": source_stamp,
            "pixelOps": case["pixel_ops"], "transform": case["transform"]}


def test_python_and_js_build_the_same_key_for_every_value_shape():
    got = _node(KEY_HARNESS, {"script": str(SRC / "breathe.js"),
                              "cases": [_js_case(c) for c in CASES]})
    assert len(got) == len(CASES)
    for case, js in zip(CASES, got):
        py = _py(case)
        assert js["key"] == py, (
            f"키가 갈렸다 — 변형 {case['transform']!r} / 픽셀 {case['pixel_ops']!r}\n"
            f"  py: {py}\n  js: {js['key']}")
        assert js["fingerprint"] == anatomy_fingerprint(py), "같은 키인데 지문이 갈렸다"


def test_every_ingredient_changes_the_key():
    """재료 하나를 건드리면 키가 **반드시** 달라진다.

    안 달라지는 재료가 있으면 그건 신선도 판정에서 빠진 것이다 — 사용자가 그걸 바꿔도
    프리뷰가 낡은 해부로 계속 그린다."""
    base = {"variant": "plain", "transform": {"rotate": 3.0}, "pixel_ops": {"2,2": "#123456"}}
    ref = _py(base)
    variants = {
        "state": _py(base, state="walk"),
        "variant": _py({**base, "variant": "pixel"}),
        "request_stamp": _py(base, request_stamp="121:5"),
        "source_index": _py(base, source_index=1),
        "source_stamp": _py(base, source_stamp="900:8"),
        "transform": _py({**base, "transform": {"rotate": 3.000001}}),
        "pixel_ops": _py({**base, "pixel_ops": {"2,2": "#123457"}}),
    }
    for name, key in variants.items():
        assert key != ref, f"{name} 을 바꿨는데 키가 그대로다 — 신선도 판정 밖에 있다"


def test_the_key_never_reads_pixels():
    """키 계산에 이미지가 **필요 없다**는 것이 이 설계의 요점이다.

    이 단언이 무너지면(키 함수가 프레임을 받게 되면) 리샘플러 차이가 다시 식에 들어온다."""
    import inspect

    from sprite_gen.effects import breathe
    sig = inspect.signature(breathe.reference_key)
    assert "frame" not in sig.parameters and "image" not in sig.parameters, \
        "reference_key 가 프레임을 받는다 — BICUBIC/NEAREST 불일치가 되돌아온다"
    js = (SRC / "breathe.js").read_text(encoding="utf-8")
    body = js[js.index("function breatheReferenceKeyOf"):]
    body = body[:body.index("\nfunction ", 1)]
    for banned in ("getImageData", "getContext", "canvas", "drawImage"):
        assert banned not in body, f"JS 키 빌더가 {banned} 를 쓴다 — 픽셀을 읽으면 안 된다"


# ── 웹뷰가 서버가 쓴 그 키를 만들어 낼 수 있는가 ──────────────────────

from tests.effects.test_breathe_anatomy_route import CELL, run_dir  # noqa: E402,F401

STORE_HARNESS = r"""
const fs = require("fs"), vm = require("vm");
const payload = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
const sources = payload.scripts.map((f) => fs.readFileSync(f, "utf8"));

// 부팅 하나 = 새 vm 컨텍스트 하나. 여러 부팅을 node 한 프로세스에 묶어도
// `run`·`entries`·`unfakeStates` 가 다음 부팅으로 새지 않는다.
function boot(one) {
  const sandbox = {
    console, TextEncoder, Set, Map, setTimeout,
    document: { createElement: () => ({ getContext: () => ({}), style: {} }),
                addEventListener() {}, querySelectorAll: () => [] },
    window: {}, fetch: () => {}, setStatus() {}, t: () => "", STR: {}, lang: "ko",
    scheduleSave() {}, flushSave: async () => {}, rebuildState() {},
    URL: { createObjectURL() {}, revokeObjectURL() {} },
  };
  sandbox.globalThis = sandbox;
  vm.createContext(sandbox);
  for (const src of sources) vm.runInContext(src, sandbox);

  // 서버 페이로드를 웹뷰 상태로 — store.js 가 읽는 필드만.
  //
  // `let run`/`let entries` 는 컨텍스트의 **렉시컬 바인딩**이라 sandbox 객체에 대입해도
  // 스크립트가 못 본다. 컨텍스트 안에서 대입해야 한다.
  sandbox.__payload = one;
  vm.runInContext(`
    run = __payload.run;
    entries = {};
    // **손으로 unfakeStates 를 먹이지 않는다.** 웹뷰가 서버 페이로드에서 변종을 스스로
    // 골라내는지가 이 하네스의 요점이다 — 시드를 밖에 두면 그 질문을 영영 못 묻는다
    // (validator 실측 2026-07-26: 변종 불일치가 그 공백으로 한 라운드를 살아남았다).
    seedUnfakeState(__payload.run);
    for (const [name, v] of Object.entries(__payload.ppOverride || {})) unfakeStates[name] = v;
    for (const [name, e] of Object.entries(__payload.entries)) {
      entries[name] = { order: e.order, sel: new Set(e.sel), transforms: e.transforms || {},
                        pixels: e.pixels || {}, clones: e.clones || {},
                        unlinked: new Set(e.unlinked || []) };
    }
    __out = {};
    for (const q of __payload.queries) {
      if (q.kind === "key") __out[q.id] = breatheReferenceKey(q.state);
      if (q.kind === "geometry") __out[q.id] = breatheGeometryFrame(q.state, q.fallback);
      if (q.kind === "variant") __out[q.id] = bakeVariant(q.state);
    }
  `, sandbox);
  return sandbox.__out;
}

// 부팅 하나가 터져도 나머지 부팅은 돈다 — 실패는 그 부팅 자리에 `error` 로 남는다.
process.stdout.write(JSON.stringify(payload.boots.map((one) => {
  try { return { out: boot(one) }; }
  catch (e) { return { error: String((e && e.stack) || e) }; }
})));
"""


def _boot(run_payload, entries, queries, pp_override=None):
    return {"run": run_payload, "entries": entries, "ppOverride": pp_override or {},
            "queries": queries}


def _webview_boots(boots):
    """웹뷰 부팅 여러 개를 node **한 프로세스**에서 돌린다 (부팅마다 새 vm 컨텍스트).

    결과는 부팅마다 `{"out": 질의 결과}` 또는 `{"error": 스택}` — 한 부팅의 실패가
    나머지를 가리지 않는다."""
    return _node(STORE_HARNESS, {
        "scripts": [str(SRC / "breathe.js"), str(SRC / "store.js")], "boots": boots})


def _webview(run_payload, entries, queries, pp_override=None):
    """웹뷰를 서버 페이로드로 부팅해 질의한다 — `unfakeStates` 는 `seedUnfakeState` 가 짓는다.

    `pp_override` 는 사용자가 화면에서 토글을 누른 상태를 흉내낼 때만 쓴다."""
    [got] = _webview_boots([_boot(run_payload, entries, queries, pp_override)])
    assert "error" not in got, f"웹뷰 부팅 실패:\n{got['error']}"
    return got["out"]


@pytest.fixture()
def web_run(run_dir):
    """`/api/run` 페이로드까지 조립되는 런 — 라우트 픽스처의 `character` 는 문자열이라
    페이로드 빌더(`request["character"]["id"]`)가 죽는다."""
    req = json.loads((run_dir / "sprite-request.json").read_text(encoding="utf-8"))
    req["character"] = {"id": "fixture", "name": "fixture"}
    (run_dir / "sprite-request.json").write_text(json.dumps(req), encoding="utf-8")
    return run_dir


def _write_curation(run_dir, curation):
    """세대 도장까지 찍어 저장 — 안 찍으면 로더가 "프레임 재생성됨" 으로 보고 그 줄을
    통째로 드롭한다 (그러면 pixel_perfect 설정도 같이 사라져 변종이 되돌아간다)."""
    from sprite_gen.curate.curation import stamp_curation
    (run_dir / "curation.json").write_text(
        json.dumps(stamp_curation(run_dir, curation)), encoding="utf-8")


def _server_payload(run_dir):
    import sprite_gen.serve.serve_curation as serve_curation
    return serve_curation._build_run_state_impl(run_dir)


def test_the_webview_builds_the_same_key_the_route_used(web_run):
    """**이 파일의 핵심 단언.**

    미러 테스트들은 같은 픽셀 버퍼를 양쪽에 먹여서 "웹뷰가 서버가 지문 찍은 그 프레임에
    도달할 수 있는가" 를 묻지 않았다 — 그래서 리샘플러 불일치가 10라운드를 살아남았다.
    여기서는 서버가 실제로 응답에 실어 보낸 페이로드만으로 웹뷰가 키를 만들게 하고,
    라우트가 해부를 얼릴 때 쓴 키와 **문자열 동일**한지 본다."""
    import sprite_gen.serve.serve_curation as serve_curation
    _, route_key = serve_curation._breathe_source_frame(web_run, "idle")
    payload = _server_payload(web_run)
    got = _webview(payload,
                   {"idle": {"order": [0, 1, 2, 3], "sel": [0, 1, 2, 3]}},
                   [{"id": "k", "kind": "key", "state": "idle"}])
    assert got["k"] == route_key, (
        "웹뷰가 라우트와 다른 키를 만든다 — 프리뷰가 영원히 원본으로 떨어진다.\n"
        f"  라우트: {route_key}\n  웹뷰  : {got['k']}")


def test_the_key_follows_the_sidecar_the_user_actually_edited(web_run):
    """사용자가 변형·픽셀편집을 바꾸면 웹뷰 키가 **따라 움직인다.**

    안 움직이면 낡은 해부로 계속 그린다 — 지문의 존재 이유 자체가 사라진다."""
    payload = _server_payload(web_run)
    base = {"idle": {"order": [0, 1, 2, 3], "sel": [0, 1, 2, 3]}}
    q = [{"id": "k", "kind": "key", "state": "idle"}]
    plain = _webview(payload, base, q)["k"]
    rotated = _webview(payload, {"idle": {**base["idle"], "transforms": {"0": {"rotate": 3.0}}}}, q)["k"]
    painted = _webview(payload, {"idle": {**base["idle"], "pixels": {"0": {"3,4": "#ff0000"}}}}, q)["k"]
    reordered = _webview(payload, {"idle": {"order": [2, 0, 1, 3], "sel": [0, 1, 2, 3]}}, q)["k"]
    assert plain and rotated != plain, "회전을 걸었는데 키가 그대로다"
    assert painted != plain, "픽셀을 칠했는데 키가 그대로다"
    assert reordered != plain, "재생 순서를 바꿔 기준 프레임이 달라졌는데 키가 그대로다"


def test_a_missing_stamp_refuses_instead_of_guessing(web_run):
    """스탬프가 없으면 **키를 만들지 않는다** (null).

    없는 재료를 기본값으로 메우면 서로 다른 프레임이 같은 키를 갖고, 그때 신선도 검사는
    통과하면서 그림은 갈린다 — 조용한 오답이 시끄러운 거부보다 나쁘다."""
    payload = _server_payload(web_run)
    for st in payload["states"]:
        for fr in st.get("frames", []):
            fr.pop("stamp", None)
            fr.pop("plainBakeStamp", None)
    got = _webview(payload, {"idle": {"order": [0, 1, 2, 3], "sel": [0, 1, 2, 3]}},
                   [{"id": "k", "kind": "key", "state": "idle"}])
    assert got["k"] is None, f"스탬프가 없는데 키를 만들어냈다: {got['k']!r}"


def test_geometry_measures_the_reference_frame_not_the_opened_one(web_run):
    """경계 지오메트리의 원점 = 재생 첫 슬롯. 모달이 열린 프레임이 아니다.

    `rigid_row` 는 기준 프레임의 콘텐츠 행 인덱스라, 열린 프레임을 재면 선의 화면
    위치와 저장되는 행 번호가 굽기와 어긋난다 — 재생 순서만 바꿔도 도달하고 골든
    픽스처에서 8px(50px 캐릭터의 16%) 어긋났다 (validator 실측 2026-07-26).
    round-10 은 이 결함을 고쳤지만 **그물이 없어** 되돌려도 전체 스위트가 통과했다."""
    payload = _server_payload(web_run)
    got = _webview(payload, {"idle": {"order": [2, 0, 1, 3], "sel": [0, 1, 2, 3]}},
                   [{"id": "g", "kind": "geometry", "state": "idle", "fallback": 3}])
    assert got["g"]["index"] == 2, (
        f"지오메트리가 재생 첫 슬롯(2)이 아니라 {got['g']['index']} 를 잰다 — "
        "열린 프레임을 재면 경계가 굽기와 어긋난다")
    empty = _webview(payload, {"idle": {"order": [0, 1, 2, 3], "sel": []}},
                     [{"id": "g", "kind": "geometry", "state": "idle", "fallback": 3}])
    assert empty["g"]["index"] == 3, "재생목록이 비면 열린 프레임으로 떨어져야 한다"


@pytest.fixture()
def web_run_plain(web_run):
    """pp OFF 줄 — `.plain.png` 쌍둥이를 굽기가 읽는다.

    R1 이 실제로 터진 경로다: 굽기는 `snap_scale` 이 없어 **BICUBIC** 으로 리샘플하고
    웹뷰는 NEAREST 라, 결과 픽셀을 해시하던 옛 지문이 여기서 영구 불일치였다."""
    from PIL import Image
    for i in range(4):
        src = web_run / f"frames/idle/frame-{i}.png"
        with Image.open(src) as im:
            im.convert("RGBA").resize((CELL, CELL), Image.NEAREST).save(
                src.with_suffix("").with_suffix(".plain.png"))
    from sprite_gen.curate.curation import empty_curation
    curation = empty_curation()
    curation["states"]["idle"] = {"pixel_unfake": False}
    _write_curation(web_run, curation)
    return web_run


def test_a_rotated_row_stays_fresh(web_run_plain):
    """**R1 회귀 그물.** 회전이 걸린 pp OFF 줄이 신선하다고 판정돼야 한다.

    옛 지문(변형 결과 RGBA 해시)에서는 이 줄이 영구 불일치라 프리뷰가 영원히 원본으로
    떨어지고 영상 내보내기가 영구 차단됐다 — 그리고 안내대로 해부를 갱신해도 라우트가
    또 BICUBIC 프레임으로 같은 숫자를 만들어 **절대 안 풀렸다** (validator 실측 2026-07-26:
    rotate 3° 에서 555px 상이).

    pp OFF 줄에서도 웹뷰 키 == 라우트 키인지를 같이 본다 — 변종이 갈리면 서로 다른
    **파일**을 기준으로 삼는다."""
    import sprite_gen.serve.serve_curation as serve_curation
    from sprite_gen.effects.breathe import freeze_anatomy
    curation = json.loads((web_run_plain / "curation.json").read_text(encoding="utf-8"))
    curation["states"]["idle"]["transforms"] = {"0": {"rotate": 3.0}}
    _write_curation(web_run_plain, curation)

    frame, route_key = serve_curation._breathe_source_frame(web_run_plain, "idle")
    assert "|plain|" in route_key, f"라우트가 plain 변종을 안 골랐다: {route_key}"
    frozen = freeze_anatomy(frame, {}, route_key)      # 라우트가 사이드카에 얼리는 값
    payload = _server_payload(web_run_plain)
    got = _webview(payload,
                   {"idle": {"order": [0, 1, 2, 3], "sel": [0, 1, 2, 3],
                             "transforms": {"0": {"rotate": 3.0}}}},
                   [{"id": "k", "kind": "key", "state": "idle"}])
    assert got["k"] == route_key, "회전이 걸린 줄에서 웹뷰가 다른 키를 만든다"
    assert anatomy_fingerprint(got["k"]) == frozen["fingerprint"], (
        "회전이 걸린 줄이 얼린 지문과 안 맞는다 — 프리뷰가 영원히 원본으로 떨어진다")


# ── 굽기 변종 해소표 전수 ────────────────────────────────────────────

# 해소 축은 셋이다: 트윈 존재(2) × per-state 선언(없음/켬/끔) × 런 전역(없음/켬/끔) = **18칸**.
#
# 앞선 판은 8칸을 "전수" 라고 적었는데 `twin=False` 일 때 `own=None` 한 줄만 돌았다. 빠진
# 6칸 중 3칸이 갈리고 있었다 — 파이썬 per-state 분기는 **무조건**인데 미러가 트윈 존재로
# 게이트했기 때문이다. 곱집합을 코드로 만들어 "전수" 가 이름이 아니라 사실이 되게 한다.
VARIANT_CASES = [(twin, own, wide)
                 for twin in (False, True)
                 for own in (None, True, False)
                 for wide in (None, True, False)]


def _variant_id(case):
    twin, own, wide = case
    fmt = {None: "없음", True: "켬", False: "끔"}
    return f"twin{'있음' if twin else '없음'}-own{fmt[own]}-wide{fmt[wide]}"


def test_the_webview_resolves_the_bake_variant_like_the_server():
    """웹뷰의 굽기 변종 == 파이썬 `frame_variant` — 해소표 전수.

    `unfakeOn` 은 **표시 렌즈**다: boot 시드가 트윈 없는 줄을 기본 OFF 로 놓는데 그 값은
    사이드카에 저장되지 않으므로 서버는 그 줄을 `pixel` 로 본다. 둘을 같은 값으로 쓰면
    `fit.pixel_perfect` 없이 만든 **기본 런 전부**에서 지문이 영구 불일치가 되고,
    해부를 갱신해도 라우트가 또 `pixel` 로 같은 키를 만들어 절대 안 풀린다
    (validator 실측 2026-07-26).

    한 칸씩 메우지 않고 표를 통째로 건다 — 같은 실패 모드가 축만 바꿔(파일 → 리샘플러
    → 변종 이름) 세 번 되돌아왔다.

    18칸은 node 한 프로세스에서 돈다 — 칸마다 새 vm 컨텍스트로 부팅하므로 칸끼리 상태가
    안 샌다. 칸은 하나도 줄이지 않고, 갈린 칸은 제 이름(`_variant_id`)으로 전부 보고한다."""
    from sprite_gen.curate.curation import frame_variant

    curations, boots = [], []
    for twin, own, wide in VARIANT_CASES:
        curation = {"states": {}}
        if own is not None:
            curation["states"]["idle"] = {"pixel_unfake": own}
        if wide is not None:
            curation["pixel_unfake"] = wide
        frames = [{"index": 0, "present": True, "url": "/f0.png", "stamp": "1:1"}]
        if twin:
            frames[0]["plainUrl"] = "/f0.plain.png"
            frames[0]["plainBakeUrl"] = "/f0.plain.png"
            frames[0]["plainBakeStamp"] = "2:2"
        payload = {"requestStamp": "9:9", "curation": curation,
                   "states": [{"name": "idle", "frames": frames}]}
        curations.append(curation)
        boots.append(_boot(payload, {"idle": {"order": [0], "sel": [0]}},
                           [{"id": "v", "kind": "variant", "state": "idle"}]))
    results = _webview_boots(boots)
    assert len(results) == len(VARIANT_CASES)

    failures = []
    for case, curation, got in zip(VARIANT_CASES, curations, results):
        want = frame_variant(curation, "idle")
        if "error" in got:
            failures.append(f"[{_variant_id(case)}] 웹뷰 부팅 실패:\n{got['error']}")
        elif got["out"]["v"] != want:
            failures.append(f"[{_variant_id(case)}] 웹뷰 {got['out']['v']!r} vs 서버 {want!r}")
    assert not failures, (
        f"해소표 {len(VARIANT_CASES)}칸 중 {len(failures)}칸이 갈렸다:\n" + "\n".join(failures))


def test_the_saved_sidecar_is_what_the_variant_resolves_from():
    """굽기 변종은 **저장되는 값**으로 해소한다.

    트윈 없는 줄의 퍼펙은 사이드카에 안 적힌다(적으면 굽기가 존재하지 않는 `.plain`
    변형을 요구한다). 그래서 그 줄의 화면 토글은 변종을 바꾸면 안 된다 — 눌렀다고
    키가 바뀌면 굽기는 그대로인데 프리뷰만 거부된다."""
    payload = {"requestStamp": "9:9", "curation": {"states": {}},
               "states": [{"name": "idle", "frames": [
                   {"index": 0, "present": True, "url": "/f0.png", "stamp": "1:1"}]}]}
    q = [{"id": "v", "kind": "variant", "state": "idle"}]
    on = _webview(payload, {"idle": {"order": [0], "sel": [0]}}, q, pp_override={"idle": True})
    off = _webview(payload, {"idle": {"order": [0], "sel": [0]}}, q, pp_override={"idle": False})
    assert on["v"] == off["v"] == "pixel", (
        f"트윈 없는 줄의 표시 토글이 굽기 변종을 바꾼다 (켬 {on['v']}, 끔 {off['v']})")


def test_a_declared_twinless_row_still_builds_a_key():
    """트윈 없는 줄에 per-state 선언이 있어도 웹뷰가 **키를 만들어야** 한다.

    변종 해소가 갈리면 웹뷰는 `plain` 을 고르고 `bakeFrame` 이 null 을 돌려줘 키가 아예
    안 만들어진다 → `breatheAssertFresh` 가 "기준 프레임 키를 만들 수 없다" 로 **영구
    거부**하고, 프리뷰 3곳·`row-export`·비교뷰 다운로드·경계 드래그가 전부 죽는다.
    굽기는 그 사이 멀쩡히 `pixel` 로 굽는다 (validator 실측 2026-07-26).

    "갈렸다" 를 값으로 보는 위 해소표와 달리, 이건 **사용자가 겪는 결과**를 본다."""
    curation = {"pixel_unfake": False, "states": {"idle": {"pixel_unfake": True}}}
    payload = {"requestStamp": "9:9", "curation": curation,
               "states": [{"name": "idle", "frames": [
                   {"index": 0, "present": True, "url": "/f0.png", "stamp": "1:1"}]}]}
    got = _webview(payload, {"idle": {"order": [0], "sel": [0]}},
                   [{"id": "k", "kind": "key", "state": "idle"},
                    {"id": "g", "kind": "geometry", "state": "idle", "fallback": 0}])
    assert got["k"] and "|pixel|" in got["k"], (
        f"키를 못 만들거나 변종이 틀렸다: {got['k']!r} — 프리뷰·내보내기가 영구 거부된다")
    assert got["g"]["url"], "경계 드래그가 잴 프레임을 못 잡는다"


# ── 미러 전수: 파이썬 함수를 JS 가 베낀 자리는 **곱집합**으로 건다 ──────
#
# 여덟 라운드 동안 같은 형태로 기각당했다: 미러가 어떤 입력 부분집합에서 원본과 갈리고,
# 그 부분집합이 손으로 적은 케이스 목록 밖에 있었다 (축만 파일 → 리샘플러 → 변종 이름 →
# per-state 게이트로 옮겨갔다). 인스턴스가 아니라 **클래스**를 닫으려면 케이스를 적지 말고
# 입력 축의 곱집합을 **생성**해야 한다. 이 절이 남은 미러들에 그 형태를 적용한다.

MIRROR_HARNESS = r"""
const fs = require("fs"), vm = require("vm");
const payload = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
const sandbox = { console, TextEncoder, Set, Map, setTimeout,
  document: { createElement: () => ({ getContext: () => ({}), style: {} }),
              addEventListener() {}, querySelectorAll: () => [] },
  window: {}, fetch: () => {}, setStatus() {}, t: () => "", STR: {}, lang: "ko",
  scheduleSave() {}, flushSave: async () => {}, rebuildState() {},
  URL: { createObjectURL() {}, revokeObjectURL() {} } };
sandbox.globalThis = sandbox;
vm.createContext(sandbox);
for (const f of payload.scripts) vm.runInContext(fs.readFileSync(f, "utf8"), sandbox);
sandbox.__payload = payload;
vm.runInContext(`
  __out = [];
  for (const c of __payload.cases) {
    if (__payload.fn === "normalizeTransform") {
      __out.push(breatheNormalizeTransform(c.transform));
    } else if (__payload.fn === "editIndex") {
      entries = { idle: { order: [0, 1, 2], sel: new Set([0, 1, 2]),
                          clones: c.clones || {},
                          unlinked: new Set(c.unlinked || []) } };
      __out.push(editIndex("idle", c.index));
    }
  }
`, sandbox);
process.stdout.write(JSON.stringify(sandbox.__out));
"""


def _mirror(fn, cases):
    return _node(MIRROR_HARNESS, {
        "scripts": [str(SRC / "breathe.js"), str(SRC / "store.js")],
        "fn": fn, "cases": cases})


# 변형 필드 × 값 모양의 곱집합 — 하나라도 갈리면 그 필드가 걸린 줄의 키가 통째로 갈린다.
_TRANSFORM_FIELDS = ["rotate", "scale", "dx", "dy", "shx", "shy", "flipX"]
_TRANSFORM_VALUES = [0, 1, -1, 3.0, 0.9, 1.0000005, "3", "0.5", True, False]
NORMALIZE_CASES = ([{"transform": None}, {"transform": {}}]
                   + [{"transform": {f: v}} for f in _TRANSFORM_FIELDS for v in _TRANSFORM_VALUES])


def test_normalize_transform_mirror_agrees_on_the_full_product():
    """`normalize_transform` 미러 — 필드 7 × 값 모양 10 곱집합.

    이 함수의 출력이 그대로 기준 프레임 키에 들어간다. 한 필드의 한 모양만 갈려도 그
    변형이 걸린 줄은 지문이 영구 불일치가 된다."""
    from sprite_gen.curate.curation import normalize_transform

    got = _mirror("normalizeTransform", NORMALIZE_CASES)
    assert len(got) == len(NORMALIZE_CASES)
    for case, js in zip(NORMALIZE_CASES, got):
        py = normalize_transform(case["transform"])
        assert {k: float(v) for k, v in js.items()} == {k: float(v) for k, v in py.items()}, (
            f"normalize_transform 미러가 갈렸다 — 입력 {case['transform']!r}\n"
            f"  py: {py}\n  js: {js}")


# 복제 링크 × 링크끊기 × 인덱스의 곱집합.
EDIT_INDEX_CASES = [{"clones": clones, "unlinked": unlinked, "index": index}
                    for clones in ({}, {"2": 0}, {"2": 1})
                    for unlinked in ([], [2])
                    for index in (0, 1, 2)]


def test_edit_index_mirror_agrees_on_the_full_product():
    """`edit_index` 미러 — 복제 링크 3 × 링크끊기 2 × 인덱스 3 곱집합.

    이 값이 어느 프레임의 변형·픽셀편집을 읽을지 정하고, 그게 기준 프레임 키의 재료다.
    갈리면 웹뷰와 굽기가 **다른 프레임의 편집**을 기준으로 삼는다. 미러라고 적혀 있지도
    않았고 교차언어 테스트도 없었다."""
    from sprite_gen.curate.curation import edit_index

    got = _mirror("editIndex", EDIT_INDEX_CASES)
    assert len(got) == len(EDIT_INDEX_CASES)
    for case, js in zip(EDIT_INDEX_CASES, got):
        curation = {"states": {"idle": {"clones": case["clones"],
                                        "unlinked": case["unlinked"]}}}
        py = edit_index(curation, "idle", case["index"])
        assert js == py, (
            f"edit_index 미러가 갈렸다 — clones={case['clones']} "
            f"unlinked={case['unlinked']} index={case['index']}: py={py} js={js}")


def test_the_mirrored_limits_are_the_same_numbers():
    """사이드카 허용 범위 상수 — 파이썬과 JS 가 **같은 숫자**여야 한다.

    갈리면 웹뷰가 굽기의 loud reject 를 못 예측해, 사용자는 저장되는데 안 구워지는
    설정을 만들 수 있다."""
    from sprite_gen.curate import curation as C

    js = (SRC / "breathe.js").read_text(encoding="utf-8")
    from sprite_gen.effects.breathe import WAVE_PEAK
    from sprite_gen.frames.extract import BORDER_MIN_FRACTION, FRAME_SIDES
    for name, want in (("BREATHE_DEPTH_MAX", C.BREATHE_DEPTH_MAX),
                       ("BREATHE_BREATHS_MAX", C.BREATHE_BREATHS_MAX),
                       ("BREATHE_LAG_MAX", C.BREATHE_LAG_MAX),
                       ("BREATHE_RANGE_MAX", C.BREATHE_RANGE_MAX),
                       ("BREATHE_WAVE_PEAK", WAVE_PEAK),
                       ("BREATHE_BORDER_MIN_FRACTION", BORDER_MIN_FRACTION)):
        m = re.search(rf"const {name} = ([\d.]+);", js)
        assert m, f"{name} 이 미러에 없다"
        assert float(m.group(1)) == float(want), \
            f"{name}: py={want} js={m.group(1)} — 갈리면 저장은 되는데 안 구워진다"
    sides = re.search(r"const BREATHE_SIDES = \[(.*?)\];", js)
    assert sides, "그림 테두리 변 목록이 미러에 없다"
    assert [k.strip().strip('"') for k in sides.group(1).split(",")] == list(FRAME_SIDES)
    keys = re.search(r"const BREATHE_RANGE_KEYS = \[(.*?)\];", js)
    assert keys, "최소·최대 키 목록이 미러에 없다"
    assert [k.strip().strip('"') for k in keys.group(1).split(",")] == list(C.BREATHE_RANGE_KEYS)

    retired = re.search(r"const RETIRED_BREATHE_KEYS = \[(.*?)\];",
                        (SRC / "store.js").read_text(encoding="utf-8"))
    assert retired, "폐기 키 목록이 미러에 없다"
    js_keys = {k.strip().strip('"') for k in retired.group(1).split(",")}
    assert js_keys == set(C.RETIRED_BREATHE_KEYS), \
        f"폐기 키 목록이 갈렸다: py={sorted(C.RETIRED_BREATHE_KEYS)} js={sorted(js_keys)}"


def test_a_plain_variant_without_a_twin_refuses_instead_of_falling_back():
    """변종이 `plain` 인데 트윈 파일이 없으면 **캐노니컬로 조용히 떨어지지 않는다**.

    그 상태는 굽기도 `row_frame_rel(row, i, "plain")` 로 없는 파일을 가리켜 실패하는
    상태다. 웹뷰만 캐노니컬로 떨어지면 두 쪽이 서로 다른 진실을 갖고, 프리뷰는 멀쩡해
    보이는데 굽기는 죽는다.

    이 계약은 round-12 가 세웠는데 그물이 없었다 — `frame.plainBakeUrl || frame.url` 로
    되돌려도 529 전부 통과했다 (validator note 2026-07-26)."""
    curation = {"states": {"idle": {"pixel_unfake": False}}}   # plain 을 강제
    payload = {"requestStamp": "9:9", "curation": curation,
               "states": [{"name": "idle", "frames": [        # 트윈 없음
                   {"index": 0, "present": True, "url": "/f0.png", "stamp": "1:1"}]}]}
    got = _webview(payload, {"idle": {"order": [0], "sel": [0]}},
                   [{"id": "v", "kind": "variant", "state": "idle"},
                    {"id": "k", "kind": "key", "state": "idle"},
                    {"id": "g", "kind": "geometry", "state": "idle", "fallback": 0}])
    assert got["v"] == "plain", "픽스처가 plain 변종을 안 만든다 — 이 테스트는 공허하다"
    assert got["k"] is None, (
        f"트윈이 없는데 키를 만들어냈다: {got['k']!r} — 캐노니컬로 조용히 떨어졌다는 뜻이다")
    assert got["g"]["url"] is None, (
        f"지오메트리가 굽기가 못 읽는 파일을 가리킨다: {got['g']['url']!r}")


def test_the_mirror_refuses_when_the_key_cannot_be_built():
    """키를 못 만들면 "확인 불가" 이지 "괜찮음" 이 아니다.

    형제 분기(지문 없음)는 round-10 R3 이후 그물이 있는데 이쪽만 비어 있었다 —
    `throw` 를 `return` 으로 바꿔도 529 전부 통과했다 (validator note 2026-07-26).
    키가 없는 상태는 트윈 없는 plain 줄·빈 재생목록·스탬프 없는 프레임에서 실제로 나온다
    — 셋 다 null 이다. 빈 문자열·undefined 도 같은 `!referenceKey` 한 줄이 받는다."""
    harness = r"""
const fs = require("fs"), vm = require("vm");
const P = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
const sb = { console, TextEncoder, document: { createElement: () => ({ getContext: () => ({}) }) },
             entries: {}, run: {}, t: () => "", setStatus: () => {}, fetch: () => {} };
sb.globalThis = sb; vm.createContext(sb);
vm.runInContext(fs.readFileSync(P.script, "utf8"), sb);
let out;
try {
  sb.breatheAssertFresh(P.key, P.cfg);
  out = { ok: true };
} catch (e) {
  out = { ok: false, refused: e.constructor.name === "BreatheRefused", message: e.message };
}
process.stdout.write(JSON.stringify(out));
"""
    cfg = {"depth": 0.06, "breaths": 1, "lag": 0.1,
           "anatomy": {"height": 50, "rigid_row": 12, "fingerprint": "pixel:0:deadbeef"}}
    got = _node(harness, {"script": str(SRC / "breathe.js"), "key": None, "cfg": cfg})
    assert not got["ok"] and got["refused"], (
        f"키가 null 인데 미러가 신선하다고 판정했다 — 낡은 해부로 그리고, "
        f"`row-export` 는 그 캔버스로 파일을 굽는다 ({got})")