@homie-rocks/studio 0.19.2 → 0.21.0

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);
+    });
+  }
+})();

package/lab/lab.ts

@@ -0,0 +1,180 @@
+/*
+ * @homie-rocks/studio/lab — a game opts into the Game Lab (`homie-studio lab <game>`) with a few calls. The lab plays
+ * the same take in two builds side by side, New (the working tree) and Today (the last commit), on one clock, with the
+ * same seed and the same presses, and draws what these calls report: a timeline of phases, graphs of tracked values,
+ * the game's own overlays, preset views and live sliders.
+ *
+ * Outside the lab every call is a no-op (one check of a constant), so the calls stay in the game for good and cost a
+ * player nothing. The lab's clock, dice and inputs are installed in the game's page before its first script (the
+ * lab's harness, lab/harness.js): requestAnimationFrame, performance.now(), Date.now(), timers and Math.random() all
+ * run on the lab's clock there, so netplay's offline host, a round's countdown and a knockback's timer all slow down,
+ * pause and step together.
+ *
+ *   import { lab } from '@homie-rocks/studio/lab';
+ *   import tuning from '../tunables.json';
+ *
+ *   const T = lab.tunables(tuning);                 // T.knockSpeed: the file's value; in the lab, the slider's
+ *   const view = lab.camera({ game: null, close: { zoom: 2.4 } });
+ *   lab.overlay('trail', (ctx) => { for (const p of lab.past('me', 30)) dot(ctx, p.x, p.y); });
+ *
+ *   function frame(t: number): void {
+ *     const dt = lab.time.dt(t, 0.05);              // seconds since the last frame, at most 0.05
+ *     ...
+ *     lab.track('speed', Math.hypot(vx, vy), 'px/s');
+ *     lab.phase(knocked ? 'LAUNCH' : null, 'Leaves fast, eases out');
+ *     lab.pose('me', { x, y });
+ *     ...in the world's transform: lab.draw(ctx);
+ *   }
+ *
+ * tunables.json (next to game.json): { "knockSpeed": { "value": 950, "min": 300, "max": 2000, "step": 10,
+ * "unit": "px/s", "group": "Knock", "note": "How fast a bumped body leaves" }, ... }. A slider the person keeps is
+ * written back into that file by the lab, so a kept change is code.
+ */
+
+/** One tunable in tunables.json: its value and the slider around it. A bare number is a value with no range. */
+export interface TunableSpec {
+  value: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  group?: string;
+  note?: string;
+}
+export type TunableFile = Record<string, TunableSpec | number>;
+export type Tuned<S extends TunableFile> = { readonly [K in keyof S]: number };
+
+/** What the lab's harness puts on the page (window.__homieLab) before the game's first script. */
+interface LabHost {
+  v: 1;
+  pane: 'new' | 'today';
+  stage: string | null;
+  frame: number;
+  fps: number;
+  scale: number;
+  paused: boolean;
+  track(name: string, value: number, unit?: string): void;
+  phase(name: string | null, note?: string): void;
+  pose(name: string, value: Record<string, unknown>): void;
+  past(name: string, count: number, every: number): Record<string, unknown>[];
+  views(names: string[]): void;
+  view(): string | null;
+  overlays(names: string[]): void;
+  overlay(name: string): boolean;
+  tunables(spec: TunableFile): Record<string, number>;
+  random(): number;
+  hold(): void;
+  ready(): void;
+}
+
+const host: LabHost | null = typeof window !== 'undefined' ? ((window as unknown as { __homieLab?: LabHost }).__homieLab ?? null) : null;
+const ON = Boolean(host && host.v === 1);
+
+type Draw = (ctx: unknown, ...rest: unknown[]) => void;
+const drawers = new Map<string, Draw>();
+let lastT = -1;
+
+const valueOf = (s: TunableSpec | number): number => (typeof s === 'number' ? s : Number(s?.value));
+
+export const lab = {
+  /** True when this page is a pane of the Game Lab. */
+  on: ON,
+
+  time: {
+    /**
+     * Seconds since the previous frame, at most `max` (a tab that slept does not teleport the world). Call it once a
+     * frame with requestAnimationFrame's time. In the lab that time is the lab's clock: every frame is exactly one step
+     * of its frame rate (60, 30, 15 or 12 a second), so a take plays the same every time, at any speed.
+     */
+    dt(t: number, max = 0.05): number {
+      const d = lastT < 0 ? 0 : Math.max(0, (t - lastT) / 1000);
+      lastT = t;
+      return Math.min(max, d);
+    },
+    /** The time now in ms (performance.now(); the lab's clock in the lab). */
+    now(): number { return performance.now(); },
+    /** The lab's frame number (1 is the take's first frame); 0 outside the lab. */
+    get frame(): number { return host?.frame ?? 0; },
+    /** Frames a second the lab runs the game at (60 outside the lab). */
+    get fps(): number { return host?.fps ?? 60; },
+    /** How fast the lab plays (1, 0.5, 0.25, 0.1): the game never needs it, a frame is a frame at any speed. */
+    get scale(): number { return host?.scale ?? 1; },
+    get paused(): boolean { return host?.paused ?? false; },
+  },
+
+  /**
+   * The take's stage (lab.json "stage"), or null: a scene the game sets up for one mechanic, the way a fighting game's
+   * training mode stands a dummy in front of you. Read it where the round starts; it is null outside the lab, so a
+   * stage never reaches a player. Check the mechanic in a take without a stage too: real play is the test.
+   */
+  get stage(): string | null { return host?.stage ?? null; },
+
+  /** A number to graph this frame (New against Today). `unit` names its axis the first time. */
+  track(name: string, value: number, unit?: string): void { if (ON) host!.track(name, value, unit); },
+
+  /**
+   * The phase the mechanic is in from now on: a short name in capitals (COIL, RISE, HANG, LAUNCH, SETTLE) and a note
+   * that says what it is for ("Overlap on the way out"). null: none. It lasts until the next call, so call it when the
+   * phase changes, or every frame with what it is.
+   */
+  phase(name: string | null, note?: string): void { if (ON) host!.phase(name, note); },
+
+  /** A small picture of something this frame ({ x, y, angle, sx, sy }): what `past` returns to an overlay. */
+  pose(name: string, value: Record<string, unknown>): void { if (ON) host!.pose(name, value); },
+
+  /** The last `count` poses of `name`, newest first, one every `every` frames (onion skins, arcs, trails). */
+  past<P extends Record<string, unknown> = Record<string, number>>(name: string, count = 8, every = 1): P[] {
+    return ON ? (host!.past(name, count, every) as P[]) : [];
+  },
+
+  /**
+   * Preset views the lab offers as buttons (Side, Front, Top, Orbit in a 3D game; Close, Arena in a flat one). Returns
+   * the active preset's value each frame: the first preset outside the lab (give it null: the game's own camera).
+   */
+  camera<V>(presets: Record<string, V>): () => V | null {
+    const names = Object.keys(presets);
+    const first = names.length ? (presets[names[0] as string] as V) : null;
+    if (!ON) return () => first;
+    host!.views(names);
+    return () => { const v = host!.view(); return v !== null && Object.hasOwn(presets, v) ? (presets[v] as V) : first; };
+  },
+
+  /** An overlay the lab can switch on (onion skin, arcs, smears, hit boxes): drawn by the game's own renderer. */
+  overlay(name: string, draw: Draw): void {
+    if (!ON) return;
+    drawers.set(name, draw);
+    host!.overlays([...drawers.keys()]);
+  },
+
+  /** Draw every overlay the lab has on, in whatever transform the game is in (call it in world space). */
+  draw(ctx: unknown, ...rest: unknown[]): void {
+    if (!ON) return;
+    for (const [name, fn] of drawers) if (host!.overlay(name)) { try { fn(ctx, ...rest); } catch { /* an overlay never breaks the frame */ } }
+  },
+
+  /**
+   * The game's tunables (tunables.json): an object of numbers by name. Outside the lab, the file's values. In the lab,
+   * the values the sliders hold now (a take restarts when one moves); the lab writes kept values back into the file.
+   */
+  tunables<S extends TunableFile>(spec: S): Tuned<S> {
+    const base: Record<string, number> = {};
+    for (const [k, s] of Object.entries(spec)) base[k] = valueOf(s);
+    if (!ON) return Object.freeze(base) as Tuned<S>;
+    const live = host!.tunables(spec);
+    const out = {} as Record<string, number>;
+    for (const k of Object.keys(base)) Object.defineProperty(out, k, { enumerable: true, get: () => (Number.isFinite(live[k]) ? (live[k] as number) : (base[k] as number)) });
+    return out as Tuned<S>;
+  },
+
+  /**
+   * Dice for juice (particles, shake, sparks): its own stream in the lab, so a build that adds a particle never moves
+   * a gem or a bot in the other build (Math.random() is the world's dice, the same in both). Math.random() outside.
+   */
+  random(): number { return ON ? host!.random() : Math.random(); },
+
+  /** A game that loads assets after its page has loaded: hold() early, ready() when it can play. */
+  hold(): void { if (ON) host!.hold(); },
+  ready(): void { if (ON) host!.ready(); },
+};
+
+export default lab;

