@playcraft/cli 0.0.44 → 0.0.46

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadProfile, globFiles } = require('./lib/node_utils');
+
+function parseArgs() {
+  const args = { profile: path.resolve('playable.ui.profile.yaml') };
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === '--profile' && process.argv[i + 1]) {
+      args.profile = path.resolve(process.argv[++i]);
+    }
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs();
+  const profilePath = args.profile;
+  const projectRoot = path.dirname(profilePath);
+  const profile = loadProfile(profilePath);
+  const patterns = profile.antipatterns || [];
+  const findings = [];
+  const add = (check, status, message, details = {}) => findings.push({ check, status, message, details });
+
+  const hits = [];
+
+  for (const pattern of patterns) {
+    const re = new RegExp(pattern.grep, 'm');
+    const exclude = new Set((pattern.exclude || []).map((p) => p.replace(/\\/g, '/')));
+    for (const globPattern of pattern.paths || []) {
+      const files = globFiles(projectRoot, globPattern);
+      for (const file of files) {
+        const rel = path.relative(projectRoot, file).split(path.sep).join('/');
+        if ([...exclude].some((ex) => rel === ex || rel.endsWith(ex))) continue;
+        const text = fs.readFileSync(file, 'utf8');
+        const lines = text.split('\n');
+        lines.forEach((line, idx) => {
+          if (re.test(line)) {
+            hits.push({ id: pattern.id, file: rel, line: idx + 1, severity: pattern.severity || 'warn' });
+          }
+        });
+      }
+    }
+  }
+
+  const fails = hits.filter((h) => h.severity === 'fail');
+  const warns = hits.filter((h) => h.severity !== 'fail');
+
+  if (fails.length) {
+    add('verify_hardcoded_layout', 'fail', `${fails.length} hardcoded layout antipattern(s)`, { hits: fails.slice(0, 20) });
+  } else if (warns.length) {
+    add('verify_hardcoded_layout', 'warn', `${warns.length} layout antipattern warning(s)`, { hits: warns.slice(0, 20) });
+  } else {
+    add('verify_hardcoded_layout', 'pass', 'No layout antipatterns detected');
+  }
+
+  const worst = findings.some((f) => f.status === 'fail') ? 'fail' : findings.some((f) => f.status === 'warn') ? 'warn' : 'pass';
+  console.log(JSON.stringify({ worst, findings }));
+  process.exit(worst === 'fail' ? 1 : 0);
+}
+
+main();

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

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { loadGameConfig, regionBounds, evaluate } = require('./lib/config_expr');
+const { loadProfile } = require('./lib/node_utils');
+
+function parseArgs() {
+  const args = { profile: path.resolve('playable.ui.profile.yaml') };
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === '--profile' && process.argv[i + 1]) {
+      args.profile = path.resolve(process.argv[++i]);
+    }
+  }
+  return args;
+}
+
+function boundsFor(name, regions, gameConfig, profile) {
+  const def = regions[name];
+  if (!def) throw new Error(`Unknown region: ${name}`);
+  return regionBounds(def, gameConfig, profile);
+}
+
+function checkRule(rule, regions, gameConfig, profile) {
+  switch (rule.type) {
+    case 'min_gap': {
+      const a = boundsFor(rule.a, regions, gameConfig, profile);
+      const b = boundsFor(rule.b, regions, gameConfig, profile);
+      const gap = b.y0 - a.y1;
+      if (gap < rule.min) {
+        return `min_gap ${rule.a}->${rule.b}: gap ${gap.toFixed(1)} < ${rule.min}`;
+      }
+      return null;
+    }
+    case 'inside_band': {
+      const region = boundsFor(rule.region, regions, gameConfig, profile);
+      const band = boundsFor(rule.band, regions, gameConfig, profile);
+      if (region.y0 < band.y0 || region.y1 > band.y1) {
+        return `inside_band ${rule.region} not inside ${rule.band}`;
+      }
+      return null;
+    }
+    case 'safe_top': {
+      const region = boundsFor(rule.region, regions, gameConfig, profile);
+      const min = evaluate(rule.min, gameConfig, profile);
+      if (region.y0 < min) {
+        return `safe_top ${rule.region}: y0 ${region.y0.toFixed(1)} < ${min}`;
+      }
+      return null;
+    }
+    case 'safe_bottom': {
+      const sbRegion = boundsFor(rule.region, regions, gameConfig, profile);
+      const sbMin = evaluate(rule.min, gameConfig, profile);
+      const height = gameConfig.DESIGN_HEIGHT || (profile.meta && profile.meta.design && profile.meta.design.height);
+      if (typeof height !== 'number') {
+        return `safe_bottom ${rule.region}: DESIGN_HEIGHT or meta.design.height required`;
+      }
+      const limit = height - sbMin;
+      if (sbRegion.y1 > limit) {
+        return `safe_bottom ${rule.region}: y1 ${sbRegion.y1.toFixed(1)} > ${limit}`;
+      }
+      return null;
+    }
+    case 'ordered': {
+      const first = boundsFor(rule.first, regions, gameConfig, profile);
+      const second = boundsFor(rule.second, regions, gameConfig, profile);
+      if (first.y1 > second.y0) {
+        return `ordered ${rule.first} before ${rule.second}: overlap or wrong order`;
+      }
+      return null;
+    }
+    default:
+      return `Unknown rule type: ${rule.type}`;
+  }
+}
+
+function main() {
+  const args = parseArgs();
+  const profile = loadProfile(args.profile);
+  const projectRoot = path.dirname(args.profile);
+  const configPath = path.resolve(projectRoot, profile.paths.gameConfig);
+  const findings = [];
+  const add = (check, status, message, details = {}) => findings.push({ check, status, message, details });
+
+  try {
+    const cfg = loadGameConfig(configPath);
+    const regions = profile.layout.regions || {};
+    const rules = profile.layout.rules || [];
+    const violations = [];
+
+    for (const rule of rules) {
+      const msg = checkRule(rule, regions, cfg, profile);
+      if (msg) violations.push(msg);
+    }
+
+    if (violations.length) {
+      add('verify_layout_regions', 'fail', `${violations.length} layout rule violation(s)`, { violations });
+    } else {
+      add('verify_layout_regions', 'pass', `${rules.length} layout rule(s) passed`);
+    }
+  } catch (err) {
+    add('verify_layout_regions', 'fail', err.message);
+  }
+
+  const worst = findings.some((f) => f.status === 'fail') ? 'fail' : 'pass';
+  console.log(JSON.stringify({ worst, findings }));
+  process.exit(worst === 'fail' ? 1 : 0);
+}
+
+main();

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

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Validate profile against JSON Schema."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.profile_loader import load_profile, validate_profile  # noqa: E402
+from lib.report import Report, exit_with_report  # noqa: E402
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Verify playable UI profile schema")
+    parser.add_argument("--profile", type=Path, default=Path("playable.ui.profile.yaml"))
+    parser.add_argument("--json", action="store_true", help="Emit JSON to stdout")
+    args = parser.parse_args()
+
+    report = Report()
+    profile_path = args.profile.resolve()
+
+    try:
+        profile = load_profile(profile_path, validate=True)
+        name = profile.get("meta", {}).get("name", profile_path.name)
+        report.pass_("verify_profile_schema", f"Profile '{name}' is valid")
+    except Exception as exc:
+        report.fail("verify_profile_schema", str(exc))
+
+    exit_with_report(report, json_stdout=args.json)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+Ring 1 reference-free visual sanity check on autoplay video frames.
+
+Conservative heuristics only — catches blank screens, full-screen single-color
+overlays, and collapsed content (not semantic gameplay quality).
+
+Usage:
+  python3 skills/playable-verify-ui/scripts/verify_ring1_visual.py --root . --frames validate/ring1/frames
+
+Exit 0 = pass
+Exit 2 = fail
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+MAX_SINGLE_COLOR_FRACTION = 0.98
+MIN_UNIQUE_COLORS = 2
+MIN_CONTENT_CELLS_GAMEPLAY = 2
+MIN_EDGE_DENSITY_GAMEPLAY = 0.002
+MIN_FRAME_DELTA = 2.5
+GRID_ROWS = 6
+GRID_COLS = 10
+CELL_VARIANCE_THRESHOLD = 120.0
+EDGE_DIFF_THRESHOLD = 18
+
+
+def load_pil():
+    try:
+        from PIL import Image  # noqa: PLC0415
+
+        return Image
+    except ImportError:
+        return None
+
+
+def analyze_frame(image_mod: Any, path: Path) -> dict[str, Any]:
+    img = image_mod.open(path).convert("RGB")
+    w, h = img.size
+    pixels = list(img.getdata())
+    total = len(pixels) or 1
+
+    counts: dict[tuple[int, int, int], int] = {}
+    for rgb in pixels:
+        # Quantize to reduce noise from compression
+        key = (rgb[0] // 16, rgb[1] // 16, rgb[2] // 16)
+        counts[key] = counts.get(key, 0) + 1
+
+    max_count = max(counts.values()) if counts else total
+    max_single_color_fraction = max_count / total
+    unique_colors = len(counts)
+
+    cell_w = max(1, w // GRID_COLS)
+    cell_h = max(1, h // GRID_ROWS)
+    content_cells = 0
+    for row in range(GRID_ROWS):
+        for col in range(GRID_COLS):
+            x0 = col * cell_w
+            y0 = row * cell_h
+            x1 = min(w, x0 + cell_w)
+            y1 = min(h, y0 + cell_h)
+            region = img.crop((x0, y0, x1, y1)).convert("L")
+            data = list(region.getdata())
+            if not data:
+                continue
+            mean = sum(data) / len(data)
+            variance = sum((v - mean) ** 2 for v in data) / len(data)
+            if variance >= CELL_VARIANCE_THRESHOLD:
+                content_cells += 1
+
+    edge_w = 96
+    edge_h = max(1, int(edge_w * h / max(1, w)))
+    edge_img = img.convert("L").resize((edge_w, edge_h))
+    edge_pixels = list(edge_img.getdata())
+    edge_hits = 0
+    edge_total = 0
+    for y in range(edge_h):
+        for x in range(edge_w):
+            idx = y * edge_w + x
+            current = edge_pixels[idx]
+            if x + 1 < edge_w:
+                edge_total += 1
+                if abs(current - edge_pixels[idx + 1]) >= EDGE_DIFF_THRESHOLD:
+                    edge_hits += 1
+            if y + 1 < edge_h:
+                edge_total += 1
+                if abs(current - edge_pixels[idx + edge_w]) >= EDGE_DIFF_THRESHOLD:
+                    edge_hits += 1
+    edge_density = edge_hits / max(1, edge_total)
+
+    return {
+        "path": str(path),
+        "width": w,
+        "height": h,
+        "maxSingleColorFraction": round(max_single_color_fraction, 4),
+        "uniqueColors": unique_colors,
+        "contentCells": content_cells,
+        "edgeDensity": round(edge_density, 5),
+    }
+
+
+def evaluate_frame(metrics: dict[str, Any], role: str, check_edge_density: bool) -> list[str]:
+    failures: list[str] = []
+    name = Path(metrics["path"]).name
+    if metrics["maxSingleColorFraction"] >= MAX_SINGLE_COLOR_FRACTION:
+        failures.append(f"{name}: nearly blank (single color covers {metrics['maxSingleColorFraction']:.0%})")
+    if metrics["uniqueColors"] < MIN_UNIQUE_COLORS:
+        failures.append(f"{name}: too few distinct colors ({metrics['uniqueColors']} < {MIN_UNIQUE_COLORS})")
+    if role == "gameplay" and metrics["contentCells"] < MIN_CONTENT_CELLS_GAMEPLAY:
+        failures.append(
+            f"{name}: gameplay frame content collapsed ({metrics['contentCells']} active cells < {MIN_CONTENT_CELLS_GAMEPLAY})"
+        )
+    if check_edge_density and role == "gameplay" and metrics["edgeDensity"] < MIN_EDGE_DENSITY_GAMEPLAY:
+        failures.append(
+            f"{name}: gameplay frame edge density too low ({metrics['edgeDensity']:.4f} < {MIN_EDGE_DENSITY_GAMEPLAY})"
+        )
+    return failures
+
+
+def frame_delta(image_mod: Any, a: Path, b: Path) -> float:
+    img_a = image_mod.open(a).convert("RGB").resize((96, 54))
+    img_b = image_mod.open(b).convert("RGB").resize((96, 54))
+    data_a = list(img_a.getdata())
+    data_b = list(img_b.getdata())
+    total = 0.0
+    for pa, pb in zip(data_a, data_b):
+        total += (abs(pa[0] - pb[0]) + abs(pa[1] - pb[1]) + abs(pa[2] - pb[2])) / 3
+    return round(total / max(1, len(data_a)), 4)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", default=".", help="Project root")
+    parser.add_argument(
+        "--frames",
+        default="validate/ring1/frames",
+        help="Directory containing 01.png, 02.png, 03.png",
+    )
+    parser.add_argument("--out", default="validate/ring1/visual.json", help="JSON report output path")
+    parser.add_argument("--check-motion", action="store_true", help="Fail when sampled frames barely change")
+    parser.add_argument("--check-edge-density", action="store_true", help="Fail low-edge gameplay frames")
+    parser.add_argument("--json", action="store_true", help="Print JSON to stdout")
+    args = parser.parse_args()
+
+    image_mod = load_pil()
+    if image_mod is None:
+        print("[verify:visual-ring1] Pillow required — pip install Pillow", file=sys.stderr)
+        return 1
+
+    root = Path(args.root).resolve()
+    frames_dir = (root / args.frames).resolve()
+    frame_specs = [
+        ("01.png", "hook"),
+        ("02.png", "gameplay"),
+        ("03.png", "endcard"),
+    ]
+
+    missing = [name for name, _ in frame_specs if not (frames_dir / name).exists()]
+    if missing:
+        msg = f"Missing frame(s) in {frames_dir}: {', '.join(missing)}"
+        print(f"[verify:visual-ring1] FAIL — {msg}", file=sys.stderr)
+        report = {"ok": False, "failures": [msg], "frames": []}
+        out_path = root / args.out
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+        if args.json:
+            print(json.dumps(report, indent=2))
+        return 2
+
+    frames: list[dict[str, Any]] = []
+    failures: list[str] = []
+    for filename, role in frame_specs:
+        metrics = analyze_frame(image_mod, frames_dir / filename)
+        metrics["role"] = role
+        frame_failures = evaluate_frame(metrics, role, args.check_edge_density)
+        metrics["ok"] = len(frame_failures) == 0
+        if frame_failures:
+            failures.extend(frame_failures)
+        frames.append(metrics)
+
+    frame_deltas: list[float] = []
+    if args.check_motion:
+        for idx in range(len(frame_specs) - 1):
+            frame_deltas.append(frame_delta(image_mod, frames_dir / frame_specs[idx][0], frames_dir / frame_specs[idx + 1][0]))
+        if frame_deltas and max(frame_deltas) < MIN_FRAME_DELTA:
+            failures.append(f"sampled frames show too little change (max delta {max(frame_deltas):.2f} < {MIN_FRAME_DELTA})")
+
+    ok = len(failures) == 0
+    report = {"ok": ok, "frames": frames, "frameDeltas": frame_deltas, "failures": failures}
+    out_path = root / args.out
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        status = "OK" if ok else "FAIL"
+        print(f"[verify:visual-ring1] CV {status} — {len(frames)} frame(s) analyzed")
+        for f in failures:
+            print(f"  ✗ {f}")
+
+    return 0 if ok else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Static check: does game/ still satisfy the recording/debug harness contract?
+ *
+ * Runs offline (no browser, no dev server) so it can gate STOP and run inside
+ * verify:ui. The live counterpart is exercised by harness:smoke.
+ */
+
+const path = require('path');
+const { scanRuntimeContract } = require('./lib/runtime_contract');
+
+function parseArgs() {
+  const args = { root: null, profile: null };
+  for (let i = 2; i < process.argv.length; i++) {
+    const arg = process.argv[i];
+    if (arg === '--profile' && process.argv[i + 1]) {
+      args.profile = path.resolve(process.argv[++i]);
+    } else if (arg === '--root' && process.argv[i + 1]) {
+      args.root = path.resolve(process.argv[++i]);
+    } else if (arg.startsWith('--root=')) {
+      args.root = path.resolve(arg.slice('--root='.length));
+    }
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs();
+  const projectRoot =
+    args.root || (args.profile ? path.dirname(args.profile) : process.cwd());
+
+  const findings = [];
+  const res = scanRuntimeContract(projectRoot);
+
+  if (res.ok) {
+    findings.push({
+      check: 'verify_runtime_contract',
+      status: 'pass',
+      message: `harness contract satisfied (${res.filesScanned} game file(s) scanned)`,
+      details: {},
+    });
+  } else {
+    findings.push({
+      check: 'verify_runtime_contract',
+      status: 'fail',
+      message: `${res.missing.length} runtime-contract symbol(s) missing — record/debug harness will break`,
+      details: { missing: res.missing },
+    });
+  }
+
+  const worst = findings.some((f) => f.status === 'fail') ? 'fail' : 'pass';
+  console.log(JSON.stringify({ worst, findings }));
+  process.exit(worst === 'fail' ? 1 : 0);
+}
+
+main();

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

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadProfile } = require('./lib/node_utils');
+
+function parseArgs() {
+  const args = { profile: path.resolve('playable.ui.profile.yaml') };
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === '--profile' && process.argv[i + 1]) {
+      args.profile = path.resolve(process.argv[++i]);
+    }
+  }
+  return args;
+}
+
+function extractScriptSrcs(html) {
+  const re = /<script[^>]+src=["']([^"']+)["']/gi;
+  const srcs = [];
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    srcs.push(m[1].replace(/^\.\//, ''));
+  }
+  return srcs;
+}
+
+function isSubsequence(needle, haystack) {
+  let i = 0;
+  for (const item of haystack) {
+    if (item.endsWith(needle[i]) || item.includes(needle[i])) {
+      i++;
+      if (i === needle.length) return true;
+    }
+  }
+  return false;
+}
+
+function main() {
+  const args = parseArgs();
+  const profilePath = args.profile;
+  const projectRoot = path.dirname(profilePath);
+  const profile = loadProfile(profilePath);
+  const indexPath = path.resolve(projectRoot, profile.paths.indexHtml);
+  const loadOrder = profile.scripts?.loadOrder || [];
+  const findings = [];
+  const add = (check, status, message, details = {}) => findings.push({ check, status, message, details });
+
+  try {
+    const html = fs.readFileSync(indexPath, 'utf8');
+    const srcs = extractScriptSrcs(html);
+    const normalized = srcs.map((s) => s.replace(/^game\//, '').replace(/^\.\//, ''));
+
+    if (!loadOrder.length) {
+      add('verify_script_load_order', 'pass', 'No loadOrder configured');
+    } else if (isSubsequence(loadOrder, normalized)) {
+      add('verify_script_load_order', 'pass', `Script load order contains required subsequence (${loadOrder.length} entries)`);
+    } else {
+      add('verify_script_load_order', 'fail', 'index.html script order missing required subsequence', {
+        expected: loadOrder,
+        actual: normalized,
+      });
+    }
+  } catch (err) {
+    add('verify_script_load_order', 'fail', err.message);
+  }
+
+  const worst = findings.some((f) => f.status === 'fail') ? 'fail' : 'pass';
+  console.log(JSON.stringify({ worst, findings }));
+  process.exit(worst === 'fail' ? 1 : 0);
+}
+
+main();