@homie-rocks/studio 0.2.0 → 0.5.0

package/README.md

@@ -1,39 +1,80 @@
 # @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.2.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):
+
+```sh
+npx homie-studio port plan ../my-game                  # grade it: easy, medium, hard or not a fit, and why
+npx homie-studio port import ../my-game --id my-game   # bring it into games/ (static, bundle or its own build)
+npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner tests, real touch, host kill, late joiner, a round
+```
+
 | Path | What it is |
 | --- | --- |
 | `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. |
-| `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects. |
+| `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>`). |
+| `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,35 +10,44 @@
  *   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 deploy
+ *   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 [--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', 'plan', 'stop'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a.startsWith('--')) {
     const [k, v] = a.slice(2).split(/=(.*)/s, 2);
     if (v !== undefined) flags.set(k, v);
-    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && !['json', 'yes', 'detach', 'no-install'].includes(k)) flags.set(k, argv[++i]);
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && !BOOL_FLAGS.includes(k)) flags.set(k, argv[++i]);
     else flags.set(k, true);
   } else positional.push(a);
 }
@@ -46,11 +56,12 @@ const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
   if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
-  if (result.ok === false) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
+  if (result.ok === false && result.command !== 'port check') { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
+  if (result.ok === false && result.command === 'port check' && !result.rows) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
   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`);
@@ -58,16 +69,53 @@ 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}`));
       break;
+    case 'port plan': {
+      const f = result.facts;
+      lines.push(`Port plan for ${result.folder}`, '', `Difficulty: ${result.grade.toUpperCase()}`, ...result.reasons.map((r) => `  - ${r}`), '',
+        `What it is: ${f.engine.join(', ')}; ${f.loc} lines of game code in ${f.files} files (${Math.round(f.bytes / 1024)} KB); ${f.turnBased ? 'turn-based / moves on input' : 'real time'}${f.physics.length ? `; physics: ${f.physics.join(', ')}` : ''}.`,
+        `Input: keys ${f.input.keys}, mouse ${f.input.mouse}, touch ${f.input.touch}, pointer ${f.input.pointer}${f.input.pointerLock ? ', pointer lock' : ''}.`,
+        `Recommended: movement "${result.recommend.movement}", check view "${result.recommend.view}", build "${result.recommend.build}".`,
+        `Licence: ${result.licence.kind}${result.licence.file ? ` (${result.licence.file})` : ''}.`, '', 'Risks:', ...(result.risks.length ? result.risks.map((r) => `  - ${r}`) : ['  - none found by reading; the checks will say']));
+      break;
+    }
+    case 'port import':
+      lines.push(`games/${result.id} is a port of ${result.from} (${result.files} files, build "${result.mode}", draft grade ${result.plan.grade}).`, ...result.edits.map((e) => `  ${e}`), '', 'Next:', ...result.next.map((n) => `  - ${n}`));
+      break;
+    case 'port check':
+      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 '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`));
@@ -89,7 +137,15 @@ async function main() {
   if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install') });
   if (cmd === 'starters') return { ok: true, command: 'starters', starters: starters() };
 
+  if (cmd === 'port' && sub === 'plan') return planPort(positional[2] ?? '.');
   const root = requireStudio();
+  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;
+    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 });
+  }
   if (cmd === 'game' && sub === 'new') return newGame(root, positional[2], { from: flags.get('from') ?? 'gem-rush', name: flags.get('name') });
   if (cmd === 'game' && sub === 'remix') return remixGame(root, positional[2], flags.get('id'), { name: flags.get('name') });
   if (cmd === 'games') return { ok: true, command: 'games', games: listGames(root).map(({ dir, ...g }) => ({ ...g, dir: relative(root, dir) })) };
@@ -98,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;
@@ -105,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);
@@ -126,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 });
     });
   });
 }
@@ -159,7 +264,7 @@ try {
   if (result && result.command !== 'help') print(result);
   if (result?.ok === false) process.exitCode = 1;
   // Chrome's pipes can outlive browser.close(); a finished check must not hang its caller.
-  if (result?.command === 'check') process.exit(process.exitCode ?? 0);
+  if (result?.command === 'check' || result?.command === 'port check') process.exit(process.exitCode ?? 0);
 } catch (error) {
   print({ ok: false, why: error instanceof Error ? error.message : String(error) });
   process.exitCode = 1;

package/lib/build.mjs

@@ -5,15 +5,55 @@
  *   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
+ *   { "mode": "static" }              the folder copied as it is (plain <script> games), plus homie-port.js,
+ *                                     the port toolkit as one classic script (window.HomiePort); an "entry"
+ *                                     is bundled to assets/main.js as well
+ *   { "mode": "command", "command": "npm run build", "out": "dist" }
+ *                                     the game's own build (Vite, webpack…), then its output copied; base must be './'
  */
+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 } from 'node:path';
-import { listGames, readStudio } from './studio.mjs';
+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';
 
