@homie-rocks/studio 0.9.0 → 0.10.0

package/README.md

@@ -10,7 +10,7 @@ Most people never run this by hand: the Homie plugin for Claude Code and Codex d
 and the person approves Cloudflare once in their browser.
 
 ```sh
-npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio new ./night-owls --name "Night Owls"
+npx -y @homie-rocks/studio new ./night-owls --name "Night Owls"
 cd night-owls && npm install
 npx homie-studio game new crown-thief --from gem-rush --name "Crown Thief"
 npx homie-studio dev                                   # the whole site locally
@@ -22,6 +22,32 @@ npx homie-studio stats                                 # the studio's own number
 npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
+## From GitHub, with Cloudflare's own CI (Workers Builds, Previews, Deploy to Cloudflare)
+
+A studio keeps `wrangler.jsonc` at its root (a studio made before 0.10.0 keeps `site/wrangler.jsonc`, and every
+command still finds it), so Cloudflare's Workers Builds can build and deploy it from its GitHub repository with no
+computer involved:
+
+| Workers Builds runs | On | What happens |
+| --- | --- | --- |
+| `npm run build` | every push | `homie-studio build`: the site, with the commit it is built from |
+| `npm run deploy` | the production branch | In Workers Builds (`WORKERS_CI=1`), `homie-studio deploy` only applies the D1 migrations (by binding name) and deploys: the Worker and database are Cloudflare's to make, so it creates and refuses nothing. The first deploy creates the database as it goes. |
+| `npx wrangler preview` | every other branch | A **Preview**: its own URL, and its own Durable Object namespace, so a branch's public rooms never meet production's. A Preview has no D1: it counts nothing into the studio's stats and never claims itself in the directory. |
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/homie-rocks/homie/tree/main/template)
+
+The button copies the public template (`template/` in this repository, exactly what `homie-studio new --template`
+writes) into the person's GitHub, makes the Worker, the D1 database and the rooms on their Cloudflare account,
+and connects Workers Builds. The site plays its first game (Gem Rush) the moment it is up, and its Home has a
+**Connect to Claude** band: one tap links it to the Claude chat that set it up (the Homie MCP tool `studio_setup`).
+In the Claude Code session that works in the repository, `homie-studio setup attach <hs_…>` then gives the studio
+the name chosen in the chat and removes the band.
+
+**The site claims itself in the directory.** The homie.rocks directory lists a studio only when its site serves
+the claim the directory handed out for that address. From 0.10.0 the site asks for it the first time its
+`/.well-known/homie-studio.json` is read (by `studio_publish`, or by `deploy` reading it once) and keeps it in
+its D1; nothing is stored by hand. studio.json `homie.directory: false` keeps a studio out.
+
 ## The site: the hub's shape, and a landing for every game
 
 Every studio site has the same sections as homie.rocks, in the studio's own look (`site/theme.json`): Home (the
@@ -46,8 +72,8 @@ site. A game made with Homie's arcade controls that knocks for a Homie box (`/__
 A studio pins one version, so nothing changes until it asks. To take a newer one:
 
 ```sh
-npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio upgrade          # the plan; changes nothing
-npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.10.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.10.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -108,6 +134,27 @@ check green ends the build. The AI marks what only it knows with `progress stage
 one runs, a shared feed asks whether Stop was pressed; a stopped command closes its
 browsers and says so, and nothing already built or deployed is undone.
 
