@homie-rocks/studio 0.3.0 → 0.6.0

package/README.md

@@ -1,24 +1,82 @@
 # @homie-rocks/studio
 
-A game studio on its own Cloudflare. One repository (`AGENTS.md`, `games/`, `music/`,
-`videos/`, `posts/`, `site/`), multiplayer games on the Homie netplay contract (every
-browser renders, strangers meet in public rooms, bots fill seats, rounds restart), and a
-site Worker with Table/Lobby Durable Objects, D1 and R2 that the studio deploys to its
-own Cloudflare account with Wrangler. The homie.rocks directory lists the games.
+A studio for games, music and video on its own Cloudflare. One repository (`AGENTS.md`,
+`games/`, `music/`, `videos/`, `posts/`, `site/`), multiplayer games on the Homie netplay
+contract (every browser renders, strangers meet in public rooms, bots fill seats, rounds
+restart), and a site Worker with Table/Lobby Durable Objects and D1 that the studio deploys
+to its own Cloudflare account with Wrangler. The homie.rocks directory lists the games.
 
 Most people never run this by hand: the Homie plugin for Claude Code and Codex does,
 and the person approves Cloudflare once in their browser.
 
 ```sh
-npx -y --package=https://homie.rocks/npm/homie-studio-0.3.0.tgz homie-studio new ./night-owls --name "Night Owls"
+npx -y --package=https://homie.rocks/npm/homie-studio-0.6.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
 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
 ```
 
+## 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
+payment method: one Worker, one D1 database and two SQLite-backed Durable Objects
+(`Table`, `Lobby`). It never creates or binds R2. A brand-new Cloudflare account verifies
+its email address before it can run a Worker; a missing `workers.dev` subdomain is
+registered by Wrangler when Claude Code or Codex runs the deploy.
+
+Storage for large media (songs, videos, big art) is a separate, optional step:
+
+```sh
+npx homie-studio storage add                           # an R2 bucket, bound as MEDIA, served at /media/<key>
+npx homie-studio deploy
+npx homie-studio media put music/theme.wav
+```
+
+Cloudflare asks for a payment method on the account before R2 works, even inside R2's free
+tier (10 GB-month of storage, 1 million writes and 10 million reads a month), so `storage add`
+refuses with the dashboard link until the account has R2 turned on, and creates nothing.
+The free plan's daily limits (100,000 Worker requests; D1 5 million rows read and 100,000
+written) reset at 00:00 UTC; past them requests fail until the reset and nothing is charged.
+
 An existing single-player web game becomes a multiplayer one with the port toolkit
 (the plugin's `port` skill drives it):
 
@@ -33,19 +91,26 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `bin/homie-studio.mjs` | The CLI. |
 | `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`: Wrangler, D1, R2, migrations, the directory claim; refuses resources it did not create. |
+| `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/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`). |
+| `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/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. |
 
 Versions are immutable: a published version never changes, so a studio that pinned one
-never changes by surprise. A change ships as a new `version`. Until the package is on the
-npm registry, each version's tarball is served at
-`https://homie.rocks/npm/homie-studio-<version>.tgz`.
+never changes by surprise. A change ships as a new `version`, on the npm registry as
+`@homie-rocks/studio` and as a tarball at `https://homie.rocks/npm/homie-studio-<version>.tgz`
+(which is what `homie-studio new` pins).
+
+## Beta
+
+This is a beta. Bugs, port requests and questions go to
+<https://github.com/homie-rocks/homie/issues/new/choose>.
 
 ## License
 

package/bin/homie-studio.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * homie-studio — make a game studio, make its games, put its site on the
- * studio's own Cloudflare, and list its games in the homie.rocks directory.
+ * homie-studio — make a studio (games, music, videos, posts), make its games,
+ * put its site on the studio's own Cloudflare (free plan, no payment method), and
+ * list its games in the homie.rocks directory.
  *
  *   homie-studio new <folder> --name "<Studio Name>" [--homie <directory url>] [--no-install]
  *   homie-studio starters
@@ -9,34 +10,43 @@
  *   homie-studio game remix <source.json url> --id <new id>
  *   homie-studio games
  *   homie-studio build [<id>]
