@homie-rocks/studio 0.6.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.6.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
@@ -21,6 +21,21 @@ npx homie-studio publish                               # the homie.rocks directo
 npx homie-studio stats                                 # the studio's own numbers, for its owner
 ```
 
+## The site: the hub's shape, and a landing for every game
+
+Every studio site has the same sections as homie.rocks, in the studio's own look (`site/theme.json`): Home (the
+featured game, live rooms, the latest posts), Games, Music, Videos, Rooms (every public room playing now,
+joinable) and Posts (`posts/*.md`, with Atom and JSON feeds). A section with nothing in it has no tab, and its
+page answers 404. Every game gets a landing at `/<game>/`: a full-bleed hero from its own footage or art, the
+pitch, a big Play button into a public room, how to play on a phone, a computer and a TV (with the join code),
+live rooms, credits (the original and its licence for a port), and "Make a game like this". Every page ends with
+"Made with Homie". Anything the studio puts in `site/` wins: a whole page, a partial, its tokens, its CSS, its
+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.
+
 ## Rooms of up to 32
 
 Every room of a game has the seats its netplay manifest names: game.json's `netplay`
@@ -49,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
@@ -97,6 +140,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `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`. |
 | `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects; `/<game>/tv` is the big screen with a join QR (`qr.mjs`); `/music/<slug>/` and `/videos/<slug>/` are song and video pages (their files served with byte ranges, from the site or from storage at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
+| `worker/site.mjs`, `lib/site.mjs`, `lib/markdown.mjs`, `site/SITE.md` | The site: its sections, each game's landing, posts and their feeds, the look (theme tokens) and what the studio's `site/` folder overrides; the safe markdown posts are written in. `worker/pages.mjs`: the play page. |
 | `worker/stats.mjs`, `worker/stats-page.mjs`, `lib/stats.mjs` | The studio's own stats: what is counted and how, the owner-only `/api/stats` and `/_studio/stats`, and `homie-studio stats`. |
 | `lib/media.mjs`, `media/MEDIA.md` | The `music/` and `videos/` manifests: which entries get a page, and where each file's bytes come from (the site itself up to 25 MiB a file, the studio's storage, or a link). `media list` shows it; `media put` uploads a file to storage and records its key. |
 | `netplay/` | The netplay contract (`NETPLAY.md`) and its game helper (`@homie-rocks/studio/netplay`). |

package/bin/homie-studio.mjs

@@ -12,6 +12,8 @@
  *   homie-studio build [<id>]
  *   homie-studio dev [--port 8787]        (--stop: stop exactly this studio's dev server, nothing else)
  *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   homie-studio look [<path>...] [--url <site>] [--shots <dir>] [--only computer,phone,sideways]
+ *                                         (the site's pages on a computer and a phone, as pictures, with what is wrong)
  *   homie-studio port plan <game folder>
  *   homie-studio port import <game folder> --id <id> [--name "<Name>"] [--mode static|bundle|command]
  *   homie-studio port check <id> [--url <site>] [--only owner-desk,owner-phone,owner-iphone,round,life,tv] [--shots <dir>]
@@ -27,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';
@@ -36,6 +56,7 @@ import { build } from '../lib/build.mjs';
 import { check } from '../lib/check.mjs';
 import { deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
 import { publish } from '../lib/directory.mjs';
+import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
 import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
@@ -43,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];
@@ -62,7 +84,7 @@ const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
   if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
-  if (result.ok === false && result.command !== 'port check') { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
+  if (result.ok === false && result.command !== 'port check' && !(result.command === 'look' && result.rows)) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
   if (result.ok === false && result.command === 'port check' && !result.rows) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
   const lines = [];
   switch (result.command) {
@@ -81,7 +103,12 @@ function print(result) {
     case 'build':
       lines.push(`Built ${result.games.map((g) => `${g.id} (${Math.round(g.bytes / 1024)} KB)`).join(', ') || 'no games'} into ${relative(process.cwd(), result.dist) || result.dist}`);
       if (result.songs?.length || result.videos?.length) lines.push(`Media pages: ${[...result.songs.map((x) => `/music/${x}/`), ...result.videos.map((x) => `/videos/${x}/`)].join(', ')}`);
+      for (const l of result.landings ?? []) lines.push(`Landing /${l.id}/: hero from ${l.hero === 'footage' ? 'its footage' : l.hero === 'art' ? 'its art (moving)' : 'the studio\'s colours (add a cover or hero/ footage)'}${l.credits ? ', credits' : ''}${l.source ? ', "Make a game like this" with its source' : ''}`);
+      if (result.posts?.length) lines.push(`Posts: ${result.posts.map((x) => `/posts/${x}/`).join(', ')} (feeds: /posts/feed.xml, /posts/feed.json)`);
+      if (result.pages?.length || result.partials?.length) lines.push(`The studio's own: ${[...(result.pages ?? []).map((x) => `page ${x}`), ...(result.partials ?? []).map((x) => `partial ${x}`)].join(', ')}`);
       for (const m of result.mediaSkipped ?? []) lines.push(`  left out: ${m.kind}/${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
+      for (const m of result.postsSkipped ?? []) lines.push(`  left out: posts/${m.post}: ${m.why}`);
+      for (const m of result.siteSkipped ?? []) lines.push(`  left out: ${m.what}: ${m.why}`);
       break;
     case 'media list':
       for (const kind of ['music', 'videos']) {
@@ -147,6 +174,30 @@ 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 '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`));
@@ -170,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)) };
@@ -191,10 +243,23 @@ 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);
+    if (!url) return { ok: false, command: 'look', why: 'give --url (the local dev address or the live site)' };
+    let paths = positional.slice(1).map((p) => (p.startsWith('/') ? p : `/${p}`));
+    if (!paths.length) {
+      let cat = null;
+      try { cat = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8')); } catch { /* not built */ }
+      const games = cat?.games?.map((g) => g.id) ?? listGames(root).map((g) => g.id);
+      paths = ['/', ...games.map((id) => `/${id}/`), ...(games.length ? ['/games/', '/rooms/'] : []), ...(cat?.posts?.length ? ['/posts/', `/posts/${cat.posts[0].slug}/`] : [])];
+    }
+    const only = flags.get('only') ? String(flags.get('only')).split(',').filter((d) => ['computer', 'phone', 'sideways'].includes(d)) : undefined;
+    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 ?? {};
@@ -217,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
@@ -301,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') process.exit(process.exitCode ?? 0);
+  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

