@homie-rocks/studio 0.8.0 → 0.9.0

package/README.md

@@ -10,7 +10,7 @@ Most people never run this by hand: the Homie plugin for Claude Code and Codex d
 and the person approves Cloudflare once in their browser.
 
 ```sh
-npx -y --package=https://homie.rocks/npm/homie-studio-0.8.0.tgz homie-studio new ./night-owls --name "Night Owls"
+npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio new ./night-owls --name "Night Owls"
 cd night-owls && npm install
 npx homie-studio game new crown-thief --from gem-rush --name "Crown Thief"
 npx homie-studio dev                                   # the whole site locally
@@ -19,6 +19,7 @@ npx homie-studio deploy --plan                         # what deploy will create
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
 npx homie-studio stats                                 # the studio's own numbers, for its owner
+npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
 ## The site: the hub's shape, and a landing for every game
@@ -33,8 +34,30 @@ live rooms, credits (the original and its licence for a port), and "Make a game
 files. `site/SITE.md` says all of it.
 
 The play page writes its room into the address, and a small room button at the edge shares it: Invite, Big
-screen and the room code. Every HTML answer is `no-transform`, and the site's pages are never framed by another
-site.
+screen and the room code. game.json's `screen.share` puts it where each game has room, per device (a corner or
+the top's middle, moved in by `x` / `y`, or kept a small icon), so it never covers a scoreboard. A game whose
+picture is white or cream gets a light landing (`landing.scheme: "light"`). Every card and the directory show a
+game's landing still. Every HTML answer is `no-transform`, and the site's pages are never framed by another
+site. A game made with Homie's arcade controls that knocks for a Homie box (`/__homie/call`) is told
+`not-a-homie`, at the site's root as under the game.
+
+## Upgrading a studio
+
+A studio pins one version, so nothing changes until it asks. To take a newer one:
+
+```sh
+npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio upgrade          # the plan; changes nothing
+npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio upgrade --apply  # after the person agrees
+npm install && npm run build
+```
+
+`upgrade` compares the studio with what this version's `new` would write for it: an AGENTS.md section, a README,
+a `.gitignore` line, a D1 migration or a package.json script it lacks is added, and one it never changed since an
+older template wrote it (`lib/template-history.json` knows every earlier version's text by a fingerprint) takes
+the newer text. Anything the studio changed or wrote itself is kept as it is: the plan lists it, and `--diff`
+shows how it differs from the template. `--apply` also pins this version in package.json and sets studio.json's
+`homie.studio`. When the template's words change, `node scripts/studio-template-history.mjs` records them (a test
+fails until it has).
 
 ## Rooms of up to 32
 
@@ -135,7 +158,8 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `lib/scaffold.mjs` | `new`: the studio monorepo, only into a new or empty folder, every file listed. |
 | `lib/build.mjs` | `build`: games bundled with esbuild into `site/dist`, `games.json`, each game's shared `source.json`. |
 | `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations, the directory claim; refuses resources it did not create. `storage add`: the optional R2 bucket. |
-| `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round. |
+| `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. |
+| `lib/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |
 | `lib/port.mjs` | `port plan` (reads a game and grades the port) and `port import`. |
 | `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |
 | `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`. |

package/bin/homie-studio.mjs

@@ -23,6 +23,10 @@
  *   homie-studio media put <file> [--as <key>]
  *   homie-studio media list
  *   homie-studio status
