@homie-rocks/studio 0.3.0 → 0.6.0

package/lib/scaffold.mjs

@@ -7,19 +7,23 @@
  *   studio.json          the studio's name, slug, and its Cloudflare resources
  *   package.json         @homie-rocks/studio and wrangler, pinned
  *   games/<id>/          one folder per game (game.json, index.html, src/)
- *   music/ videos/       manifests in the repo; the big files live in the studio's R2
+ *   music/ videos/       manifests in the repo; the big files go to the studio's own storage
+ *                        (R2) once it is added with `homie-studio storage add`
  *   posts/               words the studio publishes
- *   site/                the studio's Worker (pages, rooms), its D1 migrations
+ *   site/                the studio's Worker (pages, rooms), its D1 migrations (no R2
+ *                        binding until the studio adds storage: a free Cloudflare account
+ *                        without a payment method cannot use R2, and a new studio needs none)
  *   .claude/skills/      skills only this studio uses
  *
  * It writes only into a folder that is new or empty, never guesses one, and
  * lists every file it writes, so the person sees exactly what changed.
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
 import { STUDIO_VERSION, packageSpec } from './version.mjs';
+import { STATS_MIGRATION, STATS_MIGRATION_FILE } from '../worker/stats.mjs';
 
 export const COMPAT_DATE = '2026-06-01';
 export const WRANGLER_VERSION = '4.126.0';
@@ -47,7 +51,8 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null }) {
     observability: { enabled: true },
   };
   return `// This studio's site on its own Cloudflare account (written by homie-studio; \`homie-studio deploy\`
-// fills in the D1 id, and drops the R2 binding when the account has no R2).
+// fills in the D1 id). Everything here runs on Cloudflare's Workers Free plan. There is no R2 binding
+// until \`homie-studio storage add\` gives the studio storage for large media.
 ${JSON.stringify(config, null, 2)}
 `;
 }
