@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/phaser/skills/playable-fx-peak/scripts/repack-frame-sequence.py

@@ -0,0 +1,526 @@
+#!/usr/bin/env python3
+"""
+Slice a GPT FX sprite sheet and repack with PEAK-FRAME-driven canvas.
+
+The largest frame (by content bbox area) defines:
+  - output canvas size  (= peak bbox + padding, square by default)
+  - shared anchor       (= canvas center; every frame's centroid pasted here)
+  - unified scale       (= 1.0 unless peak exceeds --max-size cap)
+
+Usage:
+  python scripts/repack-frame-sequence.py \\
+      --raw assets/images/fx/match_burst_v2_raw.png --name match_burst_v2 --cols 6
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+ROOT = Path.cwd()
+
+Isolated = tuple[Image.Image, tuple[float, float], tuple[int, int]]
+
+
+def luminance_mask(arr: np.ndarray, threshold: int = 32) -> np.ndarray:
+    rgb = arr[:, :, :3].astype(np.float32)
+    lum = rgb.max(axis=2)
+    if arr.shape[2] == 4:
+        alpha = arr[:, :, 3].astype(np.float32) / 255.0
+        lum = lum * np.maximum(alpha, 0.05)
+    return lum > threshold
+
+
+def content_bbox(mask: np.ndarray) -> tuple[int, int, int, int] | None:
+    ys, xs = np.where(mask)
+    if len(xs) == 0:
+        return None
+    return int(xs.min()), int(ys.min()), int(xs.max()) + 1, int(ys.max()) + 1
+
+
+def cell_touches_edge(bbox: tuple[int, int, int, int], w: int, h: int, margin: int) -> bool:
+    x0, y0, x1, y1 = bbox
+    return x0 < margin or y0 < margin or x1 > w - margin or y1 > h - margin
+
+
+def normalize_cell(
+    frame: Image.Image,
+    cell_margin: int = 48,
+    lum_threshold: int = 32,
+) -> Image.Image:
+    """
+    If slice content touches the cell border (mechanical cut / neighbor bleed),
+    shrink the whole burst into the cell safe zone so flat cut lines move inward.
+    """
+    w, h = frame.size
+    arr = np.array(frame.convert("RGBA"))
+    arr = np.array(flatten_near_black(Image.fromarray(arr), threshold=lum_threshold))
+    mask = luminance_mask(arr, lum_threshold)
+    bbox = content_bbox(mask)
+    if bbox is None:
+        return Image.fromarray(arr)
+
+    x0, y0, x1, y1 = bbox
+    span_w, span_h = x1 - x0, y1 - y0
+    inner_w = max(1, w - 2 * cell_margin)
+    inner_h = max(1, h - 2 * cell_margin)
+    scale = min(inner_w / span_w, inner_h / span_h, 1.0)
+
+    if scale >= 1.0 and not cell_touches_edge(bbox, w, h, cell_margin):
+        return Image.fromarray(arr)
+
+    layer = Image.fromarray(arr).crop(bbox)
+    cx, cy = (x1 - x0) / 2, (y1 - y0) / 2
+    nw = max(1, round(span_w * scale))
+    nh = max(1, round(span_h * scale))
+    layer = layer.resize((nw, nh), Image.Resampling.LANCZOS)
+    out = Image.new("RGBA", (w, h), (0, 0, 0, 255))
+    paste_x = int(round(w / 2 - cx * scale))
+    paste_y = int(round(h / 2 - cy * scale))
+    out.alpha_composite(layer, (paste_x, paste_y))
+    return out
+
+
+def canvas_from_union(
+    isolated_list: list[Isolated | None],
+    pad_px: int,
+    square: bool = True,
+) -> tuple[int, int]:
+    """Canvas fits ALL frames when each centroid is pasted at center."""
+    half = 0.0
+    for iso in isolated_list:
+        if iso is None:
+            continue
+        _, (cx, cy), (w, h) = iso
+        half = max(half, cx, w - cx, cy, h - cy)
+    half = int(np.ceil(half))
+    if square:
+        side = 2 * half + 2 * pad_px
+        return side, side
+    # non-square: separate w/h halves
+    max_w_half = max((iso[2][0] for iso in isolated_list if iso), default=0)
+    max_h_half = max((iso[2][1] for iso in isolated_list if iso), default=0)
+    return 2 * int(np.ceil(max_w_half / 2)) + 2 * pad_px, 2 * int(np.ceil(max_h_half / 2)) + 2 * pad_px
+
+
+def fade_for_canvas(content_margin: int, requested: int) -> int:
+    """Never fade into visible content — cap fade by smallest margin."""
+    if content_margin <= 0:
+        return 0
+    return min(requested, max(0, content_margin - 8))
+
+
+def min_content_margin(mask: np.ndarray) -> int:
+    h, w = mask.shape
+    ys, xs = np.where(mask)
+    if len(xs) == 0:
+        return min(w, h) // 2
+    return int(min(xs.min(), ys.min(), w - 1 - xs.max(), h - 1 - ys.max()))
+
+
+def largest_component_bbox(mask: np.ndarray) -> tuple[int, int, int, int] | None:
+    h, w = mask.shape
+    visited = np.zeros((h, w), dtype=bool)
+    best_area = 0
+    best_bbox = None
+
+    for y0 in range(h):
+        for x0 in range(w):
+            if not mask[y0, x0] or visited[y0, x0]:
+                continue
+            stack = [(x0, y0)]
+            visited[y0, x0] = True
+            min_x = max_x = x0
+            min_y = max_y = y0
+            area = 0
+            while stack:
+                x, y = stack.pop()
+                area += 1
+                min_x = min(min_x, x)
+                max_x = max(max_x, x)
+                min_y = min(min_y, y)
+                max_y = max(max_y, y)
+                for nx, ny in ((x + 1, y), (x - 1, y), (x, y + 1), (x, y - 1)):
+                    if 0 <= nx < w and 0 <= ny < h and mask[ny, nx] and not visited[ny, nx]:
+                        visited[ny, nx] = True
+                        stack.append((nx, ny))
+            if area > best_area:
+                best_area = area
+                best_bbox = (min_x, min_y, max_x + 1, max_y + 1)
+    return best_bbox
+
+
+def centroid_in_bbox(mask: np.ndarray, bbox: tuple[int, int, int, int]) -> tuple[float, float]:
+    x0, y0, x1, y1 = bbox
+    ys, xs = np.where(mask[y0:y1, x0:x1])
+    if len(xs) == 0:
+        return (x0 + x1) / 2, (y0 + y1) / 2
+    return x0 + xs.mean(), y0 + ys.mean()
+
+
+def flatten_near_black(img: Image.Image, threshold: int = 40) -> Image.Image:
+    arr = np.array(img.convert("RGBA"))
+    rgb_max = arr[:, :, :3].max(axis=2)
+    keep = rgb_max > threshold
+    arr[~keep, :3] = 0
+    arr[~keep, 3] = 255
+    return Image.fromarray(arr)
+
+
+def apply_edge_fade(img: Image.Image, fade_px: int) -> Image.Image:
+    arr = np.array(img.convert("RGBA"))
+    h, w = arr.shape[:2]
+    fade_px = min(fade_px, w // 2, h // 2)
+    if fade_px <= 0:
+        return img
+    mask = np.ones((h, w), dtype=np.float32)
+    for x in range(fade_px):
+        alpha = x / fade_px
+        mask[:, x] = np.minimum(mask[:, x], alpha)
+        mask[:, w - 1 - x] = np.minimum(mask[:, w - 1 - x], alpha)
+    for y in range(fade_px):
+        alpha = y / fade_px
+        mask[y, :] = np.minimum(mask[y, :], alpha)
+        mask[h - 1 - y, :] = np.minimum(mask[h - 1 - y, :], alpha)
+    old_alpha = arr[:, :, 3].astype(np.float32) / 255.0
+    arr[:, :, 3] = (old_alpha * mask * 255).astype(np.uint8)
+    for c in range(3):
+        arr[:, :, c] = (arr[:, :, c].astype(np.float32) * mask).astype(np.uint8)
+    return Image.fromarray(arr)
+
+
+def isolate_subject(
+    frame: Image.Image, pad: int = 4, lum_threshold: int = 32
+) -> Isolated | None:
+    arr = np.array(frame.convert("RGBA"))
+    arr = np.array(flatten_near_black(Image.fromarray(arr), threshold=lum_threshold))
+    mask = luminance_mask(arr, lum_threshold)
+    if not mask.any():
+        return None
+    bbox = largest_component_bbox(mask)
+    if bbox is None:
+        return None
+    x0, y0, x1, y1 = bbox
+    x0 = max(0, x0 - pad)
+    y0 = max(0, y0 - pad)
+    x1 = min(arr.shape[1], x1 + pad)
+    y1 = min(arr.shape[0], y1 + pad)
+    cropped = Image.fromarray(arr).crop((x0, y0, x1, y1))
+    cx, cy = centroid_in_bbox(mask, (x0, y0, x1, y1))
+    return cropped, (cx - x0, cy - y0), (x1 - x0, y1 - y0)
+
+
+def scale_image(img: Image.Image, scale: float) -> Image.Image:
+    if abs(scale - 1.0) < 1e-6:
+        return img
+    w, h = img.size
+    nw = max(1, round(w * scale))
+    nh = max(1, round(h * scale))
+    return img.resize((nw, nh), Image.Resampling.LANCZOS)
+
+
+def repack_subject(
+    subject: Image.Image,
+    subject_centroid: tuple[float, float],
+    out_w: int,
+    out_h: int,
+    anchor: tuple[float, float],
+    scale: float = 1.0,
+) -> Image.Image:
+    scaled = scale_image(subject, scale)
+    scx, scy = subject_centroid[0] * scale, subject_centroid[1] * scale
+    out = Image.new("RGBA", (out_w, out_h), (0, 0, 0, 255))
+    paste_x = int(round(anchor[0] - scx))
+    paste_y = int(round(anchor[1] - scy))
+    out.alpha_composite(scaled, (paste_x, paste_y))
+    return out
+
+
+def slice_sheet(raw: Path, cols: int, rows: int) -> list[Image.Image]:
+    img = Image.open(raw).convert("RGBA")
+    w, h = img.size
+    fw, fh = w // cols, h // rows
+    frames = []
+    for row in range(rows):
+        for col in range(cols):
+            left, upper = col * fw, row * fh
+            frames.append(img.crop((left, upper, left + fw, upper + fh)))
+    return frames
+
+
+def find_peak_index(
+    isolated_list: list[Isolated | None],
+    peak_index: int | None = None,
+) -> int:
+    if peak_index is not None:
+        if peak_index < 0 or peak_index >= len(isolated_list):
+            raise ValueError(f"peak-index {peak_index} out of range")
+        if isolated_list[peak_index] is None:
+            raise ValueError(f"peak-index {peak_index} has no content")
+        return peak_index
+
+    best_i = 0
+    best_area = 0
+    for i, iso in enumerate(isolated_list):
+        if iso is None:
+            continue
+        _, _, (w, h) = iso
+        area = w * h
+        if area > best_area:
+            best_area = area
+            best_i = i
+    if best_area == 0:
+        raise ValueError("no frame content found")
+    return best_i
+
+
+def canvas_from_peak(
+    peak_wh: tuple[int, int],
+    pad_ratio: float = 0.12,
+    min_pad: int = 40,
+    square: bool = True,
+) -> tuple[int, int, int]:
+    """Return (out_w, out_h, pad_px) derived from peak frame bbox."""
+    pw, ph = peak_wh
+    pad = max(min_pad, round(max(pw, ph) * pad_ratio))
+    if square:
+        side = max(pw, ph) + 2 * pad
+        return side, side, pad
+    return pw + 2 * pad, ph + 2 * pad, pad
+
+
+def scale_to_fit_canvas(
+    peak_wh: tuple[int, int],
+    canvas_wh: tuple[int, int],
+    pad_px: int,
+) -> float:
+    """Only scale DOWN if peak content + pad exceeds canvas (shouldn't if derived)."""
+    pw, ph = peak_wh
+    cw, ch = canvas_wh
+    inner_w = cw - 2 * pad_px
+    inner_h = ch - 2 * pad_px
+    if pw <= inner_w and ph <= inner_h:
+        return 1.0
+    return min(inner_w / pw, inner_h / ph, 1.0)
+
+
+def apply_max_size_cap(
+    canvas_wh: tuple[int, int],
+    unified_scale: float,
+    max_size: int | None,
+) -> tuple[tuple[int, int], float]:
+    if not max_size:
+        return canvas_wh, unified_scale
+    cw, ch = canvas_wh
+    side = max(cw, ch)
+    if side <= max_size:
+        return canvas_wh, unified_scale
+    cap_scale = max_size / side
+    new_cw = max(1, round(cw * cap_scale))
+    new_ch = max(1, round(ch * cap_scale))
+    return (new_cw, new_ch), unified_scale * cap_scale
+
+
+def edge_touch_px(mask: np.ndarray, margin: int = 8) -> dict[str, int]:
+    h, w = mask.shape
+    return {
+        "left": int(mask[:, :margin].any()),
+        "right": int(mask[:, w - margin :].any()),
+        "top": int(mask[:margin, :].any()),
+        "bottom": int(mask[h - margin :, :].any()),
+    }
+
+
+def process_sequence(
+    raw_path: Path,
+    out_dir: Path,
+    name: str,
+    cols: int,
+    rows: int,
+    fade_px: int = 24,
+    lum_threshold: int = 32,
+    peak_index: int | None = None,
+    pad_ratio: float = 0.12,
+    min_pad: int = 48,
+    cell_margin: int = 48,
+    square: bool = True,
+    max_size: int | None = None,
+) -> dict:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    slices = slice_sheet(raw_path, cols, rows)
+
+    normalized = [
+        normalize_cell(slc, cell_margin=cell_margin, lum_threshold=lum_threshold)
+        for slc in slices
+    ]
+
+    isolated_list: list[Isolated | None] = []
+    for cell in normalized:
+        isolated_list.append(isolate_subject(cell, lum_threshold=lum_threshold))
+
+    peak_i = find_peak_index(isolated_list, peak_index)
+    _, _, peak_wh = isolated_list[peak_i]  # type: ignore[misc]
+
+    pad_px = max(min_pad, round(max(peak_wh) * pad_ratio))
+    out_w, out_h = canvas_from_union(isolated_list, pad_px, square)
+
+    unified_scale = 1.0
+    (out_w, out_h), unified_scale = apply_max_size_cap(
+        (out_w, out_h), unified_scale, max_size
+    )
+
+    anchor = (out_w / 2, out_h / 2)
+    print(
+        f"  peak=frame{peak_i:02d} peak_bbox={peak_wh[0]}x{peak_wh[1]} "
+        f"union_canvas={out_w}x{out_h} pad={pad_px}px scale={unified_scale:.3f} "
+        f"(cell_margin={cell_margin})"
+    )
+
+    report = {
+        "name": name,
+        "peak_frame": peak_i,
+        "peak_frame_key": f"{name}_frame{peak_i:02d}",
+        "peak_bbox": list(peak_wh),
+        "frameCanvas": [out_w, out_h],
+        "anchor": list(anchor),
+        "canvas": [out_w, out_h],
+        "pad_px": pad_px,
+        "unified_scale": round(unified_scale, 4),
+        "frames": [],
+    }
+
+    for i, isolated in enumerate(isolated_list):
+        if isolated is None:
+            repacked = Image.new("RGBA", (out_w, out_h), (0, 0, 0, 255))
+            cx, cy = anchor
+            left_mass = right_mass = 0
+            touch = {"left": 0, "right": 0, "top": 0, "bottom": 0}
+        else:
+            subject, sub_centroid, _wh = isolated
+            repacked = repack_subject(
+                subject, sub_centroid, out_w, out_h, anchor, unified_scale
+            )
+            arr = np.array(repacked)
+            mask = luminance_mask(arr, lum_threshold)
+            ys, xs = np.where(mask)
+            cx, cy = (xs.mean(), ys.mean()) if len(xs) else anchor
+            mid = out_w // 2
+            left_mass = int(mask[:, :mid].sum())
+            right_mass = int(mask[:, mid:].sum())
+            touch = edge_touch_px(mask, margin=10)
+
+        repacked = flatten_near_black(repacked, threshold=lum_threshold)
+        arr = np.array(repacked)
+        mask = luminance_mask(arr, lum_threshold)
+        margin = min_content_margin(mask)
+        eff_fade = fade_for_canvas(margin, fade_px)
+        if eff_fade > 0:
+            repacked = apply_edge_fade(repacked, eff_fade)
+
+        out_path = out_dir / f"{name}_frame{i:02d}.png"
+        repacked.save(out_path)
+
+        drift = ((cx - anchor[0]) ** 2 + (cy - anchor[1]) ** 2) ** 0.5
+        lr_ratio = left_mass / max(right_mass, 1)
+        frame_info = {
+            "index": i,
+            "path": str(out_path.relative_to(ROOT)),
+            "centroid": [round(cx, 1), round(cy, 1)],
+            "drift_px": round(drift, 1),
+            "left_right_ratio": round(lr_ratio, 2),
+            "edge_touch": touch,
+            "is_peak": i == peak_i,
+        }
+        report["frames"].append(frame_info)
+        touch_s = "+".join(k for k, v in touch.items() if v) or "none"
+        peak_mark = " *PEAK*" if i == peak_i else ""
+        print(
+            f"  frame{i:02d}: drift={drift:.1f}px lr={lr_ratio:.2f} touch={touch_s}{peak_mark} "
+            f"-> {out_path.name}"
+        )
+
+    return report
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Repack FX frames — canvas sized from peak (largest) frame"
+    )
+    parser.add_argument("--raw", required=True)
+    parser.add_argument("--name", required=True)
+    parser.add_argument("--cols", type=int, default=6)
+    parser.add_argument("--rows", type=int, default=1)
+    parser.add_argument("--out-dir", default="assets/images/fx")
+    parser.add_argument("--peak-index", type=int, default=None, help="Override auto peak detection")
+    parser.add_argument("--pad-ratio", type=float, default=0.12, help="Padding around peak bbox")
+    parser.add_argument("--min-pad", type=int, default=48)
+    parser.add_argument("--cell-margin", type=int, default=48, help="Safe zone inside each slice cell")
+    parser.add_argument("--no-square", action="store_true", help="Use peak bbox aspect, not square")
+    parser.add_argument("--max-size", type=int, default=1024, help="Cap max canvas side (0=disable)")
+    parser.add_argument("--fade-px", type=int, default=24)
+    parser.add_argument("--lum-threshold", type=int, default=32)
+    parser.add_argument("--report", default="")
+    parser.add_argument("--project-root", type=Path, default=Path.cwd(), help="Playable project root")
+    args = parser.parse_args()
+
+    root = args.project_root.resolve()
+    global ROOT
+    ROOT = root
+
+    raw_path = Path(args.raw)
+    if not raw_path.is_absolute():
+        raw_path = root / raw_path
+    if not raw_path.exists():
+        print(f"ERROR: raw not found: {raw_path}", file=sys.stderr)
+        sys.exit(1)
+
+    out_dir = Path(args.out_dir)
+    if not out_dir.is_absolute():
+        out_dir = root / out_dir
+
+    max_size = args.max_size if args.max_size > 0 else None
+
+    print(f"[repack] {raw_path.name} -> {args.name} ({args.cols}x{args.rows}) peak-driven canvas")
+    report = process_sequence(
+        raw_path, out_dir, args.name,
+        args.cols, args.rows,
+        fade_px=args.fade_px,
+        lum_threshold=args.lum_threshold,
+        peak_index=args.peak_index,
+        pad_ratio=args.pad_ratio,
+        min_pad=args.min_pad,
+        cell_margin=args.cell_margin,
+        square=not args.no_square,
+        max_size=max_size,
+    )
+
+    max_drift = max(f["drift_px"] for f in report["frames"])
+    max_lr = max(max(f["left_right_ratio"], 1 / max(f["left_right_ratio"], 0.01)) for f in report["frames"])
+    any_touch = any(any(f["edge_touch"].values()) for f in report["frames"])
+    report["summary"] = {
+        "max_drift_px": max_drift,
+        "max_lr_imbalance": round(max_lr, 2),
+        "edge_touch": any_touch,
+    }
+    print(f"[repack] max drift={max_drift}px max L/R={max_lr:.2f} edge_touch={any_touch}")
+
+    if args.report:
+        rp = Path(args.report)
+        if not rp.is_absolute():
+            rp = root / rp
+        rp.parent.mkdir(parents=True, exist_ok=True)
+        rp.write_text(json.dumps(report, indent=2), encoding="utf-8")
+        print(f"[repack] report -> {rp.relative_to(root)}")
+
+    if max_drift > 15 or max_lr > 1.8 or any_touch:
+        print("[repack] FAIL: alignment, dual-subject, or edge clip detected", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/project-templates/phaser/skills/playable-fx-peak/scripts/validate-frame-anchors.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Validate frame animation anchor alignment and dual-subject detection."""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+ROOT = Path.cwd()
+
+
+def analyze_frame(path: Path, lum_threshold: int = 32, edge_margin: int = 10) -> dict:
+    arr = np.array(Image.open(path).convert("RGBA"))
+    h, w = arr.shape[:2]
+    rgb = arr[:, :, :3].astype(np.float32)
+    lum = rgb.max(axis=2)
+    mask = lum > lum_threshold
+    grey = int(((lum > 8) & (lum <= lum_threshold)).sum())
+    if not mask.any():
+        return {"file": path.name, "empty": True}
+
+    ys, xs = np.where(mask)
+    cx, cy = float(xs.mean()), float(ys.mean())
+    mid = w // 2
+    left = int(mask[:, :mid].sum())
+    right = int(mask[:, mid:].sum())
+    lr = left / max(right, 1)
+    drift = ((cx - w / 2) ** 2 + (cy - h / 2) ** 2) ** 0.5
+    touch = {
+        "left": bool(mask[:, :edge_margin].any()),
+        "right": bool(mask[:, w - edge_margin :].any()),
+        "top": bool(mask[:edge_margin, :].any()),
+        "bottom": bool(mask[h - edge_margin :, :].any()),
+    }
+    return {
+        "file": path.name,
+        "size": [w, h],
+        "centroid": [round(cx, 1), round(cy, 1)],
+        "drift_px": round(drift, 1),
+        "left_px": left,
+        "right_px": right,
+        "lr_ratio": round(lr, 2),
+        "grey_px": grey,
+        "edge_touch": touch,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("pattern", help="Glob for frame PNGs, e.g. assets/images/fx/match_burst_v2_frame*.png")
+    parser.add_argument("--max-drift", type=float, default=12.0)
+    parser.add_argument("--max-lr", type=float, default=1.6)
+    parser.add_argument("--json", default="")
+    parser.add_argument("--project-root", type=Path, default=Path.cwd(), help="Playable project root")
+    args = parser.parse_args()
+
+    global ROOT
+    ROOT = args.project_root.resolve()
+
+    pattern = args.pattern
+    if not Path(pattern).is_absolute():
+        pattern = str(ROOT / pattern)
+
+    files = sorted(glob.glob(pattern))
+    if not files:
+        print(f"ERROR: no files for {pattern}", file=sys.stderr)
+        sys.exit(1)
+
+    results = [analyze_frame(Path(f)) for f in files]
+    fails = []
+    for r in results:
+        if r.get("empty"):
+            fails.append(f"{r['file']}: empty frame")
+            continue
+        if r["drift_px"] > args.max_drift:
+            fails.append(f"{r['file']}: drift {r['drift_px']}px > {args.max_drift}")
+        lr = r["lr_ratio"]
+        if lr > args.max_lr or lr < 1 / args.max_lr:
+            fails.append(f"{r['file']}: L/R imbalance {lr} (dual-subject?)")
+        touch = r.get("edge_touch", {})
+        touched = [k for k, v in touch.items() if v]
+        if touched:
+            fails.append(f"{r['file']}: content touches edge ({', '.join(touched)})")
+        if r.get("grey_px", 0) > 500:
+            fails.append(f"{r['file']}: grey vignette {r['grey_px']}px > 500")
+
+    print(f"=== validate-frame-anchors ({len(results)} frames) ===")
+    for r in results:
+        if r.get("empty"):
+            print(f"  {r['file']}: EMPTY")
+        else:
+            touch = r.get("edge_touch", {})
+            touch_s = "+".join(k for k, v in touch.items() if v) or "ok"
+            print(
+                f"  {r['file']}: centroid=({r['centroid'][0]},{r['centroid'][1]}) "
+                f"drift={r['drift_px']}px lr={r['lr_ratio']} edge={touch_s} grey={r.get('grey_px', 0)}"
+            )
+
+    summary = {
+        "frames": results,
+        "pass": len(fails) == 0,
+        "failures": fails,
+        "thresholds": {"max_drift": args.max_drift, "max_lr": args.max_lr},
+    }
+
+    if args.json:
+        jp = Path(args.json)
+        if not jp.is_absolute():
+            jp = ROOT / jp
+        jp.parent.mkdir(parents=True, exist_ok=True)
+        jp.write_text(json.dumps(summary, indent=2), encoding="utf-8")
+
+    if fails:
+        print("\nFAIL:")
+        for f in fails:
+            print(f"  - {f}")
+        sys.exit(1)
+
+    print("\nPASS: all frames anchor-aligned")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()