@homie-rocks/studio 0.19.2 → 0.20.0

package/CHANGELOG.md

@@ -17,9 +17,60 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.20.0] - 2026-10-02
+
+**Plugin 0.21.0** · [#30](https://github.com/homie-rocks/homie/pull/30)
+
+A Game Lab: tune how one move of your game feels (a jump, a hit, a dash), your new version beside your last commit,
+frame by frame.
+
+### Added
+
+- Plugin: the `lab` skill. Say "iterate on the jump", "make the hit feel punchier" or "tune the drift". Claude first
+  teaches your game to tell the lab about that move (its phases, the numbers that shape it) without changing how it
+  plays, and commits that. Then it proposes the change as named phases and numbers, shows it to you New beside Today,
+  keeps only what you like, and can record a side-by-side clip to share.
+- `homie-studio lab <game>`: the Game Lab, a page on your own computer. One short take of your game plays in New (your
+  working copy, rebuilt every time a file is saved) beside Today (your last commit), on one clock, with the same
+  presses on the same frames. Slow it to a quarter or a tenth, step a frame at a time, try 30, 15 or 12 frames a
+  second, or switch to a phone-sized screen; the frames are the same frames at any speed.
+- In the lab: a timeline that names each phase of the move, graphs of New against Today, captions, the game's own
+  onion skin and arcs, and its views (close, the whole arena). Its numbers are sliders: move one and New plays it at
+  once, and "Keep in code" writes the ones you like into the game's `tunables.json`. Press REC and play a move to make
+  a new take; both versions get your presses.
+- `homie-studio lab check <game>`: the same take with no window. How long each phase lasts in each version, the peaks
+  of what the game tracks, whether a replay landed on exactly the same frames, a contact sheet and a still.
+  `homie-studio lab set <game> name=value` writes a number into `tunables.json`; `homie-studio lab --stop` stops the lab.
+- Homie for Claude Desktop (`homie-studio mcp`): `game_lab` opens the lab and answers with a card: a still of both
+  versions at the move's busiest moment, their phases side by side, and Open.
+- For your game's code, `@homie-rocks/studio/lab`: `lab.tunables`, `lab.phase`, `lab.track`, `lab.camera`,
+  `lab.overlay`, `lab.stage` (a training dummy for one move) and `lab.random` (dice for sparks and shake). Every call
+  does nothing outside the lab, so the calls stay in your game.
+- Plugin: the perf skill's `try --measure` measures a change you keep for how it feels and says what it costs, without
+  reverting it (`try` on its own reverts anything that is not faster).
+
+### Changed
+
+- Gem Rush's bump lands. The bumped body holds for 70 ms, white and squashed against the hit, then flies stretched
+  along it, eases to a stop 185 px away at any frame rate (it used to slide a different distance at 12 and at 60
+  frames a second, then creep), and wobbles as it settles. Sparks, and a small camera kick for whoever was in it.
+- Ember Vale's strike lands. The slime freezes white when it is hit and its damage pops up, a swipe carries through,
+  the slime is pushed back and wobbles like jelly, and a kill bursts. Your hero steps into each strike, so three
+  strikes in a row still reach.
+- Both starters come ready for the lab: their numbers in `tunables.json` and a take in `lab.json`, which
+  `homie-studio game new` copies with the game. A new studio's AGENTS.md names both files and the lab command.
+
+### Upgrade notes
+
+- A game you made from a starter before 0.20.0 keeps its old feel: the new bump and strike come with a new copy
+  (`homie-studio game new`). To tune a move of your own game, tell Claude "build a Game Lab for <the move>": it adds
+  the lab's calls and a take, and commits that first.
+- Today is your last commit, so commit (or stash) your work in progress before you open the lab. Its builds live in
+  `.studio/lab/`, which git already ignores.
+
 ## [0.19.2] - 2026-10-02
 
-**Plugin 0.20.2** · [#29](https://github.com/homie-rocks/homie/pull/29) · [npm](https://www.npmjs.com/package/@homie-rocks/studio/v/0.19.2)
+**Plugin 0.20.2** · [#29](https://github.com/homie-rocks/homie/pull/29) · [release-2026-10-02-studio-0.19.2](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.19.2)
 
 Release notes: this changelog, on every GitHub release, inside the npm package, and at the top of
 `homie-studio upgrade`.
@@ -846,7 +897,8 @@ The first studio toolkit: a studio in one folder, a multiplayer starter, and dep
   create, and `publish` to the homie.rocks directory.
 - Plugin: the `studio-setup`, `game` and `publish` skills, and the remote Homie MCP.
 
-[0.19.2]: https://www.npmjs.com/package/@homie-rocks/studio/v/0.19.2
+[0.20.0]: https://github.com/homie-rocks/homie/pull/30
+[0.19.2]: https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.19.2
 [0.19.1]: https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.19.1
 [0.19.0]: https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.19.0
 [0.18.2]: https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.18.2

package/README.md

@@ -16,6 +16,7 @@ npx homie-studio game new crown-thief --from gem-rush --name "Crown Thief"
 npx homie-studio dev                                   # the whole site locally
 npx homie-studio check crown-thief --url http://127.0.0.1:8787
 npx homie-studio perf crown-thief --url http://127.0.0.1:8787   # how fast it runs: a computer and an emulated phone, host and replica
+npx homie-studio lab crown-thief                       # the Game Lab: how a move feels, New beside Today, frame by frame
 npx homie-studio deploy --plan                         # what deploy will create, and what it costs; changes nothing
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
@@ -452,6 +453,44 @@ Minified JavaScript gzips about as well as source text, and a bundle with three.
 source in strings, which no minifier touches; the line for such a file says `minified, 19% GLSL shader source in
 strings`, and the JSON's `code` has every measure.
 
+## How it feels: the Game Lab (`homie-studio lab`)
+
+```sh
+npx homie-studio lab crown-thief [--today HEAD|<ref>] [--port 8790]   # http://127.0.0.1:8790/crown-thief/ until --stop
+npx homie-studio lab check crown-thief [--take knock] [--fps 30] [--device phone]   # the same, headless: numbers and pictures
+npx homie-studio lab set crown-thief hitStopMs=80 knockDistance=200                 # values into games/crown-thief/tunables.json
+npx homie-studio lab --stop
+```
+
+A page on this computer for one mechanic at a time (a jump, a hit, a dash, a drift). It plays one short **take**
+(`games/<id>/lab.json`: a few seconds, a seed, the presses) in two builds side by side: **New**, the working tree,
+rebuilt on every save, and **Today**, the last commit (or any ref), built from git's own checkout of it with only the
+game's files (and what its bundle reads from the studio), cached per commit in `.studio/lab/`. Both play on the lab's
+clock: requestAnimationFrame, performance.now(), Date.now(), timers and Math.random() are the lab's in the game's page
+(its harness, `lab/harness.js`, is the page's first script), so frame f is exactly f/fps seconds in both builds, the
+dice are the same, the presses land on the same frames, and netplay's offline host, a round's clock and a knockback's
+timer all slow down, pause and step together. Every replay is compared with the last run, frame by frame: the page
+says "Replays match", or the frame where a build read something the lab does not drive.
+
+The page: New, Today, both side by side or Today ghosted over New; the game's own views (`lab.camera`) and overlays
+(`lab.overlay`: onion skin, arcs, reach); Desk (1280x800) or Phone (390x844); play, pause, a frame back or forward,
+start and end; 1x, ½, ¼ and ⅒ speed (each frame is the same frame at any speed); 60, 30, 15 or 12 frames a second (what
+a slower device draws); a frame counter; a timeline of the phases each build names (`lab.phase`), scrubbable, with each
+frame's motion marked HOLD, MOVE or FAST; graphs of every tracked value (`lab.track`), New against Today, beside the
+body's speed from the port probe and the game's JavaScript per frame; the phase each pane is in, as a caption; the
+game's tunables (`games/<id>/tunables.json`) as sliders, with Today's value marked, that restart New with the new value
+and write kept values back into the file ("Keep in code", one tunable a line); and REC, which records a new take while
+the person plays it in New (both builds get the same presses, on the same frames). A phone opens it too.
+
+A game opts in with `@homie-rocks/studio/lab` (`lab` from `/port` too, `HomiePort.lab` in a static game): every call is
+a no-op outside the lab. Both starters do: Gem Rush's bump (a dummy to bump: `lab.stage`) and Ember Vale's strike (a
+training slime). `lab check` plays the take headless twice per build and writes `.studio/lab/<id>/check-<time>/`:
+summary.json (each phase's frames, each tracked value's peak and where it ends, the JavaScript per frame, errors, the
+replay check), REPORT.md (New against Today), sheet.png (the lab at each phase's start) and still.jpg; and
+`.studio/lab/<id>/latest.json`, the last check in a few fields (`.studio/lab/server.json` says where a running lab is).
+The local MCP's `game_lab` starts the lab and answers with a card. The Homie plugin's `lab` skill has the method:
+instrument and commit first (Today is the game as it is), then change how it feels, and keep what the person likes.
+
 ## Checks on a computer without a GPU
 
 `check`, `port check` and `look` run Chrome headless. On a Mac they use its GPU. On Linux (a Claude Code cloud

package/bin/homie-studio.mjs

@@ -37,6 +37,20 @@
  *                                         (better, worse or the same within the noise: medians, a 95% interval, a rank test,
  *                                          and the guards that must not get worse; runs taken side by side with the same
  *                                          --pair label on both sides are judged as pairs, so a computer's drift cancels)
+ *   homie-studio lab <id> [--port 8790] [--today HEAD|<ref>] [--take <name>]
+ *                                         (the Game Lab, on this computer, until --stop: one take of the game (games/<id>/lab.json)
+ *                                          played in New, the working tree, rebuilt on every save, beside Today, built from git's
+ *                                          checkout of the ref, on one clock with the same seed and presses: slowed to a tenth or
+ *                                          a frame at a time, at 60, 30, 15 or 12 fps, on a computer or a phone; a timeline of the
+ *                                          phases the game names, graphs New against Today, the game's own overlays and views,
+ *                                          sliders that write kept values into games/<id>/tunables.json, and REC for a new take.
+ *                                          The game calls @homie-rocks/studio/lab; the plugin's lab skill has the method)
+ *   homie-studio lab check <id> [--take <name>] [--today <ref>] [--device desk|phone] [--fps 60] [--frames 6] [--out <dir>]
+ *                                         (the same take headless, twice per build: every phase, each tracked value's peak, the
+ *                                          game's JavaScript per frame, whether a replay lands on the same frames, a contact sheet
+ *                                          and a still; .studio/lab/<id>/check-<time>/)
+ *   homie-studio lab set <id> <name>=<value> ...   (values into games/<id>/tunables.json, one tunable a line)
+ *   homie-studio lab --stop               (this studio's Game Lab only, and the checkouts Today was built from)
  *   homie-studio chrome [install] [--fresh]  (which Chrome the checks use; on Linux, `install` fetches Chrome for Testing;
  *                                          --fresh fetches it even when the machine has a Chrome)
  *   homie-studio look [<path>...] [--url <site>] [--shots <dir>] [--only computer,phone,sideways]
@@ -169,6 +183,7 @@ import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
 import { DEFAULT_GOAL, perfCompare, perfRun, perfSizes } from '../lib/perf.mjs';
+import { LAB_PORT, labServe, labSet, labStop } from '../lib/lab.mjs';
 import { R2_COST, lineOf, mediaPlan, r2OverOf, recordUpload, resolveMedia, sizeOf, typeOf } from '../lib/media.mjs';
 import { ensureMigrations, migrationWord, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
@@ -234,6 +249,25 @@ function print(result) {
       for (const m of result.siteSkipped ?? []) lines.push(`  left out: ${m.what}: ${m.why}`);
       if (result.codexes?.length) lines.push(`Game Codex (the owner's private pages; codex link <id> opens one): ${result.codexes.map((x) => `/_studio/codex/${x}/`).join(', ')}`);
       break;
+    case 'lab':
+      lines.push(result.already ? `The Game Lab is running: ${result.url}` : `The Game Lab stopped (it was at ${result.url}).`);
+      break;
+    case 'lab stop':
+      lines.push(result.stopped.length ? 'Stopped this studio\'s Game Lab.' : 'No Game Lab of this studio was running.', ...(result.removed.length ? [`Removed the checkouts Today was built from: ${result.removed.join(', ')}`] : []));
+      break;
+    case 'lab set':
+      lines.push(result.changed.length ? `${result.file}: ${result.changed.map((c) => `${c.name} ${c.from} -> ${c.to}`).join(', ')}` : `${result.file}: nothing changed`);
+      break;
+    case 'lab check': {
+      const det = (x) => (x === null ? 'same frames' : `DIFFERED from frame ${x}`);
+      lines.push(`${result.game}: take "${result.take ?? '(none)'}", ${result.frames} frames at ${result.fps} fps`,
+        `  New:   ${result.phases.new.join(' · ') || 'no phases'}; JavaScript ${result.cost.new?.mean} ms a frame (p95 ${result.cost.new?.p95}); replay: ${det(result.deterministic.new)}`,
+        result.phases.today ? `  Today (${result.today}): ${result.phases.today.join(' · ') || 'no phases'}; JavaScript ${result.cost.today?.mean} ms a frame (p95 ${result.cost.today?.p95}); replay: ${det(result.deterministic.today)}` : `  Today: ${result.todayNote ?? 'none'}`,
+        ...(result.software ? [`  Note: a software renderer (${result.renderer}): pictures are right, the JavaScript numbers are slow`] : []),
+        ...result.errors.map((e) => `  error: ${e}`),
+        `Report: ${result.report}`, `Pictures: ${result.sheet}, ${result.still}`);
+      break;
+    }
     case 'media list':
       for (const kind of ['music', 'videos']) {
         lines.push(`${kind}/manifest.json: ${result[kind].pages.length} page(s)`);
@@ -555,6 +589,7 @@ async function main() {
   if (cmd === 'games') return { ok: true, command: 'games', games: listGames(root).map(({ dir, ...g }) => ({ ...g, dir: relative(root, dir) })) };
   if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log, maps: flags.has('maps') }), 'build');
   if (cmd === 'perf' && sub === 'sizes') return perfSizes(root, positional[2] ?? listGames(root)[0]?.id);
+  if (cmd === 'lab') return labCommand(root, sub);
   if (cmd === 'perf') {
     const game = sub ?? listGames(root)[0]?.id;
     const url = flags.get('url') ?? siteUrl(root);
@@ -662,6 +697,21 @@ async function main() {
   return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
 }
 
+/** `homie-studio lab …` (lib/lab.mjs, lib/lab-check.mjs): the Game Lab of one game. */
+async function labCommand(root, sub) {
+  if (flags.has('stop') || sub === 'stop') return labStop(root);
+  if (sub === 'set') return labSet(root, positional[2], positional.slice(3));
+  if (sub === 'check') {
+    const { labCheck } = await import('../lib/lab-check.mjs');
+    const num = (k, d) => (flags.has(k) ? Number(flags.get(k)) : d);
+    return labCheck(root, positional[2] ?? null, {
+      take: flags.get('take') ?? null, today: String(flags.get('today') ?? 'HEAD'), device: flags.get('device') ?? null, fps: num('fps', null),
+      out: flags.get('out') ? resolve(String(flags.get('out'))) : null, still: flags.get('still') ? resolve(String(flags.get('still'))) : null, frames: num('frames', 6), log,
+    });
+  }
+  return labServe(root, sub ?? null, { port: Number(flags.get('port') ?? LAB_PORT), today: String(flags.get('today') ?? 'HEAD'), take: flags.get('take') ?? null, log });
+}
+
 /** `homie-studio codex …` (lib/codex.mjs): the Game Codex of one game. */
 function codexCommand(root, sub) {
   const games = listGames(root);

package/lab/harness.js

@@ -0,0 +1,371 @@
+/*
+ * The Game Lab's harness (@homie-rocks/studio lab/harness.js): the first script of a game's page when the lab serves
+ * it (/new/ and /today/, `homie-studio lab <game>`), before the game's own. It makes a take replayable:
+ *
+ *   - THE CLOCK. requestAnimationFrame, performance.now(), Date.now() (and new Date()), setTimeout and setInterval run
+ *     on the lab's clock. Frame f happens at exactly f / fps seconds, and only when the lab steps it, so a take plays
+ *     the same at 1x, 1/10 or one frame at a time, and a paused game is paused all the way down (netplay's offline
+ *     host, a round's countdown, a knockback's timer).
+ *   - THE DICE. Math.random() is seeded (the world's dice, the same in both builds); window.__homieLab.random() is a
+ *     second stream for juice (particles, shake), so a build that adds a spark never moves a gem in the other.
+ *   - STORAGE. localStorage and sessionStorage are this take's own, in memory, seeded from the take (a hero at level
+ *     3), so a take never changes the next one.
+ *   - INPUT. A take's keys and pointer presses are dispatched at the start of their frame. While the person records,
+ *     their real presses are held back and dispatched the same way at the next frame (both panes get them at the same
+ *     frame); while a take replays, real presses are ignored. Focus changes never reach the game.
+ *   - WHAT THE GAME SAYS. window.__homieLab is what @homie-rocks/studio/lab calls: tracked values, phases, poses,
+ *     preset views, overlays and tunables, recorded per frame for the lab page to draw.
+ *
+ * The page that frames it (the lab page) drives it through window.__homieLabPane. Opened on its own (no lab around
+ * it) it plays in real time on the same seeded clock. Plain script, no build step: it is served as it is.
+ */
+(function () {
+  'use strict';
+  if (window.__homieLabPane) return;
+
+  var real = {
+    now: performance.now.bind(performance),
+    raf: window.requestAnimationFrame.bind(window),
+    setTimeout: window.setTimeout.bind(window),
+    random: Math.random,
+    Date: Date,
+  };
+
+  /* ------------------------------------------------------------------ config (from the lab page around it) */
+  var pane = /\/today\//.test(location.pathname) ? 'today' : 'new';
+  var cfg = null;
+  try { if (window.parent !== window && window.parent.__homieLabPanes) cfg = window.parent.__homieLabPanes.config(pane); } catch (e) { cfg = null; }
+  var free = !cfg;
+  cfg = cfg || {};
+  var fps = [60, 30, 15, 12].indexOf(Number(cfg.fps)) >= 0 ? Number(cfg.fps) : 60;
+  var step = 1000 / fps;
+  var seed = (Number(cfg.seed) >>> 0) || 1;
+  var epoch = Number.isFinite(cfg.epoch) ? cfg.epoch : Date.UTC(2026, 0, 1);
+  var inputs = Array.isArray(cfg.inputs) ? cfg.inputs.slice().sort(function (a, b) { return (a.at || 0) - (b.at || 0); }) : [];
+  var mode = cfg.mode === 'record' ? 'record' : 'replay';
+  var limit = Number(cfg.frames) > 0 ? Number(cfg.frames) : Infinity;
+
+  /* ------------------------------------------------------------------ the dice */
+  function sfc32(a, b, c, d) {
+    return function () {
+      a >>>= 0; b >>>= 0; c >>>= 0; d >>>= 0;
+      var t = (a + b) | 0; a = b ^ (b >>> 9); b = (c + (c << 3)) | 0; c = (c << 21) | (c >>> 11); d = (d + 1) | 0; t = (t + d) | 0; c = (c + t) | 0;
+      return (t >>> 0) / 4294967296;
+    };
+  }
+  function dice(s) { var r = sfc32(0x9e3779b9, 0x243f6a88, 0xb7e15162, s); for (var i = 0; i < 15; i++) r(); return r; }
+  var worldDice = dice(seed);
+  var fxDice = dice((seed ^ 0x5bd1e995) >>> 0);
+  Math.random = function () { return worldDice(); };
+
+  /* ------------------------------------------------------------------ the clock */
+  var vt = 0; // ms since the page started, on the lab's clock
+  var frame = 0;
+  performance.now = function () { return vt; };
+  var RealDate = real.Date;
+  function LabDate() {
+    var a = Array.prototype.slice.call(arguments);
+    if (!(this instanceof LabDate)) return new RealDate(epoch + vt).toString();
+    return a.length ? new (Function.prototype.bind.apply(RealDate, [null].concat(a)))() : new RealDate(epoch + vt);
+  }
+  LabDate.prototype = RealDate.prototype;
+  LabDate.now = function () { return epoch + vt; };
+  LabDate.parse = RealDate.parse;
+  LabDate.UTC = RealDate.UTC;
+  window.Date = LabDate;
+
+  var rafQ = new Map();
+  var rafId = 0;
+  window.requestAnimationFrame = function (cb) { rafId += 1; rafQ.set(rafId, cb); return rafId; };
+  window.cancelAnimationFrame = function (id) { rafQ.delete(id); };
+
+  var timers = new Map();
+  var timerId = 0;
+  var timerSeq = 0;
+  function addTimer(fn, ms, args, every) {
+    timerId += 1;
+    timers.set(timerId, { at: vt + Math.max(0, Number(ms) || 0), fn: fn, args: args, every: every ? Math.max(1, Number(ms) || 0) : 0, seq: ++timerSeq });
+    return timerId;
+  }
+  window.setTimeout = function (fn, ms) { return addTimer(fn, ms, Array.prototype.slice.call(arguments, 2), false); };
+  window.setInterval = function (fn, ms) { return addTimer(fn, ms, Array.prototype.slice.call(arguments, 2), true); };
+  window.clearTimeout = window.clearInterval = function (id) { timers.delete(id); };
+  function fireTimers(until) {
+    for (var guard = 0; guard < 10000; guard++) {
+      var next = null; var nextId = 0;
+      timers.forEach(function (tm, id) { if (tm.at <= until && (!next || tm.at < next.at || (tm.at === next.at && tm.seq < next.seq))) { next = tm; nextId = id; } });
+      if (!next) return;
+      if (next.at > vt) vt = next.at;
+      if (next.every) { next.at += next.every; next.seq = ++timerSeq; } else timers.delete(nextId);
+      try { if (typeof next.fn === 'function') next.fn.apply(window, next.args); } catch (e) { error(e); }
+    }
+  }
+
+  /* ------------------------------------------------------------------ storage: this take's own */
+  function memStorage(seedItems) {
+    var m = new Map();
+    if (seedItems && typeof seedItems === 'object') Object.keys(seedItems).forEach(function (k) { m.set(String(k), typeof seedItems[k] === 'string' ? seedItems[k] : JSON.stringify(seedItems[k])); });
+    return {
+      getItem: function (k) { k = String(k); return m.has(k) ? m.get(k) : null; },
+      setItem: function (k, v) { m.set(String(k), String(v)); },
+      removeItem: function (k) { m.delete(String(k)); },
+      clear: function () { m.clear(); },
+      key: function (i) { return Array.from(m.keys())[i] || null; },
+      get length() { return m.size; },
+    };
+  }
+  var local = memStorage(cfg.storage);
+  var session = memStorage(null);
+  try { Object.defineProperty(window, 'localStorage', { configurable: true, get: function () { return local; } }); } catch (e) { /* kept */ }
+  try { Object.defineProperty(window, 'sessionStorage', { configurable: true, get: function () { return session; } }); } catch (e) { /* kept */ }
+
+  /* ------------------------------------------------------------------ the display */
+  if (Number(cfg.dpr) > 0) { var dpr = Number(cfg.dpr); try { Object.defineProperty(window, 'devicePixelRatio', { configurable: true, get: function () { return dpr; } }); } catch (e) { /* kept */ } }
+
+  /* ------------------------------------------------------------------ input */
+  var KEYS = ['keydown', 'keyup'];
+  var POINTERS = ['pointerdown', 'pointermove', 'pointerup', 'pointercancel'];
+  var queued = []; // inputs for the next frame (recorded, or forwarded from the other pane)
+  var recorded = [];
+  var nextInput = 0;
+  var captured = new Map(); // pointerId -> element (pointer capture for synthetic pointers)
+  var sp = Element.prototype.setPointerCapture;
+  var rp = Element.prototype.releasePointerCapture;
+  var hp = Element.prototype.hasPointerCapture;
+  Element.prototype.setPointerCapture = function (id) { captured.set(id, this); try { sp.call(this, id); } catch (e) { /* a synthetic pointer */ } };
+  Element.prototype.releasePointerCapture = function (id) { if (captured.get(id) === this) captured.delete(id); try { rp.call(this, id); } catch (e) { /* a synthetic pointer */ } };
+  Element.prototype.hasPointerCapture = function (id) { return captured.get(id) === this || (function (el) { try { return hp.call(el, id); } catch (e) { return false; } })(this); };
+
+  function keyInfo(code) {
+    var known = { ArrowLeft: ['ArrowLeft', 37], ArrowUp: ['ArrowUp', 38], ArrowRight: ['ArrowRight', 39], ArrowDown: ['ArrowDown', 40], Space: [' ', 32], Enter: ['Enter', 13], Escape: ['Escape', 27], ShiftLeft: ['Shift', 16], ShiftRight: ['Shift', 16] };
+    if (known[code]) return known[code];
+    var l = /^Key([A-Z])$/.exec(code); if (l) return [l[1].toLowerCase(), l[1].charCodeAt(0)];
+    var d = /^Digit([0-9])$/.exec(code); if (d) return [d[1], 48 + Number(d[1])];
+    return [code, 0];
+  }
+  function dispatch(ev) {
+    if (ev.type === 'key') {
+      var k = keyInfo(ev.code);
+      var ke = new KeyboardEvent(ev.down ? 'keydown' : 'keyup', { key: k[0], code: ev.code, bubbles: true, cancelable: true, composed: true });
+      try { Object.defineProperty(ke, 'keyCode', { get: function () { return k[1]; } }); Object.defineProperty(ke, 'which', { get: function () { return k[1]; } }); } catch (e) { /* read-only */ }
+      var at = document.activeElement && document.activeElement !== document.documentElement ? document.activeElement : document.body || document;
+      at.dispatchEvent(ke);
+      return;
+    }
+    if (ev.type === 'pointer') {
+      var type = 'pointer' + ev.ev;
+      var target = captured.get(ev.id) || document.elementFromPoint(ev.x, ev.y) || document.body;
+      var pe = new PointerEvent(type, { clientX: ev.x, clientY: ev.y, screenX: ev.x, screenY: ev.y, pointerId: ev.id, pointerType: ev.pt || 'touch', isPrimary: ev.id === (ev.primary || ev.id), buttons: ev.ev === 'up' || ev.ev === 'cancel' ? 0 : 1, button: ev.ev === 'move' ? -1 : 0, bubbles: true, cancelable: true, composed: true, width: 20, height: 20, pressure: ev.ev === 'up' ? 0 : 0.5 });
+      target.dispatchEvent(pe);
+      if (ev.ev === 'up' || ev.ev === 'cancel') captured.delete(ev.id);
+    }
+  }
+  function fromEvent(e) {
+    if (KEYS.indexOf(e.type) >= 0) return { type: 'key', code: e.code, down: e.type === 'keydown' };
+    var ev = e.type.slice(7);
+    return { type: 'pointer', ev: ev, x: Math.round(e.clientX * 10) / 10, y: Math.round(e.clientY * 10) / 10, id: e.pointerId, pt: e.pointerType === 'mouse' ? 'mouse' : e.pointerType || 'touch' };
+  }
+  // Real presses: held back for the next frame while recording (and given to the other pane too), ignored otherwise.
+  function onReal(e) {
+    if (!e.isTrusted) return;
+    if (KEYS.indexOf(e.type) >= 0 && (e.repeat || e.metaKey || e.ctrlKey)) { if (e.repeat) { e.stopImmediatePropagation(); e.preventDefault(); } return; }
+    if (e.target && /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName || '')) return; // typing into the game's own box
+    e.stopImmediatePropagation();
+    if (KEYS.indexOf(e.type) >= 0 || e.type !== 'pointermove') e.preventDefault();
+    if (mode !== 'record' || free) { if (free) dispatchLater(fromEvent(e)); return; }
+    var ev = fromEvent(e);
+    try { window.parent.__homieLabPanes.input(pane, ev); } catch (x) { queue(ev); }
+  }
+  function dispatchLater(ev) { queued.push(ev); }
+  KEYS.concat(POINTERS).forEach(function (t) { window.addEventListener(t, onReal, true); });
+  // Focus coming and going (the person clicking the lab's buttons) is not the game's business.
+  ['blur', 'focus'].forEach(function (t) { window.addEventListener(t, function (e) { if (e.target === window) e.stopImmediatePropagation(); }, true); });
+  document.addEventListener('visibilitychange', function (e) { e.stopImmediatePropagation(); }, true);
+
+  function queue(ev) {
+    var at = Math.round((frame + 1) * step * 1000) / 1000;
+    var row = Object.assign({ at: at }, ev);
+    // A pointer that moved twice before the next frame: only where it ended counts (a take stays small).
+    var last = recorded[recorded.length - 1];
+    if (row.type === 'pointer' && row.ev === 'move' && last && last.at === at && last.type === 'pointer' && last.ev === 'move' && last.id === row.id) {
+      recorded[recorded.length - 1] = row;
+      for (var i = queued.length - 1; i >= 0; i--) if (queued[i] === last) { queued[i] = row; break; }
+      return;
+    }
+    queued.push(row);
+    recorded.push(row);
+  }
+
+  /* ------------------------------------------------------------------ what the game reports */
+  var meta = { units: {}, views: [], overlays: [], tunables: null, used: { track: 0, phase: 0, pose: 0 }, errors: [], held: false };
+  var phaseNow = null;
+  var cur = null;
+  var poses = new Map();
+  var view = typeof cfg.view === 'string' ? cfg.view : null;
+  var overlaysOn = new Set(Array.isArray(cfg.overlays) ? cfg.overlays : []);
+  var live = cfg.tunables && typeof cfg.tunables === 'object' ? Object.assign({}, cfg.tunables) : {};
+  var frames = [];
+  var readyWaiters = [];
+  var state = { scale: Number(cfg.scale) || 1, paused: false };
+
+  function error(e) {
+    var m = String((e && (e.message || e.reason)) || e).slice(0, 240);
+    if (meta.errors.length < 20 && meta.errors.indexOf(m) < 0) meta.errors.push(m);
+  }
+  window.addEventListener('error', function (e) { error(e.error || e.message); });
+  window.addEventListener('unhandledrejection', function (e) { error(e.reason); });
+
+  window.__homieLab = {
+    v: 1,
+    pane: pane,
+    stage: typeof cfg.stage === 'string' && cfg.stage ? cfg.stage.slice(0, 32) : null,
+    get frame() { return frame; },
+    get fps() { return fps; },
+    get scale() { return state.scale; },
+    get paused() { return state.paused; },
+    track: function (name, value, unit) {
+      meta.used.track += 1;
+      var v = Number(value);
+      if (cur) cur.tr[String(name).slice(0, 32)] = Number.isFinite(v) ? Math.round(v * 1000) / 1000 : null;
+      if (unit && !meta.units[name]) meta.units[name] = String(unit).slice(0, 12);
+      else if (!(name in meta.units)) meta.units[name] = '';
+    },
+    phase: function (name, note) {
+      meta.used.phase += 1;
+      phaseNow = name ? [String(name).slice(0, 24), note ? String(note).slice(0, 90) : ''] : null;
+      if (cur) cur.ph = phaseNow;
+    },
+    pose: function (name, value) {
+      meta.used.pose += 1;
+      var ring = poses.get(name);
+      if (!ring) { ring = []; poses.set(name, ring); }
+      var copy = {};
+      if (value && typeof value === 'object') Object.keys(value).forEach(function (k) { copy[k] = value[k]; });
+      if (ring.length && ring[ring.length - 1].f === frame) ring[ring.length - 1].v = copy; else ring.push({ f: frame, v: copy });
+      if (ring.length > 720) ring.shift();
+    },
+    past: function (name, count, every) {
+      var ring = poses.get(name) || [];
+      var out = [];
+      var stride = Math.max(1, Number(every) || 1);
+      var want = Math.max(0, Math.min(240, Number(count) || 8));
+      for (var i = ring.length - 1; i >= 0 && out.length < want; i--) {
+        var r = ring[i];
+        if (r.f >= frame) continue;
+        if ((frame - r.f) % stride === 0) out.push(r.v);
+      }
+      return out;
+    },
+    views: function (names) { meta.views = names.map(String).slice(0, 8); },
+    view: function () { return view; },
+    overlays: function (names) { meta.overlays = names.map(String).slice(0, 12); },
+    overlay: function (name) { return overlaysOn.has(name); },
+    tunables: function (spec) { meta.tunables = spec; return live; },
+    random: function () { return fxDice(); },
+    hold: function () { meta.held = true; },
+    ready: function () { meta.held = false; readyWaiters.splice(0).forEach(function (r) { r(); }); },
+  };
+
+  /* ------------------------------------------------------------------ one frame */
+  function hash(s) { var h = 2166136261; for (var i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619); } return (h >>> 0).toString(36); }
+  function selfAt() {
+    try {
+      var p = window.__homiePort;
+      if (!p) return null;
+      var rows = p.rows(vt);
+      var r = rows[rows.length - 1];
+      return r && Number.isFinite(r[1]) ? [Math.round(r[1] * 100) / 100, Math.round(r[2] * 100) / 100] : null;
+    } catch (e) { return null; }
+  }
+  function runFrame() {
+    var target = (frame + 1) * step;
+    fireTimers(target);
+    vt = target;
+    frame += 1;
+    cur = { f: frame, t: Math.round(vt * 1000) / 1000, tr: {}, ph: phaseNow, ms: 0, sig: '' };
+    // Half a millisecond of slack: a take's times are written to 0.1 ms, and frames are at least 16.7 ms apart.
+    while (nextInput < inputs.length && (inputs[nextInput].at || 0) <= vt + 0.5) { try { dispatch(inputs[nextInput]); } catch (e) { error(e); } nextInput += 1; }
+    var now = queued.splice(0);
+    for (var i = 0; i < now.length; i++) { try { dispatch(now[i]); } catch (e) { error(e); } }
+    var q = rafQ;
+    rafQ = new Map();
+    var t0 = real.now();
+    q.forEach(function (cb) { try { cb(vt); } catch (e) { error(e); } });
+    cur.ms = Math.round((real.now() - t0) * 1000) / 1000;
+    cur.ph = phaseNow;
+    var me = selfAt();
+    if (me) cur.me = me;
+    cur.sig = hash(JSON.stringify([cur.tr, cur.ph, me]));
+    frames.push(cur);
+    var done = cur;
+    cur = null;
+    return done;
+  }
+
+  var channel = new MessageChannel();
+  var waiting = [];
+  channel.port1.onmessage = function () { var w = waiting.shift(); if (w) w(); };
+  function yieldTask() { return new Promise(function (r) { waiting.push(r); channel.port2.postMessage(0); }); }
+
+  var loaded = new Promise(function (resolve) {
+    function go() {
+      var fonts = document.fonts && document.fonts.ready ? document.fonts.ready.catch(function () {}) : Promise.resolve();
+      fonts.then(function () { return yieldTask(); }).then(function () {
+        if (!meta.held) resolve();
+        else readyWaiters.push(resolve);
+      });
+    }
+    if (document.readyState === 'complete') go(); else window.addEventListener('load', go, { once: true });
+  });
+
+  var running = false;
+  window.__homieLabPane = {
+    v: 1,
+    pane: pane,
+    ready: loaded,
+    get frame() { return frame; },
+    get t() { return vt; },
+    get fps() { return fps; },
+    frames: frames,
+    recorded: recorded,
+    /** What the game said about itself: units of its tracks, its views, overlays and tunables, errors. */
+    meta: function () { return { units: meta.units, views: meta.views, overlays: meta.overlays, tunables: meta.tunables, instrumented: meta.used.track + meta.used.phase + meta.used.pose > 0, used: meta.used, errors: meta.errors.slice() }; },
+    /** Run `n` frames, a task apart (promises settle between frames, as in a browser). */
+    run: function (n) {
+      if (running) return Promise.resolve(frame);
+      running = true;
+      var left = Math.max(0, Math.min(Number(n) || 0, limit - frame));
+      return loaded.then(function loop() {
+        if (left <= 0) { running = false; return frame; }
+        left -= 1;
+        runFrame();
+        return left > 0 ? yieldTask().then(loop) : (running = false, frame);
+      });
+    },
+    /** A press for the next frame (the person's, forwarded by the lab page to both panes). */
+    input: function (ev) { queue(ev); },
+    set: function (o) {
+      if (!o) return;
+      if ('view' in o) view = o.view;
+      if (o.overlays) Object.keys(o.overlays).forEach(function (k) { if (o.overlays[k]) overlaysOn.add(k); else overlaysOn.delete(k); });
+      if (o.tunables) Object.keys(o.tunables).forEach(function (k) { live[k] = o.tunables[k]; });
+      if (o.mode === 'record' || o.mode === 'replay') mode = o.mode;
+      if (Number(o.scale) > 0) state.scale = Number(o.scale);
+      if (typeof o.paused === 'boolean') state.paused = o.paused;
+    },
+    get mode() { return mode; },
+    /** The first canvas's picture now (a still for the lab's sheet). */
+    still: function (type, quality) {
+      var c = document.querySelector('canvas');
+      try { return c ? c.toDataURL(type || 'image/jpeg', quality || 0.82) : null; } catch (e) { return null; }
+    },
+  };
+
+  // On its own (no lab around it): real time, one lab frame per screen frame, on the same seeded clock.
+  if (free) {
+    loaded.then(function () {
+      var tick = function () { runFrame(); if (frames.length > 1200) frames.splice(0, frames.length - 1200); real.raf(tick); };
+      real.raf(tick);
+    });
+  }
+})();