@homie-rocks/studio 0.3.0 → 0.5.0

package/README.md

@@ -1,24 +1,47 @@
 # @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.5.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
 ```
 
+## 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 +56,25 @@ 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>`). |
+| `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,37 @@
  *   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
  *
  * 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 { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
 import { newStudio } from '../lib/scaffold.mjs';
-import { listGames, newGame, readStudio, remixGame, requireStudio, starters, writeStudio } from '../lib/studio.mjs';
+import { listGames, newGame, readStudio, remixGame, requireStudio, starters } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.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 +61,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 +69,33 @@ 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.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}`));
@@ -129,6 +154,7 @@ async function main() {
     const studio = readStudio(root);
     return { ok: true, command: 'status', 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;
@@ -136,17 +162,62 @@ async function main() {
     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 === '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: 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);
@@ -157,30 +228,33 @@ async function dev(root) {
   });
   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) });
+      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 });
     });
   });
 }

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,6 +21,7 @@ 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 { STUDIO_VERSION } from './version.mjs';
 
@@ -135,6 +138,13 @@ export async function build(root, { only = null, log = () => {} } = {}) {
     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) => ({
@@ -142,7 +152,12 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       roundSeconds: g.roundSeconds ?? null, movement: g.netplay?.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,
+  };
 }

package/lib/cloudflare.mjs

@@ -5,12 +5,18 @@
  * The person's only step is Wrangler's sign-in (`npx wrangler login`, one
  * approval in their browser); Wrangler keeps that login, this never sees a key.
  *
- * It creates what the studio needs, by the names in studio.json:
- *   the Worker (pages + rooms), a D1 database, an R2 bucket (when the account
- *   has R2), the Table/Lobby Durable Objects (declared by the Worker)
- * and it REFUSES to touch a Worker, database or bucket of that name that this
+ * NO CREDIT CARD. It creates only what Cloudflare's free Workers plan gives a
+ * brand-new account with no payment method, by the names in studio.json:
+ *   the Worker (pages + rooms), a D1 database, and the Table/Lobby Durable
+ *   Objects (SQLite-backed, declared by the Worker).
+ * It never creates or binds R2: Cloudflare asks for a payment method before R2
+ * works, even inside its free tier, so storage for large media is its own later
+ * step (`homie-studio storage add`) that the person agrees to.
+ *
+ * It REFUSES to touch a Worker, database or bucket of that name that this
  * studio did not create (studio.json `cloudflare.created` is the record), so it
- * can never overwrite someone's existing site.
+ * can never overwrite someone's existing site. `deploy --plan` says all of this
+ * before anything happens and calls nothing.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, writeFileSync } from 'node:fs';
@@ -53,19 +59,76 @@ function parseJson(text) {
   try { return JSON.parse(text.slice(start)); } catch { return null; }
 }
 