@@ -55,22 +60,22 @@ ${JSON.stringify(config, null, 2)}
 function agentsMd({ name, slug }) {
   return `# ${name}
 
-This folder is a game studio: **${name}** (\`${slug}\`). It is one repository.
+This folder is a studio: **${name}** (\`${slug}\`). It is one repository.
 Its games, music, videos and posts live here; its website and public game rooms
-run on the studio's **own Cloudflare account** (a Worker, D1, R2, and the
-Table/Lobby Durable Objects), built from \`@homie-rocks/studio\`, pinned in
-\`package.json\`. The homie.rocks directory lists its games; homie.rocks does
-not host them.
+run on the studio's **own Cloudflare account** (one Worker, one D1 database and
+the Table/Lobby Durable Objects, all on Cloudflare's free Workers plan), built
+from \`@homie-rocks/studio\`, pinned in \`package.json\`. The homie.rocks
+directory lists its games; homie.rocks does not host them.
 
 ## Layout
 
 | Path | What it is |
 | --- | --- |
 | \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`. |
-| \`music/\`, \`videos/\` | \`manifest.json\` lists each file and its R2 key. Large files go to R2 (\`npx --no-install homie-studio media put <file>\`), never into git. |
+| \`music/\`, \`videos/\` | Songs, scores, loops; trailers, music videos, cutscenes. \`manifest.json\` lists each one (\`node_modules/@homie-rocks/studio/media/MEDIA.md\`); a published entry gets a page at \`/music/<slug>/\` or \`/videos/<slug>/\`, served from the site itself (files up to 25 MiB) or, for larger media, from the studio's storage once it has storage (see below; \`npx --no-install homie-studio media put <file>\`). Large files never go into git. The Homie plugin's \`music\` and \`video\` skills make them. |
 | \`posts/\` | Markdown the studio publishes. |
 | \`site/\` | The studio's Worker (\`src/worker.mjs\`), D1 migrations, \`wrangler.jsonc\`. |
-| \`studio.json\` | The studio's name, slug and Cloudflare resource names. |
+| \`studio.json\` | The studio's name, slug, Cloudflare resource names, custom domain and stats sharing. \`.studio/\` (git-ignored) is this computer's own state. |
 | \`.claude/skills/\` | Skills only this studio uses. Homie's own skills come from the Homie plugin. |
 
 ## Commands (all through the pinned CLI in node_modules)
@@ -87,13 +92,29 @@ studio's pinned copy, never a registry lookup of the bare name.
 - \`npm run build\` — bundle every game into \`site/dist\`.
 - \`npm run dev\` — the whole site locally (pages, the netplay relay in a local
   Durable Object, D1): open the printed address in two browsers and they share a room.
+  Stop it with \`npx --no-install homie-studio dev --stop\` (this studio's dev server only;
+  never \`pkill\` by name, which stops other projects' dev servers too).
 - \`npx --no-install homie-studio check <id> --url <site>\` — two headless browsers press Play and must
   land in the same room and finish a round. Run it before you say a game works.
-- \`npm run deploy\` — the site on this studio's Cloudflare (Workers, D1, R2).
+- \`npx --no-install homie-studio deploy --plan\` — says what deploy will create on Cloudflare and what it
+  costs, and changes nothing. Tell the person before the first deploy.
+- \`npm run deploy\` — the site on this studio's Cloudflare: one Worker, one D1 database, two
+  SQLite-backed Durable Objects, all on the free Workers plan (no payment method needed).
   If Wrangler is not signed in, run \`npx wrangler login\`: the person approves once in
   their browser. It never overwrites a Worker or database this studio did not create.
+- \`npx --no-install homie-studio storage add\` — only when the studio needs large media (songs,
+  videos): an R2 bucket for \`media put\`, served at \`/media/<key>\`. Cloudflare asks for a
+  payment method on the account before R2 works (its first 10 GB a month are free), so this
+  is a separate step the person agrees to; nothing else needs it.
 - \`npx --no-install homie-studio publish\` — list this studio's games in the homie.rocks directory
   (or call the Homie MCP tool \`studio_publish\`).
+- \`npx --no-install homie-studio stats\` — the studio's own numbers, for its owner: visits, Play presses,
+  rooms, the most people playing at once, rounds, songs played, videos watched, and where visitors came
+  from (homie.rocks, other studios, search, the web). \`stats link\` gives the owner a one-time link to the
+  private page \`/_studio/stats\` in their own browser; \`stats key\` a short read key for the Homie MCP tool
+  \`studio_stats\` (never paste a key anywhere else). \`stats share on\` tells the directory two numbers
+  (played this week). The site counts and never tracks: no cookie on a visitor, no person identified,
+  nothing sent anywhere; house QA and \`check\` runs are not counted.
 
 ## Making games
 
@@ -112,7 +133,17 @@ studio's pinned copy, never a registry lookup of the bare name.
 - Keys stay in the providers' own logins (Wrangler, ElevenLabs, fal) or the OS
   keychain. Never write a key, token or password into this repository.
 - Never touch a Cloudflare resource this studio did not create (\`studio.json\` says which).
+- The site's workers.dev address names the Cloudflare account (often after its owner): \`deploy\` keeps it in
+  \`.studio/local.json\`, which git ignores. Never copy it into a committed file. A custom domain goes in
+  studio.json as \`cloudflare.domain\`.
+- A game's room size is its netplay manifest's \`maxPlayers\` (game.json \`netplay\`, or netplay.json), up to 32.
 - Nothing in this studio needs \`~/.homie\` or a Homie box.
+
+## Beta
+
+Homie for studios is in beta. When something breaks, or a game you want to port does
+not fit, open an issue at https://github.com/homie-rocks/homie/issues/new/choose (a bug,
+a port request or a question). Leave keys, tokens and private addresses out of it.
 `;
 }
 
@@ -151,6 +182,8 @@ CREATE INDEX IF NOT EXISTS rounds_game_at ON rounds (game, at);
 `;
 
 const GITIGNORE = `node_modules/
+# This computer's own state: the site's workers.dev address (it names the Cloudflare account, often after its owner).
+.studio/
 site/dist/
 site/.wrangler/
 .wrangler/
@@ -159,7 +192,10 @@ site/.wrangler/
 *.log
 # Port checks: receipts and screenshots of each run (games/<id>/.port/check-*/).
 games/*/.port/
-# Large media lives in this studio's R2; the manifests beside it are committed.
+# Large media lives in this studio's storage (R2, after storage add) or is served by the site; the manifests beside it are committed.
+# Working files of the music and video skills (frames, captures, provider answers) stay on this computer.
+music/**/work/
+videos/**/work/
 music/**/*.wav
 music/**/*.mp3
 music/**/*.flac
