@homie-rocks/studio 0.5.0 → 0.7.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.5.0.tgz homie-studio new ./night-owls --name "Night Owls"
+npx -y --package=https://homie.rocks/npm/homie-studio-0.7.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
@@ -18,8 +18,58 @@ npx homie-studio check crown-thief --url http://127.0.0.1:8787
 npx homie-studio deploy --plan                         # what deploy will create, and what it costs; changes nothing
 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
 ```
 
+## 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`
+block (`maxPlayers`), or a `netplay.json` beside game.json or in the game's build
+(`maxPlayers` or `players.max`), else game.json's `players.max`, else 8; at most 32.
+Bots, a late joiner taking a bot's body and a new host after the old one leaves work
+the same at 32 as at 4. One address may hold every seat plus four sockets, so a party
+on one Wi-Fi (or strangers behind one carrier's address) fills a room with a TV beside it.
+
+## The studio's own stats
+
+The site counts, and never tracks: pages opened, Play presses, rooms opened, the most
+people playing at once, rounds finished, songs played, videos watched, and which site
+sent each visitor (a host name: homie.rocks, another studio, search, the web, or a
+`?via=` tag). They are daily counters in the studio's own D1, on the free plan (a write
+per visit and per round, never per frame), with no cookie on a visitor and nothing sent
+to anyone. Prefetches, crawlers and house QA are not counted. Only the owner reads them:
+
+```sh
+npx homie-studio stats [--range 7d] [--game crown-thief]   # prints them
+npx homie-studio stats link                             # a one-time link: /_studio/stats in the owner's browser
+npx homie-studio stats key                              # a 1-hour read key for the Homie MCP tool studio_stats
+npx homie-studio stats share on                         # tell the directory "played this week" (two numbers)
+```
+
+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.
+
+## The site's address
+
+`deploy` keeps the `workers.dev` address in `.studio/local.json`, which git ignores: it
+names the Cloudflare account, often after its owner. A custom domain goes in studio.json
+as `cloudflare.domain` and is what the directory claim, `publish`, `check` and `stats` use.
+
 ## No payment method needed
 
 `deploy` creates only what Cloudflare's free Workers plan gives a new account with no
@@ -61,7 +111,9 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `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`. |
-| `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>`). |
+| `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`). |
 | `starters/gem-rush/` | The reference multiplayer starter. |

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>]
@@ -21,6 +23,11 @@
  *   homie-studio media put <file> [--as <key>]
  *   homie-studio media list
  *   homie-studio status
