@homie-rocks/studio 0.17.0 → 0.18.1

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

@@ -8,6 +8,9 @@
  *                                  Homie tools are there: --connector yes|no)
  *   Cloudflare         to go online: signed in, and the account's email verified (Cloudflare checks that at the
  *                                  first deploy; a deploy that went through proves it)
+ *   Workers AI         for AI guides  only when a server's guides think with Workers AI: the model they use
+ *                                  (HOMIE_BRAIN_MODEL, else the default) answers on the studio's account, not paid-only
+ *                                  or retired (lib/brain-probe.mjs: one tiny call, about 0.1 of the free daily neurons)
  *   Chrome             for checks  the two-browser check, the look pictures and playtests
  *   ffmpeg             recommended sound effects and the theme, trailers and hero footage
  *   GitHub             optional    a private backup, publishing by pull request, building from the Claude app
@@ -17,12 +20,14 @@
  *
  * It is safe at any time, inside a studio or before one exists: it only reads (local files, `--version` of a few
  * tools, `wrangler whoami`, `gh auth status`, `elevenlabs auth status`, one GET to the directory and, when a fal key
- * is set, fal's free pricing API), never changes anything, and never prints a key, a token or an account's name.
+ * is set, fal's free pricing API; when a server's AI guides use Workers AI, one read of the live database and one
+ * one-word call to the model), never changes anything, and never prints a key, a token or an account's name or id.
  * Every check has a time limit, so it answers in seconds even with no network.
  */
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { workersAiRow } from './brain-probe.mjs';
 import { findChrome } from './chrome.mjs';
 import { whyFailed } from './net.mjs';
 import { isOurs } from './statusline.mjs';
@@ -98,7 +103,8 @@ export async function setupStatus({
       if (!bin || !existsSync(bin)) return { signedIn: null };
       const r = await exec(bin, ['whoami', '--json'], { cwd: root, timeout: 25_000, env: { ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' } });
       if (r.code === 124) return { signedIn: null, why: 'Wrangler did not answer in time' };
-      try { const d = JSON.parse(r.stdout.slice(Math.max(0, r.stdout.indexOf('{')))); return { signedIn: Boolean(d.loggedIn), accounts: Array.isArray(d.accounts) ? d.accounts.length : null }; } catch { return { signedIn: false }; }
+      // The accounts' ids stay in this process (the Workers AI row calls the studio's own account); never printed.
+      try { const d = JSON.parse(r.stdout.slice(Math.max(0, r.stdout.indexOf('{')))); return { signedIn: Boolean(d.loggedIn), accounts: Array.isArray(d.accounts) ? d.accounts.length : null, accountIds: Array.isArray(d.accounts) ? d.accounts.map((a) => a?.id).filter(Boolean) : [] }; } catch { return { signedIn: false }; }
     })(),
     (async () => {
       const git = await exec('git', ['--version']);
@@ -182,6 +188,15 @@ export async function setupStatus({
     });
   }
 
+  // Workers AI, only when a server's AI guides think with it: does the model they use answer on this account?
+  {
+    const local = root ? readLocal(root) : {};
+    const live = Boolean(local.deployedAt || local.connectedAt || (studio?.cloudflare?.created ?? []).some((c) => String(c).startsWith('worker:')));
+    const bin = root ? join(root, 'node_modules', '.bin', win ? 'wrangler.cmd' : 'wrangler') : null;
+    const row = root ? await workersAiRow({ root, studio, env, exec, fetchFn, who, bin, remote: live && Boolean(who.signedIn || env.CLOUDFLARE_API_TOKEN), cli }) : null;
+    if (row) rows.push(row);
+  }
+
   // Chrome, for the checks.
   {
     const found = chrome();
@@ -254,6 +269,7 @@ export async function setupStatus({
     { feature: 'Backup and pull requests', state: ready(by.github.state), needs: ['github'] },
     { feature: 'Songs and game scores', state: ready(by.elevenlabs.state), needs: ['elevenlabs'] },
     { feature: 'Painted art and generated video', state: ready(by.fal.state), needs: ['fal'] },
+    ...(by['workers-ai'] ? [{ feature: 'AI guides that think (Workers AI)', state: ready(by['workers-ai'].state), needs: ['workers-ai'] }] : []),
   ];
   const now = rows.filter((r) => ['missing', 'act'].includes(r.state) && r.fix);
   const meanwhile = rows.filter((r) => r.fix?.open && r.state !== 'ok' && (r.fix.who === 'person' || r.state === 'later'));

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),