@@ -174,7 +210,13 @@ export function studioFiles({ name, slug, homie }) {
   const studio = {
     name, slug,
     homie: { studio: STUDIO_VERSION, directory: homie },
-    cloudflare: { worker, d1: `${slug}-db`, r2: `${slug}-media`, accountId: null, url: null, created: [] },
+    // r2 stays null until `homie-studio storage add`: a new studio deploys with no R2 at all.
+    // `domain`: the studio's own domain once it has one (e.g. "night-owls.example"). The workers.dev address never
+    // goes here: it names the Cloudflare account, so deploy keeps it in .studio/local.json (git-ignored).
+    cloudflare: { worker, d1: `${slug}-db`, r2: null, accountId: null, domain: null, created: [] },
+    // The site counts visits, plays, rooms, rounds and songs for the owner only (`homie-studio stats`); `share`
+    // also tells the homie.rocks directory "played this week" (two numbers) for the hub.
+    stats: { share: false },
   };
   const pkg = {
     name: `${slug}-studio`,
@@ -191,21 +233,46 @@ export function studioFiles({ name, slug, homie }) {
     'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
     '.gitignore': GITIGNORE,
     'games/README.md': 'One folder per game. Start one with `npx --no-install homie-studio game new <id> --from gem-rush`.\n',
-    'music/README.md': 'Songs and stems. `manifest.json` lists them; the files themselves go to R2 with `npx --no-install homie-studio media put`.\n',
-    'music/manifest.json': '{ "items": [] }\n',
-    'videos/README.md': 'Trailers and clips. `manifest.json` lists them; the files themselves go to R2 with `npx --no-install homie-studio media put`.\n',
-    'videos/manifest.json': '{ "items": [] }\n',
+    'music/README.md': 'Songs, game scores, loops and stems, one folder each (`music/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/music/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
+    'music/manifest.json': '{ "v": 1, "items": [] }\n',
+    'videos/README.md': 'Trailers, music videos and cutscenes, one folder each (`videos/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/videos/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
+    'videos/manifest.json': '{ "v": 1, "items": [] }\n',
     'posts/README.md': 'Markdown posts this studio publishes, one file each.\n',
-    'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1 and R2.
+    'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1, and R2 once storage is added.
 // The code is @homie-rocks/studio's, pinned in package.json, so an update never changes a published game by surprise.
 export { default, Table, Lobby } from '@homie-rocks/studio/worker';
 `,
     'site/migrations/0001_studio.sql': MIGRATION,
+    [`site/migrations/${STATS_MIGRATION_FILE}`]: STATS_MIGRATION,
     'site/wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2 }),
     '.claude/skills/.gitkeep': '',
   };
 }
 
+/**
+ * A studio made before 0.6.0 has no stats migration: add it (the template owns site/migrations/), so the next
+ * `d1 migrations apply` makes the counters. Returns the file it wrote, or null when it was there.
+ */
+export function ensureStatsMigration(root) {
+  const file = join(root, 'site', 'migrations', STATS_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, STATS_MIGRATION);
+  return `site/migrations/${STATS_MIGRATION_FILE}`;
+}
+
+/**
+ * A studio made before 0.6.0 committed nothing under .studio/ yet: make sure git leaves it out before the first
+ * deploy writes the workers.dev address there. Returns true when it added the line.
+ */
+export function ensureLocalIgnored(root) {
+  const file = join(root, '.gitignore');
+  const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (/^\/?\.studio\/?$/m.test(text)) return false;
+  writeFileSync(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}# This computer's own state: the site's workers.dev address (it names the Cloudflare account).\n.studio/\n`);
+  return true;
+}
+
 function insideGit(dir) {
   try { return execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() === 'true'; } catch { return false; }
 }
@@ -254,7 +321,7 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
     'npx --no-install homie-studio game new <id> --from gem-rush --name "<Game Name>"',
     'npm run dev   (then: npx --no-install homie-studio check <id> --url http://127.0.0.1:8787)',
     'npm run deploy   (then the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish)',
-  ] };
+  ], online: 'Going online creates one Worker, one D1 database and two Durable Objects on your own Cloudflare account: free plan, no payment method, no R2. `npx --no-install homie-studio deploy --plan` says exactly what, and changes nothing.' };
 }
 
 export const _test = { relative };

package/lib/stats.mjs