+/*
+ * WHAT A NEW ACCOUNT TRIPS ON, said as the next step instead of a Wrangler stack.
+ * Measured names: 10034 is Cloudflare's "verify your email address" (a new
+ * account cannot deploy a Worker until it does); a missing workers.dev
+ * subdomain is registered by Wrangler itself when an agent runs it (Claude Code
+ * and Codex are detected), and otherwise needs one visit to the onboarding page.
+ */
+export function explainCloudflare(out, accountId = null) {
+  const text = String(out ?? '');
+  const dash = accountId ? `https://dash.cloudflare.com/${accountId}` : 'https://dash.cloudflare.com';
+  if (/\b10034\b|verify your email/i.test(text)) {
+    return { needs: 'cloudflare-verify-email', why: `Cloudflare needs this account's email address verified before it runs a Worker. Ask the person to open the verification email from Cloudflare (or ${dash}/profile and "Send verification email"), click it, then run \`npm run deploy\` again. No payment method is needed.` };
+  }
+  if (/register a workers\.dev subdomain|workers\/onboarding/i.test(text)) {
+    return { needs: 'workers-dev-subdomain', why: `This Cloudflare account has no workers.dev address yet. Ask the person to open ${dash}/workers/onboarding once and pick one (it is free), then run \`npm run deploy\` again.` };
+  }
+  if (/maximum number of (D1 )?databases|database limit|too many databases/i.test(text)) {
+    return { needs: 'd1-limit', why: 'This Cloudflare account has used all the D1 databases its plan allows (10 on the free plan). Nothing was deployed. Ask the person which unused database of theirs to remove, or use another account; never delete one yourself.' };
+  }
+  if (/\b1027\b|exceeded .*daily request limit/i.test(text)) {
+    return { needs: 'free-plan-daily-limit', why: 'This account used its free plan\'s 100,000 Worker requests for today (it resets at 00:00 UTC). Nothing is broken; try again after the reset.' };
+  }
+  return null;
+}
+
+/** What `deploy` will create and what it costs, from studio.json alone. It calls nothing. */
+export function deployPlan(root) {
+  const studio = readStudio(root);
+  const cf = { created: [], ...studio.cloudflare };
+  const created = new Set(cf.created ?? []);
+  const storage = cf.r2 && created.has(`r2:${cf.r2}`) ? cf.r2 : null;
+  const mark = (key) => (created.has(key) ? 'exists (this studio made it)' : 'will be created');
+  return {
+    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: '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
+        ? { kind: 'R2 bucket', name: storage, what: 'large media for /media/<key> (added with storage add)', state: 'exists (this studio made it)', plan: 'R2 (payment method on the account; 10 GB-month free)' }
+        : { kind: 'R2 bucket', name: null, what: 'none: a new studio needs no storage. `homie-studio storage add` adds it later, for large media only', state: 'not created', plan: null },
+    ],
+    cost: storage
+      ? 'Free on Cloudflare\'s Workers Free plan. R2 storage is free up to 10 GB-month; beyond that Cloudflare bills the account directly.'
+      : 'Free: everything above is on Cloudflare\'s Workers Free plan, which needs no payment method. Its 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, nothing is charged.',
+    login: 'One approval: `npx wrangler login` opens Cloudflare in the person\'s browser (a free account works; a new one verifies its email address first).',
+    address: `https://${cf.worker}.<the account's workers.dev subdomain>.workers.dev`,
+    directory: {
+      site: studio.homie?.directory || 'https://homie.rocks',
+      stores: 'the site\'s address and a claim token, the studio\'s name and slug, the @homie-rocks/studio version, and each game\'s id, name, blurb and Play/page links. Never code, media, keys or accounts.',
+    },
+    never: 'It never touches a Worker, database or bucket this studio did not create, and it never adds a payment method or buys anything.',
+  };
+}
+
 export async function deploy(root, { log = () => {}, homie } = {}) {
   const studio = readStudio(root);
-  const cf = { r2: `${studio.slug}-media`, created: [], ...studio.cloudflare };
+  const cf = { r2: null, created: [], ...studio.cloudflare };
   const created = new Set(cf.created ?? []);
   const who = whoami(root);
   if (!who) {
-    return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: 'Wrangler is not signed in to Cloudflare. Run `npx wrangler login` in the studio folder: it opens Cloudflare in the browser and the person approves once. Then run `npm run deploy` again.' };
+    return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: 'Wrangler is not signed in to Cloudflare. Run `npx wrangler login` in the studio folder: it opens Cloudflare in the browser and the person approves once (a free account works, no payment method). Then run `npm run deploy` again.' };
   }
   const accountId = process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || (who.accounts.length === 1 ? who.accounts[0].id : null);
   if (!accountId) {
     return { ok: false, command: 'deploy', needs: 'cloudflare-account', why: `This Cloudflare login can reach ${who.accounts.length} accounts; ask the person which one this studio uses and put its id in studio.json (cloudflare.accountId).`, accounts: who.accounts };
   }
   const w = runner(root, { CLOUDFLARE_ACCOUNT_ID: accountId });
+  const refuse = (why, out) => ({ ok: false, command: 'deploy', ...(explainCloudflare(out, accountId) ?? { why }) });
   // Record every resource the moment it exists, so a deploy cut short (an expired login, a network drop) resumes
   // instead of refusing its own database as "someone else's" next time.
   const remember = (key) => {
@@ -75,9 +138,22 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   const steps = [];
   const step = (what, extra = {}) => { steps.push({ what, ...extra }); log(what); };
 
+  // The first deploy says what it is about to create, and what it costs, before it creates anything: the person
+  // reads it in the transcript whether or not the AI repeated it.
+  const announced = [];
+  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).`,
+      '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.`,
+    );
+    for (const line of announced) log(line);
+  }
+
   const b = await build(root, { log });