package/lab/page/index.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="color-scheme" content="dark">
+<title>Game Lab</title>
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1l7 7-7 7-7-7z' fill='%23ffad3b'/%3E%3C/svg%3E">
+<link rel="stylesheet" href="/_lab/lab.css">
+</head>
+<body>
+<header class="bar top">
+  <div class="brand"><span class="mark" aria-hidden="true"></span><span class="word">GAME LAB</span></div>
+  <div class="title"><b id="game-name">…</b><span class="sep">/</span><span id="take-name">…</span></div>
+  <div class="status" id="status" aria-live="polite"></div>
+</header>
+
+<nav class="bar tools" aria-label="View">
+  <div class="group" role="group" aria-label="Which build" id="layout"></div>
+  <div class="group" role="group" aria-label="Views" id="views"></div>
+  <div class="group" role="group" aria-label="Device" id="device"></div>
+  <div class="group" role="group" aria-label="Overlays" id="overlays"></div>
+  <div class="group grow"></div>
+  <div class="group" role="group" aria-label="Take">
+    <label class="select"><span class="sr">Take</span><select id="take-pick"></select></label>
+    <button type="button" id="rec" class="rec" title="Record a take: play it in NEW">● REC</button>
+  </div>
+</nav>
+
+<main class="work">
+  <section class="stage" id="stage" aria-label="New and Today side by side">
+    <div class="slot" data-pane="new">
+      <div class="frame"><iframe title="New: the working tree" id="pane-new" tabindex="-1"></iframe></div>
+      <div class="tag new"><span>NEW</span><small id="new-sub"></small></div>
+      <div class="caption" id="cap-new"></div>
+      <div class="veil" id="veil-new" hidden></div>
+    </div>
+    <div class="slot" data-pane="today">
+      <div class="frame"><iframe title="Today: the last commit" id="pane-today" tabindex="-1"></iframe></div>
+      <div class="tag today"><span>TODAY</span><small id="today-sub"></small></div>
+      <div class="caption" id="cap-today"></div>
+      <div class="veil" id="veil-today" hidden></div>
+    </div>
+    <div class="recbar" id="recbar" hidden><span class="dot"></span><span id="rec-text">Recording: play in NEW</span><button type="button" id="rec-stop">Stop</button></div>
+  </section>
+
+  <aside class="tune" id="tune" aria-label="Tunables">
+    <div class="tune-head"><b>TUNABLES</b><small id="tune-file"></small></div>
+    <div class="tune-list" id="tune-list"></div>
+    <div class="tune-foot">
+      <button type="button" id="keep" class="primary" disabled>Keep in code</button>
+      <button type="button" id="undo" disabled>Undo</button>
+    </div>
+  </aside>
+
+  <section class="deck" aria-label="Timeline">
+    <div class="transport">
+      <div class="group" role="group" aria-label="Playback">
+        <button type="button" id="to-start" title="Start (Home)">|◀</button>
+        <button type="button" id="back" title="Back a frame (←)">◀</button>
+        <button type="button" id="play" class="wide" title="Play or pause (Space)">Pause</button>
+        <button type="button" id="fwd" title="Forward a frame (→)">▶</button>
+        <button type="button" id="to-end" title="End (End)">▶|</button>
+      </div>
+      <div class="group" role="group" aria-label="Speed" id="speeds"></div>
+      <div class="group" role="group" aria-label="Frames a second" id="fpses"></div>
+      <div class="group" role="group" aria-label="Loop"><button type="button" id="loop" class="on" title="Play the take again from the start">Loop</button></div>
+      <div class="counter" id="counter">F 0 / 0 · 0.00 s</div>
+    </div>
+    <div class="legend" id="legend"></div>
+    <div class="lines">
+      <canvas id="timeline" aria-label="Phases of the take, New above Today: click or drag to move the playhead"></canvas>
+    </div>
+    <div class="tracks" id="tracks" role="tablist" aria-label="Graphs"></div>
+    <div class="lines">
+      <canvas id="graph" aria-label="The chosen value over the take, New against Today"></canvas>
+    </div>
+    <p class="hint" id="hint"></p>
+  </section>
+</main>
+<script type="module" src="/_lab/page.js"></script>
+</body>
+</html>