Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
refactor(serve): the keys the curation and composer servers put in the JSON the screens read are declared once in each server's Wire, every body and the server's own read-backs are written through those names, and one test holds the scripts' reads of each key to the declared value
Soohong Kim7552959dafe9
diff --git a/sprite_gen/curate/curation.py b/sprite_gen/curate/curation.pyindex 4e7426a..7cc421d 100644--- a/sprite_gen/curate/curation.py+++ b/sprite_gen/curate/curation.py@@ -163,13 +163,14 @@ from sprite_gen.spec.runio import load_requestfrom sprite_gen.util.resample import transform_cellCURATION_FILENAME = "curation.json"+CURATION_KIND = "sprite-gen-curation" # 큐레이터 persistence.js 의 저장 payload 도 이 값이다SCHEMA_VERSION = 1IDENTITY = {"rotate": 0.0, "scale": 1.0, "dx": 0, "dy": 0, "shx": 0.0, "shy": 0.0, "flipX": 0}# Generation-material chip roles for imported `_refs/<role>-<name>.png` files# (run-contract.md §4). Single source shared by the importer (fail-loud on an# unknown role) and the webview server (render), so neither silently invents a role.-IMPORTED_REF_ROLES = ("anchor", "basis", "guide")+REF_ANCHOR, REF_BASIS, REF_GUIDE = IMPORTED_REF_ROLES = ("anchor", "basis", "guide")# 은퇴한 사이드카 키 -> 현행 키. `fit` 쪽과 같은 어휘 교체다 (runio.LEGACY_FIT_KEYS 참조):# "pixel perfect" 는 광의 통용어의 오용이고, 이 파이프라인이 하는 일의 정확한 명칭은@@ -818,7 +819,7 @@ def load_curation_report(run_dir: Path) -> tuple[dict[str, Any] | None, dict[strreturn None, reportraw_text = path.read_text(encoding="utf-8")data = json.loads(raw_text)- if data.get("kind") != "sprite-gen-curation":+ if data.get("kind") != CURATION_KIND:raise SystemExit(f"{path} is not a sprite-gen-curation file")# 은퇴 키 이관 (메모리) — 다음 저장이 현행 키로 파일을 갱신한다. 두 키 동시 = hard fail._migrate_curation_keys(data, str(path))@@ -1117,7 +1118,7 @@ def write_curation_atomic(run_dir: Path, payload: dict[str, Any]) -> str | None:backup: str | None = None- if payload.get("kind") != "sprite-gen-curation":+ if payload.get("kind") != CURATION_KIND:raise ValueError("payload is not a sprite-gen-curation document")_migrate_curation_keys(payload, str(run_dir / CURATION_FILENAME))payload = _carry_anchor_provenance(run_dir, payload)@@ -1340,4 +1341,4 @@ def apply_transform(def empty_curation() -> dict[str, Any]:- return {"version": SCHEMA_VERSION, "kind": "sprite-gen-curation", "states": {}}+ return {"version": SCHEMA_VERSION, "kind": CURATION_KIND, "states": {}}diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.pyindex dac3fcd..77ba6f8 100644--- a/sprite_gen/frames/extract.py+++ b/sprite_gen/frames/extract.py@@ -3584,7 +3584,7 @@ def _run_locked(args: argparse.Namespace, run_dir: Path):total_steps = len(states) * 2 # 1패스(컴포넌트/스냅) + 2패스(팔레트/배치)progress_step = 0for state in states:- _write_progress(run_dir, "extract", progress_step, total_steps, state, "components")+ _write_progress(run_dir, "extract", progress_step, total_steps, state, PROGRESS_PHASE_COMPONENTS)progress_step += 1if state not in request["states"]:raise SystemExit(f"unknown state in request: {state}")@@ -3837,7 +3837,7 @@ def heal_run(run_dir: Path | str) -> dict[str, Any]:행은 스테이징+스왑 경로가 이전 세대를 바이트 그대로 남긴다 (Atomicity)."""run_dir = Path(run_dir)- report: dict[str, Any] = {"healed": [], "kept_stale": [], "notes": []}+ report: dict[str, Any] = {HEAL_HEALED: [], HEAL_KEPT_STALE: [], HEAL_NOTES: []}manifest_path = run_dir / "frames" / "frames-manifest.json"request_path = run_dir / REQUEST_FILENAMEif not manifest_path.is_file() or not request_path.is_file():@@ -3870,17 +3870,17 @@ def heal_run(run_dir: Path | str) -> dict[str, Any]:for take in (request["states"][state].get("takes") or [])]if all((run_dir / rel).is_file() for rel in raws):- report["healed"].append(state)+ report[HEAL_HEALED].append(state)else:- report["kept_stale"].append(state)+ report[HEAL_KEPT_STALE].append(state)if frozen_kept:- report["frozen"] = frozen_kept- report["notes"].append("frozen rows kept (user-approved, heal skipped): " + ", ".join(frozen_kept))- if report["kept_stale"]:- report["notes"].append(+ report[HEAL_FROZEN] = frozen_kept+ report[HEAL_NOTES].append("frozen rows kept (user-approved, heal skipped): " + ", ".join(frozen_kept))+ if report[HEAL_KEPT_STALE]:+ report[HEAL_NOTES].append("stale rows kept as-is (raw missing, cannot re-derive): "- + ", ".join(report["kept_stale"]))- if report["healed"]:+ + ", ".join(report[HEAL_KEPT_STALE]))+ if report[HEAL_HEALED]:# 서브프로세스로 재추출한다: run-dir 락은 atexit 해제라, 장수 프로세스# (큐레이션 서버)가 인프로세스로 추출하면 락을 영구 보유해 이후의# compose/export 서브프로세스가 전부 죽는다. 자식 프로세스면 락 수명이@@ -3907,28 +3907,43 @@ def heal_run(run_dir: Path | str) -> dict[str, Any]:env = dict(os.environ)env["PYTHONPATH"] = (str(Path(__file__).resolve().parents[1])+ os.pathsep + env.get("PYTHONPATH", ""))- candidates = report["healed"]- report["healed"] = []- report["failed"] = []+ candidates = report[HEAL_HEALED]+ report[HEAL_HEALED] = []+ report[HEAL_FAILED] = []for state in candidates:cmd = [sys.executable, "-m", "sprite_gen.frames.extract","--run-dir", str(run_dir), "--states", state, *extract_flags]proc = subprocess.run(cmd, capture_output=True, text=True, env=env)if proc.returncode == 0:- report["healed"].append(state)+ report[HEAL_HEALED].append(state)else:- report["failed"].append(state)+ report[HEAL_FAILED].append(state)tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-3:]- report["notes"].append(+ report[HEAL_NOTES].append(f"heal re-extract failed for {state} — prior generation kept: "+ " | ".join(tail))- if not report["failed"]:- del report["failed"]+ if not report[HEAL_FAILED]:+ del report[HEAL_FAILED]return reportPROGRESS_REL = ".sprite-gen.progress.json"+# 진행 파일의 키 — 큐레이션 서버가 파일째로 실어 보내고 큐레이터가 읽는다 (progress.js·i18n.js).+PROGRESS_OP = "op"+PROGRESS_DONE = "done"+PROGRESS_TOTAL = "total"+PROGRESS_LABEL = "label"+PROGRESS_PHASE = "phase"+PROGRESS_TS = "ts"+PROGRESS_PHASE_COMPONENTS = "components" # i18n.js 의 ko 문구가 이 값에 갈린다+# heal_run 보고의 키 — 큐레이션 서버가 같은 모양을 만들고(_run_heal·_durable_failed_heal_report)+# `run.heal` 로 실어 보내면 큐레이터가 읽는다 (boot.js). frozen·failed 는 있을 때만 실린다.+HEAL_HEALED = "healed"+HEAL_KEPT_STALE = "kept_stale"+HEAL_FAILED = "failed"+HEAL_FROZEN = "frozen"+HEAL_NOTES = "notes"def _write_progress(run_dir: Path, op: str, done: int, total: int, label: str, phase: str) -> None:@@ -3939,8 +3954,8 @@ def _write_progress(run_dir: Path, op: str, done: int, total: int, label: str, pimport time as _timetry:atomic_write_text(run_dir / PROGRESS_REL, json.dumps({- "op": op, "done": done, "total": total, "label": label,- "phase": phase, "ts": _time.time()}, ensure_ascii=False))+ PROGRESS_OP: op, PROGRESS_DONE: done, PROGRESS_TOTAL: total, PROGRESS_LABEL: label,+ PROGRESS_PHASE: phase, PROGRESS_TS: _time.time()}, ensure_ascii=False))except OSError:passdiff --git a/sprite_gen/qa/motion.py b/sprite_gen/qa/motion.pyindex 39be2dc..66bfedb 100644--- a/sprite_gen/qa/motion.py+++ b/sprite_gen/qa/motion.py@@ -29,7 +29,8 @@ from sprite_gen._deps import npfrom PIL import Imagefrom sprite_gen.spec.assets import sequence_identity-from sprite_gen.spec.runio import acquire_run_dir_lock, atomic_write_set, release_run_dir_lock, same_folder+from sprite_gen.spec.runio import (LOCK_FILENAME, RWLOCK_SUFFIX, acquire_run_dir_lock, atomic_write_set,+ release_run_dir_lock, same_folder)from sprite_gen.util.cli_kwargs import namespace_from_kwargsfrom sprite_gen.util.console import utf8_streams@@ -428,7 +429,7 @@ def _output_path(out, source, sequence):protected = {Path(source).expanduser().resolve(), *(Path(p).resolve() for p in sequence.source_files)}if any(same_folder(path, p) for p in protected):raise ValueError("motion report must not overwrite an asset source file")- if path.name == ".sprite-gen.lock" or path.name.endswith(".sg-rwlock"):+ if path.name == LOCK_FILENAME or path.name.endswith(RWLOCK_SUFFIX):raise ValueError("motion report must not overwrite an output lock")if path.exists() and not path.is_file():raise ValueError("motion report output must be a file")diff --git a/sprite_gen/serve/serve_compose.py b/sprite_gen/serve/serve_compose.pyindex c22554c..c29bb05 100644--- a/sprite_gen/serve/serve_compose.py+++ b/sprite_gen/serve/serve_compose.py@@ -47,6 +47,7 @@ from pathlib import Pathfrom urllib.parse import parse_qs, unquote, urlparsefrom sprite_gen.frames.unpack_atlas import import_png_groups+from sprite_gen.spec.runio import REQUEST_FILENAMEfrom sprite_gen.util.console import utf8_streams# The SPA assets are package data (declared in pyproject's `package-data`), so the one@@ -65,6 +66,38 @@ CONTENT_TYPES = {}+class Wire:+ """Every key this server puts in a body the composer SPA (`composer/src/*.js`) reads,+ declared once; tests/serve/test_curator_wire_keys.py holds the SPA's read of each."""++ # /api/browse, /api/mount — one directory level and its entries+ DIR = "dir"+ ENTRIES = "entries"+ NAME = "name"+ PATH = "path"+ TYPE = "type"+ # /api/state, /api/mount+ LANG = "lang"+ MOUNT = "mount"+ # /api/pick+ CANCELLED = "cancelled"+ FILES = "files"+ # /api/build+ RUN_DIR = "runDir"+ STATES = "states"+ FRAMES = "frames"+ CELL = "cell"+ # /api/open-curation+ URL = "url"+ # errors+ ERROR = "error"+ CODE = "code"+++# entries[].type — library.js draws a folder for TYPE_DIR, an image for the rest+TYPE_DIR, TYPE_IMAGE = "dir", "image"++def _is_under(path: Path, root: Path) -> bool:"""True iff `path` resolves inside `root`. The traversal guard for browse/img:the client names paths, so every filesystem read is confined to the mounted@@ -93,12 +126,12 @@ def _list_dir(directory: Path, root: Path) -> dict:continuetry:if entry.is_dir():- dirs.append({"name": entry.name, "path": str(entry), "type": "dir"})+ dirs.append({Wire.NAME: entry.name, Wire.PATH: str(entry), Wire.TYPE: TYPE_DIR})elif entry.suffix.lower() in IMAGE_SUFFIXES and entry.is_file():- images.append({"name": entry.name, "path": str(entry), "type": "image"})+ images.append({Wire.NAME: entry.name, Wire.PATH: str(entry), Wire.TYPE: TYPE_IMAGE})except OSError:continue- return {"dir": str(directory), "entries": dirs + images}+ return {Wire.DIR: str(directory), Wire.ENTRIES: dirs + images}def _sanitize_state(name: str) -> str:@@ -172,16 +205,16 @@ def native_pick(kind: str = "folder") -> dict:proc = subprocess.run(["osascript", "-e", script], capture_output=True, text=True)if proc.returncode != 0:if "-128" in (proc.stderr or ""): # user canceled- return {"cancelled": True}+ return {Wire.CANCELLED: True}raise RuntimeError(proc.stderr.strip() or "osascript failed")if kind == "folder":picked = proc.stdout.strip()- return {"dir": picked} if picked else {"cancelled": True}+ return {Wire.DIR: picked} if picked else {Wire.CANCELLED: True}files = [line for line in proc.stdout.splitlines() if line.strip()]if not files:- return {"cancelled": True}+ return {Wire.CANCELLED: True}# Mount the image's containing folder; multiple picks are assumed to share one.- return {"dir": str(Path(files[0]).parent), "files": files}+ return {Wire.DIR: str(Path(files[0]).parent), Wire.FILES: files}def _free_port() -> int:@@ -235,7 +268,7 @@ class ComposeHandler(BaseHTTPRequestHandler):# rel is like "src/tree.js" or "composer.css"; confine to COMPOSER_DIR.target = (COMPOSER_DIR / rel).resolve()if not _is_under(target, COMPOSER_DIR) or not target.is_file():- self._send_json({"error": "not found", "path": rel}, 404)+ self._send_json({Wire.ERROR: "not found", Wire.PATH: rel}, 404)returnself._send_file(target)@@ -245,41 +278,41 @@ class ComposeHandler(BaseHTTPRequestHandler):if path == "/":index = COMPOSER_DIR / "index.html"if not index.is_file():- self._send_json({"error": f"missing composer SPA: {index}"}, 500)+ self._send_json({Wire.ERROR: f"missing composer SPA: {index}"}, 500)returnself._send_file(index)returnif path == "/api/state":self._send_json({- "lang": self.lang,- "mount": str(self.mount_root) if self.mount_root else None,+ Wire.LANG: self.lang,+ Wire.MOUNT: str(self.mount_root) if self.mount_root else None,})returnif path == "/api/browse":query = parse_qs(urlparse(self.path).query)if self.mount_root is None:- self._send_json({"error": "no folder mounted"}, 409)+ self._send_json({Wire.ERROR: "no folder mounted"}, 409)returnrequested = query.get("dir", [str(self.mount_root)])[0]try:self._send_json(_list_dir(Path(unquote(requested)), self.mount_root))except PermissionError as exc:- self._send_json({"error": str(exc)}, 403)+ self._send_json({Wire.ERROR: str(exc)}, 403)except FileNotFoundError as exc:- self._send_json({"error": str(exc)}, 404)+ self._send_json({Wire.ERROR: str(exc)}, 404)returnif path == "/api/browse-img":query = parse_qs(urlparse(self.path).query)if self.mount_root is None:- self._send_json({"error": "no folder mounted"}, 409)+ self._send_json({Wire.ERROR: "no folder mounted"}, 409)returnrequested = query.get("path", [""])[0]target = Path(unquote(requested)).resolve()if not _is_under(target, self.mount_root):- self._send_json({"error": "outside mounted root"}, 403)+ self._send_json({Wire.ERROR: "outside mounted root"}, 403)returnif target.suffix.lower() not in IMAGE_SUFFIXES or not target.is_file():- self._send_json({"error": "not an image", "path": requested}, 404)+ self._send_json({Wire.ERROR: "not an image", Wire.PATH: requested}, 404)returnself._send_file(target)return@@ -291,7 +324,7 @@ class ComposeHandler(BaseHTTPRequestHandler):if path.startswith("/src/") or path == "/composer.css":self._serve_spa_asset(path.lstrip("/"))return- self._send_json({"error": "not found", "path": path}, 404)+ self._send_json({Wire.ERROR: "not found", Wire.PATH: path}, 404)def do_POST(self) -> None:path = urlparse(self.path).path@@ -300,71 +333,71 @@ class ComposeHandler(BaseHTTPRequestHandler):try:payload = json.loads(self.rfile.read(length) or b"{}")except json.JSONDecodeError:- self._send_json({"error": "invalid JSON body"}, 400)+ self._send_json({Wire.ERROR: "invalid JSON body"}, 400)returnraw = (payload.get("dir") or "").strip()if not raw:- self._send_json({"error": "dir required"}, 400)+ self._send_json({Wire.ERROR: "dir required"}, 400)returncandidate = Path(raw).expanduser().resolve()if not candidate.is_dir():- self._send_json({"error": f"not a directory: {candidate}"}, 404)+ self._send_json({Wire.ERROR: f"not a directory: {candidate}"}, 404)returnComposeHandler.mount_root = candidate- self._send_json({"mount": str(candidate), **_list_dir(candidate, candidate)})+ self._send_json({Wire.MOUNT: str(candidate), **_list_dir(candidate, candidate)})returnif path == "/api/pick":kind = parse_qs(urlparse(self.path).query).get("kind", ["folder"])[0]try:self._send_json(native_pick(kind))except NotImplementedError as exc:- self._send_json({"error": str(exc), "code": "unsupported-platform"}, 501)+ self._send_json({Wire.ERROR: str(exc), Wire.CODE: "unsupported-platform"}, 501)except ValueError as exc:- self._send_json({"error": str(exc)}, 400)+ self._send_json({Wire.ERROR: str(exc)}, 400)except RuntimeError as exc:- self._send_json({"error": str(exc)}, 500)+ self._send_json({Wire.ERROR: str(exc)}, 500)returnif path == "/api/build":# Materialize the virtual session into a real run dir via the SSoT# importer (import_png_groups). The session is the unsaved buffer; this# is the one place references become bytes on disk.if self.mount_root is None:- self._send_json({"error": "no folder open"}, 409)+ self._send_json({Wire.ERROR: "no folder open"}, 409)returnlength = int(self.headers.get("Content-Length", 0))try:payload = json.loads(self.rfile.read(length) or b"{}")except json.JSONDecodeError:- self._send_json({"error": "invalid JSON body"}, 400)+ self._send_json({Wire.ERROR: "invalid JSON body"}, 400)returnraw_out = (payload.get("outDir") or "").strip()if not raw_out:- self._send_json({"error": "outDir required"}, 400)+ self._send_json({Wire.ERROR: "outDir required"}, 400)returnout_dir = Path(raw_out).expanduser().resolve()if out_dir.exists() and any(out_dir.iterdir()):- self._send_json({"error": f"output dir exists and is not empty: {out_dir}",- "code": "out-dir-not-empty"}, 409)+ self._send_json({Wire.ERROR: f"output dir exists and is not empty: {out_dir}",+ Wire.CODE: "out-dir-not-empty"}, 409)returntry:groups = _build_groups(payload.get("rows") or [], self.mount_root)except PermissionError as exc:- self._send_json({"error": str(exc)}, 403)+ self._send_json({Wire.ERROR: str(exc)}, 403)returnexcept FileNotFoundError as exc:- self._send_json({"error": str(exc)}, 404)+ self._send_json({Wire.ERROR: str(exc)}, 404)returnif not groups:- self._send_json({"error": "no rows with files to build"}, 400)+ self._send_json({Wire.ERROR: "no rows with files to build"}, 400)returnout_dir.mkdir(parents=True, exist_ok=True)try:summary = import_png_groups(out_dir, groups)except Exception as exc: # surface the importer's failure, do not swallow- self._send_json({"error": f"build failed: {exc}"}, 500)+ self._send_json({Wire.ERROR: f"build failed: {exc}"}, 500)return- self._send_json({"runDir": str(out_dir), "states": summary.get("states", []),- "frames": summary.get("frames", 0), "cell": summary.get("cell")})+ self._send_json({Wire.RUN_DIR: str(out_dir), Wire.STATES: summary.get("states", []),+ Wire.FRAMES: summary.get("frames", 0), Wire.CELL: summary.get("cell")})returnif path == "/api/open-curation":# Hand off to the curation view: launch a serve_curation process on the@@ -374,11 +407,11 @@ class ComposeHandler(BaseHTTPRequestHandler):try:payload = json.loads(self.rfile.read(length) or b"{}")except json.JSONDecodeError:- self._send_json({"error": "invalid JSON body"}, 400)+ self._send_json({Wire.ERROR: "invalid JSON body"}, 400)returnrun_dir = Path(str(payload.get("runDir", ""))).expanduser().resolve()- if not (run_dir / "sprite-request.json").is_file():- self._send_json({"error": f"not a run dir (no sprite-request.json): {run_dir}"}, 404)+ if not (run_dir / REQUEST_FILENAME).is_file():+ self._send_json({Wire.ERROR: f"not a run dir (no sprite-request.json): {run_dir}"}, 404)returnport = _free_port()subprocess.Popen(@@ -387,11 +420,11 @@ class ComposeHandler(BaseHTTPRequestHandler):stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,)if not _wait_ready(port):- self._send_json({"error": "curation server did not become ready"}, 504)+ self._send_json({Wire.ERROR: "curation server did not become ready"}, 504)return- self._send_json({"url": f"http://127.0.0.1:{port}/"})+ self._send_json({Wire.URL: f"http://127.0.0.1:{port}/"})return- self._send_json({"error": "not found", "path": path}, 404)+ self._send_json({Wire.ERROR: "not found", Wire.PATH: path}, 404)def add_arguments(parser: argparse.ArgumentParser) -> None:diff --git a/sprite_gen/serve/serve_curation.py b/sprite_gen/serve/serve_curation.pyindex efe8c5b..b124432 100644--- a/sprite_gen/serve/serve_curation.py+++ b/sprite_gen/serve/serve_curation.py@@ -59,12 +59,15 @@ from sprite_gen.effects import interpolate as interpolate_modfrom sprite_gen import gen as gen_modfrom sprite_gen.gen.base import PROVIDER_CODEX, PROVIDER_GROKfrom sprite_gen.curate.curation import (CURATION_FILENAME, SCHEMA_VERSION, effective_logical_height,+ REF_ANCHOR, REF_BASIS, REF_GUIDE,empty_curation, frame_variant, imported_ref_role,load_curation, load_curation_report, pixel_snap_scale,recolor_pick, run_revision, write_curation_atomic)-from sprite_gen.frames.extract import heal_run, load_consistent_frames_manifest+from sprite_gen.frames.extract import (HEAL_FAILED, HEAL_HEALED, HEAL_KEPT_STALE, HEAL_NOTES, PROGRESS_REL,+ heal_run, load_consistent_frames_manifest)from sprite_gen.spec.layout import frames_dir_rel, raw_rel, row_frame_rel, row_orig_rel, state_frame_total-from sprite_gen.spec.runio import load_request, publish_guard, read_guard, write_request+from sprite_gen.spec.runio import (LOCK_FILENAME, REQUEST_FILENAME, load_request, publish_guard,+ read_guard, write_request)from sprite_gen.util.hexcolor import parse_hexfrom sprite_gen._modules import qualifiedfrom sprite_gen.util.console import utf8_streams@@ -101,6 +104,145 @@ CONTENT_TYPES = {}+class Wire:+ """The curator's wire: every key this server puts in a body (or header) the curator SPA+ (`curator/src/*.js`) reads, declared once. Each body is written through these names, and+ the server reads its own keys back through them; tests/serve/test_curator_wire_keys.py+ holds the SPA's read of each one. A key is declared under the first object it appears in.+ Keys other modules own arrive under their own names: the heal report and the progress+ file (`frames.extract`), the ref roles (`curate.curation`)."""++ # /api/run — the run snapshot+ CHARACTER_ID = "characterId"+ RUN_DIR = "runDir"+ BASE_URL = "baseUrl"+ CELL = "cell"+ PIXEL_UNFAKE = "pixelUnfake"+ SCHEMA_VERSION = "schemaVersion"+ RUN_REVISION = "runRevision"+ REQUEST_STAMP = "requestStamp"+ DIRECTION_GROUPS = "directionGroups"+ ANCHOR_FILES = "anchorFiles"+ STATES = "states"+ CURATION = "curation"+ CURATION_DROPPED = "curationDropped"+ ISO = "iso"+ LANG = "lang"+ HAS_ATLAS = "hasAtlas"+ ATLAS = "atlas"+ RECOLOR = "recolor"+ FIT_PIXEL_UNFAKE = "fitPixelUnfake"+ CONTRACT = "contract"+ HEAL = "heal"+ # cell+ WIDTH = "width"+ HEIGHT = "height"+ SAFE_MARGIN_X = "safeMarginX"+ SAFE_MARGIN_Y = "safeMarginY"+ # pixelUnfake+ LOGICAL_HEIGHT = "logicalHeight"+ SCALE = "scale"+ SOURCE = "source"+ LABEL = "label"+ # states[] — one row+ NAME = "name"+ RAW_PRESENT = "rawPresent"+ PIXEL_SCALE = "pixelScale"+ REFS = "refs"+ FPS = "fps"+ LOOP = "loop"+ ACTION = "action"+ REQUEST_FRAMES = "requestFrames"+ EXTRACT_OK = "extractOk"+ FRAMES = "frames"+ TAKES = "takes"+ # states[].frames[] — one frame+ INDEX = "index"+ URL = "url"+ PRESENT = "present"+ PLAIN_URL = "plainUrl"+ STAMP = "stamp"+ PLAIN_BAKE_URL = "plainBakeUrl"+ PLAIN_BAKE_STAMP = "plainBakeStamp"+ INPUT_GRID = "inputGrid"+ SIZE = "size"+ CONTENT_SIZE = "contentSize"+ CONTENT_BOX = "contentBox"+ # states[].refs[] — one generation-material chip+ ROLE = "role"+ ANCHOR_FRAME = "anchorFrame"+ # directionGroups[] — one direction, and its anchorFrame {state, index, source}+ DIRECTION = "direction"+ ANCHOR = "anchor"+ STATE = "state"+ ANCHOR_ERROR = "anchorError"+ ANCHOR_ERROR_CODE = "anchorErrorCode"+ ANCHOR_PENDING = "anchorPending"+ ANCHOR_URL = "anchorUrl"+ MIRROR_OF = "mirrorOf"+ # contract — the view's self-report+ BASE = "base"+ REFS_STATES = "refsStates"+ GRID = "grid"+ SOURCELESS = "sourceless"+ # atlas+ MTIME = "mtime"+ MANIFEST_URL = "manifestUrl"+ # recolor — the baked colourways, the thumbnail box (swatch) and each variant+ DIR = "dir"+ SWATCH = "swatch"+ MATCH = "match"+ TOLERANCE = "tolerance"+ VARIANTS = "variants"+ PICKED = "picked"+ PICKED_KNOWN = "pickedKnown"+ X = "x"+ Y = "y"+ W = "w"+ H = "h"+ SHEET_WIDTH = "sheetWidth"+ SHEET_HEIGHT = "sheetHeight"+ SHEET = "sheet"+ SUBSTITUTED_PIXELS = "substitutedPixels"+ PASSTHROUGH_PIXELS = "passthroughPixels"+ PASSTHROUGH_COLOR_COUNT = "passthroughColorCount"+ UNUSED_SOURCES = "unusedSources"+ # replies — an error, a busy run and its long-op progress+ ERROR = "error"+ PATH = "path"+ BUSY = "busy"+ PROGRESS = "progress"+ # /api/progress — states[]+ RAW = "raw"+ RAW_URL = "rawUrl"+ FRAME0_URL = "frame0Url"+ REL_RAW = "relRaw"+ REL_FRAMES = "relFrames"+ # /api/breathe-anatomy+ ANATOMY = "anatomy"+ DEFAULTS = "defaults"+ DEPTH = "depth"+ LAG = "lag"+ BREATHS = "breaths"+ # /api/base-grid+ NOTE = "note"+ X_EDGES = "xEdges"+ Y_EDGES = "yEdges"+ PITCH = "pitch"+ # POST results+ OK = "ok"+ RETURNCODE = "returncode"+ STDOUT = "stdout"+ STDERR = "stderr"+ EXPORT = "export"+ GIF = "gif"+ APPLIED = "applied"+ SPACE = "space"+ BACKUP = "backup"+ # downloads — the file name the browser saves under+ FILENAME_HEADER = "X-Filename"++# ── 픽셀 격자 자동 측정 ──────────────────────────────────────────────# fit.pixel_unfake 계약이 없는 런(예: --pngs-dir 임포트)에서도 격자 오버레이를 켠다:@@ -158,7 +300,7 @@ def _breathe_source_frame(run_dir: Path, state: str):with Image.open(candidate) as opened:source = apply_pixel_edits(opened.convert("RGBA"), ops)key = reference_key(state=state, variant=variant,- request_stamp=_file_stamp(run_dir / "sprite-request.json"),+ request_stamp=_file_stamp(run_dir / REQUEST_FILENAME),source_index=source_index, source_stamp=_file_stamp(candidate),pixel_ops=ops, transform=transforms.get(edit_idx))return apply_transform(source, transforms.get(edit_idx), cell, snap_scale=snap), key@@ -188,7 +330,7 @@ def _base_grid_response(run_dir: Path, base_path: Path) -> dict:cleaned = remove_chroma_background_ycbcr(opened.convert("RGBA"), chroma)box = solid_alpha_bbox(cleaned) or cleaned.getbbox()if not box:- result = {"grid": None, "note": "base has no content to detect a grid on"}+ result = {Wire.GRID: None, Wire.NOTE: "base has no content to detect a grid on"}else:tight = cleaned.crop(box)# 여기서 쓰는 위상은 `detect_pixel_grid` 의 히스토그램 위상이고, 추출 스냅이 쓰는@@ -201,12 +343,12 @@ def _base_grid_response(run_dir: Path, base_path: Path) -> dict:# 위상 정확도는 별건이다 (docs/pixel-unfake.md "위상은 근사가 아니라 실측으로 고른다").(pitch_x, pitch_y), (phase_x, phase_y) = detect_pixel_grid(tight)if min(pitch_x, pitch_y) < 2.0:- result = {"grid": None, "note": "no confident pixel grid detected"}+ result = {Wire.GRID: None, Wire.NOTE: "no confident pixel grid detected"}else:x_edges = [box[0] + e for e in _grid_edges(tight.width, pitch_x, phase_x)]y_edges = [box[1] + e for e in _grid_edges(tight.height, pitch_y, phase_y)]- result = {"grid": {"xEdges": x_edges, "yEdges": y_edges,- "pitch": [round(pitch_x, 2), round(pitch_y, 2)]}}+ result = {Wire.GRID: {Wire.X_EDGES: x_edges, Wire.Y_EDGES: y_edges,+ Wire.PITCH: [round(pitch_x, 2), round(pitch_y, 2)]}}_BASE_GRID_CACHE.clear() # 베이스는 런당 1개 — 이전 세대 항목만 치움_BASE_GRID_CACHE[cache_key] = resultreturn result@@ -293,12 +435,12 @@ def _anchor_group_fields(view: dict) -> dict:"""directionGroups 항목에 실리는 앵커 필드. `pending`(그 행을 아직 안 뽑았다)은오류가 아니라 정상 구간이라 뷰가 경고색으로 칠하지 않는다 — 코드로 구분한다."""return {- "anchorFrame": ({"state": view["state"], "index": view["index"], "source": view["source"]}+ Wire.ANCHOR_FRAME: ({Wire.STATE: view["state"], Wire.INDEX: view["index"], Wire.SOURCE: view["source"]}if view.get("state") is not None else None),- "anchorError": view.get("error"),- "anchorErrorCode": view.get("code"),- "anchorPending": bool(view.get("pending")),- "anchorUrl": view.get("url"), # 라이브 베이크 (파이프라인 트리 썸네일도 이걸 쓴다)+ Wire.ANCHOR_ERROR: view.get("error"),+ Wire.ANCHOR_ERROR_CODE: view.get("code"),+ Wire.ANCHOR_PENDING: bool(view.get("pending")),+ Wire.ANCHOR_URL: view.get("url"), # 라이브 베이크 (파이프라인 트리 썸네일도 이걸 쓴다)}@@ -325,22 +467,22 @@ def _state_refs(run_dir, state, request, anchor_views=None):anchor = run_dir / anchor_relif state != anchor_state_name:if view.get("url"):- refs.append({"role": "anchor",- "name": f"{view['state']}#{view['index']}"+ refs.append({Wire.ROLE: REF_ANCHOR,+ Wire.NAME: f"{view['state']}#{view['index']}"f"{' · picked' if view.get('source') == 'picked' else ''}",- "url": view["url"], "anchorFrame": True})+ Wire.URL: view["url"], Wire.ANCHOR_FRAME: True})elif anchor.is_file():# 앵커 행이 아직 큐레이션/추출 전 — 실재하는 raw 스트립을 그대로 보여준다- refs.append({"role": "anchor", "name": anchor.name, "url": _url("run", *anchor_rel.split("/"))})+ refs.append({Wire.ROLE: REF_ANCHOR, Wire.NAME: anchor.name, Wire.URL: _url("run", *anchor_rel.split("/"))})base = state[len(direction) + 1:] if state.startswith(direction + "_") else Noneif base and direction != "down":basis_rel = raw_rel(request, f"down_{base}")basis = run_dir / basis_relif basis.is_file():- refs.append({"role": "basis", "name": basis.name, "url": _url("run", *basis_rel.split("/"))})+ refs.append({Wire.ROLE: REF_BASIS, Wire.NAME: basis.name, Wire.URL: _url("run", *basis_rel.split("/"))})guide = run_dir / "references" / "layout-guides" / f"{state}.png"if guide.is_file():- refs.append({"role": "guide", "name": guide.name, "url": _url("run", "references", "layout-guides", f"{state}.png")})+ refs.append({Wire.ROLE: REF_GUIDE, Wire.NAME: guide.name, Wire.URL: _url("run", "references", "layout-guides", f"{state}.png")})# imported runs (--pngs-dir): references/imported/<state>/<role>-<name>.png → 생성 재료 칩.# role 파싱 SSoT = curation.imported_ref_role. 미지 role 은 스킵한다 — import 가 fail-loud# 로 걸러 여기 도달하지 않지만, 손으로 놓인 파일도 조용히 guide 로 relabel 하지 않는다.@@ -350,8 +492,8 @@ def _state_refs(run_dir, state, request, anchor_views=None):role = imported_ref_role(ref.name)if role is None:continue- refs.append({"role": role, "name": ref.name,- "url": _url("run", "references", "imported", state, ref.name)})+ refs.append({Wire.ROLE: role, Wire.NAME: ref.name,+ Wire.URL: _url("run", "references", "imported", state, ref.name)})return refs@@ -359,7 +501,7 @@ def _state_refs(run_dir, state, request, anchor_views=None):def _read_op_progress(run_dir: Path) -> dict | None:"""엔진이 기록한 진행 파일 (.sprite-gen.progress.json) — 없으면 None."""try:- return json.loads((run_dir / ".sprite-gen.progress.json").read_text(encoding="utf-8"))+ return json.loads((run_dir / PROGRESS_REL).read_text(encoding="utf-8"))except (OSError, ValueError):return None@@ -392,11 +534,11 @@ def _build_run_state_impl(run_dir: Path) -> dict:cell = request["cell"]cell_state = {- "width": int(cell.get("width", cell.get("size", 0))),- "height": int(cell.get("height", cell.get("size", 0))),+ Wire.WIDTH: int(cell.get("width", cell.get("size", 0))),+ Wire.HEIGHT: int(cell.get("height", cell.get("size", 0))),# 안전영역/여백 알림 계산용 (여백 침범 = 정보성, 리롤 대상 아님)- "safeMarginX": int(cell.get("safe_margin_x", cell.get("safe_margin", 0))),- "safeMarginY": int(cell.get("safe_margin_y", cell.get("safe_margin", 0))),+ Wire.SAFE_MARGIN_X: int(cell.get("safe_margin_x", cell.get("safe_margin", 0))),+ Wire.SAFE_MARGIN_Y: int(cell.get("safe_margin_y", cell.get("safe_margin", 0))),}# 픽셀 언페이크 격자: 논리 픽셀 1칸이 셀 픽셀 몇 칸인가. extract 의 pp_scale 과 같은 식이어야@@ -408,8 +550,8 @@ def _build_run_state_impl(run_dir: Path) -> dict:# 빠져 있었고, 선언값을 그대로 라벨에 쓰면 정수 격자가 반올림한 뒤에도 "48px"# 처럼 거짓 표기가 된다 (maintainer 2026-07-25).scale = pixel_snap_scale(request) or 1- logical_height = effective_logical_height(request) or cell_state["height"]- pixel_unfake = {"logicalHeight": logical_height, "scale": scale, "source": "request", "label": f"{logical_height}px"}+ logical_height = effective_logical_height(request) or cell_state[Wire.HEIGHT]+ pixel_unfake = {Wire.LOGICAL_HEIGHT: logical_height, Wire.SCALE: scale, Wire.SOURCE: "request", Wire.LABEL: f"{logical_height}px"}states = []# 온디맨드 픽셀 프리뷰 계산 예산 (요청당) — 초과분은 deferred 로 세서 보고한다@@ -431,64 +573,64 @@ def _build_run_state_impl(run_dir: Path) -> dict:else:rel = f"{state_frames_rel}/frame-{index}.png"present = (run_dir / rel).is_file()- frame = {"index": index, "url": _url(*rel.split("/")), "present": present}+ frame = {Wire.INDEX: index, Wire.URL: _url(*rel.split("/")), Wire.PRESENT: present}# pp 해제 토글 표시본: 원본 화질(orig/ 고해상본) 우선, 없으면 셀 크기 .plain.png.# 둘 중 하나라도 있으면 큐레이터가 전/후 토글을 켠다.head, _, tail = rel.rpartition("/")orig_rel = f"{head}/orig/{tail}"plain_rel = rel[: -len(".png")] + ".plain.png"if (run_dir / orig_rel).is_file():- frame["plainUrl"] = _url(*orig_rel.split("/"))+ frame[Wire.PLAIN_URL] = _url(*orig_rel.split("/"))elif (run_dir / plain_rel).is_file():- frame["plainUrl"] = _url(*plain_rel.split("/"))+ frame[Wire.PLAIN_URL] = _url(*plain_rel.split("/"))# **굽기가 실제로 읽는 파일** — `row_frame_rel(row, i, "plain")` 과 같은 경로다.# 위 `plainUrl` 은 표시 화질용이라 `orig/` 고해상본을 우선하는데, 굽기는 그걸# 절대 안 읽는다. 호흡 프리뷰·신선도 판정이 `plainUrl` 을 쓰면 지문이 **영구# 불일치**라 그 줄의 영상 내보내기가 영구 차단된다 (validator 2026-07-26).if present:- frame["stamp"] = _file_stamp(run_dir / rel)+ frame[Wire.STAMP] = _file_stamp(run_dir / rel)if (run_dir / plain_rel).is_file():- frame["plainBakeUrl"] = _url(*plain_rel.split("/"))+ frame[Wire.PLAIN_BAKE_URL] = _url(*plain_rel.split("/"))# URL 과 **짝으로** 나간다. 굽기가 읽는 파일이 곧 호흡 기준 프레임 키의# 원본 조각이라, 둘 중 하나만 보내면 웹뷰가 키를 못 만든다.- frame["plainBakeStamp"] = _file_stamp(run_dir / plain_rel)+ frame[Wire.PLAIN_BAKE_STAMP] = _file_stamp(run_dir / plain_rel)# 트윈 없는 프레임의 퍼펙은 클라 렌더러가 측정 k(pixelScale)로 양자화한다# — 서버 추정 스냅 프리뷰 레거시는 표시 격자와 다른 검출기(엔진 주기성,# 1:1 에 4.99)로 스냅해 같은 줄의 프레임마다 다른 진실을 만들었다# (validator R1 기각, plan curator-single-display-pipeline 에서 삭제).if index < len(labels):- frame["label"] = labels[index]+ frame[Wire.LABEL] = labels[index]# 추출이 검출한 실제 절단선 (쌍둥이 셀 좌표) — 원본 화질 뷰의 최종 대응# 격자가 균등 분할 대신 이 선을 그린다 (중간 드리프트 제거)row_grids = row.get("input_grids") or []if index < len(row_grids) and row_grids[index]:- frame["inputGrid"] = row_grids[index]+ frame[Wire.INPUT_GRID] = row_grids[index]if present and Image is not None:# 실제 스프라이트 픽셀 크기(투명 패딩 제외 알파 bbox) — 사이즈 통일 검수용try:with Image.open(run_dir / rel) as im:- frame["size"] = [im.width, im.height]+ frame[Wire.SIZE] = [im.width, im.height]alpha = im.getchannel("A") if "A" in im.getbands() else Nonebbox = alpha.getbbox() if alpha is not None else im.getbbox()if bbox:- frame["contentSize"] = [bbox[2] - bbox[0], bbox[3] - bbox[1]]+ frame[Wire.CONTENT_SIZE] = [bbox[2] - bbox[0], bbox[3] - bbox[1]]# 최종 픽셀 콘텐츠 bbox(셀 좌표) — 원본 뷰의 "최종 대응 격자"# (칸 수 = 최종 픽셀 수)가 이 상자를 균등 분할해 그린다- frame["contentBox"] = list(bbox)+ frame[Wire.CONTENT_BOX] = list(bbox)except OSError:passframes.append(frame)state_scale = Noneif pixel_unfake is not None:- state_scale = pixel_unfake["scale"]+ state_scale = pixel_unfake[Wire.SCALE]else:for fr in frames:- if fr.get("present"):+ if fr.get(Wire.PRESENT):# measure from the real (decoded) file path, not fr["url"] — the url is# percent-encoded for HTTP, so a special-char state name would point the# measurement at a nonexistent encoded dir → pixelScale silently null.row_files_m = row.get("files") or []- rel_m = row_files_m[fr["index"]] if fr["index"] < len(row_files_m) else f"{state_frames_rel}/frame-{fr['index']}.png"+ rel_m = row_files_m[fr[Wire.INDEX]] if fr[Wire.INDEX] < len(row_files_m) else f"{state_frames_rel}/frame-{fr[Wire.INDEX]}.png"state_scale = detect_pixel_pitch(run_dir / rel_m)breakif state_scale is None:@@ -497,18 +639,18 @@ def _build_run_state_impl(run_dir: Path) -> dict:state_scale = 1states.append({- "name": state,- "rawPresent": raw_present,- "pixelScale": state_scale,- "refs": _state_refs(run_dir, state, request, anchor_views),- "fps": int(entry.get("fps", 6)),- "loop": bool(entry.get("loop", True)),- "action": entry.get("action", ""),- "requestFrames": frame_count,- "extractOk": bool(row.get("ok", bool(files))),- "frames": frames,+ Wire.NAME: state,+ Wire.RAW_PRESENT: raw_present,+ Wire.PIXEL_SCALE: state_scale,+ Wire.REFS: _state_refs(run_dir, state, request, anchor_views),+ Wire.FPS: int(entry.get("fps", 6)),+ Wire.LOOP: bool(entry.get("loop", True)),+ Wire.ACTION: entry.get("action", ""),+ Wire.REQUEST_FRAMES: frame_count,+ Wire.EXTRACT_OK: bool(row.get("ok", bool(files))),+ Wire.FRAMES: frames,# 테이크 선언 (호흡 에디터가 저장된 선/진폭을 복원하는 데 쓴다)- "takes": entry.get("takes") or [],+ Wire.TAKES: entry.get("takes") or [],})@@ -527,20 +669,20 @@ def _build_run_state_impl(run_dir: Path) -> dict:# 지금 이 방향의 identity 로 쓰이는 인스턴스 (지정 or 앵커 행 시퀀스 헤드)# — 뷰가 그 카드에 앵커 배지를 붙이고, 해석 실패는 이유를 보여준다.direction_groups.append({- "direction": direction,- "anchor": anchor if anchor in request["states"] else None,- "states": members,+ Wire.DIRECTION: direction,+ Wire.ANCHOR: anchor if anchor in request["states"] else None,+ Wire.STATES: members,**_anchor_group_fields(anchor_views.get(direction) or {}),})for target, source in (directions_cfg.get("mirror") or {}).items():- direction_groups.append({"direction": target, "mirrorOf": source, "states": []})+ direction_groups.append({Wire.DIRECTION: target, Wire.MIRROR_OF: source, Wire.STATES: []})# 방향 앵커 파일 (references/anchors/*.png) — 파일트리 표시용anchors_dir = run_dir / "references" / "anchors"anchor_files = []if anchors_dir.is_dir():for path in sorted(anchors_dir.glob("*.png")):- anchor_files.append({"name": path.name, "url": _url("run", "references", "anchors", path.name)})+ anchor_files.append({Wire.NAME: path.name, Wire.URL: _url("run", "references", "anchors", path.name)})# 원본 베이스(아이덴티티 truth)가 있으면 큐레이터 최상단에 참조 줄로 노출base_url = None@@ -551,53 +693,53 @@ def _build_run_state_impl(run_dir: Path) -> dict:# 뷰 계약 자가 보고 (run-contract.md §3): base 참조 줄 / 생성 재료 칩 / 픽셀 격자# 충족 여부. 셋 다 없으면 "소스 없는 뷰" — 세션마다 경험이 갈라지는 신호.has_base = base_url is not None- refs_states = sum(1 for st in states if st.get("refs"))+ refs_states = sum(1 for st in states if st.get(Wire.REFS))# 격자는 언제나 있다 — `detect_pixel_pitch` 가 실패할 수 없는 정확 판정이라# 모든 상태가 ≥1 의 scale 을 갖는다. 조건부 False 는 곧 컨트롤 숨김이었고# 그게 버그였다 (maintainer 2026-07-24).has_grid = Truecontract = {- "base": has_base,- "refs": refs_states > 0,- "refsStates": refs_states,- "grid": has_grid,+ Wire.BASE: has_base,+ Wire.REFS: refs_states > 0,+ Wire.REFS_STATES: refs_states,+ Wire.GRID: has_grid,# 격자가 보편이 된 뒤로는 판별자가 못 된다 — 항상 참인 항을 or 에 두면# sourceless 가 영원히 False 라 경고가 죽는다. 남은 판별자(base/refs)로만 본다.- "sourceless": not (has_base or refs_states > 0),+ Wire.SOURCELESS: not (has_base or refs_states > 0),}return {- "characterId": request["character"]["id"],- "runDir": str(run_dir),- "baseUrl": base_url,- "cell": cell_state,+ Wire.CHARACTER_ID: request["character"]["id"],+ Wire.RUN_DIR: str(run_dir),+ Wire.BASE_URL: base_url,+ Wire.CELL: cell_state,# 계약 scale(pp 런)이 없으면 줄별 실측이 진실이다 — null 로 접지 않는다.- "pixelUnfake": pixel_unfake if pixel_unfake is not None else {- "source": "auto", "label": "auto",- "scale": min((st["pixelScale"] for st in states if st.get("pixelScale")), default=1)},- "schemaVersion": SCHEMA_VERSION,- "runRevision": revision,+ Wire.PIXEL_UNFAKE: pixel_unfake if pixel_unfake is not None else {+ Wire.SOURCE: "auto", Wire.LABEL: "auto",+ Wire.SCALE: min((st[Wire.PIXEL_SCALE] for st in states if st.get(Wire.PIXEL_SCALE)), default=1)},+ Wire.SCHEMA_VERSION: SCHEMA_VERSION,+ Wire.RUN_REVISION: revision,# 호흡 기준 프레임 키의 조각 — 셀 크기·`pixel_snap_scale` 같은 request 파생값을# 웹뷰가 재구현하지 않고 원인 하나로 덮는다 (`breathe.reference_key` 주석).- "requestStamp": _file_stamp(run_dir / "sprite-request.json"),- "directionGroups": direction_groups,- "anchorFiles": anchor_files,- "states": states,- "curation": curation,+ Wire.REQUEST_STAMP: _file_stamp(run_dir / REQUEST_FILENAME),+ Wire.DIRECTION_GROUPS: direction_groups,+ Wire.ANCHOR_FILES: anchor_files,+ Wire.STATES: states,+ Wire.CURATION: curation,# 세대 불일치로 이번 로드에서 무효화(드롭)된 행 — 뷰가 배너로 알린다 (stderr 만으로는# 사용자가 못 본다; 조용한 소실 금지). 백업 파일명은 싣지 않는다: 로드는 아무것도# 쓰지 않고, 원문은 덮이는 순간 writer 가 백업한다 (`write_curation_atomic`).- "curationDropped": curation_report["dropped"],- "iso": request.get("iso"),- "lang": CurationHandler.lang,- "hasAtlas": (run_dir / "sprite-sheet-alpha.png").is_file(),+ Wire.CURATION_DROPPED: curation_report["dropped"],+ Wire.ISO: request.get("iso"),+ Wire.LANG: CurationHandler.lang,+ Wire.HAS_ATLAS: (run_dir / "sprite-sheet-alpha.png").is_file(),# 최종 산출물 섹션 (뷰 맨 아래, 아틀라스+manifest 좌우) — 파일이 실재할 때만.# 아틀라스는 다운로드/합성 시점 산출물이라 mtime 을 실어 시점을 표시한다.- "atlas": _atlas_info(run_dir),+ Wire.ATLAS: _atlas_info(run_dir),# 팔레트 스왑 베이크 산출물 (`<run>/variants/`) — 없으면 None (섹션 자체가 안 뜬다).- "recolor": _recolor_info(run_dir, curation),- "fitPixelUnfake": bool((request.get("fit") or {}).get("pixel_unfake")),+ Wire.RECOLOR: _recolor_info(run_dir, curation),+ Wire.FIT_PIXEL_UNFAKE: bool((request.get("fit") or {}).get("pixel_unfake")),# 예산에 밀려 아직 못 만든 온디맨드 픽셀 프리뷰 수 — 0 이 아니면 리로드가 이어서 계산- "contract": contract,+ Wire.CONTRACT: contract,}@@ -626,10 +768,10 @@ def _first_frame_rect(run_dir: Path) -> dict | None:cell = cells[0]try:return {- "x": int(cell["x"]), "y": int(cell["y"]),- "w": int(cell["w"]), "h": int(cell["h"]),- "sheetWidth": int(layout["sheetWidth"]),- "sheetHeight": int(layout["sheetHeight"]),+ Wire.X: int(cell["x"]), Wire.Y: int(cell["y"]),+ Wire.W: int(cell["w"]), Wire.H: int(cell["h"]),+ Wire.SHEET_WIDTH: int(layout["sheetWidth"]),+ Wire.SHEET_HEIGHT: int(layout["sheetHeight"]),}except (KeyError, TypeError, ValueError):return None@@ -661,17 +803,17 @@ def _recolor_info(run_dir: Path, curation: dict | None) -> dict | None:present = bool(sheet) and path.is_file()manifest_name = entry.get("manifest")variants.append({- "name": entry.get("name"),- "sheet": sheet,+ Wire.NAME: entry.get("name"),+ Wire.SHEET: sheet,# mtime cache-bust: a re-bake rewrites the same filename, and a stale# browser cache would show the previous colourway under the new name.- "url": (_url("run", VARIANTS_DIRNAME, sheet) + f"?v={int(path.stat().st_mtime)}") if present else None,- "present": present,- "substitutedPixels": entry.get("substituted_pixels"),- "passthroughPixels": entry.get("passthrough_pixels"),- "passthroughColorCount": entry.get("passthrough_color_count"),- "unusedSources": [record.get("from") for record in entry.get("unused_sources", [])],- "manifestUrl": (_url("run", VARIANTS_DIRNAME, str(manifest_name))+ Wire.URL: (_url("run", VARIANTS_DIRNAME, sheet) + f"?v={int(path.stat().st_mtime)}") if present else None,+ Wire.PRESENT: present,+ Wire.SUBSTITUTED_PIXELS: entry.get("substituted_pixels"),+ Wire.PASSTHROUGH_PIXELS: entry.get("passthrough_pixels"),+ Wire.PASSTHROUGH_COLOR_COUNT: entry.get("passthrough_color_count"),+ Wire.UNUSED_SOURCES: [record.get("from") for record in entry.get("unused_sources", [])],+ Wire.MANIFEST_URL: (_url("run", VARIANTS_DIRNAME, str(manifest_name))if isinstance(manifest_name, str) else None),})base_name = str(report.get("base") or "")@@ -679,21 +821,21 @@ def _recolor_info(run_dir: Path, curation: dict | None) -> dict | None:base_present = bool(base_name) and base_path.is_file()picked = recolor_pick(curation)return {- "dir": VARIANTS_DIRNAME,+ Wire.DIR: VARIANTS_DIRNAME,# 썸네일이 잘라 볼 프레임 상자 (없으면 시트 전체를 보여준다 — _first_frame_rect 참조)- "swatch": _first_frame_rect(run_dir),- "match": report.get("match"),- "tolerance": report.get("tolerance"),- "base": {- "name": base_name,- "url": (_url("run", base_name) + f"?v={int(base_path.stat().st_mtime)}") if base_present else None,- "present": base_present,+ Wire.SWATCH: _first_frame_rect(run_dir),+ Wire.MATCH: report.get("match"),+ Wire.TOLERANCE: report.get("tolerance"),+ Wire.BASE: {+ Wire.NAME: base_name,+ Wire.URL: (_url("run", base_name) + f"?v={int(base_path.stat().st_mtime)}") if base_present else None,+ Wire.PRESENT: base_present,},- "variants": variants,- "picked": picked,+ Wire.VARIANTS: variants,+ Wire.PICKED: picked,# The pick is stored by name; if the spec dropped that variant the name is# kept and flagged, so the view can say so instead of quietly un-picking.- "pickedKnown": picked is not None and any(v["name"] == picked for v in variants),+ Wire.PICKED_KNOWN: picked is not None and any(v[Wire.NAME] == picked for v in variants),}@@ -705,9 +847,9 @@ def _atlas_info(run_dir: Path) -> dict | None:mtime = int(atlas_path.stat().st_mtime)manifest_path = run_dir / "manifest.json"return {- "url": _url("run", "sprite-sheet-alpha.png") + f"?v={mtime}",- "mtime": mtime,- "manifestUrl": (_url("run", "manifest.json") + f"?v={mtime}") if manifest_path.is_file() else None,+ Wire.URL: _url("run", "sprite-sheet-alpha.png") + f"?v={mtime}",+ Wire.MTIME: mtime,+ Wire.MANIFEST_URL: (_url("run", "manifest.json") + f"?v={mtime}") if manifest_path.is_file() else None,}@@ -727,7 +869,7 @@ def _heal_attempt_key(run_dir: Path) -> tuple:"""from sprite_gen.frames.extract import engine_revision- paths = [run_dir / "sprite-request.json", run_dir / "curation.json",+ paths = [run_dir / REQUEST_FILENAME, run_dir / CURATION_FILENAME,run_dir / "frames" / "frames-manifest.json"]raw_dir = run_dir / "raw"if raw_dir.is_dir():@@ -766,8 +908,8 @@ def _durable_failed_heal_report(run_dir: Path, attempt_key: tuple) -> dict | Nonif not failed:failed = sorted({str(error).split(":", 1)[0] for error in failure.get("errors", [])if ":" in str(error)})- return {"healed": [], "kept_stale": [], "failed": failed,- "notes": ["same engine/input already failed validation; previous frames kept"]}+ return {HEAL_HEALED: [], HEAL_KEPT_STALE: [], HEAL_FAILED: failed,+ HEAL_NOTES: ["same engine/input already failed validation; previous frames kept"]}def _run_heal(run_dir: Path, attempt_key: tuple) -> None:@@ -776,12 +918,12 @@ def _run_heal(run_dir: Path, attempt_key: tuple) -> None:report = heal_run(run_dir)except (Exception, SystemExit) as exc:attempt_failed = True- report = {"healed": [], "kept_stale": [], "failed": [],- "notes": [f"heal skipped: {exc}"]}+ report = {HEAL_HEALED: [], HEAL_KEPT_STALE: [], HEAL_FAILED: [],+ HEAL_NOTES: [f"heal skipped: {exc}"]}with _heal_lock:- if report["healed"] or report["kept_stale"] or report.get("failed") or report["notes"]:+ if report[HEAL_HEALED] or report[HEAL_KEPT_STALE] or report.get(HEAL_FAILED) or report[HEAL_NOTES]:_heal_state["pending_report"] = report- if report.get("failed") or attempt_failed:+ if report.get(HEAL_FAILED) or attempt_failed:_heal_state["failed_attempt"] = attempt_keyelif _heal_state["failed_attempt"] == attempt_key:_heal_state["failed_attempt"] = None@@ -855,20 +997,20 @@ def build_download(run_dir: Path, kind: str) -> tuple[bytes, str] | dict:character = str(request.get("character", {}).get("id") or run_dir.name)if kind == "atlas":result = run_compose(run_dir)- if not result["ok"]:+ if not result[Wire.OK]:return resultfiles = [run_dir / "sprite-sheet-alpha.png", run_dir / "manifest.json"]files = [f for f in files if f.is_file()]return _zip_paths(run_dir, files), f"{character}-atlas.zip"if kind == "pngs":result = run_export(run_dir)- if not result["ok"]:+ if not result[Wire.OK]:return resultout = run_dir / "curated"return _zip_paths(run_dir, sorted(out.rglob("*.png"))), f"{character}-pngs.zip"if kind == "gifs":result = run_export_gif(run_dir)- if not result["ok"]:+ if not result[Wire.OK]:return resultout = run_dir / "exports"return _zip_paths(run_dir, sorted(out.glob("*.gif"))), f"{character}-gifs.zip"@@ -879,13 +1021,13 @@ def build_download(run_dir: Path, kind: str) -> tuple[bytes, str] | dict:state, _, scale_part = kind[len("gif:"):].partition(":")scale = max(1, min(8, int(scale_part or 4)))result = run_export_gif(run_dir, state=state, scale=scale)- if not result["ok"]:+ if not result[Wire.OK]:return resultgif_path = run_dir / "exports" / f"{state}.gif"if not gif_path.is_file():- return {"ok": False, "error": f"gif not produced: {gif_path}"}+ return {Wire.OK: False, Wire.ERROR: f"gif not produced: {gif_path}"}return gif_path.read_bytes(), f"{character}-{state}.gif"- return {"ok": False, "error": f"unknown download kind: {kind}"}+ return {Wire.OK: False, Wire.ERROR: f"unknown download kind: {kind}"}def _run_module(name: str, run_dir: Path, *extra: str) -> dict:@@ -905,10 +1047,10 @@ def _run_module(name: str, run_dir: Path, *extra: str) -> dict:text=True,)return {- "ok": proc.returncode == 0,- "returncode": proc.returncode,- "stdout": proc.stdout,- "stderr": proc.stderr,+ Wire.OK: proc.returncode == 0,+ Wire.RETURNCODE: proc.returncode,+ Wire.STDOUT: proc.stdout,+ Wire.STDERR: proc.stderr,}@@ -951,9 +1093,9 @@ def run_reroll(run_dir: Path, state: str, provider: str = gen_mod.HARD_DEFAULT_Pdef run_export(run_dir: Path) -> dict:"""Export curated frames back to named PNGs under <run-dir>/curated/."""result = _run_module("export_pngs", run_dir)- if result["ok"] and result["stdout"]:+ if result[Wire.OK] and result[Wire.STDOUT]:try:- result["export"] = json.loads(result["stdout"])+ result[Wire.EXPORT] = json.loads(result[Wire.STDOUT])except json.JSONDecodeError:passreturn result@@ -967,9 +1109,9 @@ def run_export_gif(run_dir: Path, state: str | None = None, scale: int = 1) -> d`state` limits to one row (`--state`) — the per-row download button path."""extra = (["--state", state] if state else []) + (["--scale", str(scale)] if scale > 1 else [])result = _run_module("compose_gif", run_dir, *extra)- if result["ok"] and result["stdout"]:+ if result[Wire.OK] and result[Wire.STDOUT]:try:- result["gif"] = json.loads(result["stdout"])+ result[Wire.GIF] = json.loads(result[Wire.STDOUT])except json.JSONDecodeError:passreturn result@@ -994,7 +1136,7 @@ class CurationHandler(BaseHTTPRequestHandler):def _send_file(self, path: Path) -> None:if not path.is_file():- self._send_json({"error": "not found", "path": str(path)}, 404)+ self._send_json({Wire.ERROR: "not found", Wire.PATH: str(path)}, 404)returndata = path.read_bytes()self.send_response(200)@@ -1033,35 +1175,35 @@ class CurationHandler(BaseHTTPRequestHandler):if busy:# 장기 heal 진행 중 — 첫 탭부터 진행률 로딩 UI 가 뜨도록 즉답self._send_json({- "error": "re-extraction in progress — frames are being "+ Wire.ERROR: "re-extraction in progress — frames are being ""re-derived for the current engine; the view opens ""automatically when it finishes",- "busy": True, "lang": CurationHandler.lang,- "progress": _read_op_progress(self.run_dir)}, 503)+ Wire.BUSY: True, Wire.LANG: CurationHandler.lang,+ Wire.PROGRESS: _read_op_progress(self.run_dir)}, 503)returnsnapshot = build_run_state(self.run_dir)heal = take_heal_report() # 스냅샷 성공 뒤에만 소비 (단일 소비자)if heal:- snapshot["heal"] = heal+ snapshot[Wire.HEAL] = healself._send_json(snapshot)except (Exception, SystemExit) as exc: # incl. load_frames_manifest fail-loud; no silent fallback# 재추출이 돌고 있으면 request(새 테이크 선언)와 manifest(이전 세대)가# 일시적으로 어긋난다 — corrupt 가 아니라 in-flight 다. 락 보유 중엔# 그렇게 말해준다 (회귀 2026-07-17: 보간 직후 로드가 'corrupt frames# manifest' 로 보여 사용자가 파손으로 오인).- if (self.run_dir / ".sprite-gen.lock").exists():- self._send_json({"error": "re-extraction in progress — "+ if (self.run_dir / LOCK_FILENAME).exists():+ self._send_json({Wire.ERROR: "re-extraction in progress — ""the run is being re-derived; reload when it finishes",- "busy": True, "progress": _read_op_progress(self.run_dir)}, 503)+ Wire.BUSY: True, Wire.PROGRESS: _read_op_progress(self.run_dir)}, 503)else:- self._send_json({"error": str(exc)}, 500)+ self._send_json({Wire.ERROR: str(exc)}, 500)returnif path == "/api/op-progress":# 오래 걸리는 파이프라인(추출 등)의 잘게 쪼갠 진행도 — 큐레이터가 폴링해# 퍼센트 표시 (maintainer 요청 2026-07-18). busy=락 보유 여부, progress=엔진 기록.self._send_json({- "busy": (self.run_dir / ".sprite-gen.lock").exists(),- "progress": _read_op_progress(self.run_dir),+ Wire.BUSY: (self.run_dir / LOCK_FILENAME).exists(),+ Wire.PROGRESS: _read_op_progress(self.run_dir),})returnif path == "/api/anchor":@@ -1073,7 +1215,7 @@ class CurationHandler(BaseHTTPRequestHandler):try:scale = max(1, min(16, int((query.get("scale") or ["8"])[0])))except ValueError:- self._send_json({"error": "scale must be an integer"}, 400)+ self._send_json({Wire.ERROR: "scale must be an integer"}, 400)returntry:from sprite_gen.curate import anchor as anchor_mod@@ -1085,7 +1227,7 @@ class CurationHandler(BaseHTTPRequestHandler):buffer = io.BytesIO()image.save(buffer, format="PNG")except (Exception, SystemExit) as exc:- self._send_json({"error": str(exc)}, 404)+ self._send_json({Wire.ERROR: str(exc)}, 404)returndata = buffer.getvalue()self.send_response(200)@@ -1111,13 +1253,13 @@ class CurationHandler(BaseHTTPRequestHandler):try:frame, key = _breathe_source_frame(self.run_dir, state)if frame is None:- self._send_json({"error": f"no extracted frame for state {state!r}"}, 404)+ self._send_json({Wire.ERROR: f"no extracted frame for state {state!r}"}, 404)returnfrozen = freeze_anatomy(frame, overrides, key)- self._send_json({"anatomy": frozen, "defaults": {- "depth": DEFAULT_DEPTH, "lag": DEFAULT_LAG, "breaths": 1}})+ self._send_json({Wire.ANATOMY: frozen, Wire.DEFAULTS: {+ Wire.DEPTH: DEFAULT_DEPTH, Wire.LAG: DEFAULT_LAG, Wire.BREATHS: 1}})except (Exception, SystemExit) as exc:- self._send_json({"error": str(exc)}, 500)+ self._send_json({Wire.ERROR: str(exc)}, 500)returnif path == "/api/base-grid":# 베이스의 검출 픽셀 격자 — 편집기(줌 모달)의 논리 해상도와 base-edit 의@@ -1125,11 +1267,11 @@ class CurationHandler(BaseHTTPRequestHandler):try:base_path = _find_base_path(self.run_dir)if base_path is None:- self._send_json({"error": "no base-source image in this run"}, 404)+ self._send_json({Wire.ERROR: "no base-source image in this run"}, 404)returnself._send_json(_base_grid_response(self.run_dir, base_path))except (Exception, SystemExit) as exc:- self._send_json({"error": str(exc)}, 500)+ self._send_json({Wire.ERROR: str(exc)}, 500)returnif path.startswith("/download/"):kind = path[len("/download/"):]@@ -1142,14 +1284,14 @@ class CurationHandler(BaseHTTPRequestHandler):busy = maybe_heal(self.run_dir) # 리포트 미소비 — 소비자는 /api/run 만if busy:self._send_json({- "error": "re-extraction in progress — retry the download "+ Wire.ERROR: "re-extraction in progress — retry the download ""when it finishes",- "busy": True,- "progress": _read_op_progress(self.run_dir)}, 503)+ Wire.BUSY: True,+ Wire.PROGRESS: _read_op_progress(self.run_dir)}, 503)returnbuilt = build_download(self.run_dir, kind)except (Exception, SystemExit) as exc:- self._send_json({"error": str(exc)}, 500)+ self._send_json({Wire.ERROR: str(exc)}, 500)returnif isinstance(built, dict):self._send_json(built, 500)@@ -1173,8 +1315,8 @@ class CurationHandler(BaseHTTPRequestHandler):busy = maybe_heal(self.run_dir) # 리포트 미소비 — 소비자는 /api/run 만if busy:# heal 이 publish 락을 쥔 동안 read_guard 에서 행 걸리지 않게 즉답- self._send_json({"busy": True,- "progress": _read_op_progress(self.run_dir)}, 503)+ self._send_json({Wire.BUSY: True,+ Wire.PROGRESS: _read_op_progress(self.run_dir)}, 503)returnwith read_guard(self.run_dir):request = load_request(self.run_dir)@@ -1187,23 +1329,23 @@ class CurationHandler(BaseHTTPRequestHandler):if state_dir.is_dir():count = sum(1 for f in state_dir.glob("frame-*.png") if not f.name.endswith(".plain.png"))progress.append({- "name": state,- "raw": (self.run_dir / state_raw).is_file(),- "frames": count,+ Wire.NAME: state,+ Wire.RAW: (self.run_dir / state_raw).is_file(),+ Wire.FRAMES: count,# 트리 썸네일용 실제 경로 URL (클라이언트 패턴 조립 금지)- "rawUrl": _url("run", *state_raw.split("/")),- "frame0Url": _url(*f"{state_frames}/frame-0.png".split("/")),- "relRaw": state_raw,- "relFrames": state_frames,+ Wire.RAW_URL: _url("run", *state_raw.split("/")),+ Wire.FRAME0_URL: _url(*f"{state_frames}/frame-0.png".split("/")),+ Wire.REL_RAW: state_raw,+ Wire.REL_FRAMES: state_frames,})- self._send_json({"states": progress, "runRevision": run_revision(self.run_dir)})+ self._send_json({Wire.STATES: progress, Wire.RUN_REVISION: run_revision(self.run_dir)})except (Exception, SystemExit) as exc:- self._send_json({"error": str(exc)}, 500)+ self._send_json({Wire.ERROR: str(exc)}, 500)returnif path.startswith("/curator/"):resolved = self._safe_path(CURATOR_DIR, path[len("/curator/"):])if resolved is None:- self._send_json({"error": "path escapes curator dir"}, 403)+ self._send_json({Wire.ERROR: "path escapes curator dir"}, 403)returnself._send_file(resolved)return@@ -1211,7 +1353,7 @@ class CurationHandler(BaseHTTPRequestHandler):rel = path[len("/run/"):] if path.startswith("/run/") else path[1:]resolved = self._safe_path(self.run_dir, rel)if resolved is None:- self._send_json({"error": "path escapes run dir"}, 403)+ self._send_json({Wire.ERROR: "path escapes run dir"}, 403)return# read_guard: serve run-dir files under the shared reader lock so a concurrent# publish swap can't 404 a file mid-move (reader isolation, same as /api/run).@@ -1221,12 +1363,12 @@ class CurationHandler(BaseHTTPRequestHandler):# bare static asset (curator.js / curator.css served from /)asset = self._safe_path(CURATOR_DIR, path.lstrip("/"))if asset is None:- self._send_json({"error": "path escapes curator dir"}, 403)+ self._send_json({Wire.ERROR: "path escapes curator dir"}, 403)returnif asset.is_file():self._send_file(asset)return- self._send_json({"error": "not found", "path": path}, 404)+ self._send_json({Wire.ERROR: "not found", Wire.PATH: path}, 404)def do_POST(self) -> None:path = urlparse(self.path).path@@ -1247,7 +1389,7 @@ class CurationHandler(BaseHTTPRequestHandler):# names but swapping the candidate images — old selections/transforms# must not apply to the new frames (Consistency: observable 409, not a# silent overwrite). runRevision is a content fingerprint of the frames.- stale = payload.get("runRevision") != run_revision(self.run_dir)+ stale = payload.get(Wire.RUN_REVISION) != run_revision(self.run_dir)if not stale:# 엔진-소유 사이드카 필드 보존: 클라이언트 payload 는 자기가 아는# 필드만 싣는다 — 에이전트/엔진이 심어둔 행 필드(frozen 등)가@@ -1298,10 +1440,10 @@ class CurationHandler(BaseHTTPRequestHandler):slot[field] = prev_entry[field]write_curation_atomic(self.run_dir, payload)if stale:- self._send_json({"error": "curation is from a different run generation "+ self._send_json({Wire.ERROR: "curation is from a different run generation ""(the run changed under this session; reload the view)"}, 409)else:- self._send_json({"ok": True})+ self._send_json({Wire.OK: True})returnif path == "/api/compare-gif":# 비교 캔버스 캡처 프레임들(PNG dataURL) → 투명 GIF 조립.@@ -1314,7 +1456,7 @@ class CurationHandler(BaseHTTPRequestHandler):except (TypeError, ValueError):duration_ms = 100if not isinstance(raw_frames, list) or not raw_frames or len(raw_frames) > 200:- self._send_json({"error": "frames: 1..200 data URLs required"}, 400)+ self._send_json({Wire.ERROR: "frames: 1..200 data URLs required"}, 400)returnimport base64from sprite_gen.util.gif_utils import save_clean_gif@@ -1326,16 +1468,16 @@ class CurationHandler(BaseHTTPRequestHandler):raise ValueError("expected image/png data URLs")images.append(Image.open(io.BytesIO(base64.b64decode(b64))).convert("RGBA"))except (ValueError, OSError) as exc:- self._send_json({"error": f"bad frame data: {exc}"}, 400)+ self._send_json({Wire.ERROR: f"bad frame data: {exc}"}, 400)return# 포맷 선택 (maintainer 2026-07-19 "webm/mp4 로도"): gif=save_clean_gif,# webm=VP9 알파 보존, mp4=x264 (알파 불가 — 화이트 배경 합성).fmt = str(payload.get("format", "gif")).lower()if fmt not in ("gif", "webm", "mp4"):- self._send_json({"error": "format: gif|webm|mp4"}, 400)+ self._send_json({Wire.ERROR: "format: gif|webm|mp4"}, 400)returnif fmt != "gif" and shutil.which("ffmpeg") is None:- self._send_json({"error": "ffmpeg not found on server machine (webm/mp4 assembly requires it)"}, 500)+ self._send_json({Wire.ERROR: "ffmpeg not found on server machine (webm/mp4 assembly requires it)"}, 500)returnwith tempfile.TemporaryDirectory() as td:out = Path(td) / f"compare.{fmt}"@@ -1362,7 +1504,7 @@ class CurationHandler(BaseHTTPRequestHandler):args.append(str(out))proc = subprocess.run(args, capture_output=True, text=True)if proc.returncode != 0 or not out.exists():- self._send_json({"error": f"ffmpeg failed: {proc.stderr[-300:]}"}, 500)+ self._send_json({Wire.ERROR: f"ffmpeg failed: {proc.stderr[-300:]}"}, 500)returndata = out.read_bytes()content_type = {"gif": "image/gif", "webm": "video/webm", "mp4": "video/mp4"}[fmt]@@ -1376,7 +1518,7 @@ class CurationHandler(BaseHTTPRequestHandler):returnif path == "/api/compose":result = run_compose(self.run_dir)- self._send_json(result, 200 if result["ok"] else 500)+ self._send_json(result, 200 if result[Wire.OK] else 500)returnif path == "/api/base-edit":# 베이스(base-source) 픽셀 편집 — 프레임과 달리 사이드카가 아니라@@ -1390,23 +1532,23 @@ class CurationHandler(BaseHTTPRequestHandler):if not isinstance(ops, dict):ops = {}if not ops and not transform_req:- self._send_json({"error": 'body needs ops {"x,y": "#rrggbb"|null} and/or transform'}, 400)+ self._send_json({Wire.ERROR: 'body needs ops {"x,y": "#rrggbb"|null} and/or transform'}, 400)returnbase_path = _find_base_path(self.run_dir)if base_path is None:- self._send_json({"error": "no base-source image in this run"}, 404)+ self._send_json({Wire.ERROR: "no base-source image in this run"}, 404)returnspace = str(payload.get("space") or "raw")grid = Noneif space == "logical":# 논리 셀 좌표 (줌 모달 편집 공간) — 검출 격자로 raw 블록에 확장.# 격자 SSoT = _base_grid_response (클라 표시와 동일 절단선).- grid = _base_grid_response(self.run_dir, base_path).get("grid")+ grid = _base_grid_response(self.run_dir, base_path).get(Wire.GRID)if not grid:- self._send_json({"error": "logical ops need a detected base grid"}, 422)+ self._send_json({Wire.ERROR: "logical ops need a detected base grid"}, 422)returnelif space != "raw":- self._send_json({"error": f"unknown ops space: {space}"}, 400)+ self._send_json({Wire.ERROR: f"unknown ops space: {space}"}, 400)returnrequest = load_request(self.run_dir)from sprite_gen.frames.cutout import KEY_TARGETS, MAGENTA@@ -1432,7 +1574,7 @@ class CurationHandler(BaseHTTPRequestHandler):else:fill = chroma + (255,) # 지우개 = 크로마 배경 복원if grid is not None:- xe, ye = grid["xEdges"], grid["yEdges"]+ xe, ye = grid[Wire.X_EDGES], grid[Wire.Y_EDGES]if not (0 <= x < len(xe) - 1 and 0 <= y < len(ye) - 1):continuefor ry in range(ye[y], ye[y + 1]):@@ -1453,16 +1595,16 @@ class CurationHandler(BaseHTTPRequestHandler):from sprite_gen.curate.curation import normalize_transform as _normalize_transformtnorm = dict(_normalize_transform(transform_req))if grid is not None:- tnorm["dx"] = tnorm.get("dx", 0.0) * grid["pitch"][0]- tnorm["dy"] = tnorm.get("dy", 0.0) * grid["pitch"][1]+ tnorm["dx"] = tnorm.get("dx", 0.0) * grid[Wire.PITCH][0]+ tnorm["dy"] = tnorm.get("dy", 0.0) * grid[Wire.PITCH][1]moved = _apply_transform(image, tnorm, (image.width, image.height))canvas = Image.new("RGBA", (image.width, image.height), chroma + (255,))canvas.alpha_composite(moved)image = canvasapplied += 1image.save(base_path)- self._send_json({"ok": True, "applied": applied, "space": space,- "backup": backup.name})+ self._send_json({Wire.OK: True, Wire.APPLIED: applied, Wire.SPACE: space,+ Wire.BACKUP: backup.name})returnif path == "/api/state-fps":# 줄 전체 재생 속도 = state fps (SSoT = sprite-request.json).@@ -1474,28 +1616,28 @@ class CurationHandler(BaseHTTPRequestHandler):try:fps = int(payload.get("fps"))except (TypeError, ValueError):- self._send_json({"error": "fps:int required"}, 400)+ self._send_json({Wire.ERROR: "fps:int required"}, 400)returnif not 1 <= fps <= 30:- self._send_json({"error": f"fps must be 1..30: {fps}"}, 400)+ self._send_json({Wire.ERROR: f"fps must be 1..30: {fps}"}, 400)returnwith publish_guard(self.run_dir):# 게이트 경유 (락 안이어도 안전 — 게이트는 읽기만 한다)request = load_request(self.run_dir)if state not in request.get("states", {}):- self._send_json({"error": f"unknown state: {state}"}, 400)+ self._send_json({Wire.ERROR: f"unknown state: {state}"}, 400)returnrequest["states"][state]["fps"] = fps# 쓰기도 게이트 경유 — fps 편집이 디스크 스키마를 바꾸지 않는다.write_request(self.run_dir, request)- self._send_json({"ok": True, "state": state, "fps": fps})+ self._send_json({Wire.OK: True, Wire.STATE: state, Wire.FPS: fps})returnif path == "/api/interpolate":payload = self._read_body()state = str(payload.get("state") or "")request = load_request(self.run_dir)if state not in request.get("states", {}):- self._send_json({"error": f"unknown state: {state}"}, 400)+ self._send_json({Wire.ERROR: f"unknown state: {state}"}, 400)returntry:index_a = int(payload["from"])@@ -1503,10 +1645,10 @@ class CurationHandler(BaseHTTPRequestHandler):t_value = float(payload.get("t", 0.5))except (KeyError, TypeError, ValueError):self._send_json(- {"error": "body needs integer 'from'/'to' (+ optional float 't')"}, 400)+ {Wire.ERROR: "body needs integer 'from'/'to' (+ optional float 't')"}, 400)returnif not 0.0 < t_value < 1.0:- self._send_json({"error": f"t must be inside (0, 1): {t_value}"}, 400)+ self._send_json({Wire.ERROR: f"t must be inside (0, 1): {t_value}"}, 400)returnprovider = str(payload.get("provider") or interpolate_mod.DEFAULT_PROVIDER)if provider not in CURATOR_PROVIDERS:@@ -1528,20 +1670,20 @@ class CurationHandler(BaseHTTPRequestHandler):self._send_json({"error": f"unknown provider: {provider}"}, 400)returnresult = run_reroll(self.run_dir, state, provider)- self._send_json(result, 200 if result["ok"] else 500)+ self._send_json(result, 200 if result[Wire.OK] else 500)returnif path == "/api/export":result = run_export(self.run_dir)- self._send_json(result, 200 if result["ok"] else 500)+ self._send_json(result, 200 if result[Wire.OK] else 500)returnif path == "/api/export-gif":result = run_export_gif(self.run_dir)- self._send_json(result, 200 if result["ok"] else 500)+ self._send_json(result, 200 if result[Wire.OK] else 500)returnexcept Exception as exc:- self._send_json({"error": str(exc)}, 500)+ self._send_json({Wire.ERROR: str(exc)}, 500)return- self._send_json({"error": "not found", "path": path}, 404)+ self._send_json({Wire.ERROR: "not found", Wire.PATH: path}, 404)def add_arguments(parser: argparse.ArgumentParser) -> None:@@ -1566,7 +1708,7 @@ def run(*, run_dir: Path, host: str = "127.0.0.1", port: int = 0,which is also what `main()` below calls — one implementation, no per-entrypoint branch."""run_dir = run_dir.expanduser().resolve()- if not (run_dir / "sprite-request.json").is_file():+ if not (run_dir / REQUEST_FILENAME).is_file():raise SystemExit(f"not a sprite-gen run dir (no sprite-request.json): {run_dir}")if not CURATOR_DIR.is_dir():raise SystemExit(f"missing curator SPA dir: {CURATOR_DIR}")@@ -1583,12 +1725,12 @@ def run(*, run_dir: Path, host: str = "127.0.0.1", port: int = 0,# 셋 다 없으면 "소스 없는 뷰" 경고 (관측 가능하게 — No Silent Fallback).try:snapshot = build_run_state(run_dir)- c = snapshot.get("contract", {})- n_states = len(snapshot.get("states", []))- print(f" view-contract: base={'yes' if c.get('base') else 'no'} · "- f"refs={c.get('refsStates', 0)}/{n_states} states · "- f"grid={'yes' if c.get('grid') else 'no'}")- if c.get("sourceless"):+ c = snapshot.get(Wire.CONTRACT, {})+ n_states = len(snapshot.get(Wire.STATES, []))+ print(f" view-contract: base={'yes' if c.get(Wire.BASE) else 'no'} · "+ f"refs={c.get(Wire.REFS_STATES, 0)}/{n_states} states · "+ f"grid={'yes' if c.get(Wire.GRID) else 'no'}")+ if c.get(Wire.SOURCELESS):print(" WARNING: sourceless view — no base-source, no generation-material refs, no pixel grid. ""이 뷰는 세션마다 경험이 갈라진다 (run-contract.md §3/§4: _base/_refs 동봉 또는 fit.pixel_unfake 권장).")except Exception as exc: # 계약 보고 실패는 서빙을 막지 않는다 — 관측만diff --git a/tests/curate/test_logical_height_contract.py b/tests/curate/test_logical_height_contract.pyindex bdc16d7..6f77f9d 100644--- a/tests/curate/test_logical_height_contract.py+++ b/tests/curate/test_logical_height_contract.py@@ -163,7 +163,7 @@ def test_scale_formula_has_a_single_owner():"""extract·웹뷰가 배율 식을 손으로 복제하지 않는다 (원칙 1).복제본은 실제로 갈렸다 — 웹뷰 사본에는 usable-height 클램프 분기가 없었다."""- formula = re.compile(r"cell(_state\[.height.\]|_height)\s*//\s*max\(1,\s*logical_height")+ formula = re.compile(r"cell(_state\[(.height.|Wire\.HEIGHT)\]|_height)\s*//\s*max\(1,\s*logical_height")for rel in ("sprite_gen/frames/extract.py", "sprite_gen/serve/serve_curation.py"):source = (REPO_ROOT / rel).read_text(encoding="utf-8")assert not formula.search(source), (diff --git a/tests/effects/test_breathe_sidecar_roundtrip.py b/tests/effects/test_breathe_sidecar_roundtrip.pyindex df1be79..32c2aba 100644--- a/tests/effects/test_breathe_sidecar_roundtrip.py+++ b/tests/effects/test_breathe_sidecar_roundtrip.py@@ -24,7 +24,7 @@ ROOT = Path(__file__).resolve().parent.parent.parentsys.path.insert(0, str(ROOT))from sprite_gen.effects.breathe import fit_breathe_pattern # noqa: E402-from sprite_gen.curate.curation import state_breathe # noqa: E402+from sprite_gen.curate.curation import CURATION_KIND, state_breathe # noqa: E402from sprite_gen.serve.serve_curation import CURATOR_DIR # noqa: E402CURATOR = CURATOR_DIR / "src"@@ -111,6 +111,8 @@ def test_curator_preserves_a_retired_breathe_sidecar(tmp_path):"frames": [{"index": 0, "present": True}, {"index": 1, "present": True}]}],"curation": {"states": {"idle": {"selected": [0, 1], "breathe": breathe}}}}got = _roundtrip(run, tmp_path)+ # 저장 payload 의 kind 가 다르면 서버(write_curation_atomic)가 모든 autosave 를 거부한다.+ assert got["payload"]["kind"] == CURATION_KIND, f"buildPayload 의 kind 가 갈렸다: {got['payload']['kind']!r}"saved = got["payload"]["states"]["idle"].get("breathe")assert saved is not None, "splits: 저장 payload 에서 breathe 가 통째로 사라졌다"assert "splits" in saved, "splits: 폐기 키가 삭제됐다 — migrate 근거가 파괴된다"diff --git a/tests/serve/test_curator_wire_keys.py b/tests/serve/test_curator_wire_keys.pynew file mode 100644index 0000000..3d8c3a6--- /dev/null+++ b/tests/serve/test_curator_wire_keys.py@@ -0,0 +1,353 @@+# SPDX-License-Identifier: Apache-2.0+"""The keys the servers put on the wire and the screens read are declared once.++`serve_curation.py` builds every JSON body the curator (`curator/src/*.js`) reads, and+`serve_compose.py` every body the composer (`composer/src/*.js`) reads. A key spelt one+letter apart on the two sides is no error anywhere: the screen reads `undefined` and+quietly shows nothing (`extractOk` -> `extractOK` left every test green). So each server+declares its keys once (`Wire`), writes every body through those names, and this file+holds the screen to them:++1. Every key the screen reads is found in the comment-stripped scripts **with the object+ it is read from**, built from the declared value. Looking for the bare token is not+ enough: `cell` -> `cells`, `takes` -> `take`, `anchor` -> `anchors`, `sheet` -> `sheets`,+ `defaults` -> `default`, `breaths` -> `breath` and `dir` -> `dirs` each land on a word+ the scripts already use for something else.+2. Every declared key is either read that way or listed as unread here — a new key has to+ say which.+3. The servers write no key as a bare string literal (dict key or subscript store), apart+ from the other vocabularies listed below, and every `Wire.X` they name exists. The+ second half matters because the curation server's `do_POST` catch-all turns a+ misspelt name into a quiet HTTP 500 on routes no other test calls.+"""++from __future__ import annotations++import ast+import re+from collections import Counter+from pathlib import Path++from sprite_gen.curate.curation import IMPORTED_REF_ROLES+from sprite_gen.frames import extract+from sprite_gen.serve import serve_compose, serve_curation+from test_curator_single_display_pipeline import _no_comment++W = serve_curation.Wire+C = serve_compose.Wire+++def _scripts(src: Path) -> str:+ return "\n".join(_no_comment(p.read_text(encoding="utf-8"), "js") for p in sorted(src.glob("*.js")))+++CURATOR_JS = _scripts(serve_curation.CURATOR_DIR / "src")+COMPOSER_JS = _scripts(serve_compose.COMPOSER_DIR / "src")+++def _member(parent: str, *keys: str) -> str:+ """`parent.key[.key]` as a whole read — the object the value is read from, then the key."""+ return r"\b" + re.escape(parent) + "".join(r"\." + re.escape(key) for key in keys) + r"\b"+++# ── curator ──────────────────────────────────────────────────────────++# Key -> where the curator reads it (one pattern per object it is read from).+CURATOR_READS: dict[str, tuple[str, ...]] = {+ # /api/run+ W.CHARACTER_ID: (_member("run", W.CHARACTER_ID),),+ W.RUN_DIR: (_member("run", W.RUN_DIR),),+ W.BASE_URL: (_member("run", W.BASE_URL),),+ W.CELL: (_member("run", W.CELL, W.WIDTH),),+ W.PIXEL_UNFAKE: (_member("run", W.PIXEL_UNFAKE, W.SCALE),),+ W.SCHEMA_VERSION: (_member("run", W.SCHEMA_VERSION),),+ W.RUN_REVISION: (_member("run", W.RUN_REVISION), _member("next", W.RUN_REVISION)),+ W.REQUEST_STAMP: (_member("run", W.REQUEST_STAMP),),+ W.DIRECTION_GROUPS: (_member("run", W.DIRECTION_GROUPS),),+ W.ANCHOR_FILES: (_member("run", W.ANCHOR_FILES),),+ W.STATES: (_member("run", W.STATES), _member("next", W.STATES), _member("group", W.STATES)),+ W.CURATION: (_member("run", W.CURATION),),+ W.CURATION_DROPPED: (_member("run", W.CURATION_DROPPED),),+ W.ISO: (_member("run", W.ISO),),+ W.LANG: (_member("run", W.LANG),),+ W.HAS_ATLAS: (_member("run", W.HAS_ATLAS),),+ W.ATLAS: (_member("run", W.ATLAS),),+ W.RECOLOR: (_member("run", W.RECOLOR),),+ W.FIT_PIXEL_UNFAKE: (_member("run", W.FIT_PIXEL_UNFAKE),),+ W.HEAL: (_member("run", W.HEAL),),+ # cell, pixelUnfake+ W.WIDTH: (_member("run", W.CELL, W.WIDTH),),+ W.HEIGHT: (_member("run", W.CELL, W.HEIGHT),),+ W.SCALE: (_member("run", W.PIXEL_UNFAKE, W.SCALE),),+ W.LABEL: (_member("run", W.PIXEL_UNFAKE, W.LABEL), _member("frame", W.LABEL)),+ # states[]+ W.NAME: (_member("state", W.NAME), _member("p", W.NAME), _member("r", W.NAME), _member("a", W.NAME),+ _member("v", W.NAME), _member("info", W.BASE, W.NAME)),+ W.RAW_PRESENT: (_member("state", W.RAW_PRESENT),),+ W.PIXEL_SCALE: (_member("st", W.PIXEL_SCALE),),+ W.REFS: (_member("state", W.REFS),),+ W.FPS: (_member("state", W.FPS),),+ W.LOOP: (_member("state", W.LOOP),),+ W.ACTION: (_member("state", W.ACTION),),+ W.REQUEST_FRAMES: (_member("state", W.REQUEST_FRAMES),),+ W.EXTRACT_OK: (_member("state", W.EXTRACT_OK),),+ W.FRAMES: (_member("st", W.FRAMES), _member("p", W.FRAMES)),+ W.TAKES: (_member("st", W.TAKES),),+ # states[].frames[]+ W.INDEX: (_member("frame", W.INDEX),),+ W.URL: (_member("frame", W.URL), _member("r", W.URL), _member("a", W.URL), _member("v", W.URL),+ _member("info", W.URL), _member("info", W.BASE, W.URL), _member("run", W.ATLAS, W.URL)),+ W.PRESENT: (_member("frame", W.PRESENT), _member("v", W.PRESENT), _member("info", W.BASE, W.PRESENT)),+ W.PLAIN_URL: (_member("frame", W.PLAIN_URL),),+ W.STAMP: (_member("frame", W.STAMP),),+ W.PLAIN_BAKE_URL: (_member("frame", W.PLAIN_BAKE_URL),),+ W.PLAIN_BAKE_STAMP: (_member("frame", W.PLAIN_BAKE_STAMP),),+ W.INPUT_GRID: (_member("frame", W.INPUT_GRID),),+ W.CONTENT_SIZE: (_member("frame", W.CONTENT_SIZE),),+ W.CONTENT_BOX: (_member("frame", W.CONTENT_BOX),),+ # states[].refs[]+ W.ROLE: (_member("r", W.ROLE),),+ W.ANCHOR_FRAME: (_member("r", W.ANCHOR_FRAME),),+ # directionGroups[]+ W.DIRECTION: (_member("group", W.DIRECTION),),+ W.ANCHOR: (_member("group", W.ANCHOR),),+ W.ANCHOR_ERROR: (_member("g", W.ANCHOR_ERROR),),+ W.ANCHOR_PENDING: (_member("g", W.ANCHOR_PENDING),),+ W.ANCHOR_URL: (_member("g", W.ANCHOR_URL),),+ W.MIRROR_OF: (_member("group", W.MIRROR_OF),),+ # atlas+ W.MTIME: (_member("info", W.MTIME),),+ W.MANIFEST_URL: (_member("info", W.MANIFEST_URL), _member("v", W.MANIFEST_URL)),+ # recolor+ W.DIR: (_member("run", W.RECOLOR, W.DIR),),+ W.SWATCH: (_member("info", W.SWATCH),),+ W.MATCH: (_member("info", W.MATCH),),+ W.TOLERANCE: (_member("info", W.TOLERANCE),),+ W.BASE: (_member("info", W.BASE, W.URL),),+ W.VARIANTS: (_member("run", W.RECOLOR, W.VARIANTS), _member("info", W.VARIANTS)),+ W.PICKED: (_member("runState", W.RECOLOR, W.PICKED), _member("info", W.PICKED)),+ W.PICKED_KNOWN: (_member("info", W.PICKED_KNOWN),),+ W.X: (_member("swatch", W.X),),+ W.Y: (_member("swatch", W.Y),),+ W.W: (_member("swatch", W.W),),+ W.H: (_member("swatch", W.H),),+ W.SHEET_WIDTH: (_member("swatch", W.SHEET_WIDTH),),+ W.SHEET: (_member("v", W.SHEET),),+ W.SUBSTITUTED_PIXELS: (_member("v", W.SUBSTITUTED_PIXELS),),+ W.PASSTHROUGH_PIXELS: (_member("v", W.PASSTHROUGH_PIXELS),),+ W.UNUSED_SOURCES: (_member("v", W.UNUSED_SOURCES),),+ # replies+ W.ERROR: (_member("run", W.ERROR), _member("data", W.ERROR)),+ W.BUSY: (_member("run", W.BUSY), _member("data", W.BUSY)),+ W.PROGRESS: (_member("data", W.PROGRESS),),+ # /api/progress+ W.RAW: (_member("p", W.RAW),),+ W.RAW_URL: (_member("p", W.RAW_URL),),+ W.FRAME0_URL: (_member("p", W.FRAME0_URL),),+ W.REL_RAW: (f'"{W.REL_RAW}"',),+ W.REL_FRAMES: (f'"{W.REL_FRAMES}"',),+ # /api/breathe-anatomy+ W.ANATOMY: (rf"\{{ {W.ANATOMY}, {W.DEFAULTS} \}} = await fetchBreatheAnatomy\(",),+ W.DEFAULTS: (rf"\{{ {W.ANATOMY}, {W.DEFAULTS} \}} = await fetchBreatheAnatomy\(",),+ W.DEPTH: (_member("defaults", W.DEPTH),),+ W.LAG: (_member("defaults", W.LAG),),+ W.BREATHS: (_member("defaults", W.BREATHS),),+ # /api/base-grid+ W.GRID: (rf'fetch\("/api/base-grid"\)\)\.json\(\)\)\.{W.GRID}\b',),+ W.X_EDGES: (_member("grid", W.X_EDGES),),+ W.Y_EDGES: (_member("grid", W.Y_EDGES),),+ # POST results+ W.OK: (_member("data", W.OK),),+ W.STDERR: (_member("data", W.STDERR),),+ W.APPLIED: (_member("data", W.APPLIED),),+ # download header+ W.FILENAME_HEADER: (rf'headers\.get\("{W.FILENAME_HEADER}"\)',),+}++# On the wire, read by no script (dropping one changes the response bytes and any outside+# caller, so they stay; listed here so a new key has to say which kind it is).+CURATOR_UNREAD = {+ W.SAFE_MARGIN_X, W.SAFE_MARGIN_Y, W.LOGICAL_HEIGHT, W.SOURCE, W.STATE, W.ANCHOR_ERROR_CODE,+ W.CONTRACT, W.REFS_STATES, W.SOURCELESS, W.SHEET_HEIGHT, W.PASSTHROUGH_COLOR_COUNT, W.SIZE,+ W.PATH, W.NOTE, W.PITCH, W.RETURNCODE, W.STDOUT, W.EXPORT, W.GIF, W.SPACE, W.BACKUP,+}++# Keys other modules own that reach the curator inside a body: the heal report+# (`extract.heal_run`, relayed as `run.heal`) and the progress file (`extract._write_progress`,+# relayed as `progress`), plus the values the screen branches on.+CURATOR_READS_OF_OTHERS: dict[str, tuple[str, ...]] = {+ extract.HEAL_HEALED: (_member("run", W.HEAL, extract.HEAL_HEALED),),+ extract.HEAL_KEPT_STALE: (_member("run", W.HEAL, extract.HEAL_KEPT_STALE),),+ extract.HEAL_FAILED: (_member("run", W.HEAL, extract.HEAL_FAILED),),+ extract.PROGRESS_DONE: (_member("p", extract.PROGRESS_DONE),),+ extract.PROGRESS_TOTAL: (_member("p", extract.PROGRESS_TOTAL),),+ extract.PROGRESS_LABEL: (_member("p", extract.PROGRESS_LABEL),),+ extract.PROGRESS_PHASE: (rf'\bp\.{extract.PROGRESS_PHASE} === "{extract.PROGRESS_PHASE_COMPONENTS}"',),+ **{f"ref_{role}": (rf"\bref_{role}:",) for role in IMPORTED_REF_ROLES},+}++# Dict keys and stores in serve_curation.py that are not on the curator wire: other+# vocabularies the module also writes. Dicts by the def (or module table) they are in,+# stores by the name of the object they write into; "*" = every key.+CURATOR_OTHER_DICTS = {+ ("CONTENT_TYPES", "*"), # file suffix -> HTTP Content-Type+ ("_heal_state", "*"), # the heal thread's slots, server-side only+ ("_breathe_source_frame", "rows"), # frames-manifest default+ ("_build_run_state_impl", "rows"), # frames-manifest default+ ("_anchor_views", "url"), # the inner anchor view, read back by _state_refs+ ("CurationHandler.do_POST", "gif"), # compare format -> MIME+ ("CurationHandler.do_POST", "webm"),+ ("CurationHandler.do_POST", "mp4"),+}+CURATOR_OTHER_STORES = {+ ("_heal_state", "*"),+ ("payload", "anchors"), # curation.json keys a save does not author, carried over+ ("payload", "recolor"),+ ("payload", "pixel_unfake"),+ ("tnorm", "dx"), # curation transform keys+ ("tnorm", "dy"),+ ("request", "fps"), # sprite-request.json+}+# Left as text in this change: the replies on the curator's provider lines, which another+# change in the same plan rewrites; they move to `Wire.ERROR` with it.+CURATOR_LEFT_AS_TEXT = Counter({+ '{"error": f"unknown provider: {provider}"}': 2,+ '{"error": f"unknown state: {state}"}': 1,+})+++def _owner(stack: list[ast.AST]) -> str:+ """The innermost def as a dotted name (classes included), or "" at module level."""+ return ".".join(n.name for n in stack if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)))+++def _root_name(node: ast.AST) -> str:+ while isinstance(node, (ast.Subscript, ast.Attribute)):+ node = node.value+ return node.id if isinstance(node, ast.Name) else ""+++def _raw_keys(source: str, other_dicts: set, other_stores: set) -> list[tuple[int, str, str]]:+ """(line, key, source of the dict or store) for every str literal written as a dict key or+ subscript store that is not one of the listed other vocabularies."""+ tree = ast.parse(source)+ found: list[tuple[int, str, str]] = []++ def listed(entries: set, owner: str, key: str) -> bool:+ return (owner, key) in entries or (owner, "*") in entries++ def visit(node: ast.AST, stack: list[ast.AST], table: str) -> None:+ if isinstance(node, ast.Dict):+ owner = table or _owner(stack)+ for key in node.keys:+ if isinstance(key, ast.Constant) and isinstance(key.value, str) \+ and not listed(other_dicts, owner, key.value):+ found.append((key.lineno, key.value, ast.get_source_segment(source, node)))+ if isinstance(node, ast.Subscript) and isinstance(node.ctx, ast.Store) \+ and isinstance(node.slice, ast.Constant) and isinstance(node.slice.value, str) \+ and not listed(other_stores, _root_name(node.value), node.slice.value):+ found.append((node.lineno, node.slice.value, ast.get_source_segment(source, node)))+ inner = stack + [node] if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) else stack+ for child in ast.iter_child_nodes(node):+ child_table = table+ if not stack and isinstance(node, (ast.Assign, ast.AnnAssign)):+ targets = node.targets if isinstance(node, ast.Assign) else [node.target]+ child_table = next((t.id for t in targets if isinstance(t, ast.Name)), table)+ visit(child, inner, child_table)++ visit(tree, [], "")+ return found+++def _undeclared(source: str, namespace: type) -> list[tuple[int, str]]:+ return [(node.lineno, node.attr) for node in ast.walk(ast.parse(source))+ if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name)+ and node.value.id == namespace.__name__ and not hasattr(namespace, node.attr)]+++def _declared(namespace: type) -> dict[str, str]:+ return {name: value for name, value in vars(namespace).items() if name.isupper()}+++def _missing_reads(reads: dict[str, tuple[str, ...]], scripts: str) -> list[str]:+ return [f"{key}: {pattern}" for key, patterns in reads.items() for pattern in patterns+ if not re.search(pattern, scripts)]+++def test_the_curator_reads_every_key_from_the_object_the_server_puts_it_on():+ missing = _missing_reads({**CURATOR_READS, **CURATOR_READS_OF_OTHERS}, CURATOR_JS)+ assert not missing, ("the curator no longer reads these keys as declared — a key renamed "+ "on one side only:\n" + "\n".join(missing))+++def test_every_curator_key_is_read_or_listed_as_unread():+ declared = _declared(W)+ values = list(declared.values())+ assert len(values) == len(set(values)), \+ f"one key declared twice: {[v for v, n in Counter(values).items() if n > 1]}"+ assert not set(CURATOR_READS) & CURATOR_UNREAD+ assert set(values) == set(CURATOR_READS) | CURATOR_UNREAD, (+ f"declared but neither read nor listed unread: {sorted(set(values) - set(CURATOR_READS) - CURATOR_UNREAD)}; "+ f"listed but not declared: {sorted(set(CURATOR_READS) | CURATOR_UNREAD - set(values))}")+++def test_serve_curation_writes_no_wire_key_as_text():+ source = Path(serve_curation.__file__).read_text(encoding="utf-8")+ raw = _raw_keys(source, CURATOR_OTHER_DICTS, CURATOR_OTHER_STORES)+ left = Counter(text for _, _, text in raw if text in CURATOR_LEFT_AS_TEXT)+ raw = [site for site in raw if site[2] not in CURATOR_LEFT_AS_TEXT]+ assert not raw, (f"{len(raw)} keys written as text in serve_curation.py — name them in `Wire` "+ "(or, if not on the wire, list them above):\n"+ + "\n".join(f" {line}: {key!r}" for line, key, _ in raw))+ assert left == CURATOR_LEFT_AS_TEXT, f"the text left for the provider change moved: {dict(left)}"+++def test_every_wire_name_the_servers_use_is_declared():+ for module, namespace in ((serve_curation, W), (serve_compose, C)):+ source = Path(module.__file__).read_text(encoding="utf-8")+ assert not _undeclared(source, namespace), \+ f"{module.__name__}: Wire names that do not exist: {_undeclared(source, namespace)}"+++# ── composer ─────────────────────────────────────────────────────────++COMPOSER_READS: dict[str, tuple[str, ...]] = {+ C.DIR: (_member("picked", C.DIR),),+ C.ENTRIES: (_member("data", C.ENTRIES),),+ C.NAME: (_member("entry", C.NAME),),+ C.PATH: (_member("entry", C.PATH),),+ C.TYPE: (rf'\bentry\.{C.TYPE} === "{serve_compose.TYPE_DIR}"',),+ C.LANG: (_member("state", C.LANG),),+ C.MOUNT: (_member("state", C.MOUNT), _member("data", C.MOUNT)),+ C.CANCELLED: (_member("picked", C.CANCELLED),),+ C.RUN_DIR: (_member("data", C.RUN_DIR),),+ C.STATES: (_member("data", C.STATES),),+ C.FRAMES: (_member("data", C.FRAMES),),+ C.URL: (_member("data", C.URL),),+ C.ERROR: (_member("data", C.ERROR),),+}+COMPOSER_UNREAD = {C.FILES, C.CELL, C.CODE}+COMPOSER_OTHER_DICTS = {+ ("CONTENT_TYPES", "*"), # file suffix -> HTTP Content-Type+ ("_PICK_SCRIPTS", "*"), # pick kind -> osascript+ ("_build_groups", "*"), # import_png_groups' group shape+}+++def test_the_composer_reads_every_key_from_the_object_the_server_puts_it_on():+ missing = _missing_reads(COMPOSER_READS, COMPOSER_JS)+ assert not missing, ("the composer no longer reads these keys as declared:\n" + "\n".join(missing))+++def test_every_composer_key_is_read_or_listed_as_unread():+ values = list(_declared(C).values())+ assert len(values) == len(set(values))+ assert not set(COMPOSER_READS) & COMPOSER_UNREAD+ assert set(values) == set(COMPOSER_READS) | COMPOSER_UNREAD+++def test_serve_compose_writes_no_wire_key_as_text():+ source = Path(serve_compose.__file__).read_text(encoding="utf-8")+ raw = _raw_keys(source, COMPOSER_OTHER_DICTS, set())+ assert not raw, (f"{len(raw)} keys written as text in serve_compose.py:\n"+ + "\n".join(f" {line}: {key!r}" for line, key, _ in raw))diff --git a/tests/serve/test_pixel_grid_always_available.py b/tests/serve/test_pixel_grid_always_available.pyindex 4b060f4..51f80f4 100644--- a/tests/serve/test_pixel_grid_always_available.py+++ b/tests/serve/test_pixel_grid_always_available.py@@ -76,7 +76,8 @@ def test_server_never_reports_grid_as_absent():"has_grid 가 조건식으로 되돌아갔다 — 조건이 곧 컨트롤 숨김이다")# pixelUnfake 가 null 로 접히면 클라의 contractScale 이 사라진다- assert not re.search(r'"pixelUnfake":[^\n]*else None', SERVE), (+ assert "Wire.PIXEL_UNFAKE:" in SERVE, "pixelUnfake 를 쓰는 줄의 모양이 바뀌었다 — 아래 부재 검사가 빈 검사가 된다"+ assert not re.search(r"Wire\.PIXEL_UNFAKE:[^\n]*else None", SERVE), ("pixelUnfake 를 None 으로 접는 분기 부활 — 격자 scale 이 사라진다")