@@ -0,0 +1,125 @@
+/**
+ * `homie-studio stats` — the studio's own numbers, for its owner (worker/stats.mjs says what is counted).
+ *
+ *   homie-studio stats [--range 1d|7d|30d|90d] [--game <id> | --song <slug> | --video <slug>]
+ *                                  the numbers, read with a key that lives ten minutes and is dropped after
+ *   homie-studio stats key [--hours 1]    a read key for the Homie MCP tool `studio_stats` (up to 30 days)
+ *   homie-studio stats link               a one-time link that opens /_studio/stats in the owner's browser
+ *   homie-studio stats revoke             every key and page session ends now
+ *   homie-studio stats share on|off       tell the homie.rocks directory "played this week" (two numbers), or stop
+ *
+ * THE PROOF OF OWNERSHIP IS THE STUDIO'S OWN CLOUDFLARE LOGIN. A key is minted here, on this computer, and only
+ * its SHA-256 goes into the studio's D1 (through Wrangler, which only the studio's owner is signed in to). The key
+ * itself is never sent to Cloudflare, never written to a file, and lives for its hours only. A studio running
+ * locally (`npm run dev`, a loopback --url) uses the local D1.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { runner } from './cloudflare.mjs';
+import { readStudio, siteUrl, writeStudio } from './studio.mjs';
+
+const HOUR = 3600_000;
+const RANGES = new Set(['1d', '7d', '30d', '90d']);
+const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
+
+function siteOf(root, url) {
+  const studio = readStudio(root);
+  const site = String(url || siteUrl(root, studio) || '').replace(/\/+$/, '');
+  if (!/^https?:\/\//.test(site)) return { studio, site: null };
+  return { studio, site };
+}
+
+/** Put a key's hash into the studio's D1 (remote, or local for a loopback site). The key never leaves this machine. */
+function mint(root, studio, kind, ttlMs, { local }) {
+  const key = `hsk_${randomBytes(24).toString('hex')}`;
+  const hash = createHash('sha256').update(key).digest('hex');
+  const now = Date.now();
+  const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+  const sql = `DELETE FROM stats_keys WHERE expires_at < ${now}; INSERT INTO stats_keys (hash, kind, expires_at) VALUES ('${hash}', '${kind}', ${now + ttlMs});`;
+  const res = w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', sql]);
+  if (res.code !== 0) {
+    const why = /no such table: stats_keys/i.test(res.out)
+      ? 'this studio\'s D1 has no stats tables yet: run `npm run deploy` (it applies migration 0002_studio_stats.sql), or `npm run dev` for a local site'
+      : /not logged in|login|authenticat/i.test(res.out) ? 'Wrangler is not signed in to this studio\'s Cloudflare: run `npx wrangler login` (the person approves once)'
+        : `could not write the key's hash to D1: ${res.out.trim().split('\n').slice(-3).join(' ')}`;
+    return { ok: false, why };
+  }
+  return { ok: true, key, hash, expiresAt: new Date(now + ttlMs).toISOString() };
+}
+
+function drop(root, studio, hash, { local }) {
+  const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+  w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', `DELETE FROM stats_keys WHERE hash = '${hash}';`]);
+}
+
+export function statsQuery({ range, game, song, video } = {}) {
+  const q = new URLSearchParams();
+  q.set('range', RANGES.has(range) ? range : '7d');
+  if (game && SLUG.test(game)) q.set('game', game);
+  else if (song && SLUG.test(song)) q.set('song', song);
+  else if (video && SLUG.test(video)) q.set('video', video);
+  return q;
+}
+
+/** The numbers, read with a ten-minute key that is dropped as soon as they are in. */
+export async function statsShow(root, { url, range, game, song, video } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'stats', why: 'this studio has no live site yet: `npm run deploy` first, or give --url http://127.0.0.1:8787 for `npm run dev`' };
+  const local = loopback(site);
+  const k = mint(root, studio, 'read', 10 * 60_000, { local });
+  if (!k.ok) return { ok: false, command: 'stats', why: k.why };
+  try {
+    const res = await fetch(`${site}/api/stats?${statsQuery({ range, game, song, video })}`, { headers: { authorization: `Bearer ${k.key}` }, signal: AbortSignal.timeout(20_000) });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok || !body.ok) return { ok: false, command: 'stats', why: body.message ?? `${site}/api/stats answered ${res.status}` };
+    return { command: 'stats', ...body, ok: true };
+  } catch (error) {
+    return { ok: false, command: 'stats', why: `could not read ${site}/api/stats: ${error.message}` };
+  } finally { drop(root, studio, k.hash, { local }); }
+}
+
+/** A read key for `studio_stats` (the Homie MCP): 1 hour by default, 30 days at most. */
+export function statsKey(root, { url, hours } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'stats key', why: 'this studio has no live site yet: `npm run deploy` first' };
+  const h = Math.max(1, Math.min(24 * 30, Math.floor(Number(hours) || 1)));
+  const k = mint(root, studio, 'read', h * HOUR, { local: loopback(site) });
+  if (!k.ok) return { ok: false, command: 'stats key', why: k.why };
+  return {
+    ok: true, command: 'stats key', site, key: k.key, expiresAt: k.expiresAt, hours: h,
+    use: `Call the Homie MCP tool studio_stats with { "site": "${site}", "key": "<this key>" } (and range, game, song or video). The key only reads this studio's numbers, ends at ${k.expiresAt}, and \`homie-studio stats revoke\` ends it sooner. Never paste it anywhere else.`,
+  };
+}
+
+/** A one-time sign-in link (30 minutes) that opens the private stats page in the owner's own browser. */
+export function statsLink(root, { url } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'stats link', why: 'this studio has no live site yet: `npm run deploy` first' };
+  const k = mint(root, studio, 'signin', 30 * 60_000, { local: loopback(site) });
+  if (!k.ok) return { ok: false, command: 'stats link', why: k.why };
+  return {
+    ok: true, command: 'stats link', site, link: `${site}/_studio/signin?k=${k.key}`, expiresAt: k.expiresAt,
+    use: 'Give this link to the studio\'s owner to open in their own browser: it works once, within 30 minutes, and keeps that browser signed in to the stats page for 30 days. It is theirs alone; do not post it anywhere.',
+  };
+}
+
+export function statsRevoke(root, { url } = {}) {
+  const { studio, site } = siteOf(root, url);
+  const local = site ? loopback(site) : false;
+  const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+  const res = w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', 'DELETE FROM stats_keys;']);
+  return res.code === 0 ? { ok: true, command: 'stats revoke', site, message: 'Every stats key and page session has ended.' } : { ok: false, command: 'stats revoke', why: res.out.trim().split('\n').slice(-3).join(' ') };
+}
+
+export function statsShare(root, on) {
+  const studio = readStudio(root);
+  const share = on === 'on' || on === true || on === 'true';
+  writeStudio(root, { ...studio, stats: { ...(studio.stats ?? {}), share } });
+  return {
+    ok: true, command: 'stats share', share,
+    message: share
+      ? 'studio.json stats.share is on. After `npm run deploy`, the site tells the homie.rocks directory two numbers for the whole studio: Play presses and rounds with people in them, over the last 7 days. Nothing else leaves the studio.'
+      : 'studio.json stats.share is off. After `npm run deploy`, the site tells the directory nothing.',
+  };
+}

