@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/threejs/skills/playable-verify-ui/scripts/verify_slice_plan.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""Validate GPT art slice-plan evidence as a machine gate."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+SCHEMA = "playcraft.slice-plan-validator.v1"
+BLOCKING_CLASSES = {"source_clipped", "slice_count_mismatch", "slice_safe_box_invalid"}
+
+
+def rel(root: Path, path: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def issue(
+    issue_id: str,
+    status: str,
+    severity: str,
+    class_name: str,
+    message: str,
+    source_path: str,
+    *,
+    box: list[float] | None = None,
+    metrics: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    item: dict[str, Any] = {
+        "id": issue_id,
+        "status": status,
+        "severity": severity,
+        "className": class_name,
+        "message": message,
+        "evidenceType": "asset",
+        "sourcePath": source_path,
+        "recommendedSkill": "playable-art",
+        "alphaStrategy": "n-a",
+    }
+    if box is not None:
+        item["box"] = box
+    if metrics:
+        item["metrics"] = metrics
+    return item
+
+
+def box_is_valid(box: Any, image_size: Any) -> bool:
+    if not isinstance(box, list) or len(box) != 4:
+        return False
+    if not all(isinstance(v, (int, float)) for v in box):
+        return False
+    x1, y1, x2, y2 = [float(v) for v in box]
+    if x1 < 0 or y1 < 0 or x2 <= x1 or y2 <= y1:
+        return False
+    if isinstance(image_size, list) and len(image_size) == 2:
+        w, h = image_size
+        if isinstance(w, (int, float)) and isinstance(h, (int, float)):
+            if x2 > float(w) or y2 > float(h):
+                return False
+    return True
+
+
+def normalized_box(box: Any) -> list[float] | None:
+    if not isinstance(box, list) or len(box) != 4:
+        return None
+    if not all(isinstance(v, (int, float)) for v in box):
+        return None
+    return [float(v) for v in box]
+
+
+def validate_plan(root: Path, plan_path: Path, strict: bool) -> dict[str, Any]:
+    if not plan_path.exists():
+        return {
+            "schemaVersion": SCHEMA,
+            "ok": True,
+            "issues": [],
+            "summary": {
+                "status": "pass",
+                "plan": rel(root, plan_path),
+                "sheets": 0,
+                "marks": 0,
+                "fail": 0,
+                "warn": 0,
+                "skipped": True,
+            },
+        }
+
+    try:
+        plan = json.loads(plan_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        fail = issue(
+            "slice_plan_invalid",
+            "fail",
+            "P1",
+            "slice_plan_invalid",
+            f"slice-plan JSON is unreadable: {exc}",
+            rel(root, plan_path),
+        )
+        return {
+            "schemaVersion": SCHEMA,
+            "ok": False,
+            "issues": [fail],
+            "summary": {"status": "fail", "plan": rel(root, plan_path), "sheets": 0, "marks": 0, "fail": 1, "warn": 0},
+        }
+
+    issues: list[dict[str, Any]] = []
+    sheets = plan.get("sheets") if isinstance(plan.get("sheets"), list) else []
+    mark_count = 0
+
+    for sheet_index, sheet in enumerate(sheets):
+        if not isinstance(sheet, dict):
+            continue
+        source = str(sheet.get("sourcePath") or sheet.get("source") or rel(root, plan_path))
+        image_size = sheet.get("imageSize")
+        expected = sheet.get("expected")
+        marks = sheet.get("marks") if isinstance(sheet.get("marks"), list) else []
+        marked = sheet.get("marked", len(marks))
+
+        if isinstance(expected, int) and int(marked) != expected:
+            issues.append(
+                issue(
+                    f"slice_count_mismatch:{source}",
+                    "fail",
+                    "P1",
+                    "slice_count_mismatch",
+                    f"slice count mismatch: expected {expected}, found {marked}",
+                    source,
+                    metrics={"expected": expected, "marked": marked, "sheetIndex": sheet_index},
+                )
+            )
+
+        dropped = sheet.get("droppedFragments")
+        if isinstance(dropped, list) and dropped:
+            issues.append(
+                issue(
+                    f"slice_count_mismatch:dropped:{source}",
+                    "fail",
+                    "P1",
+                    "slice_count_mismatch",
+                    f"slice plan dropped {len(dropped)} fragment(s)",
+                    source,
+                    metrics={"droppedFragments": len(dropped), "sheetIndex": sheet_index},
+                )
+            )
+
+        for mark_index, mark in enumerate(marks):
+            if not isinstance(mark, dict):
+                continue
+            mark_count += 1
+            safe_box = mark.get("safeSliceBox")
+            box = normalized_box(safe_box)
+            metrics = {
+                "sheetIndex": sheet_index,
+                "markIndex": mark_index,
+                "label": mark.get("label"),
+                "margin": mark.get("margin"),
+            }
+            if not box_is_valid(safe_box, image_size):
+                issues.append(
+                    issue(
+                        f"slice_safe_box_invalid:{source}:{mark_index}",
+                        "fail",
+                        "P1",
+                        "slice_safe_box_invalid",
+                        "safeSliceBox is missing, inverted, negative, or outside the source image",
+                        source,
+                        box=box,
+                        metrics=metrics,
+                    )
+                )
+
+            for raw in mark.get("issues", []) if isinstance(mark.get("issues"), list) else []:
+                if not isinstance(raw, dict):
+                    continue
+                class_name = str(raw.get("className") or raw.get("class_name") or raw.get("id") or "slice_issue")
+                severity = str(raw.get("severity") or ("P1" if class_name in BLOCKING_CLASSES else "P2"))
+                is_blocking = class_name in BLOCKING_CLASSES or severity in {"P0", "P1"}
+                status = "fail" if is_blocking or (strict and class_name == "slice_margin_tight") else "warn"
+                if class_name == "slice_margin_tight" and not strict:
+                    severity = "P2"
+                issues.append(
+                    issue(
+                        f"{class_name}:{source}:{mark_index}",
+                        status,
+                        "P1" if status == "fail" else severity,
+                        class_name,
+                        str(raw.get("message") or class_name),
+                        source,
+                        box=box,
+                        metrics={**metrics, **(raw.get("metrics") if isinstance(raw.get("metrics"), dict) else {})},
+                    )
+                )
+
+    fail_count = sum(1 for item in issues if item["status"] == "fail")
+    warn_count = sum(1 for item in issues if item["status"] == "warn")
+    return {
+        "schemaVersion": SCHEMA,
+        "ok": fail_count == 0,
+        "issues": issues,
+        "summary": {
+            "status": "fail" if fail_count else "warn" if warn_count else "pass",
+            "plan": rel(root, plan_path),
+            "sheets": len(sheets),
+            "marks": mark_count,
+            "fail": fail_count,
+            "warn": warn_count,
+            "strict": strict,
+        },
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".", help="Project root")
+    parser.add_argument("--plan", default="assets/reference/slice-plan.json", help="slice-plan path")
+    parser.add_argument("--strict", action="store_true", help="Upgrade slice_margin_tight to fail")
+    parser.add_argument("--json", action="store_true", help="Print JSON to stdout")
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    plan_path = Path(args.plan)
+    if not plan_path.is_absolute():
+        plan_path = root / plan_path
+    report = validate_plan(root, plan_path, args.strict)
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print(f"[verify:slice-plan] {report['summary']['status'].upper()} — {report['summary']['plan']}")
+    return 2 if any(item.get("status") == "fail" for item in report.get("issues", [])) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/project-templates/threejs/skills/playable-verify-ui/scripts/verify_slice_plan_test.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Unit tests for verify_slice_plan.py."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).resolve().with_name("verify_slice_plan.py")
+spec = importlib.util.spec_from_file_location("verify_slice_plan", SCRIPT)
+assert spec and spec.loader
+module = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = module
+spec.loader.exec_module(module)
+
+
+class VerifySlicePlanTest(unittest.TestCase):
+    def make_root(self, plan: dict) -> Path:
+        root = Path(tempfile.mkdtemp(prefix="playcraft-slice-plan-"))
+        plan_path = root / "assets" / "reference" / "slice-plan.json"
+        plan_path.parent.mkdir(parents=True)
+        plan_path.write_text(json.dumps(plan), encoding="utf-8")
+        return root
+
+    def test_clean_plan_passes(self) -> None:
+        root = self.make_root(
+            {
+                "schemaVersion": "playcraft.slice-plan.v1",
+                "sheets": [
+                    {
+                        "sourcePath": "assets/reference/sheet.png",
+                        "imageSize": [100, 100],
+                        "expected": 1,
+                        "marked": 1,
+                        "marks": [{"safeSliceBox": [10, 10, 50, 50], "issues": []}],
+                    }
+                ],
+            }
+        )
+
+        report = module.validate_plan(root, root / "assets" / "reference" / "slice-plan.json", strict=False)
+
+        self.assertTrue(report["ok"])
+        self.assertEqual(report["summary"]["status"], "pass")
+
+    def test_source_clipped_fails(self) -> None:
+        root = self.make_root(
+            {
+                "schemaVersion": "playcraft.slice-plan.v1",
+                "sheets": [
+                    {
+                        "sourcePath": "assets/reference/sheet.png",
+                        "imageSize": [100, 100],
+                        "expected": 1,
+                        "marked": 1,
+                        "marks": [
+                            {
+                                "safeSliceBox": [0, 0, 50, 50],
+                                "issues": [{"className": "source_clipped", "severity": "P1"}],
+                            }
+                        ],
+                    }
+                ],
+            }
+        )
+
+        report = module.validate_plan(root, root / "assets" / "reference" / "slice-plan.json", strict=False)
+
+        self.assertFalse(report["ok"])
+        self.assertTrue(any(i["className"] == "source_clipped" and i["status"] == "fail" for i in report["issues"]))
+
+    def test_invalid_safe_slice_box_fails(self) -> None:
+        root = self.make_root(
+            {
+                "schemaVersion": "playcraft.slice-plan.v1",
+                "sheets": [
+                    {
+                        "sourcePath": "assets/reference/sheet.png",
+                        "imageSize": [100, 100],
+                        "marks": [{"safeSliceBox": [70, 10, 50, 50], "issues": []}],
+                    }
+                ],
+            }
+        )
+
+        report = module.validate_plan(root, root / "assets" / "reference" / "slice-plan.json", strict=False)
+
+        self.assertFalse(report["ok"])
+        self.assertTrue(any(i["className"] == "slice_safe_box_invalid" for i in report["issues"]))
+
+    def test_tight_margin_warns_by_default_and_fails_in_strict(self) -> None:
+        root = self.make_root(
+            {
+                "schemaVersion": "playcraft.slice-plan.v1",
+                "sheets": [
+                    {
+                        "sourcePath": "assets/reference/sheet.png",
+                        "imageSize": [100, 100],
+                        "marks": [
+                            {
+                                "safeSliceBox": [10, 10, 50, 50],
+                                "issues": [{"className": "slice_margin_tight", "severity": "P2"}],
+                            }
+                        ],
+                    }
+                ],
+            }
+        )
+
+        normal = module.validate_plan(root, root / "assets" / "reference" / "slice-plan.json", strict=False)
+        strict = module.validate_plan(root, root / "assets" / "reference" / "slice-plan.json", strict=True)
+
+        self.assertTrue(normal["ok"])
+        self.assertEqual(normal["issues"][0]["status"], "warn")
+        self.assertFalse(strict["ok"])
+        self.assertEqual(strict["issues"][0]["status"], "fail")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/project-templates/threejs/skills/playable-verify-ui/scripts/verify_text_overlap.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""
+Text overlap gate — detects overlapping text regions in ui_diff screenshots (bottom/CTA ROI).
+
+Uses OCR bounding boxes. Fails when multiple text clusters overlap in CTA zone (B13).
+
+Text overlap can only be judged reliably with OCR — pixel heuristics cannot tell
+"INSTALL on top of 立即下载" (a real overlap) from "white label on a colored button"
+(legitimate). So when OCR is unavailable this gate refuses to silently pass:
+  - default: reports `degraded: true` (ok: true) so projects without tesseract are
+    not bricked, but the result clearly states the check did not run.
+  - --strict (used by the Ring 4 gate): a missing OCR toolchain is a hard failure.
+
+Usage:
+  python3 skills/playable-verify-ui/scripts/verify_text_overlap.py [--root .] [--strict]
+
+Exit 0 = pass / skip / degraded (non-strict)
+Exit 2 = fail
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import 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 allowed_text_set, load_manifest  # noqa: E402
+
+
+def make_issue(
+    *,
+    issue_id: str,
+    class_name: str,
+    message: str,
+    source_path: str,
+    box: list[float] | None = None,
+    status: str = "fail",
+    severity: str = "P1",
+    metrics: dict | None = None,
+) -> dict:
+    issue = {
+        "id": issue_id,
+        "status": status,
+        "severity": severity,
+        "className": class_name,
+        "message": message,
+        "evidenceType": "screenshot",
+        "sourcePath": source_path,
+        "recommendedSkill": "playable-verify-ui",
+        "alphaStrategy": "n-a",
+    }
+    if box is not None:
+        issue["box"] = [float(v) for v in box]
+    if metrics:
+        issue["metrics"] = metrics
+    return issue
+
+
+def global_issue(
+    *,
+    issue_id: str,
+    class_name: str,
+    message: str,
+    status: str,
+    severity: str,
+) -> dict:
+    return {
+        "id": issue_id,
+        "status": status,
+        "severity": severity,
+        "className": class_name,
+        "message": message,
+        "evidenceType": "screenshot",
+        "sourcePath": "logs",
+        "recommendedSkill": "playable-verify-ui",
+        "alphaStrategy": "n-a",
+    }
+
+
+def load_pil() -> Any | None:
+    try:
+        from PIL import Image
+
+        return Image
+    except ImportError:
+        return None
+
+
+def ocr_available() -> bool:
+    """True only when pytesseract is importable AND the tesseract binary is callable."""
+    try:
+        import pytesseract
+
+        pytesseract.get_tesseract_version()
+        return True
+    except Exception:
+        return False
+
+
+def ocr_boxes(image_mod: Any, crop: Any) -> list[dict]:
+    try:
+        import pytesseract
+        from pytesseract import Output
+
+        data = pytesseract.image_to_data(crop, output_type=Output.DICT)
+        boxes: list[dict] = []
+        n = len(data.get("text", []))
+        for i in range(n):
+            try:
+                conf = int(data["conf"][i])
+            except (TypeError, ValueError):
+                continue
+            if conf < 45:
+                continue
+            text = str(data["text"][i]).strip()
+            if len(text) < 2:
+                continue
+            boxes.append(
+                {
+                    "text": text,
+                    "left": int(data["left"][i]),
+                    "top": int(data["top"][i]),
+                    "width": int(data["width"][i]),
+                    "height": int(data["height"][i]),
+                }
+            )
+        return boxes
+    except Exception:
+        return []
+
+
+def iou(a: dict, b: dict) -> float:
+    ax2, ay2 = a["left"] + a["width"], a["top"] + a["height"]
+    bx2, by2 = b["left"] + b["width"], b["top"] + b["height"]
+    ix1, iy1 = max(a["left"], b["left"]), max(a["top"], b["top"])
+    ix2, iy2 = min(ax2, bx2), min(ay2, by2)
+    if ix2 <= ix1 or iy2 <= iy1:
+        return 0.0
+    inter = (ix2 - ix1) * (iy2 - iy1)
+    area_a = a["width"] * a["height"]
+    area_b = b["width"] * b["height"]
+    union = area_a + area_b - inter
+    return inter / union if union else 0.0
+
+
+def box_xyxy(box: dict, offset_y: int = 0) -> list[float]:
+    return [
+        float(box["left"]),
+        float(box["top"] + offset_y),
+        float(box["left"] + box["width"]),
+        float(box["top"] + offset_y + box["height"]),
+    ]
+
+
+def union_box(a: dict, b: dict, offset_y: int = 0) -> list[float]:
+    ax = box_xyxy(a, offset_y)
+    bx = box_xyxy(b, offset_y)
+    return [min(ax[0], bx[0]), min(ax[1], bx[1]), max(ax[2], bx[2]), max(ax[3], bx[3])]
+
+
+def analyze_shot(
+    image_mod: Any, path: Path, root: Path, allowed_text: set[str] | None = None
+) -> tuple[list[str], list[dict]]:
+    img = image_mod.open(path)
+    w, h = img.size
+    # CTA / bottom third where baked + art text overlap (B13)
+    offset_y = int(h * 0.55)
+    crop = img.crop((0, offset_y, w, h))
+    boxes = ocr_boxes(image_mod, crop)
+    failures: list[str] = []
+    issues: list[dict] = []
+    rel = str(path.relative_to(root))
+    # Overlap (IoU) is always a layout bug — a whitelist cannot make two
+    # overlapping labels acceptable, so this rule is never relaxed.
+    for i in range(len(boxes)):
+        for j in range(i + 1, len(boxes)):
+            overlap = iou(boxes[i], boxes[j])
+            if overlap > 0.15:
+                message = (
+                    f"{path.relative_to(root)}: overlapping text "
+                    f"{boxes[i]['text']!r} vs {boxes[j]['text']!r} (IoU={overlap:.2f})"
+                )
+                failures.append(message)
+                issues.append(
+                    make_issue(
+                        issue_id=f"text_overlap:{rel}:{i}:{j}",
+                        class_name="text_overlap",
+                        message=message,
+                        source_path=rel,
+                        box=union_box(boxes[i], boxes[j], offset_y),
+                        metrics={"iou": round(overlap, 4), "texts": [boxes[i]["text"], boxes[j]["text"]]},
+                    )
+                )
+    # The "too many text regions" heuristic is a proxy for baked text-on-art. If
+    # the manifest whitelists the legit on-screen copy (CTA label, etc.), only the
+    # UNDECLARED text counts toward the threshold — kills the false positive on a
+    # legitimately text-heavy but approved CTA.
+    allowed = allowed_text or set()
+    unknown = [b for b in boxes if b["text"].strip().lower() not in allowed]
+    if len(unknown) >= 4:
+        message = (
+            f"{path.relative_to(root)}: {len(unknown)} undeclared text regions in CTA ROI "
+            f"(of {len(boxes)} total) — possible text-on-art overlap"
+        )
+        failures.append(message)
+        issues.append(
+            make_issue(
+                issue_id=f"text_overlap_density:{rel}",
+                class_name="text_overlap",
+                message=message,
+                source_path=rel,
+                box=[0.0, float(offset_y), float(w), float(h)],
+                metrics={"unknownTextRegions": len(unknown), "totalTextRegions": len(boxes)},
+            )
+        )
+    return failures, issues
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".")
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat a missing OCR toolchain as a failure instead of a degraded pass.",
+    )
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    logs = root / "logs"
+    image_mod = load_pil()
+    if image_mod is None:
+        issue = global_issue(
+            issue_id="text_overlap:pillow_missing",
+            class_name="validator_dependency_missing",
+            message="Pillow required",
+            status="fail",
+            severity="P0",
+        )
+        print(json.dumps({"ok": False, "issues": [issue], "failures": ["Pillow required"]}))
+        return 2
+
+    # A malformed/stale manifest is a contract failure; surface it before anything else.
+    manifest, manifest_errors = load_manifest(root)
+    if manifest_errors:
+        issues = [
+            global_issue(
+                issue_id=f"asset_manifest:{i}",
+                class_name="asset_manifest_invalid",
+                message=err,
+                status="fail",
+                severity="P1",
+            )
+            for i, err in enumerate(manifest_errors)
+        ]
+        print(json.dumps({"ok": False, "manifestErrors": manifest_errors, "issues": issues, "failures": manifest_errors}, indent=2))
+        return 2
+    allowed_text = allowed_text_set(manifest)
+
+    shots = sorted(logs.glob("ui-diff-*.png")) + sorted(logs.glob("load-check.png"))
+    if not shots:
+        msg = "no ui_diff screenshots — run Reviewer ui_diff/load_check before text-overlap gate"
+        out = {
+            "ok": not args.strict,
+            "skipped": not args.strict,
+            "screenshotCount": 0,
+            "issues": [
+                global_issue(
+                    issue_id="text_overlap:no_screenshots",
+                    class_name="text_overlap_no_screenshots",
+                    message=msg,
+                    status="fail" if args.strict else "warn",
+                    severity="P2",
+                )
+            ]
+            if args.strict
+            else [],
+            "failures": [msg] if args.strict else [],
+            "note": None if args.strict else msg,
+        }
+        print(json.dumps(out, indent=2))
+        return 2 if args.strict else 0
+
+    # Text overlap is only verifiable with OCR. Never silently pass when it is absent.
+    if not ocr_available():
+        msg = (
+            "OCR toolchain unavailable (need `pip install pytesseract` + the tesseract "
+            "binary) — text-overlap cannot be verified; install OCR to run this gate"
+        )
+        out = {
+            "ok": not args.strict,
+            "ocrAvailable": False,
+            "degraded": True,
+            "screenshotCount": len(shots),
+            "issues": [
+                global_issue(
+                    issue_id="text_overlap:ocr_unavailable",
+                    class_name="text_overlap_degraded",
+                    message=msg,
+                    status="fail" if args.strict else "warn",
+                    severity="P2",
+                )
+            ],
+            "failures": [msg] if args.strict else [],
+            "note": None if args.strict else f"DEGRADED: {msg}",
+        }
+        print(json.dumps(out, indent=2))
+        return 2 if args.strict else 0
+
+    failures: list[str] = []
+    issues: list[dict] = []
+    for shot in shots:
+        shot_failures, shot_issues = analyze_shot(image_mod, shot, root, allowed_text=allowed_text)
+        failures.extend(shot_failures)
+        issues.extend(shot_issues)
+
+    out = {
+        "ok": len(failures) == 0,
+        "ocrAvailable": True,
+        "screenshotCount": len(shots),
+        "allowedTextCount": len(allowed_text),
+        "issues": issues,
+        "failures": failures,
+    }
+    print(json.dumps(out, indent=2))
+    return 0 if out["ok"] else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())