@homie-rocks/studio 0.19.1 → 0.20.0

package/lib/mcp-tools.mjs

@@ -28,15 +28,20 @@ import { cliJob, findNode, getJob, installJob, installed, jobView, runningJobs,
 import { Feed, currentId, publicFeed, readFeed, startProgress } from './progress.mjs';
 import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
-import { GAME_ID, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
+import { GAME_ID, PACKAGE_ROOT, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
+import { compareVersions, whatsNew, whatsNewLines } from './changelog.mjs';
+import { pinnedVersion } from './upgrade.mjs';
 import { AgentSeat } from './agent-seat.mjs';
+import { LAB_PORT, runningLab } from './lab.mjs';
+import { pictureFor } from './pictures.mjs';
 
 export const UI = Object.freeze({
   setup: 'ui://homie-studio/setup',
   build: 'ui://homie-studio/build',
   studio: 'ui://homie-studio/studio',
   codex: 'ui://homie-studio/codex',
+  lab: 'ui://homie-studio/lab',
 });
 
 const inside = (base, p) => p === base || p.startsWith(base.endsWith(sep) ? base : `${base}${sep}`);
@@ -120,8 +125,8 @@ const ok = (text, structured, extra = {}) => ({ content: [{ type: 'text', text }
 const fail = (text, structured) => ({ content: [{ type: 'text', text }], ...(structured ? { structuredContent: structured } : {}), isError: true });
 
 /** Run the pinned CLI and wait a while; { ended, job, result }. */
-async function cli(ctx, root, label, args, { wait = ctx.waitMs, onEnd = null } = {}) {
-  const job = cliJob(root, label, args, { onEnd });
+async function cli(ctx, root, label, args, { wait = ctx.waitMs, onEnd = null, cli: bin = null } = {}) {
+  const job = cliJob(root, label, args, { onEnd, ...(bin ? { cli: bin } : {}) });
   const ended = await waitJob(job, wait);
   return { ended, job, result: job.result };
 }
@@ -245,6 +250,18 @@ function published(root, kind) {
   } catch { return []; }
 }
 
+/**
+ * When the studio pins an older @homie-rocks/studio than this one: the pin, this version, and what's new between them
+ * (this package's own CHANGELOG.md). null when it is on this version, a newer one, or a link to a checkout.
+ */
+export function behindOf(root) {
+  let pkg = null;
+  try { pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); } catch { return null; }
+  const pinned = pinnedVersion(pkg?.devDependencies?.['@homie-rocks/studio'] ?? pkg?.dependencies?.['@homie-rocks/studio']);
+  if (!pinned || compareVersions(pinned, STUDIO_VERSION) >= 0) return null;
+  return { pinned, here: STUDIO_VERSION, whatsNew: whatsNew(pinned, STUDIO_VERSION) };
+}
+
 async function studioCard(ctx, root) {
   const studio = readStudio(root);
   const dev = devOf(root);
@@ -282,6 +299,8 @@ async function studioCard(ctx, root) {
     games, songs: published(root, 'music'), videos: published(root, 'videos'), posts,
     dev: dev ? { url: dev.url } : null, site: live, rooms, demo, installed: installed(root),
   };
+  const behind = behindOf(root);
+  if (behind) data.behind = { ...behind, whatsNew: behind.whatsNew ? { ...behind.whatsNew, versions: behind.whatsNew.versions.slice(0, 6).map(({ version, summary, upgrade }) => ({ version, summary, upgrade: upgrade.slice(0, 2) })) } : null };
   const text = [
     `${studio.name} (${root})`,
     games.length ? `Games: ${games.map((g) => `${g.name} (${g.id}${live ? (g.live ? ', live' : ', not deployed yet') : ''})`).join(', ')}` : 'No game yet: its home page says "First game coming soon".',
@@ -289,6 +308,10 @@ async function studioCard(ctx, root) {
     live ? `Live: ${live}/` : 'Not online yet (studio_deploy).',
     ...(rooms.length ? [`Live rooms: ${rooms.map((r) => `${r.game} ${r.room} (${r.players})`).join(', ')}`] : []),
     ...(demo ? [`See a working game meanwhile: ${demo.name}, ${demo.play}`] : []),
+    ...(behind ? [
+      `Toolkit: this studio pins @homie-rocks/studio ${behind.pinned}; this Homie is ${behind.here}. Tell the person what is new (below) and offer the upgrade: studio_run { "args": ["upgrade"] } shows the plan and changes nothing; with their yes, ["upgrade","--apply"], then studio_install.`,
+      ...whatsNewLines(behind.whatsNew, { maxVersions: 6, maxNotes: 6 }),
+    ] : []),
   ].join('\n');
   return ok(text, data);
 }
@@ -853,6 +876,46 @@ export function toolDefs(ctx, avail = {}) {
         ] });
       },
     },
+    {
+      name: 'game_lab', title: 'Open the Game Lab',
+      description: 'The Game Lab for one mechanic of a game (a jump, a hit, a dash): one short take played in New (the working tree) beside Today (the last commit) on one clock, slowed down or a frame at a time, with its phases, graphs and live sliders that write kept values into the game\'s tunables.json. Starts the lab on this computer, plays the take headless once (New against Today: phases, peaks, whether replays match, JavaScript per frame) and answers with a card: a still of both builds at the take\'s busiest moment and Open. The game must call @homie-rocks/studio/lab (the starters do); studio_guide { "topic": "lab" } has the whole method. The person opens the lab from the card or the link; do not open a browser.',
+      inputSchema: { type: 'object', properties: { game: str('The game\'s id (default: the only game)'), take: str('Optional: a take in games/<id>/lab.json (default: its default)'), today: str('Optional: the git ref Today is built from (default HEAD)'), ...STUDIO_ARG } },
+      annotations: { title: 'Open the Game Lab', ...RW }, _meta: ui(UI.lab),
+      run: async (a) => {
+        const root = ctx.root(a.studio);
+        const need = needsInstall(ctx, root); if (need) return need;
+        const games = listGames(root);
+        const game = a.game ?? (games.length === 1 ? games[0].id : null);
+        if (!game || !games.some((g) => g.id === game)) return fail(games.length ? `which game? ${games.map((g) => g.id).join(', ')}` : 'there is no game yet');
+        const ref = a.today ? String(a.today) : 'HEAD';
+        let lab = await runningLab(root);
+        if (!lab) {
+          const port = await freePort(LAB_PORT);
+          const job = cliJob(root, `the Game Lab, here (port ${port})`, ['lab', game, '--port', String(port), ...(ref !== 'HEAD' ? ['--today', ref] : [])]);
+          const until = Date.now() + 20_000;
+          while (!lab && Date.now() < until && !job.endedAt) { await new Promise((r) => setTimeout(r, 400)); lab = await runningLab(root); }
+          if (!lab) return fail(`the Game Lab did not start: ${whyOf(job)}`);
+        }
+        const q = new URLSearchParams({ ...(a.take ? { take: String(a.take) } : {}), ...(ref !== 'HEAD' ? { today: ref } : {}) }).toString();
+        const url = `${lab.url}/${game}/${q ? `?${q}` : ''}`;
+        const r = await cli(ctx, root, `Game Lab check of ${game}`, ['lab', 'check', game, ...(a.take ? ['--take', String(a.take)] : []), ...(ref !== 'HEAD' ? ['--today', ref] : [])]);
+        if (!r.ended) return ok(`The Game Lab is running: ${url}\nIts headless check is still going (job ${r.job.id}); the person can open the lab now.`, { kind: 'lab', game, url, running: true });
+        const c = r.result;
+        if (!c?.ok) return fail(`The Game Lab is running at ${url}, but its check failed: ${whyOf(r.job)}`, { kind: 'lab', game, url });
+        let still = null;
+        try { const p = pictureFor(resolve(root, c.still), { label: c.still, max: 420 * 1024 }); still = `data:${p.mimeType};base64,${p.data}`; } catch { still = null; }
+        const name = games.find((g) => g.id === game)?.name ?? game;
+        const det = (x) => (x === null ? 'replays match' : `replays DIFFER from frame ${x}`);
+        return ok([
+          `The Game Lab for ${name}: ${url} (on this computer; the person opens it from the card or this link).`,
+          `Take "${c.take ?? '(none)'}", ${c.frames} frames at ${c.fps} fps.`,
+          `New: ${c.phases.new.join(' · ') || 'no phases yet'} (${det(c.deterministic.new)}; JavaScript ${c.cost.new?.mean} ms a frame, p95 ${c.cost.new?.p95}).`,
+          c.phases.today ? `Today (${c.today}): ${c.phases.today.join(' · ') || 'no phases'} (${det(c.deterministic.today)}; JavaScript ${c.cost.today?.mean} ms, p95 ${c.cost.today?.p95}).` : `Today: ${c.todayNote ?? 'none'}.`,
+          `Report: ${c.report}; pictures: ${c.sheet} (file_read shows it).`,
+          ...(c.errors?.length ? [`Errors: ${c.errors.join('; ')}`] : []),
+        ].join('\n'), { kind: 'lab', game, name, url, take: c.take, frames: c.frames, fps: c.fps, phases: c.phases, timeline: c.timeline, deterministic: c.deterministic, cost: c.cost, today: c.today, todayNote: c.todayNote, report: c.report, sheet: c.sheet, still, errors: c.errors ?? [] });
+      },
+    },
     {
       name: 'studio_deploy', title: 'Put the studio online',
       description: 'Put the studio\'s site online on the studio\'s OWN Cloudflare account: one Worker, one D1 database and two Durable Objects, free plan, no payment method. Call it with plan: true first and tell the person in two or three lines what it creates and costs. If Cloudflare is not signed in, cloudflare_login opens it in their browser to approve once. Runs in the background with the build card.',
@@ -948,18 +1011,21 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_run', title: 'Run a studio command',
-      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job.',
+      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job. ["upgrade"] runs with THIS Homie\'s toolkit when the studio pins an older one (that is how a studio moves up to it): it says what is new since the studio\'s version and what would change, and changes nothing; ["upgrade","--apply"] only after the person agrees, then studio_install.',
       inputSchema: { type: 'object', properties: { args: { type: 'array', items: { type: 'string' }, description: 'The command\'s words after `homie-studio`' }, ...STUDIO_ARG }, required: ['args'] },
       annotations: { title: 'Run a studio command', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       run: async (a) => {
         const root = ctx.root(a.studio);
         const args = Array.isArray(a.args) ? a.args.map((x) => String(x)).filter((x) => x !== '--json') : [];
         if (!args.length) return fail('args: the command\'s words, e.g. ["look"]');
-        const refused = { mcp: 'this is it', new: 'studio_scaffold makes a studio', dev: 'preview_run runs the site here, preview_stop stops it', statusline: 'only for Claude Code' }[args[0]];
+        const refused = { mcp: 'this is it', new: 'studio_scaffold makes a studio', dev: 'preview_run runs the site here, preview_stop stops it', statusline: 'only for Claude Code' }[args[0]]
+          ?? (args[0] === 'lab' && !['check', 'set', 'stop'].includes(args[1] ?? '') && !args.includes('--stop') ? 'game_lab starts the Game Lab here (and answers with its card)' : null);
         if (refused) return fail(`not here: ${refused}`);
         if (!['help', 'version', 'setup', 'doctor', 'demo', 'starters', 'progress', 'codex', 'games', 'status'].includes(args[0])) { const need = needsInstall(ctx, root); if (need) return need; }
         if (args[0] === 'game' && args[1] === 'new') ctx.note(root).demo = true;
-        const r = await cli(ctx, root, `homie-studio ${args.slice(0, 3).join(' ')}`, args);
+        // The upgrade is the newer toolkit's to make: the studio's own pinned copy knows nothing newer than itself.
+        const own = args[0] === 'upgrade' && behindOf(root) ? { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs') } : {};
+        const r = await cli(ctx, root, `homie-studio ${args.slice(0, 3).join(' ')}`, args, own);
         if (!r.ended) return stillRunning(r.job, `homie-studio ${args.slice(0, 2).join(' ')}`);
         const text = r.result ? JSON.stringify(r.result, null, 1).slice(0, 12_000) : jobView(r.job, { lines: 40 }).tail.join('\n');
         return r.job.code === 0 ? ok(text, { kind: 'run', args, result: r.result }) : fail(`homie-studio ${args.join(' ')}: ${whyOf(r.job)}`, { kind: 'run', args, result: r.result });

package/lib/mcp.mjs

@@ -46,10 +46,12 @@ A studio made elsewhere (on a phone, with Deploy to Cloudflare, so it lives on G
 
 Links are the person's to open: give them in your reply (the cards have their own buttons). Never open a browser or run a command such as open to open one yourself.
 
+To make one mechanic of a game feel better (a jump, a hit, a dash), game_lab opens the Game Lab: New beside Today, one take, its phases and sliders (studio_guide { "topic": "lab" }).
+
 Long work (npm install, check, playtest, deploy, renders) runs in the background: the tool answers at once with a card that follows it, and build_progress or studio_job reads where it is. studio_guide has Homie's full guide for each job (game, plan, port, playtest, publish, music, sound, art, video). Never put a key or password in a file or the chat. If Homie's homie.rocks connector is connected too, its tools of the same names say what to run; these run it.`;
 
-const CARD_FILES = { [UI.setup]: 'setup.js', [UI.build]: 'build.js', [UI.studio]: 'studio.js', [UI.codex]: 'codex.js' };
-const CARD_TITLES = { [UI.setup]: 'Studio setup', [UI.build]: 'Build progress', [UI.studio]: 'Studio', [UI.codex]: 'Game Codex' };
+const CARD_FILES = { [UI.setup]: 'setup.js', [UI.build]: 'build.js', [UI.studio]: 'studio.js', [UI.codex]: 'codex.js', [UI.lab]: 'lab.js' };
+const CARD_TITLES = { [UI.setup]: 'Studio setup', [UI.build]: 'Build progress', [UI.studio]: 'Studio', [UI.codex]: 'Game Codex', [UI.lab]: 'Game Lab' };
 const UI_DIR = join(PACKAGE_ROOT, 'mcp', 'ui');
 
 /** One card's whole document: the shared look and bridge, and the card's own script, as the files are. */

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

@@ -813,6 +813,80 @@
      }
     }
    }
+  },
+  "0.19.2": {
+   "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": "8dc97df0d77e655e",
+     "## Commands (all through the pinned CLI in node_modules)": "a06ab13fc385ab25",
+     "## 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)": "677ee39dc13485e0"
+      }
+     }
+    }
+   }
+  },
+  "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/lib/upgrade.mjs

@@ -25,11 +25,16 @@
  * Media (0.18.0): the plan also says which songs and videos are big media (over studio.json media.r2Over, 1 MiB
  * unless set, or left out of git), what is in the studio's R2 already, and the step that moves the rest
  * (`media move`, which every deploy of a studio with storage also runs). Upgrade itself never moves a file.
+ *
+ * What's new (0.19.2): the plan and the applied result carry `whatsNew`, every version after the one the studio
+ * was on up to this one, each with its one-line summary and its upgrade notes, read from THIS package's own
+ * CHANGELOG.md (lib/changelog.mjs): the version being moved to says what it brings, with no network.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
+import { whatsNew } from './changelog.mjs';
 import { R2_COST, mediaPlan, r2OverOf, sizeOf } from './media.mjs';
 import { studioFiles } from './scaffold.mjs';
 import { readStudio } from './studio.mjs';
@@ -243,12 +248,15 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
   const git = spawnSync('git', ['status', '--porcelain'], { cwd: root, encoding: 'utf8' });
   const dirty = git.status === 0 ? git.stdout.split('\n').filter(Boolean).length : null;
   const media = mediaNote(root, studio);
+  const news = whatsNew(from, STUDIO_VERSION);
   return {
     ok: true, command: 'upgrade', applied: false, root, studio: name, from, to: STUDIO_VERSION,
+    ...(news ? { whatsNew: news } : {}),
     changes, kept,
     ...(media ? { media } : {}),
     ...(dirty ? { uncommitted: dirty } : {}),
-    next: changes.length ? ['npx --no-install homie-studio upgrade --apply   (after the person agrees)'] : [],
+    // A plan that moves the pin is this (newer) toolkit's to apply: the studio's own older copy knows nothing newer.
+    next: changes.length ? [`${changes.some((c) => c.kind === 'pin') ? `npx -y @homie-rocks/studio@${STUDIO_VERSION} upgrade --apply` : 'npx --no-install homie-studio upgrade --apply'}   (after the person agrees)`] : [],
   };
 }
 

package/mcp/ui/card.css

@@ -63,6 +63,8 @@ ol.list,ul.list{list-style:none;margin:0;padding:0;display:grid;gap:6px}
 .game b{font-size:14px}.game span{font-size:12.5px;color:var(--c-fg2)}
 .soon{padding:14px;border-radius:var(--r-md);background:linear-gradient(135deg,color-mix(in srgb,var(--accent) 18%,var(--c-bg2)),var(--c-bg2));display:grid;gap:6px}
 .soon b{font-size:16px}
+.news{margin:12px 0 0;padding:12px 14px;border-radius:var(--r-md);background:var(--c-bg2);display:grid;gap:6px;font-size:13px;color:var(--c-fg2)}
+.news b{color:var(--c-fg);font-size:14px}.news code{font-weight:600;color:var(--c-fg);margin-right:2px}.news .fine{margin:2px 0 0}
 .stats{display:flex;flex-wrap:wrap;gap:6px 16px;margin:4px 0 6px;color:var(--c-fg2);font-size:13px}.stats b{color:var(--c-fg)}
 .log{margin:10px 0 0;padding:8px 10px;border-radius:var(--r-md);background:var(--c-bg2);font:12px/1.5 var(--f-mono);color:var(--c-fg2);white-space:pre-wrap;overflow-wrap:anywhere}
 .frame{width:100%;height:620px;border:0;border-radius:var(--r-md);background:var(--c-bg2);display:block}

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/mcp/ui/studio.js

@@ -1,5 +1,5 @@
 /* The studio card: its games with Play (on this computer and live), songs, videos and posts, where it runs, its
- * live rooms, and a live game to try while it has none. */
+ * live rooms, a live game to try while it has none, and what's new when its toolkit is older than this Homie. */
 (function () {
   var C = Card;
   function initials(name) { return String(name || '?').split(/\s+/).filter(Boolean).slice(0, 2).map(function (w) { return w[0]; }).join('').toUpperCase(); }
@@ -28,6 +28,14 @@
       card.appendChild(soon);
     }
     if ((sc.rooms || []).length) card.appendChild(C.el('p', 'fine', 'Playing now: ' + sc.rooms.map(function (r) { return r.game + ' (' + r.players + ')'; }).join(', ')));
+    // A studio on an older toolkit than this Homie: what's new since (this package's CHANGELOG.md), and the words to ask.
+    if (sc.behind) {
+      var news = C.add(C.el('div', 'news'), C.el('b', '', 'New in Homie since ' + sc.behind.pinned));
+      ((sc.behind.whatsNew && sc.behind.whatsNew.versions) || []).slice(0, 3).forEach(function (v) { news.appendChild(C.add(C.el('span'), C.el('code', '', v.version), C.el('span', '', ' ' + v.summary))); });
+      news.appendChild(C.el('span', 'fine', 'This studio is on ' + sc.behind.pinned + ', and ' + sc.behind.here + ' is here. Say \u201cUpgrade my studio\u201d to see what changes; nothing does until you agree.'));
+      card.appendChild(news);
+      C.tell('behind', sc.name + ' pins @homie-rocks/studio ' + sc.behind.pinned + ' and this Homie is ' + sc.behind.here + ': offer the upgrade (studio_run ["upgrade"] shows what is new and the plan, and changes nothing).');
+    }
     var foot = C.el('div', 'foot');
     foot.appendChild(C.el('span', 'when', sc.site ? sc.site.replace(/^https?:\/\//, '') : sc.dev ? sc.dev.url.replace(/^https?:\/\//, '') : 'Not online yet'));
     var acts = C.el('div', 'actions');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.19.1",
+  "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,10 +50,12 @@
     "mcp/",
     "saves/",
     "agents/",
+    "lab/",
     "starters/",
     "media/",
     "site/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE"
   ],

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 }
+      ]
+    }
+  }
+}