-const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler']);
+const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
+/** Never copied into a static game's served folder. */
+const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md']);
+const LOADERS = { '.png': 'file', '.jpg': 'file', '.jpeg': 'file', '.gif': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.m4a': 'file', '.glb': 'file', '.gltf': 'file', '.bin': 'file', '.hdr': 'file', '.svg': 'file', '.json': 'json', '.woff2': 'file', '.ttf': 'file' };
+
+/** The port toolkit as one classic script (window.HomiePort), for static games. Built once per build. */
+async function portScript(esbuild, root, cache) {
+  if (cache.text) return cache.text;
+  const entry = join(PACKAGE_ROOT, 'port', 'global.ts');
+  const res = await esbuild.build({ entryPoints: [entry], bundle: true, format: 'iife', target: 'es2020', minify: true, write: false, absWorkingDir: root, logLevel: 'silent' });
+  cache.text = `/* homie-port.js — @homie-rocks/studio port toolkit (window.HomiePort). Load it first in <head>. */\n${res.outputFiles[0].text}`;
+  return cache.text;
+}
+
+function copyStatic(from, to) {
+  for (const entry of readdirSync(from, { withFileTypes: true })) {
+    if (STATIC_SKIP.has(entry.name)) continue;
+    const src = join(from, entry.name);
+    const dest = join(to, entry.name);
+    if (entry.isDirectory()) { mkdirSync(dest, { recursive: true }); copyStatic(src, dest); }
+    else if (entry.isFile()) cpSync(src, dest);
+  }
+}
+
+function dirBytes(dir) {
+  let n = 0;
+  for (const e of readdirSync(dir, { withFileTypes: true })) n += e.isDirectory() ? dirBytes(join(dir, e.name)) : statSync(join(dir, e.name)).size;
+  return n;
+}
 const TEXT = /\.(ts|tsx|js|mjs|jsx|json|html|css|md|txt|svg|glsl|wgsl|frag|vert)$/i;
 /** Text files of a game folder, capped (2 MB total, 512 KB each): what `homie-studio game remix` takes. */
 export function sourceOf(dir, id) {
@@ -47,40 +87,77 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   if (!only) rmSync(dist, { recursive: true, force: true });
   mkdirSync(dist, { recursive: true });
   const built = [];
+  const cache = {};
   for (const g of games) {
     const out = join(dist, 'games', g.id);
     rmSync(out, { recursive: true, force: true });
     mkdirSync(join(out, 'assets'), { recursive: true });
-    const entry = join(g.dir, g.entry ?? 'src/main.ts');
-    if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${g.entry ?? 'src/main.ts'} not found`);
+    const mode = g.build?.mode ?? 'bundle';
     const started = Date.now();
-    const result = await esbuild.build({
-      entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: false,
-      outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
-      loader: { '.png': 'file', '.jpg': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.glb': 'file', '.svg': 'file' },
-      assetNames: '[name]-[hash]',
-    }).catch((error) => {
-      const first = error.errors?.[0];
-      throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
-    });
-    const html = join(g.dir, 'index.html');
-    if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
-    writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
-    if (existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
+    let warnings = 0;
+    const bundle = async (entryRel) => {
+      const entry = join(g.dir, entryRel);
+      if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
+      const result = await esbuild.build({
+        entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: false,
+        outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
+        loader: LOADERS, assetNames: '[name]-[hash]',
+      }).catch((error) => {
+        const first = error.errors?.[0];
+        throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
+      });
+      warnings += result.warnings.length;
+    };
+    if (mode === 'static') {
+      copyStatic(g.dir, out);
+      writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
+      if (g.entry) await bundle(g.entry);
+      const html = readFileSync(join(out, 'index.html'), 'utf8');
+      if (!/homie-port\.js/.test(html)) log(`warning: games/${g.id}/index.html does not load ./homie-port.js (the port toolkit); add <script src="./homie-port.js"></script> first in <head>`);
+    } else if (mode === 'command') {
+      const command = String(g.build.command ?? 'npm run build');
+      const res = spawnSync(command, { cwd: g.dir, shell: true, encoding: 'utf8', timeout: 10 * 60_000, maxBuffer: 64 * 1024 * 1024 });
+      if (res.status !== 0) throw new Error(`games/${g.id}: \`${command}\` failed: ${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-6).join(' ')}`);
+      const built = join(g.dir, String(g.build.out ?? 'dist'));
+      if (!existsSync(join(built, 'index.html'))) throw new Error(`games/${g.id}: \`${command}\` left no index.html in ${relative(g.dir, built) || '.'}`);
+      cpSync(built, out, { recursive: true });
+      writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
+    } else {
+      await bundle(g.entry ?? 'src/main.ts');
+      const html = join(g.dir, 'index.html');
+      if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
+      writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
+    }
+    if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
+    if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
     // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).
     if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id))}\n`);
-    const bytes = statSync(join(out, 'assets', 'main.js')).size;
-    built.push({ id: g.id, name: g.name, bytes, ms: Date.now() - started, warnings: result.warnings.length });
-    log(`built ${g.id} (${Math.round(bytes / 1024)} KB)`);
+    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 });
+    log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB)`);
   }
   const all = listGames(root);
+  // Songs and videos (music/ and videos/ manifests): rebuilt with every full build; a one-game build keeps them.
+  const r2 = Boolean(studio.cloudflare?.r2 && (studio.cloudflare?.created ?? []).includes(`r2:${studio.cloudflare.r2}`));
+  let media = null;
+  if (!only) media = buildMedia(root, dist, { r2, log });
+  else {
+    try { const prev = JSON.parse(readFileSync(join(dist, 'games.json'), 'utf8')); media = { songs: prev.songs ?? [], videos: prev.videos ?? [], skipped: [] }; } catch { media = { songs: [], videos: [], skipped: [] }; }
+  }
   const catalogue = {
     studio: { name: studio.name, slug: studio.slug, version: STUDIO_VERSION },
     games: all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))).map((g) => ({
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: g.players ?? { min: 1, max: 8 },
       roundSeconds: g.roundSeconds ?? null, movement: g.netplay?.movement ?? null, cover: g.cover ?? null,
+      ...(g.screen ? { screen: g.screen } : {}),
     })),
+    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,
+  };
 }