+**From the Claude app.** The chat can open the build first (the Homie MCP tool `build_open`, or the "Build it"
+card on a make, port or remix) and hand the work to a Claude Code session with a prefilled prompt. The session
+takes the build once, with no key in the prompt, and the card follows it; the change goes out as a pull request
+the person merges with one tap:
+
+```sh
+npx homie-studio progress attach hb_…                  # this session takes the build the chat opened (once)
+npx homie-studio progress change "Crowns spawn twice as often"   # its mark, in changes/, committed with the change
+git switch -c faster-crowns && git add -A && git commit -m "Faster crowns" && git push -u origin HEAD
+gh pr create --fill                                     # then:
+npx homie-studio progress pr --url https://github.com/<owner>/<repo>/pull/<n>
+```
+
+Workers Builds deploys the branch as a Preview; the card's **Publish** opens the pull request in GitHub, where the
+person's merge is the approval; Workers Builds deploys `main`, and the card says **Live** when the live site's
+manifest lists the change's mark (`homie-studio build` lists the newest marks from `changes/`).
+
+A Claude Code cloud session's default network ("Trusted") does not reach homie.rocks; the toolkit says so, and
+names the setting (the environment's Network access: Custom, add homie.rocks), instead of "did not answer". The
+build goes on with its local feed.
+
 The feed is `.studio/progress/<build>.json` (git-ignored). With `--share` the studio's
 directory (studio.json `homie.directory`, homie.rocks by default) keeps a copy for 24
 hours so the Claude app can show it: the feed only (plain bounded text, pictures under
@@ -121,6 +168,14 @@ feed every command behaves exactly as before. `lib/progress.mjs` has the whole f
 names the Cloudflare account, often after its owner. A custom domain goes in studio.json
 as `cloudflare.domain` and is what the directory claim, `publish`, `check` and `stats` use.
 
+## 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
+session, GitHub Actions, a container) `npx homie-studio chrome install` puts Chrome for Testing in
+the home folder's `.cache/homie-studio` (from storage.googleapis.com, which a cloud session's default network reaches), and WebGL
+renders with SwiftShader. `check` reports how fast each browser drew the game and on what renderer; on SwiftShader
+it says the frame rate is not a person's, and judges only seats, rooms and rounds.
+
 ## No payment method needed
 
 `deploy` creates only what Cloudflare's free Workers plan gives a new account with no
@@ -157,9 +212,11 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `bin/homie-studio.mjs` | The CLI. |
 | `lib/scaffold.mjs` | `new`: the studio monorepo, only into a new or empty folder, every file listed. |
 | `lib/build.mjs` | `build`: games bundled with esbuild into `site/dist`, `games.json`, each game's shared `source.json`. |
-| `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations, the directory claim; refuses resources it did not create. `storage add`: the optional R2 bucket. |
-| `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. |
+| `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations; refuses resources it did not create. In Workers Builds, migrations and deploy only. `storage add`: the optional R2 bucket. |
+| `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it, with each one's frame rate; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. `lib/chrome.mjs`: which Chrome, and how (the GPU on a Mac, SwiftShader on Linux). |
 | `lib/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |
+| `lib/progress.mjs`, `lib/setup.mjs` | The progress feed (`progress …`), a build the chat opened (`progress attach`), a change as a pull request (`progress change`, `progress pr`), and `setup attach`. |
+| `template/` (repository root), `scripts/template.mjs` | The public "Deploy to Cloudflare" template, generated from `new --template`. |
 | `lib/port.mjs` | `port plan` (reads a game and grades the port) and `port import`. |
 | `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |
 | `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`. |
@@ -171,9 +228,10 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `starters/gem-rush/` | The reference multiplayer starter. |
 
 Versions are immutable: a published version never changes, so a studio that pinned one
-never changes by surprise. A change ships as a new `version`, on the npm registry as
-`@homie-rocks/studio` and as a tarball at `https://homie.rocks/npm/homie-studio-<version>.tgz`
-(which is what `homie-studio new` pins).
+never changes by surprise. A change ships as a new `version` on the npm registry as
+`@homie-rocks/studio`, which is what `homie-studio new` pins (the exact version; package-lock.json keeps its
+integrity). The registry is what Workers Builds and a Claude Code cloud session reach by default. Older studios
+pinned a tarball at `https://homie.rocks/npm/homie-studio-<version>.tgz`, which stays.
 
 ## Beta
 

package/bin/homie-studio.mjs

@@ -4,7 +4,8 @@
  * put its site on the studio's own Cloudflare (free plan, no payment method), and
  * list its games in the homie.rocks directory.
  *
- *   homie-studio new <folder> --name "<Studio Name>" [--homie <directory url>] [--no-install]
+ *   homie-studio new <folder> --name "<Studio Name>" [--homie <directory url>] [--no-install] [--template]
+ *                                         (--template: the public "Deploy to Cloudflare" template: a first game and a Connect band)
  *   homie-studio starters
  *   homie-studio game new <id> [--from gem-rush] [--name "<Game Name>"]
  *   homie-studio game remix <source.json url> --id <new id>
