@homie-rocks/studio 0.3.0 → 0.6.0

package/lib/cloudflare.mjs

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

package/lib/directory.mjs

@@ -4,12 +4,12 @@
  * claim the directory gave it (`homie-studio deploy` stores it in D1), so
  * nobody can list games under someone else's site.
  */
-import { readStudio } from './studio.mjs';
+import { readStudio, siteUrl } from './studio.mjs';
 
 export async function publish(root, { homie, site } = {}) {
   const studio = readStudio(root);
   const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
-  const url = site || studio.cloudflare?.url;
+  const url = site || siteUrl(root, studio);
   if (!url) return { ok: false, command: 'publish', why: 'this studio has no live site yet: run `npm run deploy` first' };
   const res = await fetch(`${directory}/api/studio/publish`, {
     method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ site: url }),

package/lib/media.mjs

@@ -0,0 +1,126 @@
+/**
+ * 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).
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, 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}$/;
+export const KINDS = {
+  music: ['song', 'score', 'loop', 'stem', 'sfx'],
+  videos: ['trailer', 'music-video', 'cutscene', 'clip'],
+};
+/** Cloudflare Workers static assets: one file may be at most 25 MiB. */
+export const MAX_ASSET_BYTES = 25 * 1024 * 1024;
+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',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.webp': 'image/webp', '.vtt': 'text/vtt', '.json': 'application/json',
+};
+export const typeOf = (path) => TYPES[(/\.[a-z0-9]+$/i.exec(String(path)) ?? [''])[0].toLowerCase()] ?? 'application/octet-stream';
+
+export function manifestPath(root, kind) { return join(root, kind, 'manifest.json'); }
+
+export function readManifest(root, kind) {
+  const file = manifestPath(root, kind);
+  if (!existsSync(file)) return { v: 1, items: [] };
+  const m = JSON.parse(readFileSync(file, 'utf8'));
+  return { v: 1, ...m, items: Array.isArray(m.items) ? m.items : [] };
+}
+
+export function writeManifest(root, kind, manifest) {
+  mkdirSync(join(root, kind), { recursive: true });
+  writeFileSync(manifestPath(root, kind), `${JSON.stringify({ v: 1, ...manifest }, null, 2)}\n`);
+}
+
+/** A path inside the studio, or null (no absolute paths, no `..` out of the repository). */
+function inside(root, rel) {
+  if (typeof rel !== 'string' || !rel || rel.startsWith('/') || /^[a-z]+:/i.test(rel)) return null;
+  const abs = resolve(root, normalize(rel));
+  return abs.startsWith(`${resolve(root)}${sep}`) ? abs : null;
+}
+
+/**
+ * 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>).
+ */
+export function resolveMedia(root, kind, { r2 = false } = {}) {
+  const manifest = readManifest(root, kind);
+  const entries = [];
+  const skipped = [];
+  const seen = new Set();
+  for (const item of manifest.items) {
+    if (!item || typeof item !== 'object') continue;
+    const label = item.slug ?? item.key ?? item.file ?? '(unnamed)';
+    if (!SLUG.test(String(item.slug ?? '')) || !item.title) { if (item.published !== false) skipped.push({ kind, item: label, why: 'no slug and title: kept in the manifest, no page' }); continue; }
+    if (seen.has(item.slug)) { skipped.push({ kind, item: label, why: 'a second entry with the same slug' }); continue; }
+    seen.add(item.slug);
+    if (item.published !== true) { skipped.push({ kind, item: label, why: 'not published yet ("published": true shows it)' }); continue; }
+    const files = [];
+    for (const f of Array.isArray(item.files) ? item.files : []) {
+      if (!f || f.public === false) continue;
+      let src = null;
+      if (typeof f.key === 'string' && f.key && r2) src = { from: 'r2', url: `/media/${f.key.split('/').map(encodeURIComponent).join('/')}` };
+      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' });
+      }
+      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 } : {}) });
+    }
+    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; }
+    entries.push({
+      slug: item.slug, kind: KINDS[kind].includes(item.kind) ? item.kind : KINDS[kind][0], title: String(item.title).slice(0, 120), blurb: String(item.blurb ?? '').slice(0, 600),
+      duration: Number.isFinite(item.duration) ? item.duration : null, bpm: Number.isFinite(item.bpm) ? item.bpm : null, key: item.key ?? null,
+      lyrics: typeof item.lyrics === 'string' ? item.lyrics.slice(0, 8000) : null, credits: typeof item.credits === 'string' ? item.credits.slice(0, 600) : null,
+      rights: item.rights && typeof item.rights === 'object' ? item.rights : null, for: item.for && typeof item.for === 'object' ? item.for : null,
+      honesty: typeof item.honesty === 'string' ? item.honesty.slice(0, 600) : null, made: item.made?.at ? { at: item.made.at, provider: item.made.provider ?? null } : null,
+      files,
+    });
+  }
+  return { entries, skipped };
+}
+
+/** 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 = () => {} } = {}) {
+  const out = {};
+  const skipped = [];
+  for (const kind of ['music', 'videos']) {
+    const r = resolveMedia(root, kind, { r2 });
+    skipped.push(...r.skipped);
+    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); }
+        return f;
+      }),
+    }));
+    if (out[kind].length) log(`${kind}: ${out[kind].map((e) => e.slug).join(', ')}`);
+  }
+  for (const s of skipped) log(`${s.kind}/${s.item}${s.file ? ` ${s.file}` : ''}: ${s.why}`);
+  return { songs: out.music, videos: out.videos, skipped };
+}
+
+/** `homie-studio media put`: record an uploaded file's R2 key on the entry that names it (or a bare entry). */
+export function recordUpload(root, rel, key, bytes) {
+  const kind = rel.startsWith('videos/') ? 'videos' : 'music';
+  const m = readManifest(root, kind);
+  let hit = false;
+  for (const item of m.items) {
+    for (const f of Array.isArray(item?.files) ? item.files : []) {
+      if (f.path === rel) { f.key = key; f.bytes = bytes; hit = true; }
+    }
+  }
+  if (!hit) m.items = [...m.items.filter((i) => i.key !== key), { key, file: rel, bytes, url: `/media/${key.split('/').map(encodeURIComponent).join('/')}`, at: new Date().toISOString() }];
+  writeManifest(root, kind, m);
+  return { kind, manifest: relative(root, manifestPath(root, kind)), entry: hit };
+}