+ *   homie-studio stats [--range 1d|7d|30d|90d] [--game <id> | --song <slug> | --video <slug>] [--url <site>]
+ *   homie-studio stats key [--hours 1]    (a read key for the Homie MCP tool studio_stats)
+ *   homie-studio stats link               (a one-time link to the private stats page, for the owner's browser)
+ *   homie-studio stats revoke             (every stats key and page session ends)
+ *   homie-studio stats share on|off       (tell the homie.rocks directory "played this week", or stop)
  *
  * Every command prints a few lines for a person; --json prints the result.
  */
@@ -31,12 +38,14 @@ 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';
-import { newStudio } from '../lib/scaffold.mjs';
-import { listGames, newGame, readStudio, remixGame, requireStudio, starters } from '../lib/studio.mjs';
+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';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
@@ -56,7 +65,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) {
@@ -75,7 +84,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']) {
@@ -85,7 +99,9 @@ function print(result) {
       }
       break;
     case 'deploy':
-      lines.push(`Live: ${result.url}`, ...result.games.map((g) => `  ${g.id}: ${g.play}`), ...(result.songs ?? []).map((m) => `  song ${m.slug}: ${m.page}`), ...(result.videos ?? []).map((m) => `  video ${m.slug}: ${m.page}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}, Durable Objects Table + Lobby${result.r2 ? `, R2 ${result.r2}` : ' (no storage: none needed; `homie-studio storage add` adds it for large media)'}. All on the free Workers plan${result.r2 ? ' plus R2' : ''}.`,
+      lines.push(`Live: ${result.url}`, ...(result.workersDev && result.workersDev !== result.url ? [`  also at ${result.workersDev}`] : []),
+        ...(result.local ? [`  (the workers.dev address names your Cloudflare account, so it is kept in ${result.local} on this computer, never in studio.json)`] : []),
+        ...result.games.map((g) => `  ${g.id}: ${g.play}`), ...(result.songs ?? []).map((m) => `  song ${m.slug}: ${m.page}`), ...(result.videos ?? []).map((m) => `  video ${m.slug}: ${m.page}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}, Durable Objects Table + Lobby${result.r2 ? `, R2 ${result.r2}` : ' (no storage: none needed; `homie-studio storage add` adds it for large media)'}. All on the free Workers plan${result.r2 ? ' plus R2' : ''}.`,
         result.claim ? 'Directory claim stored: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the directory did not answer); publish will try again.');
       break;
     case 'deploy plan':
@@ -116,6 +132,32 @@ function print(result) {
       lines.push(`${result.ok ? 'PASS' : 'NOT YET'}: ${result.game} at ${result.url} (${Math.round(result.totalMs / 1000)} s)`,
         ...result.passed.map((p) => `  ok    ${p}`), ...result.failed.map((f) => `  FAIL  ${f}`), ...result.skipped.map((f) => `  skip  ${f}`), '', `Receipt and screenshots: ${result.out}`);
       break;
+    case 'stats': {
+      const t = result.totals;
+      const n = (x) => Number(x || 0).toLocaleString('en-US');
+      lines.push(`${result.studio ?? 'Studio'}: ${result.range.from} to ${result.range.to} (UTC)${result.only ? `, ${result.only.kind} ${result.only.id}` : ''}`,
+        `  ${n(t.visits)} visits · ${n(t.plays)} Play presses · ${n(t.rooms)} rooms opened · ${n(t.rounds)} rounds finished (${n(t.roundsWithPeople)} with people, ${n(t.peopleInRounds)} people in them)`,
+        `  most playing at once: ${n(t.peakPlayers)} (${n(t.peakInOneRoom)} in one room) · playing now: ${n(t.playingNow)} · songs played: ${n(t.songPlays)} · videos watched: ${n(t.videoViews)}`,
+        `  came from homie.rocks: ${n(result.crossings.fromHub)} · other studios: ${n(result.crossings.fromStudios)} · search: ${n(result.crossings.fromSearch)} · the web: ${n(result.crossings.fromWeb)} · ?via= links: ${n(result.crossings.fromLinks)}`);
+      for (const g of result.games) lines.push(`  game ${g.id}: ${n(g.visits)} visits, ${n(g.plays)} plays, ${n(g.rooms)} rooms, ${n(g.rounds)} rounds, peak ${n(g.peakPlayers)}, now ${n(g.playingNow)}`);
+      for (const e of result.songs) lines.push(`  song ${e.slug}: ${n(e.visits)} page visits, played ${n(e.plays)}`);
+      for (const e of result.videos) lines.push(`  video ${e.slug}: ${n(e.visits)} page visits, watched ${n(e.views)}`);
+      for (const r of result.referrers.slice(0, 10)) lines.push(`  from ${r.from} (${r.kind}): ${n(r.visits)} visits, ${n(r.plays)} plays`);
+      break;
+    }
+    case 'stats key':
+      lines.push(`Read key (until ${result.expiresAt}): ${result.key}`, result.use);
+      break;
+    case 'stats link':
+      lines.push(`One-time link (until ${result.expiresAt}): ${result.link}`, result.use);
+      break;
+    case 'stats revoke':
+    case 'stats share':
+      lines.push(result.message);
+      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`));
@@ -142,7 +184,7 @@ async function main() {
   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') ?? readStudio(root).cloudflare?.url;
+    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 });
   }
@@ -152,16 +194,29 @@ async function main() {
   if (cmd === 'build') return build(root, { only: positional[1] ?? null, log });
   if (cmd === 'status') {
     const studio = readStudio(root);
-    return { ok: true, command: 'status', root, studio, games: listGames(root).map((g) => g.id), cloudflareSignedIn: Boolean(wranglerBin(root) && whoami(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 === 'dev' && flags.has('stop')) return stopDev(root);
   if (cmd === 'dev') return dev(root);
   if (cmd === 'check') {
     const game = positional[1] ?? listGames(root)[0]?.id;
-    const url = flags.get('url') ?? readStudio(root).cloudflare?.url;
+    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 });
   }
+  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 === 'storage' && sub === 'add') return storageAdd(root, { log });
@@ -171,12 +226,17 @@ async function main() {
     return { ok: true, command: 'storage', storage: has ? { kind: 'r2', bucket: cf.r2 } : null, why: has ? undefined : 'no storage yet: the studio runs without it; `homie-studio storage add` adds an R2 bucket for large media (Cloudflare asks for a payment method before R2 works)' };
   }
   if (cmd === 'publish') return publish(root, { homie: flags.get('homie'), site: flags.get('site') });
+  if (cmd === 'stats' && sub === 'key') return statsKey(root, { url: flags.get('url'), hours: flags.get('hours') });
+  if (cmd === 'stats' && sub === 'link') return statsLink(root, { url: flags.get('url') });
+  if (cmd === 'stats' && sub === 'revoke') return statsRevoke(root, { url: flags.get('url') });
+  if (cmd === 'stats' && sub === 'share') return statsShare(root, positional[2]);
+  if (cmd === 'stats' && !sub) return statsShow(root, { url: flags.get('url'), range: flags.get('range'), game: flags.get('game'), song: flags.get('song'), video: flags.get('video') });
   if (cmd === 'media' && sub === 'put') return mediaPut(root, positional[2], flags.get('as'));
   if (cmd === 'media' && sub === 'list') {
     const studio = readStudio(root);
     const r2 = Boolean(studio.cloudflare?.r2 && (studio.cloudflare?.created ?? []).includes(`r2:${studio.cloudflare.r2}`));
     const view = (kind) => { const r = resolveMedia(root, kind, { r2 }); return { pages: r.entries.map((e) => ({ slug: e.slug, title: e.title, kind: e.kind, files: e.files.map(({ abs, rel, ...f }) => f) })), skipped: r.skipped }; };
-    return { ok: true, command: 'media list', r2, site: studio.cloudflare?.url ?? null, music: view('music'), videos: view('videos') };
+    return { ok: true, command: 'media list', r2, site: siteUrl(root, studio), music: view('music'), videos: view('videos') };
   }
   return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
 }
@@ -222,6 +282,8 @@ async function dev(root) {
   if (!bin) return { ok: false, command: 'dev', why: 'run npm install in the studio first' };
   const studio = readStudio(root);
   const env = { ...process.env, WRANGLER_SEND_METRICS: 'false', CI: '1' };
+  const added = ensureStatsMigration(root);
+  if (added) log(`added ${added} (the studio's own stats)`);
   await new Promise((done) => {
     const m = spawn(bin, ['d1', 'migrations', 'apply', studio.cloudflare.d1, '--local'], { cwd: join(root, 'site'), env, stdio: ['ignore', 'ignore', 'inherit'] });
     m.on('close', done);
@@ -253,8 +315,10 @@ function mediaPut(root, file, as) {
     const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: join(root, 'site'), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
     p.on('close', (code) => {
       if (code !== 0) return done({ ok: false, command: 'media put', why: 'wrangler r2 object put failed' });
-      const rec = recordUpload(root, rel, key, statSync(file).size, studio.cloudflare?.url ?? null);
-      done({ ok: true, command: 'media put', key, manifest: rec.manifest, entry: rec.entry, url: studio.cloudflare?.url ? `${studio.cloudflare.url}/media/${key}` : null });
+      // The manifest is committed: it names the file by its path on the site, never the workers.dev address.
+      const rec = recordUpload(root, rel, key, statSync(file).size);
+      const site = siteUrl(root, studio);
+      done({ ok: true, command: 'media put', key, manifest: rec.manifest, entry: rec.entry, url: site ? `${site}/media/${key}` : null });
     });
   });
 }
@@ -264,7 +328,7 @@ try {
   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) {
   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,7 +26,9 @@ 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';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
@@ -76,6 +82,31 @@ export function sourceOf(dir, id) {
   return { v: 1, kind: 'homie-game-source', id, files };
 }
 
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+/**
+ * A game's netplay manifest: game.json's `netplay` block, over a `netplay.json` beside game.json or in the game's
+ * built output (a ported Vite game ships public/netplay.json), over nothing.
+ */
+export function netplayOf(g, out = null) {
+  const file = readJson(join(g.dir, 'netplay.json')) ?? (out ? readJson(join(out, 'netplay.json')) : null) ?? {};
+  return { ...(file && typeof file === 'object' ? file : {}), ...(g.netplay && typeof g.netplay === 'object' ? g.netplay : {}) };
+}
+
+/**
+ * How many seats a room of this game has: the netplay manifest's `maxPlayers` (or `players.max`), else game.json's
+ * `players.max`, else 8; at most SEAT_MAX (32). `asked` is what the game named, so a build can say it was capped.
+ */
+export function seatsFor(g, net = netplayOf(g)) {
+  const named = [net.maxPlayers, net.players?.max, g.players?.max].map((n) => Math.floor(Number(n))).find((n) => Number.isFinite(n) && n >= 1);
+  const asked = named ?? 8;
+  const max = Math.min(SEAT_MAX, asked);
+  const minNamed = [net.minPlayers, net.players?.min, g.players?.min].map((n) => Math.floor(Number(n))).find((n) => Number.isFinite(n) && n >= 1);
+  return { min: Math.min(max, minNamed ?? 1), max, asked };
+}
+
 export async function build(root, { only = null, log = () => {} } = {}) {
   const require = createRequire(join(root, 'package.json'));
   let esbuild;
@@ -134,7 +165,9 @@ export async function build(root, { only = null, log = () => {} } = {}) {
     if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id))}\n`);
     const main = join(out, 'assets', 'main.js');
     const bytes = existsSync(main) ? statSync(main).size : dirBytes(out);
-    built.push({ id: g.id, name: g.name, mode, bytes, ms: Date.now() - started, warnings });
+    const seats = seatsFor(g, netplayOf(g, out));
+    if (seats.asked > SEAT_MAX) log(`warning: games/${g.id} asks for ${seats.asked} players; a room holds at most ${SEAT_MAX}, so its rooms have ${SEAT_MAX} seats`);
+    built.push({ id: g.id, name: g.name, mode, bytes, ms: Date.now() - started, warnings, seats: seats.max });
     log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB)`);
   }
   const all = listGames(root);
@@ -145,19 +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: [] }; }
   }
-  const catalogue = {
-    studio: { name: studio.name, slug: studio.slug, version: STUDIO_VERSION },
-    games: all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))).map((g) => ({
-      id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: g.players ?? { min: 1, max: 8 },
-      roundSeconds: g.roundSeconds ?? null, movement: g.netplay?.movement ?? null, cover: g.cover ?? null,
+  // 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: 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/cloudflare.mjs

@@ -22,8 +22,8 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.mjs';
-import { wranglerConfig } from './scaffold.mjs';
-import { readStudio, writeStudio } from './studio.mjs';
+import { ensureLocalIgnored, ensureStatsMigration, wranglerConfig } from './scaffold.mjs';
+import { LOCAL_STATE, isWorkersDev, readLocal, readStudio, siteUrl, writeLocal, writeStudio } from './studio.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
 
@@ -32,7 +32,8 @@ export function wranglerBin(root) {
   return existsSync(local) ? local : null;
 }
 
-function runner(root, env) {
+/** Wrangler from the studio's own node_modules, run in site/ with the given environment. */
+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 } = {}) => {
@@ -95,7 +96,7 @@ export function deployPlan(root) {
     ok: true, command: 'deploy plan', studio: studio.name, account: cf.accountId ?? null,
     cloudflare: [
       { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`), plan: 'Workers Free' },
-      { kind: 'D1 database', name: cf.d1, what: 'the directory claim and every finished round', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
+      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, and the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor)', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
       { kind: 'Durable Object', name: 'Table', what: 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       storage
@@ -144,7 +145,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   if (!created.has(`worker:${cf.worker}`)) {
     const account = who.accounts.find((a) => a.id === accountId)?.name ?? 'the signed-in account';
     announced.push(
-      `First deploy of ${studio.name} to the Cloudflare account "${account}". It creates: the Worker ${cf.worker} (the site and its rooms), the D1 database ${cf.d1}, and the Durable Objects Table and Lobby (SQLite-backed).`,
+      `First deploy of ${studio.name} to the Cloudflare account "${account}". It creates: the Worker ${cf.worker} (the site and its rooms), the D1 database ${cf.d1} (rounds, and the studio's own stats: counts for the owner, never a visitor's identity), and the Durable Objects Table and Lobby (SQLite-backed).`,
       'Cost: free, on the Workers Free plan; no payment method, no R2 (storage for large media is `homie-studio storage add`, later, only if wanted).',
       `The directory (${homie || studio.homie?.directory || 'https://homie.rocks'}) will store the site's address and claim, the studio's name, and each game's name, blurb and Play link.`,
     );
@@ -186,6 +187,8 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   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 }));
+  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']);
   if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   step('D1 migrations applied');
@@ -194,10 +197,22 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   const dep = w(['deploy']);
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
   remember(`worker:${cf.worker}`);
-  const url = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? cf.url ?? null;
-  step(`deployed ${cf.worker} in ${Math.round((Date.now() - started) / 1000)} s`, { url });
+  // The workers.dev address names the Cloudflare account (often after its owner): it stays on this computer, in
+  // .studio/local.json (git-ignored), and never in the committed studio.json. A custom domain stays in studio.json.
+  if (ensureLocalIgnored(root)) step(`added .studio/ to .gitignore (${LOCAL_STATE} keeps this computer's own state)`);
+  const workersDev = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? readLocal(root).url ?? (isWorkersDev(cf.url) ? cf.url : null);
+  if (workersDev) writeLocal(root, { url: workersDev, deployedAt: new Date().toISOString() });
+  const movedOut = isWorkersDev(cf.url);
+  if (movedOut) {
+    cf.url = null;
+    writeStudio(root, { ...readStudio(root), cloudflare: { ...readStudio(root).cloudflare, url: null } });
+    step(`studio.json no longer keeps the workers.dev address (it names the Cloudflare account); it is in ${LOCAL_STATE} on this computer. An earlier commit of studio.json still has it in the repository's history.`);
+  }
+  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: the site serves it, which proves this studio controls the site.
+  // 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.
   const directory = homie || studio.homie?.directory || 'https://homie.rocks';
   let claim = null;
   if (url) {
@@ -212,10 +227,12 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
     }
   }
 
-  const next = { ...cf, accountId, url, d1Id: db.uuid, r2: cf.r2 ?? null, created: [...created].sort(), deployedAt: new Date().toISOString() };
-  writeStudio(root, { ...studio, cloudflare: next });
+  // studio.json keeps what is safe to commit: names, ids, the custom domain; never the workers.dev address.
+  const { url: _url, deployedAt: _at, ...kept } = cf;
+  const next = { ...kept, ...(cf.url && !isWorkersDev(cf.url) ? { url: cf.url } : {}), accountId, d1Id: db.uuid, r2: cf.r2 ?? null, created: [...created].sort() };
+  writeStudio(root, { ...readStudio(root), cloudflare: next });
   return {
-    ok: true, command: 'deploy', url, worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
+    ok: true, command: 'deploy', url, ...(workersDev ? { workersDev, local: LOCAL_STATE } : {}), worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
     games: b.catalogue.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null })),
     songs: b.songs.map((slug) => ({ slug, page: url ? `${url}/music/${slug}/` : null })),
     videos: b.videos.map((slug) => ({ slug, page: url ? `${url}/videos/${slug}/` : null })),