@@ -12,12 +13,16 @@
  *   homie-studio build [<id>]
  *   homie-studio dev [--port 8787]        (--stop: stop exactly this studio's dev server, nothing else)
  *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   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]
  *                                         (the site's pages on a computer and a phone, as pictures, with what is wrong)
  *   homie-studio port plan <game folder>
  *   homie-studio port import <game folder> --id <id> [--name "<Name>"] [--mode static|bundle|command]
  *   homie-studio port check <id> [--url <site>] [--only owner-desk,owner-phone,owner-iphone,round,life,tv] [--shots <dir>]
  *   homie-studio deploy [--plan]          (--plan: what it will create on Cloudflare and what it costs; changes nothing)
+ *                                         In Cloudflare's Workers Builds (WORKERS_CI=1, or --ci) it only applies the D1
+ *                                         migrations and deploys: the Worker and database are the Deploy button's.
  *   homie-studio publish
  *   homie-studio storage add              (large media only: an R2 bucket; needs R2 turned on for the account)
  *   homie-studio media put <file> [--as <key>]
@@ -46,11 +51,18 @@
  *   homie-studio progress log "<one line>"
  *   homie-studio progress stop            (ask the running build to stop at its next safe point)
  *   homie-studio progress end passed|failed|stopped [--note "<one line>"]
+ *   homie-studio progress attach <hb_…>   (the build the Claude app opened with build_open: this session takes it, once)
+ *   homie-studio progress change "<what the change does>"   (its mark in changes/, committed with the change)
+ *   homie-studio progress pr --url <pull request> [--state open|merged|closed] [--files n --additions n --deletions n]
+ *                                         [--preview <Preview URL>]   (the card's Publish opens it for the person's merge)
  *   homie-studio progress show [<build>]
  *                                         While a feed is open, build, check, port check and deploy report
  *                                         into it (stage, each check going green, a preview picture) and stop
  *                                         when asked. Without one, nothing changes.
  *
+ *   homie-studio setup attach <hs_…>      (this repository is the studio the Claude app's setup card is making: say so, once,
+ *                                          learn its live address, and give a template copy its real name)
+ *
  * Every command prints a few lines for a person; --json prints the result.
  */
 import { spawn, spawnSync } from 'node:child_process';
@@ -58,7 +70,9 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, wr
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { build } from '../lib/build.mjs';
 import { check } from '../lib/check.mjs';
-import { deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { ciDeploy, deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { setupAttach } from '../lib/setup.mjs';
+import { chromeArgs, findChrome, installChrome, noChrome } from '../lib/chrome.mjs';
 import { publish } from '../lib/directory.mjs';
 import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
@@ -66,14 +80,14 @@ import { portCheck } from '../lib/port-check.mjs';
 import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
 import { ensureStatsMigration, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
-import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters } from '../lib/studio.mjs';
+import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
-import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, startProgress } from '../lib/progress.mjs';
+import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff'];
+const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -123,10 +137,14 @@ function print(result) {
       }
       break;
     case 'deploy':
+      if (result.ci) {
+        lines.push(`Live: ${result.url ?? '(Wrangler printed no address)'}${result.commit ? ` (commit ${result.commit.slice(0, 7)}${result.branch ? ` on ${result.branch}` : ''})` : ''}`, ...result.steps.map((x) => `  ${x.what}`), ...result.games.map((g) => `  ${g.id}: ${g.play}`));
+        break;
+      }
       lines.push(`Live: ${result.url}`, ...(result.workersDev && result.workersDev !== result.url ? [`  also at ${result.workersDev}`] : []),
         ...(result.local ? [`  (the workers.dev address names your Cloudflare account, so it is kept in ${result.local} on this computer, never in studio.json)`] : []),
         ...result.games.map((g) => `  ${g.id}: ${g.play}`), ...(result.songs ?? []).map((m) => `  song ${m.slug}: ${m.page}`), ...(result.videos ?? []).map((m) => `  video ${m.slug}: ${m.page}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}, Durable Objects Table + Lobby${result.r2 ? `, R2 ${result.r2}` : ' (no storage: none needed; `homie-studio storage add` adds it for large media)'}. All on the free Workers plan${result.r2 ? ' plus R2' : ''}.`,
-        result.claim ? 'Directory claim stored: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the directory did not answer); publish will try again.');
+        result.claim ? 'The site claimed itself in the directory: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the site claims itself when the directory first reads it; publish does).');
       break;
     case 'deploy plan':
       lines.push(`What \`npm run deploy\` does for ${result.studio}, on the Cloudflare account the person approves:`, '',
@@ -179,6 +197,10 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    case 'setup attach':
+      lines.push(result.message, ...(result.site ? [`  live site: ${result.site}`] : []), ...(result.renamed?.length ? ['  changed (commit these on a branch):', ...result.renamed.map((f) => `    ${f}`)] : []), ...(result.next ?? []).map((n) => `  next: ${n}`));
+      break;
+    case 'progress attach':
     case 'progress start':
       lines.push(`Build ${result.build}: ${result.title} (${result.stages.join(' → ')})${result.budget !== null ? `, budget ${result.unit === 'usd' ? `$${result.budget.toFixed(2)}` : `${result.budget} credits`}` : ''}`,
         `  feed: ${result.file}`,
@@ -230,9 +252,15 @@ function print(result) {
       if (result.next?.length) lines.push('', 'Next:', ...result.next.map((n) => `  ${n}`));
       break;
     }
+    case 'chrome':
+    case 'chrome install':
+      lines.push(result.already || result.command === 'chrome' ? `Chrome: ${result.chrome}` : `Installed Chrome for Testing ${result.buildId}: ${result.chrome}`);
+      break;
     case 'check':
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
-        ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`));
+        ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`),
+        ...(result.frames ?? []).map((f) => `  ${f.browser} drew ${f.fps ?? '?'} fps${f.renderer ? ` on ${f.renderer}` : ''}`),
+        ...(result.software ? [`  ${result.software}`] : []));
       break;
     default:
       lines.push(JSON.stringify(result, null, 2));
@@ -248,12 +276,15 @@ async function main() {
     return { ok: true, command: 'help' };
   }
   if (cmd === 'version' || flags.has('version')) return { ok: true, command: 'version', version: STUDIO_VERSION };
-  if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install') });
+  if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install'), template: flags.has('template') });
   if (cmd === 'starters') return { ok: true, command: 'starters', starters: starters() };
 
   if (cmd === 'port' && sub === 'plan') return planPort(positional[2] ?? '.');
+  if (cmd === 'chrome' && sub === 'install') return installChrome({ log, fresh: flags.has('fresh') });
+  if (cmd === 'chrome') { const chrome = findChrome(); return chrome ? { ok: true, command: 'chrome', chrome, args: chromeArgs() } : { ok: false, command: 'chrome', why: noChrome() }; }
   const root = requireStudio();
   if (cmd === 'progress') return progressCommand(root, sub);
+  if (cmd === 'setup' && sub === 'attach') return setupAttach(root, positional[2], { homie: flags.get('homie') });
   if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
   if (cmd === 'port' && sub === 'check') {
     const game = positional[2] ?? listGames(root)[0]?.id;
@@ -295,6 +326,8 @@ async function main() {
     return look({ url, paths, shots: flags.get('shots') ? resolve(flags.get('shots')) : join(root, '.studio', 'look'), devices: only, log });
   }
   if (cmd === 'deploy' && flags.has('plan')) return deployPlan(root);
+  // Cloudflare's Workers Builds runs `npm run deploy` with WORKERS_CI=1 (and its own token for this one account).
+  if (cmd === 'deploy' && (process.env.WORKERS_CI === '1' || flags.has('ci'))) return tracked(root, 'deploy', () => ciDeploy(root, { log }), 'deploy');
   if (cmd === 'deploy') return tracked(root, 'deploy', () => deploy(root, { log, homie: flags.get('homie') }), 'deploy');
   if (cmd === 'storage' && sub === 'add') return storageAdd(root, { log });
   if (cmd === 'storage') {
@@ -372,6 +405,12 @@ async function progressCommand(root, sub) {
       budget: flags.get('budget'), unit: flags.get('unit'), share: flags.has('share'), directory: flags.get('homie'),
     });
   }
+  if (sub === 'attach') {
+    return startProgress(root, {
+      attach: arg ?? null, what: flags.get('what') ?? 'game', id: flags.get('id') ?? null, title: flags.get('title'),
+      budget: flags.get('budget'), unit: flags.get('unit'), directory: flags.get('homie'),
+    });
+  }
   if (sub === 'show') {
     const id = arg ?? currentId(root) ?? flags.get('build');
     const doc = readFeed(root, id);
@@ -400,8 +439,10 @@ async function progressCommand(root, sub) {
       }
       case 'log': feed.log(positional.slice(2).join(' ')); return done('logged');
       case 'stop': feed.stop('local'); return done('stop asked: the running command stops at its next safe point');
+      case 'change': { const c = recordChange(root, id, positional.slice(2).join(' ') || flags.get('title')); return { ...done(`change recorded: commit ${c.file} with the change`), file: c.file, mark: c.mark }; }
+      case 'pr': feed.pr({ url: flags.get('url'), state: flags.get('state') ?? 'open', title: flags.get('title'), branch: flags.get('branch'), files: flags.get('files'), additions: flags.get('additions'), deletions: flags.get('deletions'), preview: flags.get('preview'), site: siteUrl(root) }); return done(`pull request on the card: ${feed.doc.change.url}`);
       case 'end': feed.end(arg, note); return done(`ended: ${arg}`);
-      default: return { ok: false, command: 'progress', why: `unknown: progress ${sub ?? ''} (start, stage, check, preview, spend, shot, song, log, stop, end, show)` };
+      default: return { ok: false, command: 'progress', why: `unknown: progress ${sub ?? ''} (start, attach, stage, check, preview, spend, shot, song, log, change, pr, stop, end, show)` };
     }
   } catch (error) { return { ok: false, command: 'progress', why: error instanceof Error ? error.message : String(error) }; }
 }
