@playcraft/cli 0.0.44 → 0.0.47

package/project-template/skills/playable-verify-ui/scripts/verify_vision_evidence.py

@@ -0,0 +1,894 @@
+#!/usr/bin/env python3
+"""
+Thin vision evidence layer for ui_diff and Video Validator.
+
+Uses Pillow only (already a required harness dependency). Does not run detection
+models. When --detections is omitted, auto-collects spatial hints from the same
+Ring 4 local verifiers (bg-clean, tile-consistency, text-overlap) so Reviewer
+gets annotated screenshots without LLM-prepared JSON.
+
+Exit 0 = pass / degraded skip, 2 = strict failure.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+DEFAULT_SCREENSHOT_PATTERNS = ("ui-diff-*.png", "load-check.png", "conform-*.png", "review-*.png")
+VERIFIER_SCRIPTS = (
+    "skills/playable-verify-ui/scripts/verify_bg_clean.py",
+    "skills/playable-verify-ui/scripts/verify_tile_consistency.py",
+    "skills/playable-verify-ui/scripts/verify_text_overlap.py",
+)
+
+
+@dataclass
+class PillowDeps:
+    Image: Any
+    ImageDraw: Any
+    ImageFont: Any
+
+
+def load_pillow() -> tuple[PillowDeps | None, str | None]:
+    try:
+        from PIL import Image, ImageDraw, ImageFont
+
+        return PillowDeps(Image=Image, ImageDraw=ImageDraw, ImageFont=ImageFont), None
+    except Exception as exc:  # pragma: no cover
+        return None, str(exc)
+
+
+def read_json(path: Path | None) -> dict[str, Any]:
+    if path is None or not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def normalize_box(raw: Any) -> list[float] | None:
+    if isinstance(raw, dict):
+        if "xyxy" in raw:
+            vals = raw["xyxy"]
+        elif all(k in raw for k in ("x1", "y1", "x2", "y2")):
+            vals = [raw["x1"], raw["y1"], raw["x2"], raw["y2"]]
+        elif all(k in raw for k in ("x", "y", "width", "height")):
+            vals = [raw["x"], raw["y"], raw["x"] + raw["width"], raw["y"] + raw["height"]]
+        elif all(k in raw for k in ("left", "top", "width", "height")):
+            vals = [raw["left"], raw["top"], raw["left"] + raw["width"], raw["top"] + raw["height"]]
+        else:
+            return None
+    elif isinstance(raw, (list, tuple)) and len(raw) >= 4:
+        vals = raw[:4]
+    else:
+        return None
+    try:
+        x1, y1, x2, y2 = [float(v) for v in vals]
+    except (TypeError, ValueError):
+        return None
+    if x2 <= x1 or y2 <= y1:
+        return None
+    return [x1, y1, x2, y2]
+
+
+def iter_raw_detections(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    if isinstance(payload.get("detections"), list):
+        return [d for d in payload["detections"] if isinstance(d, dict)]
+    if isinstance(payload.get("items"), list):
+        return [d for d in payload["items"] if isinstance(d, dict)]
+    boxes = payload.get("boxes")
+    if not isinstance(boxes, list):
+        return []
+    class_names = payload.get("className") or payload.get("classNames") or []
+    confidences = payload.get("confidence") or payload.get("confidences") or []
+    frames = payload.get("frame") or payload.get("frames") or []
+    source_paths = payload.get("sourcePath") or payload.get("sourcePaths") or []
+    out: list[dict[str, Any]] = []
+    for i, box in enumerate(boxes):
+        out.append(
+            {
+                "box": box,
+                "className": class_names[i] if i < len(class_names) else "object",
+                "confidence": confidences[i] if i < len(confidences) else 1.0,
+                "frame": frames[i] if i < len(frames) else None,
+                "sourcePath": source_paths[i] if i < len(source_paths) else None,
+            }
+        )
+    return out
+
+
+def normalize_detections(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    normalized: list[dict[str, Any]] = []
+    for raw in iter_raw_detections(payload):
+        box = normalize_box(raw.get("box") or raw.get("bbox") or raw.get("xyxy") or raw)
+        if not box:
+            continue
+        class_name = str(raw.get("className") or raw.get("class_name") or raw.get("label") or "object")
+        try:
+            confidence = float(raw.get("confidence", raw.get("score", 1.0)))
+        except (TypeError, ValueError):
+            confidence = 1.0
+        frame = raw.get("frame")
+        try:
+            frame = None if frame is None else int(frame)
+        except (TypeError, ValueError):
+            frame = None
+        normalized.append(
+            {
+                "box": box,
+                "className": class_name,
+                "confidence": max(0.0, min(1.0, confidence)),
+                "frame": frame,
+                "sourcePath": str(raw.get("sourcePath") or raw.get("source_path") or ""),
+                "recommendedSkill": route_skill(class_name),
+                "alphaStrategy": route_alpha_strategy(class_name),
+            }
+        )
+    return normalized
+
+
+def iter_raw_issues(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    if isinstance(payload.get("issues"), list):
+        return [i for i in payload["issues"] if isinstance(i, dict)]
+    if isinstance(payload.get("findings"), list):
+        issues: list[dict[str, Any]] = []
+        for idx, finding in enumerate(payload["findings"]):
+            if not isinstance(finding, dict):
+                continue
+            details = finding.get("details") if isinstance(finding.get("details"), dict) else {}
+            issues.append(
+                {
+                    "id": details.get("id") or f"finding:{idx}",
+                    "status": finding.get("status", "warn"),
+                    "severity": details.get("severity", "P2"),
+                    "className": details.get("className") or finding.get("check") or "validator_finding",
+                    "message": finding.get("message", ""),
+                    "evidenceType": details.get("evidenceType", "screenshot"),
+                    "sourcePath": details.get("sourcePath", ""),
+                    "box": details.get("box"),
+                    "recommendedSkill": details.get("recommendedSkill"),
+                    "alphaStrategy": details.get("alphaStrategy"),
+                }
+            )
+        return issues
+    return []
+
+
+def normalize_issue(raw: dict[str, Any], idx: int) -> dict[str, Any]:
+    class_name = str(raw.get("className") or raw.get("class_name") or raw.get("label") or "validator_issue")
+    status = str(raw.get("status") or "warn")
+    if status not in {"pass", "warn", "fail"}:
+        status = "warn"
+    evidence_type = str(raw.get("evidenceType") or raw.get("evidence_type") or "screenshot")
+    if evidence_type not in {"screenshot", "asset", "asset-group"}:
+        evidence_type = "screenshot"
+    issue = {
+        "id": str(raw.get("id") or f"{class_name}:{idx}"),
+        "status": status,
+        "severity": str(raw.get("severity") or ("P1" if status == "fail" else "P2")),
+        "className": class_name,
+        "message": str(raw.get("message") or class_name),
+        "evidenceType": evidence_type,
+        "sourcePath": str(raw.get("sourcePath") or raw.get("source_path") or ""),
+        "recommendedSkill": str(raw.get("recommendedSkill") or route_skill(class_name)),
+        "alphaStrategy": str(raw.get("alphaStrategy") or route_alpha_strategy(class_name)),
+    }
+    box = normalize_box(raw.get("box") or raw.get("bbox") or raw.get("xyxy"))
+    if box:
+        issue["box"] = box
+    if isinstance(raw.get("sources"), list):
+        issue["sources"] = raw["sources"]
+    if isinstance(raw.get("metrics"), dict):
+        issue["metrics"] = raw["metrics"]
+    return issue
+
+
+def normalize_issues(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    return [normalize_issue(raw, idx) for idx, raw in enumerate(iter_raw_issues(payload))]
+
+
+def detection_from_issue(issue: dict[str, Any]) -> dict[str, Any] | None:
+    box = normalize_box(issue.get("box"))
+    if not box:
+        return None
+    return {
+        "id": issue["id"],
+        "status": issue["status"],
+        "severity": issue["severity"],
+        "message": issue["message"],
+        "evidenceType": issue["evidenceType"],
+        "box": box,
+        "className": issue["className"],
+        "confidence": 1.0,
+        "frame": issue.get("frame"),
+        "sourcePath": issue.get("sourcePath", ""),
+        "recommendedSkill": issue["recommendedSkill"],
+        "alphaStrategy": issue["alphaStrategy"],
+    }
+
+
+def detections_from_issues(issues: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    detections: list[dict[str, Any]] = []
+    dropped: list[dict[str, Any]] = []
+    for issue in issues:
+        if issue.get("evidenceType") == "asset-group":
+            continue
+        det = detection_from_issue(issue)
+        if det is None:
+            dropped.append(
+                {
+                    "id": issue.get("id"),
+                    "sourcePath": issue.get("sourcePath", ""),
+                    "className": issue.get("className"),
+                    "reason": "issue has no valid box for deterministic annotation",
+                }
+            )
+            continue
+        detections.append(det)
+    return detections, dropped
+
+
+def route_skill(class_name: str) -> str:
+    name = class_name.lower()
+    if any(token in name for token in ("halo", "glow", "particle", "vfx", "black_block")):
+        return "playable-fx-peak"
+    if any(token in name for token in ("crack", "shard", "decompose", "wrong_tile")):
+        return "playable-fx-decompose"
+    if any(token in name for token in ("fringe", "white_edge", "green_edge", "alpha", "matte")):
+        return "playable-art"
+    if any(token in name for token in ("overlap", "cta", "hud", "layout", "text", "grid", "baked")):
+        return "playable-verify-ui"
+    return "n-a"
+
+
+def route_alpha_strategy(class_name: str) -> str:
+    name = class_name.lower()
+    if any(token in name for token in ("halo", "glow", "particle", "vfx", "black_block")):
+        return "black-add"
+    if any(token in name for token in ("fringe", "white_edge", "green_edge", "matte", "alpha")):
+        return "rgb-alpha-split"
+    if "dual" in name or "double" in name:
+        return "rgb-alpha-split"
+    return "n-a"
+
+
+def region_box(w: int, h: int, name: str) -> list[float]:
+    if name == "top":
+        return [0.0, 0.0, float(w), float(h) * 0.18]
+    if name == "bottom":
+        return [0.0, float(h) * 0.82, float(w), float(h)]
+    if name == "board":
+        return [float(w) * 0.08, float(h) * 0.22, float(w) * 0.92, float(h) * 0.72]
+    return [0.0, 0.0, float(w), float(h)]
+
+
+def run_verifier_json(root: Path, script_rel: str) -> dict[str, Any]:
+    script = root / script_rel
+    if not script.exists():
+        return {}
+    proc = subprocess.run(
+        [sys.executable, str(script), "--root", str(root)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode not in (0, 2):
+        return {}
+    try:
+        return json.loads(proc.stdout or "{}")
+    except json.JSONDecodeError:
+        return {}
+
+
+def tile_content_bbox(image_mod: Any, path: Path) -> list[float] | None:
+    img = image_mod.open(path).convert("RGBA")
+    w, h = img.size
+    pixels = img.load()
+    min_x, min_y, max_x, max_y = w, h, 0, 0
+    found = False
+    for y in range(h):
+        for x in range(w):
+            if pixels[x, y][3] > 16:
+                found = True
+                min_x = min(min_x, x)
+                min_y = min(min_y, y)
+                max_x = max(max_x, x)
+                max_y = max(max_y, y)
+    if not found:
+        return None
+    return [float(min_x), float(min_y), float(max_x + 1), float(max_y + 1)]
+
+
+def ocr_boxes_for_cta(image_mod: Any, path: Path) -> list[dict[str, Any]]:
+    try:
+        import pytesseract
+        from pytesseract import Output
+    except Exception:
+        return []
+    img = image_mod.open(path)
+    w, h = img.size
+    crop = img.crop((0, int(h * 0.55), w, h))
+    offset_y = int(h * 0.55)
+    data = pytesseract.image_to_data(crop, output_type=Output.DICT)
+    boxes: list[dict[str, Any]] = []
+    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
+        left = int(data["left"][i])
+        top = int(data["top"][i]) + offset_y
+        width = int(data["width"][i])
+        height = int(data["height"][i])
+        boxes.append(
+            {
+                "box": [left, top, left + width, top + height],
+                "className": "text_overlap",
+                "confidence": max(0.0, min(1.0, conf / 100.0)),
+                "sourcePath": str(path),
+                "text": text,
+            }
+        )
+    return boxes
+
+
+def detections_from_bg_clean(root: Path, payload: dict[str, Any], image_mod: Any) -> list[dict[str, Any]]:
+    if payload.get("ok") is True and not payload.get("failures"):
+        return []
+    out: list[dict[str, Any]] = []
+    for asset in payload.get("assets") or []:
+        if not isinstance(asset, dict):
+            continue
+        rel = str(asset.get("path") or "")
+        if not rel or not asset.get("failures"):
+            continue
+        path = root / rel
+        if not path.exists():
+            continue
+        img = image_mod.open(path)
+        w, h = img.size
+        flagged_regions: set[str] = set()
+        for failure in asset.get("failures") or []:
+            text = str(failure).lower()
+            if "top roi" in text:
+                flagged_regions.add("top")
+            elif "bottom roi" in text:
+                flagged_regions.add("bottom")
+            elif "board roi" in text or "grid" in text or "composite" in text:
+                flagged_regions.add("board")
+        if not flagged_regions:
+            flagged_regions.add("board")
+        for region in flagged_regions:
+            box = region_box(w, h, region)
+            class_name = "baked_grid" if region == "board" else f"bg_{region}_text"
+            out.append(
+                {
+                    "box": box,
+                    "className": class_name,
+                    "confidence": 0.85,
+                    "sourcePath": rel,
+                    "recommendedSkill": route_skill(class_name),
+                    "alphaStrategy": route_alpha_strategy(class_name),
+                }
+            )
+    return out
+
+
+def detections_from_tile_consistency(root: Path, payload: dict[str, Any], image_mod: Any) -> list[dict[str, Any]]:
+    if payload.get("ok") is True and not payload.get("failures"):
+        return []
+    out: list[dict[str, Any]] = []
+    tiles_dir = root / "assets" / "images" / "tiles"
+    group = payload.get("silhouetteGroup") or []
+    for name in group:
+        path = tiles_dir / name
+        if not path.exists():
+            continue
+        box = tile_content_bbox(image_mod, path)
+        if not box:
+            continue
+        out.append(
+            {
+                "box": box,
+                "className": "tile_inconsistent",
+                "confidence": 0.8,
+                "sourcePath": str(path.relative_to(root)),
+                "recommendedSkill": route_skill("wrong_tile"),
+                "alphaStrategy": route_alpha_strategy("wrong_tile"),
+            }
+        )
+    return out
+
+
+def detections_from_text_overlap(root: Path, payload: dict[str, Any], image_mod: Any) -> list[dict[str, Any]]:
+    if payload.get("ok") is True and not payload.get("failures"):
+        return []
+    if not payload.get("ocrAvailable", True):
+        return []
+    logs = root / "logs"
+    out: list[dict[str, Any]] = []
+    for pattern in ("ui-diff-*.png", "load-check.png"):
+        for path in sorted(logs.glob(pattern)):
+            for raw in ocr_boxes_for_cta(image_mod, path):
+                rel = str(path.relative_to(root))
+                out.append(
+                    {
+                        "box": raw["box"],
+                        "className": raw["className"],
+                        "confidence": raw["confidence"],
+                        "sourcePath": rel,
+                        "recommendedSkill": route_skill("text_overlap"),
+                        "alphaStrategy": route_alpha_strategy("text_overlap"),
+                    }
+                )
+    return out
+
+
+def collect_auto_detections(root: Path, image_mod: Any) -> tuple[list[dict[str, Any]], list[str]]:
+    sources: list[str] = []
+    merged: list[dict[str, Any]] = []
+    collectors = (
+        ("verify_bg_clean", detections_from_bg_clean),
+        ("verify_tile_consistency", detections_from_tile_consistency),
+        ("verify_text_overlap", detections_from_text_overlap),
+    )
+    for i, (name, collector) in enumerate(collectors):
+        payload = run_verifier_json(root, VERIFIER_SCRIPTS[i])
+        if payload:
+            sources.append(name)
+            merged.extend(collector(root, payload, image_mod))
+    return merged, sources
+
+
+def collect_auto_issues(root: Path) -> tuple[list[dict[str, Any]], list[str]]:
+    sources: list[str] = []
+    issues: list[dict[str, Any]] = []
+    for script_rel in VERIFIER_SCRIPTS:
+        name = Path(script_rel).stem
+        payload = run_verifier_json(root, script_rel)
+        if not payload:
+            continue
+        sources.append(name)
+        normalized = normalize_issues(payload)
+        if normalized:
+            issues.extend(normalized)
+    return issues, sources
+
+
+def collect_screenshots(root: Path, logs_dir: Path) -> list[Path]:
+    found: list[Path] = []
+    seen: set[Path] = set()
+    if not logs_dir.exists():
+        return []
+    for pattern in DEFAULT_SCREENSHOT_PATTERNS:
+        for path in sorted(logs_dir.glob(pattern)):
+            resolved = path.resolve()
+            if resolved not in seen:
+                seen.add(resolved)
+                found.append(path)
+    return found
+
+
+def detections_for_source(detections: list[dict[str, Any]], source: Path, root: Path) -> list[dict[str, Any]]:
+    source_posix = source.as_posix()
+    rel = source.relative_to(root).as_posix()
+    by_path = [
+        d
+        for d in detections
+        if d.get("sourcePath") and (d["sourcePath"] in source_posix or d["sourcePath"] in rel)
+    ]
+    if by_path:
+        return by_path
+    return [d for d in detections if not d.get("sourcePath")]
+
+
+def annotate_image(deps: PillowDeps, image: Any, detections: list[dict[str, Any]]) -> Any:
+    annotated = image.copy().convert("RGBA")
+    overlay = deps.Image.new("RGBA", annotated.size, (0, 0, 0, 0))
+    draw = deps.ImageDraw.Draw(overlay)
+    try:
+        font = deps.ImageFont.load_default()
+    except Exception:
+        font = None
+    for det in detections:
+        x1, y1, x2, y2 = [int(v) for v in det["box"]]
+        draw.rectangle([x1, y1, x2, y2], outline=(255, 64, 64, 255), width=3)
+        label = f"{det['className']} {det['confidence']:.2f}"
+        if font is not None:
+            text_box = draw.textbbox((x1, max(0, y1 - 14)), label, font=font)
+            draw.rectangle(text_box, fill=(255, 64, 64, 200))
+            draw.text((x1, max(0, y1 - 14)), label, fill=(255, 255, 255, 255), font=font)
+    return deps.Image.alpha_composite(annotated, overlay).convert("RGB")
+
+
+def summarize_detection(
+    det: dict[str, Any],
+    source: Path,
+    root: Path,
+    evidence_type: str = "screenshot",
+) -> dict[str, Any]:
+    return {
+        "id": det.get("id"),
+        "source": str(source.relative_to(root)),
+        "evidenceType": evidence_type,
+        "status": det.get("status", "warn"),
+        "severity": det.get("severity", "evidence"),
+        "message": det.get("message"),
+        "frame": det.get("frame"),
+        "className": det["className"],
+        "confidence": det["confidence"],
+        "box": det["box"],
+        "recommendedSkill": det["recommendedSkill"],
+        "alphaStrategy": det["alphaStrategy"],
+    }
+
+
+def process_screenshots(
+    deps: PillowDeps,
+    root: Path,
+    screenshots: list[Path],
+    detections: list[dict[str, Any]],
+    out_dir: Path,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], set[tuple[str, str, tuple[float, float, float, float], int | None]]]:
+    images: list[dict[str, Any]] = []
+    findings: list[dict[str, Any]] = []
+    used: set[tuple[str, str, tuple[float, float, float, float], int | None]] = set()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for path in screenshots:
+        try:
+            image = deps.Image.open(path)
+        except Exception:
+            findings.append({"source": str(path.relative_to(root)), "severity": "warn", "message": "image unreadable"})
+            continue
+        source_dets = detections_for_source(detections, path, root)
+        for det in source_dets:
+            used.add(detection_key(det))
+        annotated = annotate_image(deps, image, source_dets)
+        out_path = out_dir / f"{path.stem}-vision.png"
+        annotated.save(out_path, format="PNG")
+        images.append(
+            {
+                "source": str(path.relative_to(root)),
+                "annotated": str(out_path.relative_to(root)),
+                "detections": len(source_dets),
+            }
+        )
+        for det in source_dets:
+            finding = summarize_detection(det, path, root, "screenshot")
+            findings.append(finding)
+    return images, findings, used
+
+
+def detection_key(det: dict[str, Any]) -> tuple[str, str, tuple[float, float, float, float], int | None]:
+    box = tuple(round(float(v), 3) for v in det["box"])
+    return (str(det.get("sourcePath") or ""), str(det.get("className") or ""), box, det.get("frame"))
+
+
+def source_path_for_detection(root: Path, det: dict[str, Any]) -> Path | None:
+    raw = str(det.get("sourcePath") or "").strip()
+    if not raw:
+        return None
+    path = Path(raw)
+    if not path.is_absolute():
+        path = root / raw
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return None
+    return path if path.exists() else None
+
+
+def process_asset_detections(
+    deps: PillowDeps,
+    root: Path,
+    detections: list[dict[str, Any]],
+    used: set[tuple[str, str, tuple[float, float, float, float], int | None]],
+    out_dir: Path,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
+    assets: list[dict[str, Any]] = []
+    findings: list[dict[str, Any]] = []
+    dropped: list[dict[str, Any]] = []
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    for det in detections:
+        key = detection_key(det)
+        if key in used:
+            continue
+        source = source_path_for_detection(root, det)
+        if source is None:
+            dropped.append(
+                {
+                    "sourcePath": str(det.get("sourcePath") or ""),
+                    "className": det.get("className"),
+                    "reason": "sourcePath does not match a screenshot and is not a readable asset under project root",
+                }
+            )
+            continue
+        try:
+            image = deps.Image.open(source)
+        except Exception:
+            dropped.append(
+                {
+                    "sourcePath": str(det.get("sourcePath") or ""),
+                    "className": det.get("className"),
+                    "reason": "asset image unreadable",
+                }
+            )
+            continue
+
+        annotated = annotate_image(deps, image, [det])
+        rel = source.relative_to(root)
+        safe_stem = "-".join(rel.with_suffix("").parts)
+        out_path = out_dir / f"{safe_stem}-asset-vision.png"
+        annotated.save(out_path, format="PNG")
+        assets.append(
+            {
+                "source": str(rel),
+                "annotated": str(out_path.relative_to(root)),
+                "detections": 1,
+            }
+        )
+        finding = summarize_detection(det, source, root, "asset")
+        finding["annotated"] = str(out_path.relative_to(root))
+        findings.append(finding)
+
+    return assets, findings, dropped
+
+
+def safe_output_stem(value: str) -> str:
+    cleaned = "".join(ch if ch.isalnum() or ch in ("-", "_", ".") else "-" for ch in value)
+    return cleaned.strip("-") or "issue"
+
+
+def source_entry_path(root: Path, entry: Any) -> tuple[str, Path | None]:
+    if isinstance(entry, dict):
+        raw = str(entry.get("sourcePath") or entry.get("path") or "")
+    else:
+        raw = str(entry or "")
+    if not raw:
+        return "", None
+    path = Path(raw)
+    if not path.is_absolute():
+        path = root / raw
+    try:
+        rel = path.relative_to(root).as_posix()
+    except ValueError:
+        return raw, None
+    return rel, path if path.exists() else None
+
+
+def render_group_evidence(
+    deps: PillowDeps,
+    root: Path,
+    issue: dict[str, Any],
+    out_dir: Path,
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None, list[dict[str, Any]]]:
+    sources = issue.get("sources") if isinstance(issue.get("sources"), list) else []
+    dropped: list[dict[str, Any]] = []
+    tiles: list[dict[str, Any]] = []
+    thumb_w, thumb_h = 176, 150
+    for entry in sources:
+        rel, path = source_entry_path(root, entry)
+        if path is None:
+            dropped.append(
+                {
+                    "id": issue.get("id"),
+                    "sourcePath": rel,
+                    "className": issue.get("className"),
+                    "reason": "asset-group source is missing or outside project root",
+                }
+            )
+            continue
+        try:
+            image = deps.Image.open(path).convert("RGBA")
+        except Exception:
+            dropped.append(
+                {
+                    "id": issue.get("id"),
+                    "sourcePath": rel,
+                    "className": issue.get("className"),
+                    "reason": "asset-group source image unreadable",
+                }
+            )
+            continue
+        image.thumbnail((thumb_w, thumb_h))
+        metrics = entry.get("metrics") if isinstance(entry, dict) and isinstance(entry.get("metrics"), dict) else {}
+        tiles.append({"rel": rel, "image": image, "metrics": metrics})
+
+    if not tiles:
+        return None, None, dropped
+
+    cols = min(4, max(1, len(tiles)))
+    rows = (len(tiles) + cols - 1) // cols
+    label_h = 76
+    pad = 14
+    canvas_w = cols * (thumb_w + pad) + pad
+    canvas_h = rows * (thumb_h + label_h + pad) + pad
+    canvas = deps.Image.new("RGB", (canvas_w, canvas_h), (248, 248, 248))
+    draw = deps.ImageDraw.Draw(canvas)
+    try:
+        font = deps.ImageFont.load_default()
+    except Exception:
+        font = None
+
+    for idx, tile in enumerate(tiles):
+        col = idx % cols
+        row = idx // cols
+        x = pad + col * (thumb_w + pad)
+        y = pad + row * (thumb_h + label_h + pad)
+        draw.rectangle([x, y, x + thumb_w, y + thumb_h + label_h], outline=(220, 220, 220), width=1)
+        image = tile["image"]
+        ox = x + (thumb_w - image.width) // 2
+        oy = y + (thumb_h - image.height) // 2
+        canvas.paste(image.convert("RGB"), (ox, oy), image if image.mode == "RGBA" else None)
+        label = Path(tile["rel"]).name
+        metrics = tile.get("metrics") or {}
+        metric_lines = [
+            f"{k}={metrics[k]}"
+            for k in ("bboxOccupancy", "aspect", "fillRatio")
+            if k in metrics
+        ]
+        draw.text((x + 6, y + thumb_h + 8), label[:28], fill=(30, 30, 30), font=font)
+        for line_idx, metric_label in enumerate(metric_lines[:3]):
+            draw.text(
+                (x + 6, y + thumb_h + 26 + line_idx * 14),
+                metric_label[:30],
+                fill=(120, 40, 40),
+                font=font,
+            )
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / f"{safe_output_stem(str(issue.get('id') or issue.get('className')))}-group-vision.png"
+    canvas.save(out_path, format="PNG")
+    output = {
+        "id": issue.get("id"),
+        "source": issue.get("sourcePath", ""),
+        "annotated": str(out_path.relative_to(root)),
+        "sources": [tile["rel"] for tile in tiles],
+        "detections": len(tiles),
+    }
+    finding = {
+        "id": issue.get("id"),
+        "source": issue.get("sourcePath", ""),
+        "evidenceType": "asset-group",
+        "status": issue.get("status", "warn"),
+        "severity": issue.get("severity", "P1"),
+        "message": issue.get("message"),
+        "className": issue.get("className"),
+        "recommendedSkill": issue.get("recommendedSkill"),
+        "alphaStrategy": issue.get("alphaStrategy"),
+        "annotated": str(out_path.relative_to(root)),
+        "metrics": issue.get("metrics", {}),
+    }
+    return output, finding, dropped
+
+
+def process_group_issues(
+    deps: PillowDeps,
+    root: Path,
+    issues: list[dict[str, Any]],
+    out_dir: Path,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
+    groups: list[dict[str, Any]] = []
+    findings: list[dict[str, Any]] = []
+    dropped: list[dict[str, Any]] = []
+    for issue in issues:
+        if issue.get("evidenceType") != "asset-group":
+            continue
+        output, finding, group_dropped = render_group_evidence(deps, root, issue, out_dir)
+        if output:
+            groups.append(output)
+        if finding:
+            findings.append(finding)
+        dropped.extend(group_dropped)
+    return groups, findings, dropped
+
+
+def write_report(path: Path, report: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate thin Pillow vision evidence for Reviewer")
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--issues", type=Path, default=None, help="Validator issues JSON generated by verify:ui")
+    parser.add_argument("--detections", type=Path, default=None, help="Optional detector JSON from playcraft tools detect")
+    parser.add_argument("--strict", action="store_true", help="Fail when Pillow or evidence inputs are missing")
+    parser.add_argument("--json", action="store_true", help="Print report JSON to stdout")
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    out_dir = root / "validate" / "vision"
+    report_path = out_dir / "vision-evidence.json"
+    deps, dep_error = load_pillow()
+    if deps is None:
+        report = {
+            "ok": not args.strict,
+            "status": "degraded",
+            "reason": "Pillow is not installed",
+            "detail": dep_error,
+            "install": "pip install -r skills/playable-verify-ui/requirements.txt",
+            "issues": [],
+            "findings": [],
+        }
+        write_report(report_path, report)
+        if args.json:
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+        return 2 if args.strict else 0
+
+    issue_payload = read_json(args.issues.resolve() if args.issues else None)
+    issues = normalize_issues(issue_payload)
+    auto_sources: list[str] = []
+    if not issues:
+        issues, auto_sources = collect_auto_issues(root)
+
+    issue_detections, issue_dropped = detections_from_issues(issues)
+    detector_payload = read_json(args.detections.resolve() if args.detections else None)
+    detector_detections = normalize_detections(detector_payload)
+    detections = issue_detections + detector_detections
+
+    screenshots = collect_screenshots(root, root / "logs")
+    image_outputs, image_findings, used_detections = process_screenshots(deps, root, screenshots, detections, out_dir)
+    asset_outputs, asset_findings, dropped_detections = process_asset_detections(
+        deps,
+        root,
+        detections,
+        used_detections,
+        out_dir,
+    )
+    group_outputs, group_findings, group_dropped = process_group_issues(deps, root, issues, out_dir)
+    dropped_detections = issue_dropped + dropped_detections + group_dropped
+
+    status = "pass"
+    failures: list[str] = []
+    if args.strict and not image_outputs:
+        status = "fail"
+        failures.append("no screenshots found for vision evidence")
+    report = {
+        "ok": status != "fail",
+        "status": status,
+        "issuesJson": str(args.issues) if args.issues else None,
+        "detectorJson": str(args.detections) if args.detections else None,
+        "autoSources": auto_sources,
+        "summary": {
+            "screenshots": len(screenshots),
+            "detections": len(detections),
+            "annotatedImages": len(image_outputs),
+            "assetEvidence": len(asset_outputs),
+            "groupEvidence": len(group_outputs),
+            "droppedDetections": len(dropped_detections),
+        },
+        "issues": issues,
+        "images": image_outputs,
+        "assets": asset_outputs,
+        "groups": group_outputs,
+        "findings": image_findings + asset_findings + group_findings,
+        "droppedDetections": dropped_detections,
+        "failures": failures,
+    }
+    write_report(report_path, report)
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print(f"[verify:vision] {status.upper()} — {report_path.relative_to(root)}")
+        print(
+            f"  screenshots={report['summary']['screenshots']} "
+            f"detections={report['summary']['detections']} "
+            f"groups={report['summary']['groupEvidence']} "
+            f"autoSources={','.join(auto_sources) if auto_sources else 'none'}"
+        )
+    return 0 if report["ok"] else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())