package/lib/directory.mjs

@@ -4,12 +4,12 @@
  * claim the directory gave it (`homie-studio deploy` stores it in D1), so
  * nobody can list games under someone else's site.
  */
-import { readStudio } from './studio.mjs';
+import { readStudio, siteUrl } from './studio.mjs';
 
 export async function publish(root, { homie, site } = {}) {
   const studio = readStudio(root);
   const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
-  const url = site || studio.cloudflare?.url;
+  const url = site || siteUrl(root, studio);
   if (!url) return { ok: false, command: 'publish', why: 'this studio has no live site yet: run `npm run deploy` first' };
   const res = await fetch(`${directory}/api/studio/publish`, {
     method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ site: url }),

package/lib/look.mjs

@@ -0,0 +1,101 @@
+/**
+ * `homie-studio look [<path>...] --url <site> [--shots <dir>]` — the studio's pages as a stranger sees them:
+ * each page on a computer (1440 x 900), a phone held upright (390 x 844) and the phone turned sideways
+ * (844 x 390), scrolled to the end so everything that rises into view has, then shot whole and above the fold.
+ * Measured on every shot: the answer's status, anything wider than the screen, whether the Play button is on the
+ * first screen (Home and a game's landing), pictures that did not load, footage that did not play, and script errors. Pictures go to
+ * `--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 { 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);
+
+export const LOOK_DEVICES = {
+  computer: { width: 1440, height: 900, deviceScaleFactor: 1 },
+  phone: { width: 390, height: 844, deviceScaleFactor: 2, isMobile: true, hasTouch: true },
+  sideways: { width: 844, height: 390, deviceScaleFactor: 2, isMobile: true, hasTouch: true },
+};
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const nameOf = (path) => path.replace(/^\/+|\/+$/g, '').replace(/[^a-z0-9]+/gi, '-') || 'home';
+
+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)' };
+  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-'));
+  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'],
+  });
+  const rows = [];
+  try {
+    for (const path of paths) {
+      for (const device of devices) {
+        const page = await browser.newPage();
+        const errors = [];
+        page.on('pageerror', (e) => errors.push(String(e?.message ?? e).slice(0, 200)));
+        page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text().slice(0, 200)); });
+        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 ms = Date.now() - t0;
+        await sleep(900);
+        const fold = await page.evaluate(() => {
+          // Home and a game's landing lead with Play; other pages (a post, the rooms) are not judged on it.
+          if (!['home', 'landing'].includes(document.body?.dataset?.page ?? '')) return { play: null };
+          const play = [...document.querySelectorAll('.play')].find((a) => { const r = a.getBoundingClientRect(); return r.width > 0 && r.height > 0; });
+          const r = play?.getBoundingClientRect();
+          return { play: r ? r.bottom <= innerHeight && r.top >= 0 : false };
+        });
+        const foldFile = join(shots, `${nameOf(path)}-${device}-fold.png`);
+        await page.screenshot({ path: foldFile });
+        await page.evaluate(async () => { for (let y = 0; y < document.documentElement.scrollHeight; y += Math.round(innerHeight * 0.7)) { window.scrollTo({ top: y, behavior: 'instant' }); await new Promise((r) => setTimeout(r, 110)); } window.scrollTo({ top: 0, behavior: 'instant' }); });
+        await sleep(900);
+        const facts = await page.evaluate(() => ({
+          title: document.title,
+          wide: [...document.querySelectorAll('body *')].filter((e) => { const b = e.getBoundingClientRect(); return b.width > 0 && b.right > innerWidth + 1 && !e.closest('[data-hero-media],.nav,pre,.hero-media'); }).slice(0, 5).map((e) => `${e.tagName.toLowerCase()}${e.className ? `.${String(e.className).split(' ')[0]}` : ''}`),
+          brokenImages: [...document.images].filter((i) => i.complete && i.naturalWidth === 0 && i.getAttribute('src')).map((i) => i.getAttribute('src')).slice(0, 5),
+          footage: [...document.querySelectorAll('[data-hero-media] video')].map((v) => ({ playing: !v.paused && v.readyState >= 2, src: (v.currentSrc || '').split('/').pop() })),
+          height: document.documentElement.scrollHeight,
+        }));
+        const file = join(shots, `${nameOf(path)}-${device}.png`);
+        await page.screenshot({ path: file, fullPage: true });
+        const row = {
+          path, device, status: res?.status() ?? null, ms, title: facts.title, height: facts.height, playAboveFold: fold.play,
+          tooWide: facts.wide, brokenImages: facts.brokenImages, footage: facts.footage, errors, shot: file, fold: foldFile,
+        };
+        const bad = [];
+        if (!row.status || row.status >= 400) bad.push(`answered ${row.status}`);
+        if (row.tooWide.length) bad.push(`wider than the screen: ${row.tooWide.join(', ')}`);
+        if (row.playAboveFold === false && device !== 'sideways') bad.push('Play is not on the first screen');
+        if (row.brokenImages.length) bad.push(`pictures that did not load: ${row.brokenImages.join(', ')}`);
+        if (row.footage.some((f) => !f.playing)) bad.push('the hero footage did not play');
+        if (errors.length) bad.push(`${errors.length} script error(s): ${errors[0]}`);
+        row.ok = bad.length === 0;
+        row.problems = bad;
+        rows.push(row);
+        log(`${row.ok ? 'ok  ' : 'LOOK'} ${path} ${device}: ${row.status} in ${ms} ms${bad.length ? ` · ${bad.join(' · ')}` : ''}`);
+        await page.close();
+      }
+    }
+  } finally {
+    await browser.close().catch(() => {});
+    rmSync(profile, { recursive: true, force: true });
+  }
+  writeFileSync(join(shots, 'look.json'), `${JSON.stringify(rows, null, 2)}\n`);
+  return { ok: rows.every((r) => r.ok), command: 'look', url: base, shots, rows };
+}