@@ -411,7 +452,7 @@ async function progressCommand(root, sub) {
  * and `dev --stop` stops exactly those two (each checked to still be a process of this studio's folder), so an AI
  * never has to reach for `pkill -f "wrangler dev"`, which stops every project's dev server on the machine.
  */
-const devFile = (root) => join(root, 'site', '.wrangler', 'homie-dev.json');
+const devFile = (root) => join(workerDir(root), '.wrangler', 'homie-dev.json');
 function processOfStudio(pid, root, kind) {
   if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid) return false;
   try { process.kill(pid, 0); } catch { return false; }
@@ -450,11 +491,11 @@ async function dev(root) {
   const added = ensureStatsMigration(root);
   if (added) log(`added ${added} (the studio's own stats)`);
   await new Promise((done) => {
-    const m = spawn(bin, ['d1', 'migrations', 'apply', studio.cloudflare.d1, '--local'], { cwd: join(root, 'site'), env, stdio: ['ignore', 'ignore', 'inherit'] });
+    const m = spawn(bin, ['d1', 'migrations', 'apply', 'DB', '--local'], { cwd: workerDir(root), env, stdio: ['ignore', 'ignore', 'inherit'] });
     m.on('close', done);
   });
   log(`Local site: http://127.0.0.1:${port}/  (each game: http://127.0.0.1:${port}/<id>/play — open it in two browsers)`);
-  const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port], { cwd: join(root, 'site'), env, stdio: 'inherit' });
+  const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port], { cwd: workerDir(root), env, stdio: 'inherit' });
   mkdirSync(dirname(devFile(root)), { recursive: true });
   writeFileSync(devFile(root), `${JSON.stringify({ pid: process.pid, child: child.pid, port: Number(port), at: new Date().toISOString() })}\n`);
   log(`Stop it with: npx --no-install homie-studio dev --stop   (this studio's dev server only)`);
