@playcraft/cli 0.0.44 → 0.0.46

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Unit tests for verify_vision_evidence helpers."""
+from __future__ import annotations
+
+import unittest
+from tempfile import TemporaryDirectory
+from pathlib import Path
+
+# Run-as-script import path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from verify_vision_evidence import (  # noqa: E402
+    load_pillow,
+    normalize_box,
+    normalize_detections,
+    normalize_issues,
+    process_group_issues,
+    region_box,
+    route_alpha_strategy,
+    route_skill,
+    source_path_for_detection,
+)
+
+
+class VisionEvidenceTests(unittest.TestCase):
+    def test_normalize_box_xyxy_dict(self) -> None:
+        self.assertEqual(normalize_box({"xyxy": [1, 2, 10, 20]}), [1.0, 2.0, 10.0, 20.0])
+
+    def test_normalize_box_wh_dict(self) -> None:
+        self.assertEqual(normalize_box({"x": 5, "y": 6, "width": 4, "height": 3}), [5.0, 6.0, 9.0, 9.0])
+
+    def test_normalize_box_rejects_invalid(self) -> None:
+        self.assertIsNone(normalize_box({"x": 1, "y": 2}))
+        self.assertIsNone(normalize_box([1, 2, 1, 2]))
+
+    def test_normalize_detections_payload(self) -> None:
+        payload = {
+            "detections": [
+                {
+                    "sourcePath": "logs/ui-diff-game.png",
+                    "box": [0, 0, 100, 100],
+                    "className": "green_edge",
+                    "confidence": 0.9,
+                }
+            ]
+        }
+        out = normalize_detections(payload)
+        self.assertEqual(len(out), 1)
+        self.assertEqual(out[0]["recommendedSkill"], "playable-art")
+        self.assertEqual(out[0]["alphaStrategy"], "rgb-alpha-split")
+
+    def test_normalize_issues_payload(self) -> None:
+        payload = {
+            "issues": [
+                {
+                    "id": "bg_baked_ui:bg",
+                    "status": "fail",
+                    "severity": "P1",
+                    "className": "bg_baked_ui",
+                    "message": "baked board",
+                    "evidenceType": "asset",
+                    "sourcePath": "assets/images/bg/bg_game.webp",
+                    "box": [1, 2, 30, 40],
+                }
+            ]
+        }
+        out = normalize_issues(payload)
+        self.assertEqual(len(out), 1)
+        self.assertEqual(out[0]["id"], "bg_baked_ui:bg")
+        self.assertEqual(out[0]["recommendedSkill"], "playable-verify-ui")
+        self.assertEqual(out[0]["box"], [1.0, 2.0, 30.0, 40.0])
+
+    def test_route_skill_text_overlap(self) -> None:
+        self.assertEqual(route_skill("text_overlap"), "playable-verify-ui")
+
+    def test_region_box_board(self) -> None:
+        box = region_box(1000, 2000, "board")
+        self.assertEqual(box[0], 80.0)
+        self.assertEqual(box[1], 440.0)
+
+    def test_source_path_for_detection_stays_under_root(self) -> None:
+        root = Path(__file__).resolve().parent
+        path = source_path_for_detection(root, {"sourcePath": "verify_vision_evidence_test.py"})
+        self.assertEqual(path, root / "verify_vision_evidence_test.py")
+        self.assertIsNone(source_path_for_detection(root, {"sourcePath": "../outside.png"}))
+        self.assertIsNone(source_path_for_detection(root, {"sourcePath": "missing.png"}))
+
+    def test_process_group_issues_generates_contact_sheet(self) -> None:
+        deps, _ = load_pillow()
+        if deps is None:
+            self.skipTest("Pillow unavailable")
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            tile_dir = root / "assets" / "images" / "tiles"
+            tile_dir.mkdir(parents=True)
+            for name, color in (("tile_red.webp", (255, 0, 0, 255)), ("tile_blue.webp", (0, 0, 255, 255))):
+                img = deps.Image.new("RGBA", (24, 24), color)
+                img.save(tile_dir / name)
+            issue = {
+                "id": "tile_inconsistent_silhouette:color_group",
+                "status": "fail",
+                "severity": "P1",
+                "className": "tile_inconsistent_silhouette",
+                "message": "mixed silhouettes",
+                "evidenceType": "asset-group",
+                "sourcePath": "assets/images/tiles",
+                "sources": [
+                    {"sourcePath": "assets/images/tiles/tile_red.webp", "metrics": {"bboxOccupancy": 1.0}},
+                    {"sourcePath": "assets/images/tiles/tile_blue.webp", "metrics": {"bboxOccupancy": 0.5}},
+                ],
+                "metrics": {"bboxOccupancySpread": 0.5},
+            }
+            groups, findings, dropped = process_group_issues(deps, root, [issue], root / "validate" / "vision")
+            self.assertEqual(len(groups), 1)
+            self.assertEqual(len(findings), 1)
+            self.assertEqual(dropped, [])
+            self.assertTrue((root / groups[0]["annotated"]).exists())
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,422 @@
+#!/usr/bin/env python3
+"""
+Objective visual diff scorer — screenshots vs locked ASR/MC reference (growth-rings ring 4).
+
+Uses histogram correlation + SSIM + 3×3 grid SSIM. Pairs each screenshot with a scene-appropriate
+reference (not a single global reference). Rejects circular self-proof (references from logs/ or
+newer than all screenshots when sourced from suspicious paths).
+
+Usage:
+  python3 skills/playable-verify-ui/scripts/verify_visual.py [--root .] [--min-score 0.35]
+  python3 skills/playable-verify-ui/scripts/verify_visual.py --strict-if-references
+
+Exit 0 = pass or intentional skip (no ASR yet)
+Exit 2 = fail
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+# Run-as-script: the manifest helper lives next to this file.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from asset_manifest import load_manifest, reference_paths, runtime_paths  # noqa: E402
+
+if TYPE_CHECKING:
+    from PIL import Image as PilImage
+
+SCREENSHOT_PATTERNS = (
+    "ui-diff-*.png",
+    "load-check.png",
+    "conform-*.png",
+    "review-*.png",
+)
+
+ALLOWED_REFERENCE_ROOTS = (
+    "assets/images/reference",
+    "assets/images/storyboard",
+    "assets/images/asr",
+)
+
+# Reference image roots scanned for candidates, in priority order.
+REFERENCE_DIRS = ("asr", "reference", "storyboard")
+
+FORBIDDEN_REFERENCE_PARTS = ("logs/", "mc_snapshot", "ui-diff-", "load-check", "current-state")
+
+
+def load_pil_image_module() -> Any | None:
+    try:
+        from PIL import Image
+
+        return Image
+    except ImportError:
+        return None
+
+
+def histogram_correlation(image_mod: Any, a: PilImage, b: PilImage) -> float:
+    a = a.convert("RGB").resize((128, 128))
+    b = b.convert("RGB").resize((128, 128))
+    ha = a.histogram()
+    hb = b.histogram()
+    if len(ha) != len(hb):
+        return 0.0
+    mean_a = sum(ha) / len(ha)
+    mean_b = sum(hb) / len(hb)
+    num = sum((x - mean_a) * (y - mean_b) for x, y in zip(ha, hb))
+    den_a = sum((x - mean_a) ** 2 for x in ha) ** 0.5
+    den_b = sum((y - mean_b) ** 2 for y in hb) ** 0.5
+    if den_a == 0 or den_b == 0:
+        return 0.0
+    return max(0.0, min(1.0, num / (den_a * den_b)))
+
+
+def _to_gray_array(image_mod: Any, img: PilImage, size: int = 128) -> list[float]:
+    g = img.convert("L").resize((size, size))
+    return [p / 255.0 for p in g.getdata()]
+
+
+def ssim_grayscale(image_mod: Any, a: PilImage, b: PilImage, size: int = 128) -> float:
+    """Windowless SSIM on grayscale resize (PIL-only, no numpy)."""
+    xa = _to_gray_array(image_mod, a, size)
+    xb = _to_gray_array(image_mod, b, size)
+    n = len(xa)
+    if n == 0:
+        return 0.0
+    mean_a = sum(xa) / n
+    mean_b = sum(xb) / n
+    var_a = sum((x - mean_a) ** 2 for x in xa) / n
+    var_b = sum((x - mean_b) ** 2 for x in xb) / n
+    cov = sum((xa[i] - mean_a) * (xb[i] - mean_b) for i in range(n)) / n
+    c1 = (0.01) ** 2
+    c2 = (0.03) ** 2
+    num = (2 * mean_a * mean_b + c1) * (2 * cov + c2)
+    den = (mean_a**2 + mean_b**2 + c1) * (var_a + var_b + c2)
+    if den == 0:
+        return 0.0
+    return max(0.0, min(1.0, num / den))
+
+
+def grid_ssim_min(image_mod: Any, a: PilImage, b: PilImage, grids: int = 3) -> float:
+    """Minimum SSIM across a grids×grids partition (catches local layout drift)."""
+    a = a.convert("RGB")
+    b = b.convert("RGB")
+    w, h = a.size
+    b = b.resize((w, h))
+    cell_w = max(1, w // grids)
+    cell_h = max(1, h // grids)
+    scores: list[float] = []
+    for gy in range(grids):
+        for gx in range(grids):
+            box = (gx * cell_w, gy * cell_h, min(w, (gx + 1) * cell_w), min(h, (gy + 1) * cell_h))
+            if box[2] <= box[0] or box[3] <= box[1]:
+                continue
+            ca = a.crop(box)
+            cb = b.crop(box)
+            scores.append(ssim_grayscale(image_mod, ca, cb, size=64))
+    return min(scores) if scores else 0.0
+
+
+def combined_score(hist: float, ssim: float, grid_min: float) -> float:
+    return round(0.25 * hist + 0.45 * ssim + 0.30 * grid_min, 4)
+
+
+def read_selected_mc_option(root: Path) -> str | None:
+    state_path = root / "docs" / "project-state.md"
+    if not state_path.exists():
+        return None
+    text = state_path.read_text(encoding="utf-8")
+    yaml_match = re.search(
+        r"```yaml[\s\S]*?selectedMcOption:\s*([A-Za-z0-9]+)",
+        text,
+        re.IGNORECASE,
+    )
+    if yaml_match:
+        return yaml_match.group(1).strip().lower()
+    table_match = re.search(
+        r"\|\s*selectedMcOption\s*\|\s*([A-Za-z0-9]+)\s*\|",
+        text,
+        re.IGNORECASE,
+    )
+    if table_match and not table_match.group(1).startswith("{{"):
+        return table_match.group(1).strip().lower()
+    return None
+
+
+def collect_screenshots(logs: Path) -> list[Path]:
+    if not logs.exists():
+        return []
+    found: list[Path] = []
+    seen: set[Path] = set()
+    for pattern in SCREENSHOT_PATTERNS:
+        for path in sorted(logs.glob(pattern)):
+            resolved = path.resolve()
+            if resolved not in seen:
+                seen.add(resolved)
+                found.append(path)
+    return found
+
+
+def is_allowed_reference(root: Path, ref: Path) -> bool:
+    rel = str(ref.relative_to(root)).replace("\\", "/").lower()
+    if any(part in rel for part in FORBIDDEN_REFERENCE_PARTS):
+        return False
+    return any(rel.startswith(prefix) for prefix in ALLOWED_REFERENCE_ROOTS)
+
+
+def detect_circular_self_proof(root: Path, ref: Path, screenshots: list[Path]) -> str | None:
+    rel = str(ref.relative_to(root)).replace("\\", "/")
+    if not is_allowed_reference(root, ref):
+        return f"Reference {rel} is not from ASR/MC/storyboard (forbidden path — possible circular self-proof)"
+    if not screenshots:
+        return None
+    ref_mtime = ref.stat().st_mtime
+    shot_min_mtime = min(s.stat().st_mtime for s in screenshots)
+    if ref_mtime > shot_min_mtime and "storyboard" not in rel.lower():
+        return (
+            f"Reference {rel} mtime is newer than screenshots — may be derived from game capture (circular self-proof)"
+        )
+    return None
+
+
+def _rel(root: Path, p: Path) -> str:
+    return str(p.relative_to(root)).replace("\\", "/")
+
+
+def _ref_admissible(
+    root: Path, cand: Path, allowlist: frozenset[str], excluded: frozenset[str]
+) -> bool:
+    """A candidate reference is usable when it is an allowed reference path, not a
+    declared runtime asset (circular self-proof), and — if the manifest declares a
+    reference set — a member of that set (allowlist acts as a filter, NOT a reorder,
+    so scene-aware option pairing still chooses *which* declared reference to use)."""
+    rel = _rel(root, cand)
+    if rel in excluded:
+        return False
+    if allowlist and rel not in allowlist:
+        return False
+    return is_allowed_reference(root, cand)
+
+
+def resolve_reference_for_screenshot(
+    root: Path,
+    shot: Path,
+    option: str | None,
+    allowlist: frozenset[str] = frozenset(),
+    excluded: frozenset[str] = frozenset(),
+) -> Path | None:
+    """Scene-aware reference pairing (not references[0] for every shot).
+
+    Handles a missing ``option`` (no selectedMcOption yet) without raising —
+    earlier revisions called ``option.upper()`` unconditionally and crashed the
+    Ring 4 gate with ``AttributeError`` instead of reporting a visual diff.
+
+    When an asset-manifest declares references, ``allowlist`` restricts pairing to
+    that set and ``excluded`` removes runtime assets (circular-self-proof guard),
+    but the option-based ordering below still decides *which* declared reference
+    pairs with this screenshot.
+    """
+    name = shot.stem.lower()
+    ref_dir = root / "assets" / "images" / "reference"
+    asr_dir = root / "assets" / "images" / "asr"
+    story_dir = root / "assets" / "images" / "storyboard"
+
+    candidates: list[Path] = []
+
+    if option:
+        o = option.lower()
+        upper = option.upper()
+        # Whole-screen screenshots match the full-frame storyboard composite (MC mockup)
+        # best; the ui/element state sheets are component grids and are only a fallback.
+        candidates += [
+            story_dir / f"master_composite_option_{upper}.png",
+            story_dir / f"master_composite_option_{o}.png",
+            ref_dir / f"ui_state_sheet_{o}.png",
+            asr_dir / f"ui_state_sheet_{upper}.png",
+            asr_dir / f"ui_state_sheet_{o}.png",
+            ref_dir / f"element_state_sheet_{o}.png",
+            asr_dir / f"element_state_sheet_{upper}.png",
+            asr_dir / f"element_state_sheet_{o}.png",
+        ]
+
+    # Generic globs across all allowed reference roots (priority: storyboard → reference → asr).
+    glob_specs = (
+        (story_dir, "master_composite*.png"),
+        (ref_dir, "ui_state_sheet_*.png"),
+        (asr_dir, "ui_state_sheet_*.png"),
+        (asr_dir, "element_state_sheet_*.png"),
+    )
+    for folder, pattern in glob_specs:
+        if folder.exists():
+            candidates += sorted(folder.glob(pattern))
+
+    seen: set[Path] = set()
+    for cand in candidates:
+        if cand.exists() and cand.resolve() not in seen:
+            seen.add(cand.resolve())
+            if _ref_admissible(root, cand, allowlist, excluded):
+                return cand
+
+    # Fallback: any admissible reference under the allowed roots.
+    for folder in (asr_dir, ref_dir, story_dir):
+        if folder.exists():
+            for p in sorted(folder.glob("*.png")):
+                if _ref_admissible(root, p, allowlist, excluded):
+                    return p
+    return None
+
+
+def resolve_all_references(
+    root: Path,
+    ref_dir: Path,
+    allowlist: frozenset[str] = frozenset(),
+    excluded: frozenset[str] = frozenset(),
+) -> list[Path]:
+    option = read_selected_mc_option(root)
+    asr_dir = root / "assets" / "images" / "asr"
+    story_dir = root / "assets" / "images" / "storyboard"
+
+    preferred: list[Path] = []
+    if option:
+        o = option.lower()
+        upper = option.upper()
+        for folder, name in (
+            (ref_dir, f"ui_state_sheet_{o}.png"),
+            (asr_dir, f"ui_state_sheet_{upper}.png"),
+            (asr_dir, f"ui_state_sheet_{o}.png"),
+            (ref_dir, f"element_state_sheet_{o}.png"),
+            (asr_dir, f"element_state_sheet_{upper}.png"),
+            (asr_dir, f"element_state_sheet_{o}.png"),
+        ):
+            candidate = folder / name
+            if candidate.exists() and _ref_admissible(root, candidate, allowlist, excluded):
+                preferred.append(candidate)
+    if preferred:
+        return preferred
+
+    refs: list[Path] = []
+    seen: set[Path] = set()
+    for folder in (asr_dir, ref_dir):
+        if folder.exists():
+            for p in sorted(folder.glob("*.png")):
+                if not _ref_admissible(root, p, allowlist, excluded):
+                    continue
+                if p.resolve() not in seen:
+                    seen.add(p.resolve())
+                    refs.append(p)
+    if story_dir.exists():
+        for p in sorted(story_dir.glob("master_composite*.png")):
+            if not _ref_admissible(root, p, allowlist, excluded):
+                continue
+            if p.resolve() not in seen:
+                seen.add(p.resolve())
+                refs.append(p)
+    return refs
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".", help="Project root")
+    parser.add_argument("--min-score", type=float, default=0.35, help="Minimum combined score")
+    parser.add_argument("--strict", action="store_true")
+    parser.add_argument("--strict-if-references", action="store_true")
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    logs = root / "logs"
+    ref_dir = root / "assets" / "images" / "reference"
+    option = read_selected_mc_option(root)
+
+    # A malformed/stale manifest is a contract failure.
+    manifest, manifest_errors = load_manifest(root)
+    if manifest_errors:
+        print(json.dumps({"ok": False, "manifestErrors": manifest_errors, "failures": manifest_errors}, indent=2))
+        return 2
+
+    # When the manifest declares references, restrict pairing to that set
+    # (allowlist filter — scene-aware option ordering still picks which one);
+    # declared runtime assets are excluded so a runtime asset can never prove itself.
+    ref_decls = reference_paths(manifest)
+    allowlist = frozenset(ref_decls)
+    excluded = frozenset(runtime_paths(manifest))
+    manifest_ref_on_disk = sum(1 for rel in ref_decls if (root / rel).exists())
+
+    screenshots = collect_screenshots(logs)
+    references = resolve_all_references(root, ref_dir, allowlist=allowlist, excluded=excluded)
+
+    pairs: list[dict] = []
+    failures: list[str] = []
+
+    if not references:
+        msg = "No ASR reference images in assets/images/reference/ — skip until ring 3 ASR is locked"
+        if args.strict:
+            failures.append(msg)
+        else:
+            pairs.append({"note": msg, "skipped": True})
+    elif not screenshots:
+        msg = "No ui_diff screenshots in logs/ — run Reviewer ui_diff first"
+        if args.strict or args.strict_if_references:
+            failures.append(msg)
+        else:
+            pairs.append({"note": msg, "skipped": True})
+    else:
+        image_mod = load_pil_image_module()
+        if image_mod is None:
+            failures.append("Pillow (PIL) not installed — pip install Pillow")
+        else:
+            for shot in screenshots:
+                ref = resolve_reference_for_screenshot(
+                    root, shot, option, allowlist=allowlist, excluded=excluded
+                )
+                if ref is None:
+                    failures.append(f"No allowed reference for {shot.name}")
+                    continue
+                circular = detect_circular_self_proof(root, ref, [shot])
+                if circular:
+                    failures.append(circular)
+                    continue
+                try:
+                    ref_img = image_mod.open(ref)
+                    shot_img = image_mod.open(shot)
+                except OSError as exc:
+                    failures.append(f"Could not read images for {shot.name}: {exc}")
+                    continue
+
+                hist = histogram_correlation(image_mod, ref_img, shot_img)
+                ssim = ssim_grayscale(image_mod, ref_img, shot_img)
+                grid_min = grid_ssim_min(image_mod, ref_img, shot_img)
+                score = combined_score(hist, ssim, grid_min)
+                entry = {
+                    "screenshot": str(shot.relative_to(root)),
+                    "reference": str(ref.relative_to(root)),
+                    "histogram": round(hist, 4),
+                    "ssim": round(ssim, 4),
+                    "gridMinSsim": round(grid_min, 4),
+                    "score": score,
+                }
+                pairs.append(entry)
+                if score < args.min_score:
+                    failures.append(
+                        f"{entry['screenshot']} combined score {score:.3f} < {args.min_score} "
+                        f"(hist={hist:.3f} ssim={ssim:.3f} grid={grid_min:.3f})"
+                    )
+
+    result = {
+        "ok": len(failures) == 0,
+        "minScore": args.min_score,
+        "selectedMcOption": option,
+        "screenshotCount": len(screenshots),
+        "referenceCount": len(references),
+        "manifestReferenceCount": manifest_ref_on_disk,
+        "pairs": pairs,
+        "failures": failures,
+    }
+    print(json.dumps(result, indent=2))
+    return 0 if result["ok"] else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())