@homie-rocks/studio 0.19.2 → 0.21.0

package/CHANGELOG.md

@@ -17,9 +17,99 @@ 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.21.0] - 2026-10-02
+
+**Plugin 0.22.0** · [#31](https://github.com/homie-rocks/homie/pull/31)
+
+The Homie mod for Claude Code: your studio, its rooms and a real seat in a live game beside the chat, with a look
+before protected files, deploys and spending, and keys kept out of what Claude reads.
+
+### Added
+
+- Plugin: the Homie mod (Claude Code 2.1.287 or later). Inside a studio, a one-row band above the prompt shows the
+  studio, the game, the build step, ▶ Play and how many people are playing now. Outside a studio it adds nothing.
+- Plugin: the Studio pane (`/studio`) opens by itself when a build starts, on a wide enough terminal. **Build** has the
+  live Plan, Build, Checks, Deploy feed and the latest check frame, or a live Watch of a room of the game being built.
+  **Rooms** lists who is playing and the AI players, with Watch and Join links; Announce, Mute and Kick go through
+  the office, and Mute and Kick are only ever asked for, so you still confirm them with one tap. **Games** has
+  launch states and the remix switch; **Stats** and **Codex** link to the rest. **Lab** shows each game's last Game
+  Lab check (New's phases beside Today's, whether the replays match) and the lab's link while it runs.
+- Plugin: the Arcade pane (`/arcade`). Take a real seat in a public room of a Homie game (Homie Arcade's, or your
+  studio's own) and play it in the pane with w/a/s/d or the arrow keys while Claude works. It runs in one headless
+  Chrome on your computer at the lowest priority, about 8 frames a second in a terminal, pauses while the pane is
+  hidden and stops when you leave.
+- Plugin: a Parts pane for the `parallel` skill: each part, its last step, and the merge waiting for all of them.
+- Plugin: instant commands that answer without a Claude turn: `/play`, `/watch [room]`, `/rooms`, `/build`, `/codex`,
+  `/deploy-status`, `/perf-numbers`, `/parts`, `/arcade`. They print links or open a pane; nothing opens a browser.
+- Plugin: guards. An edit to a file matched by studio.json `"protect"` (globs, such as `"games/*/game.json"`) shows
+  the diff and waits for Proceed or Cancel. So does a deploy (where it goes, what it creates, the commits and files
+  since the last one, the checks) and a paid fal or ElevenLabs run that would pass studio.json `"budget"`.
+- Plugin: Cloudflare tokens, provider keys, agent passes, office keys and one-time owner links are taken out of
+  command output before Claude reads it.
+- Plugin: setup status, check, playtest and deploy results are drawn as checklists and rows, with the live link.
+- `homie-studio office mute <game> <room> <seat | name> [--minutes 10] [--off]`, asked for like `office kick`.
+- A build's latest check frame is also kept as a small picture beside its progress feed, for the mod to draw.
+
+### Upgrade notes
+
+- Every part of the mod has its own switch (`/config`, or `pluginConfigs` in settings.json). Codex installs the plugin
+  as before; it does not run plugin hooks, so there it is the skills and tools you had.
+- `homie-studio upgrade --apply` adds `office mute` and the `protect` and `budget` lines to AGENTS.md.
+
+## [0.20.0] - 2026-10-02
+
+**Plugin 0.21.0** · [#30](https://github.com/homie-rocks/homie/pull/30) · [release-2026-10-02-studio-0.20.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.20.0)
+
+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 +936,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]
@@ -80,8 +94,9 @@
  *   homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1] [--days <n>] [--server <id>]
  *   homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]
  *   homie-studio office kick <game> <room> <seat number | name> [--minutes 10]
+ *   homie-studio office mute <game> <room> <seat number | name> [--minutes 10] [--off]
  *   homie-studio office close <game> <room> [--minutes 10] [--reopen]
- *                                         (kick, close and launch are ASKED for: the owner confirms each with one
+ *                                         (kick, mute, close and launch are ASKED for: the owner confirms each with one
  *                                          tap in their own browser, from the link this prints)
  *   homie-studio office revoke            (every office key, play ticket and pending ask ends)
  *
@@ -169,6 +184,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';
@@ -177,7 +193,7 @@ import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, star
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
 import { playersOwner, playersShow } from '../lib/players.mjs';
-import { officeAnnounce, officeClose, officeInvite, officeKey, officeKick, officeLaunch, officeLines, officeLink, officeRevoke, officeShow } from '../lib/office.mjs';
+import { officeAnnounce, officeClose, officeInvite, officeKey, officeKick, officeLaunch, officeLines, officeLink, officeMute, officeRevoke, officeShow } from '../lib/office.mjs';
 import { agentsBrain, agentsBrainKey, agentsPass, agentsPasses, agentsRevoke, serversClose, serversLevel, serversLines, serversList, serversMember, serversNew, serversSet } from '../lib/servers.mjs';
 import { AgentSeat } from '../lib/agent-seat.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
@@ -191,7 +207,7 @@ import { formatHandoff, handoff } from '../lib/handoff.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile'];
+const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -234,6 +250,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)`);
@@ -377,6 +412,7 @@ function print(result) {
     case 'agents brain':
     case 'office launch':
     case 'office kick':
+    case 'office mute':
     case 'office close':
       lines.push(result.asked ? `Asked: ${result.what}` : result.message, ...(result.asked ? [`Owner's one-tap link (until the ask ends, 15 min): ${result.link}`, result.use] : []));
       break;
@@ -555,6 +591,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);
@@ -619,6 +656,7 @@ async function main() {
     if (sub === 'invite') return officeInvite(root, positional[2], { url, label: flags.get('label'), uses: flags.get('uses'), count: flags.get('count'), days: flags.get('days'), server: flags.get('server') });
     if (sub === 'launch') return officeLaunch(root, positional[2], positional[3], { url, remixable: flags.get('remixable'), max: flags.get('max') });
     if (sub === 'kick') return officeKick(root, positional[2], positional[3], positional.slice(4).join(' ') || undefined, { url, minutes: flags.get('minutes') });
+    if (sub === 'mute') return officeMute(root, positional[2], positional[3], positional.slice(4).join(' ') || undefined, { url, minutes: flags.get('minutes'), off: flags.has('off') });
     if (sub === 'close') return officeClose(root, positional[2], positional[3], { url, minutes: flags.get('minutes'), reopen: flags.has('reopen') });
     if (sub === 'revoke') return officeRevoke(root, { url });
   }
@@ -662,6 +700,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);