@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/phaser/skills/playable-verify-ui/scripts/lib/runtime_contract.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Static scan for the Playable ⇄ Harness runtime contract.
+ *
+ * The recording/debug harness (skills/playable-record, skills/playable-debug)
+ * drives every playable through fixed runtime hooks. If the game code drops one
+ * of them, `record:mp4` and one-click clear silently time out. This scanner lets
+ * `verify:ui` and the STOP hook fail fast and loudly instead.
+ *
+ * Keep these symbols in sync with:
+ *   - game/runtime-contract.ts
+ *   - skills/playable-record/scripts/record-playable.mjs
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const LEGACY_SCENE_SYMBOLS = [
+  { name: '_onDebugAutoPlay', why: 'recorder triggers one-click auto-play' },
+  { name: 'sceneManager', why: 'recorder reads scene phase state' },
+  { name: 'currentPhase', why: 'recorder waits for HOOK then ENDCARD' },
+  { name: 'isGameOver', why: 'recorder detects end of run' },
+  { name: 'ENDCARD', why: 'recorder waits for the ENDCARD phase' },
+];
+
+const NEUTRAL_PLAYABLE_SYMBOLS = [
+  { name: '__playable', why: 'engine-neutral recorder entry point' },
+  { name: 'autoPlay', why: 'recorder triggers one-click auto-play' },
+  { name: 'getState', why: 'recorder reads phase state' },
+  { name: 'currentPhase', why: 'recorder waits for HOOK then ENDCARD' },
+  { name: 'ENDCARD', why: 'recorder waits for the ENDCARD phase' },
+];
+
+// At least one of these must publish a recorder entry point.
+const ENTRY_SYMBOLS = ['window.__playable', '__playable =', 'publishPlayableRuntime', 'window.__game', 'registerPlayable', '__game ='];
+const REQUIRED_SYMBOLS = LEGACY_SCENE_SYMBOLS;
+
+/**
+ * Strip line + block comments so commented-out or documentation mentions of a
+ * symbol don't create false-negatives. Not a full parser, but removes the
+ * dominant source of substring false matches.
+ * @param {string} src
+ */
+function stripComments(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+/** Match a bare JS identifier with word boundaries (no dotted members). */
+function hasIdentifier(code, name) {
+  return new RegExp(`(?<![A-Za-z0-9_$])${name}(?![A-Za-z0-9_$])`).test(code);
+}
+
+function walkGameFiles(gameDir) {
+  const out = [];
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (/\.(ts|tsx|js|mjs|cjs)$/.test(entry.name)) {
+        out.push(full);
+      }
+    }
+  }
+  walk(gameDir);
+  return out;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ ok: boolean, missing: string[], filesScanned: number }}
+ */
+function scanRuntimeContract(projectRoot) {
+  const gameDir = path.join(projectRoot, 'game');
+  const files = walkGameFiles(gameDir);
+  if (files.length === 0) {
+    return { ok: false, missing: ['game/ contains no source files'], filesScanned: 0 };
+  }
+
+  const blob = stripComments(
+    files.map((f) => fs.readFileSync(f, 'utf8')).join('\n'),
+  );
+  const missing = [];
+
+  const missingNeutral = NEUTRAL_PLAYABLE_SYMBOLS
+    .filter((sym) => !hasIdentifier(blob, sym.name))
+    .map((sym) => `${sym.name} — ${sym.why}`);
+  const missingLegacy = LEGACY_SCENE_SYMBOLS
+    .filter((sym) => !hasIdentifier(blob, sym.name))
+    .map((sym) => `${sym.name} — ${sym.why}`);
+
+  // Entry symbols include dotted forms (window.__playable), so match as substrings
+  // after comment stripping.
+  if (!ENTRY_SYMBOLS.some((s) => blob.includes(s))) {
+    missing.push('window.__playable / publishPlayableRuntime — recorder entry point');
+  }
+  if (missingNeutral.length > 0 && missingLegacy.length > 0) {
+    missing.push(...missingNeutral.map((m) => `neutral contract: ${m}`));
+    if (!blob.includes('publishPlayableRuntime')) {
+      missing.push(...missingLegacy.map((m) => `legacy scene contract (deprecated): ${m}`));
+    }
+  } else if (missingNeutral.length > 0 && blob.includes('publishPlayableRuntime')) {
+    missing.push(...missingNeutral.map((m) => `neutral contract: ${m}`));
+  }
+  if (/\b(?:window\.__game|__game)\.start\s*=/.test(blob)) {
+    missing.push('window.__game.start must not be assigned; put harness methods on window.__playable');
+  }
+
+  return { ok: missing.length === 0, missing, filesScanned: files.length };
+}
+
+module.exports = { scanRuntimeContract, REQUIRED_SYMBOLS, ENTRY_SYMBOLS, NEUTRAL_PLAYABLE_SYMBOLS, LEGACY_SCENE_SYMBOLS };