+ *   homie-studio upgrade [--apply] [--diff]
+ *                                         (what this version's template adds to an existing studio: AGENTS.md
+ *                                          sections, READMEs, .gitignore lines, the pin; changes nothing until
+ *                                          --apply, and never a file or section the studio changed)
  *   homie-studio stats [--range 1d|7d|30d|90d] [--game <id> | --song <slug> | --video <slug>] [--url <site>]
  *   homie-studio stats key [--hours 1]    (a read key for the Homie MCP tool studio_stats)
  *   homie-studio stats link               (a one-time link to the private stats page, for the owner's browser)
@@ -61,6 +65,7 @@ import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
 import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
 import { ensureStatsMigration, newStudio } from '../lib/scaffold.mjs';
+import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
@@ -68,7 +73,7 @@ import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, star
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share'];
+const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -198,6 +203,33 @@ function print(result) {
     case 'look':
       lines.push(`${result.ok ? 'Looks right' : 'Look again'}: ${result.rows.length} views of ${result.url}`, ...result.rows.map((r) => `  ${r.ok ? 'ok  ' : 'FIX '} ${r.path} on ${({ computer: 'a computer', phone: 'a phone', sideways: 'a phone turned sideways' })[r.device] ?? r.device}${r.problems.length ? `: ${r.problems.join('; ')}` : ''}`), '', `Pictures (open them and look): ${result.shots}`);
       break;
+    case 'upgrade': {
+      const show = (text, n = 14) => { const l = String(text ?? '').replace(/\n+$/, '').split('\n'); return [...l.slice(0, n).map((x) => `      ${x}`), ...(l.length > n ? [`      … (${l.length - n} more lines; --json has all of it)`] : [])]; };
+      const mark = { 'add-file': '+', 'add-section': '+', 'add-lines': '+', scripts: '+', 'update-file': '~', 'update-section': '~', pin: '~', version: '~' };
+      const list = result.applied ? result.done : result.changes;
+      lines.push(result.applied
+        ? `${result.studio} is on the @homie-rocks/studio ${result.to} template now (${list.length} change${list.length === 1 ? '' : 's'}).`
+        : list.length ? `${result.studio}: what the @homie-rocks/studio ${result.to} template adds (from ${result.from ?? 'an older version'}). Nothing is changed until --apply.` : `${result.studio} has everything the @homie-rocks/studio ${result.to} template writes.`);
+      if (list.length) lines.push('');
+      for (const c of list) {
+        lines.push(`  ${mark[c.kind] ?? '·'} ${c.file.padEnd(18)} ${c.what}${c.kind === 'add-section' && (c.after || c.before) ? ` (${c.after ? `after "${c.after}"` : `before "${c.before}"`})` : ''}`);
+        if (result.applied) continue;
+        if (c.kind === 'add-section' || (c.kind === 'add-file' && c.file.endsWith('.md'))) lines.push(...show(c.text));
+        if (c.kind === 'update-section' || c.kind === 'update-file') lines.push(...lineDiff(c.from, c.text).map((x) => `      ${x}`));
+      }
+      for (const c of result.skipped ?? []) lines.push(`  ! ${c.file.padEnd(18)} not applied: ${c.why}`);
+      if (result.kept?.length) {
+        lines.push('', 'Kept as this studio wrote them (never changed by upgrade; the template\'s text differs):');
+        for (const k of result.kept) {
+          lines.push(`  = ${k.file.padEnd(18)} ${k.what}`);
+          if (flags.has('diff') && k.mine !== undefined) lines.push(...lineDiff(k.mine, k.template).map((x) => `      ${x}`));
+        }
+        if (!flags.has('diff')) lines.push('  (--diff shows how each differs from the template: "-" this studio\'s lines, "+" the template\'s)');
+      }
+      if (result.uncommitted && !result.applied && result.changes.length) lines.push('', `Note: ${result.uncommitted} file(s) have uncommitted changes; commit them first so the upgrade is a change of its own.`);
+      if (result.next?.length) lines.push('', 'Next:', ...result.next.map((n) => `  ${n}`));
+      break;
+    }
     case 'check':
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
         ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`));
@@ -237,6 +269,10 @@ async function main() {
     const studio = readStudio(root);
     return { ok: true, command: 'status', root, studio, site: siteUrl(root, studio), games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && whoami(root)) };
   }
+  if (cmd === 'upgrade') {
+    const plan = upgradePlan(root);
+    return flags.has('apply') || flags.has('yes') ? upgradeApply(root, plan) : plan;
+  }
   if (cmd === 'dev' && flags.has('stop')) return stopDev(root);
   if (cmd === 'dev') return dev(root);
   if (cmd === 'check') {

package/lib/build.mjs

@@ -208,6 +208,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       },
       // studio.json `stats.share`: the site tells the directory two numbers for the hub (played this week).
       ...(studio.stats?.share === true ? { stats: { share: true }, directory: studio.homie?.directory ?? 'https://homie.rocks' } : {}),
+      // studio.json `"rooms": { "share": false }`: the manifest names no rooms, so the hub shows none of this studio's.
+      ...(studio.rooms?.share === false ? { rooms: { share: false } } : {}),
     },
     games: rows,
     songs: media.songs,

package/lib/check.mjs

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

package/lib/look.mjs

@@ -36,8 +36,9 @@ export async function look({ url, paths, shots, devices = Object.keys(LOOK_DEVIC
   const base = String(url).replace(/\/+$/, '');
   mkdirSync(shots, { recursive: true });
   const profile = mkdtempSync(join(tmpdir(), 'homie-studio-look-'));
+  // 150 s for Chrome to start: on a loaded computer a cold start has taken over a minute.
   const browser = await puppeteer.launch({
-    executablePath: chrome, headless: true, userDataDir: profile,
+    executablePath: chrome, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 180_000,
     args: ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
   });
   const rows = [];
@@ -51,7 +52,7 @@ export async function look({ url, paths, shots, devices = Object.keys(LOOK_DEVIC
         await page.setViewport(LOOK_DEVICES[device]);
         await page.setUserAgent(`${await browser.userAgent()} homie-studio-check look`);
         const t0 = Date.now();
-        const res = await page.goto(`${base}${path}`, { waitUntil: 'networkidle2', timeout: 45_000 }).catch((e) => { errors.push(`open: ${e.message}`); return null; });
+        const res = await page.goto(`${base}${path}`, { waitUntil: 'networkidle2', timeout: 90_000 }).catch((e) => { errors.push(`open: ${e.message}`); return null; });
         const ms = Date.now() - t0;
         await sleep(900);
         const fold = await page.evaluate(() => {

package/lib/media.mjs

@@ -50,6 +50,11 @@ export function resolveMedia(root, kind, { r2 = false } = {}) {
   const entries = [];
   const skipped = [];
   const seen = new Set();
+  // The manifest's own picture (music: `cover`, videos: `poster`): an album cover for every song that has none of
+  // its own. A path in the studio (copied into the site) or an https:// address, like any file.
+  const artRole = kind === 'music' ? 'cover' : 'poster';
+  const shared = manifest[artRole];
+  const sharedFile = typeof shared === 'string' ? (/^https:\/\//.test(shared) ? { url: shared } : { path: shared }) : shared && typeof shared === 'object' ? shared : null;
   for (const item of manifest.items) {
     if (!item || typeof item !== 'object') continue;
     const label = item.slug ?? item.key ?? item.file ?? '(unnamed)';
@@ -58,7 +63,9 @@ export function resolveMedia(root, kind, { r2 = false } = {}) {
     seen.add(item.slug);
     if (item.published !== true) { skipped.push({ kind, item: label, why: 'not published yet ("published": true shows it)' }); continue; }
     const files = [];
-    for (const f of Array.isArray(item.files) ? item.files : []) {
+    const own = Array.isArray(item.files) ? item.files : [];
+    const list = sharedFile && !own.some((f) => f?.role === artRole) ? [...own, { ...sharedFile, role: artRole }] : own;
+    for (const f of list) {
       if (!f || f.public === false) continue;
       let src = null;
       if (typeof f.key === 'string' && f.key && r2) src = { from: 'r2', url: `/media/${f.key.split('/').map(encodeURIComponent).join('/')}` };

package/lib/port-check.mjs

@@ -197,7 +197,8 @@ function descendants(pid) {
 async function chrome(puppeteer, kind, exe) {
   const dir = mkdtempSync(join(tmpdir(), 'homie-port-check-'));
   const vp = kind === 'phone' ? { width: 412, height: 915 } : kind === 'tv' ? { width: 1280, height: 720 } : { width: 1280, height: 800 };
-  const browser = await puppeteer.launch({ executablePath: exe, headless: true, userDataDir: dir, protocolTimeout: 120_000, args: [...GPU, `--window-size=${vp.width},${vp.height}`] });
+  // 150 s for Chrome to start: on a loaded computer a cold start has taken over a minute.
+  const browser = await puppeteer.launch({ executablePath: exe, headless: true, userDataDir: dir, timeout: 150_000, protocolTimeout: 120_000, args: [...GPU, `--window-size=${vp.width},${vp.height}`] });
   const page = (await browser.pages())[0] ?? await browser.newPage();
   if (kind === 'phone') await page.emulate({ viewport: { ...vp, deviceScaleFactor: 2.625, isMobile: true, hasTouch: true }, userAgent: `${ANDROID_UA} ${TAG}` });
   else { await page.setViewport({ ...vp, deviceScaleFactor: 1 }); await page.setUserAgent(`${await browser.userAgent()} ${TAG}`); }
@@ -215,7 +216,7 @@ async function chrome(puppeteer, kind, exe) {
 }
 
 async function webkit(pw) {
-  const browser = await pw.webkit.launch({ headless: true });
+  const browser = await pw.webkit.launch({ headless: true, timeout: 150_000 });
   const dev = pw.devices['iPhone 15'];
   const ctx = await browser.newContext({ ...dev, userAgent: `${dev.userAgent} ${TAG}` });
   const page = await ctx.newPage();

package/lib/scaffold.mjs

@@ -116,6 +116,10 @@ studio's pinned copy, never a registry lookup of the bare name.
   \`studio_stats\` (never paste a key anywhere else). \`stats share on\` tells the directory two numbers
   (played this week). The site counts and never tracks: no cookie on a visitor, no person identified,
   nothing sent anywhere; house QA and \`check\` runs are not counted.
+- \`npx --no-install homie-studio upgrade\` — after pinning a newer \`@homie-rocks/studio\` (or through
+  \`npx -y --package=<its tarball> homie-studio upgrade\`): what the newer template adds to this studio (AGENTS.md
+  sections, READMEs, .gitignore lines) and what it keeps. It changes nothing until \`--apply\`, and never
+  touches a file or section this studio changed; \`--diff\` shows how those differ from the template's.
 
 ## The site
 
@@ -132,7 +136,11 @@ studio's pinned copy, never a registry lookup of the bare name.
   (\`pitch\`, \`about\`, \`controls\`, \`howToPlay\`, \`credits\`) and art with the plugin's \`art\` and \`video\` skills.
 - **The look** is \`site/theme.json\` (colours, fonts, corner radius, a logo). Anything in \`site/\` wins: a whole
   page in \`site/pages/\`, a piece of every page in \`site/partials/\`, files in \`site/public/\`, extra CSS in
-  \`site/theme.css\` (\`site/README.md\`).
+  \`site/theme.css\` (\`site/README.md\`). A game whose picture is white or cream gets a light landing with
+  game.json \`"landing": { "scheme": "light" }\` (a dark tint would turn it grey).
+- **Cards and the directory** show each game's landing still (\`hero/wide.jpg\`), else its cover. A song without
+  a cover of its own shows the music manifest's \`cover\`, else its game's still.
+- **Live rooms** are listed on homie.rocks too; studio.json \`"rooms": { "share": false }\` keeps them off it.
 - Every page ends with "Made with Homie", linking to homie.rocks/studio/. Restyle it in \`site/theme.css\`; keep it.
 
 ## Making games
@@ -144,6 +152,10 @@ studio's pinned copy, never a registry lookup of the bare name.
 - Import it as \`import { createNetplay } from '@homie-rocks/studio/netplay'\`.
 - Phones and computers: touch controls on phones only, keys on computers; keep the
   centre of the screen clear during play.
+- The play page's small room button (Invite, Big screen, the room code) sits top right. If the game's
+  scoreboard or a bar is there, move it in game.json \`"screen": { "share": … }\`: a corner or \`top-center\`, per
+  device (\`desk\`, \`phone\`, \`sideways\`), with an \`x\` / \`y\` offset in pixels, and \`"label": false\` to keep it
+  a small icon (\`node_modules/@homie-rocks/studio/site/SITE.md\`). Look at it on a phone and a computer.
 - Change a game in small steps, build, and look at it (\`dev\`, then \`check\`).
 - A game's id is its URL (\`/<id>/\`); keep it once published.
 

package/lib/site.mjs

@@ -416,6 +416,12 @@ export function landingOf(g, out, { videos = [], songs = [], log = () => {} } =
   if (texts.length) { mkdirSync(landDir, { recursive: true }); writeFileSync(join(landDir, 'credits.json'), `${JSON.stringify({ v: 1, texts })}\n`); }
 
   const words = L.players && typeof L.players === 'object' ? { one: str(L.players.one, 24), many: str(L.players.many, 24) } : null;
+  // The landing's own colours (landing.theme): only colours, and the ink on its own accent worked out like the studio's.
+  const theme = L.theme && typeof L.theme === 'object' ? Object.fromEntries(['accent', 'glow', 'bg', 'fg'].filter((k) => COLOR.test(String(L.theme[k] ?? ''))).map((k) => [k, L.theme[k]])) : null;
+  if (theme?.accent) { const l = luminance(theme.accent); if (l !== null) theme.accentInk = l > 0.4 ? '#0b0b10' : '#ffffff'; }
+  // landing.scheme: "light" for a white or cream game (its hero is tinted light and its words dark), "dark" for a
+  // dark game in a light studio. Anything else follows the studio's look.
+  if (L.scheme !== undefined && L.scheme !== 'light' && L.scheme !== 'dark') log(`warning: games/${g.id}/game.json landing.scheme is "light" or "dark"; left out`);
   return {
     pitch: str(L.pitch, 240) ?? str(credits.tagline, 240),
     kicker: str(L.kicker, 120),
@@ -431,7 +437,8 @@ export function landingOf(g, out, { videos = [], songs = [], log = () => {} } =
     music: forGame(songs).map((e) => e.slug),
     source: g.share?.source !== false,
     tv: g.screen?.tv !== false && L.tv !== false,
-    theme: L.theme && typeof L.theme === 'object' ? Object.fromEntries(['accent', 'glow', 'bg', 'fg'].filter((k) => COLOR.test(String(L.theme[k] ?? ''))).map((k) => [k, L.theme[k]])) : null,
+    theme: theme && Object.keys(theme).length ? theme : null,
+    ...(L.scheme === 'light' || L.scheme === 'dark' ? { scheme: L.scheme } : {}),
   };
 }