@homie-rocks/studio 0.7.0 → 0.8.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.8.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
@@ -64,6 +64,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

package/bin/homie-studio.mjs

@@ -29,6 +29,24 @@
  *   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';
@@ -46,10 +64,11 @@ import { ensureStatsMigration, newStudio } from '../lib/scaffold.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'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -155,6 +174,27 @@ 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;
@@ -181,17 +221,18 @@ 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)) };
@@ -202,7 +243,7 @@ async function main() {
     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 +259,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 +282,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 +454,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/check.mjs

@@ -4,6 +4,10 @@
  * 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.
  */
 import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -18,7 +22,17 @@ 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. */
+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 {}
+
+export async function check({ url, game, roundTimeoutMs = 150_000, 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,7 +49,22 @@ 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 = [];
+  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);
@@ -58,15 +87,23 @@ export async function check({ url, game, roundTimeoutMs = 150_000, shots = null,
       const deadline = Date.now() + 45_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 45 s' });
       return null;
     }));
     if (seated.some((s) => !s)) return { ok: false, command: 'check', why: 'a browser never got a seat within 45 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 };
+    step('round', 'running');
     // Play: the computer holds keys, the phone drags from the lower left.
     const playing = (async () => {
       const keys = ['KeyD', 'KeyS', 'KeyA', 'KeyW'];
@@ -80,10 +117,12 @@ export async function check({ url, game, roundTimeoutMs = 150_000, shots = null,
         await players[1].page.touchscreen.touchMove(vp.width * 0.2 + (i % 2 ? 60 : -60), vp.height * 0.8 - 40).catch(() => {});
         await sleep(300);
         await players[1].page.touchscreen.touchEnd().catch(() => {});
-        if (players.every((p) => p.over)) break;
+        if (players.every((p) => p.over) || 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(() => {});
+    await sleep(1500);
+    await picture('Playing: computer and phone in one room');
     // 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.
     const bothSeated = Math.max(...players.map((p) => p.seatedAt));
@@ -97,15 +136,18 @@ export async function check({ url, game, roundTimeoutMs = 150_000, shots = null,
           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 }; }
+        halt();
         await sleep(500);
       }
       return null;
     }));
     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 };
+    if (over.some((o) => !o)) { step('round', 'fail', { note: 'no round finished in time' }); 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;
+    step('round', sameRound && humans >= 2 ? 'pass' : 'fail', { ms: Math.max(...over.map((o) => o.ms)), note: `round ${over[0].n}: ${humans} people, ${over[0].results.length - humans} bots` });
+    await picture(`Round ${over[0].n} finished with both; the next one is on`);
     return {
       ok: sameRoom && sameRound && humans >= 2,
       command: 'check',
@@ -116,6 +158,10 @@ export async function check({ url, game, roundTimeoutMs = 150_000, shots = null,
       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`,
       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 {
     for (const b of browsers) await b.close().catch(() => {});
     for (const p of profiles) rmSync(p, { recursive: true, force: true });

package/lib/port-check.mjs

@@ -379,7 +379,19 @@ async function ownerTests(h, how, log) {
 
 /* ------------------------------------------------------------------ the check */
 
-export async function portCheck({ url, game, root, only = null, shots = null, log = () => {}, roundTimeoutMs = 240_000 }) {
+/** What a progress feed calls each port check row. */
+export const PORT_CHECK_LABELS = {
+  'owner-desk': 'Moves on a computer', 'owner-phone': 'Moves on a phone', 'owner-iphone': 'Moves on an iPhone (WebKit)',
+  audio: 'Sound starts on the first touch', sandbox: 'Runs in the sandbox', 'ui-cover': 'UI stays out of the middle',
+  round: 'Two browsers finish a round', 'host-kill': 'The host leaves, the round goes on', 'late-join': 'A late joiner takes a bot\'s seat',
+  tv: 'The big screen watches', errors: 'No errors in the game',
+};
+
+/**
+ * `report` (optional; the open progress feed, lib/progress.mjs) hears each row as it runs, passes or fails, gets a
+ * small picture after each screenshot, and can ask the check to stop between rows. Without it nothing changes.
+ */
+export async function portCheck({ url, game, root, only = null, shots = null, log = () => {}, roundTimeoutMs = 240_000, report = null }) {
   if (!url || !game) throw new Error('usage: homie-studio port check <game> --url <site>');
   const base = String(url).replace(/\/+$/, '');
   const want = new Set((only ? String(only).split(',') : ALL).map((s) => s.trim()).filter(Boolean));
@@ -393,13 +405,21 @@ export async function portCheck({ url, game, root, only = null, shots = null, lo
   mkdirSync(out, { recursive: true });
   if (root) { try { writeFileSync(join(root, 'games', game, '.port', '.gitignore'), '*\n'); } catch { /* fine */ } }
   const rows = [];
-  const row = (name, ok, detail) => { rows.push({ name, ok, ...detail }); log(`${ok === null ? 'SKIP' : ok ? 'PASS' : 'FAIL'} ${name}${detail?.why ? `: ${detail.why}` : ''}`); };
+  const tell = (name, state, note) => { try { report?.check?.(name, state, { label: PORT_CHECK_LABELS[name] ?? name, ...(note ? { note } : {}) }); } catch { /* a feed never breaks a check */ } };
+  const row = (name, ok, detail) => { rows.push({ name, ok, ...detail }); log(`${ok === null ? 'SKIP' : ok ? 'PASS' : 'FAIL'} ${name}${detail?.why ? `: ${detail.why}` : ''}`); tell(name, ok === null ? 'skip' : ok ? 'pass' : 'fail', detail?.why); };
   const open_ = [];
   const launch = async (kind) => { const h = await chrome(puppeteer, kind, exe); open_.push(h); return h; };
   const close = async (h) => { const i = open_.indexOf(h); if (i >= 0) open_.splice(i, 1); await h.close(); };
-  const shot = async (h, name) => { await T(h.page.screenshot({ path: join(out, `${name}.png`) }), 15_000); };
+  const shot = async (h, name) => {
+    await T(h.page.screenshot({ path: join(out, `${name}.png`) }), 15_000);
+    if (report?.preview && h.vp) {
+      const b64 = await T(h.page.screenshot({ type: 'jpeg', quality: 60, clip: { x: 0, y: 0, width: h.vp.width, height: h.vp.height, scale: Math.min(1, 480 / h.vp.width) }, encoding: 'base64' }), 15_000, null);
+      if (b64) { try { report.preview({ url: `${base}/${game}/play`, image: `data:image/jpeg;base64,${b64}`, caption: PORT_CHECK_LABELS[name.replace(/-(?:before|after|playing|over|\d+)$/, '')] ?? name }); } catch { /* too big: no picture */ } }
+    }
+  };
   const privateRoom = (tag) => `chk-${stamp.slice(-6)}-${tag}`.slice(0, 32);
   const errorsSeen = [];
+  let stoppedAt = null;
   const collect = (h) => { for (const e of h.errors) errorsSeen.push(`${h.engine}-${h.kind}: ${e}`); for (const r of h.badResponses) errorsSeen.push(`${h.engine}-${h.kind}: HTTP ${r}`); };
   const started = Date.now();
   // The site must answer before each row: a dev server that died mid-check made every later row fail as "no game
@@ -408,6 +428,8 @@ export async function portCheck({ url, game, root, only = null, shots = null, lo
     try { const r = await fetch(`${base}/${game}/play`, { signal: AbortSignal.timeout(8000) }); return r.ok; } catch { return false; }
   };
   const gate = async (name) => {
+    if (report?.stopped?.()) { row(name, null, { why: 'stopped by the person' }); stoppedAt ??= name; return false; }
+    tell(name, 'running');
     if (await alive()) return true;
     row(name, false, { why: `${base} stopped answering: is the dev server still running? (restart it as a background task that outlives this command, then rerun the check)` });
     return false;
@@ -631,7 +653,7 @@ export async function portCheck({ url, game, root, only = null, shots = null, lo
   }
   const failed = rows.filter((r) => r.ok === false);
   const skipped = rows.filter((r) => r.ok === null);
-  const result = { ok: failed.length === 0 && rows.length > 0, command: 'port check', game, url: base, out, totalMs: Date.now() - started, passed: rows.filter((r) => r.ok === true).map((r) => r.name), failed: failed.map((r) => `${r.name}: ${r.why ?? 'failed'}`), skipped: skipped.map((r) => `${r.name}: ${r.why ?? ''}`), rows };
+  const result = { ok: failed.length === 0 && rows.length > 0 && !stoppedAt, command: 'port check', game, url: base, out, totalMs: Date.now() - started, ...(stoppedAt ? { stopped: true, why: `stopped by the person (before ${stoppedAt})` } : {}), passed: rows.filter((r) => r.ok === true).map((r) => r.name), failed: failed.map((r) => `${r.name}: ${r.why ?? 'failed'}`), skipped: skipped.map((r) => `${r.name}: ${r.why ?? ''}`), rows };
   writeFileSync(join(out, 'receipt.json'), `${JSON.stringify(result, null, 1)}\n`);
   return result;
 }

package/lib/progress.mjs

@@ -0,0 +1,420 @@
+/**
+ * THE PROGRESS FEED — what a build is doing right now, for a person watching from anywhere (a terminal, or the
+ * Homie MCP's build progress widget in the Claude app on a phone).
+ *
+ * One build is one small JSON document (kind "homie-studio-progress", v 1), rewritten whole at every step:
+ *
+ *   .studio/progress/<build>.json   the feed
+ *   .studio/progress/<build>.key    the shared copy's write key (only when shared; never printed, git-ignored)
+ *   .studio/progress/current        the open build's id
+ *
+ * The stages depend on what is being made:
+ *   a game   plan → build → checks → deploy
+ *   a song   plan → render → lyric check → publish
+ *   a video  plan → shots → cut → publish
+ *
+ * `homie-studio progress start` opens a feed. While one is open, `build`, `check`, `port check` and `deploy` write
+ * their stage into it, their checks as each goes green or red, and a preview (a small picture of the game and the
+ * address to play it), and they stop at the next safe point when a stop was asked. The AI marks what only it
+ * knows (the plan, money spent, a song's lyric check, a video's shots) with the other `progress` commands.
+ * WITHOUT AN OPEN FEED NOTHING CHANGES: every command behaves exactly as before.
+ *
+ * SHARED (`progress start --share`): the directory named in studio.json (homie.rocks by default) keeps a copy for
+ * 24 hours, so the Homie MCP tool `build_progress { build }` can show it in the Claude app, and answers every
+ * write with whether the person pressed Stop there. It receives the feed and nothing else: never a key, a file
+ * path, code, or more than the feed's last few log lines. Only a loopback directory may be plain http.
+ *
+ * The document (every text is plain, bounded; pictures are small data: URLs):
+ *   { v: 1, kind, build, what: game|song|video, id, title, studio,
+ *     state: running|passed|failed|stopped, stage, startedAt, updatedAt, endedAt,
+ *     stages: [{ id, label, state: pending|running|done|failed|skipped|stopped, startedAt, endedAt, note }],
+ *     checks: [{ id, label, stage, state: pending|running|pass|fail|skip, ms, note }],
+ *     preview: { url, image, caption, at } | null,
+ *     spend: { unit: usd|credits, used, budget, items: [{ what, amount, at, receipt }] },
+ *     stop: { requested, at, by },
+ *     song?: { peaks: [0..1], lyrics: [{ line, sung: true|false|null }] },
+ *     video?: { shots: [{ id, label, state, image }] },
+ *     log: [{ at, text }], error, shared?: { build, directory } }
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { readStudio } from './studio.mjs';
+
+export const PROGRESS_KIND = 'homie-studio-progress';
+export const PROGRESS_DIR = join('.studio', 'progress');
+export const STAGES = Object.freeze({
+  game: [['plan', 'Plan'], ['build', 'Build'], ['checks', 'Checks'], ['deploy', 'Deploy']],
+  song: [['plan', 'Plan'], ['render', 'Render'], ['check', 'Lyric check'], ['publish', 'Publish']],
+  video: [['plan', 'Plan'], ['shots', 'Shots'], ['cut', 'Cut'], ['publish', 'Publish']],
+});
+/** The same bounds the directory enforces on a shared feed. */
+export const LIMITS = Object.freeze({
+  title: 120, note: 200, label: 80, logLines: 12, logLine: 160, checks: 24, shots: 24, items: 50, peaks: 240, lyrics: 80,
+  image: 96 * 1024, shotImage: 32 * 1024, doc: 256 * 1024,
+});
+const STAGE_STATES = new Set(['pending', 'running', 'done', 'failed', 'skipped', 'stopped']);
+const CHECK_STATES = new Set(['pending', 'running', 'pass', 'fail', 'skip']);
+const END_STATES = new Set(['passed', 'failed', 'stopped']);
+const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const BUILD_ID = /^[a-z0-9][a-z0-9-]{5,63}$/;
+const REMOTE_ID = /^hb_[a-f0-9]{32}$/;
+const PUSH_GAP_MS = 1200;
+const HEARTBEAT_MS = 5000;
+const IMAGE_TYPES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };
+
+const now = () => new Date().toISOString();
+/** Plain text of at most `max` characters: no control characters, trimmed. */
+export const plain = (value, max) => String(value ?? '').replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+const dir = (root) => join(root, PROGRESS_DIR);
+const docPath = (root, id) => join(dir(root), `${id}.json`);
+const keyPath = (root, id) => join(dir(root), `${id}.key`);
+const currentPath = (root) => join(dir(root), 'current');
+const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
+
+function writeAtomic(file, text) {
+  const tmp = `${file}.${process.pid}.${randomBytes(3).toString('hex')}.tmp`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, file);
+}
+
+export function readFeed(root, id) {
+  if (!BUILD_ID.test(String(id ?? ''))) return null;
+  try { const d = JSON.parse(readFileSync(docPath(root, id), 'utf8')); return d?.kind === PROGRESS_KIND ? d : null; } catch { return null; }
+}
+
+/** The open build's id, or null. */
+export function currentId(root) {
+  try { const id = readFileSync(currentPath(root), 'utf8').trim(); return readFeed(root, id)?.state === 'running' ? id : null; } catch { return null; }
+}
+
+/** A picture for the feed: a data: URL as it is, or a png/jpg/webp file, at most `max` bytes. */
+export function imageData(value, max = LIMITS.image) {
+  const raw = String(value ?? '');
+  if (!raw) return null;
+  if (raw.startsWith('data:')) {
+    if (!/^data:image\/(?:png|jpeg|webp);base64,[A-Za-z0-9+/=]+$/.test(raw)) throw new Error('a picture is a data:image/png, jpeg or webp base64 URL, or a .png/.jpg/.webp file');
+    if (raw.length > Math.ceil(max * 4 / 3) + 40) throw new Error(`the picture is over ${Math.round(max / 1024)} KB; use a smaller JPEG`);
+    return raw;
+  }
+  const type = IMAGE_TYPES[extname(raw).toLowerCase()];
+  if (!type) throw new Error('a picture is a .png, .jpg or .webp file');
+  if (!existsSync(raw) || !statSync(raw).isFile()) throw new Error(`no picture at ${raw}`);
+  if (statSync(raw).size > max) throw new Error(`${raw} is over ${Math.round(max / 1024)} KB; use a smaller JPEG (about 480 px wide)`);
+  return `data:${type};base64,${readFileSync(raw).toString('base64')}`;
+}
+
+/* ------------------------------------------------------------------ the shared copy */
+
+const pushers = new Map();
+
+async function pushDoc(root, id) {
+  const doc = readFeed(root, id);
+  if (!doc?.shared?.build) return null;
+  let key = null;
+  try { key = readFileSync(keyPath(root, id), 'utf8').trim(); } catch { return null; }
+  const { shared, ...body } = doc;
+  const res = await fetch(`${shared.directory}/api/studio/progress/${shared.build}`, {
+    method: 'PUT',
+    headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json', 'user-agent': 'homie-studio' },
+    body: JSON.stringify({ ...body, build: shared.build }),
+    signal: AbortSignal.timeout(8000),
+  });
+  if (res.status === 404 || res.status === 410) {
+    // The shared copy ended (24 hours, or the directory dropped it): keep the local feed, stop sending.
+    mutateDoc(root, id, (d) => { d.shared = { ...d.shared, ended: true }; });
+    return null;
+  }
+  const reply = await res.json().catch(() => null);
+  if (reply?.stop) {
+    mutateDoc(root, id, (d) => {
+      if (!d.stop?.requested) { d.stop = { requested: true, at: now(), by: 'person' }; pushLog(d, 'Stop pressed in the Claude app; stopping at the next safe point.'); }
+    });
+  }
+  return reply;
+}
+
+function schedule(root, id, { soon = false } = {}) {
+  const doc = readFeed(root, id);
+  if (!doc?.shared?.build || doc.shared.ended) return;
+  const p = pushers.get(id) ?? { root, last: 0, timer: null, inflight: null, dirty: false, beat: null };
+  pushers.set(id, p);
+  p.dirty = true;
+  if (p.inflight) return;
+  const wait = soon ? 0 : Math.max(0, p.last + PUSH_GAP_MS - Date.now());
+  if (p.timer) { if (!soon) return; clearTimeout(p.timer); }
+  p.timer = setTimeout(() => { p.timer = null; send(id, p); }, wait);
+  p.timer.unref?.();
+}
+
+function send(id, p) {
+  p.dirty = false;
+  p.last = Date.now();
+  p.inflight = pushDoc(p.root, id).catch(() => null).finally(() => {
+    p.inflight = null;
+    if (p.dirty) schedule(p.root, id);
+  });
+  return p.inflight;
+}
+
+/** While a stage runs, re-send the feed every few seconds: the widget sees it is alive, and hears Stop. */
+function heartbeat(root, id, on) {
+  const p = pushers.get(id) ?? { root, last: 0, timer: null, inflight: null, dirty: false, beat: null };
+  pushers.set(id, p);
+  if (on && !p.beat) { p.beat = setInterval(() => { if (!p.inflight) send(id, p); }, HEARTBEAT_MS); p.beat.unref?.(); }
+  if (!on && p.beat) { clearInterval(p.beat); p.beat = null; }
+}
+
+/** Send whatever is waiting, now (a command calls this before it exits). Never throws, never waits past `ms`. */
+export async function flushProgress(ms = 6000) {
+  const waits = [];
+  for (const [id, p] of pushers) {
+    if (p.beat) { clearInterval(p.beat); p.beat = null; }
+    if (p.timer) { clearTimeout(p.timer); p.timer = null; p.dirty = true; }
+    if (p.inflight) waits.push(p.inflight.then(() => (p.dirty ? send(id, p) : null)));
+    else if (p.dirty) waits.push(send(id, p));
+  }
+  if (!waits.length) return;
+  await Promise.race([Promise.allSettled(waits), new Promise((r) => { const t = setTimeout(r, ms); t.unref?.(); })]);
+}
+
+/* ------------------------------------------------------------------ the document */
+
+function pushLog(d, text) {
+  d.log = [...(d.log ?? []), { at: now(), text: plain(text, LIMITS.logLine) }].slice(-LIMITS.logLines);
+}
+
+function mutateDoc(root, id, fn) {
+  const d = readFeed(root, id);
+  if (!d) return null;
+  fn(d);
+  d.updatedAt = now();
+  let text = `${JSON.stringify(d, null, 1)}\n`;
+  // A feed never grows past its bound: the oldest shot pictures, then the preview picture, give way first.
+  while (text.length > LIMITS.doc && d.video?.shots?.some((s) => s.image)) { d.video.shots.find((s) => s.image).image = null; text = `${JSON.stringify(d, null, 1)}\n`; }
+  if (text.length > LIMITS.doc && d.preview?.image) { d.preview.image = null; text = `${JSON.stringify(d, null, 1)}\n`; }
+  writeAtomic(docPath(root, id), text);
+  return d;
+}
+
+/** One open build's feed. Every call re-reads the file, changes it and writes it whole, so two commands can share it. */
+export class Feed {
+  constructor(root, id) { this.root = root; this.id = id; }
+
+  get doc() { return readFeed(this.root, this.id); }
+
+  change(fn, { soon = false } = {}) {
+    const d = mutateDoc(this.root, this.id, fn);
+    if (d) schedule(this.root, this.id, { soon });
+    return d;
+  }
+
+  /** A stage's state. Starting one ends the stage before it (done) and skips any never started. */
+  stage(stage, state, note) {
+    if (!STAGE_STATES.has(state)) throw new Error(`a stage is ${[...STAGE_STATES].join(', ')}`);
+    const d = this.change((doc) => {
+      const at = doc.stages.findIndex((s) => s.id === stage);
+      if (at < 0) throw new Error(`this ${doc.what} build has no stage "${stage}" (${doc.stages.map((s) => s.id).join(', ')})`);
+      const s = doc.stages[at];
+      if (state === 'running') {
+        for (const before of doc.stages.slice(0, at)) {
+          if (before.state === 'running') { before.state = 'done'; before.endedAt = now(); }
+          else if (before.state === 'pending') before.state = 'skipped';
+        }
+        s.startedAt = now(); s.endedAt = null;
+        doc.stage = stage;
+      } else if (state !== 'pending') s.endedAt = now();
+      s.state = state;
+      if (note !== undefined) s.note = plain(note, LIMITS.note);
+      if (state === 'failed' && note) doc.error = plain(note, LIMITS.note);
+      if (state === 'running' || state === 'done') doc.error = null;
+      pushLog(doc, `${s.label}: ${state}${note ? ` (${plain(note, 100)})` : ''}`);
+    }, { soon: true });
+    heartbeat(this.root, this.id, d?.stages?.some((s) => s.state === 'running') && d.state === 'running');
+    return d;
+  }
+
+  /** One check's state; a check is added the first time it is named. */
+  check(id, state, { label, note, ms, stage } = {}) {
+    if (!CHECK_STATES.has(state)) throw new Error(`a check is ${[...CHECK_STATES].join(', ')}`);
+    return this.change((doc) => {
+      const key = plain(id, 40);
+      let c = doc.checks.find((x) => x.id === key);
+      if (!c) {
+        if (doc.checks.length >= LIMITS.checks) return;
+        c = { id: key, label: plain(label ?? key, LIMITS.label), stage: stage ?? doc.stage ?? null, state: 'pending', ms: null, note: '' };
+        doc.checks.push(c);
+      }
+      c.state = state;
+      if (label) c.label = plain(label, LIMITS.label);
+      if (note !== undefined) c.note = plain(note, LIMITS.note);
+      if (Number.isFinite(ms)) c.ms = Math.round(ms);
+    });
+  }
+
+  /** Forget the checks of one stage (a stage run again starts its checks afresh). */
+  resetChecks(stage) { return this.change((doc) => { doc.checks = doc.checks.filter((c) => c.stage !== stage); }); }
+
+  preview({ url, image, caption } = {}) {
+    const picture = image ? imageData(image) : undefined;
+    return this.change((doc) => {
+      doc.preview = {
+        url: url ? String(url).slice(0, 300) : doc.preview?.url ?? null,
+        image: picture ?? doc.preview?.image ?? null,
+        caption: caption !== undefined ? plain(caption, LIMITS.label) : doc.preview?.caption ?? '',
+        at: now(),
+      };
+    }, { soon: true });
+  }
+
+  spend(amount, what, { receipt, unit } = {}) {
+    const n = Number(amount);
+    if (!Number.isFinite(n) || n < 0 || n > 1e6) throw new Error('spend is a number of dollars (or credits) of 0 or more');
+    return this.change((doc) => {
+      if (unit && unit !== doc.spend.unit) throw new Error(`this build counts ${doc.spend.unit}, not ${unit}`);
+      doc.spend.used = Math.round((doc.spend.used + n) * 10000) / 10000;
+      doc.spend.items = [...doc.spend.items, { what: plain(what ?? 'spend', LIMITS.label), amount: n, at: now(), receipt: receipt ? plain(receipt, LIMITS.label) : null }].slice(-LIMITS.items);
+      pushLog(doc, `Spent ${doc.spend.unit === 'usd' ? `$${n.toFixed(2)}` : `${n} credits`} on ${plain(what ?? 'spend', 80)}`);
+    }, { soon: true });
+  }
+
+  log(text) { return this.change((doc) => pushLog(doc, text)); }
+
+  /** A video's shot (it fills in with its picture as it renders). */
+  shot(id, state, { label, image } = {}) {
+    if (!CHECK_STATES.has(state)) throw new Error(`a shot is ${[...CHECK_STATES].join(', ')}`);
+    const picture = image ? imageData(image, LIMITS.shotImage) : undefined;
+    return this.change((doc) => {
+      doc.video ??= { shots: [] };
+      let s = doc.video.shots.find((x) => x.id === plain(id, 40));
+      if (!s) { if (doc.video.shots.length >= LIMITS.shots) return; s = { id: plain(id, 40), label: plain(label ?? id, LIMITS.label), state: 'pending', image: null }; doc.video.shots.push(s); }
+      s.state = state;
+      if (label) s.label = plain(label, LIMITS.label);
+      if (picture !== undefined) s.image = picture;
+    });
+  }
+
+  /** A song's waveform (peaks of 0..1) and lyric lines as the check hears them. */
+  song({ peaks, lyric, sung } = {}) {
+    return this.change((doc) => {
+      doc.song ??= { peaks: [], lyrics: [] };
+      if (Array.isArray(peaks)) doc.song.peaks = peaks.slice(0, LIMITS.peaks).map((p) => Math.max(0, Math.min(1, Math.round(Number(p) * 1000) / 1000 || 0)));
+      if (lyric) {
+        const line = plain(lyric, LIMITS.label);
+        const known = doc.song.lyrics.find((l) => l.line === line);
+        const value = sung === true || sung === false ? sung : null;
+        if (known) known.sung = value;
+        else if (doc.song.lyrics.length < LIMITS.lyrics) doc.song.lyrics.push({ line, sung: value });
+      }
+    });
+  }
+
+  stopRequested() { return Boolean(this.doc?.stop?.requested); }
+
+  /**
+   * Ask the shared copy now (one write, answered with the person's Stop). A stage calls this before it starts,
+   * so a Stop pressed in the Claude app while nothing was running still stops the next command before it opens a
+   * browser or deploys. A local feed, or a directory that does not answer, changes nothing.
+   */
+  async sync() {
+    if (!this.doc?.shared?.build || this.doc.shared.ended) return;
+    await pushDoc(this.root, this.id).catch(() => null);
+  }
+
+  /** Ask the build to stop (the terminal's own Stop; the Claude app's arrives through the shared copy). */
+  stop(by = 'local') {
+    return this.change((doc) => { if (!doc.stop.requested) { doc.stop = { requested: true, at: now(), by }; pushLog(doc, 'Stop asked; stopping at the next safe point.'); } }, { soon: true });
+  }
+
+  /** The build is over: passed, failed or stopped. */
+  end(state, note) {
+    if (!END_STATES.has(state)) throw new Error(`a build ends ${[...END_STATES].join(', ')}`);
+    const d = this.change((doc) => {
+      for (const s of doc.stages) {
+        if (s.state === 'running') { s.state = state === 'passed' ? 'done' : state === 'stopped' ? 'stopped' : 'failed'; s.endedAt = now(); }
+      }
+      for (const c of doc.checks) if (c.state === 'running') c.state = state === 'passed' ? 'pass' : 'skip';
+      doc.state = state;
+      doc.endedAt = now();
+      if (note) { if (state === 'failed') doc.error = plain(note, LIMITS.note); pushLog(doc, note); }
+      pushLog(doc, state === 'passed' ? 'Done.' : state === 'stopped' ? 'Stopped.' : 'Failed.');
+    }, { soon: true });
+    heartbeat(this.root, this.id, false);
+    try { if (readFileSync(currentPath(this.root), 'utf8').trim() === this.id) rmSync(currentPath(this.root), { force: true }); } catch { /* none */ }
+    return d;
+  }
+}
+
+/** The open feed, or null (then a command reports nothing and behaves exactly as before). */
+export function currentFeed(root) {
+  const id = root ? currentId(root) : null;
+  return id ? new Feed(root, id) : null;
+}
+
+/** The feed as the Claude app's widget and `progress show` see it (never the write key). */
+export function publicFeed(doc) {
+  if (!doc) return null;
+  const { shared, ...rest } = doc;
+  return { ...rest, ...(shared ? { shared: { build: shared.build, directory: shared.directory, ...(shared.ended ? { ended: true } : {}) } } : {}) };
+}
+
+/**
+ * Open a feed for one build. `share` asks the studio's directory (studio.json `homie.directory`, or `directory`)
+ * to keep a copy for the Claude app's widget; if it cannot, the build goes on with the local feed only.
+ */
+export async function startProgress(root, { what = 'game', id, title, budget, unit, share = false, directory } = {}) {
+  if (!STAGES[what]) return { ok: false, command: 'progress start', why: `what is being made: ${Object.keys(STAGES).join(', ')}` };
+  if (id !== undefined && id !== null && !SLUG.test(String(id))) return { ok: false, command: 'progress start', why: 'the id is the game, song or video id (lowercase letters, digits and hyphens)' };
+  const studio = readStudio(root);
+  const open = currentId(root);
+  if (open) return { ok: false, command: 'progress start', why: `build ${open} is still open: end it first (homie-studio progress end passed|failed|stopped)`, build: open };
+  const b = budget === undefined || budget === null || budget === true ? null : Number(budget);
+  if (b !== null && (!Number.isFinite(b) || b < 0)) return { ok: false, command: 'progress start', why: 'the budget is a number (dollars, or credits with --unit credits)' };
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..*/, '').toLowerCase();
+  const build = `${stamp}-${randomBytes(3).toString('hex')}`;
+  const doc = {
+    v: 1, kind: PROGRESS_KIND, build, what, id: id ?? null,
+    title: plain(title || `${id ?? studio.name ?? 'Studio'}`, LIMITS.title),
+    studio: plain(studio.name ?? '', 60),
+    state: 'running', stage: STAGES[what][0][0], startedAt: now(), updatedAt: now(), endedAt: null,
+    stages: STAGES[what].map(([sid, label], i) => ({ id: sid, label, state: i === 0 ? 'running' : 'pending', startedAt: i === 0 ? now() : null, endedAt: null, note: '' })),
+    checks: [], preview: null,
+    spend: { unit: unit === 'credits' ? 'credits' : 'usd', used: 0, budget: b, items: [] },
+    stop: { requested: false, at: null, by: null },
+    log: [{ at: now(), text: `Started: ${plain(title || id || what, 100)}` }],
+    error: null,
+  };
+  mkdirSync(dir(root), { recursive: true });
+  writeAtomic(docPath(root, build), `${JSON.stringify(doc, null, 1)}\n`);
+  writeAtomic(currentPath(root), `${build}\n`);
+  let shared = null;
+  let why = null;
+  if (share) {
+    const at = String(directory || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+    if (!/^https:\/\//.test(at) && !(/^http:\/\//.test(at) && loopback(at))) why = `the directory ${at} is not https`;
+    else {
+      try {
+        const res = await fetch(`${at}/api/studio/progress`, {
+          method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': 'homie-studio' },
+          body: JSON.stringify({ what, id: id ?? null, title: doc.title, studio: doc.studio }), signal: AbortSignal.timeout(10_000),
+        });
+        const body = await res.json().catch(() => null);
+        if (res.ok && body?.ok && REMOTE_ID.test(String(body.build)) && /^hbk_[a-f0-9]{48}$/.test(String(body.key))) {
+          writeFileSync(keyPath(root, build), `${body.key}\n`, { mode: 0o600 });
+          try { chmodSync(keyPath(root, build), 0o600); } catch { /* not on this filesystem */ }
+          shared = { build: body.build, directory: at, expiresAt: body.expiresAt ?? null };
+          mutateDoc(root, build, (d) => { d.shared = { build: body.build, directory: at }; });
+          schedule(root, build, { soon: true });
+          heartbeat(root, build, true);
+        } else why = body?.message ?? `${at} answered ${res.status}`;
+      } catch (error) { why = `${at} did not answer (${error?.message ?? error})`; }
+    }
+  }
+  return {
+    ok: true, command: 'progress start', build, file: join(PROGRESS_DIR, `${build}.json`), what, id: id ?? null, title: doc.title,
+    stages: doc.stages.map((s) => s.id), budget: doc.spend.budget, unit: doc.spend.unit,
+    shared: shared ? { build: shared.build, directory: shared.directory, expiresAt: shared.expiresAt } : null,
+    ...(share && !shared ? { sharedWhy: `not shared: ${why}; the feed is local only` } : {}),
+    widget: shared ? `In the Claude app: call the Homie MCP tool build_progress with { "build": "${shared.build}" }` : null,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.7.0';
+export const STUDIO_VERSION_TAG = '0.8.0';