@playcraft/cli 0.1.54 → 0.1.56-beta

package/project-template-v2/skills/playable-record/scripts/record-playable.mjs

@@ -0,0 +1,425 @@
+#!/usr/bin/env node
+/**
+ * Playwright auto-record: HOOK → debug auto-play → ENDCARD → MP4 (60fps canvas + audio).
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright';
+import { evaluateContract, snapshotContractInPage } from './verify-contract.mjs';
+import {
+  detectDevUrl,
+  pickServerPort,
+  startDevServer,
+  startHttpServer,
+  waitForHttp,
+} from './lib/dev-server.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BRIDGE_PATH = join(__dirname, 'lib', 'record-audio-bridge.js');
+
+function parseArgs(argv) {
+  const defaultRoot = process.cwd();
+  const opts = {
+    port: 8080,
+    root: defaultRoot,
+    out: join(defaultRoot, 'recordings'),
+    hookDelay: 1200,
+    tailDelay: 2500,
+    timeout: 180000,
+    fps: 60,
+    keepIntermediate: false,
+    headed: false,
+    useDev: false,
+    url: null,
+    outputName: null,
+  };
+
+  for (const arg of argv) {
+    if (arg === '--keep-intermediate') opts.keepIntermediate = true;
+    else if (arg === '--headed') opts.headed = true;
+    else if (arg === '--use-dev') opts.useDev = true;
+    else if (arg.startsWith('--port=')) opts.port = Number(arg.slice(7));
+    else if (arg.startsWith('--root=')) {
+      const rootArg = arg.slice(7);
+      opts.root = rootArg.startsWith('/') ? rootArg : join(process.cwd(), rootArg);
+    } else if (arg.startsWith('--out=')) {
+      const outArg = arg.slice(6);
+      opts._outArg = outArg;
+    } else if (arg.startsWith('--url=')) {
+      opts.url = arg.slice(6);
+    }
+    else if (arg.startsWith('--hook-delay=')) opts.hookDelay = Number(arg.slice(13));
+    else if (arg.startsWith('--tail-delay=')) opts.tailDelay = Number(arg.slice(13));
+    else if (arg.startsWith('--timeout=')) opts.timeout = Number(arg.slice(10));
+    else if (arg.startsWith('--fps=')) opts.fps = Number(arg.slice(6));
+    else if (arg.startsWith('--name=')) opts.outputName = arg.slice(7).trim() || null;
+    else if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+  }
+
+  if (opts._outArg) {
+    const outArg = opts._outArg;
+    opts.out = outArg.startsWith('/') ? outArg : join(opts.root, outArg);
+    delete opts._outArg;
+  } else {
+    opts.out = join(opts.root, 'recordings');
+  }
+
+  return opts;
+}
+
+function printHelp() {
+  console.log(`Usage: node scripts/record-playable.mjs [options]
+
+Options:
+  --port=8080           Local http-server port (standalone projects)
+  --root=.              Project root (http-server cwd or npm run dev cwd)
+  --out=recordings/     Output directory for MP4 (relative to cwd unless absolute)
+  --name=autoplay       Stable output basename (autoplay.mp4) instead of timestamp
+  --fps=60              Canvas capture frame rate (default 60)
+  --hook-delay=1200     Wait after HOOK before auto-play (ms)
+  --tail-delay=2500     Hold ENDCARD tail frame (ms)
+  --timeout=180000      Whole run timeout (ms)
+  --keep-intermediate   Keep intermediate webm
+  --headed              Run browser with UI (debug WebGL/audio)
+  --use-dev             Run "npm run dev" instead of starting http-server
+  --url=http://...      Use an existing dev server URL (implies external server)
+`);
+}
+
+function run(cmd, args, { cwd = process.cwd(), quiet = false } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: quiet ? 'pipe' : 'inherit' });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+    });
+  });
+}
+
+function runCapture(cmd, args, { cwd = process.cwd() } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve(stdout);
+      else reject(new Error(stderr || `${cmd} failed with code ${code}`));
+    });
+  });
+}
+
+async function ensureFfmpeg() {
+  try {
+    await runCapture('ffmpeg', ['-version']);
+  } catch {
+    console.error('ffmpeg is required. Install with: brew install ffmpeg');
+    process.exit(1);
+  }
+}
+
+function timestamp() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+/* Browser-side helpers: prefer engine-neutral window.__playable, keep legacy Phaser fallback. */
+function getPlayablePhaseInPage(sceneKey = 'MainScene') {
+  if (window.__playable && typeof window.__playable.getState === 'function') {
+    return window.__playable.getState()?.currentPhase;
+  }
+  return window.__game?.scene?.getScene(sceneKey)?.sceneManager?.currentPhase;
+}
+
+function isPlayableGameOverInPage(sceneKey = 'MainScene') {
+  if (window.__playable && typeof window.__playable.getState === 'function') {
+    const state = window.__playable.getState();
+    return !!state?.isGameOver && state.currentPhase === 'ENDCARD';
+  }
+  const sm = window.__game?.scene?.getScene(sceneKey)?.sceneManager;
+  return !!sm?.isGameOver?.() && sm.currentPhase === 'ENDCARD';
+}
+
+function triggerPlayableAutoPlayInPage(sceneKey = 'MainScene') {
+  if (window.__playable && typeof window.__playable.autoPlay === 'function') {
+    window.__playable.autoPlay();
+    return true;
+  }
+  const scene = window.__game?.scene?.getScene(sceneKey);
+  if (scene && typeof scene._onDebugAutoPlay === 'function') {
+    scene._onDebugAutoPlay();
+    return true;
+  }
+  return false;
+}
+
+function hideDebugUiInPage(sceneKey = 'MainScene') {
+  if (window.__playable && typeof window.__playable.hideDebugUi === 'function') {
+    window.__playable.hideDebugUi();
+    return;
+  }
+  const btn = window.__game?.scene?.getScene(sceneKey)?.debugButton;
+  if (btn?.container?.setVisible) btn.container.setVisible(false);
+}
+
+async function webmToMp4(webmPath, mp4Path, fps) {
+  await run('ffmpeg', [
+    '-y',
+    '-i', webmPath,
+    '-c:v', 'libx264',
+    '-preset', 'medium',
+    '-crf', '18',
+    '-pix_fmt', 'yuv420p',
+    '-r', String(fps),
+    '-c:a', 'aac',
+    '-b:a', '192k',
+    '-ar', '48000',
+    '-movflags', '+faststart',
+    mp4Path
+  ], { quiet: true });
+}
+
+async function probeMp4(mp4Path) {
+  const out = await runCapture('ffprobe', [
+    '-v', 'error',
+    '-select_streams', 'v:0',
+    '-show_entries', 'stream=width,height,avg_frame_rate',
+    '-of', 'csv=p=0:s=x',
+    mp4Path
+  ]);
+  const fps = await runCapture('ffprobe', [
+    '-v', 'error',
+    '-select_streams', 'v:0',
+    '-show_entries', 'stream=avg_frame_rate',
+    '-of', 'csv=p=0',
+    mp4Path
+  ]);
+  const audio = await runCapture('ffprobe', [
+    '-v', 'error',
+    '-select_streams', 'a:0',
+    '-show_entries', 'stream=codec_name',
+    '-of', 'csv=p=0',
+    mp4Path
+  ]);
+  return { video: out.trim(), fps: fps.trim(), audio: audio.trim() };
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const projectRoot = opts.root;
+  await ensureFfmpeg();
+
+  const bridgeSource = await readFile(BRIDGE_PATH, 'utf8');
+  const ts = timestamp();
+  const tmpDir = join(opts.out, `.tmp-${ts}`);
+
+  const outputLabel = opts.outputName
+    ? `${opts.outputName}.mp4`
+    : `playable-${ts}.mp4`;
+  const webmPath = join(tmpDir, 'capture.webm');
+  const mp4Path = join(opts.out, outputLabel);
+
+  await mkdir(opts.out, { recursive: true });
+  await mkdir(tmpDir, { recursive: true });
+
+  let server = null;
+  let browser;
+  let externalServer = false;
+
+  if (opts.url && !opts.useDev) {
+    externalServer = true;
+  } else if (opts.useDev) {
+    server = startDevServer(projectRoot);
+    const preferredUrl = opts.url || 'http://127.0.0.1:3000/';
+    console.log(`[record] Starting dev server, waiting for ${preferredUrl}`);
+    const detectedUrl = await detectDevUrl(server, preferredUrl, 30000);
+    opts.url = detectedUrl;
+    await waitForHttp(opts.url, 30000);
+  } else {
+    opts.port = await pickServerPort(opts.port, '/game/index.html');
+    server = startHttpServer(opts.port, projectRoot);
+    opts.url = `http://127.0.0.1:${opts.port}/game/index.html`;
+  }
+
+  const killServer = () => {
+    if (server && !server.killed) server.kill('SIGTERM');
+  };
+
+  process.on('SIGINT', () => {
+    killServer();
+    process.exit(130);
+  });
+
+  try {
+    const pageUrl = opts.url;
+    const viewport = { width: 1080, height: 1920 };
+    console.log(`[record] Project: ${projectRoot}`);
+    console.log('[record] Mode: full');
+    console.log(`[record] Server: ${externalServer ? 'external' : opts.useDev ? 'npm run dev' : 'http-server'}`);
+    console.log(`[record] Waiting for ${pageUrl}`);
+    await waitForHttp(pageUrl, 30000);
+
+    browser = await chromium.launch({
+      headless: !opts.headed,
+      args: [
+        '--disable-background-timer-throttling',
+        '--disable-backgrounding-occluded-windows',
+        '--disable-renderer-backgrounding'
+      ]
+    });
+    const context = await browser.newContext({
+      viewport,
+      deviceScaleFactor: 1,
+      locale: 'zh-CN'
+    });
+    const page = await context.newPage();
+
+    page.on('console', (msg) => {
+      const text = msg.text();
+      if (text.includes('[MainScene]')) {
+        console.log(`[browser] ${text}`);
+      }
+    });
+
+    console.log('[record] Loading game…');
+    await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: 60000 });
+
+    console.log('[record] Waiting for HOOK phase…');
+    try {
+      await page.waitForFunction(
+        (src) => {
+          // eslint-disable-next-line no-eval
+          const phase = eval(`(${src})`);
+          return phase() === 'HOOK';
+        },
+        getPlayablePhaseInPage.toString(),
+        { timeout: 30000 },
+      );
+    } catch (err) {
+      const hasEntry = await page.evaluate(() => typeof window.__playable !== 'undefined' || typeof window.__game !== 'undefined');
+      if (!hasEntry) {
+        throw new Error(
+          'window.__playable not found. The playable must publish the neutral runtime contract; legacy Phaser projects may also expose window.__game. See game/runtime-contract.ts.'
+        );
+      }
+      throw err;
+    }
+
+    // Fail fast (in ~0s) with a clear reason when a hook the recorder needs is
+    // missing, instead of waiting out the ENDCARD timeout below.
+    const contractSnapshot = await page.evaluate(
+      ([key, src]) => {
+        // eslint-disable-next-line no-eval
+        const fn = eval(`(${src})`);
+        return fn(key);
+      },
+      ['MainScene', snapshotContractInPage.toString()],
+    );
+    const contract = evaluateContract(contractSnapshot, 'MainScene');
+    if (!contract.ok) {
+      throw new Error(
+        'runtime contract broken before capture:\n' +
+          contract.problems.map((p) => `  - ${p}`).join('\n') +
+          '\nSee game/runtime-contract.ts — record:mp4 depends on these hooks.',
+      );
+    }
+
+    console.log(`[record] Starting canvas capture (${opts.fps} fps) + audio…`);
+    await page.evaluate(({ source, fps }) => {
+      // eslint-disable-next-line no-eval
+      eval(source);
+      startAvCapture(fps);
+    }, { source: bridgeSource, fps: opts.fps });
+
+    // Debug: check capture state
+    const debugStart = await page.evaluate(() => window.__avCaptureDebug);
+    console.log('[record] Capture debug:', JSON.stringify(debugStart));
+
+    console.log(`[record] HOOK entry (${opts.hookDelay}ms)…`);
+    await page.waitForTimeout(opts.hookDelay);
+
+    await page.evaluate(
+      ({ src, key }) => {
+        // eslint-disable-next-line no-eval
+        const hide = eval(`(${src})`);
+        hide(key);
+      },
+      { src: hideDebugUiInPage.toString(), key: 'MainScene' },
+    );
+
+    console.log('[record] Triggering debug auto-play…');
+    const autoStarted = await page.evaluate(
+      (src) => {
+        // eslint-disable-next-line no-eval
+        const trigger = eval(`(${src})`);
+        return trigger();
+      },
+      triggerPlayableAutoPlayInPage.toString(),
+    );
+    if (!autoStarted) {
+      throw new Error('runtime contract broken before capture: no __playable.autoPlay() or MainScene._onDebugAutoPlay() hook');
+    }
+
+    console.log('[record] Waiting for ENDCARD…');
+    await page.waitForFunction(
+      (src) => {
+        // eslint-disable-next-line no-eval
+        const done = eval(`(${src})`);
+        return done();
+      },
+      isPlayableGameOverInPage.toString(),
+      { timeout: opts.timeout },
+    );
+
+    console.log(`[record] Tail frame (${opts.tailDelay}ms)…`);
+    await page.waitForTimeout(opts.tailDelay);
+
+    console.log('[record] Stopping capture…');
+    const avBytes = await page.evaluate(async (source) => {
+      // eslint-disable-next-line no-eval
+      eval(source);
+      return stopAvCapture();
+    }, bridgeSource);
+
+    // Debug: check capture result
+    const debugStop = await page.evaluate(() => window.__avCaptureDebug);
+    console.log('[record] Capture result:', JSON.stringify(debugStop));
+
+    await writeFile(webmPath, Buffer.from(avBytes));
+
+    await context.close();
+    await browser.close();
+    browser = null;
+
+    console.log('[record] Transcoding to MP4…');
+    await webmToMp4(webmPath, mp4Path, opts.fps);
+
+    const probe = await probeMp4(mp4Path);
+    console.log(`[record] Done: ${mp4Path}`);
+    console.log(`[record] Video: ${probe.video}, FPS: ${probe.fps}, Audio: ${probe.audio || '(none)'}`);
+
+    if (!opts.keepIntermediate) {
+      await rm(tmpDir, { recursive: true, force: true });
+    } else {
+      console.log(`[record] Intermediate file kept: ${webmPath}`);
+    }
+  } finally {
+    killServer();
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+main().catch((err) => {
+  console.error('[record] Failed:', err.message);
+  process.exit(1);
+});

package/project-template-v2/skills/playable-record/scripts/verify-contract.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * Live runtime-contract probe — the dynamic half of the Playable ⇄ Harness
+ * contract check (the static half is verify_runtime_contract.js).
+ *
+ * It boots the game in a headless browser and asserts, within a few seconds,
+ * that the recorder's entry points are actually wired at runtime:
+ *   - window.__playable is published as the neutral harness entry point
+ *   - window.__game may exist as a legacy engine handle, but must not shadow
+ *     Phaser.Game.start()
+ *   - MainScene.sceneManager.currentPhase is a string, or __playable.getState()
+ *     returns a string currentPhase
+ *   - MainScene._onDebugAutoPlay() or __playable.autoPlay() is a function
+ *
+ * This turns "record:mp4 silently times out after 30s" into a clear failure in
+ * seconds. The validation rule lives in `evaluateContract` so it can be unit
+ * tested and reused by record-playable.mjs without a second browser launch.
+ *
+ * Exit 0 = contract satisfied, 2 = contract broken, 1 = unexpected error.
+ *
+ * Usage:
+ *   node skills/playable-record/scripts/verify-contract.mjs --root=. --use-dev --url=http://localhost:3000/
+ *   node skills/playable-record/scripts/verify-contract.mjs --root=.            # standalone http-server
+ *   node skills/playable-record/scripts/verify-contract.mjs --url=http://localhost:3000/ --json
+ */
+
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectDevUrl, startDevServer, startHttpServer, waitForHttp } from './lib/dev-server.mjs';
+import { writeValidatorArtifact } from '../../_shared/scripts/lib/validator-artifacts.mjs';
+
+const DEFAULT_SCENE = 'MainScene';
+
+function parseArgs(argv) {
+  const opts = {
+    root: process.cwd(),
+    url: null,
+    useDev: false,
+    port: 8080,
+    scene: DEFAULT_SCENE,
+    timeout: 8000,
+    headed: false,
+    json: false,
+  };
+  for (const arg of argv) {
+    if (arg === '--use-dev') opts.useDev = true;
+    else if (arg === '--headed') opts.headed = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg.startsWith('--url=')) opts.url = arg.slice('--url='.length);
+    else if (arg.startsWith('--port=')) opts.port = Number(arg.slice('--port='.length));
+    else if (arg.startsWith('--scene=')) opts.scene = arg.slice('--scene='.length);
+    else if (arg.startsWith('--timeout=')) opts.timeout = Number(arg.slice('--timeout='.length));
+  }
+  return opts;
+}
+
+/**
+ * Validate a runtime snapshot of the contract surface. Pure — no browser — so it
+ * is unit-tested directly and shared with record-playable.mjs.
+ *
+ * @param {object|null|undefined} snapshot
+ * @param {string} [sceneKey]
+ * @returns {{ ok: boolean, problems: string[] }}
+ */
+export function evaluateContract(snapshot, sceneKey = DEFAULT_SCENE) {
+  const problems = [];
+  const warnings = [];
+  if (!snapshot || (!snapshot.hasPlayable && !snapshot.hasGame)) {
+    problems.push('window.__playable is not defined — publishPlayableRuntime() was never called');
+    return { ok: false, problems, warnings };
+  }
+  if (snapshot.gameStartShadowed) {
+    problems.push('window.__game.start shadows Phaser.Game.start — put harness start/autoPlay on window.__playable instead');
+  }
+  if (snapshot.hasPlayable) {
+    if (snapshot.playableAutoPlayType !== 'function') {
+      problems.push('window.__playable.autoPlay() must be a function');
+    }
+    if (snapshot.playableGetStateType !== 'function') {
+      problems.push('window.__playable.getState() must be a function');
+    }
+    if (snapshot.playableCurrentPhaseType !== 'string') {
+      problems.push('window.__playable.getState().currentPhase must be a PlayablePhase string');
+    } else if (snapshot.playableCurrentPhase !== 'HOOK') {
+      problems.push('window.__playable.getState().currentPhase must start at HOOK');
+    }
+    if (snapshot.playableIsGameOverType !== 'boolean') {
+      problems.push('window.__playable.getState().isGameOver must be a boolean');
+    }
+  } else {
+    warnings.push(
+      'Legacy scene contract in use — migrate to window.__playable via publishPlayableRuntime() (deprecation target: 2026-Q3)',
+    );
+    if (!snapshot.hasScene) {
+      problems.push(`scene "${sceneKey}" not found on window.__game`);
+      return { ok: false, problems, warnings };
+    }
+    if (!snapshot.hasSceneManager) {
+      problems.push('scene.sceneManager is missing');
+    } else {
+      if (snapshot.currentPhaseType !== 'string') {
+        problems.push('sceneManager.currentPhase must be a PlayablePhase string');
+      }
+      if (snapshot.isGameOverType !== 'function') {
+        problems.push('sceneManager.isGameOver() must be a function');
+      }
+    }
+    if (snapshot.onDebugAutoPlayType !== 'function') {
+      problems.push('scene._onDebugAutoPlay() must be a function');
+    }
+  }
+  return { ok: problems.length === 0, problems, warnings };
+}
+
+/** The function evaluated inside the page to snapshot the contract surface. */
+/* c8 ignore start — runs in the browser, not under node coverage */
+export function snapshotContractInPage(sceneKey) {
+  const playable = window.__playable;
+  const game = window.__game;
+  const gameStartShadowed = !!(
+    game &&
+    Object.prototype.hasOwnProperty.call(game, 'start') &&
+    Object.getPrototypeOf(game) &&
+    typeof Object.getPrototypeOf(game).start === 'function'
+  );
+  let playableState = null;
+  try {
+    playableState = playable && typeof playable.getState === 'function' ? playable.getState() : null;
+  } catch {
+    playableState = null;
+  }
+  if (playable) {
+    return {
+      hasPlayable: true,
+      hasGame: !!game,
+      gameStartShadowed,
+      playableAutoPlayType: typeof playable.autoPlay,
+      playableGetStateType: typeof playable.getState,
+      playableCurrentPhase: playableState ? playableState.currentPhase : undefined,
+      playableCurrentPhaseType: playableState ? typeof playableState.currentPhase : 'undefined',
+      playableIsGameOverType: playableState ? typeof playableState.isGameOver : 'undefined',
+    };
+  }
+  if (!game) return { hasPlayable: false, hasGame: false };
+  const scene = game.scene && game.scene.getScene ? game.scene.getScene(sceneKey) : null;
+  if (!scene) return { hasPlayable: false, hasGame: true, hasScene: false, gameStartShadowed };
+  const sm = scene.sceneManager;
+  return {
+    hasPlayable: false,
+    hasGame: true,
+    hasScene: true,
+    gameStartShadowed,
+    hasSceneManager: sm != null,
+    currentPhase: sm ? sm.currentPhase : undefined,
+    currentPhaseType: sm ? typeof sm.currentPhase : 'undefined',
+    isGameOverType: sm ? typeof sm.isGameOver : 'undefined',
+    onDebugAutoPlayType: typeof scene._onDebugAutoPlay,
+  };
+}
+/* c8 ignore stop */
+
+/**
+ * Boot the game and probe the runtime contract.
+ * @returns {Promise<{ ok: boolean, problems: string[], snapshot: object, url: string }>}
+ */
+export async function runContractProbe(opts) {
+  const { chromium } = await import('playwright');
+  const projectRoot = resolve(opts.root);
+  let server = null;
+  let browser = null;
+  let url = opts.url;
+  let external = false;
+
+  if (opts.url && !opts.useDev) {
+    external = true;
+  } else if (opts.useDev) {
+    server = startDevServer(projectRoot);
+    url = await detectDevUrl(server, opts.url || 'http://127.0.0.1:3000/', 30000);
+  } else {
+    server = startHttpServer(opts.port, projectRoot);
+    url = `http://127.0.0.1:${opts.port}/game/index.html`;
+  }
+
+  const killServer = () => {
+    if (server && !server.killed) server.kill('SIGTERM');
+  };
+
+  try {
+    await waitForHttp(url, 30000);
+    browser = await chromium.launch({ headless: !opts.headed });
+    const context = await browser.newContext({ viewport: { width: 1080, height: 1920 } });
+    const page = await context.newPage();
+    await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
+
+    // Give the game a few seconds to boot and bind the contract, but fail fast.
+    await page
+      .waitForFunction(
+        (key) => {
+          if (window.__playable && typeof window.__playable.autoPlay === 'function') return true;
+          const s = window.__game && window.__game.scene && window.__game.scene.getScene(key);
+          return !!(s && s.sceneManager && typeof s._onDebugAutoPlay === 'function');
+        },
+        opts.scene,
+        { timeout: opts.timeout },
+      )
+      .catch(() => {
+        /* tolerate — the snapshot below reports exactly what is missing */
+      });
+
+    const snapshot = await page.evaluate(
+      ([key, src]) => {
+        // eslint-disable-next-line no-eval
+        const fn = eval(`(${src})`);
+        return fn(key);
+      },
+      [opts.scene, snapshotContractInPage.toString()],
+    );
+
+    const result = evaluateContract(snapshot, opts.scene);
+    return { ...result, snapshot, url, external };
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    killServer();
+  }
+}
+
+function printHuman(result) {
+  console.log(`[verify:contract] ${result.ok ? 'OK' : 'BROKEN'} — ${result.url}`);
+  if (result.ok) {
+    const phase = result.snapshot?.currentPhase ?? result.snapshot?.playableCurrentPhase ?? '?';
+    console.log(`  contract satisfied (phase=${phase})`);
+    for (const w of result.warnings ?? []) console.log(`  ⚠ ${w}`);
+  } else {
+    for (const p of result.problems) console.log(`  ✗ ${p}`);
+    for (const w of result.warnings ?? []) console.log(`  ⚠ ${w}`);
+    console.log('  See game/runtime-contract.ts — record:mp4 / one-click clear depend on these hooks.');
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = await runContractProbe(opts);
+  await writeValidatorArtifact(opts.root, 'contract', result).catch(() => {});
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(result.ok ? 0 : 2);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((err) => {
+    console.error(`[verify:contract] ${err.message}`);
+    process.exit(1);
+  });
+}