@@ -477,7 +518,7 @@ function mediaPut(root, file, as) {
   const key = as ?? (/^(music|videos)\//.test(rel) && !rel.includes('..') ? rel : `${folder}/${basename(file)}`);
   const bin = wranglerBin(root);
   return new Promise((done) => {
-    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: join(root, 'site'), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
+    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: workerDir(root), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
     p.on('close', (code) => {
       if (code !== 0) return done({ ok: false, command: 'media put', why: 'wrangler r2 object put failed' });
       // The manifest is committed: it names the file by its path on the site, never the workers.dev address.

package/lib/build.mjs

@@ -82,6 +82,34 @@ export function sourceOf(dir, id) {
   return { v: 1, kind: 'homie-game-source', id, files };
 }
 
+/*
+ * WHAT THIS BUILD IS, for the site's manifest: the commit and branch (Cloudflare's Workers Builds names them in
+ * WORKERS_CI_COMMIT_SHA and WORKERS_CI_BRANCH; elsewhere git is asked), when it was built, and the marks of the
+ * newest changes in changes/ (lib/progress.mjs recordChange), so the Claude app's card can tell when a merged pull
+ * request is live. Nothing here names a person or an account.
+ */
+export function buildInfo(root) {
+  const git = (args) => { try { const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 5000 }); return r.status === 0 ? r.stdout.trim() : null; } catch { return null; } };
+  const commit = /^[a-f0-9]{40}$/.test(process.env.WORKERS_CI_COMMIT_SHA ?? '') ? process.env.WORKERS_CI_COMMIT_SHA : git(['rev-parse', 'HEAD']);
+  const branch = String(process.env.WORKERS_CI_BRANCH || git(['rev-parse', '--abbrev-ref', 'HEAD']) || '').slice(0, 100) || null;
+  const marks = [];
+  const dir = join(root, 'changes');
+  if (existsSync(dir)) {
+    for (const name of readdirSync(dir).filter((n) => n.endsWith('.json'))) {
+      const c = readJson(join(dir, name));
+      if (c && /^[a-f0-9]{16}$/.test(String(c.change)) && !Number.isNaN(Date.parse(c.at))) marks.push({ mark: c.change, at: c.at });
+    }
+  }
+  marks.sort((a, b) => b.at.localeCompare(a.at));
+  return {
+    commit: /^[a-f0-9]{40}$/.test(String(commit)) ? commit : null,
+    branch: branch && /^[A-Za-z0-9._/-]+$/.test(branch) && branch !== 'HEAD' ? branch : null,
+    at: new Date().toISOString(),
+    ci: process.env.WORKERS_CI === '1' ? 'workers-builds' : null,
+    changes: [...new Set(marks.map((m) => m.mark))].slice(0, 50),
+  };
+}
+
 function readJson(path) {
   try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
 }
@@ -207,9 +235,16 @@ export async function build(root, { only = null, log = () => {} } = {}) {
         ...(Array.isArray(s.frameAncestors) ? { frameAncestors: s.frameAncestors.filter((o) => /^https:\/\/[a-z0-9.-]+(?::\d+)?$/i.test(String(o))).slice(0, 8) } : {}),
       },
       // studio.json `stats.share`: the site tells the directory two numbers for the hub (played this week).
-      ...(studio.stats?.share === true ? { stats: { share: true }, directory: studio.homie?.directory ?? 'https://homie.rocks' } : {}),
+      ...(studio.stats?.share === true ? { stats: { share: true } } : {}),
       // studio.json `"rooms": { "share": false }`: the manifest names no rooms, so the hub shows none of this studio's.
       ...(studio.rooms?.share === false ? { rooms: { share: false } } : {}),
+      // The directory the live site claims itself in (0.10.0); studio.json `homie.directory: false` keeps it out.
+      // HOMIE_DIRECTORY (a build variable) points one build at another directory, such as a staging one.
+      directory: /^https:\/\/[a-z0-9.-]+$/i.test(process.env.HOMIE_DIRECTORY ?? '') ? process.env.HOMIE_DIRECTORY
+        : studio.homie?.directory === false || studio.homie?.directory === null ? null : String(studio.homie?.directory ?? 'https://homie.rocks'),
+      // A copy of the public template that nobody has named yet shows the name typed in Cloudflare's form.
+      ...(studio.template === true ? { template: true } : {}),
+      build: buildInfo(root),
     },
     games: rows,
     songs: media.songs,

package/lib/check.mjs

@@ -16,16 +16,10 @@
  * the game's autopilot) is still that person. When no round counts, the result says which seat was missing from
  * each finished round and whether that browser lost its connection, instead of only "no round finished".
  */
-import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { cpus, loadavg, tmpdir } from 'node:os';
 import { join } from 'node:path';
-
-const CHROMES = [
-  process.env.CHROME_PATH,
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  '/Applications/Chromium.app/Contents/MacOS/Chromium',
-  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
-].filter(Boolean);
+import { SOFTWARE_GL, chromeArgs, findChrome, measureFrames, noChrome } from './chrome.mjs';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -63,8 +57,8 @@ export function judgeRounds(browsers, missed = new Map()) {
 
 export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
   if (!url || !game) throw new Error('usage: homie-studio check <game> --url <site url>');
-  const chrome = CHROMES.find((p) => existsSync(p));
-  if (!chrome) return { ok: false, command: 'check', why: 'no Chrome found (set CHROME_PATH)' };
+  const chrome = findChrome();
+  if (!chrome) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   const base = String(url).replace(/\/+$/, '');
@@ -101,7 +95,7 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
       profiles.push(profile);
       const browser = await puppeteer.launch({
         executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, protocolTimeout: 180_000,
-        args: ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
+        args: [...chromeArgs(), '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
       });
       browsers.push(browser);
       const page = await browser.newPage();
@@ -157,6 +151,12 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
     if (shots) for (const [i, p] of players.entries()) await p.page.screenshot({ path: join(shots, `${kinds[i].name}-playing.png`) }).catch(() => {});
     await sleep(1500);
     await picture('Playing: computer and phone in one room');
+    // How fast each browser draws the game while it plays (reported, never judged: a VM without a GPU draws
+    // with SwiftShader, which is not a person's frame rate).
+    const frames = await Promise.all(players.map((p) => measureFrames(p.page)));
+    const software = frames.some((f) => f.renderer && SOFTWARE_GL.test(f.renderer));
+    const drawn = frames.map((f, i) => `${kinds[i].name} ${f.fps ?? '?'} fps`).join(', ');
+    log(`drawing: ${drawn}${frames[0]?.renderer ? ` (${frames[0].renderer})` : ''}`);
     // Only a round that finishes AFTER both browsers were seated, seen by both, with BOTH of them in its results,
     // counts: an idle room remembers its last round for a while, and that stale result proves nothing. A browser is
     // in a round when a row carries a seat it held (a reconnect keeps its seat; a game may still mark an idle
@@ -202,7 +202,7 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
       return { ok: false, command: 'check', why, play, room: seated[0].room, seated, missed: misses, connection, load, totalMs: Date.now() - started };
     }
     const humans = hit.people;
-    step('round', humans >= 2 ? 'pass' : 'fail', { ms: Math.max(...hit.overMs), note: `round ${hit.n}: ${humans} people, ${hit.results.length - humans} bots${missed.size ? ` (after ${missed.size} round(s) without both)` : ''}` });
+    step('round', humans >= 2 ? 'pass' : 'fail', { ms: Math.max(...hit.overMs), note: `round ${hit.n}: ${humans} people, ${hit.results.length - humans} bot${hit.results.length - humans === 1 ? '' : 's'}${missed.size ? ` (after ${missed.size} round(s) without both)` : ''}; ${drawn}${software ? ' (software GL: not measurable here)' : ''}` });
     await picture(`Round ${hit.n} finished with both; the next one is on`);
     return {
       ok: sameRoom && humans >= 2,
@@ -213,6 +213,8 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
       round: { n: hit.n, humans, bots: hit.results.length - humans, results: hit.results, overMs: hit.overMs },
       ...(missed.size ? { missed: [...missed.values()] } : {}),
       connection,
+      frames: frames.map((f, i) => ({ browser: kinds[i].name, fps: f.fps, renderer: f.renderer })),
+      ...(software ? { software: 'This machine has no GPU (WebGL is SwiftShader): seats, rooms and rounds are measured; the frame rate is not a person\'s.' } : {}),
       why: humans >= 2 ? undefined : `the round's results list ${humans} person(s); both browsers should be in it`,
       totalMs: Date.now() - started,
     };

package/lib/chrome.mjs

@@ -0,0 +1,126 @@
+/**
+ * WHICH CHROME THE CHECKS RUN, AND HOW (check, port check, look).
+ *
+ * On a Mac: that Mac's Chrome, on its GPU (`--use-angle=metal`). A software renderer runs a 3D game at a
+ * few frames a second and makes it look stuck, so a Mac never falls back to one.
+ *
+ * On Linux (a Claude Code cloud session, GitHub Actions, a container) there is usually no GPU and often no
+ * Chrome. `homie-studio chrome install` puts Chrome for Testing in this user's cache (from
+ * storage.googleapis.com, which a Claude Code cloud session's default "Trusted" network reaches), and the
+ * checks render WebGL with SwiftShader (`--enable-unsafe-swiftshader`, needed since Chrome 137), headless,
+ * without the setuid sandbox when they run as root (as a container does). What they measure there is seats,
+ * rooms and rounds on the room's own clock; a frame rate on SwiftShader is not a person's, so the checks
+ * report it with the renderer's name and never judge it.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Where `homie-studio chrome install` keeps Chrome for Testing (one copy per user, shared by every studio). */
+export const CHROME_CACHE = join(homedir(), '.cache', 'homie-studio', 'chrome');
+
+/** The newest build of `browser` in a @puppeteer/browsers or Playwright cache, or null. */
+function newestIn(dir, rel) {
+  if (!existsSync(dir)) return null;
+  const builds = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
+    .sort((a, b) => b.localeCompare(a, 'en', { numeric: true }));
+  for (const b of builds) {
+    for (const r of rel) {
+      const path = join(dir, b, ...r);
+      if (existsSync(path)) return path;
+    }
+  }
+  return null;
+}
+
+/** Chrome for this machine: CHROME_PATH, an installed Chrome, or one in a known cache. */
+export function findChrome() {
+  const fixed = [
+    process.env.CHROME_PATH,
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/opt/google/chrome/chrome',
+  ].filter(Boolean);
+  const found = fixed.find((p) => existsSync(p));
+  if (found) return found;
+  const home = homedir();
+  return newestIn(join(CHROME_CACHE, 'chrome'), [['chrome-linux64', 'chrome'], ['chrome-mac-arm64', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing'], ['chrome-mac-x64', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing']])
+    ?? newestIn(join(home, '.cache', 'puppeteer', 'chrome'), [['chrome-linux64', 'chrome']])
+    ?? newestIn(join(home, '.cache', 'ms-playwright'), [['chrome-linux', 'chrome'], ['chrome-linux64', 'chrome']]);
+}
+
+/** Linux without a GPU renders with SwiftShader: say so with every number measured there. */
+export const SOFTWARE_GL = /swiftshader|llvmpipe|softpipe|software/i;
+
+/*
+ * Chrome's own sandbox needs unprivileged user namespaces. Running as root (a container), or on a Linux that
+ * restricts them with AppArmor (Ubuntu 23.10 and later: a system Chrome package brings its own AppArmor profile,
+ * Chrome for Testing does not), Chrome refuses to start without --no-sandbox. The checks only open the studio's
+ * own site, in throwaway profiles.
+ */
+function noSandboxNeeded() {
+  if (typeof process.getuid === 'function' && process.getuid() === 0) return true;
+  try { return readFileSync('/proc/sys/kernel/apparmor_restrict_unprivileged_userns', 'utf8').trim() === '1'; } catch { return false; }
+}
+
+/** The launch flags for this machine (the GPU on a Mac; SwiftShader, headless and container-safe on Linux). */
+export function chromeArgs() {
+  if (process.platform === 'darwin') return ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist'];
+  return [
+    '--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist', '--disable-dev-shm-usage',
+    ...(noSandboxNeeded() ? ['--no-sandbox'] : []),
+  ];
+}
+
+/** Why there is no Chrome, and the one command that fixes it on this machine. */
+export function noChrome() {
+  return process.platform === 'linux'
+    ? 'no Chrome on this machine: run `npx --no-install homie-studio chrome install` (Chrome for Testing into .cache/homie-studio in the home folder, from storage.googleapis.com), or set CHROME_PATH'
+    : 'no Chrome found: install Google Chrome, or set CHROME_PATH';
+}
+
+/**
+ * `homie-studio chrome install`: Chrome for Testing (stable) into CHROME_CACHE, through @puppeteer/browsers (it comes
+ * with puppeteer-core). About 170 MB, once per user; a second run finds it and downloads nothing.
+ */
+export async function installChrome({ log = () => {}, fresh = false } = {}) {
+  // `fresh`: Chrome for Testing even when the machine has a Chrome (what a machine without one would get).
+  const existing = fresh ? null : findChrome();
+  if (existing) return { ok: true, command: 'chrome install', chrome: existing, already: true };
+  let browsers;
+  try { browsers = await import('@puppeteer/browsers'); } catch { return { ok: false, command: 'chrome install', why: '@puppeteer/browsers is missing (it comes with @homie-rocks/studio: npm install)' }; }
+  const platform = browsers.detectBrowserPlatform();
+  if (!platform) return { ok: false, command: 'chrome install', why: `Chrome for Testing has no build for ${process.platform} ${process.arch}` };
+  const buildId = await browsers.resolveBuildId(browsers.Browser.CHROME, platform, 'stable');
+  log(`downloading Chrome for Testing ${buildId} (${platform}) into ${CHROME_CACHE}`);
+  const got = await browsers.install({ browser: browsers.Browser.CHROME, buildId, cacheDir: CHROME_CACHE });
+  return { ok: true, command: 'chrome install', chrome: got.executablePath, buildId, platform };
+}
+
+/**
+ * The frame rate a page's game frame draws at, over `ms` (requestAnimationFrame in the game's own frame, or the
+ * page's), and the renderer WebGL reports there. Never throws: { fps: null } when it cannot tell.
+ */
+export async function measureFrames(page, ms = 2000) {
+  const frame = page.frames().find((f) => /\/__game\//.test(f.url())) ?? page.mainFrame();
+  // Runs inside the frame (puppeteer sends the function itself, so a game's CSP never blocks it).
+  const probe = (span) => new Promise((resolve) => {
+    let renderer = null;
+    try {
+      const c = document.createElement('canvas');
+      const gl = c.getContext('webgl2') || c.getContext('webgl');
+      const d = gl && gl.getExtension('WEBGL_debug_renderer_info');
+      renderer = gl ? String(d ? gl.getParameter(d.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER)) : 'no WebGL';
+    } catch { renderer = null; }
+    let n = 0;
+    const t0 = performance.now();
+    const tick = () => { n++; if (performance.now() - t0 < span) requestAnimationFrame(tick); else resolve({ fps: Math.round((n * 1000) / (performance.now() - t0)), renderer }); };
+    requestAnimationFrame(tick);
+  });
+  try {
+    return await Promise.race([
+      frame.evaluate(probe, ms),
+      new Promise((r) => setTimeout(() => r({ fps: null, renderer: null }), ms + 5000)),
+    ]);
+  } catch { return { fps: null, renderer: null }; }
+}