@@ -5,8 +5,12 @@
  *   site/dist/games/<id>/index.html        the game's page (the Worker adds HOMIE_NET)
  *   site/dist/games/<id>/assets/main.js    its bundle (esbuild; @homie-rocks/studio/netplay inlined)
  *   site/dist/games/<id>/...               everything in games/<id>/public/
- *   site/dist/games.json                   { studio, games[], songs[], videos[] } from studio.json, game.json
- *                                          files and the music/ and videos/ manifests (media/MEDIA.md)
+ *   site/dist/games.json                   { studio, games[], songs[], videos[], posts[], site } from studio.json,
+ *                                          game.json files, the music/ and videos/ manifests (media/MEDIA.md),
+ *                                          posts/*.md and the studio's site/ folder (site/SITE.md)
+ *   site/dist/games/<id>/_landing/...      what the game's landing shows (hero footage, its cover, licence texts)
+ *   site/dist/_site/                       posts.json (the posts' HTML), the studio's own pages (site/pages)
+ *   site/dist/<file>                       site/public, as it is (fonts, a logo, hero footage)
  *   site/dist/music/..., site/dist/videos/...   media files the site serves itself (R2 keys are served from R2)
  *
  * game.json "build" picks how a game becomes files (a ported game keeps its own shape):
@@ -22,6 +26,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statS
 import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
 import { buildMedia } from './media.mjs';
+import { buildSiteFiles, landingOf, readPosts, readTheme } from './site.mjs';
 import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
 import { SEAT_MAX } from '../worker/seats.mjs';
 import { STUDIO_VERSION } from './version.mjs';
@@ -173,28 +178,49 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   else {
     try { const prev = JSON.parse(readFileSync(join(dist, 'games.json'), 'utf8')); media = { songs: prev.songs ?? [], videos: prev.videos ?? [], skipped: [] }; } catch { media = { songs: [], videos: [], skipped: [] }; }
   }
+  // The site around the games (site/SITE.md): the look, each game's landing, posts, and what site/ overrides.
+  const theme = readTheme(root, { log });
+  const shown = all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html')));
+  const rows = shown.map((g) => {
+    // The seats come from the game's netplay manifest (NETPLAY.md §3): what the Worker gives every room of it.
+    const net = netplayOf(g, join(dist, 'games', g.id));
+    const { min, max } = seatsFor(g, net);
+    return {
+      id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
+      roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
+      ...(g.screen ? { screen: g.screen } : {}),
+      landing: landingOf(g, join(dist, 'games', g.id), { videos: media.videos, songs: media.songs, log }),
+    };
+  });
+  const { posts, skipped: postsSkipped } = readPosts(root, { games: rows, songs: media.songs, videos: media.videos, log });
+  const site = buildSiteFiles(root, dist, { gameIds: rows.map((g) => g.id), log });
+  mkdirSync(join(dist, '_site'), { recursive: true });
+  writeFileSync(join(dist, '_site', 'posts.json'), `${JSON.stringify({ v: 1, posts })}\n`);
+  const s = studio.site && typeof studio.site === 'object' ? studio.site : {};
   const catalogue = {
     studio: {
       name: studio.name, slug: studio.slug, version: STUDIO_VERSION,
+      ...(typeof studio.tagline === 'string' && studio.tagline.trim() ? { tagline: studio.tagline.trim().slice(0, 140) } : {}),
+      theme,
+      site: {
+        ...(rows.some((g) => g.id === s.featured) ? { featured: s.featured } : {}),
+        ...(Array.isArray(s.frameAncestors) ? { frameAncestors: s.frameAncestors.filter((o) => /^https:\/\/[a-z0-9.-]+(?::\d+)?$/i.test(String(o))).slice(0, 8) } : {}),
+      },
       // studio.json `stats.share`: the site tells the directory two numbers for the hub (played this week).
       ...(studio.stats?.share === true ? { stats: { share: true }, directory: studio.homie?.directory ?? 'https://homie.rocks' } : {}),
     },
-    games: all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))).map((g) => {
-      // The seats come from the game's netplay manifest (NETPLAY.md §3): what the Worker gives every room of it.
-      const net = netplayOf(g, join(dist, 'games', g.id));
-      const { min, max } = seatsFor(g, net);
-      return {
-        id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
-        roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
-        ...(g.screen ? { screen: g.screen } : {}),
-      };
-    }),
+    games: rows,
     songs: media.songs,
     videos: media.videos,
+    // Summaries only; each post's HTML is in _site/posts.json.
+    posts: posts.map(({ html, record, ...p }) => p),
+    site: { pages: site.pages, partials: site.partials, ...(site.css ? { css: site.css } : {}) },
   };
   writeFileSync(join(dist, 'games.json'), `${JSON.stringify(catalogue, null, 2)}\n`);
   return {
     ok: true, command: 'build', dist, games: built, catalogue: catalogue.games.map((g) => g.id),
     songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped,
+    posts: posts.map((p) => p.slug), postsSkipped, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
+    landings: rows.map((g) => ({ id: g.id, hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length), source: g.landing.source })),
   };
 }

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 });