- *   homie-studio dev [--port 8787]
+ *   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 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>]
- *   homie-studio deploy
+ *   homie-studio deploy [--plan]          (--plan: what it will create on Cloudflare and what it costs; changes nothing)
  *   homie-studio publish
+ *   homie-studio storage add              (large media only: an R2 bucket; needs R2 turned on for the account)
  *   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.
  */
-import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { basename, join, relative, resolve } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { build } from '../lib/build.mjs';
 import { check } from '../lib/check.mjs';
-import { deploy, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
 import { publish } from '../lib/directory.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
-import { newStudio } from '../lib/scaffold.mjs';
-import { listGames, newGame, readStudio, remixGame, requireStudio, starters, writeStudio } from '../lib/studio.mjs';
+import { recordUpload, resolveMedia, typeOf } from '../lib/media.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();
-const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install'];
+const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -57,7 +67,7 @@ function print(result) {
   const lines = [];
   switch (result.command) {
     case 'new':
-      lines.push(`${result.name} is a studio now: ${result.dir}`, '', 'Wrote:', ...result.wrote.map((f) => `  ${f}`), '', `Dependencies: ${result.installed}`, '', 'Next:', ...result.next.map((n) => `  ${n}`));
+      lines.push(`${result.name} is a studio now: ${result.dir}`, '', 'Wrote:', ...result.wrote.map((f) => `  ${f}`), '', `Dependencies: ${result.installed}`, '', 'Next:', ...result.next.map((n) => `  ${n}`), '', result.online);
       break;
     case 'game remix':
       lines.push(`games/${result.id} is a remix of ${result.from} (${result.files.length} files). Make it yours in games/${result.id}/src/, then: npx homie-studio dev`);
@@ -65,12 +75,35 @@ function print(result) {
     case 'game new':
       lines.push(`games/${result.id} is a new game from the ${result.from} starter. Change it in games/${result.id}/src/, then: npx homie-studio dev`);
       break;
+    case 'dev stop':
+      lines.push(result.stopped.length ? `Stopped this studio's dev server (${result.stopped.join(', ')}).` : `Nothing to stop: ${result.why ?? 'no dev server of this studio is running'}.`);
+      break;
     case 'build':
-      lines.push(`Built ${result.games.map((g) => `${g.id} (${Math.round(g.bytes / 1024)} KB)`).join(', ') || 'nothing'} into ${relative(process.cwd(), result.dist) || result.dist}`);
+      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 m of result.mediaSkipped ?? []) lines.push(`  left out: ${m.kind}/${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
+      break;
+    case 'media list':
+      for (const kind of ['music', 'videos']) {
+        lines.push(`${kind}/manifest.json: ${result[kind].pages.length} page(s)`);
+        for (const e of result[kind].pages) lines.push(`  /${kind}/${e.slug}/  ${e.title}  (${e.files.map((f) => `${f.role} from ${f.from}`).join(', ')})`);
+        for (const m of result[kind].skipped) lines.push(`  left out: ${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
+      }
       break;
     case 'deploy':
-      lines.push(`Live: ${result.url}`, ...result.games.map((g) => `  ${g.id}: ${g.play}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}${result.r2 ? `, R2 ${result.r2}` : ', no R2 (not enabled on this account)'}`,
-        result.claim ? 'Directory claim stored: list the games with the Homie MCP tool studio_publish, or: npx homie-studio publish' : 'No directory claim yet (the directory did not answer); publish will try again.');
+      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':
+      lines.push(`What \`npm run deploy\` does for ${result.studio}, on the Cloudflare account the person approves:`, '',
+        ...result.cloudflare.map((r) => `  ${r.kind}${r.name ? ` ${r.name}` : ''}: ${r.what} [${r.state}${r.plan ? `; ${r.plan}` : ''}]`), '',
+        `Cost: ${result.cost}`, `Sign-in: ${result.login}`, `Address: ${result.address}`,
+        `The directory (${result.directory.site}) stores: ${result.directory.stores}`, result.never);
+      break;
+    case 'storage add':
+      lines.push(result.already ? `Storage is already added: R2 bucket ${result.bucket}.` : `Storage added: R2 bucket ${result.bucket}.`, 'Next:', ...result.next.map((n) => `  ${n}`));
       break;
     case 'publish':
       lines.push(`Listed in the directory: ${result.studioPage ?? result.directory}`, ...(result.games ?? []).map((g) => `  ${g.name}: ${g.play}`));
@@ -91,6 +124,29 @@ 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 '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`));
@@ -117,7 +173,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 });
   }
@@ -127,60 +183,118 @@ 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 === '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 });
+  if (cmd === 'storage') {
+    const cf = readStudio(root).cloudflare ?? {};
+    const has = Boolean(cf.r2 && (cf.created ?? []).includes(`r2:${cf.r2}`));
+    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: 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)` };
 }
 
+/*
+ * WHICH DEV SERVER IS THIS STUDIO'S. `dev` writes its own PID and Wrangler's to site/.wrangler/homie-dev.json,
+ * and `dev --stop` stops exactly those two (each checked to still be a process of this studio's folder), so an AI
+ * never has to reach for `pkill -f "wrangler dev"`, which stops every project's dev server on the machine.
+ */
+const devFile = (root) => join(root, 'site', '.wrangler', 'homie-dev.json');
+function processOfStudio(pid, root, kind) {
+  if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid) return false;
+  try { process.kill(pid, 0); } catch { return false; }
+  const ps = spawnSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' });
+  if (ps.status !== 0) return process.platform === 'win32'; // no ps: the PID file is all there is
+  let real = root;
+  try { real = realpathSync(root); } catch { /* keep */ }
+  // A PID the file names is still ours when it runs from this studio, or is still the kind of process it was
+  // (a recycled PID is neither), so nothing else on the machine is ever stopped.
+  return ps.stdout.includes(root) || ps.stdout.includes(real) || (kind === 'dev' ? /homie-studio/.test(ps.stdout) : /wrangler|workerd/.test(ps.stdout));
+}
+async function stopDev(root) {
+  const file = devFile(root);
+  if (!existsSync(file)) return { ok: true, command: 'dev stop', stopped: [], why: 'no dev server of this studio is running' };
+  let rec = {};
+  try { rec = JSON.parse(readFileSync(file, 'utf8')); } catch { /* a torn file */ }
+  const pids = [[rec.child, 'wrangler'], [rec.pid, 'dev']].filter(([p, kind]) => processOfStudio(p, root, kind)).map(([p]) => p);
+  for (const pid of pids) { try { process.kill(pid, 'SIGTERM'); } catch { /* gone */ } }
+  const deadline = Date.now() + 8000;
+  const alive = () => pids.filter((p) => { try { process.kill(p, 0); return true; } catch { return false; } });
+  while (alive().length && Date.now() < deadline) await new Promise((r) => setTimeout(r, 200));
+  for (const pid of alive()) { try { process.kill(pid, 'SIGKILL'); } catch { /* gone */ } }
+  rmSync(file, { force: true });
+  return { ok: true, command: 'dev stop', stopped: pids };
+}
+
 /** The whole site locally: pages, rooms (room.mjs in a local Durable Object), D1. */
 async function dev(root) {
   const port = String(flags.get('port') ?? 8787);
   const b = await build(root, { log });
-  if (!b.catalogue.length) return { ok: false, command: 'dev', why: 'no games yet: npx homie-studio game new <id> --from gem-rush' };
+  if (!b.catalogue.length && !b.songs.length && !b.videos.length) return { ok: false, command: 'dev', why: 'nothing to show yet: npx homie-studio game new <id> --from gem-rush, or publish a song or video (media/MEDIA.md)' };
   const bin = wranglerBin(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);
   });
   log(`Local site: http://127.0.0.1:${port}/  (each game: http://127.0.0.1:${port}/<id>/play — open it in two browsers)`);
   const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port], { cwd: join(root, 'site'), env, stdio: 'inherit' });
