@homie-rocks/studio 0.19.2 → 0.20.0

package/lab/take.js

@@ -0,0 +1,189 @@
+/*
+ * A take: one short, repeatable piece of play the Game Lab shows in both builds (games/<id>/lab.json). The same file
+ * is read by the lab page (served as it is) and by `homie-studio lab` in Node.
+ *
+ *   {
+ *     "v": 1,
+ *     "default": "knock",
+ *     "takes": {
+ *       "knock": {
+ *         "note": "Walk right into Rook and bump him",
+ *         "seconds": 3,              // how long the take is
+ *         "seed": 7,                 // the world's dice (Math.random) in both builds
+ *         "device": "desk",          // desk (1280x800) or phone (390x844)
+ *         "fps": 60,                 // 60, 30, 15 or 12 frames a second
+ *         "stage": "dummy",          // a scene the game sets up for this mechanic (lab.stage; optional)
+ *         "view": "close",           // one of the game's lab.camera presets (optional)
+ *         "overlays": ["onion"],     // overlays on at the start (optional)
+ *         "track": "speed",          // the graph shown first (optional)
+ *         "storage": { "key": "value" },   // localStorage at the start (a saved hero, a setting)
+ *         "inputs": [
+ *           { "at": 0.1, "key": "ArrowRight", "hold": 0.6 },   // pressed at 0.1 s, held 0.6 s
+ *           { "at": 0.9, "key": "Space" },                    // a tap
+ *           { "at": 1.0, "down": "KeyW" }, { "at": 1.4, "up": "KeyW" },
+ *           { "at": 1.5, "pointer": "down", "x": 120, "y": 600, "id": 2, "pt": "touch" }
+ *         ]
+ *       }
+ *     }
+ *   }
+ *
+ * Times are seconds from the take's start; x and y are CSS pixels of the game's page at the take's device size.
+ */
+
+export const DEVICES = Object.freeze({
+  desk: { w: 1280, h: 800, dpr: 1, label: 'Desk' },
+  phone: { w: 390, h: 844, dpr: 2, label: 'Phone' },
+});
+export const FPS = Object.freeze([60, 30, 15, 12]);
+export const SCALES = Object.freeze([1, 0.5, 0.25, 0.1]);
+export const LIMITS = Object.freeze({ seconds: 60, inputs: 5000, takes: 24, name: 32 });
+export const TAKE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+const num = (v, d) => (Number.isFinite(Number(v)) ? Number(v) : d);
+const r4 = (v) => Math.round(v * 10000) / 10000;
+
+/** What is wrong with a take, in words (empty: nothing). */
+export function checkTake(take, name = 'take') {
+  const out = [];
+  if (!take || typeof take !== 'object' || Array.isArray(take)) return [`${name} is not an object`];
+  const s = Number(take.seconds);
+  if (!(s > 0 && s <= LIMITS.seconds)) out.push(`${name}.seconds must be between 0 and ${LIMITS.seconds}`);
+  if (take.fps !== undefined && !FPS.includes(Number(take.fps))) out.push(`${name}.fps must be one of ${FPS.join(', ')}`);
+  if (take.device !== undefined && !Object.hasOwn(DEVICES, take.device)) out.push(`${name}.device must be desk or phone`);
+  if (take.seed !== undefined && !(Number.isInteger(Number(take.seed)) && Number(take.seed) >= 0)) out.push(`${name}.seed must be a whole number`);
+  if (take.stage !== undefined && !(typeof take.stage === 'string' && /^[a-z0-9][a-z0-9-]{0,31}$/.test(take.stage))) out.push(`${name}.stage is a short lowercase name`);
+  if (take.storage !== undefined && (typeof take.storage !== 'object' || Array.isArray(take.storage) || take.storage === null)) out.push(`${name}.storage must be an object of keys`);
+  const inputs = take.inputs ?? [];
+  if (!Array.isArray(inputs)) out.push(`${name}.inputs must be a list`);
+  else {
+    if (inputs.length > LIMITS.inputs) out.push(`${name} has ${inputs.length} inputs (at most ${LIMITS.inputs})`);
+    inputs.forEach((row, i) => {
+      const at = Number(row?.at);
+      if (!(at >= 0)) { out.push(`${name}.inputs[${i}].at must be seconds from the start`); return; }
+      const kinds = ['key', 'down', 'up', 'pointer'].filter((k) => row[k] !== undefined);
+      if (kinds.length !== 1) out.push(`${name}.inputs[${i}] needs exactly one of key, down, up or pointer`);
+      else if (kinds[0] === 'pointer') {
+        if (!['down', 'move', 'up', 'cancel'].includes(row.pointer)) out.push(`${name}.inputs[${i}].pointer is down, move, up or cancel`);
+        if (!Number.isFinite(Number(row.x)) || !Number.isFinite(Number(row.y))) out.push(`${name}.inputs[${i}] needs x and y`);
+      } else if (typeof row[kinds[0]] !== 'string' || !/^[A-Za-z0-9]{1,24}$/.test(row[kinds[0]])) out.push(`${name}.inputs[${i}].${kinds[0]} is a KeyboardEvent code such as ArrowRight, KeyW or Space`);
+    });
+  }
+  return out;
+}
+
+/** Every take of a lab file, checked: { takes, default, problems }. */
+export function readLabFile(json) {
+  const problems = [];
+  const takes = {};
+  if (!json || typeof json !== 'object') return { takes, default: null, problems: ['lab.json is not an object'] };
+  const all = json.takes && typeof json.takes === 'object' ? json.takes : {};
+  for (const [name, take] of Object.entries(all).slice(0, LIMITS.takes)) {
+    if (!TAKE_NAME.test(name)) { problems.push(`take "${name}": a name is lowercase letters, digits and hyphens`); continue; }
+    const p = checkTake(take, name);
+    if (p.length) problems.push(...p); else takes[name] = take;
+  }
+  const names = Object.keys(takes);
+  return { takes, default: names.includes(json.default) ? json.default : names[0] ?? null, problems };
+}
+
+/** How many frames a take has at its frame rate. */
+export function framesOf(take, fps = take?.fps ?? 60) { return Math.max(1, Math.round(num(take?.seconds, 3) * fps)); }
+
+/** A take as the harness plays it: inputs as events in ms, in order. */
+export function expandTake(take, { fps } = {}) {
+  const f = FPS.includes(Number(fps)) ? Number(fps) : FPS.includes(Number(take.fps)) ? Number(take.fps) : 60;
+  const events = [];
+  for (const row of take.inputs ?? []) {
+    const at = num(row.at, 0) * 1000;
+    if (row.key !== undefined) {
+      events.push({ at, type: 'key', code: row.key, down: true });
+      events.push({ at: at + Math.max(1000 / f, num(row.hold, 0.05) * 1000), type: 'key', code: row.key, down: false });
+    } else if (row.down !== undefined) events.push({ at, type: 'key', code: row.down, down: true });
+    else if (row.up !== undefined) events.push({ at, type: 'key', code: row.up, down: false });
+    else if (row.pointer !== undefined) events.push({ at, type: 'pointer', ev: row.pointer, x: num(row.x, 0), y: num(row.y, 0), id: Math.max(1, Math.round(num(row.id, 1))), pt: row.pt === 'mouse' || row.pt === 'pen' ? row.pt : 'touch' });
+  }
+  // Stable: two events at one time keep the file's order.
+  const order = events.map((e, i) => [e, i]).sort((a, b) => a[0].at - b[0].at || a[1] - b[1]).map(([e]) => e);
+  return {
+    fps: f,
+    frames: framesOf(take, f),
+    seed: Number.isInteger(Number(take.seed)) ? Number(take.seed) : 1,
+    device: Object.hasOwn(DEVICES, take.device) ? take.device : 'desk',
+    stage: typeof take.stage === 'string' ? take.stage : null,
+    view: typeof take.view === 'string' ? take.view : null,
+    overlays: Array.isArray(take.overlays) ? take.overlays.map(String) : [],
+    track: typeof take.track === 'string' ? take.track : null,
+    storage: take.storage && typeof take.storage === 'object' ? take.storage : null,
+    inputs: order,
+  };
+}
+
+/**
+ * What the harness recorded (events in ms) as a take's inputs (seconds): a key pressed and let go becomes one row
+ * with its hold; anything else stays an edge.
+ */
+export function inputsFromRecording(events) {
+  const rows = [];
+  const open = new Map();
+  for (const e of events) {
+    const at = r4(num(e.at, 0) / 1000);
+    if (e.type === 'key' && e.down) { const row = { at, down: e.code }; open.set(e.code, row); rows.push(row); }
+    else if (e.type === 'key') {
+      const d = open.get(e.code);
+      if (d) { open.delete(e.code); delete d.down; d.key = e.code; d.hold = r4(at - d.at); } else rows.push({ at, up: e.code });
+    } else if (e.type === 'pointer') rows.push({ at, pointer: e.ev, x: e.x, y: e.y, id: e.id, pt: e.pt });
+  }
+  return rows.map((r) => (r.key !== undefined ? { at: r.at, key: r.key, hold: r.hold } : r));
+}
+
+/** lab.json as text: readable, one input to a line. */
+export function formatLabFile(json) {
+  const out = ['{', `  "v": 1,`, `  "default": ${JSON.stringify(json.default ?? null)},`, '  "takes": {'];
+  const names = Object.keys(json.takes ?? {});
+  names.forEach((name, i) => {
+    const t = json.takes[name];
+    const keys = Object.keys(t).filter((k) => k !== 'inputs');
+    out.push(`    ${JSON.stringify(name)}: {`);
+    const lines = keys.map((k) => `      ${JSON.stringify(k)}: ${JSON.stringify(t[k])}`);
+    const inputs = Array.isArray(t.inputs) ? t.inputs : [];
+    lines.push(`      "inputs": [${inputs.length ? `\n${inputs.map((r) => `        ${JSON.stringify(r)}`).join(',\n')}\n      ` : ''}]`);
+    out.push(lines.join(',\n'));
+    out.push(`    }${i < names.length - 1 ? ',' : ''}`);
+  });
+  out.push('  }', '}');
+  return `${out.join('\n')}\n`;
+}
+
+/** tunables.json as text: one tunable to a line, so a kept change is a one-line diff. */
+export function formatTunables(spec) {
+  const names = Object.keys(spec ?? {});
+  if (!names.length) return '{}\n';
+  const one = (s) => (s && typeof s === 'object' && !Array.isArray(s) ? `{ ${Object.entries(s).map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`).join(', ')} }` : JSON.stringify(s));
+  return `{\n${names.map((k, i) => `  ${JSON.stringify(k)}: ${one(spec[k])}${i < names.length - 1 ? ',' : ''}`).join('\n')}\n}\n`;
+}
+
+/** A tunable's value (a bare number, or { value }). */
+export function tunableValue(s) { return typeof s === 'number' ? s : num(s?.value, NaN); }
+
+/** tunables.json with new values (by name): what is unknown or not a number is refused, ranges are kept. */
+export function setTunables(spec, values) {
+  const next = JSON.parse(JSON.stringify(spec ?? {}));
+  const changed = [];
+  const refused = [];
+  for (const [k, raw] of Object.entries(values ?? {})) {
+    const v = Number(raw);
+    if (!Object.hasOwn(next, k)) { refused.push(`${k}: not in tunables.json`); continue; }
+    if (!Number.isFinite(v)) { refused.push(`${k}: ${JSON.stringify(raw)} is not a number`); continue; }
+    const s = next[k];
+    const before = tunableValue(s);
+    if (typeof s === 'number') next[k] = v;
+    else {
+      s.value = v;
+      // A value past the slider's end moves the end: the file says what was kept, and the slider still reaches it.
+      if (Number.isFinite(s.min) && v < s.min) s.min = v;
+      if (Number.isFinite(s.max) && v > s.max) s.max = v;
+    }
+    if (before !== v) changed.push({ name: k, from: before, to: v });
+  }
+  return { spec: next, changed, refused };
+}

package/lib/build.mjs

@@ -46,7 +46,7 @@ import { vocabularyOf } from '../worker/brain.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
-const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md']);
+const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md', 'lab.json']);
 const LOADERS = { '.png': 'file', '.jpg': 'file', '.jpeg': 'file', '.gif': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.m4a': 'file', '.glb': 'file', '.gltf': 'file', '.bin': 'file', '.hdr': 'file', '.svg': 'file', '.json': 'json', '.woff2': 'file', '.ttf': 'file' };
 
 /** The port toolkit as one classic script (window.HomiePort), for static games. Built once per build. */
@@ -222,10 +222,66 @@ function keepMap(root, id, out, metafile) {
   writeFileSync(join(dir, 'main.js.sha256'), `${createHash('sha256').update(readFileSync(join(out, 'assets', 'main.js'))).digest('hex')}\n`);
 }
 
-export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false } = {}) {
+/** esbuild, as the studio has it installed (the version its package.json pins). */
+export async function studioEsbuild(root) {
   const require = createRequire(join(root, 'package.json'));
-  let esbuild;
-  try { esbuild = require('esbuild'); } catch { esbuild = await import('esbuild'); }
+  try { return require('esbuild'); } catch { return import('esbuild'); }
+}
+
+/**
+ * One game's own files into `out` (emptied first): its bundle, static copy or own build's output, its index.html and
+ * its public/ folder. What `build` serves at /games/<id>/, and what the Game Lab (lib/lab.mjs) builds New and Today
+ * with. `sourcemap` is esbuild's (the lab keeps a linked map beside its builds); `maps` keeps the site build's map in
+ * .studio/maps/<id>/. Returns { mode, warnings, metafile } (metafile: the bundle's inputs, null for other modes).
+ */
+export async function buildGameFiles(esbuild, root, g, out, { maps = false, sourcemap = null, cache = {}, log = () => {} } = {}) {
+  rmSync(out, { recursive: true, force: true });
+  mkdirSync(join(out, 'assets'), { recursive: true });
+  const mode = g.build?.mode ?? 'bundle';
+  let warnings = 0;
+  let metafile = null;
+  const bundle = async (entryRel) => {
+    const entry = join(g.dir, entryRel);
+    if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
+    const result = await esbuild.build({
+      entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: sourcemap ?? (maps ? 'external' : false),
+      outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
+      loader: LOADERS, assetNames: '[name]-[hash]',
+    }).catch((error) => {
+      const first = error.errors?.[0];
+      throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
+    });
+    warnings += result.warnings.length;
+    metafile = result.metafile;
+    if (maps) keepMap(root, g.id, out, result.metafile);
+  };
+  if (mode === 'static') {
+    copyStatic(g.dir, out);
+    writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
+    if (g.entry) await bundle(g.entry);
+    const html = readFileSync(join(out, 'index.html'), 'utf8');
+    if (!/homie-port\.js/.test(html)) log(`warning: games/${g.id}/index.html does not load ./homie-port.js (the port toolkit); add <script src="./homie-port.js"></script> first in <head>`);
+  } else if (mode === 'command') {
+    const command = String(g.build.command ?? 'npm run build');
+    const res = spawnSync(command, { cwd: g.dir, shell: true, encoding: 'utf8', timeout: 10 * 60_000, maxBuffer: 64 * 1024 * 1024 });
+    if (res.status !== 0) throw new Error(`games/${g.id}: \`${command}\` failed: ${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-6).join(' ')}`);
+    const built = join(g.dir, String(g.build.out ?? 'dist'));
+    if (!existsSync(join(built, 'index.html'))) throw new Error(`games/${g.id}: \`${command}\` left no index.html in ${relative(g.dir, built) || '.'}`);
+    cpSync(built, out, { recursive: true });
+    writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
+  } else {
+    await bundle(g.entry ?? 'src/main.ts');
+    const html = join(g.dir, 'index.html');
+    if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
+    writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
+  }
+  if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
+  if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
+  return { mode, warnings, metafile };
+}
+
+export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false } = {}) {
+  const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
   const dist = join(root, 'site', 'dist');
   const games = listGames(root).filter((g) => !only || g.id === only);
@@ -236,47 +292,8 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   const cache = {};
   for (const g of games) {
     const out = join(dist, 'games', g.id);
-    rmSync(out, { recursive: true, force: true });
-    mkdirSync(join(out, 'assets'), { recursive: true });
-    const mode = g.build?.mode ?? 'bundle';
     const started = Date.now();
-    let warnings = 0;
-    const bundle = async (entryRel) => {
-      const entry = join(g.dir, entryRel);
-      if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
-      const result = await esbuild.build({
-        entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: maps ? 'external' : false,
-        outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
-        loader: LOADERS, assetNames: '[name]-[hash]',
-      }).catch((error) => {
-        const first = error.errors?.[0];
-        throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
-      });
-      warnings += result.warnings.length;
-      if (maps) keepMap(root, g.id, out, result.metafile);
-    };
-    if (mode === 'static') {
-      copyStatic(g.dir, out);
-      writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
-      if (g.entry) await bundle(g.entry);
-      const html = readFileSync(join(out, 'index.html'), 'utf8');
-      if (!/homie-port\.js/.test(html)) log(`warning: games/${g.id}/index.html does not load ./homie-port.js (the port toolkit); add <script src="./homie-port.js"></script> first in <head>`);
-    } else if (mode === 'command') {
-      const command = String(g.build.command ?? 'npm run build');
-      const res = spawnSync(command, { cwd: g.dir, shell: true, encoding: 'utf8', timeout: 10 * 60_000, maxBuffer: 64 * 1024 * 1024 });
-      if (res.status !== 0) throw new Error(`games/${g.id}: \`${command}\` failed: ${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-6).join(' ')}`);
-      const built = join(g.dir, String(g.build.out ?? 'dist'));
-      if (!existsSync(join(built, 'index.html'))) throw new Error(`games/${g.id}: \`${command}\` left no index.html in ${relative(g.dir, built) || '.'}`);
-      cpSync(built, out, { recursive: true });
-      writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
-    } else {
-      await bundle(g.entry ?? 'src/main.ts');
-      const html = join(g.dir, 'index.html');
-      if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
-      writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
-    }
-    if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
-    if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
+    const { mode, warnings } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log });
     // The guides' vocabulary (NETPLAY.md section 18): checked here, so a room never meets a line it cannot say.
     vocabFor(g, out);
     // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).

