@homie-rocks/studio 0.7.0 → 0.9.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.7.0.tgz homie-studio new ./night-owls --name "Night Owls"
+npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-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
@@ -19,6 +19,7 @@ npx homie-studio deploy --plan                         # what deploy will create
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
 npx homie-studio stats                                 # the studio's own numbers, for its owner
+npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
 ## The site: the hub's shape, and a landing for every game
@@ -33,8 +34,30 @@ live rooms, credits (the original and its licence for a port), and "Make a game
 files. `site/SITE.md` says all of it.
 
 The play page writes its room into the address, and a small room button at the edge shares it: Invite, Big
-screen and the room code. Every HTML answer is `no-transform`, and the site's pages are never framed by another
-site.
+screen and the room code. game.json's `screen.share` puts it where each game has room, per device (a corner or
+the top's middle, moved in by `x` / `y`, or kept a small icon), so it never covers a scoreboard. A game whose
+picture is white or cream gets a light landing (`landing.scheme: "light"`). Every card and the directory show a
+game's landing still. Every HTML answer is `no-transform`, and the site's pages are never framed by another
+site. A game made with Homie's arcade controls that knocks for a Homie box (`/__homie/call`) is told
+`not-a-homie`, at the site's root as under the game.
+
+## Upgrading a studio
+
+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
+npm install && npm run build
+```
+
+`upgrade` compares the studio with what this version's `new` would write for it: an AGENTS.md section, a README,
+a `.gitignore` line, a D1 migration or a package.json script it lacks is added, and one it never changed since an
+older template wrote it (`lib/template-history.json` knows every earlier version's text by a fingerprint) takes
+the newer text. Anything the studio changed or wrote itself is kept as it is: the plan lists it, and `--diff`
+shows how it differs from the template. `--apply` also pins this version in package.json and sets studio.json's
+`homie.studio`. When the template's words change, `node scripts/studio-template-history.mjs` records them (a test
+fails until it has).
 
 ## Rooms of up to 32
 
@@ -64,6 +87,34 @@ npx homie-studio stats share on                         # tell the directory "pl
 Each key is minted on the owner's computer; only its SHA-256 goes into D1, through the
 studio's own Cloudflare login. `worker/stats.mjs` says exactly what is counted.
 
+## A build the person can watch (the progress feed)
+
+A build of a game, song or video can keep a small progress feed, so the person follows it
+from wherever they are (the Claude app on a phone, through the Homie MCP's build progress
+card), sees each check go green, what it spent against its budget, and can press Stop:
+
+```sh
+npx homie-studio progress start crown-thief --share --title "Crown Thief: faster rounds" --budget 2
+npx homie-studio progress stage plan done --note "Rounds from 60 s to 45 s"
+npm run build && npx homie-studio check crown-thief --url http://127.0.0.1:8787 && npm run deploy
+```
+
+While a feed is open, `build`, `check`, `port check` and `deploy` report into it by
+themselves: their stage (a game: plan → build → checks → deploy), each check as it runs
+and passes, a small picture of the game and the address to play it; a deploy with every
+check green ends the build. The AI marks what only it knows with `progress stage`,
+`progress check`, `progress spend`, `progress shot` (a video's shots) and `progress song`
+(a song's waveform and lyric check). Before each stage starts, and every few seconds while
+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.
+
+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
+96 KB), never a key, a path or code. Its write key stays in `.studio/progress/` and is
+never printed; the shared id is printed for the MCP tool `build_progress`. Without an open
+feed every command behaves exactly as before. `lib/progress.mjs` has the whole format.
+
 ## The site's address
 
 `deploy` keeps the `workers.dev` address in `.studio/local.json`, which git ignores: it
@@ -107,7 +158,8 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `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. |
+| `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/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |
 | `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`. |

package/bin/homie-studio.mjs

@@ -23,12 +23,34 @@
  *   homie-studio media put <file> [--as <key>]
  *   homie-studio media list
  *   homie-studio status
+ *   homie-studio upgrade [--apply] [--diff]
+ *                                         (what this version's template adds to an existing studio: AGENTS.md
+ *                                          sections, READMEs, .gitignore lines, the pin; changes nothing until
+ *                                          --apply, and never a file or section the studio changed)
  *   homie-studio stats [--range 1d|7d|30d|90d] [--game <id> | --song <slug> | --video <slug>] [--url <site>]
  *   homie-studio stats key [--hours 1]    (a read key for the Homie MCP tool studio_stats)
  *   homie-studio stats link               (a one-time link to the private stats page, for the owner's browser)
  *   homie-studio stats revoke             (every stats key and page session ends)
  *   homie-studio stats share on|off       (tell the homie.rocks directory "played this week", or stop)
  *
+ *   homie-studio progress start [<id>] [--what game|song|video] [--title "<what this build does>"]
+ *                                        [--budget <dollars>] [--unit usd|credits] [--share]
+ *                                         (a progress feed for one build; --share shows it in the Claude app
+ *                                          through the Homie MCP's build_progress widget, which can press Stop)
+ *   homie-studio progress stage <stage> running|done|failed|skipped [--note "<one line>"]
+ *   homie-studio progress check <id> pending|running|pass|fail|skip [--label "<words>"] [--note "<one line>"]
+ *   homie-studio progress preview [--url <address>] [--image <small .jpg/.png>] [--caption "<words>"]
+ *   homie-studio progress spend <amount> --what "<what it bought>" [--receipt <file>]
+ *   homie-studio progress shot <id> pending|running|pass|fail [--label "<words>"] [--image <small .jpg>]
+ *   homie-studio progress song [--peaks <peaks.json>] [--lyric "<line>" --sung yes|no]
+ *   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 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.
+ *
  * Every command prints a few lines for a person; --json prints the result.
  */
 import { spawn, spawnSync } from 'node:child_process';
@@ -43,13 +65,15 @@ import { importPort, planPort } from '../lib/port.mjs';
 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 { 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';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop'];
+const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -155,9 +179,57 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    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}`,
+        ...(result.shared ? [`  shared for the Claude app until ${result.shared.expiresAt ?? 'tomorrow'}: ${result.widget}`] : []),
+        ...(result.sharedWhy ? [`  ${result.sharedWhy}`] : []),
+        '  build, check, port check and deploy now report into it; mark the plan done with: npx --no-install homie-studio progress stage plan done --note "<the plan in one line>"');
+      break;
+    case 'progress':
+      lines.push(result.message ?? `${result.feed?.title}: ${result.feed?.state}${result.feed?.stage ? ` (${result.feed.stage})` : ''}`);
+      break;
+    case 'progress show': {
+      const f = result.feed;
+      const mark = { done: 'ok  ', pass: 'ok  ', running: '... ', failed: 'FAIL', fail: 'FAIL', skipped: 'skip', skip: 'skip', stopped: 'stop', pending: '    ' };
+      lines.push(`${f.title} [${f.state}] build ${f.build}${f.shared ? ` (shared as ${f.shared.build})` : ''}`,
+        ...f.stages.map((s) => `  ${mark[s.state] ?? s.state} ${s.label}${s.note ? `: ${s.note}` : ''}`),
+        ...f.checks.map((c) => `      ${mark[c.state] ?? c.state} ${c.label}${c.note ? `: ${c.note}` : ''}`),
+        ...(f.preview?.url ? [`  preview: ${f.preview.url}`] : []),
+        `  spent ${f.spend.unit === 'usd' ? `$${f.spend.used.toFixed(2)}` : `${f.spend.used} credits`}${f.spend.budget !== null ? ` of ${f.spend.unit === 'usd' ? `$${f.spend.budget.toFixed(2)}` : `${f.spend.budget} credits`}` : ''}`,
+        ...(f.stop?.requested ? [`  stop asked (${f.stop.by}) at ${f.stop.at}`] : []));
+      break;
+    }
     case 'look':
       lines.push(`${result.ok ? 'Looks right' : 'Look again'}: ${result.rows.length} views of ${result.url}`, ...result.rows.map((r) => `  ${r.ok ? 'ok  ' : 'FIX '} ${r.path} on ${({ computer: 'a computer', phone: 'a phone', sideways: 'a phone turned sideways' })[r.device] ?? r.device}${r.problems.length ? `: ${r.problems.join('; ')}` : ''}`), '', `Pictures (open them and look): ${result.shots}`);
       break;
