@homie-rocks/studio 0.19.2 → 0.20.0

package/lib/scaffold.mjs

@@ -104,7 +104,7 @@ directory lists its games; homie.rocks does not host them.
 
 | Path | What it is |
 | --- | --- |
-| \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`. |
+| \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`; and, when it has them, \`tunables.json\` (the numbers that shape how it feels: the Game Lab's sliders, kept values written back) and \`lab.json\` (the Game Lab's takes). |
 | \`music/\`, \`videos/\` | Songs, scores, loops; trailers, music videos, cutscenes. \`manifest.json\` lists each one (\`node_modules/@homie-rocks/studio/media/MEDIA.md\`); a published entry gets a page at \`/music/<slug>/\` or \`/videos/<slug>/\`. Without storage the site serves each file itself (up to 25 MiB). Once the studio has storage (see below), its big media (over 1 MiB, or left out of git) lives in its own R2: every deploy uploads it, checks it by SHA-256 and serves it from R2 at the same address. Large files never go into git. The Homie plugin's \`music\` and \`video\` skills make them. |
 | \`posts/\` | The studio's news and drops: one markdown file each (\`posts/2026-09-30-we-are-live.md\`: \`title:\`, \`date:\`, \`summary:\`, and \`game:\` / \`song:\` / \`video:\` to link one). They are the site's Posts, with Atom and JSON feeds. |
 | \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`) and its D1 migrations. |
