@homie-rocks/studio 0.17.0 → 0.18.0

package/README.md

@@ -414,21 +414,26 @@ it says the frame rate is not a person's, and judges only seats, rooms and round
 
 `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
+(`Table`, `Lobby`). It never creates 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:
+Storage for songs and videos is a separate, optional step. Once a studio has it, its big media
+lives in R2 by default:
 
 ```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
+npx homie-studio storage add                           # the studio's R2 bucket, bound as MEDIA
+npx homie-studio media move --dry-run                  # what goes: over 1 MiB, or left out of git
+npx homie-studio deploy                                # moves it (uploaded, read back, SHA-256 checked), then deploys
 ```
 
-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.
+Each moved file keeps its address (`/videos/<slug>/<file>.mp4`), served from R2 with byte ranges,
+HEAD, ETags and the site's own cache headers, and the site's static files stop carrying it; the file
+stays in the studio folder, and the committed manifest names its R2 copy, so a deploy from another
+computer or Workers Builds still has it (`media/MEDIA.md`). 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; no egress fees; then US$0.015 per GB-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.
 
@@ -446,7 +451,7 @@ 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` (and `deploy --plan`): Wrangler, D1, migrations; refuses resources it did not create. In Workers Builds, migrations and deploy only. `storage add`: the optional R2 bucket. |
+| `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations; refuses resources it did not create. In Workers Builds, migrations and deploy only. `storage add`: the optional R2 bucket; `media move`: big media into it, checked by SHA-256 (every deploy runs it). |
 | `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it, with each one's frame rate; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. `lib/chrome.mjs`: which Chrome, and how (the GPU on a Mac, SwiftShader on Linux). |
 | `lib/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |
 | `lib/progress.mjs`, `lib/setup.mjs` | The progress feed (`progress …`), a build the chat opened (`progress attach`), a change as a pull request (`progress change`, `progress pr`), and `setup attach`. |
@@ -455,10 +460,10 @@ 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`); `/<game>/watch` watches a live room from any player's view (NETPLAY.md section 16); `/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/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`); `/<game>/watch` watches a live room from any player's view (NETPLAY.md section 16); `/music/<slug>/` and `/videos/<slug>/` are song and video pages (their files served with byte ranges, from the site's files or, once moved, from the studio's R2 at the same address; a loose file from `media put` at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
 | `worker/site.mjs`, `lib/site.mjs`, `lib/markdown.mjs`, `site/SITE.md` | The site: its sections, each game's landing, posts and their feeds, the look (theme tokens) and what the studio's `site/` folder overrides; the safe markdown posts are written in. `worker/pages.mjs`: the play page. |
 | `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. |
+| `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 R2, or a link). `media list` shows it; `media move` puts the big ones in R2 and records each one's SHA-256; `media put` uploads a loose file to `/media/<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

@@ -32,8 +32,14 @@
  *                                         migrations and deploys: the Worker and database are the Deploy button's.
  *   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 media list               (every song and video page, where each file is served from, what moves to R2)
+ *   homie-studio media move [<file>...] [--dry-run] [--verify]
+ *                                         (with storage: the big files of published songs and videos into R2, each
+ *                                          read back and checked by SHA-256 before the site stops carrying it; the
+ *                                          address stays the same and the file stays in this folder. With no file:
+ *                                          everything over studio.json media.r2Over, 1 MiB unless set, or left out of
+ *                                          git. Every deploy does it too. --verify re-checks what R2 holds)
+ *   homie-studio media put <file> [--as <key>]   (a loose file at /media/<key>; for a song or video, media move)
  *   homie-studio status
  *   homie-studio upgrade [--apply] [--diff]
  *                                         (what this version's template adds to an existing studio: AGENTS.md
@@ -136,14 +142,14 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, wr
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { build } from '../lib/build.mjs';
 import { check } from '../lib/check.mjs';
-import { ciDeploy, deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { ciDeploy, deploy, deployPlan, mediaMove, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
 import { setupAttach } from '../lib/setup.mjs';
 import { chromeArgs, findChrome, installChrome, noChrome } from '../lib/chrome.mjs';
 import { publish } from '../lib/directory.mjs';
 import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
-import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
+import { R2_COST, lineOf, mediaPlan, r2OverOf, recordUpload, resolveMedia, sizeOf, typeOf } from '../lib/media.mjs';
 import { ensureMigrations, migrationWord, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
@@ -164,7 +170,7 @@ import { formatHandoff, handoff } from '../lib/handoff.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai'];
+const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -210,10 +216,31 @@ function print(result) {
     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 e of result[kind].pages) lines.push(`  /${kind}/${e.slug}/  ${e.title}  (${e.files.map((f) => `${f.role} from ${f.from === 'r2' ? 'R2' : f.from}`).join(', ')})`);
         for (const m of result[kind].skipped) lines.push(`  left out: ${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
+        for (const m of result[kind].notes ?? []) lines.push(`  note: ${m.item} ${m.file}: ${m.why}`);
       }
+      if (result.moves.length) {
+        lines.push('', `Big media${result.r2 ? ' for R2' : ''} (over ${result.over === null ? '(off)' : lineOf(result.over)}, or left out of git):`);
+        for (const m of result.moves) lines.push(`  ${m.path}  ${m.bytes ? sizeOf(m.bytes) : ''}  ${m.state === 'too-big' ? m.why : m.reason ?? ''}`);
+      }
+      if (result.storage) lines.push('', result.storage);
+      if (result.r2) lines.push(`R2 holds about ${sizeOf(result.inR2)} of this studio's media once these are in. ${result.cost}`);
+      break;
+    case 'media move': {
+      const verb = result.dryRun ? 'Would move' : 'Moved';
+      if (result.ok === false && result.needs === 'storage') { lines.push(result.why); break; }
+      if (result.off) { lines.push(result.why); break; }
+      const todo = result.rows.filter((r) => r.state === 'move');
+      if (result.dryRun) lines.push(todo.length ? `${verb} ${todo.length} file(s) to R2 ${result.bucket}:` : 'Nothing to move: every big file is in R2 already, or none is published.', ...todo.map((r) => `  ${r.path}  ${sizeOf(r.bytes)}  (${r.reason})`));
+      else lines.push(result.moved.length ? `${verb} ${result.moved.length} file(s) to R2 ${result.bucket}, each read back and checked by SHA-256:` : 'Nothing moved.', ...result.moved.map((m) => `  ${m.path}  ${sizeOf(m.bytes)}  -> served at ${m.url} (the same address)`));
+      for (const f of result.failed ?? []) lines.push(`  NOT moved: ${f.path}: ${f.why}`);
+      for (const v of result.verified ?? []) lines.push(`  ${v.ok ? 'verified' : 'MISMATCH'}: ${v.path}${v.why ? `: ${v.why}` : ''}`);
+      for (const r of result.rows.filter((x) => x.state === 'too-big' || x.state === 'unlisted' || x.state === 'missing')) lines.push(`  ${r.state}: ${r.path}: ${r.why}`);
+      if (result.next) lines.push('', result.next);
+      lines.push(`R2 holds about ${sizeOf(result.inR2)} of this studio's media. ${result.cost}`, ...(result.warning ? [`Warning: ${result.warning}`] : []));
       break;
+    }
     case 'deploy':
       if (result.ci) {
         lines.push(`Live: ${result.url ?? '(Wrangler printed no address)'}${result.commit ? ` (commit ${result.commit.slice(0, 7)}${result.branch ? ` on ${result.branch}` : ''})` : ''}`, ...result.steps.map((x) => `  ${x.what}`), ...result.games.map((g) => `  ${g.id}: ${g.play}`));
@@ -221,7 +248,8 @@ function print(result) {
       }
       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.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}`),
+        ...(result.media?.moved ?? []).map((m) => `  moved to R2 (checked by SHA-256): ${m.path}, still at ${m.url}`), ...(result.media?.failed ?? []).map((m) => `  not moved to R2: ${m.path}: ${m.why}`), '', `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 ? 'The site claimed itself in the directory: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the site claims itself when the directory first reads it; publish does).');
       break;
     case 'deploy plan':
@@ -410,6 +438,12 @@ function print(result) {
         if (!flags.has('diff')) lines.push('  (--diff shows how each differs from the template: "-" this studio\'s lines, "+" the template\'s)');
       }
       if (result.uncommitted && !result.applied && result.changes.length) lines.push('', `Note: ${result.uncommitted} file(s) have uncommitted changes; commit them first so the upgrade is a change of its own.`);
+      if (result.media) {
+        lines.push('', `Big media (songs and videos over ${result.media.over === null ? '(off)' : lineOf(result.media.over)}, or left out of git):`);
+        for (const r of result.media.inR2) lines.push(`  = ${r.path}  in R2`);
+        for (const r of result.media.big) lines.push(`  > ${r.path}  ${r.bytes ? sizeOf(r.bytes) : ''}  ${r.state === 'too-big' ? r.why : r.reason ?? ''}`);
+        if (result.media.next) lines.push(`  ${result.media.next}`);
+      }
       if (result.next?.length) lines.push('', 'Next:', ...result.next.map((n) => `  ${n}`));
       break;
     }
@@ -553,11 +587,21 @@ async function main() {
     return { ok: false, command: 'agents', why: `unknown: agents ${sub ?? ''} (pass, passes, revoke, brain, brain key, sit)` };
   }
   if (cmd === 'media' && sub === 'put') return mediaPut(root, positional[2], flags.get('as'));
+  if (cmd === 'media' && sub === 'move') return mediaMove(root, { paths: positional.slice(2), dryRun: flags.has('dry-run') || flags.has('plan'), verify: flags.has('verify'), log });
   if (cmd === 'media' && sub === 'list') {
     const studio = readStudio(root);
     const r2 = Boolean(studio.cloudflare?.r2 && (studio.cloudflare?.created ?? []).includes(`r2:${studio.cloudflare.r2}`));
-    const view = (kind) => { const r = resolveMedia(root, kind, { r2 }); return { pages: r.entries.map((e) => ({ slug: e.slug, title: e.title, kind: e.kind, files: e.files.map(({ abs, rel, ...f }) => f) })), skipped: r.skipped }; };
-    return { ok: true, command: 'media list', r2, site: siteUrl(root, studio), music: view('music'), videos: view('videos') };
+    // What a deploy would serve (deploy: true), so "from r2" means the site no longer carries the file.
+    const view = (kind) => { const r = resolveMedia(root, kind, { r2, deploy: true }); 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, notes: r.notes }; };
+    const over = r2OverOf(studio);
+    const plan = mediaPlan(root, { over });
+    const moves = plan.filter((x) => x.state === 'move' || x.state === 'too-big').map(({ abs, held, ...x }) => x);
+    const inR2 = plan.filter((x) => x.state === 'r2' || x.state === 'move').reduce((n, x) => n + (x.bytes ?? 0), 0);
+    return {
+      ok: true, command: 'media list', r2, site: siteUrl(root, studio), music: view('music'), videos: view('videos'), over, moves, inR2,
+      storage: r2 ? (moves.length ? 'the next deploy (or media move now) puts these in R2, checked by SHA-256; their addresses stay the same' : 'every big file is in R2') : (moves.length ? 'no storage: these stay on the site (files up to 25 MiB each), and a deploy from another computer or Workers Builds leaves out any file git does not keep. homie-studio storage add (a payment method on the Cloudflare account, asked first) fixes both' : null),
+      cost: R2_COST,
+    };
   }
   return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
 }