-  if (!b.catalogue.length) return { ok: false, command: 'deploy', why: 'no games built yet: make one with `npx --no-install homie-studio game new <id> --from gem-rush`' };
-  step(`built ${b.catalogue.length} game(s)`);
+  if (!b.catalogue.length && !b.songs.length && !b.videos.length) return { ok: false, command: 'deploy', why: 'nothing to put online yet: make a game (`npx --no-install homie-studio game new <id> --from gem-rush`) or publish a song or video in music/ or videos/ (media/MEDIA.md)' };
+  step(`built ${b.catalogue.length} game(s), ${b.songs.length} song(s), ${b.videos.length} video(s)`);
 
   // The Worker: never one this studio did not make.
   if (!created.has(`worker:${cf.worker}`)) {
@@ -85,7 +161,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
     if (exists.code === 0) {
       return { ok: false, command: 'deploy', why: `A Worker named "${cf.worker}" already exists on this Cloudflare account and this studio did not create it, so nothing was deployed. Pick another name in studio.json (cloudflare.worker) and site/wrangler.jsonc (name).` };
     }
-    if (!/10007|does not exist/i.test(exists.out)) return { ok: false, command: 'deploy', why: `could not check the Worker name: ${exists.out.trim().split('\n').slice(-3).join(' ')}` };
+    if (!/10007|does not exist/i.test(exists.out)) return refuse(`could not check the Worker name: ${exists.out.trim().split('\n').slice(-3).join(' ')}`, exists.out);
   }
 
   // D1.
@@ -98,34 +174,25 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   if (!db) {
     const made = w(['d1', 'create', cf.d1]);
     const id = /"?database_id"?\s*[:=]\s*"([0-9a-f-]{36})"/.exec(made.out)?.[1];
-    if (made.code !== 0 || !id) return { ok: false, command: 'deploy', why: `could not create the D1 database "${cf.d1}": ${made.out.trim().split('\n').slice(-4).join(' ')}` };
+    if (made.code !== 0 || !id) return refuse(`could not create the D1 database "${cf.d1}": ${made.out.trim().split('\n').slice(-4).join(' ')}`, made.out);
     db = { name: cf.d1, uuid: id };
     remember(`d1:${cf.d1}`);
     step(`created D1 ${cf.d1}`);
   }
 
-  // R2, when the account has it (R2 needs a payment method on the account; without it the site runs without MEDIA).
-  let r2 = cf.r2 || null;
-  if (r2 && !created.has(`r2:${r2}`)) {
-    const buckets = w(['r2', 'bucket', 'list']);
-    const names = [...buckets.out.matchAll(/^name:\s+(\S+)/gm)].map((m) => m[1]);
-    if (names.includes(r2)) {
-      return { ok: false, command: 'deploy', why: `An R2 bucket named "${r2}" already exists on this account and this studio did not create it; nothing was deployed. Pick another name in studio.json (cloudflare.r2).` };
-    }
-    const made = w(['r2', 'bucket', 'create', r2]);
-    if (made.code === 0) { remember(`r2:${r2}`); step(`created R2 ${r2}`); }
-    else if (/enable R2|R2 is not enabled|10042|purchase|subscription/i.test(made.out)) { step('R2 is not enabled on this account: the site deploys without media storage for now'); r2 = null; }
-    else return { ok: false, command: 'deploy', why: `could not create the R2 bucket "${r2}": ${made.out.trim().split('\n').slice(-4).join(' ')}` };
-  }
+  // Storage (R2) is bound only when `storage add` made the bucket. Deploy itself never creates or lists R2, so a
+  // free account with no payment method deploys the whole studio.
+  const r2 = cf.r2 && created.has(`r2:${cf.r2}`) ? cf.r2 : null;
+  if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
   writeFileSync(join(root, 'site', 'wrangler.jsonc'), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2 }));
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
-  if (migrate.code !== 0) return { ok: false, command: 'deploy', why: `D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}` };
+  if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   step('D1 migrations applied');
 
   const started = Date.now();
   const dep = w(['deploy']);
-  if (dep.code !== 0) return { ok: false, command: 'deploy', why: `wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}` };
+  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 });
@@ -145,11 +212,62 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
     }
   }
 