package/project-templates/phaser/skills/playable-verify-ui/scripts/measure_frame_content.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Measure content safe zone for a frame in a Phaser atlas."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    from PIL import Image
+except ImportError as exc:  # pragma: no cover
+    raise SystemExit("Pillow required: pip install pillow") from exc
+
+
+def is_red(px: tuple[int, int, int, int]) -> bool:
+    r, g, b, a = px
+    return a > 40 and r > 140 and g < 130 and b < 90 and r > g
+
+
+def measure(png_path: Path, json_path: Path, frame_name: str) -> dict:
+    meta = json.loads(json_path.read_text())
+    frame = meta["frames"][frame_name]["frame"]
+    img = Image.open(png_path).convert("RGBA")
+    px = img.crop((frame["x"], frame["y"], frame["x"] + frame["w"], frame["y"] + frame["h"])).load()
+    w, h = frame["w"], frame["h"]
+
+    rows = []
+    for y in range(h):
+        if sum(1 for x in range(w) if is_red(px[x, y])) > w * 0.45:
+            rows.append(y)
+    if not rows:
+        raise ValueError(f"No red content band found in {frame_name}")
+
+    y0, y1 = rows[0], rows[-1]
+    mid_y = (y0 + y1) // 2
+    xs = [x for x in range(w) if is_red(px[x, mid_y])]
+    x0, x1 = xs[0], xs[-1]
+
+    content = {
+        "left": x0,
+        "right": w - x1 - 1,
+        "top": y0,
+        "bottom": h - y1 - 1,
+    }
+    return {
+        "frame": frame_name,
+        "sourceSize": {"w": w, "h": h},
+        "content": content,
+        "textCenter": {
+            "x": x0 + (x1 - x0 + 1) / 2,
+            "y": y0 + (y1 - y0 + 1) / 2,
+        },
+        "textCenterYRatio": (y0 + (y1 - y0 + 1) / 2) / h,
+        "suggestedNineSlice": {
+            "left": x0,
+            "right": w - x1 - 1,
+            "top": y0,
+            "bottom": h - y1 - 1,
+        },
+    }
+
+
+def main() -> None:
+    if len(sys.argv) != 4:
+        print(
+            "Usage: measure_frame_content.py <atlas.png> <atlas.json> <frame_name>",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+
+    result = measure(Path(sys.argv[1]), Path(sys.argv[2]), sys.argv[3])
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/phaser/skills/playable-verify-ui/scripts/run_all.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""Run all playable UI verification checks."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.report import Report, Status, exit_with_report  # noqa: E402
+
+ASSET_CHECKS = [
+    "verify_profile_schema.py",
+    "verify_assets_present.py",
+    "verify_asset_sizes.py",
+    "verify_atlas_frames.py",
+    "verify_atlas_budget.py",
+    "verify_doc_asset_sync.py",
+    "verify_fetch_antipatterns.py",
+]
+
+ASSET_ROOT_CHECKS = [
+    "verify_slice_plan.py",
+]
+
+VISUAL_CHECKS = [
+    "verify_bg_clean.py",
+    "verify_tile_consistency.py",
+    "verify_text_overlap.py",
+]
+
+LAYOUT_CHECKS = [
+    "verify_game_config_load.js",
+    "verify_layout_regions.js",
+    "verify_hardcoded_layout.js",
+    "verify_script_load_order.js",
+    "verify_runtime_contract.js",
+]
+
+
+@dataclass
+class Check:
+    script: str
+    args: list[str] = field(default_factory=list)
+    kind: str = "profile"
+
+    @property
+    def name(self) -> str:
+        return self.script.rsplit(".", 1)[0]
+
+
+def normalize_issue_for_report(issue: dict[str, Any], fallback_check: str) -> dict[str, Any]:
+    class_name = str(issue.get("className") or issue.get("class_name") or fallback_check)
+    status = str(issue.get("status") or "fail")
+    if status not in {"pass", "warn", "fail"}:
+        status = "warn"
+    normalized = {
+        "id": str(issue.get("id") or f"{class_name}:{issue.get('sourcePath', '')}"),
+        "status": status,
+        "severity": str(issue.get("severity") or ("P1" if status == "fail" else "P2")),
+        "className": class_name,
+        "message": str(issue.get("message") or class_name),
+        "evidenceType": str(issue.get("evidenceType") or "screenshot"),
+        "sourcePath": str(issue.get("sourcePath") or ""),
+        "recommendedSkill": str(issue.get("recommendedSkill") or "playable-verify-ui"),
+        "alphaStrategy": str(issue.get("alphaStrategy") or "n-a"),
+    }
+    for key in ("box", "sources", "metrics"):
+        if key in issue:
+            normalized[key] = issue[key]
+    return normalized
+
+
+def merge_issue_payload(report: Report, name: str, payload: dict[str, Any]) -> list[dict[str, Any]]:
+    issues = [normalize_issue_for_report(i, name) for i in payload.get("issues", []) if isinstance(i, dict)]
+    for issue in issues:
+        st = Status(issue["status"])
+        details = {k: v for k, v in issue.items() if k not in {"status", "message"}}
+        if st == Status.FAIL:
+            report.fail(name, issue["message"], **details)
+        elif st == Status.WARN:
+            report.warn(name, issue["message"], **details)
+        else:
+            report.pass_(name, issue["message"], **details)
+    return issues
+
+
+def merge_json_payload(report: Report, name: str, payload: dict) -> list[dict[str, Any]]:
+    issues = merge_issue_payload(report, name, payload)
+    if issues:
+        return issues
+    for finding in payload.get("findings", []):
+        st = Status(finding["status"])
+        details = finding.get("details") or {}
+        if st == Status.FAIL:
+            report.fail(name, finding["message"], **details)
+        elif st == Status.WARN:
+            report.warn(name, finding["message"], **details)
+        else:
+            report.pass_(name, finding["message"], **details)
+    return []
+
+
+def command_for_check(check: Check, profile: Path, root: Path) -> list[str]:
+    script = str(SCRIPT_DIR / check.script)
+    if check.script.endswith(".py"):
+        if check.kind == "root":
+            return [sys.executable, script, "--root", str(root), *check.args]
+        return [sys.executable, script, "--profile", str(profile), "--json", *check.args]
+    if check.kind == "root":
+        return ["node", script, "--root", str(root), *check.args]
+    return ["node", script, "--profile", str(profile), *check.args]
+
+
+def run_check(check: Check, profile: Path, root: Path, report: Report) -> tuple[int, list[dict[str, Any]]]:
+    name = check.name
+    cmd = command_for_check(check, profile, root)
+    if check.script.endswith(".py"):
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+        )
+        stdout = proc.stdout.strip()
+        if stdout:
+            try:
+                issues = merge_json_payload(report, name, json.loads(stdout))
+            except json.JSONDecodeError:
+                if proc.returncode != 0:
+                    report.fail(name, stdout or proc.stderr.strip() or f"{name} failed")
+                else:
+                    report.pass_(name, "OK")
+                issues = []
+        elif proc.returncode != 0:
+            report.fail(name, proc.stderr.strip() or f"{name} failed")
+            issues = []
+        else:
+            report.pass_(name, "OK")
+            issues = []
+        return proc.returncode, issues
+
+    proc = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+    )
+    stdout = proc.stdout.strip()
+    if stdout:
+        try:
+            issues = merge_json_payload(report, name, json.loads(stdout))
+        except json.JSONDecodeError:
+            if proc.returncode != 0:
+                report.fail(name, proc.stderr.strip() or stdout or f"{name} failed")
+            else:
+                report.pass_(name, "OK")
+            issues = []
+    elif proc.returncode != 0:
+        report.fail(name, proc.stderr.strip() or f"{name} failed")
+        issues = []
+    else:
+        report.pass_(name, "OK")
+        issues = []
+    return proc.returncode, issues
+
+
+def write_validator_issues(root: Path, issues: list[dict[str, Any]]) -> Path:
+    out = root / "validate" / "vision" / "validator-issues.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps({"issues": issues}, ensure_ascii=False, indent=2), encoding="utf-8")
+    return out
+
+
+def run_annotations(root: Path, issues_path: Path, report: Report) -> None:
+    proc = subprocess.run(
+        [
+            sys.executable,
+            str(SCRIPT_DIR / "verify_vision_evidence.py"),
+            "--root",
+            str(root),
+            "--issues",
+            str(issues_path),
+            "--json",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    payload: dict[str, Any] = {}
+    if proc.stdout.strip():
+        try:
+            payload = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            payload = {}
+    if proc.returncode != 0:
+        report.warn(
+            "verify_vision_evidence",
+            "annotation stage failed",
+            stdout=proc.stdout.strip(),
+            stderr=proc.stderr.strip(),
+        )
+    summary = payload.get("summary") if isinstance(payload.get("summary"), dict) else {}
+    outputs: list[str] = []
+    for key in ("images", "assets", "groups"):
+        for item in payload.get(key, []) if isinstance(payload.get(key), list) else []:
+            if isinstance(item, dict) and item.get("annotated"):
+                outputs.append(str(item["annotated"]))
+    report.metadata["annotations"] = {
+        "enabled": True,
+        "generated": int(summary.get("annotatedImages", 0))
+        + int(summary.get("assetEvidence", 0))
+        + int(summary.get("groupEvidence", 0)),
+        "droppedDetections": int(summary.get("droppedDetections", 0)),
+        "outputs": outputs,
+        "report": "validate/vision/vision-evidence.json",
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run playable UI verification suite")
+    parser.add_argument("--profile", type=Path, default=Path("playable.ui.profile.yaml"))
+    parser.add_argument("--only", choices=["assets", "layout", "all"], default="all")
+    parser.add_argument("--json", dest="json_out", type=Path, default=None)
+    parser.add_argument("--no-annotations", action="store_true", help="Run validators but skip annotated evidence images")
+    args = parser.parse_args()
+
+    profile = args.profile.resolve()
+    root = Path.cwd().resolve()
+    checks: list[Check] = []
+    if args.only in ("all", "assets"):
+        checks.extend(Check(script=s) for s in ASSET_CHECKS)
+        checks.extend(Check(script=s, kind="root", args=["--json"]) for s in ASSET_ROOT_CHECKS)
+        checks.extend(Check(script=s, kind="root") for s in VISUAL_CHECKS)
+    if args.only in ("all", "layout"):
+        checks.extend(Check(script=s) for s in LAYOUT_CHECKS)
+
+    report = Report()
+    validator_issues: list[dict[str, Any]] = []
+    for check in checks:
+        _, issues = run_check(check, profile, root, report)
+        validator_issues.extend(issues)
+
+    issues_path = write_validator_issues(root, validator_issues)
+    if args.no_annotations:
+        report.metadata["annotations"] = {
+            "enabled": False,
+            "reason": "disabled_by_flag",
+            "generated": 0,
+            "droppedDetections": 0,
+            "outputs": [],
+            "issues": str(issues_path.relative_to(root)),
+        }
+    else:
+        run_annotations(root, issues_path, report)
+
+    exit_with_report(report, json_path=str(args.json_out) if args.json_out else None)
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/phaser/skills/playable-verify-ui/scripts/verify_asset_sizes.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Verify PNG dimensions match profile specifications."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.profile_loader import get_paths, load_profile  # noqa: E402
+from lib.report import Report, exit_with_report  # noqa: E402
+
+
+def read_png_size(path: Path) -> tuple[int, int]:
+    from PIL import Image
+
+    with Image.open(path) as img:
+        return img.size
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Verify asset PNG dimensions")
+    parser.add_argument("--profile", type=Path, default=Path("playable.ui.profile.yaml"))
+    parser.add_argument("--json", action="store_true", help="Emit JSON to stdout")
+    args = parser.parse_args()
+
+    profile_path = args.profile.resolve()
+    profile = load_profile(profile_path, validate=False)
+    paths = get_paths(profile, profile_path)
+    assets_root = paths["assetsRoot"]
+    report = Report()
+    mismatches: list[str] = []
+
+    for item in profile.get("assets", {}).get("standalone", []):
+        full = assets_root / item["path"]
+        if not full.is_file():
+            continue
+        actual = read_png_size(full)
+        expected = (item["width"], item["height"])
+        if actual != expected:
+            mismatches.append(f"{item['key']}: expected {expected[0]}x{expected[1]}, got {actual[0]}x{actual[1]}")
+
+    for atlas in profile.get("assets", {}).get("atlases", []):
+        if atlas.get("procedural"):
+            continue
+        for frame in atlas.get("frames", []):
+            source = frame.get("source")
+            if not source:
+                continue
+            full = assets_root / source
+            if not full.is_file():
+                continue
+            actual = read_png_size(full)
+            expected = (frame["width"], frame["height"])
+            if actual != expected:
+                mismatches.append(
+                    f"{frame['name']}: expected {expected[0]}x{expected[1]}, got {actual[0]}x{actual[1]}"
+                )
+
+    if mismatches:
+        report.fail(
+            "verify_asset_sizes",
+            f"{len(mismatches)} dimension mismatch(es)",
+            mismatches=mismatches[:20],
+            total=len(mismatches),
+        )
+    else:
+        report.pass_("verify_asset_sizes", "All checked PNG dimensions match profile")
+
+    exit_with_report(report, json_stdout=args.json)
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/phaser/skills/playable-verify-ui/scripts/verify_assets_present.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Verify standalone PNGs and atlas source PNGs exist."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.profile_loader import get_paths, load_profile  # noqa: E402
+from lib.report import Report, exit_with_report  # noqa: E402
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Verify asset files are present")
+    parser.add_argument("--profile", type=Path, default=Path("playable.ui.profile.yaml"))
+    parser.add_argument("--json", action="store_true", help="Emit JSON to stdout")
+    args = parser.parse_args()
+
+    profile_path = args.profile.resolve()
+    profile = load_profile(profile_path, validate=False)
+    paths = get_paths(profile, profile_path)
+    assets_root = paths["assetsRoot"]
+    report = Report()
+
+    missing: list[str] = []
+
+    for item in profile.get("assets", {}).get("standalone", []):
+        rel = item["path"]
+        full = assets_root / rel
+        if not full.is_file():
+            missing.append(str(full.relative_to(profile_path.parent)))
+
+    for atlas in profile.get("assets", {}).get("atlases", []):
+        if atlas.get("procedural"):
+            continue
+        for frame in atlas.get("frames", []):
+            source = frame.get("source")
+            if not source:
+                continue
+            full = assets_root / source
+            if not full.is_file():
+                missing.append(str(full.relative_to(profile_path.parent)))
+
+    if missing:
+        report.fail(
+            "verify_assets_present",
+            f"{len(missing)} asset file(s) missing",
+            missing=missing[:20],
+            total=len(missing),
+        )
+    else:
+        report.pass_("verify_assets_present", "All profile assets exist on disk")
+
+    exit_with_report(report, json_stdout=args.json)
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/phaser/skills/playable-verify-ui/scripts/verify_atlas_budget.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Verify atlas and standalone file sizes against profile thresholds."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.profile_loader import get_paths, load_profile  # noqa: E402
+from lib.report import Report, exit_with_report  # noqa: E402
+
+
+def kb(path: Path) -> float:
+    return path.stat().st_size / 1024
+
+
+def mb(path: Path) -> float:
+    return path.stat().st_size / (1024 * 1024)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Verify asset size budgets")
+    parser.add_argument("--profile", type=Path, default=Path("playable.ui.profile.yaml"))
+    parser.add_argument("--json", action="store_true", help="Emit JSON to stdout")
+    args = parser.parse_args()
+
+    profile_path = args.profile.resolve()
+    profile = load_profile(profile_path, validate=False)
+    paths = get_paths(profile, profile_path)
+    assets_root = paths["assetsRoot"]
+    atlas_root = paths["atlasRoot"]
+    thresholds = profile.get("thresholds", {})
+    max_atlas_kb = thresholds.get("maxAtlasSheetKb", 512)
+    max_standalone_kb = thresholds.get("maxStandaloneKb", 256)
+    max_total_mb = thresholds.get("maxTotalAssetsMb", 8)
+
+    report = Report()
+    fails: list[str] = []
+    warns: list[str] = []
+    total_bytes = 0
+
+    for item in profile.get("assets", {}).get("standalone", []):
+        full = assets_root / item["path"]
+        if not full.is_file():
+            continue
+        size_kb = kb(full)
+        total_bytes += full.stat().st_size
+        if size_kb > max_standalone_kb:
+            fails.append(f"{item['key']}: {size_kb:.1f}KB > {max_standalone_kb}KB")
+
+    for atlas in profile.get("assets", {}).get("atlases", []):
+        png_path = atlas_root / atlas["png"]
+        if not png_path.is_file():
+            continue
+        size_kb = kb(png_path)
+        total_bytes += png_path.stat().st_size
+        json_path = atlas_root / atlas["json"]
+        if json_path.is_file():
+            total_bytes += json_path.stat().st_size
+        if size_kb > max_atlas_kb:
+            fails.append(f"{atlas['name']}.png: {size_kb:.1f}KB > {max_atlas_kb}KB")
+
+    total_mb = total_bytes / (1024 * 1024)
+    if total_mb > max_total_mb:
+        fails.append(f"total assets: {total_mb:.2f}MB > {max_total_mb}MB")
+
+    if fails:
+        report.fail("verify_atlas_budget", f"{len(fails)} budget violation(s)", violations=fails)
+    else:
+        report.pass_(
+            "verify_atlas_budget",
+            f"Asset budgets OK (total {total_mb:.2f}MB)",
+            totalMb=round(total_mb, 2),
+        )
+
+    exit_with_report(report, json_stdout=args.json)
+
+
+if __name__ == "__main__":
+    main()