package/lib/build.mjs

@@ -15,7 +15,11 @@
  *   site/dist/_studio/codex/<id>/          each game's Game Codex (games/<id>/CODEX.md, lib/codex.mjs): served only to
  *                                          the studio's owner (worker/stats-page.mjs), never listed or indexed
  *   site/dist/<file>                       site/public, as it is (fonts, a logo, hero footage)
- *   site/dist/music/..., site/dist/videos/...   media files the site serves itself (R2 keys are served from R2)
+ *   site/dist/music/..., site/dist/videos/...   media files the site serves itself. A file the studio's R2 has (media
+ *                                          move: the same bytes, by SHA-256) is left out of a deploy's build and
+ *                                          served from R2 at the same address; a local build still copies it when it
+ *                                          fits, for `dev` (whose R2 is empty). Workers Builds (WORKERS_CI=1) builds
+ *                                          as a deploy.
  *
  * 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
@@ -201,7 +205,7 @@ export function seatsFor(g, net = netplayOf(g)) {
   return { min: Math.min(max, minNamed ?? 1), max, asked };
 }
 
-export async function build(root, { only = null, log = () => {} } = {}) {
+export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1' } = {}) {
   const require = createRequire(join(root, 'package.json'));
   let esbuild;
   try { esbuild = require('esbuild'); } catch { esbuild = await import('esbuild'); }
@@ -270,9 +274,9 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   // 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 });
+  if (!only) media = buildMedia(root, dist, { r2, deploy, 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: [] }; }
+    try { const prev = JSON.parse(readFileSync(join(dist, 'games.json'), 'utf8')); media = { songs: prev.songs ?? [], videos: prev.videos ?? [], skipped: [], notes: [] }; } catch { media = { songs: [], videos: [], skipped: [], notes: [] }; }
   }
   // The site around the games (site/SITE.md): the look, each game's landing, posts, and what site/ overrides.
   const theme = readTheme(root, { log });
@@ -345,7 +349,7 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   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),
-    songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped,
+    songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped, mediaNotes: media.notes ?? [],
     posts: posts.map((p) => p.slug), postsSkipped, codexes, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
     landings: rows.map((g) => ({ id: g.id, hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length), source: g.landing.source })),
   };

package/lib/cloudflare.mjs

@@ -9,19 +9,24 @@
  * 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 never creates 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. Once a studio has it,
+ * deploy binds it and moves the big songs and videos there first (mediaMove:
+ * uploaded, read back, checked by SHA-256), so the site stops carrying them and
+ * serves them from R2 at the same addresses.
  *
  * 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. `deploy --plan` says all of this
  * before anything happens and calls nothing.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.mjs';
+import { MAX_ASSET_BYTES, R2_COST, mediaPlan, r2OverOf, recordMove, sha256File, sizeOf } from './media.mjs';
 import { repoOf } from './repo.mjs';
 import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
 import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
@@ -101,11 +106,11 @@ export function deployPlan(root) {
       { 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: storage, what: 'the studio\'s big media: songs and videos over the size studio.json media.r2Over names (1 MiB unless set) or that git leaves out, uploaded and checked by SHA-256 before the site stops carrying them, served at their same addresses', 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 on Cloudflare's Workers Free plan. ${R2_COST} Beyond the free tier 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`,
@@ -158,9 +163,22 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
     for (const line of announced) log(line);
   }
 
-  const b = await build(root, { log });
+  // Big media into the studio's R2 before the build (0.18.0): only with storage this studio made, so a free account
+  // with no payment method is never asked anything about R2. Each file is read back and its SHA-256 compared before
+  // the build stops carrying it; a file that did not make it stays on the site (when it fits) and is named here.
+  const storage = cf.r2 && created.has(`r2:${cf.r2}`) ? cf.r2 : null;
+  let media = null;
+  if (storage) {
+    media = await mediaMove(root, { auto: true, accountId, log });
+    for (const m of media.moved ?? []) step(`moved ${m.path} (${sizeOf(m.bytes)}) to R2 and checked it by SHA-256; the site serves it at the same address, ${m.url}`);
+    for (const m of media.failed ?? []) step(`not moved to R2: ${m.path}: ${m.why}`);
+    if (media.why && !media.ok) step(`big media stays on the site this time: ${media.why}`);
+  }
+
+  const b = await build(root, { log, deploy: true });
   // A new studio goes live with its own Home ("First game coming soon") before it has a game.
   step(b.catalogue.length || b.songs.length || b.videos.length ? `built ${b.catalogue.length} game(s), ${b.songs.length} song(s), ${b.videos.length} video(s)` : 'built the home page (no game yet: "First game coming soon")');
+  for (const n of b.mediaNotes ?? []) step(`note: ${n.file}: ${n.why}`);
 
   // The Worker: never one this studio did not make.
   if (!created.has(`worker:${cf.worker}`)) {
@@ -189,7 +207,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
 
   // 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;
+  const r2 = storage;
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
   writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root) }));
@@ -237,6 +255,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   writeStudio(root, { ...readStudio(root), cloudflare: next });
   return {
     ok: true, command: 'deploy', url, ...(workersDev ? { workersDev, local: LOCAL_STATE } : {}), worker: cf.worker, d1: cf.d1, r2, account: accountId, announced, steps,
+    ...(media ? { media: { moved: media.moved ?? [], failed: media.failed ?? [], inR2: media.inR2 ?? null } } : {}),
     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 })),