package/lib/lab-check.mjs

@@ -0,0 +1,212 @@
+/**
+ * `homie-studio lab check <game>`: the Game Lab, headless. The same lab page a person opens (lab/page) plays the take
+ * in New and Today in a headless Chrome on this computer's GPU, then plays it again from a fresh load and compares
+ * every frame, and writes what it saw:
+ *
+ *   .studio/lab/<game>/check-<time>/
+ *     summary.json   per build: each phase (frames, ms), each tracked value (peak, when, where it ends), the game's
+ *                    JavaScript per frame (median, p95), errors; whether a replay landed on the same frames
+ *     REPORT.md      the same, New against Today, in a few lines a person reads
+ *     sheet.png      the lab at the start of each phase, New beside Today
+ *     still.jpg      New beside Today at the take's busiest moment (what the Homie card shows)
+ *     page.jpg       the whole lab page at that moment
+ *   .studio/lab/<game>/latest.json   the last check, in a few fields (where its files are, its phases and numbers): what a
+ *                    Studio pane or a card shows without running anything (.studio/lab/server.json says where the
+ *                    lab itself is running)
+ *
+ *   homie-studio lab check <game> [--take <name>] [--today HEAD|<ref>] [--device desk|phone] [--fps 60] [--frames 6]
+ *                                 [--out <dir>] [--still <file.jpg>]
+ *
+ * It prints paths and a few numbers, never the data. The cost numbers are the game's JavaScript per frame on this
+ * computer, both builds on the same frames: a hint that a feel change costs something, never a frame-rate claim (the
+ * perf skill measures that, in two browsers in a room).
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { chromeArgs, findChrome, noChrome, SOFTWARE_GL } from './chrome.mjs';
+import { labDir, startLabServer } from './lab.mjs';
+import { listGames } from './studio.mjs';
+
+const round = (v, d = 2) => (Number.isFinite(v) ? Math.round(v * 10 ** d) / 10 ** d : null);
+const pct = (xs, p) => { const s = xs.filter(Number.isFinite).sort((a, b) => a - b); return s.length ? s[Math.min(s.length - 1, Math.floor((s.length - 1) * p))] : null; };
+
+/** One build's take, in numbers. */
+export function summarise(pane, { fps, units }) {
+  if (!pane?.available) return { available: false, why: pane?.why ?? null };
+  const frames = pane.frames ?? [];
+  const phases = (pane.phases ?? []).map((s) => ({ name: s.name, note: s.note ?? '', from: s.from + 1, to: s.to, frames: s.to - s.from, ms: round(((s.to - s.from) * 1000) / fps, 0) }));
+  const names = new Set();
+  for (const r of frames) for (const k of Object.keys(r?.tr ?? {})) names.add(k);
+  const tracks = {};
+  for (const name of names) {
+    const xs = frames.map((r) => (r?.tr && Object.hasOwn(r.tr, name) ? r.tr[name] : null));
+    let peak = null; let peakAt = null; let last = null;
+    xs.forEach((v, i) => { if (v === null) return; if (peak === null || Math.abs(v) > Math.abs(peak)) { peak = v; peakAt = i + 1; } last = v; });
+    const vals = xs.filter((v) => v !== null);
+    tracks[name] = { unit: units?.[name] ?? '', peak: round(peak), peakAt, final: round(last), mean: round(vals.reduce((a, b) => a + b, 0) / Math.max(1, vals.length)) };
+  }
+  const ms = frames.map((r) => r?.ms).filter(Number.isFinite);
+  return {
+    available: true,
+    instrumented: Boolean(pane.meta?.instrumented || pane.meta?.views?.length || pane.meta?.overlays?.length),
+    frames: frames.filter(Boolean).length,
+    phases, tracks,
+    // Chrome's clock in a page is coarse (0.1 ms steps): the mean over every frame is the finer number.
+    cost: { mean: round(ms.reduce((a, b) => a + b, 0) / Math.max(1, ms.length), 3), median: round(pct(ms, 0.5), 3), p95: round(pct(ms, 0.95), 3), max: round(Math.max(0, ...ms), 3) },
+    views: pane.meta?.views ?? [], overlays: pane.meta?.overlays ?? [],
+    errors: pane.meta?.errors ?? [],
+  };
+}
+
+/** Where two runs of one build first differ (frame number), or null when every frame matches. */
+export function firstDifference(a, b) {
+  const n = Math.max(a?.length ?? 0, b?.length ?? 0);
+  for (let i = 0; i < n; i += 1) if ((a?.[i]?.sig ?? null) !== (b?.[i]?.sig ?? null)) return i + 1;
+  return null;
+}
+
+/** Frames worth a picture: where each phase starts (New's, then Today's), filled in evenly, at most `n`. */
+export function keyFrames(newPhases, todayPhases, total, n = 6) {
+  const want = [];
+  const add = (f) => { if (f >= 1 && f <= total && !want.some((x) => Math.abs(x - f) < 3)) want.push(f); };
+  for (const s of newPhases ?? []) add(Math.min(s.to, s.from + 3));
+  for (const s of todayPhases ?? []) add(Math.min(s.to, s.from + 3));
+  for (let i = 1; want.length < n && i <= n * 2; i += 1) add(Math.round((i / (n * 2 + 1)) * total));
+  return want.sort((a, b) => a - b).slice(0, n);
+}
+
+function reportOf(r) {
+  const n = r.new; const t = r.today;
+  const lines = [`# ${r.game}: take "${r.take ?? '(none)'}"`, '', `${r.note ?? ''}`.trim(), '',
+    `- ${r.frames} frames at ${r.fps} fps (${round(r.frames / r.fps, 2)} s), ${r.device}, seed ${r.seed}, ${r.inputs} input events.`,
+    `- New: the working tree${r.newBuild?.dirty ? ` (${r.newBuild.dirty} changed in games/${r.game})` : ''}. Today: ${r.todayBuild?.commit ? `${r.todayBuild.commit.short} "${r.todayBuild.commit.subject}"` : r.todayBuild?.none ?? 'none'}.`,
+    `- Replays: ${r.deterministic.new === null ? 'New replayed on the same frames' : `New DIFFERED from frame ${r.deterministic.new}`}${t.available ? `; ${r.deterministic.today === null ? 'Today replayed on the same frames' : `Today DIFFERED from frame ${r.deterministic.today}`}` : ''}.`,
+    ...(Object.keys(r.overrides ?? {}).length ? [`- Sliders not kept yet: ${Object.entries(r.overrides).map(([k, v]) => `${k}=${v}`).join(', ')}`] : []),
+    '', '## Phases', '', '| | New | Today |', '| --- | --- | --- |'];
+  const names = [...new Set([...(n.phases ?? []).map((p) => p.name), ...(t.phases ?? []).map((p) => p.name)])];
+  const of = (side, name) => (side.phases ?? []).filter((p) => p.name === name).map((p) => `F${p.from}-${p.to} (${p.frames} f, ${p.ms} ms)`).join(', ') || '-';
+  for (const name of names) lines.push(`| ${name} | ${of(n, name)} | ${t.available ? of(t, name) : 'n/a'} |`);
+  lines.push('', '## Tracked values (peak, at frame; where it ends)', '', '| | New | Today |', '| --- | --- | --- |');
+  for (const name of [...new Set([...Object.keys(n.tracks ?? {}), ...Object.keys(t.tracks ?? {})])]) {
+    const cell = (side) => { const x = side.tracks?.[name]; return x ? `${x.peak}${x.unit ? ` ${x.unit}` : ''} at F${x.peakAt}; ends ${x.final}` : '-'; };
+    lines.push(`| ${name} | ${cell(n)} | ${t.available ? cell(t) : 'n/a'} |`);
+  }
+  lines.push('', `## The game's JavaScript per frame (this computer, the same frames)`, '',
+    `New mean ${n.cost?.mean} ms (median ${n.cost?.median}, p95 ${n.cost?.p95})${t.available ? `; Today mean ${t.cost?.mean} ms (median ${t.cost?.median}, p95 ${t.cost?.p95})` : ''}. Chrome times a page in steps of about 0.1 ms, so the mean over every frame is the finer number. A hint, not a frame rate: the perf skill measures that.`);
+  const errors = [...(n.errors ?? []).map((e) => `New: ${e}`), ...(t.errors ?? []).map((e) => `Today: ${e}`)];
+  if (errors.length) lines.push('', '## Errors', '', ...errors.map((e) => `- ${e}`));
+  lines.push('', `Pictures: sheet.png (the lab at ${r.keyFrames.map((f) => `F${f}`).join(', ')}), still.jpg (F${r.stillFrame}).`, '');
+  return lines.join('\n');
+}
+
+export async function labCheck(root, id, { take = null, today = 'HEAD', device = null, fps = null, out = null, still = null, frames: nKey = 6, log = () => {} } = {}) {
+  const games = listGames(root);
+  const game = id ?? (games.length === 1 ? games[0].id : null);
+  if (!game || !games.some((g) => g.id === game)) return { ok: false, command: 'lab check', why: `name the game: homie-studio lab check <${games.map((g) => g.id).join('|') || 'id'}>` };
+  const chrome = findChrome();
+  if (!chrome) return { ok: false, command: 'lab check', why: noChrome() };
+  let puppeteer;
+  try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'lab check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const dir = out ?? join(labDir(root, game), `check-${stamp}`);
+  mkdirSync(dir, { recursive: true });
+  const server = await startLabServer(root, { port: 0, today, watchFiles: false, log: () => {} });
+  const browser = await puppeteer.launch({
+    executablePath: chrome, headless: true, timeout: 150_000, protocolTimeout: 240_000,
+    args: [...chromeArgs(), '--mute-audio', '--window-size=1600,1000', '--no-first-run', '--no-default-browser-check', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows', '--force-color-profile=srgb'],
+  });
+  const t0 = Date.now();
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: 1600, height: 1000, deviceScaleFactor: 1 });
+    await page.setUserAgent(`${await browser.userAgent()} homie-studio-check homie-studio-lab`);
+    const pageErrors = [];
+    page.on('pageerror', (e) => { if (pageErrors.length < 10) pageErrors.push(String(e?.message ?? e).slice(0, 240)); });
+    const q = new URLSearchParams({ check: '1', ...(take ? { take } : {}), ...(device ? { device } : {}), ...(fps ? { fps: String(fps) } : {}), ...(today !== 'HEAD' ? { today } : {}) });
+    log(`lab: ${server.url}/${game}/ (headless)`);
+    await page.goto(`${server.url}/${game}/?${q}`, { waitUntil: 'load', timeout: 90_000 });
+    await page.waitForFunction(() => Boolean(window.labApp), { timeout: 30_000 });
+    await page.evaluate(() => window.labApp.ready);
+    const renderer = await page.evaluate(() => { try { const g = document.createElement('canvas').getContext('webgl'); const i = g?.getExtension('WEBGL_debug_renderer_info'); return i ? g.getParameter(i.UNMASKED_RENDERER_WEBGL) : null; } catch { return null; } });
+    const first = await page.evaluate(() => window.labApp.data());
+    if (!first.take && !Object.keys(first.tunables?.spec ?? {}).length) log('lab: this game has no take yet (lab.json): the check played a still take with no presses');
+    log(`lab: played ${first.frames} frames in both builds; playing them again from a fresh load`);
+    const second = await page.evaluate(() => window.labApp.rerun());
+    const deterministic = {
+      new: first.new.available ? firstDifference(first.new.frames, second.new.frames) : null,
+      today: first.today.available ? firstDifference(first.today.frames, second.today.frames) : null,
+    };
+    const summary = {
+      ok: true, game, take: first.take, note: first.note, fps: first.fps, frames: first.frames, device: first.device, seed: first.seed, inputs: first.inputs,
+      newBuild: first.newBuild, todayBuild: first.todayBuild, overrides: first.overrides, renderer, software: SOFTWARE_GL.test(String(renderer ?? '')),
+      deterministic, new: summarise(first.new, first), today: summarise(first.today, first), pageErrors,
+    };
+    // Pictures: the lab at the start of each phase, New beside Today.
+    const keys = keyFrames(first.new.phases, first.today.phases, first.frames, Math.max(1, Math.min(12, Number(nKey) || 6)));
+    const shots = [];
+    // Just the panes (their names above, their phases below), not the stage's empty margin.
+    const panes = () => page.evaluate(() => {
+      const rs = [...document.querySelectorAll('.slot')].filter((e) => !e.hidden).map((e) => e.getBoundingClientRect());
+      const x = Math.min(...rs.map((r) => r.left)); const y = Math.min(...rs.map((r) => r.top));
+      return { x: Math.max(0, x - 6), y: Math.max(0, y - 6), width: Math.max(...rs.map((r) => r.right)) - x + 12, height: Math.max(...rs.map((r) => r.bottom)) - y + 12 };
+    });
+    for (const f of keys) {
+      await page.evaluate((x) => window.labApp.seek(x), f);
+      const png = await page.screenshot({ type: 'png', clip: await panes() });
+      const at = (side) => side.phases?.find((p) => f >= p.from && f <= p.to)?.name ?? '';
+      shots.push({ f, png: `data:image/png;base64,${Buffer.from(png).toString('base64')}`, label: `F${f} · ${round(f / first.fps, 2)} s`, newPhase: at(summary.new), todayPhase: summary.today.available ? at(summary.today) : '' });
+    }
+    // The still: the take's busiest moment (the first phase of New, a few frames in), the whole lab page.
+    const stillFrame = summary.new.phases?.[0] ? Math.min(summary.new.phases[0].to, summary.new.phases[0].from + 6) : Math.round(first.frames / 2);
+    await page.evaluate((x) => window.labApp.seek(x), stillFrame);
+    const stillPath = still ?? join(dir, 'still.jpg');
+    await page.screenshot({ path: stillPath, type: 'jpeg', quality: 84, clip: await panes() });
+    await page.screenshot({ path: join(dir, 'page.jpg'), type: 'jpeg', quality: 82 });
+    const sheet = await browser.newPage();
+    await sheet.setViewport({ width: 1600, height: 900, deviceScaleFactor: 1 });
+    await sheet.setContent(sheetHtml(summary, shots), { waitUntil: 'load' });
+    await sheet.screenshot({ path: join(dir, 'sheet.png'), fullPage: true });
+    summary.keyFrames = keys;
+    summary.stillFrame = stillFrame;
+    summary.ms = Date.now() - t0;
+    writeFileSync(join(dir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
+    writeFileSync(join(dir, 'REPORT.md'), reportOf(summary));
+    const rel = (p) => relative(root, p) || p;
+    const latest = {
+      v: 1, at: new Date().toISOString(), game, take: summary.take, frames: summary.frames, fps: summary.fps, device: summary.device,
+      out: rel(dir), report: rel(join(dir, 'REPORT.md')), sheet: rel(join(dir, 'sheet.png')), still: rel(stillPath), page: rel(join(dir, 'page.jpg')),
+      today: summary.todayBuild?.commit?.short ?? null, deterministic,
+      timeline: { new: (summary.new.phases ?? []).map(({ name, from, to }) => ({ name, from, to })), today: summary.today.available ? summary.today.phases.map(({ name, from, to }) => ({ name, from, to })) : null },
+      cost: { new: summary.new.cost ?? null, today: summary.today.available ? summary.today.cost : null },
+    };
+    if (!out) writeFileSync(join(labDir(root, game), 'latest.json'), `${JSON.stringify(latest, null, 2)}\n`);
+    return {
+      ok: true, command: 'lab check', game, take: summary.take, out: rel(dir), report: rel(join(dir, 'REPORT.md')), sheet: rel(join(dir, 'sheet.png')), still: rel(stillPath),
+      frames: summary.frames, fps: summary.fps, deterministic, renderer, software: summary.software,
+      phases: { new: summary.new.phases?.map((p) => `${p.name} ${p.frames}f`) ?? [], today: summary.today.available ? summary.today.phases.map((p) => `${p.name} ${p.frames}f`) : null },
+      timeline: { new: (summary.new.phases ?? []).map(({ name, from, to }) => ({ name, from, to })), today: summary.today.available ? summary.today.phases.map(({ name, from, to }) => ({ name, from, to })) : null },
+      page: rel(join(dir, 'page.jpg')),
+      cost: { new: summary.new.cost ?? null, today: summary.today.available ? summary.today.cost : null },
+      errors: [...(summary.new.errors ?? []), ...(summary.today.errors ?? []), ...pageErrors].slice(0, 6),
+      today: summary.todayBuild?.commit?.short ?? null, todayNote: summary.todayBuild?.none ?? summary.todayBuild?.error ?? null,
+    };
+  } finally {
+    await browser.close().catch(() => {});
+    await server.close().catch(() => {});
+  }
+}
+
+function sheetHtml(summary, shots) {
+  const esc = (s) => String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+  const cells = shots.map((s) => `<figure><img src="${s.png}" alt=""><figcaption><b>${esc(s.label)}</b><span class="n">${esc(s.newPhase || '·')}</span><span class="t">${esc(s.todayPhase || '·')}</span></figcaption></figure>`).join('');
+  return `<!doctype html><html><head><meta charset="utf-8"><style>
+    body { margin: 0; padding: 24px; background: #080b12; color: #e7eaf3; font: 600 13px/1.3 ui-monospace, Menlo, monospace; }
+    h1 { margin: 0 0 4px; font-size: 16px; letter-spacing: .2em; } p { margin: 0 0 18px; color: #8d96b0; }
+    .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
+    figure { margin: 0; } img { width: 100%; display: block; border: 1px solid #232c42; }
+    figcaption { display: flex; gap: 12px; margin-top: 6px; } .n { color: #ffad3b; } .t { color: #7cc4ff; }
+  </style></head><body><h1>GAME LAB · ${esc(summary.game)} · ${esc(summary.take ?? 'no take')}</h1>
+  <p>New (amber) beside Today (blue)${summary.todayBuild?.commit ? `, Today ${esc(summary.todayBuild.commit.short)}` : ''} · ${summary.frames} frames at ${summary.fps} fps · seed ${summary.seed}</p>
+  <div class="grid">${cells}</div></body></html>`;
+}
+