@homie-rocks/studio 0.8.0 → 0.10.0

package/lib/check.mjs

@@ -8,21 +8,25 @@
  * `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 { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { cpus, loadavg, tmpdir } from 'node:os';
 import { join } from 'node:path';
-
-const CHROMES = [
-  process.env.CHROME_PATH,
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  '/Applications/Chromium.app/Contents/MacOS/Chromium',
-  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
-].filter(Boolean);
+import { SOFTWARE_GL, chromeArgs, findChrome, measureFrames, noChrome } from './chrome.mjs';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 /** 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,10 +36,29 @@ 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)' };
+  const chrome = findChrome();
+  if (!chrome) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   const base = String(url).replace(/\/+$/, '');
@@ -49,6 +72,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,8 +94,8 @@ 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,
-        args: ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
+        executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, protocolTimeout: 180_000,
+        args: [...chromeArgs(), '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
       });
       browsers.push(browser);
       const page = await browser.newPage();
@@ -78,13 +103,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 +120,102 @@ 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.
+    // How fast each browser draws the game while it plays (reported, never judged: a VM without a GPU draws
+    // with SwiftShader, which is not a person's frame rate).
+    const frames = await Promise.all(players.map((p) => measureFrames(p.page)));
+    const software = frames.some((f) => f.renderer && SOFTWARE_GL.test(f.renderer));
+    const drawn = frames.map((f, i) => `${kinds[i].name} ${f.fps ?? '?'} fps`).join(', ');
+    log(`drawing: ${drawn}${frames[0]?.renderer ? ` (${frames[0].renderer})` : ''}`);
+    // Only a round that finishes AFTER both browsers were seated, seen by both, with BOTH of them in its results,
+    // counts: an idle room remembers its last round for a while, and that stale result proves nothing. A browser is
+    // in a round when a row carries a seat it held (a reconnect keeps its seat; a game may still mark an idle
+    // 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} bot${hit.results.length - humans === 1 ? '' : 's'}${missed.size ? ` (after ${missed.size} round(s) without both)` : ''}; ${drawn}${software ? ' (software GL: not measurable here)' : ''}` });
+    await picture(`Round ${hit.n} finished with both; the next one is on`);
     return {
-      ok: sameRoom && 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,
+      frames: frames.map((f, i) => ({ browser: kinds[i].name, fps: f.fps, renderer: f.renderer })),
+      ...(software ? { software: 'This machine has no GPU (WebGL is SwiftShader): seats, rooms and rounds are measured; the frame rate is not a person\'s.' } : {}),
+      why: humans >= 2 ? undefined : `the round's results list ${humans} person(s); both browsers should be in it`,
       totalMs: Date.now() - started,
     };
   } catch (error) {
@@ -163,6 +223,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/chrome.mjs

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

package/lib/cloudflare.mjs

@@ -19,11 +19,11 @@
  * before anything happens and calls nothing.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.mjs';
 import { ensureLocalIgnored, ensureStatsMigration, wranglerConfig } from './scaffold.mjs';
-import { LOCAL_STATE, isWorkersDev, readLocal, readStudio, siteUrl, writeLocal, writeStudio } from './studio.mjs';
+import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
 
@@ -36,7 +36,7 @@ export function wranglerBin(root) {
 export function runner(root, env) {
   const bin = wranglerBin(root);
   if (!bin) throw new Error('Wrangler is not installed in this studio yet: run `npm install` in the studio folder first');
-  return (args, { cwd = join(root, 'site'), input } = {}) => {
+  return (args, { cwd = workerDir(root), input } = {}) => {
     const res = spawnSync(bin, args, {
       cwd, env: { ...process.env, ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' }, encoding: 'utf8',
       input, maxBuffer: 64 * 1024 * 1024, timeout: 10 * 60_000,
@@ -186,7 +186,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   const r2 = cf.r2 && created.has(`r2:${cf.r2}`) ? cf.r2 : null;
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
-  writeFileSync(join(root, 'site', 'wrangler.jsonc'), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2 }));
+  writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root) }));
   const added = ensureStatsMigration(root);
   if (added) step(`added ${added} (the studio's own stats: counts, never tracks)`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
@@ -211,20 +211,14 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   const url = siteUrl(root);
   step(`deployed ${cf.worker} in ${Math.round((Date.now() - started) / 1000)} s`, { url, ...(workersDev && workersDev !== url ? { workersDev } : {}) });
 
-  // The homie.rocks directory claim, for the site's public address (its own domain when it has one): the site
-  // serves it, which proves this studio controls the site.
+  // The homie.rocks directory claim: the live site claims itself the first time its manifest is read (0.10.0), so
+  // reading it once now is all it takes; nothing is stored by hand.
   const directory = homie || studio.homie?.directory || 'https://homie.rocks';
   let claim = null;
   if (url) {
-    try {
-      const res = await fetch(`${directory.replace(/\/+$/, '')}/api/studio/claim?site=${encodeURIComponent(url)}`);
-      const body = await res.json();
-      if (res.ok && /^[a-f0-9]{16,128}$/.test(body.claim ?? '')) claim = body.claim;
-    } catch { /* the directory is optional for a live site */ }
-    if (claim) {
-      const put = w(['d1', 'execute', cf.d1, '--remote', '--command', `INSERT OR REPLACE INTO meta (key, value) VALUES ('homie_claim', '${claim}')`]);
-      step(put.code === 0 ? 'directory claim stored' : 'could not store the directory claim (publish will say so)');
-    }
+    claim = await warmClaim(url);
+    if (claim) step('the site claimed itself in the directory');
+    else step('the directory claim is not there yet (the site claims itself when the directory first reads it)');
   }
 
   // studio.json keeps what is safe to commit: names, ids, the custom domain; never the workers.dev address.
@@ -240,6 +234,81 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   };
 }
 
+/**
+ * Read the live site's manifest once, which makes a 0.10.0 site claim itself in its directory. Returns the claim it
+ * serves, or null (the directory did not answer, the site is not reachable yet, or it is a Preview). A fresh deploy
+ * can take a few seconds to answer everywhere, so it asks three times.
+ */
+export async function warmClaim(site, { tries = 3, wait = 2500 } = {}) {
+  if (process.env.HOMIE_STUDIO_WARM === '0') return null; // the toolkit's own tests: their live site is made up
+  for (let i = 0; i < tries; i++) {
+    try {
+      const res = await fetch(`${String(site).replace(/\/+$/, '')}/.well-known/homie-studio.json`, { headers: { accept: 'application/json', 'user-agent': 'homie-studio-deploy' }, signal: AbortSignal.timeout(15_000) });
+      if (res.ok) {
+        const body = await res.json();
+        if (/^[a-f0-9]{16,128}$/.test(body?.claim ?? '')) return body.claim;
+      }
+    } catch { /* not answering yet */ }
+    if (i < tries - 1) await new Promise((r) => setTimeout(r, wait));
+  }
+  return null;
+}
+
+/** The Worker's name and D1 database, as the studio's wrangler.jsonc says (Cloudflare's forms may have renamed them). */
+export function configNames(root) {
+  try {
+    const text = readFileSync(configPath(root), 'utf8');
+    const json = JSON.parse(text.replace(/^\s*\/\/.*$/gm, ''));
+    return { worker: json.name ?? null, d1: json.d1_databases?.[0]?.database_name ?? null, binding: json.d1_databases?.[0]?.binding ?? 'DB' };
+  } catch { return { worker: null, d1: null, binding: 'DB' }; }
+}
+
+/*
+ * `npm run deploy` IN WORKERS BUILDS (WORKERS_CI=1, or `deploy --ci`). Cloudflare's own CI has already run
+ * `npm run build`, and holds its own API token for this one account; the Worker and its database were made by the
+ * "Deploy to Cloudflare" flow or by an earlier deploy. So this only applies the D1 migrations (by binding name: the
+ * form may have renamed the database) and deploys. It creates nothing by hand and refuses nothing, and writes
+ * nothing back (a CI checkout is thrown away). On the very first deploy the database may not exist yet: Wrangler
+ * creates the one the binding names while it deploys, and the migrations run right after.
+ */
+export async function ciDeploy(root, { log = () => {} } = {}) {
+  const w = runner(root, {});
+  const names = configNames(root);
+  const steps = [];
+  const step = (what) => { steps.push({ what }); log(what); };
+  const refuse = (why, out) => ({ ok: false, command: 'deploy', ci: true, ...(explainCloudflare(out) ?? { why }), steps });
+  if (!existsSync(join(root, 'site', 'dist', 'games.json'))) return { ok: false, command: 'deploy', ci: true, why: 'nothing is built: the build command is `npm run build` (homie-studio build), and it runs before this', steps };
+  if (ensureStatsMigration(root)) step('added the stats migration (the studio\'s own counters)');
+  const apply = () => w(['d1', 'migrations', 'apply', names.binding, '--remote']);
+  let migrate = apply();
+  const first = migrate.code !== 0 && /not found|could(?:n't| not) find|does not exist|no database|database_id/i.test(migrate.out);
+  if (migrate.code !== 0 && !first) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
+  if (!first) step('D1 migrations applied');
+  const started = Date.now();
+  const dep = w(['deploy']);
+  if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
+  step(`deployed ${names.worker ?? 'the Worker'} in ${Math.round((Date.now() - started) / 1000)} s`);
+  if (first) {
+    migrate = apply();
+    if (migrate.code !== 0) return refuse(`D1 migrations failed after the first deploy: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
+    step('D1 migrations applied (the database was created with this first deploy)');
+  }
+  // The live address, from what Wrangler printed (a custom domain in studio.json wins).
+  const workersDev = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? null;
+  let url = null;
+  try { url = siteUrl(root) ?? workersDev; } catch { url = workersDev; }
+  const claim = url ? await warmClaim(url) : null;
+  step(claim ? 'the site claimed itself in the directory' : 'no directory claim yet (the site claims itself when the directory first reads it)');
+  let games = [];
+  try { games = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8')).games.map((g) => g.id); } catch { games = []; }
+  return {
+    ok: true, command: 'deploy', ci: true, url, worker: names.worker, d1: names.d1, r2: null, steps, announced: [],
+    commit: process.env.WORKERS_CI_COMMIT_SHA ?? null, branch: process.env.WORKERS_CI_BRANCH ?? null,
+    games: games.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null })), songs: [], videos: [],
+    claim: Boolean(claim),
+  };
+}
+
 /*
  * `homie-studio storage add` — the studio's own storage for large media (songs,
  * videos, big art), as an R2 bucket on its account, bound as MEDIA and served at
@@ -283,7 +352,7 @@ export async function storageAdd(root, { log = () => {} } = {}) {
   const next = { ...readStudio(root), cloudflare: { ...readStudio(root).cloudflare, accountId, r2: bucket, created: [...created].sort() } };
   writeStudio(root, next);
   if (next.cloudflare.d1Id) {
-    writeFileSync(join(root, 'site', 'wrangler.jsonc'), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket }));
+    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root) }));
   }
   log(`created R2 ${bucket}`);
   return { ok: true, command: 'storage add', bucket, account: accountId, next: ['npm run deploy   (binds the bucket as MEDIA; the site serves it at /media/<key>)', 'npx --no-install homie-studio media put <file>'] };

package/lib/look.mjs

@@ -7,16 +7,11 @@
  * `--shots` (default .studio/look/), which git ignores. One Chrome, closed at the end; its visits are house QA
  * (the studio's stats leave them out).
  */
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { chromeArgs, findChrome, noChrome } from './chrome.mjs';
 
-const CHROMES = [
-  process.env.CHROME_PATH,
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-  '/Applications/Chromium.app/Contents/MacOS/Chromium',
-  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
-].filter(Boolean);
 
 export const LOOK_DEVICES = {
   computer: { width: 1440, height: 900, deviceScaleFactor: 1 },
@@ -29,16 +24,17 @@ const nameOf = (path) => path.replace(/^\/+|\/+$/g, '').replace(/[^a-z0-9]+/gi,
 
 export async function look({ url, paths, shots, devices = Object.keys(LOOK_DEVICES), log = () => {} }) {
   if (!url) return { ok: false, command: 'look', why: 'give --url (the local dev address or the live site)' };
-  const chrome = CHROMES.find((p) => existsSync(p));
-  if (!chrome) return { ok: false, command: 'look', why: 'no Chrome found (set CHROME_PATH)' };
+  const chrome = findChrome();
+  if (!chrome) return { ok: false, command: 'look', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'look', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
   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,
-    args: ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
+    executablePath: chrome, headless: true, userDataDir: profile, timeout: 150_000, protocolTimeout: 180_000,
+    args: [...chromeArgs(), '--autoplay-policy=no-user-gesture-required', '--no-first-run', '--no-default-browser-check'],
   });
   const rows = [];
   try {
@@ -51,7 +47,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('/')}` };