package/lib/studio.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
-const RESERVED_IDS = new Set(['api', 'media', 'games', 'assets', '_homie', 'well-known', 'index', 'play', 'studio', 'studios']);
+const RESERVED_IDS = new Set(['api', 'media', 'games', 'assets', '_homie', 'well-known', 'index', 'play', 'studio', 'studios', 'music', 'videos', 'posts']);
 
 export function findStudio(from = process.cwd()) {
   let at = resolve(from);
@@ -29,6 +29,48 @@ export function requireStudio(from) {
 export function readStudio(root) { return JSON.parse(readFileSync(join(root, 'studio.json'), 'utf8')); }
 export function writeStudio(root, studio) { writeFileSync(join(root, 'studio.json'), `${JSON.stringify(studio, null, 2)}\n`); }
 
+/*
+ * WHERE THE SITE'S ADDRESS LIVES. studio.json is committed, and a workers.dev address carries the Cloudflare
+ * account's subdomain, which is often the person's own name. So studio.json keeps only a CUSTOM domain
+ * (`cloudflare.domain`, e.g. "night-owls.example"); the workers.dev address `deploy` gets back stays on this
+ * computer in .studio/local.json, which the studio's .gitignore leaves out.
+ */
+export const LOCAL_STATE = '.studio/local.json';
+export const isWorkersDev = (url) => { try { return /\.workers\.dev$/i.test(new URL(url).hostname); } catch { return false; } };
+
+/** `cloudflare.domain` as an origin: "example.com" or "https://example.com/" become "https://example.com"; else null. */
+export function domainOrigin(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return null;
+  try {
+    const u = new URL(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`);
+    if (u.protocol !== 'https:' || !u.hostname.includes('.') || isWorkersDev(u.origin)) return null;
+    return u.origin;
+  } catch { return null; }
+}
+
+export function readLocal(root) {
+  try { return JSON.parse(readFileSync(join(root, LOCAL_STATE), 'utf8')); } catch { return {}; }
+}
+export function writeLocal(root, patch) {
+  const path = join(root, LOCAL_STATE);
+  mkdirSync(dirname(path), { recursive: true });
+  const next = { ...readLocal(root), ...patch };
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/**
+ * The studio site's public address: its custom domain (studio.json `cloudflare.domain`, or a non-workers.dev
+ * `cloudflare.url` an older studio wrote by hand), else the workers.dev address this computer's deploy got back,
+ * else an older studio.json's workers.dev `url` (until the next deploy moves it out).
+ */
+export function siteUrl(root, studio = readStudio(root)) {
+  const cf = studio.cloudflare ?? {};
+  const custom = domainOrigin(cf.domain) ?? (cf.url && !isWorkersDev(cf.url) ? domainOrigin(cf.url) : null);
+  return custom ?? readLocal(root).url ?? cf.url ?? null;
+}
+
 export function listGames(root) {
   const dir = join(root, 'games');
   if (!existsSync(dir)) return [];

package/media/MEDIA.md

@@ -0,0 +1,81 @@
+# Studio media: music/ and videos/
+
+A studio's songs, scores, loops, trailers, music videos and cutscenes live in the studio
+repository as folders plus one manifest per kind. The manifests are the contract between
+whatever made the media (the Homie plugin's `music` and `video` skills, or a person) and the
+studio site, which turns every published entry into a page:
+
+| Manifest | Page | Listed in |
+| --- | --- | --- |
+| `music/manifest.json` | `/music/<slug>/` (an audio player) | the home page, `/music/`, `/.well-known/homie-studio.json` `songs` |
+| `videos/manifest.json` | `/videos/<slug>/` (a video player) | the home page, `/videos/`, `/.well-known/homie-studio.json` `videos` |
+
+`homie-studio build` reads both manifests. `homie-studio media list` prints what the site will
+show and why anything is left out.
+
+## An entry
+
+```json
+{
+  "v": 1,
+  "items": [
+    {
+      "slug": "theme",
+      "kind": "song",
+      "title": "Night Owls Theme",
+      "blurb": "The studio's theme: a short sung hook over a driving synth line.",
+      "published": true,
+      "duration": 16.0,
+      "bpm": 120,
+      "key": "A minor",
+      "files": [
+        { "role": "audio", "path": "music/theme/theme.mp3", "type": "audio/mpeg" },
+        { "role": "cover", "path": "music/theme/cover.jpg", "type": "image/jpeg" },
+        { "role": "loop", "path": "music/theme/theme-loop.ogg", "type": "audio/ogg", "bars": 8 },
+        { "role": "master", "path": "music/theme/theme-master.wav", "type": "audio/wav", "public": false }
+      ],
+      "lyrics": "…",
+      "credits": "Music made with Eleven Music (ElevenLabs).",
+      "rights": { "provider": "elevenlabs", "plan": "creator", "commercial": true, "attribution": null },
+      "for": { "game": "crown-thief" },
+      "made": { "provider": "elevenlabs", "model": "music_v2", "at": "2026-09-30T02:00:00Z", "receipt": "music/theme/receipt.json" }
+    }
+  ]
+}
+```
+
+- The manifest's order is the site's order (the plugin's skills put a new entry first).
+- `slug`: lowercase letters, digits and hyphens, up to 40; it is the page address and never changes
+  once published. `title` is required for a page; an entry without `slug` and `title` is kept in
+  the manifest but gets no page.
+- `kind`: music is `song`, `score`, `loop`, `stem` or `sfx`; video is `trailer`, `music-video`,
+  `cutscene` or `clip`.
+- `published`: only `true` entries get a page and a directory listing. Work in progress stays
+  `false`.
+- `files[].role`: music uses `audio` (what the player plays), `cover`, `loop`, `stem`,
+  `master`; video uses `video` (the 16:9 cut the player plays), `vertical` (the 9:16 cut),
+  `poster`, `captions` (WebVTT), `master`. `"public": false` keeps a file off the site (masters,
+  raw captures). Loops and stems are offered for download on the song page, so another game can
+  use them.
+- `rights` and `credits` are shown on the page, in plain words. Say what the provider's terms
+  say for the plan the file was made on; nothing on the site claims more.
+
+## Where the bytes come from
+
+A studio needs no storage for songs and videos: the site serves them itself. For every public
+file of a published entry, the build picks the first that exists:
+
+1. `key`: the file is in the studio's storage, an R2 bucket that `homie-studio storage add`
+   creates (Cloudflare asks for a payment method on the account before R2 works, so the person
+   agrees first) and `homie-studio media put <file>` uploads to; the site serves it at
+   `/media/<key>`, with byte ranges so phones can seek.
+2. `path`: the file is in the studio folder; the build copies it into the site as `/<path>` when
+   it is 25 MiB or smaller (Cloudflare's limit for one static file), and the Worker answers byte
+   ranges for it too. This is the default, and it needs nothing but a deploy.
+3. `url`: an absolute `https://` address somewhere else.
+
+A file with none of these is left out and `media list` says so. Media never goes into git: the
+studio's `.gitignore` keeps `*.wav`, `*.mp3`, `*.flac`, `*.mp4`, `*.mov` and `*.webm` under
+`music/` and `videos/` out of the repository, so without storage the site is deployed from the
+computer that has the files. Keep deliveries under 25 MiB (the video skill's cuts do) or add
+storage for bigger ones.

package/netplay/NETPLAY.md

@@ -1,8 +1,19 @@
-# Homie netplay contract, v1 (revision 2)
-
-Status: **v1, revision 2** (2026-09-26). The wire version is `v: 1`. Everything revision
-2 added is either an optional field or a new message type, and both sides ignore types
-they do not know. A change to the contract bumps `v` and keeps v1 working.
+# Homie netplay contract, v1 (revision 3)
+
+Status: **v1, revision 3** (2026-09-30, `@homie-rocks/studio` 0.6.0). The wire version is
+`v: 1`. Everything revision 2 and 3 added is either an optional field, a new message type,
+or a change of pace inside the old caps, and both sides ignore types they do not know. A
+change to the contract bumps `v` and keeps v1 working.
+
+**What revision 3 added** (nothing on the wire changed; every v1 game plays on it):
+- **Rooms of up to 32 seats**, sized by the game's netplay manifest (section 3).
+- **One address may hold every seat plus four sockets** (section 6), so a party on one
+  Wi-Fi fills a 32-seat room with a TV beside it.
+- **The checkpoint, round and roster caps double for 17–32 seats** (section 6): a
+  32-seat courier game's checkpoint measured 56 KB against the 64 KB cap.
+- **Idle input keepalive** in the helper: an unchanged input frame goes out at most four
+  times a second (section 11).
+- Measured cost and free-plan headroom of a 32-seat room (section 11).
 
 **What revision 2 added:**
 - Interpolation measures transit time.
@@ -95,8 +106,12 @@ code.
 | `colour` | `seat % 12` | An index into a 12-colour palette. |
 
 - **Every visitor gets a seat at once**, phone or desktop. There is no gathering.
-- **Room size.** `maxPlayers` comes from the manifest. On the site the Table reads it.
-  Locally, the first visitor of an empty room sends it in `hello.max`.
+- **Room size.** `maxPlayers` comes from the game's netplay manifest: game.json's
+  `netplay.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. **A room holds
+  at most 32** (`SEAT_MAX`). `homie-studio build` writes the number into the catalogue and
+  the site's Table takes it from there; the first visitor of an empty room may lower it
+  (`hello.max`), never raise it.
 - **A dropped seat is held 60 s** for its token, which covers a reload or a network blip.
   **A visitor who is present beats one who left:** when no seat is free, the relay
   reclaims the seat that has been absent longest. Visitors who leave can never lock a
@@ -259,13 +274,15 @@ so `ev.origin` is `"null"`.
 | `in` | < 256 B | 2 KB | 20 Hz, plus an immediate flush (≤ 60 Hz) on a press edge | 60 |
 | `ev` | < 1 KB | 4 KB (512 B from a screen) | as needed | host 30, replica 10, screen 2 |
 | `state` | < 2 KB per key | 8 KB per key; **64 keys and 64 KB per room** → `state-full` | only on change | 64 |
-| `ckpt` | < 32 KB | 64 KB | 1 Hz | 4 |
-| `round` / `roster` | < 2 KB / < 1 KB | 8 KB / 4 KB | on change | 4 / 8 |
+| `ckpt` | < 32 KB | 64 KB (128 KB for 17–32 seats) | 1 Hz | 4 |
+| `round` / `roster` | < 2 KB / < 1 KB | 8 KB / 4 KB (16 / 8 KB for 17–32 seats) | on change | 4 / 8 |
 | `ping` | — | 256 B | every 2 s | 8 |
 
 **Sockets.**
-- At most `maxPlayers + 16` per room, and **12 per client address per room**. The Worker
-  passes `CF-Connecting-IP` as `conn.ip`.
+- At most `maxPlayers + 16` per room, and per client address per room **12, or every seat
+  plus four when that is more** (`perAddress`: 12 for 8 seats, 20 for 16, 36 for 32). The
+  Worker passes `CF-Connecting-IP` as `conn.ip`. Measured before revision 3: 32 visitors on
+  one address got 12 seats and 20 `too-many` refusals.
 - A client dropping more than 100 messages over the caps within 5 s is closed (`flood`).
 
 **Keep it small.**
@@ -494,6 +511,31 @@ Measured, with Gem Rush's bump (owner movement, 30–50 ms one way):
   writes/h ≈ $0.07/h, 9× everything else), or rewriting a whole log per event.
 - Re-check Cloudflare's published prices before quoting.
 
+**A 32-seat room (measured 2026-09-30, `@homie-rocks/studio` 0.6.0).** Every incoming
+socket message is a Durable Object request (billed 20:1; outgoing messages are free), and
+in a full room the replicas' inputs are nearly all of them:
+
+| 32 seats, one host | Incoming msgs/s at the relay | Requests/hour (20:1) | Free plan (100,000 a day) |
+|---|---|---|---|
+| every replica moving, input 20 Hz | ≈ 630 | ≈ 114 k | ≈ 53 room-minutes a day |
+| a game's own vendored helper, input 30 Hz | ≈ 860 | ≈ 155 k | ≈ 39 room-minutes a day |
+| half the replicas standing still, 0.6.0 helper | ≈ 415 | ≈ 75 k | ≈ 80 room-minutes a day |
+
+  - Put another way, the free plan carries roughly **28 player-hours a day** at 20 Hz input
+    (each seated player costs about one request a second). A studio that plays more than
+    that a day needs Workers Paid ($5 a month), where a full 32-seat room-hour costs about
+    $0.02 in requests plus $0.006 in duration.
+  - **Idle keepalive (helper, 0.6.0):** an input frame identical to the last one sent (same
+    avatar or intent, same held keys, no press, same reset epoch) is re-sent at most every
+    250 ms. The host already holds that frame, so nothing it reads changes. A player standing
+    still costs 4 messages a second instead of 20. A game that vendors its own copy of the
+    helper gets this by updating that copy.
+  - Keep `inputHz` at 20 unless the game needs more: 30 Hz costs 1.5× the requests.
+  - Snapshots of a real 32-seat courier game (32 bodies plus the control table) were 1.1–1.7 KB at
+    20 Hz: about 32 KB/s down per replica, 2 KB/s up. No snapshot delta or compression was
+    needed; the 2 KB target and 16 KB cap hold at 32 seats. Duration (13,000 GB-s a day free)
+    covers one busy room all day.
+
 ## 12. Trust and safety
 
 - **The host is a visitor's browser.** A modified host could fake scores. That is
@@ -569,7 +611,8 @@ npx --no-install homie-studio check my-game --url http://127.0.0.1:8787
     candidate for v2, not in v1.
 - **No lag compensation for hits.** A game can rewind a victim by the attacker's
   `rtt/2 + delay` itself.
-- **No snapshot deltas.** They are not needed at the measured sizes (Gem Rush: 364–427 B).
+- **No snapshot deltas.** They are not needed at the measured sizes (Gem Rush: 364–427 B;
+  a 32-body courier game's snapshot: 1.1–1.7 KB).
 - **A reload shows a bot in the player's body for about 1–2 s**, and then the player
   takes the same body back.
 - **The host is a visitor's browser** (section 12).