+    case 'upgrade': {
+      const show = (text, n = 14) => { const l = String(text ?? '').replace(/\n+$/, '').split('\n'); return [...l.slice(0, n).map((x) => `      ${x}`), ...(l.length > n ? [`      … (${l.length - n} more lines; --json has all of it)`] : [])]; };
+      const mark = { 'add-file': '+', 'add-section': '+', 'add-lines': '+', scripts: '+', 'update-file': '~', 'update-section': '~', pin: '~', version: '~' };
+      const list = result.applied ? result.done : result.changes;
+      lines.push(result.applied
+        ? `${result.studio} is on the @homie-rocks/studio ${result.to} template now (${list.length} change${list.length === 1 ? '' : 's'}).`
+        : list.length ? `${result.studio}: what the @homie-rocks/studio ${result.to} template adds (from ${result.from ?? 'an older version'}). Nothing is changed until --apply.` : `${result.studio} has everything the @homie-rocks/studio ${result.to} template writes.`);
+      if (list.length) lines.push('');
+      for (const c of list) {
+        lines.push(`  ${mark[c.kind] ?? '·'} ${c.file.padEnd(18)} ${c.what}${c.kind === 'add-section' && (c.after || c.before) ? ` (${c.after ? `after "${c.after}"` : `before "${c.before}"`})` : ''}`);
+        if (result.applied) continue;
+        if (c.kind === 'add-section' || (c.kind === 'add-file' && c.file.endsWith('.md'))) lines.push(...show(c.text));
+        if (c.kind === 'update-section' || c.kind === 'update-file') lines.push(...lineDiff(c.from, c.text).map((x) => `      ${x}`));
+      }
+      for (const c of result.skipped ?? []) lines.push(`  ! ${c.file.padEnd(18)} not applied: ${c.why}`);
+      if (result.kept?.length) {
+        lines.push('', 'Kept as this studio wrote them (never changed by upgrade; the template\'s text differs):');
+        for (const k of result.kept) {
+          lines.push(`  = ${k.file.padEnd(18)} ${k.what}`);
+          if (flags.has('diff') && k.mine !== undefined) lines.push(...lineDiff(k.mine, k.template).map((x) => `      ${x}`));
+        }
+        if (!flags.has('diff')) lines.push('  (--diff shows how each differs from the template: "-" this studio\'s lines, "+" the template\'s)');
+      }
+      if (result.uncommitted && !result.applied && result.changes.length) lines.push('', `Note: ${result.uncommitted} file(s) have uncommitted changes; commit them first so the upgrade is a change of its own.`);
+      if (result.next?.length) lines.push('', 'Next:', ...result.next.map((n) => `  ${n}`));
+      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`));
@@ -181,28 +253,33 @@ async function main() {
 
   if (cmd === 'port' && sub === 'plan') return planPort(positional[2] ?? '.');
   const root = requireStudio();
+  if (cmd === 'progress') return progressCommand(root, sub);
   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;
     const url = flags.get('url') ?? siteUrl(root);
     if (!url) return { ok: false, command: 'port check', why: 'give --url (the local dev address or the live site)' };
-    return portCheck({ url, game, root, only: flags.get('only') ?? null, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log });
+    return tracked(root, 'checks', (report) => portCheck({ url, game, root, only: flags.get('only') ?? null, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log, report }), 'port check');
   }
   if (cmd === 'game' && sub === 'new') return newGame(root, positional[2], { from: flags.get('from') ?? 'gem-rush', name: flags.get('name') });
   if (cmd === 'game' && sub === 'remix') return remixGame(root, positional[2], flags.get('id'), { name: flags.get('name') });
   if (cmd === 'games') return { ok: true, command: 'games', games: listGames(root).map(({ dir, ...g }) => ({ ...g, dir: relative(root, dir) })) };
-  if (cmd === 'build') return build(root, { only: positional[1] ?? null, log });
+  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log }), 'build');
   if (cmd === 'status') {
     const studio = readStudio(root);
     return { ok: true, command: 'status', root, studio, site: siteUrl(root, studio), games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && whoami(root)) };
   }
+  if (cmd === 'upgrade') {
+    const plan = upgradePlan(root);
+    return flags.has('apply') || flags.has('yes') ? upgradeApply(root, plan) : plan;
+  }
   if (cmd === 'dev' && flags.has('stop')) return stopDev(root);
   if (cmd === 'dev') return dev(root);
   if (cmd === 'check') {
     const game = positional[1] ?? listGames(root)[0]?.id;
     const url = flags.get('url') ?? siteUrl(root);
     if (!url) return { ok: false, command: 'check', why: 'give --url (the local dev address or the live site)' };
-    return check({ url, game, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log });
+    return tracked(root, 'checks', (report) => check({ url, game, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log, report }), 'check');
   }
   if (cmd === 'look') {
     const url = flags.get('url') ?? siteUrl(root);
@@ -218,7 +295,7 @@ 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);
-  if (cmd === 'deploy') return deploy(root, { log, homie: flags.get('homie') });
+  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') {
     const cf = readStudio(root).cloudflare ?? {};
@@ -241,6 +318,94 @@ async function main() {
   return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
 }
 
+/*
+ * THE PROGRESS FEED (lib/progress.mjs). A command that is a stage of the open build (build, check, port check,
+ * deploy) says so: the stage runs, then is done or failed with one line; a check's steps go green as they pass; a
+ * stop asked in the Claude app (or by `progress stop`) ends it at the next safe point. With no open feed, or a
+ * feed whose build has no such stage (a song has no deploy), the command runs exactly as it did before.
+ */
+async function tracked(root, stage, run, command) {
+  const feed = currentFeed(root);
+  if (!feed || !feed.doc.stages.some((s) => s.id === stage)) return run(null);
+  await feed.sync();
+  if (feed.stopRequested()) {
+    feed.stage(stage, 'stopped', 'stopped by the person before it started');
+    feed.end('stopped', 'Stopped by the person.');
+    return { ok: false, command, stopped: true, why: 'stopped by the person (in the Claude app, or `progress stop`): the build is over; ask them before starting again' };
+  }
+  if (stage === 'checks') feed.resetChecks('checks');
+  feed.stage(stage, 'running');
+  const report = {
+    check: (id, state, opts) => feed.check(id, state, { ...opts, stage }),
+    preview: (p) => feed.preview(p),
+    stopped: () => feed.stopRequested(),
+    state: (id) => feed.doc?.checks.find((c) => c.id === id)?.state,
+  };
+  let result;
+  try { result = await run(report); } catch (error) { feed.stage(stage, 'failed', error instanceof Error ? error.message : String(error)); throw error; }
+  if (result?.stopped || feed.stopRequested()) {
+    feed.stage(stage, 'stopped', 'stopped by the person');
+    feed.end('stopped', 'Stopped by the person.');
+    return { ...result, ok: false, stopped: true, why: result?.why ?? 'stopped by the person' };
+  }
+  if (!result?.ok) { feed.stage(stage, 'failed', result?.why ?? 'failed'); return result; }
+  const note = stage === 'build' ? `Built ${(result.games ?? []).map((g) => `${g.id} (${Math.round(g.bytes / 1024)} KB)`).join(', ') || 'the site'}`
+    : stage === 'deploy' ? `Live: ${result.url ?? 'deployed'}`
+      : result.command === 'port check' ? `${result.passed.length} passed${result.skipped.length ? `, ${result.skipped.length} skipped` : ''} in ${Math.round(result.totalMs / 1000)} s`
+        : `Room ${result.room}: round ${result.round?.n} finished with ${result.round?.humans} people in ${Math.round(result.totalMs / 1000)} s`;
+  feed.stage(stage, 'done', note);
+  if (stage === 'deploy') {
+    const doc = feed.doc;
+    const game = (result.games ?? []).find((g) => g.id === doc.id) ?? (result.games ?? [])[0];
+    if (game?.play) feed.preview({ url: game.play });
+    // Deployed, and every check that ran passed: the build is done.
+    if (doc.checks.every((c) => ['pass', 'skip'].includes(c.state))) feed.end('passed', `Live: ${game?.play ?? result.url}`);
+  }
+  return result;
+}
+
+async function progressCommand(root, sub) {
+  const arg = positional[2];
+  if (sub === 'start') {
+    return startProgress(root, {
+      what: flags.get('what') ?? 'game', id: arg ?? flags.get('id') ?? null, title: flags.get('title'),
+      budget: flags.get('budget'), unit: flags.get('unit'), share: flags.has('share'), directory: flags.get('homie'),
+    });
+  }
+  if (sub === 'show') {
+    const id = arg ?? currentId(root) ?? flags.get('build');
+    const doc = readFeed(root, id);
+    return doc ? { ok: true, command: 'progress show', feed: publicFeed(doc) } : { ok: false, command: 'progress show', why: id ? `no feed ${id} in .studio/progress/` : 'no build is open (homie-studio progress start)' };
+  }
+  const id = flags.get('build') ?? currentId(root);
+  if (!id || !readFeed(root, id)) return { ok: false, command: 'progress', why: 'no build is open: start one with `homie-studio progress start <id> --share`' };
+  const feed = new Feed(root, id);
+  const done = (message) => ({ ok: true, command: 'progress', build: id, message, feed: publicFeed(feed.doc) });
+  const note = flags.has('note') ? String(flags.get('note')) : undefined;
+  try {
+    switch (sub) {
+      case 'stage': feed.stage(arg, positional[3], note); return done(`${arg}: ${positional[3]}`);
+      case 'check': feed.check(arg, positional[3], { label: flags.get('label'), note }); return done(`check ${arg}: ${positional[3]}`);
+      case 'preview': feed.preview({ url: flags.get('url'), image: flags.get('image') ? resolve(String(flags.get('image'))) : undefined, caption: flags.get('caption') }); return done('preview updated');
+      case 'spend': feed.spend(arg, flags.get('what'), { receipt: flags.get('receipt'), unit: flags.get('unit') }); {
+        const s = feed.doc.spend;
+        return done(`spent ${s.unit === 'usd' ? `$${s.used.toFixed(2)}` : `${s.used} credits`}${s.budget !== null ? ` of ${s.unit === 'usd' ? `$${s.budget.toFixed(2)}` : `${s.budget} credits`}` : ''}`);
+      }
+      case 'shot': feed.shot(arg, positional[3], { label: flags.get('label'), image: flags.get('image') ? resolve(String(flags.get('image'))) : undefined }); return done(`shot ${arg}: ${positional[3]}`);
+      case 'song': {
+        const peaks = flags.get('peaks') ? JSON.parse(readFileSync(resolve(String(flags.get('peaks'))), 'utf8')) : undefined;
+        const sung = flags.get('sung') === 'yes' ? true : flags.get('sung') === 'no' ? false : null;
+        feed.song({ peaks: Array.isArray(peaks) ? peaks : peaks?.peaks, lyric: flags.get('lyric'), sung });
+        return done('song updated');
+      }
+      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 '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)` };
+    }
+  } catch (error) { return { ok: false, command: 'progress', why: error instanceof Error ? error.message : String(error) }; }
+}
+
 /*
  * WHICH DEV SERVER IS THIS STUDIO'S. `dev` writes its own PID and Wrangler's to site/.wrangler/homie-dev.json,
  * and `dev --stop` stops exactly those two (each checked to still be a process of this studio's folder), so an AI
@@ -325,11 +490,14 @@ function mediaPut(root, file, as) {
 
 try {
   const result = await main();
+  // A shared progress feed sends its last word before the command exits.
+  await flushProgress();
   if (result && result.command !== 'help') print(result);
   if (result?.ok === false) process.exitCode = 1;
   // Chrome's pipes can outlive browser.close(); a finished check must not hang its caller.
   if (result?.command === 'check' || result?.command === 'port check' || result?.command === 'look') process.exit(process.exitCode ?? 0);
 } catch (error) {
+  await flushProgress().catch(() => {});
   print({ ok: false, why: error instanceof Error ? error.message : String(error) });
   process.exitCode = 1;
 }

package/lib/build.mjs

@@ -208,6 +208,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       },
       // 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.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 } } : {}),
     },
     games: rows,
     songs: media.songs,

package/lib/check.mjs

@@ -4,9 +4,20 @@
  * phone) press Play, land in the SAME public room, play, and both see the round
  * finish. Exit 0 only when all of that happened. Uses this Mac's Chrome through
  * puppeteer-core, on the GPU (a software renderer fakes a stuck game).
+ *
+ * `report` (optional; the open progress feed, lib/progress.mjs) hears each step as it goes green or red, gets a
+ * small picture of the computer's view, and can ask the check to stop: then the browsers close and the result
+ * says `stopped`. Without it the check is exactly what it was.
+ *
+ * UNDER LOAD (a busy computer, another project's browsers): Chrome gets 150 s to start, a page 90 s to open and a
+ * seat 90 s. A browser that stalls for 10 s is let go by the relay and comes back with its seat token; the round it
+ * was away for lists its body as a bot, so that round cannot prove anything and the check waits for the next one
+ * (up to `rounds` rounds). A person the game lists as a bot while it keeps their seat (an idle player driven by
+ * 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 { tmpdir } from 'node:os';
+import { cpus, loadavg, tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 const CHROMES = [
@@ -18,7 +29,39 @@ const CHROMES = [
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-export async function check({ url, game, roundTimeoutMs = 150_000, shots = null, userAgentTag = 'homie-studio-check', log = () => {} }) {
+/** The steps a progress feed shows for this check, in order. */
+/** Chrome's own start, on a loaded computer (a cold start there took over a minute). */
+export const LAUNCH_TIMEOUT_MS = 150_000;
+
+export const CHECK_STEPS = [
+  ['computer-seated', 'A computer gets a seat'],
+  ['phone-seated', 'A phone gets a seat'],
+  ['same-room', 'Both in the same public room'],
+  ['round', 'They finish a round together'],
+];
+
+class Stopped extends Error {}
+
+/**
+ * WHICH FINISHED ROUND PROVES THE TWO BROWSERS PLAYED TOGETHER. `browsers`: each `{ kind, seats, seen }`, where
+ * `seats` is every seat it held (a Set) and `seen` the rounds it saw finish after both were seated (a Map from
+ * `n:endsAt` to `{ n, endsAt, results, ms }`). A round counts when both saw it and each has a row carrying one of
+ * its seats, whatever the row's `bot` says (a game may hand an idle person's body to its autopilot and still keep
+ * their seat on the row: that is still the person). A round seen by both without one of them is a miss, kept in
+ * `missed` with who was missing and the rows, so the check can say why. Returns the round that counts, or null.
+ */
+export function judgeRounds(browsers, missed = new Map()) {
+  const mine = new Set(browsers.flatMap((b) => [...b.seats]));
+  for (const [key, r] of browsers[0]?.seen ?? []) {
+    if (missed.has(key) || !browsers.every((b) => b.seen.has(key))) continue;
+    const absent = browsers.filter((b) => !(r.results ?? []).some((row) => b.seats.has(row?.seat))).map((b) => b.kind);
+    if (!absent.length) return { ...r, key, overMs: browsers.map((b) => b.seen.get(key).ms), people: r.results.filter((row) => !row?.bot || mine.has(row?.seat)).length };
+    missed.set(key, { n: r.n, missing: absent, rows: (r.results ?? []).slice(0, 12).map((row) => ({ seat: row?.seat ?? null, name: row?.name ?? null, bot: Boolean(row?.bot) })) });
+  }
+  return null;
+}
+
+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)' };
@@ -35,12 +78,29 @@ export async function check({ url, game, roundTimeoutMs = 150_000, shots = null,
     { name: 'phone', viewport: { width: 390, height: 844, isMobile: true, hasTouch: true, deviceScaleFactor: 2 } },
   ];
   const players = [];
+  // The playing loop runs until this is false: the round is settled, or the check ends in any way (finally).
+  let playingOn = true;
+  const step = (id, state, opts = {}) => { try { report?.check?.(id, state, { label: CHECK_STEPS.find(([k]) => k === id)?.[1], ...opts }); } catch { /* a feed never breaks a check */ } };
+  const halt = () => { if (report?.stopped?.()) throw new Stopped('stopped by the person'); };
+  // The computer's view, small (480 px wide), for the feed's preview.
+  const picture = async (caption) => {
+    if (!report?.preview || !players[0]) return;
+    try {
+      const vp = kinds[0].viewport;
+      const b64 = await players[0].page.screenshot({ type: 'jpeg', quality: 62, clip: { x: 0, y: 0, width: vp.width, height: vp.height, scale: 480 / vp.width }, encoding: 'base64' });
+      report.preview({ url: play, image: `data:image/jpeg;base64,${b64}`, caption });
+    } catch { /* no picture this time */ }
+  };
+  for (const [id] of CHECK_STEPS) step(id, 'pending');
   try {
+    halt();
+    step('computer-seated', 'running');
+    step('phone-seated', 'running');
     for (const kind of kinds) {
       const profile = mkdtempSync(join(tmpdir(), 'homie-studio-check-'));
       profiles.push(profile);
       const browser = await puppeteer.launch({
-        executablePath: chrome, headless: true, userDataDir: profile,
+        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'],
       });
       browsers.push(browser);
@@ -49,74 +109,119 @@ export async function check({ url, game, roundTimeoutMs = 150_000, shots = null,
       const ua = await browser.userAgent();
       await page.setUserAgent(`${ua} ${userAgentTag}`);
       const t0 = Date.now();
-      await page.goto(play, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+      await page.goto(play, { waitUntil: 'domcontentloaded', timeout: 90_000 });
       players.push({ kind: kind.name, page, t0 });
       log(`${kind.name} opened ${play}`);
     }
     // Seated: the shell knows its room and the game reported a seat.
     const seated = await Promise.all(players.map(async (p) => {
-      const deadline = Date.now() + 45_000;
+      const deadline = Date.now() + 90_000;
       while (Date.now() < deadline) {
         const s = await p.page.evaluate(() => { const s = window.__shell; return s ? { room: s.room, seat: s.seat, role: s.stats?.role ?? null, players: s.facts?.counts?.players ?? null } : null; }).catch(() => null);
-        if (s?.room && s.seat !== null && s.seat !== undefined && s.role) { p.seatedAt = Date.now(); p.seat = s.seat; return { ...s, ms: Date.now() - p.t0 }; }
+        if (s?.room && s.seat !== null && s.seat !== undefined && s.role) {
+          p.seatedAt = Date.now(); p.seat = s.seat;
+          step(`${p.kind}-seated`, 'pass', { ms: Date.now() - p.t0, note: `seat ${s.seat}, ${s.role}` });
+          return { ...s, ms: Date.now() - p.t0 };
+        }
+        halt();
         await sleep(250);
       }
+      step(`${p.kind}-seated`, 'fail', { note: 'no seat within 90 s' });
       return null;
     }));
-    if (seated.some((s) => !s)) return { ok: false, command: 'check', why: 'a browser never got a seat within 45 s', seated };
+    if (seated.some((s) => !s)) return { ok: false, command: 'check', why: 'a browser never got a seat within 90 s', seated };
     const sameRoom = seated[0].room === seated[1].room;
     log(`seated: ${seated.map((s, i) => `${kinds[i].name} room ${s.room} seat ${s.seat} ${s.role}`).join('; ')}`);
+    step('same-room', sameRoom ? 'pass' : 'fail', { note: sameRoom ? `room ${seated[0].room}` : `rooms ${seated[0].room} and ${seated[1].room}` });
     if (!sameRoom) return { ok: false, command: 'check', why: `the two browsers landed in different rooms (${seated[0].room}, ${seated[1].room})`, seated };
-    // Play: the computer holds keys, the phone drags from the lower left.
+    step('round', 'running');
+    // Play: the computer holds keys; the phone drags from the lower left (a stick) and swipes across the bottom
+    // middle (a wheel, a slider). A game that hands an untouched player to its autopilot, or lets an idle one go,
+    // sees a hand on both. It plays until the check is over, through as many rounds as that takes.
     const playing = (async () => {
       const keys = ['KeyD', 'KeyS', 'KeyA', 'KeyW'];
-      for (let i = 0; Date.now() - started < roundTimeoutMs && i < 400; i++) {
+      const vp = kinds[1].viewport;
+      for (let i = 0; playingOn && i < 5000; i++) {
         const k = keys[i % keys.length];
         await players[0].page.keyboard.down(k).catch(() => {});
         await sleep(600);
         await players[0].page.keyboard.up(k).catch(() => {});
-        const vp = kinds[1].viewport;
-        await players[1].page.touchscreen.touchStart(vp.width * 0.2, vp.height * 0.8).catch(() => {});
-        await players[1].page.touchscreen.touchMove(vp.width * 0.2 + (i % 2 ? 60 : -60), vp.height * 0.8 - 40).catch(() => {});
+        const [x, y, dx, dy] = i % 3 === 2 ? [vp.width * 0.5, vp.height * 0.86, i % 2 ? 70 : -70, 0] : [vp.width * 0.2, vp.height * 0.8, i % 2 ? 60 : -60, -40];
+        await players[1].page.touchscreen.touchStart(x, y).catch(() => {});
+        await players[1].page.touchscreen.touchMove(x + dx, y + dy).catch(() => {});
         await sleep(300);
         await players[1].page.touchscreen.touchEnd().catch(() => {});
-        if (players.every((p) => p.over)) break;
+        if (report?.stopped?.()) break;
       }
     })();
     if (shots) for (const [i, p] of players.entries()) await p.page.screenshot({ path: join(shots, `${kinds[i].name}-playing.png`) }).catch(() => {});
-    // Only a round that finishes AFTER both browsers were seated, with BOTH of them in its results, counts: an
-    // idle room remembers its last round for a while, and that stale result proves nothing.
+    await sleep(1500);
+    await picture('Playing: computer and phone in one room');
+    // 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
+    // person's row as a bot, and that is still the person). A round finished without one of them is a miss: its
+    // cause is kept, and the check waits for the next round, up to `rounds` of them.
     const bothSeated = Math.max(...players.map((p) => p.seatedAt));
-    const seats = players.map((p) => p.seat);
-    const over = await Promise.all(players.map(async (p) => {
-      const deadline = Date.now() + roundTimeoutMs;
-      while (Date.now() < deadline) {
-        const r = await p.page.evaluate((after, want) => {
-          const s = window.__shell;
-          const hit = (s?.results ?? []).find((x) => x.at > after && want.every((seat) => x.results.some((row) => row.seat === seat)));
-          return hit ? { n: hit.n, endsAt: hit.endsAt, results: hit.results, room: s.room } : null;
-        }, bothSeated, seats).catch(() => null);
-        if (r) { p.over = true; return { ...r, ms: Date.now() - p.t0 }; }
-        await sleep(500);
+    for (const p of players) { p.seats = new Set([p.seat]); p.reconnects = null; p.reconnects0 = null; p.closed = null; p.seen = new Map(); }
+    const t1 = Date.now();
+    const budget = roundTimeoutMs * Math.max(1, rounds);
+    const missed = new Map();
+    let hit = null;
+    while (!hit && Date.now() - t1 < budget && missed.size < Math.max(1, rounds)) {
+      for (const p of players) {
+        const s = await p.page.evaluate(() => {
+          const sh = window.__shell;
+          return sh ? { seat: sh.seat, room: sh.room, closed: sh.closed, reconnects: sh.stats?.reconnects ?? null, results: (sh.results ?? []).map((x) => ({ n: x.n, endsAt: x.endsAt, at: x.at, results: x.results })) } : null;
+        }).catch(() => null);
+        if (!s) continue;
+        if (Number.isInteger(s.seat)) p.seats.add(s.seat);
+        if (Number.isFinite(s.reconnects)) { p.reconnects0 ??= s.reconnects; p.reconnects = s.reconnects; }
+        if (s.closed) p.closed = s.closed;
+        for (const r of s.results) if (r.at > bothSeated && Array.isArray(r.results) && !p.seen.has(`${r.n}:${r.endsAt}`)) p.seen.set(`${r.n}:${r.endsAt}`, { ...r, room: s.room, ms: Date.now() - p.t0 });
       }
-      return null;
-    }));
+      const before = missed.size;
+      hit = judgeRounds(players, missed);
+      for (const m of [...missed.values()].slice(before)) log(`round ${m.n} finished without the ${m.missing.join(' and the ')}: waiting for the next one`);
+      if (hit) break;
+      halt();
+      await sleep(700);
+    }
+    playingOn = false;
     await playing.catch(() => {});
     if (shots) for (const [i, p] of players.entries()) await p.page.screenshot({ path: join(shots, `${kinds[i].name}-round-over.png`) }).catch(() => {});
-    if (over.some((o) => !o)) return { ok: false, command: 'check', why: 'a browser did not see a round finish in time', seated, over };
-    const humans = over[0].results.filter((r) => !r.bot).length;
-    const sameRound = over[0].n === over[1].n && over[0].endsAt === over[1].endsAt && over[0].room === over[1].room;
+    const connection = players.map((p) => ({ browser: p.kind, seats: [...p.seats], reconnects: p.reconnects !== null && p.reconnects0 !== null ? p.reconnects - p.reconnects0 : null, closed: p.closed }));
+    const load = { perCore: +(loadavg()[0] / Math.max(1, cpus().length)).toFixed(2), average: +loadavg()[0].toFixed(1), cores: cpus().length };
+    if (!hit) {
+      const misses = [...missed.values()];
+      const dropped = connection.filter((c) => c.reconnects > 0).map((c) => `the ${c.browser} lost its connection ${c.reconnects} time${c.reconnects === 1 ? '' : 's'}`);
+      const why = misses.length
+        ? `${misses.length} round${misses.length === 1 ? '' : 's'} finished, and none had both browsers in it: ${misses.map((m) => `round ${m.n} left out the ${m.missing.join(' and the ')}`).join('; ')}.${dropped.length ? ` ${dropped.join(', ')} (a browser silent for 10 s is let go by the relay and its body plays as a bot until it is back).` : ' The game listed that seat\'s body as a bot with no seat: it may hand an idle player to a bot.'}${load.perCore > 1.5 ? ` This computer is busy (load ${load.average} on ${load.cores} cores): run the check again when it is quieter.` : ''}`
+        : `no round finished within ${Math.round(budget / 1000)} s of both browsers being seated${load.perCore > 1.5 ? ` (this computer is busy: load ${load.average} on ${load.cores} cores)` : ''}`;
+      step('round', 'fail', { note: misses.length ? `${misses.length} round(s) without both` : 'no round finished in time' });
+      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)` : ''}` });
+    await picture(`Round ${hit.n} finished with both; the next one is on`);
     return {
-      ok: sameRoom && sameRound && humans >= 2,
+      ok: sameRoom && humans >= 2,
       command: 'check',
       play,
       room: seated[0].room,
       seats: seated.map((s, i) => ({ browser: kinds[i].name, seat: s.seat, role: s.role, seatedMs: s.ms })),
-      round: { n: over[0].n, humans, bots: over[0].results.length - humans, results: over[0].results, overMs: over.map((o) => o.ms) },
-      why: !sameRound ? 'the two browsers saw different rounds finish' : humans >= 2 ? undefined : `the round's results list ${humans} human(s); both browsers should be in it`,
+      round: { n: hit.n, humans, bots: hit.results.length - humans, results: hit.results, overMs: hit.overMs },
+      ...(missed.size ? { missed: [...missed.values()] } : {}),
+      connection,
+      why: humans >= 2 ? undefined : `the round's results list ${humans} person(s); both browsers should be in it`,
       totalMs: Date.now() - started,
     };
+  } catch (error) {
+    if (!(error instanceof Stopped)) throw error;
+    for (const [id] of CHECK_STEPS) { try { if (['pending', 'running'].includes(report?.state?.(id))) step(id, 'skip', { note: 'stopped' }); } catch { /* fine */ } }
+    return { ok: false, command: 'check', stopped: true, why: 'stopped by the person', play, totalMs: Date.now() - started };
   } finally {
+    playingOn = false;
     for (const b of browsers) await b.close().catch(() => {});
     for (const p of profiles) rmSync(p, { recursive: true, force: true });
   }