Skip to content

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.py
index 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_request
from sprite_gen.util.resample import transform_cell
CURATION_FILENAME = "curation.json"
+CURATION_KIND = "sprite-gen-curation" # 큐레이터 persistence.js 의 저장 payload 도 이 값이다
SCHEMA_VERSION = 1
IDENTITY = {"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[str
return None, report
raw_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.py
index 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 = 0
for 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 += 1
if 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_FILENAME
if 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 report
PROGRESS_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, p
import time as _time
try:
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:
pass
diff --git a/sprite_gen/qa/motion.py b/sprite_gen/qa/motion.py
index 39be2dc..66bfedb 100644
--- a/sprite_gen/qa/motion.py
+++ b/sprite_gen/qa/motion.py
@@ -29,7 +29,8 @@ from sprite_gen._deps import np
from PIL import Image
from 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_kwargs
from 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.py
index c22554c..c29bb05 100644
--- a/sprite_gen/serve/serve_compose.py
+++ b/sprite_gen/serve/serve_compose.py
@@ -47,6 +47,7 @@ from pathlib import Path
from urllib.parse import parse_qs, unquote, urlparse
from sprite_gen.frames.unpack_atlas import import_png_groups
+from sprite_gen.spec.runio import REQUEST_FILENAME
from 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:
continue
try:
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)
return
self._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)
return
self._send_file(index)
return
if 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,
})
return
if 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)
return
requested = 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)
return
if 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)
return
requested = 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)
return
if 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)
return
self._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)
return
raw = (payload.get("dir") or "").strip()
if not raw:
- self._send_json({"error": "dir required"}, 400)
+ self._send_json({Wire.ERROR: "dir required"}, 400)
return
candidate = 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)
return
ComposeHandler.mount_root = candidate
- self._send_json({"mount": str(candidate), **_list_dir(candidate, candidate)})
+ self._send_json({Wire.MOUNT: str(candidate), **_list_dir(candidate, candidate)})
return
if 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)
return
if 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)
return
length = 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)
return
raw_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)
return
out_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)
return
try:
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)
return
except FileNotFoundError as exc:
- self._send_json({"error": str(exc)}, 404)
+ self._send_json({Wire.ERROR: str(exc)}, 404)
return
if 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)
return
out_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")})
return
if 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)
return
run_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)
return
port = _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.py
index 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_mod
from sprite_gen import gen as gen_mod
from sprite_gen.gen.base import PROVIDER_CODEX, PROVIDER_GROK
from 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_hex
from sprite_gen._modules import qualified
from 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] = result
return 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_rel
if 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 None
if base and direction != "down":
basis_rel = raw_rel(request, f"down_{base}")
basis = run_dir / basis_rel
if 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 None
bbox = 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:
pass
frames.append(frame)
state_scale = None
if 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)
break
if state_scale is None:
@@ -497,18 +639,18 @@ def _build_run_state_impl(run_dir: Path) -> dict:
state_scale = 1
states.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 = True
contract = {
- "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 | Non
if 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_key
elif _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 result
files = [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 result
out = 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 result
out = 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 result
gif_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_P
def 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:
pass
return 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:
pass
return 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)
return
data = 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)
return
snapshot = build_run_state(self.run_dir)
heal = take_heal_report() # 스냅샷 성공 뒤에만 소비 (단일 소비자)
if heal:
- snapshot["heal"] = heal
+ snapshot[Wire.HEAL] = heal
self._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)
return
if 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),
})
return
if 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)
return
try:
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)
return
data = 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)
return
frozen = 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)
return
if 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)
return
self._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)
return
if 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)
return
built = 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)
return
if 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)
return
with 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)
return
if 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)
return
self._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)
return
if 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})
return
if path == "/api/compare-gif":
# 비교 캔버스 캡처 프레임들(PNG dataURL) → 투명 GIF 조립.
@@ -1314,7 +1456,7 @@ class CurationHandler(BaseHTTPRequestHandler):
except (TypeError, ValueError):
duration_ms = 100
if 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)
return
import base64
from 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)
return
if 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)
return
with 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)
return
data = out.read_bytes()
content_type = {"gif": "image/gif", "webm": "video/webm", "mp4": "video/mp4"}[fmt]
@@ -1376,7 +1518,7 @@ class CurationHandler(BaseHTTPRequestHandler):
return
if 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)
return
if 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)
return
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)
return
space = str(payload.get("space") or "raw")
grid = None
if 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)
return
elif space != "raw":
- self._send_json({"error": f"unknown ops space: {space}"}, 400)
+ self._send_json({Wire.ERROR: f"unknown ops space: {space}"}, 400)
return
request = 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):
continue
for 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_transform
tnorm = 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 = canvas
applied += 1
image.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})
return
if 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)
return
if 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)
return
with 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)
return
request["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})
return
if 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)
return
try:
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)
return
if 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)
return
provider = 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)
return
result = 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)
return
if 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)
return
if 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)
return
except 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.py
index 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.py
index 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.parent
sys.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: E402
from sprite_gen.serve.serve_curation import CURATOR_DIR # noqa: E402
CURATOR = 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.py
new file mode 100644
index 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.py
index 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 이 사라진다"
)