@@ -400,5 +419,112 @@ export async function storageAdd(root, { log = () => {} } = {}) {
     writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root) }));
   }
   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>'] };
+  return { ok: true, command: 'storage add', bucket, account: accountId, cost: R2_COST, next: ['npx --no-install homie-studio media move --dry-run   (which songs and videos go to R2: over 1 MiB, or left out of git)', 'npm run deploy   (binds the bucket as MEDIA, moves them, checks each by SHA-256, and serves them from R2 at the same addresses; the files stay in this folder)'] };
+}
+
+/** One Wrangler command, run without blocking (an upload of a music video takes a while); the last of its words kept. */
+function wranglerRun(bin, args, { cwd, env }) {
+  return new Promise((done) => {
+    const p = spawn(bin, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    const keep = (d) => { out = `${out}${d}`.slice(-8000); };
+    p.stdout.on('data', keep);
+    p.stderr.on('data', keep);
+    p.on('error', (e) => done({ code: 1, out: String(e.message) }));
+    p.on('close', (code) => done({ code: code ?? 1, out: out.replace(ANSI, '') }));
+  });
+}
+
+/** Read an object back from R2 (`wrangler r2 object get --pipe`) and hash it as it streams: nothing is written to disk. */
+function hashRemote(bin, path, { cwd, env }) {
+  return new Promise((done) => {
+    const p = spawn(bin, ['r2', 'object', 'get', path, '--remote', '--pipe'], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const h = createHash('sha256');
+    let bytes = 0;
+    let err = '';
+    p.stdout.on('data', (d) => { h.update(d); bytes += d.length; });
+    p.stderr.on('data', (d) => { err = `${err}${d}`.slice(-4000); });
+    p.on('error', (e) => done({ code: 1, err: String(e.message) }));
+    p.on('close', (code) => done({ code: code ?? 1, sha256: h.digest('hex'), bytes, err: err.replace(ANSI, '') }));
+  });
+}
+
+/*
+ * `homie-studio media move [<file>...] [--dry-run] [--verify]` (and every `deploy` of a studio with storage): the big
+ * public files of the studio's published songs and videos go into its own R2, at the key that is their path, so the
+ * site keeps serving them at the same address.
+ *
+ *   1. hash the file on this computer (SHA-256);
+ *   2. `wrangler r2 object put <bucket>/<path>`;
+ *   3. read it back (`wrangler r2 object get --pipe`) and hash what R2 returns;
+ *   4. only when size and hash match, record `r2: { key, sha256, bytes, at }` on the manifest's file.
+ *
+ * The next deploy's build leaves a recorded file out of the site's static assets (and serves it from R2). The file
+ * on this computer is never deleted, moved or changed. A file that fails any step is named, and stays on the site.
+ * `--verify` reads every file already recorded back from R2 and checks its hash again (it changes nothing).
+ */
+export async function mediaMove(root, { paths = null, dryRun = false, verify = false, auto = false, accountId = null, log = () => {} } = {}) {
+  const studio = readStudio(root);
+  const cf = { created: [], ...studio.cloudflare };
+  const bucket = cf.r2 && (cf.created ?? []).includes(`r2:${cf.r2}`) ? cf.r2 : null;
+  const over = r2OverOf(studio);
+  const named = Array.isArray(paths) && paths.length ? paths : null;
+  const rows = mediaPlan(root, { over, paths: named });
+  const view = (r) => ({ path: r.path, kind: r.kind, slug: r.slug, role: r.role, state: r.state, bytes: r.bytes ?? null, ...(r.reason ? { reason: r.reason } : {}), ...(r.why ? { why: r.why } : {}) });
+  const held = rows.filter((r) => r.state === 'r2');
+  const todo = rows.filter((r) => r.state === 'move');
+  const inR2 = [...held, ...todo].reduce((n, r) => n + (r.bytes ?? 0), 0);
+  const base = {
+    command: 'media move', bucket, over, rows: rows.map(view), inR2, cost: R2_COST,
+    // Over the free 10 GB-month, Cloudflare bills the account: say so with the number.
+    ...(inR2 > 10e9 ? { warning: `R2 would hold ${sizeOf(inR2)} of this studio's media, over the 10 GB-month free tier: about US$${(((inR2 - 10e9) / 1e9) * 0.015).toFixed(2)} a month more, billed by Cloudflare to the account` } : {}),
+  };
+  if (!bucket) {
+    return { ok: false, ...base, needs: 'storage', why: 'this studio has no storage yet, so its media stays on the site (files up to 25 MiB each). `npx --no-install homie-studio storage add` adds an R2 bucket; Cloudflare asks for a payment method on the account before R2 works, so ask the person first. Games never need it.' };
+  }
+  if (auto && over === null && !named) return { ok: true, ...base, off: true, moved: [], failed: [], why: 'studio.json media.r2Over is false: nothing moves on its own' };
+  if (dryRun || (!todo.length && !verify)) return { ok: true, ...base, dryRun, moved: [], failed: [], next: todo.length ? 'npx --no-install homie-studio media move   (then npm run deploy)' : null };
+  const bin = wranglerBin(root);
+  if (!bin) return { ok: false, ...base, why: 'Wrangler is not installed in this studio yet: run `npm install` in the studio folder first' };
+  const account = accountId || process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || null;
+  const opts = { cwd: workerDir(root), env: { ...process.env, ...(account ? { CLOUDFLARE_ACCOUNT_ID: account } : {}), WRANGLER_SEND_METRICS: 'false', CI: '1' } };
+  const moved = [];
+  const failed = [];
+  const verified = [];
+  if (verify) {
+    for (const r of held) {
+      const key = r.held?.key ?? r.path;
+      const got = await hashRemote(bin, `${bucket}/${key}`, opts);
+      const ok = got.code === 0 && got.sha256 === r.held?.sha256 && got.bytes === Number(r.held?.bytes);
+      verified.push({ path: r.path, key, ok, bytes: got.bytes, ...(ok ? {} : { why: got.code !== 0 ? `could not read it back: ${got.err.trim().split('\n').slice(-2).join(' ')}` : 'R2 returned different bytes than were recorded' }) });
+      log(`${ok ? 'verified' : 'MISMATCH'} ${r.path} in R2 ${bucket}/${key}`);
+    }
+  }
+  for (const r of todo) {
+    const key = r.path;
+    const url = `/${key.split('/').map(encodeURIComponent).join('/')}`;
+    const sha256 = sha256File(r.abs);
+    log(`uploading ${r.path} (${sizeOf(r.bytes)}) to R2 ${bucket}/${key}`);
+    const put = await wranglerRun(bin, ['r2', 'object', 'put', `${bucket}/${key}`, '--file', r.abs, '--content-type', r.type, '--remote'], opts);
+    // Where the file is meanwhile: on the site when it fits; a bigger one keeps an older R2 copy, or waits.
+    const meanwhile = r.bytes <= MAX_ASSET_BYTES ? ' It stays on the site.' : r.held ? ' Its page keeps playing the older copy in R2.' : ' At this size the site cannot carry it, so its page waits until it is in R2.';
+    if (put.code !== 0) {
+      failed.push({ path: r.path, bytes: r.bytes, why: `${explainCloudflare(put.out, account)?.why ?? `the upload failed: ${put.out.trim().split('\n').slice(-3).join(' ')}`}${meanwhile}` });
+      continue;
+    }
+    const got = await hashRemote(bin, `${bucket}/${key}`, opts);
+    if (got.code !== 0 || got.sha256 !== sha256 || got.bytes !== r.bytes) {
+      failed.push({ path: r.path, bytes: r.bytes, why: `${got.code !== 0 ? `uploaded, but it could not be read back to check it (${got.err.trim().split('\n').slice(-2).join(' ')}); nothing recorded.` : `R2 returned ${got.bytes} bytes with a different SHA-256 from this file's ${r.bytes}; nothing recorded.`}${meanwhile}` });
+      continue;
+    }
+    const at = new Date().toISOString();
+    const manifests = recordMove(root, r.path, { key, sha256, bytes: r.bytes, at });
+    moved.push({ path: r.path, key, bytes: r.bytes, sha256, url, manifests });
+    log(`checked ${r.path} in R2 by SHA-256 (${sha256.slice(0, 12)}…); its address stays ${url}`);
+  }
+  const bad = verified.filter((v) => !v.ok);
+  return {
+    ok: !failed.length && !bad.length, ...base, moved, failed, ...(verify ? { verified } : {}),
+    ...(moved.length ? { next: 'npm run deploy: the site stops carrying these files and serves them from R2 at the same addresses. The files stay in this folder; commit the manifests (they name each file\'s R2 copy), never the media.' } : {}),
+  };
 }

package/lib/media.mjs

@@ -1,9 +1,18 @@
 /**
  * A studio's music/ and videos/ manifests (media/MEDIA.md): what the site shows,
- * and where each file's bytes come from (R2 key, a file in the repository copied
- * into the site, or an absolute https address).
+ * and where each file's bytes come from (the studio's R2, a file in the repository
+ * copied into the site, or an absolute https address).
+ *
+ * BIG MEDIA LIVES IN R2 (0.18.0). Once a studio has storage (`homie-studio storage add`), every public file of a
+ * published song or video that is over `R2_OVER` bytes (studio.json `media.r2Over`), or that git leaves out of the
+ * repository, goes to the studio's own bucket: `homie-studio media move` (and every `deploy`) uploads it, reads it
+ * back and compares SHA-256, and only then records `r2: { key, sha256, bytes, at }` on the manifest's file. A deploy
+ * build then stops carrying that file in the site's static assets, and the Worker serves the very same address
+ * (`/<path>`) from R2, with byte ranges and the same cache headers. The local file is never deleted.
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, normalize, relative, resolve, sep } from 'node:path';
 
 export const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
@@ -13,6 +22,15 @@ export const KINDS = {
 };
 /** Cloudflare Workers static assets: one file may be at most 25 MiB. */
 export const MAX_ASSET_BYTES = 25 * 1024 * 1024;
+/**
+ * Over this many bytes a public file of a published entry is kept in the studio's R2 once it has storage (the
+ * default for studio.json `media.r2Over`; `false` there keeps every file on the site unless `media move` names it).
+ */
+export const R2_OVER = 1024 * 1024;
+/** Wrangler uploads one object of at most 300 MiB (`wrangler r2 object put`). */
+export const MAX_PUT_BYTES = 300 * 1024 * 1024;
+/** What R2 costs, said the same way everywhere (Cloudflare's R2 pricing page, read 2026-10-01). */
+export const R2_COST = 'R2 is on the studio\'s own Cloudflare account. Serving its files costs nothing in bandwidth (R2 has no egress fees). Storage is free up to 10 GB-month, then US$0.015 per GB-month; uploads (Class A) are free up to 1 million a month and reads (Class B) up to 10 million a month. Cloudflare asks for a payment method on the account before R2 works, even inside the free tier.';
 const TYPES = {
   '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.aac': 'audio/aac', '.ogg': 'audio/ogg', '.opus': 'audio/ogg', '.wav': 'audio/wav', '.flac': 'audio/flac',
   '.mp4': 'video/mp4', '.m4v': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime',
@@ -40,15 +58,64 @@ function inside(root, rel) {
   const abs = resolve(root, normalize(rel));
   return abs.startsWith(`${resolve(root)}${sep}`) ? abs : null;
 }
+/** A file's address on the site: its path in the studio, each part encoded (the same before and after it moves to R2). */
+const siteUrlOf = (root, abs) => `/${relative(root, abs).split(sep).map(encodeURIComponent).join('/')}`;
+const relOf = (root, abs) => relative(root, abs).split(sep).join('/');
+const fileOf = (abs) => { try { const st = statSync(abs); return st.isFile() ? st.size : null; } catch { return null; } };
+
+/** studio.json `media.r2Over`: bytes over which a public file goes to R2, or null (`false`: only `media move <file>`). */
+export function r2OverOf(studio) {
+  const v = studio?.media?.r2Over;
+  if (v === false || v === 'off') return null;
+  return Number.isFinite(v) && v >= 0 ? v : R2_OVER;
+}
+
+/** Sizes for people: "45.4 MB", "1.20 GB". */
+export const sizeOf = (n) => (n >= 1e9 ? `${(n / 1e9).toFixed(2)} GB` : n >= 1e6 ? `${(n / 1e6).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1e3))} KB`);
+/** A size line as it was set: "1 MiB" for 1048576, else as sizeOf says it. */
+export const lineOf = (n) => (n > 0 && n % 1048576 === 0 ? `${n / 1048576} MiB` : n > 0 && n % 1024 === 0 && n < 1048576 ? `${n / 1024} KiB` : sizeOf(n));
+
+const hashes = new Map();
+/** SHA-256 of a file, read in 8 MiB pieces; remembered per path, size and modified time for the life of the command. */
+export function sha256File(abs) {
+  const st = statSync(abs);
+  const memo = `${abs}\0${st.size}\0${st.mtimeMs}`;
+  if (hashes.has(memo)) return hashes.get(memo);
+  const h = createHash('sha256');
+  const fd = openSync(abs, 'r');
+  const buf = Buffer.allocUnsafe(8 << 20);
+  try {
+    for (;;) { const n = readSync(fd, buf, 0, buf.length, null); if (!n) break; h.update(buf.subarray(0, n)); }
+  } finally { closeSync(fd); }
+  const hex = h.digest('hex');
+  hashes.set(memo, hex);
+  return hex;
+}
+
+/** The R2 record `media move` wrote on a manifest file (its key and the SHA-256 it read back from R2), or null. */
+export function heldOf(f) {
+  const r = f?.r2;
+  return r && typeof r === 'object' && typeof r.key === 'string' && r.key && !r.key.startsWith('players/') && /^[0-9a-f]{64}$/.test(String(r.sha256 ?? '')) ? r : null;
+}
+
+/** Whether R2 has exactly this file: the size and the SHA-256 that `media move` read back from it. */
+export function sameAsHeld(abs, held) {
+  const bytes = fileOf(abs);
+  return bytes !== null && held && Number(held.bytes) === bytes && sha256File(abs) === held.sha256;
+}
 
 /**
  * Every entry of one manifest with its files resolved, and why anything is left out.
- * `r2`: the studio has its own bucket (so a `key` is served at /media/<key>).
+ * `r2`: the studio has its own bucket (so a `key` is served at /media/<key>, and a file `media move` put there at its
+ * own address). `deploy`: a build that goes live (`homie-studio deploy`, or Workers Builds): a file whose exact bytes
+ * are in R2 is not copied into the site. Without it (a local `build`, `dev`), a file that is also on this computer is
+ * still copied when it fits, because `wrangler dev`'s own R2 is empty.
  */
-export function resolveMedia(root, kind, { r2 = false } = {}) {
+export function resolveMedia(root, kind, { r2 = false, deploy = false } = {}) {
   const manifest = readManifest(root, kind);
   const entries = [];
   const skipped = [];
+  const notes = [];
   const seen = new Set();
   // The manifest's own picture (music: `cover`, videos: `poster`): an album cover for every song that has none of
   // its own. A path in the studio (copied into the site) or an https:// address, like any file.
@@ -68,20 +135,45 @@ export function resolveMedia(root, kind, { r2 = false } = {}) {
     for (const f of list) {
       if (!f || f.public === false) continue;
       let src = null;
+      // A key from `media put` (before 0.18.0): served at /media/<key>, as it always was.
       if (typeof f.key === 'string' && f.key && r2) src = { from: 'r2', url: `/media/${f.key.split('/').map(encodeURIComponent).join('/')}` };
+      // A file `media move` put in R2: served at its own address, from R2 once the site no longer carries it.
+      const held = heldOf(f);
+      if (!src && held && r2 && f.path) {
+        const abs = inside(root, f.path);
+        if (!abs) { skipped.push({ kind, item: item.slug, file: f.path, why: 'the path is outside the studio' }); continue; }
+        const url = siteUrlOf(root, abs);
+        const local = fileOf(abs);
+        const fromR2 = { from: 'r2', url, key: held.key, bytes: Number(held.bytes) || null };
+        if (local === null) src = fromR2;
+        else if (!deploy) src = local <= MAX_ASSET_BYTES ? { from: 'site', url, abs, rel: relative(root, abs), bytes: local } : fromR2;
+        else if (sameAsHeld(abs, held)) src = { ...fromR2, bytes: local };
+        else if (local <= MAX_ASSET_BYTES) {
+          src = { from: 'site', url, abs, rel: relative(root, abs), bytes: local };
+          notes.push({ kind, item: item.slug, file: f.path, why: 'changed since it went to R2: the site carries this copy until `homie-studio media move` uploads it again (deploy does it when the studio has storage)' });
+        } else {
+          src = fromR2;
+          notes.push({ kind, item: item.slug, file: f.path, why: `changed since it went to R2 (${held.at ?? 'earlier'}), and at ${sizeOf(local)} it is too big for the site: the page plays the copy in R2 until \`homie-studio media move ${f.path}\` uploads this one` });
+        }
+      }
       if (!src && f.path) {
         const abs = inside(root, f.path);
         if (!abs) { skipped.push({ kind, item: item.slug, file: f.path, why: 'the path is outside the studio' }); continue; }
-        if (existsSync(abs) && statSync(abs).isFile()) {
-          const bytes = statSync(abs).size;
-          if (bytes <= MAX_ASSET_BYTES) src = { from: 'site', url: `/${relative(root, abs).split(sep).map(encodeURIComponent).join('/')}`, abs, rel: relative(root, abs), bytes };
-          else skipped.push({ kind, item: item.slug, file: f.path, why: `${Math.round(bytes / 1048576)} MiB is over the 25 MiB the site serves itself: make it smaller, or give the studio storage (homie-studio storage add; Cloudflare asks for a payment method first, so ask the person) and upload it (homie-studio media put ${f.path})` });
-        } else if (f.key && !r2) skipped.push({ kind, item: item.slug, file: f.path, why: `the file is not on this computer and its storage key "${f.key}" needs the studio's storage (homie-studio storage add)` });
-        else if (!f.key && !f.url) skipped.push({ kind, item: item.slug, file: f.path, why: 'the file is not on this computer and has no R2 key or url' });
+        const bytes = fileOf(abs);
+        if (bytes !== null) {
+          if (bytes <= MAX_ASSET_BYTES) src = { from: 'site', url: siteUrlOf(root, abs), abs, rel: relative(root, abs), bytes };
+          else skipped.push({ kind, item: item.slug, file: f.path, why: `${Math.round(bytes / 1048576)} MiB is over the 25 MiB the site serves itself: give the studio storage (homie-studio storage add; Cloudflare asks for a payment method first, so ask the person) and the next deploy moves it to R2 (or homie-studio media move ${f.path} now), or make it smaller` });
+        } else if ((f.key || held) && !r2) skipped.push({ kind, item: item.slug, file: f.path, why: `the file is not on this computer and its copy in R2 ("${f.key ?? held.key}") needs the studio's storage (homie-studio storage add)` });
+        else if (!f.key && !held && !f.url) skipped.push({ kind, item: item.slug, file: f.path, why: 'the file is not on this computer and has no R2 copy or url' });
       }
       if (!src && typeof f.url === 'string' && /^https:\/\//.test(f.url)) src = { from: 'url', url: f.url };
       if (!src) continue;
-      files.push({ role: String(f.role ?? 'file'), name: f.name ?? null, type: f.type ?? typeOf(f.path ?? f.key ?? f.url), bytes: f.bytes ?? src.bytes ?? null, bars: f.bars ?? null, url: src.url, from: src.from, ...(src.abs ? { abs: src.abs, rel: src.rel } : {}) });
+      files.push({
+        role: String(f.role ?? 'file'), name: f.name ?? null, type: f.type ?? typeOf(f.path ?? f.key ?? f.url), bytes: f.bytes ?? src.bytes ?? null, bars: f.bars ?? null, url: src.url, from: src.from,
+        // The Worker serves this address from R2 (the site does not carry it): the catalogue says which key.
+        ...(src.from === 'r2' && src.key ? { r2: src.key } : {}),
+        ...(src.abs ? { abs: src.abs, rel: src.rel } : {}),
+      });
     }
     const main = kind === 'music' ? 'audio' : 'video';
     if (!files.some((f) => f.role === main)) { skipped.push({ kind, item: item.slug, why: `no playable "${main}" file reachable (see the file lines above)` }); continue; }
@@ -94,27 +186,104 @@ export function resolveMedia(root, kind, { r2 = false } = {}) {
       files,
     });
   }
-  return { entries, skipped };
+  return { entries, skipped, notes };
 }
 
 /** Copy the site-served files into site/dist and return the catalogue rows (no local paths in them). */
-export function buildMedia(root, dist, { r2 = false, log = () => {} } = {}) {
+export function buildMedia(root, dist, { r2 = false, deploy = false, log = () => {} } = {}) {
   const out = {};
   const skipped = [];
+  const notes = [];
+  let inR2 = 0;
   for (const kind of ['music', 'videos']) {
-    const r = resolveMedia(root, kind, { r2 });
+    const r = resolveMedia(root, kind, { r2, deploy });
     skipped.push(...r.skipped);
+    notes.push(...r.notes);
     out[kind] = r.entries.map((e) => ({
       ...e,
       files: e.files.map(({ abs, rel, from, ...f }) => {
         if (from === 'site') { const dest = join(dist, rel); mkdirSync(dirname(dest), { recursive: true }); cpSync(abs, dest); }
+        if (from === 'r2' && f.r2) inR2++;
         return f;
       }),
     }));
     if (out[kind].length) log(`${kind}: ${out[kind].map((e) => e.slug).join(', ')}`);
   }
+  if (inR2) log(`${inR2} file(s) served from the studio's R2 at their own addresses (not in the site's files)`);
   for (const s of skipped) log(`${s.kind}/${s.item}${s.file ? ` ${s.file}` : ''}: ${s.why}`);
-  return { songs: out.music, videos: out.videos, skipped };
+  for (const s of notes) log(`note: ${s.kind}/${s.item} ${s.file}: ${s.why}`);
+  return { songs: out.music, videos: out.videos, skipped, notes };
+}
+
+/** The files git leaves out of the repository (its .gitignore): a deploy from another computer, or Workers Builds, would not have them. */
+export function gitIgnored(root, rels) {
+  if (!rels.length) return new Set();
+  const r = spawnSync('git', ['check-ignore', '--stdin'], { cwd: root, input: `${rels.join('\n')}\n`, encoding: 'utf8' });
+  if (r.status !== 0 && r.status !== 1) return new Set();
+  return new Set(String(r.stdout ?? '').split('\n').map((l) => l.trim()).filter(Boolean));
+}
+
+/**
+ * What `media move` would do, file by file: every public file of a published song or video (or exactly the files
+ * named), with its state:
+ *   move       it goes to R2 (over the size, git leaves it out, or it was named; or it changed since it went there)
+ *   r2         R2 already has these exact bytes (size and SHA-256 match the record)
+ *   site       it stays on the site (small enough, and in the repository)
+ *   media      it has a /media/<key> address from `media put` (left as it is)
+ *   too-big    over the 300 MiB one Wrangler upload takes
+ *   missing    not on this computer
+ *   unlisted   named, but in no manifest
+ */
+export function mediaPlan(root, { over = R2_OVER, paths = null } = {}) {
+  const want = paths ? new Set(paths.map((p) => { const abs = inside(root, relative(root, resolve(String(p)))); return abs ? relOf(root, abs) : String(p); })) : null;
+  const found = [];
+  const seen = new Set();
+  for (const kind of ['music', 'videos']) {
+    for (const item of readManifest(root, kind).items) {
+      if (!item || typeof item !== 'object') continue;
+      for (const f of Array.isArray(item.files) ? item.files : []) {
+        if (!f || f.public === false || typeof f.path !== 'string') continue;
+        const abs = inside(root, f.path);
+        if (!abs) continue;
+        const rel = relOf(root, abs);
+        if (seen.has(rel) || (want ? !want.has(rel) : item.published !== true)) continue;
+        seen.add(rel);
+        found.push({ kind, slug: item.slug ?? null, role: String(f.role ?? 'file'), path: rel, abs, type: f.type ?? typeOf(rel), f });
+      }
+    }
+  }
+  const ignored = gitIgnored(root, found.map((r) => r.path));
+  const rows = found.map(({ f, ...row }) => {
+    const held = heldOf(f);
+    if (typeof f.key === 'string' && f.key) return { ...row, state: 'media', why: `in R2 at /media/${f.key} since \`media put\`; left as it is` };
+    if (row.path.startsWith('players/')) return { ...row, state: 'site', why: 'players/ is the players\' own part of the bucket' };
+    const bytes = fileOf(row.abs);
+    if (bytes === null) return { ...row, state: held ? 'r2' : 'missing', bytes: held ? Number(held.bytes) : null, ...(held ? { held } : { why: 'not on this computer' }) };
+    const reason = want ? 'named' : over !== null && bytes > over ? `over ${lineOf(over)}` : ignored.has(row.path) ? 'git leaves it out of the repository' : null;
+    if (held && sameAsHeld(row.abs, held)) return { ...row, bytes, state: 'r2', held };
+    if (!reason && !held) return { ...row, bytes, state: 'site' };
+    if (bytes > MAX_PUT_BYTES) return { ...row, bytes, state: 'too-big', why: `${sizeOf(bytes)} is over the 300 MiB one Wrangler upload takes: make a smaller delivery (the video skill's cuts are far smaller), or upload it with an S3 tool and record it by hand` };
+    return { ...row, bytes, state: 'move', reason: held ? 'changed since it went to R2' : reason, ...(held ? { held } : {}) };
+  });
+  if (want) for (const p of want) if (!seen.has(p)) rows.push({ path: p, state: 'unlisted', why: 'not a public file of any entry in music/manifest.json or videos/manifest.json: add it to an entry first' });
+  return rows;
+}
+
+/** After R2 has the file and its SHA-256 matched: record it on every manifest file with that path. */
+export function recordMove(root, rel, { key, sha256, bytes, at = new Date().toISOString() }) {
+  const touched = [];
+  for (const kind of ['music', 'videos']) {
+    const m = readManifest(root, kind);
+    let hit = false;
+    for (const item of m.items) {
+      for (const f of Array.isArray(item?.files) ? item.files : []) {
+        const abs = typeof f?.path === 'string' ? inside(root, f.path) : null;
+        if (abs && relOf(root, abs) === rel) { f.bytes = bytes; f.r2 = { key, sha256, bytes, at }; hit = true; }
+      }
+    }
+    if (hit) { writeManifest(root, kind, m); touched.push(relative(root, manifestPath(root, kind))); }
+  }
+  return touched;
 }
 
 /** `homie-studio media put`: record an uploaded file's R2 key on the entry that names it (or a bare entry). */

package/lib/scaffold.mjs

@@ -9,7 +9,7 @@
  *   package.json         @homie-rocks/studio and wrangler, pinned
  *   games/<id>/          one folder per game (game.json, index.html, src/)
  *   music/ videos/       manifests in the repo; the big files go to the studio's own storage
- *                        (R2) once it is added with `homie-studio storage add`
+ *                        (R2) once it is added with `homie-studio storage add` (media move, deploy)
  *   posts/               the studio's news and drops (markdown; the site's Posts, with feeds)
  *   site/                the studio's Worker (pages, rooms), its look (theme.json), its D1 migrations (no R2
  *                        binding until the studio adds storage: a free Cloudflare account
@@ -105,7 +105,7 @@ directory lists its games; homie.rocks does not host them.
 | Path | What it is |
 | --- | --- |
 | \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`. |
-| \`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. |
+| \`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>/\`. Without storage the site serves each file itself (up to 25 MiB). Once the studio has storage (see below), its big media (over 1 MiB, or left out of git) lives in its own R2: every deploy uploads it, checks it by SHA-256 and serves it from R2 at the same address. Large files never go into git. The Homie plugin's \`music\` and \`video\` skills make them. |
 | \`posts/\` | The studio's news and drops: one markdown file each (\`posts/2026-09-30-we-are-live.md\`: \`title:\`, \`date:\`, \`summary:\`, and \`game:\` / \`song:\` / \`video:\` to link one). They are the site's Posts, with Atom and JSON feeds. |
 | \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`) and its D1 migrations. |
 | \`wrangler.jsonc\` | The Worker's Cloudflare config (the Worker, D1, the Table and Lobby Durable Objects, and \`previews\` for branch Previews), at the root, where Cloudflare's Workers Builds reads it. A studio made before 0.10.0 keeps it in \`site/\` and deploys from a computer; every command finds either. |
@@ -145,10 +145,16 @@ studio's pinned copy, never a registry lookup of the bare name.
   the D1 migrations and deploys (it never creates or refuses anything); on every other branch it runs
   \`npm run build\` and \`npx wrangler preview\`, a Preview URL with its own rooms. The live site claims itself
   in the homie.rocks directory the first time it is read, so nothing is stored by hand.
-- \`npx --no-install homie-studio storage add\` — only when the studio needs large media (songs,
-  videos): an R2 bucket for \`media put\`, served at \`/media/<key>\`. Cloudflare asks for a
-  payment method on the account before R2 works (its first 10 GB a month are free), so this
-  is a separate step the person agrees to; nothing else needs it.
+- \`npx --no-install homie-studio storage add\` — only when the studio has songs or videos: an R2
+  bucket on the studio's own Cloudflare account. Cloudflare asks for a payment method on the account
+  before R2 works, so this is a separate step the person agrees to; nothing else needs it. R2 has no
+  egress fees; storage is free up to 10 GB-month, then US$0.015 per GB-month.
+- \`npx --no-install homie-studio media move\` (\`--dry-run\` first) — with storage, the big files of
+  published songs and videos (over 1 MiB, or left out of git; studio.json \`media.r2Over\` changes the
+  size) go to R2: each is uploaded, read back and checked by SHA-256, and only then does the site stop
+  carrying it; it keeps its address, and the file stays in this folder. Every \`npm run deploy\` does
+  it too; once a file is in R2 (the committed manifest says so), a deploy from another computer or
+  Workers Builds still serves it. \`media list\` says where each file is served from.
 - \`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,
@@ -450,7 +456,7 @@ site/.wrangler/
 games/*/.port/
 # Screenshots from check and look runs.
 .checks/
-# Large media lives in this studio's storage (R2, after storage add) or is served by the site; the manifests beside it are committed.
+# Large media lives in this studio's storage (R2, after storage add: media move) or is served by the site; the manifests beside it (which name each file's R2 copy) are committed.
 # Working files of the music and video skills (frames, captures, provider answers) stay on this computer.
 music/**/work/
 videos/**/work/
@@ -504,9 +510,9 @@ export function studioFiles({ name, slug, homie, template = false }) {
     'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
     '.gitignore': GITIGNORE,
     'games/README.md': 'One folder per game. A new studio has none (its home page says "First game coming soon"). Start one with `npx --no-install homie-studio game new <id> --from gem-rush` when the person asks for a copy of the starter, or once their game is planned.\n',
-    'music/README.md': 'Songs, game scores, loops and stems, one folder each (`music/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/music/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
+    'music/README.md': 'Songs, game scores, loops and stems, one folder each (`music/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/music/<slug>/`. Without storage the site serves files up to 25 MiB itself. With storage (`npx --no-install homie-studio storage add`), the big ones live in the studio\'s R2: `npx --no-install homie-studio media move` and every deploy put them there, checked by SHA-256, at the same address. Never into git.\n',
     'music/manifest.json': '{ "v": 1, "items": [] }\n',
-    'videos/README.md': 'Trailers, music videos and cutscenes, one folder each (`videos/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/videos/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
+    'videos/README.md': 'Trailers, music videos and cutscenes, one folder each (`videos/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/videos/<slug>/`. Without storage the site serves files up to 25 MiB itself. With storage (`npx --no-install homie-studio storage add`), the big ones live in the studio\'s R2: `npx --no-install homie-studio media move` and every deploy put them there, checked by SHA-256, at the same address. Never into git.\n',
     'videos/manifest.json': '{ "v": 1, "items": [] }\n',
     'posts/README.md': POSTS_README,
     'site/theme.json': themeFile(slug),

package/lib/template-history.json

@@ -518,6 +518,34 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.18.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "eb1942414b8af7f8",
+     "## Commands (all through the pinned CLI in node_modules)": "9c51f189412e6a9f",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Servers and AI seats": "0a332b07e22d3fce",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/lib/upgrade.mjs

@@ -21,11 +21,16 @@
  * Without --apply it changes nothing and says what --apply would do: the person agrees first. It never touches
  * studio.json beyond `homie.studio`, the studio's look (site/theme.json), its Worker config (deploy's), its games,
  * media or posts.
+ *
+ * Media (0.18.0): the plan also says which songs and videos are big media (over studio.json media.r2Over, 1 MiB
+ * unless set, or left out of git), what is in the studio's R2 already, and the step that moves the rest
+ * (`media move`, which every deploy of a studio with storage also runs). Upgrade itself never moves a file.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
+import { R2_COST, mediaPlan, r2OverOf, sizeOf } from './media.mjs';
 import { studioFiles } from './scaffold.mjs';
 import { readStudio } from './studio.mjs';
 import { STUDIO_VERSION, packageSpec } from './version.mjs';
@@ -210,14 +215,36 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
 
   const git = spawnSync('git', ['status', '--porcelain'], { cwd: root, encoding: 'utf8' });
   const dirty = git.status === 0 ? git.stdout.split('\n').filter(Boolean).length : null;
+  const media = mediaNote(root, studio);
   return {
     ok: true, command: 'upgrade', applied: false, root, studio: name, from, to: STUDIO_VERSION,
     changes, kept,
+    ...(media ? { media } : {}),
     ...(dirty ? { uncommitted: dirty } : {}),
     next: changes.length ? ['npx --no-install homie-studio upgrade --apply   (after the person agrees)'] : [],
   };
 }
 
+/** What the studio's big media does from this version on: what R2 holds, what would go there, and the step that does it. */
+function mediaNote(root, studio) {
+  const cf = studio.cloudflare ?? {};
+  const storage = cf.r2 && (cf.created ?? []).includes(`r2:${cf.r2}`) ? cf.r2 : null;
+  const over = r2OverOf(studio);
+  let rows = [];
+  try { rows = mediaPlan(root, { over }); } catch { return null; }
+  const big = rows.filter((r) => r.state === 'move' || r.state === 'too-big').map(({ abs, held, ...r }) => r);
+  const inR2 = rows.filter((r) => r.state === 'r2').map(({ abs, held, ...r }) => r);
+  if (!big.length && !inR2.length) return null;
+  const bytes = big.reduce((n, r) => n + (r.bytes ?? 0), 0);
+  return {
+    storage, over, big, inR2,
+    next: !big.length ? null : storage
+      ? `npx --no-install homie-studio media move --dry-run, then media move (the next npm run deploy also does it): ${big.length} file(s), ${sizeOf(bytes)}, go to R2 ${storage}, each read back and checked by SHA-256 before the site stops carrying it; the addresses stay the same and the files stay in this folder. Upgrade itself moves nothing.`
+      : `no storage: these stay on the site (up to 25 MiB a file), and a deploy from another computer or Workers Builds leaves out any that git does not keep. With the person's agreement: npx --no-install homie-studio storage add (Cloudflare asks for a payment method on the account first), then media move.`,
+    cost: R2_COST,
+  };
+}
+
 function writeAtomic(path, text) {
   mkdirSync(dirname(path), { recursive: true });
   const tmp = `${path}.upgrade-${process.pid}`;

package/media/MEDIA.md

@@ -75,20 +75,71 @@ homie.rocks shows a cover only from the studio's own site, as a `.jpg`, `.png`,
 
 ## Where the bytes come from
 
-A studio needs no storage for songs and videos: the site serves them itself. For every public
-file of a published entry, the build picks the first that exists:
-
-1. `key`: the file is in the studio's storage, an R2 bucket that `homie-studio storage add`
-   creates (Cloudflare asks for a payment method on the account before R2 works, so the person
-   agrees first) and `homie-studio media put <file>` uploads to; the site serves it at
-   `/media/<key>`, with byte ranges so phones can seek.
-2. `path`: the file is in the studio folder; the build copies it into the site as `/<path>` when
-   it is 25 MiB or smaller (Cloudflare's limit for one static file), and the Worker answers byte
-   ranges for it too. This is the default, and it needs nothing but a deploy.
-3. `url`: an absolute `https://` address somewhere else.
-
-A file with none of these is left out and `media list` says so. Media never goes into git: the
-studio's `.gitignore` keeps `*.wav`, `*.mp3`, `*.flac`, `*.mp4`, `*.mov` and `*.webm` under
-`music/` and `videos/` out of the repository, so without storage the site is deployed from the
-computer that has the files. Keep deliveries under 25 MiB (the video skill's cuts do) or add
-storage for bigger ones.
+A new studio needs no storage for songs and videos: the site serves each file itself, up to 25 MiB
+a file (Cloudflare's limit for one static file of a Worker). Once the studio has storage, its big
+media lives in R2 instead. For every public file of a published entry, the build picks the first
+that applies:
+
+1. `r2`: the file is in the studio's own R2 bucket, put there by `homie-studio media move` (or a
+   deploy). The site serves it at **the same address it always had**, `/<path>` (for example
+   `/videos/trailer/trailer.mp4`), from R2, with byte ranges (206: phones seek with them, Safari needs
+   them to play a video at all), HEAD, an ETag and `If-None-Match` (304), and the same
+   `Cache-Control` as the site's own files (`public, max-age=0, must-revalidate`). A deploy's build
+   no longer carries the file in the site's static assets.
+2. `key`: a file `homie-studio media put` uploaded before 0.18.0 is served at `/media/<key>`, as it
+   always was (`media move` leaves it alone).
+3. `path`: the file is in the studio folder; the build copies it into the site as `/<path>` when it
+   is 25 MiB or smaller, and the Worker answers byte ranges for it too. This is the default, and it
+   needs nothing but a deploy.
+4. `url`: an absolute `https://` address somewhere else.
+
+A file with none of these is left out and `media list` says so.
+
+### Big media goes to R2, by default, once the studio has storage
+
+`homie-studio storage add` makes the studio's R2 bucket (one step the person agrees to: Cloudflare
+asks for a payment method on the account before R2 works, even inside its free tier). From then on,
+every `npm run deploy` first moves the studio's big media into it, and `homie-studio media move` does
+the same on its own:
+
+- **What moves:** every public file of a published song or video that is over 1 MiB, or that git
+  leaves out of the repository (`*.mp4`, `*.mp3`, `*.wav`… under `music/` and `videos/`, by the
+  studio's `.gitignore`). A deploy from another computer, or Cloudflare's Workers Builds, does not
+  have git-ignored files, so a file that is only on this computer would disappear from the site;
+  in R2 it stays. `studio.json` sets another size: `"media": { "r2Over": 5242880 }` (bytes), or
+  `"media": { "r2Over": false }` to move nothing on its own (`media move <file>` still moves the file
+  it names).
+- **How:** each file is hashed (SHA-256), uploaded with `wrangler r2 object put` to the key that is
+  its path, read back with `wrangler r2 object get --pipe` and hashed again. Only when the size and
+  the hash match does `media move` record it on the manifest's file:
+
+  ```json
+  { "role": "video", "path": "videos/trailer/trailer.mp4", "type": "video/mp4", "bytes": 45431041,
+    "r2": { "key": "videos/trailer/trailer.mp4", "sha256": "8efe9b96…", "bytes": 45431041, "at": "2026-10-02T03:00:00Z" } }
+  ```
+
+  A copy that comes back different is refused, nothing is recorded, and the file stays on the site.
+  The file on this computer is never deleted, moved or changed.
+- **After a re-cut** at the same path, the next `media move` or deploy sees a different hash and
+  uploads it again; until then a deploy's site carries the changed file itself when it fits.
+- **`media move --dry-run`** says what would move and calls nothing; **`media move --verify`** reads
+  every file R2 already holds back and checks its hash again.
+- **Local `dev`** still copies a moved file into the local site when it is 25 MiB or smaller,
+  because `wrangler dev`'s own R2 is empty; a bigger one does not play locally.
+
+**What it costs (Cloudflare's R2 pricing):** serving costs nothing in bandwidth (R2 has no egress
+fees). Storage is free up to 10 GB-month, then US$0.015 per GB-month; uploads (Class A operations)
+are free up to 1 million a month, reads (Class B) up to 10 million a month. A video served from R2
+costs one or two reads per byte range a player asks for. Beyond the free tier Cloudflare bills the
+studio's own account; `media move` and `media list` say how much the studio's media adds up to, and
+warn past 10 GB. Wrangler uploads at most 300 MiB in one go: a bigger file is refused with the
+reason (the video skill's deliveries are far smaller).
+
+Why not the site's own files for everything? A Worker's static files are at most 25 MiB each (and
+20,000 per version on the free plan); every deploy of a site carrying them uploads whichever
+changed; a byte range of a static file is cut out by the Worker after reading the whole file; and
+files git does not keep exist only on the computer that made them.
+
+Media never goes into git: the studio's `.gitignore` keeps `*.wav`, `*.mp3`, `*.flac`, `*.mp4`,
+`*.mov` and `*.webm` under `music/` and `videos/` out of the repository. Commit the manifests: they
+name each file's R2 copy, which is all a deploy from anywhere else needs.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.17.0",
-  "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, optional R2 storage for large media, deploy, and the homie.rocks directory.",
+  "version": "0.18.0",
+  "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
   "homepage": "https://homie.rocks/studio/",

package/worker/index.mjs

@@ -37,7 +37,10 @@
  *                              knocks for a Homie box, so it stops knocking (a studio site is not a box)
  *   /.well-known/homie-studio.json   what the homie.rocks directory reads
  *   /games/<id>/source.json    a public game's source for remixing, with its credit and licence (worker/license.mjs)
- *   /media/<key>               the studio's large media, from R2 (once `storage add` bound it), with byte ranges
+ *   /media/<key>               a loose file in the studio's R2 (`media put`), with byte ranges
+ *   /music/<slug>/<file>, /videos/<slug>/<file>   a song's or video's files: from the site's own files, or, for a
+ *                              file `media move` put in the studio's R2 (the catalogue names its key), from R2 at the
+ *                              same address, with byte ranges, HEAD, ETag and the site's own cache headers
  *   /api/stats                 the studio's numbers, for its owner only (a read key, or the owner's page session)
  *   /_studio/stats             the owner's private stats page (one-time sign-in link from `homie-studio stats link`)
  *   /_studio/office            the owner's back office: live rooms and who is in them, kick, mute, announce, close,
@@ -278,21 +281,50 @@ async function assetWithRange(request, env, url) {
   return new Response(body.subarray(r.start, r.end + 1), { status: 206, headers });
 }
 
-/** A file from the studio's R2 bucket, with byte ranges. */
-async function mediaObject(request, env, key) {
+/** Does an If-None-Match header name this ETag (or `*`)? Weak and strong forms compare alike for a GET. */
+function etagMatches(header, etag) {
+  if (!header || !etag) return false;
+  const bare = (t) => String(t).trim().replace(/^W\//, '');
+  return header.split(',').some((t) => t.trim() === '*' || bare(t) === bare(etag));
+}
+
+/**
+ * A file from the studio's R2 bucket, with byte ranges (206), HEAD, and If-None-Match (304).
+ * `cache`: the Cache-Control it is served with. /media/<key> keeps its hour; a song or video served at its own
+ * address (media move) gets exactly what the site's static files get, `public, max-age=0, must-revalidate` with an
+ * ETag, so moving a file to R2 changes nothing a browser or a phone sees. `type`: the catalogue's type, for an
+ * object stored without one.
+ */
+async function mediaObject(request, env, key, { cache = 'public, max-age=3600', type = null } = {}) {
   const range = request.headers.get('range');
+  const inm = request.headers.get('if-none-match');
+  const headOnly = request.method === 'HEAD';
   let head = null;
-  if (range) head = await env.MEDIA.head(key);
-  if (range && !head) return new Response('not found', { status: 404 });
-  const r = head ? parseRange(range, head.size) : null;
-  if (r?.unsatisfiable) return new Response(null, { status: 416, headers: { 'content-range': `bytes */${head.size}` } });
+  if (range || inm || headOnly) {
+    head = await env.MEDIA.head(key);
+    if (!head) return new Response('not found', { status: 404 });
+  }
+  const base = (obj) => {
+    const headers = new Headers();
+    obj.writeHttpMetadata?.(headers);
+    if (!headers.get('content-type') && type) headers.set('content-type', type);
+    if (obj.httpEtag) headers.set('etag', obj.httpEtag);
+    if (obj.uploaded) headers.set('last-modified', new Date(obj.uploaded).toUTCString());
+    headers.set('cache-control', cache);
+    headers.set('accept-ranges', 'bytes');
+    return headers;
+  };
+  if (head && inm && etagMatches(inm, head.httpEtag)) return new Response(null, { status: 304, headers: base(head) });
+  const r = head && range ? parseRange(range, head.size) : null;
+  if (r?.unsatisfiable) return new Response(null, { status: 416, headers: { 'content-range': `bytes */${head.size}`, 'accept-ranges': 'bytes' } });
+  if (headOnly) {
+    const headers = base(head);
+    headers.set('content-length', String(head.size));
+    return new Response(null, { headers });
+  }
   const obj = await env.MEDIA.get(key, r ? { range: { offset: r.start, length: r.end - r.start + 1 } } : undefined);
   if (!obj) return new Response('not found', { status: 404 });
-  const headers = new Headers();
-  obj.writeHttpMetadata(headers);
-  headers.set('etag', obj.httpEtag);
-  headers.set('cache-control', 'public, max-age=3600');
-  headers.set('accept-ranges', 'bytes');
+  const headers = base(obj);
   if (r) {
     headers.set('content-range', `bytes ${r.start}-${r.end}/${head.size}`);
     headers.set('content-length', String(r.end - r.start + 1));
@@ -302,6 +334,30 @@ async function mediaObject(request, env, key) {
   return new Response(obj.body, { headers });
 }
 
+/** The same Cache-Control the site's static files are served with (Workers static assets' default). */
+const ASSET_CACHE = 'public, max-age=0, must-revalidate';
+
+/**
+ * A song's or video's file that `media move` put in R2, by the address it always had (/music/<slug>/x.mp3,
+ * /videos/<slug>/x.mp4): the catalogue names its key (`r2`). Only files the catalogue lists as public are served this
+ * way, never any other key of the bucket.
+ */
+async function heldInR2(env, getCat, path) {
+  if (!env.MEDIA) return null;
+  const cat = await getCat();
+  let want;
+  try { want = decodeURIComponent(path); } catch { return null; }
+  for (const e of [...(cat.songs ?? []), ...(cat.videos ?? [])]) {
+    for (const f of e.files ?? []) {
+      if (typeof f.r2 !== 'string' || !f.r2 || f.r2.startsWith('players/') || typeof f.url !== 'string') continue;
+      let at;
+      try { at = decodeURIComponent(f.url); } catch { continue; }
+      if (at === want) return f;
+    }
+  }
+  return null;
+}
+
 /**
  * A catalogue media row as the directory reads it (absolute addresses). A song's cover (a video's poster) is its
  * own, else the manifest's default, else the landing still of the game it was made for (site.mjs mediaArt).
@@ -617,7 +673,12 @@ async function route(request, env, ctx) {
     }
     if (parts.some((p) => p === '..')) return notFoundPage('Nothing here.', cat);
     const file = await assetWithRange(request, env, url);
-    if (file.status === 404) return notFoundPage('Nothing here.', cat);
+    if (file.status === 404) {
+      // Not in the site's files: a song's or video's file that lives in the studio's R2 (media move), same address.
+      const held = await heldInR2(env, getCat, path);
+      if (held) return mediaObject(request, env, held.r2, { cache: ASSET_CACHE, type: held.type ?? null });
+      return notFoundPage('Nothing here.', cat);
+    }
     return file;
   }
   if (path === '/' || path === '/index.html') {
@@ -928,7 +989,12 @@ async function weekOf(env, game) {
 /** Everything else is a file of the built site (site/public, the games' files), with byte ranges for media. */
 async function fallback(request, env, url, getCat) {
   const asset = MEDIA_FILE.test(url.pathname) && request.headers.get('range') ? await assetWithRange(request, env, url) : await env.ASSETS.fetch(request);
-  if (asset.status === 404) return notFoundPage('Nothing here.', await getCat());
+  if (asset.status === 404) {
+    // A manifest file outside music/ and videos/ that media move put in R2 keeps its address too.
+    const held = (request.method === 'GET' || request.method === 'HEAD') ? await heldInR2(env, getCat, url.pathname) : null;
+    if (held) return mediaObject(request, env, held.r2, { cache: ASSET_CACHE, type: held.type ?? null });
+    return notFoundPage('Nothing here.', await getCat());
+  }
   return asset;
 }
 

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.17.0';
+export const STUDIO_VERSION_TAG = '0.18.0';