@@ -140,6 +140,12 @@ studio's pinned copy, never a registry lookup of the bare name.
   per frame, time to playable, what it downloads, the heap, netplay messages a second (files under \`.perf/\`). The
   Homie plugin's \`perf\` skill runs the whole loop: one change at a time, kept only when it is better beyond the noise
   and \`check\` still passes, and a report in \`perf/<id>/\`.
+- \`npx --no-install homie-studio lab <id>\` — the Game Lab, on this computer (run it in the background; stop it with
+  \`lab --stop\`): one take of a move (\`games/<id>/lab.json\`) played in the working tree beside the last commit, on
+  one clock, slowed down or a frame at a time, with the phases, graphs and tunables the game reports
+  (\`@homie-rocks/studio/lab\`). \`lab check <id>\` plays it headless and writes the numbers and a contact sheet. The
+  Homie plugin's \`lab\` skill runs the whole loop: instrument and commit first, change how it feels, keep what the
+  person likes.
 - \`npx --no-install homie-studio deploy --plan\` — says what deploy will create on Cloudflare and what it
   costs, and changes nothing. Tell the person before the first deploy.
 - \`npm run deploy\` — the site on this studio's Cloudflare: one Worker, one D1 database, two

package/lib/studio.mjs

@@ -103,6 +103,18 @@ export function starters() {
   });
 }
 
+/**
+ * A game's Game Lab takes (lab.json) seed its saves by the game's id (`homie-saves.local.<id>`, saves/saves.ts): a copy
+ * under a new id renames them, so a take's saved hero is still found.
+ */
+function renameTakeSaves(dir, from, id) {
+  const file = join(dir, 'lab.json');
+  if (!existsSync(file) || from === id) return;
+  const text = readFileSync(file, 'utf8');
+  const next = text.split(`"homie-saves.local.${from}"`).join(`"homie-saves.local.${id}"`);
+  if (next !== text) writeFileSync(file, next);
+}
+
 /** `homie-studio game new <id> --from <starter> --name "<Name>"`: a starter copied in as this studio's own game. */
 export function newGame(root, id, { from = 'gem-rush', name } = {}) {
   if (!GAME_ID.test(String(id ?? '')) || RESERVED_IDS.has(id)) throw new Error(`a game id is lowercase letters, digits and hyphens, up to 40, and not one of ${[...RESERVED_IDS].join(', ')} (got ${JSON.stringify(id)})`);
@@ -121,6 +133,7 @@ export function newGame(root, id, { from = 'gem-rush', name } = {}) {
   writeFileSync(join(dest, 'game.json'), `${JSON.stringify(meta, null, 2)}\n`);
   const main = join(dest, meta.entry ?? 'src/main.ts');
   if (existsSync(main)) writeFileSync(main, readFileSync(main, 'utf8').replace(new RegExp(`game: '${from}'`, 'g'), `game: '${id}'`));
+  renameTakeSaves(dest, from, id);
   const html = join(dest, 'index.html');
   if (name && existsSync(html)) writeFileSync(html, readFileSync(html, 'utf8').replace(/<title>[^<]*<\/title>/, `<title>${String(name).replace(/[<&]/g, '')}</title>`));
   return { ok: true, command: 'game new', id, from, dir: dest, files: readdirSync(dest, { recursive: true }).map(String) };
@@ -174,5 +187,6 @@ export async function remixGame(root, source, id, { name } = {}) {
   writeFileSync(join(dest, 'game.json'), `${JSON.stringify(meta, null, 2)}\n`);
   const main = join(dest, meta.entry ?? 'src/main.ts');
   if (existsSync(main) && from) writeFileSync(main, readFileSync(main, 'utf8').replace(new RegExp(`game: '${from}'`, 'g'), `game: '${id}'`));
+  if (from) renameTakeSaves(dest, from, id);
   return { ok: true, command: 'game remix', id, from: String(url), credit: meta.remixOf.credit, page: meta.remixOf.page, license, files: wrote };
 }

package/lib/template-history.json

@@ -850,6 +850,43 @@
      }
     }
    }
+  },
+  "0.20.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "43a4c5bf07db36f9",
+     "## Commands (all through the pinned CLI in node_modules)": "d80ec56e4b4fc4c6",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Servers and AI seats": "0a332b07e22d3fce",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "b35df2c19cd4b534"
+      }
+     }
+    }
+   }
   }
  }
 }

package/mcp/ui/lab.js

@@ -0,0 +1,67 @@
+/* The Game Lab card: one take of a game's mechanic, New (the working tree) beside Today (the last commit). A still of
+ * both at the take's busiest moment, the phases of each as a timing strip, whether replays match, the game's
+ * JavaScript per frame, and Open (the lab runs on this computer). */
+(function () {
+  var C = Card;
+  var COLOURS = ['#a374ff', '#17c3b2', '#f5a524', '#ff6fb5', '#8bd346', '#4dd2ff', '#ffd84a', '#e58cff'];
+  function strip(rows, frames) {
+    // rows: { label, phases: [{ name, from, to }] }: blocks at their frames on the take's own axis; colours by name, shared.
+    var names = [];
+    rows.forEach(function (r) { (r.phases || []).forEach(function (p) { if (names.indexOf(p.name) < 0) names.push(p.name); }); });
+    var box = C.el('div');
+    box.style.cssText = 'display:grid;gap:6px;margin:12px 0 4px';
+    rows.forEach(function (r) {
+      var line = C.el('div');
+      line.style.cssText = 'display:grid;grid-template-columns:52px 1fr;gap:8px;align-items:center';
+      var label = C.el('span', '', r.label);
+      label.style.cssText = 'font:700 11px/1 var(--f-mono);letter-spacing:.08em;color:' + r.colour;
+      var bar = C.el('div');
+      bar.style.cssText = 'position:relative;height:20px;border-radius:4px;overflow:hidden;background:var(--c-bg2)';
+      (r.phases || []).forEach(function (p) {
+        var b = C.el('span', '', p.name);
+        var colour = COLOURS[names.indexOf(p.name) % COLOURS.length];
+        b.title = p.name + ': frames ' + p.from + ' to ' + p.to;
+        b.style.cssText = 'position:absolute;top:0;bottom:0;left:' + ((p.from - 1) / frames) * 100 + '%;width:calc(' + ((p.to - p.from + 1) / frames) * 100 + '% - 1px);background:' + colour + ';color:#0b0d14;font:700 10px/20px var(--f-mono);padding:0 4px;white-space:nowrap;overflow:hidden;text-overflow:clip';
+        bar.appendChild(b);
+      });
+      if (!(r.phases || []).length) { var e = C.el('span', 'fine', r.empty || 'no phases'); e.style.cssText = 'margin:0;line-height:20px;padding:0 8px'; bar.appendChild(e); }
+      line.appendChild(label); line.appendChild(bar);
+      box.appendChild(line);
+    });
+    return box;
+  }
+  function render(sc) {
+    var card = C.el('main', 'card');
+    var det = sc.deterministic || {};
+    var same = det.new === null && (det.today === null || det.today === undefined);
+    var head = sc.running ? C.pill('Checking', 'live', true) : same ? C.pill('Replays match', 'ok') : C.pill('Replays differ', 'bad');
+    C.add(card, C.top('Game Lab', C.add(C.el('div', 'actions'), head, C.fullscreenButton())), C.el('h1', '', (sc.name || sc.game) + (sc.take ? ' · ' + sc.take : '')),
+      C.el('p', 'sub', sc.running ? 'The lab is open on this computer; its first check is still running.' : 'New (the working tree) beside Today' + (sc.today ? ' (' + sc.today + ')' : '') + ' · ' + sc.frames + ' frames at ' + sc.fps + ' fps'));
+    if (sc.still) {
+      var box = C.el('div', 'preview');
+      var pic = C.img(sc.still, 'New beside Today at the take\'s busiest moment');
+      if (pic) { pic.style.maxHeight = 'none'; pic.style.objectFit = 'contain'; box.appendChild(pic); }
+      card.appendChild(box);
+    }
+    if (sc.timeline && sc.frames) {
+      card.appendChild(strip([
+        { label: 'NEW', colour: '#e08a12', phases: sc.timeline.new },
+        { label: 'TODAY', colour: '#2f8fd8', phases: sc.timeline.today || [], empty: sc.todayNote || 'no phases' },
+      ], sc.frames));
+      card.appendChild(C.el('p', 'fine', 'Phases on the take\'s ' + sc.frames + ' frames (' + (sc.frames / sc.fps).toFixed(2) + ' s).'));
+    }
+    if (sc.cost && sc.cost.new) {
+      card.appendChild(C.el('p', 'fine', 'The game\'s JavaScript a frame, on average: New ' + sc.cost.new.mean + ' ms (p95 ' + sc.cost.new.p95 + ')' + (sc.cost.today ? ', Today ' + sc.cost.today.mean + ' ms (p95 ' + sc.cost.today.p95 + ')' : '') + '.'));
+    }
+    if (!same && !sc.running) card.appendChild(C.el('p', 'note bad', 'The same build played the take differently' + (det.new !== null ? ' (New from frame ' + det.new + ')' : '') + (det.today ? ' (Today from frame ' + det.today + ')' : '') + ': something in the game reads a clock or dice the lab does not drive.'));
+    (sc.errors || []).slice(0, 3).forEach(function (e) { card.appendChild(C.el('p', 'note bad', e)); });
+    var foot = C.el('div', 'foot');
+    foot.appendChild(C.el('span', 'when', 'Runs on this computer'));
+    var acts = C.el('div', 'actions');
+    if (sc.url) acts.appendChild(C.btn('Open the lab', '', function () { C.open(sc.url); C.tell('lab-open', 'The person opened the Game Lab for ' + (sc.name || sc.game) + ' from the card.'); }));
+    foot.appendChild(acts);
+    card.appendChild(foot);
+    return card;
+  }
+  C.start({ kind: 'lab', label: 'Game Lab', fullscreen: true, render: render, poll: null });
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -34,6 +34,10 @@
       "types": "./agents/agents.ts",
       "default": "./agents/agents.ts"
     },
+    "./lab": {
+      "types": "./lab/lab.ts",
+      "default": "./lab/lab.ts"
+    },
     "./worker": "./worker/index.mjs",
     "./package.json": "./package.json"
   },
@@ -46,6 +50,7 @@
     "mcp/",
     "saves/",
     "agents/",
+    "lab/",
     "starters/",
     "media/",
     "site/",

package/port/index.ts

@@ -18,6 +18,7 @@
  *   jitter, engages, standoff
  *                the dial for the rest of a bot's decisions (port/skill.ts)
  *   createSaves  player accounts and cloud saves (a character that lasts days, on every device; saves/SAVES.md)
+ *   lab          the Game Lab's calls (@homie-rocks/studio/lab): tracks, phases, tunables, overlays, views
  * and everything from @homie-rocks/studio/netplay.
  */
 import './early';
@@ -35,4 +36,5 @@ export { createRoom, type Room, type RoomOptions, type BodyBase, type RoomSnap,
 export { createHud, type HudOptions } from './hud';
 export { BotBrain, brainOf, seek, flee, wanderer, nearest, rubberBand, protectedNewcomer, type V2 } from './bots';
 export { jitter, engages, standoff } from './skill';
+export { lab, type TunableSpec, type TunableFile, type Tuned } from '../lab/lab';
 export { createSaves, SAVES_VERSION, type Saves, type SavesOptions, type Player, type SaveEntry, type SetResult, type Memorial, type SavesStatus, type Conflict } from '../saves/saves';

package/starters/ember-vale/lab.json

@@ -0,0 +1,22 @@
+{
+  "v": 1,
+  "default": "strike",
+  "takes": {
+    "strike": {
+      "note": "Three strikes on a big training slime",
+      "seconds": 2.6,
+      "seed": 11,
+      "stage": "dummy",
+      "device": "desk",
+      "fps": 60,
+      "view": "close",
+      "track": "slime squash",
+      "storage": { "homie-saves.local.ember-vale": { "saves": { "hero": { "v": { "v": 1, "name": "Wren", "level": 1, "xp": 0, "gold": 0, "hardcore": false, "kills": 0, "deaths": 0, "born": 1767225600000 }, "ver": 1, "at": 1767225600000 } }, "stats": {}, "fallen": [] } },
+      "inputs": [
+        { "at": 0.4, "key": "Space", "hold": 0.08 },
+        { "at": 1.0, "key": "Space", "hold": 0.08 },
+        { "at": 1.6, "key": "Space", "hold": 0.08 }
+      ]
+    }
+  }
+}