@homie-rocks/studio 0.5.0 → 0.6.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.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
@@ -18,8 +18,43 @@ 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
@@ -61,7 +96,8 @@ 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/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

@@ -21,6 +21,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.
  */
@@ -34,9 +39,10 @@ import { publish } from '../lib/directory.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();
@@ -85,7 +91,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 +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`));
@@ -142,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 });
   }
@@ -152,13 +183,13 @@ 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 });
   }
@@ -171,12 +202,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 +258,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 +291,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 });
     });
   });
 }

package/lib/build.mjs

@@ -23,6 +23,7 @@ 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']);
@@ -76,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;
@@ -134,7 +160,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);
@@ -146,12 +174,21 @@ export async function build(root, { only = null, log = () => {} } = {}) {
     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,
   };

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/media.mjs

@@ -111,7 +111,7 @@ export function buildMedia(root, dist, { r2 = false, log = () => {} } = {}) {
 }
 
 /** `homie-studio media put`: record an uploaded file's R2 key on the entry that names it (or a bare entry). */
-export function recordUpload(root, rel, key, bytes, siteUrl) {
+export function recordUpload(root, rel, key, bytes) {
   const kind = rel.startsWith('videos/') ? 'videos' : 'music';
   const m = readManifest(root, kind);
   let hit = false;
@@ -120,7 +120,7 @@ export function recordUpload(root, rel, key, bytes, siteUrl) {
       if (f.path === rel) { f.key = key; f.bytes = bytes; hit = true; }
     }
   }
-  if (!hit) m.items = [...m.items.filter((i) => i.key !== key), { key, file: rel, bytes, url: siteUrl ? `${siteUrl}/media/${key}` : null, at: new Date().toISOString() }];
+  if (!hit) m.items = [...m.items.filter((i) => i.key !== key), { key, file: rel, bytes, url: `/media/${key.split('/').map(encodeURIComponent).join('/')}`, at: new Date().toISOString() }];
   writeManifest(root, kind, m);
   return { kind, manifest: relative(root, manifestPath(root, kind)), entry: hit };
 }

package/lib/scaffold.mjs

@@ -19,10 +19,11 @@
  * 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';
@@ -74,7 +75,7 @@ directory lists its games; homie.rocks does not host them.
 | \`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)
@@ -107,6 +108,13 @@ studio's pinned copy, never a registry lookup of the bare name.
   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
 
@@ -125,6 +133,10 @@ 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
@@ -170,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/
@@ -197,7 +211,12 @@ export function studioFiles({ name, slug, homie }) {
     name, slug,
     homie: { studio: STUDIO_VERSION, directory: homie },
     // r2 stays null until `homie-studio storage add`: a new studio deploys with no R2 at all.
-    cloudflare: { worker, d1: `${slug}-db`, r2: null, accountId: null, url: null, created: [] },
+    // `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`,
@@ -224,11 +243,36 @@ export function studioFiles({ name, slug, homie }) {
 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; }
 }