+  mkdirSync(dirname(devFile(root)), { recursive: true });
+  writeFileSync(devFile(root), `${JSON.stringify({ pid: process.pid, child: child.pid, port: Number(port), at: new Date().toISOString() })}\n`);
+  log(`Stop it with: npx --no-install homie-studio dev --stop   (this studio's dev server only)`);
+  // Stopping this process stops Wrangler with it, so no dev server is left running on its own.
+  for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => { try { child.kill(signal); } catch { /* gone */ } });
   await new Promise((done) => child.on('close', done));
+  rmSync(devFile(root), { force: true });
   return { ok: true, command: 'dev', stopped: true };
 }
 
-/** A big file into the studio's R2, and its line in music/ or videos/ manifest.json. */
+/** A big file into the studio's R2, and its key on the music/ or videos/ manifest entry that names it. */
 function mediaPut(root, file, as) {
   if (!file || !existsSync(file) || !statSync(file).isFile()) return { ok: false, command: 'media put', why: 'usage: homie-studio media put <file> [--as <key>]' };
   const studio = readStudio(root);
   const r2 = studio.cloudflare?.r2;
-  if (!r2 || !(studio.cloudflare?.created ?? []).includes(`r2:${r2}`)) return { ok: false, command: 'media put', why: 'this studio has no R2 bucket yet (deploy first; R2 needs to be enabled on the Cloudflare account)' };
+  if (!r2 || !(studio.cloudflare?.created ?? []).includes(`r2:${r2}`)) return { ok: false, command: 'media put', needs: 'storage', why: 'this studio has no storage yet. `npx --no-install homie-studio storage add` adds an R2 bucket; Cloudflare asks for a payment method on the account before R2 works (10 GB-month free), so ask the person first. Games never need it.' };
   const rel = relative(root, resolve(file));
   const folder = rel.startsWith('videos/') ? 'videos' : 'music';
-  const key = as ?? `${folder}/${basename(file)}`;
+  // A file already in music/ or videos/ keeps its repository path as its key (two songs may share a file name).
+  const key = as ?? (/^(music|videos)\//.test(rel) && !rel.includes('..') ? rel : `${folder}/${basename(file)}`);
   const bin = wranglerBin(root);
   return new Promise((done) => {
-    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--remote'], { cwd: join(root, 'site'), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
+    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 manifest = join(root, folder, 'manifest.json');
-      const m = existsSync(manifest) ? JSON.parse(readFileSync(manifest, 'utf8')) : { items: [] };
-      m.items = [...(m.items ?? []).filter((i) => i.key !== key), { key, file: rel, bytes: statSync(file).size, url: studio.cloudflare?.url ? `${studio.cloudflare.url}/media/${key}` : null, at: new Date().toISOString() }];
-      writeFileSync(manifest, `${JSON.stringify(m, null, 2)}\n`);
-      writeStudio(root, studio);
-      done({ ok: true, command: 'media put', key, manifest: relative(root, manifest) });
+      // 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 });
     });
   });
 }