-  const next = { ...cf, accountId, url, d1Id: db.uuid, r2, created: [...created].sort(), deployedAt: new Date().toISOString() };
+  const next = { ...cf, accountId, url, d1Id: db.uuid, r2: cf.r2 ?? null, created: [...created].sort(), deployedAt: new Date().toISOString() };
   writeStudio(root, { ...studio, cloudflare: next });
   return {
-    ok: true, command: 'deploy', url, worker: cf.worker, d1: cf.d1, r2, account: accountId, steps,
+    ok: true, command: 'deploy', url, 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 })),
     claim: Boolean(claim), directory,
   };
 }
+
+/*
+ * `homie-studio storage add` — the studio's own storage for large media (songs,
+ * videos, big art), as an R2 bucket on its account, bound as MEDIA and served at
+ * /media/<key>. It is separate from deploy on purpose: Cloudflare asks for a
+ * payment method on the account before R2 works, even inside R2's free tier
+ * (10 GB-month), so this is a step the person agrees to, and a studio that only
+ * makes games never needs it. It changes nothing on Cloudflare but the one bucket.
+ */
+export async function storageAdd(root, { log = () => {} } = {}) {
+  const studio = readStudio(root);
+  const cf = { created: [], ...studio.cloudflare };
+  const created = new Set(cf.created ?? []);
+  const bucket = cf.r2 || `${studio.slug}-media`;
+  if (created.has(`r2:${bucket}`)) {
+    return { ok: true, command: 'storage add', bucket, already: true, next: ['npm run deploy   (binds it as MEDIA if the live site does not have it yet)'] };
+  }
+  const who = whoami(root);
+  if (!who) return { ok: false, command: 'storage add', needs: 'cloudflare-login', why: 'Wrangler is not signed in to Cloudflare. Run `npx wrangler login` first (one approval in the browser).' };
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || (who.accounts.length === 1 ? who.accounts[0].id : null);
+  if (!accountId) return { ok: false, command: 'storage add', needs: 'cloudflare-account', why: 'This login reaches several Cloudflare accounts; put the studio\'s in studio.json (cloudflare.accountId) first.', accounts: who.accounts };
+  const w = runner(root, { CLOUDFLARE_ACCOUNT_ID: accountId });
+  const enable = {
+    ok: false, command: 'storage add', needs: 'r2-payment-method', bucket,
+    why: `R2 is not turned on for this Cloudflare account. Cloudflare asks for a payment method before R2 works, even inside its free tier (10 GB-month of storage, 1 million writes and 10 million reads a month free). Only the person can decide that: if they want storage, they open https://dash.cloudflare.com/${accountId}/r2/overview, add R2 there, and you run \`npx --no-install homie-studio storage add\` again. Nothing was created; the studio keeps working without storage.`,
+  };
+  const buckets = w(['r2', 'bucket', 'list']);
+  if (buckets.code !== 0) {
+    if (/enable R2|R2 is not enabled|10042|purchase|subscription|payment/i.test(buckets.out)) return enable;
+    return { ok: false, command: 'storage add', ...(explainCloudflare(buckets.out, accountId) ?? { why: `could not list R2 buckets: ${buckets.out.trim().split('\n').slice(-3).join(' ')}` }) };
+  }
+  const names = [...buckets.out.matchAll(/^name:\s+(\S+)/gm)].map((m) => m[1]);
+  if (names.includes(bucket)) {
+    return { ok: false, command: 'storage add', why: `An R2 bucket named "${bucket}" already exists on this account and this studio did not create it; nothing was created. Put another name in studio.json (cloudflare.r2) and run storage add again.` };
+  }
+  const made = w(['r2', 'bucket', 'create', bucket]);
+  if (made.code !== 0) {
+    if (/enable R2|R2 is not enabled|10042|purchase|subscription|payment/i.test(made.out)) return enable;
+    return { ok: false, command: 'storage add', why: `could not create the R2 bucket "${bucket}": ${made.out.trim().split('\n').slice(-4).join(' ')}` };
+  }
+  created.add(`r2:${bucket}`);
+  const next = { ...readStudio(root), cloudflare: { ...readStudio(root).cloudflare, accountId, r2: bucket, created: [...created].sort() } };
+  writeStudio(root, next);
+  if (next.cloudflare.d1Id) {
+    writeFileSync(join(root, 'site', 'wrangler.jsonc'), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket }));
+  }
+  log(`created R2 ${bucket}`);
+  return { ok: true, command: 'storage add', bucket, account: accountId, next: ['npm run deploy   (binds the bucket as MEDIA; the site serves it at /media/<key>)', 'npx --no-install homie-studio media put <file>'] };
+}