@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/phaser/skills/playable-record/scripts/record-playable.mjs

@@ -0,0 +1,583 @@
+#!/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,
+    focusMode: false,
+    focusScope: null,
+    focusFixture: null,
+    focusDuration: 8000,
+    focusWarmup: 800,
+    cleanLab: null,
+    harness: null,
+    harnessSpec: null,
+    sweepMode: 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 === '--focus') opts.focusMode = true;
+    else if (arg === '--sweep') opts.sweepMode = true;
+    else if (arg === '--use-dev') opts.useDev = true;
+    else if (arg.startsWith('--lab=')) opts.cleanLab = arg.slice(6);
+    else if (arg.startsWith('--harness=')) opts.harness = arg.slice(10);
+    else if (arg.startsWith('--spec=')) opts.harnessSpec = arg.slice(7);
+    else if (arg.startsWith('--scope=')) opts.focusScope = arg.slice(8);
+    else if (arg.startsWith('--fixture=')) opts.focusFixture = arg.slice(10);
+    else if (arg.startsWith('--duration=')) opts.focusDuration = Number(arg.slice(11));
+    else if (arg.startsWith('--warmup=')) opts.focusWarmup = Number(arg.slice(9));
+    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)
+
+Focus playground (Integration Lab — MainScene, real composite):
+  --focus               Enable focus mode (short clip, URL query params)
+  --scope=PHASE         focusScope (PHASE | EVENT | FX)
+  --fixture=endcard-win fixture name
+  --duration=8000       Capture duration ms (default 8000)
+  --warmup=800          Wait after load before capture (ms)
+
+Clean Lab (type harness + catalog spec):
+  --harness=frame       focus-lab/frame.html?spec=…&capture=1
+  --harness=particle    focus-lab/particle.html?spec=…&capture=1
+  --spec=match_burst_v2 catalog spec id (required with --harness)
+  --lab=shatter         (legacy) alias → shatter composite page
+`);
+}
+
+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 waitForPlayableReadyInPage(sceneKey = 'MainScene') {
+  if (window.__playable && typeof window.__playable.getState === 'function') {
+    try {
+      window.__playable.getState();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  const scene = window.__game?.scene?.getScene(sceneKey);
+  return !!(scene?.sys?.isActive?.());
+}
+
+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}`);
+
+  if (opts.harness || opts.cleanLab) {
+    if (!opts.sweepMode) opts.out = join(opts.out, 'clean');
+  } else if (opts.focusMode) {
+    if (!opts.focusScope) {
+      console.error('[record] --focus requires --scope=PHASE|EVENT|FX');
+      process.exit(1);
+    }
+    if (!opts.sweepMode) opts.out = join(opts.out, 'focus');
+  }
+
+  let harnessMeta = null;
+  if (opts.harness) {
+    const catalog = JSON.parse(await readFile(join(projectRoot, 'playground', 'vfx-catalog.json'), 'utf8'));
+    harnessMeta = catalog.renderTypes[opts.harness];
+    if (!harnessMeta) {
+      console.error(`[record] unknown harness type: ${opts.harness}`);
+      process.exit(1);
+    }
+    if (!opts.harnessSpec) {
+      console.error('[record] --harness requires --spec=<catalogSpecId>');
+      process.exit(1);
+    }
+  }
+
+  const focusLabel = opts.outputName
+    ? `${opts.outputName}.mp4`
+    : opts.harness
+    ? `${opts.harness}-${opts.harnessSpec}-${ts}.mp4`
+    : opts.cleanLab
+      ? `FX-${opts.cleanLab}-${ts}.mp4`
+      : opts.focusMode
+        ? `${opts.focusScope}-${opts.focusFixture || 'default'}-${ts}.mp4`
+        : `playable-${ts}.mp4`;
+  const webmPath = join(tmpDir, 'capture.webm');
+  const mp4Path = join(opts.out, focusLabel);
+
+  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 {
+    let pageUrl = opts.url;
+    let viewport = { width: 1080, height: 1920 };
+    let cleanSceneKey = null;
+
+    const baseUrl = opts.url.replace(/\/+$/, '');
+    if (opts.harness && harnessMeta) {
+      const q = new URLSearchParams();
+      q.set('spec', opts.harnessSpec);
+      q.set('capture', '1');
+      pageUrl = `${baseUrl}${harnessMeta.harness}?${q.toString()}`;
+      viewport = {
+        width: harnessMeta.viewport.width,
+        height: harnessMeta.viewport.height
+      };
+      cleanSceneKey = harnessMeta.sceneKey;
+      if (opts.focusDuration === 8000) {
+        opts.focusDuration = (harnessMeta.loopMs || 1800) * 3;
+      }
+    } else if (opts.cleanLab === 'shatter') {
+      pageUrl = `${baseUrl}/focus-lab/shatter.html?capture=1`;
+      viewport = { width: 720, height: 800 };
+      cleanSceneKey = 'ShatterLabScene';
+    } else if (opts.focusMode) {
+      const q = new URLSearchParams();
+      q.set('focusScope', opts.focusScope);
+      if (opts.focusFixture) q.set('fixture', opts.focusFixture);
+      pageUrl += `?${q.toString()}`;
+    }
+    console.log(`[record] Project: ${projectRoot}`);
+    console.log(`[record] Mode: ${opts.harness ? `harness:${opts.harness}/${opts.harnessSpec}` : opts.cleanLab ? `clean-lab:${opts.cleanLab}` : opts.focusMode ? 'focus' : '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('[FrameLab]') || text.includes('[ParticleLab]') || text.includes('[ShatterLab]') || text.includes('[Playground]') || text.includes('[MainScene]')) {
+        console.log(`[browser] ${text}`);
+      }
+    });
+
+    console.log('[record] Loading game…');
+    await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: 60000 });
+
+    if (opts.harness || opts.cleanLab) {
+      console.log(`[record] Waiting for playable ready (clean harness)…`);
+      await page.waitForFunction(
+        ({ src, key }) => {
+          // eslint-disable-next-line no-eval
+          const ready = eval(`(${src})`);
+          return ready(key);
+        },
+        { src: waitForPlayableReadyInPage.toString(), key: cleanSceneKey },
+        { timeout: 30000 },
+      );
+
+      console.log(`[record] Starting clean harness capture (${opts.fps} fps)…`);
+      await page.evaluate(({ source, fps }) => {
+        // eslint-disable-next-line no-eval
+        eval(source);
+        startAvCapture(fps);
+      }, { source: bridgeSource, fps: opts.fps });
+
+      console.log(`[record] Warmup (${opts.focusWarmup}ms)…`);
+      await page.waitForTimeout(opts.focusWarmup);
+
+      console.log(`[record] Clean hold (${opts.focusDuration}ms)…`);
+      await page.waitForTimeout(opts.focusDuration);
+    } else if (opts.focusMode) {
+      console.log('[record] Waiting for MainScene (focus)…');
+      await page.waitForFunction(() => {
+        return !!window.__playable || window.__game?.scene?.getScene('MainScene')?.sceneManager != null;
+      }, { timeout: 30000 });
+
+      console.log(`[record] Starting focus capture (${opts.fps} fps)…`);
+      await page.evaluate(({ source, fps }) => {
+        // eslint-disable-next-line no-eval
+        eval(source);
+        startAvCapture(fps);
+      }, { source: bridgeSource, fps: opts.fps });
+
+      console.log(`[record] Warmup (${opts.focusWarmup}ms)…`);
+      await page.waitForTimeout(opts.focusWarmup);
+
+      if (opts.focusScope === 'PHASE') {
+        await page.waitForFunction(
+          (src) => {
+            // eslint-disable-next-line no-eval
+            const phase = eval(`(${src})`);
+            return phase() === 'ENDCARD';
+          },
+          getPlayablePhaseInPage.toString(),
+          { timeout: 15000 },
+        ).catch(() => {
+          console.warn('[record] ENDCARD wait timeout — continuing capture');
+        });
+      }
+
+      console.log(`[record] Focus hold (${opts.focusDuration}ms)…`);
+      await page.waitForTimeout(opts.focusDuration);
+    } else {
+    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);
+});