package/lib/build.mjs

@@ -5,7 +5,9 @@
  *   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[] } from studio.json and game.json files
+ *   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/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):
  *   (absent) / { "mode": "bundle" }   src/main.ts (or "entry") bundled by esbuild — new games and ES-module ports
@@ -19,7 +21,9 @@ import { spawnSync } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
+import { buildMedia } from './media.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']);
@@ -73,6 +77,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;
@@ -131,18 +160,41 @@ 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);
+  // Songs and videos (music/ and videos/ manifests): rebuilt with every full build; a one-game build keeps them.
+  const r2 = Boolean(studio.cloudflare?.r2 && (studio.cloudflare?.created ?? []).includes(`r2:${studio.cloudflare.r2}`));
+  let media = null;
+  if (!only) media = buildMedia(root, dist, { r2, 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,
-      ...(g.screen ? { screen: g.screen } : {}),
-    })),
+    studio: {
+      name: studio.name, slug: studio.slug, version: STUDIO_VERSION,
+      // studio.json `stats.share`: the site tells the directory two numbers for the hub (played this week).
+      ...(studio.stats?.share === true ? { stats: { share: true }, directory: studio.homie?.directory ?? 'https://homie.rocks' } : {}),
+    },
+    games: all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))).map((g) => {
+      // The seats come from the game's netplay manifest (NETPLAY.md §3): what the Worker gives every room of it.
+      const net = netplayOf(g, join(dist, 'games', g.id));
+      const { min, max } = seatsFor(g, net);
+      return {
+        id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
+        roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
+        ...(g.screen ? { screen: g.screen } : {}),
+      };
+    }),
+    songs: media.songs,
+    videos: media.videos,
   };
   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) };
+  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,
+  };
 }