@playcraft/cli 0.1.54 → 0.1.55-beta

package/project-template-v2/skills/playable-verify-ui/scripts/lib/runtime_contract.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Static scan for the Playable ⇄ Harness runtime contract.
+ *
+ * The recording/debug harness (skills/playable-record, skills/playable-debug)
+ * drives every playable through fixed runtime hooks. If the game code drops one
+ * of them, `record:mp4` and one-click clear silently time out. This scanner lets
+ * `verify:ui` and the STOP hook fail fast and loudly instead.
+ *
+ * Keep these symbols in sync with:
+ *   - game/runtime-contract.ts
+ *   - skills/playable-record/scripts/record-playable.mjs
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const LEGACY_SCENE_SYMBOLS = [
+  { name: '_onDebugAutoPlay', why: 'recorder triggers one-click auto-play' },
+  { name: 'sceneManager', why: 'recorder reads scene phase state' },
+  { name: 'currentPhase', why: 'recorder waits for HOOK then ENDCARD' },
+  { name: 'isGameOver', why: 'recorder detects end of run' },
+  { name: 'ENDCARD', why: 'recorder waits for the ENDCARD phase' },
+];
+
+const NEUTRAL_PLAYABLE_SYMBOLS = [
+  { name: '__playable', why: 'engine-neutral recorder entry point' },
+  { name: 'autoPlay', why: 'recorder triggers one-click auto-play' },
+  { name: 'getState', why: 'recorder reads phase state' },
+  { name: 'currentPhase', why: 'recorder waits for HOOK then ENDCARD' },
+  { name: 'ENDCARD', why: 'recorder waits for the ENDCARD phase' },
+];
+
+// At least one of these must publish a recorder entry point.
+const ENTRY_SYMBOLS = ['window.__playable', '__playable =', 'publishPlayableRuntime', 'window.__game', 'registerPlayable', '__game ='];
+const REQUIRED_SYMBOLS = LEGACY_SCENE_SYMBOLS;
+
+/**
+ * Strip line + block comments so commented-out or documentation mentions of a
+ * symbol don't create false-negatives. Not a full parser, but removes the
+ * dominant source of substring false matches.
+ * @param {string} src
+ */
+function stripComments(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+/** Match a bare JS identifier with word boundaries (no dotted members). */
+function hasIdentifier(code, name) {
+  return new RegExp(`(?<![A-Za-z0-9_$])${name}(?![A-Za-z0-9_$])`).test(code);
+}
+
+function walkGameFiles(gameDir) {
+  const out = [];
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (/\.(ts|tsx|js|mjs|cjs)$/.test(entry.name)) {
+        out.push(full);
+      }
+    }
+  }
+  walk(gameDir);
+  return out;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ ok: boolean, missing: string[], filesScanned: number }}
+ */
+function scanRuntimeContract(projectRoot) {
+  const gameDir = path.join(projectRoot, 'game');
+  const files = walkGameFiles(gameDir);
+  if (files.length === 0) {
+    return { ok: false, missing: ['game/ contains no source files'], filesScanned: 0 };
+  }
+
+  const blob = stripComments(
+    files.map((f) => fs.readFileSync(f, 'utf8')).join('\n'),
+  );
+  const missing = [];
+
+  const missingNeutral = NEUTRAL_PLAYABLE_SYMBOLS
+    .filter((sym) => !hasIdentifier(blob, sym.name))
+    .map((sym) => `${sym.name} — ${sym.why}`);
+  const missingLegacy = LEGACY_SCENE_SYMBOLS
+    .filter((sym) => !hasIdentifier(blob, sym.name))
+    .map((sym) => `${sym.name} — ${sym.why}`);
+
+  // Entry symbols include dotted forms (window.__playable), so match as substrings
+  // after comment stripping.
+  if (!ENTRY_SYMBOLS.some((s) => blob.includes(s))) {
+    missing.push('window.__playable / publishPlayableRuntime — recorder entry point');
+  }
+  if (missingNeutral.length > 0 && missingLegacy.length > 0) {
+    missing.push(...missingNeutral.map((m) => `neutral contract: ${m}`));
+    if (!blob.includes('publishPlayableRuntime')) {
+      missing.push(...missingLegacy.map((m) => `legacy scene contract (deprecated): ${m}`));
+    }
+  } else if (missingNeutral.length > 0 && blob.includes('publishPlayableRuntime')) {
+    missing.push(...missingNeutral.map((m) => `neutral contract: ${m}`));
+  }
+  if (/\b(?:window\.__game|__game)\.start\s*=/.test(blob)) {
+    missing.push('window.__game.start must not be assigned; put harness methods on window.__playable');
+  }
+
+  return { ok: missing.length === 0, missing, filesScanned: files.length };
+}
+
+module.exports = { scanRuntimeContract, REQUIRED_SYMBOLS, ENTRY_SYMBOLS, NEUTRAL_PLAYABLE_SYMBOLS, LEGACY_SCENE_SYMBOLS };

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

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Warn when fetch/build scripts use placehold.co for UI/rewards assets."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from lib.profile_loader import get_paths, load_profile  # noqa: E402
+from lib.report import Report, exit_with_report  # noqa: E402
+
+PLACEHOLD_RE = re.compile(r"placehold\.co", re.IGNORECASE)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Detect placehold.co antipatterns")
+    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()
+
+    profile_path = args.profile.resolve()
+    profile = load_profile(profile_path, validate=False)
+    paths = get_paths(profile, profile_path)
+    report = Report()
+    hits: list[str] = []
+
+    candidates = [
+        paths.get("fetchAssetsScript"),
+        paths.get("buildAtlasScript"),
+        profile_path.parent / "scripts" / "generate-ui-placeholders.py",
+    ]
+
+    for path in candidates:
+        if not path or not path.is_file():
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        if PLACEHOLD_RE.search(text):
+            rel = path.relative_to(profile_path.parent) if path.is_relative_to(profile_path.parent) else path
+            hits.append(str(rel))
+
+    if hits:
+        report.warn(
+            "verify_fetch_antipatterns",
+            f"placehold.co references in {len(hits)} script(s)",
+            scripts=hits,
+        )
+    else:
+        report.pass_("verify_fetch_antipatterns", "No placehold.co references in asset scripts")
+
+    exit_with_report(report, json_stdout=args.json)
+
+
+if __name__ == "__main__":
+    main()

package/project-template-v2/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-template-v2/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-template-v2/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())

package/project-template-v2/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["node"],
+    "paths": {
+      "assets/*": ["./assets/*"]
+    }
+  },
+  "include": ["main.ts", "game/**/*.ts", "globals.d.ts", "vite.config.ts"]
+}

package/project-template-v2/vite.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "vite";
+import path from "path";
+
+export default defineConfig(({ command }) => ({
+  define: {
+    __DEV__: JSON.stringify(command === "serve"),
+  },
+  resolve: {
+    alias: {
+      assets: path.resolve(__dirname, "assets"),
+    },
+  },
+  server: {
+    host: "0.0.0.0",
+    // Preferred port; strictPort:false (the default, set explicitly here for
+    // intent) lets Vite auto-increment when 3000 is taken. The harness scripts
+    // (dev:start / verify:* / record:mp4) parse Vite's actual "Local:" URL, so
+    // port drift never needs to be tracked by hand. See dev-start.mjs.
+    port: 3000,
+    strictPort: false,
+    open: true,
+  },
+  build: {
+    outDir: "dist",
+    sourcemap: true,
+  },
+}));