@homie-rocks/studio 0.8.0 → 0.10.0

package/lib/studio.mjs

@@ -26,6 +26,17 @@ export function requireStudio(from) {
   return root;
 }
 
+/*
+ * WHERE THE WORKER'S CONFIG LIVES. From 0.10.0 a new studio keeps `wrangler.jsonc` at its root, which is what
+ * Cloudflare's Workers Builds and its "Deploy to Cloudflare" button read (they run the studio's own `npm run build`
+ * and `npm run deploy` at the repository's root). A studio made before 0.10.0 keeps `site/wrangler.jsonc`; every
+ * command runs Wrangler next to whichever the studio has, so both keep working.
+ */
+export function workerDir(root) { return existsSync(join(root, 'wrangler.jsonc')) || !existsSync(join(root, 'site', 'wrangler.jsonc')) ? root : join(root, 'site'); }
+export function configPath(root) { return join(workerDir(root), 'wrangler.jsonc'); }
+/** 'root' (0.10.0 and later: Workers Builds ready) or 'site' (older studios). */
+export function layoutOf(root) { return workerDir(root) === root ? 'root' : 'site'; }
+
 export function readStudio(root) { return JSON.parse(readFileSync(join(root, 'studio.json'), 'utf8')); }
 export function writeStudio(root, studio) { writeFileSync(join(root, 'studio.json'), `${JSON.stringify(studio, null, 2)}\n`); }
 

package/lib/template-history.json

@@ -0,0 +1,180 @@
+{
+ "v": 1,
+ "about": "Fingerprints of every studio template version (scripts/studio-template-history.mjs): homie-studio upgrade replaces a file or an AGENTS.md section only when it is exactly one of these.",
+ "versions": {
+  "0.2.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "fd3d904cfa5b39d9",
+    "videos/README.md": "0546814c9382b601",
+    "posts/README.md": "ef1a30b0d7aa77bd",
+    "site/src/worker.mjs": "70148970cf81d685"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "9ecc7809a3b9b4f7",
+     "## Layout": "1829a9bfb106455b",
+     "## Commands (all through the pinned CLI in node_modules)": "000952727c257f96",
+     "## Making games": "a4c11a533a03391f",
+     "## Rules": "d9da1f3e572199f6"
+    }
+   }
+  },
+  "0.3.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "fd3d904cfa5b39d9",
+    "videos/README.md": "0546814c9382b601",
+    "posts/README.md": "ef1a30b0d7aa77bd",
+    "site/src/worker.mjs": "70148970cf81d685"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "9ecc7809a3b9b4f7",
+     "## Layout": "1829a9bfb106455b",
+     "## Commands (all through the pinned CLI in node_modules)": "583e8fd0eece6f76",
+     "## Making games": "a4c11a533a03391f",
+     "## Rules": "d9da1f3e572199f6"
+    }
+   }
+  },
+  "0.5.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "ef1a30b0d7aa77bd",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f8e01e41892420d3",
+     "## Commands (all through the pinned CLI in node_modules)": "dff7046dac113123",
+     "## Making games": "a4c11a533a03391f",
+     "## Rules": "d9da1f3e572199f6",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.6.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "ef1a30b0d7aa77bd",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "b2af4e6842972cbd",
+     "## Commands (all through the pinned CLI in node_modules)": "3849a47e757f544a",
+     "## Making games": "a4c11a533a03391f",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.7.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "0fd152a20a3eb55f",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "b5f801e112d163a9",
+     "## Commands (all through the pinned CLI in node_modules)": "3849a47e757f544a",
+     "## The site": "e174cd30932df888",
+     "## Making games": "a4c11a533a03391f",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.8.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "0fd152a20a3eb55f",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "b5f801e112d163a9",
+     "## Commands (all through the pinned CLI in node_modules)": "3849a47e757f544a",
+     "## The site": "e174cd30932df888",
+     "## Making games": "a4c11a533a03391f",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.9.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "0fd152a20a3eb55f",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "b5f801e112d163a9",
+     "## Commands (all through the pinned CLI in node_modules)": "63833b7006efdef4",
+     "## The site": "7d3525ba39b7f262",
+     "## Making games": "c204473d9b468f49",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.10.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "2af7c804c1e81d86",
+     "## The site": "7d3525ba39b7f262",
+     "## Making games": "c204473d9b468f49",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  }
+ }
+}

package/lib/upgrade.mjs

@@ -0,0 +1,285 @@
+/**
+ * `homie-studio upgrade [--apply] [--diff]` — an existing studio takes what this version's template adds, and
+ * nothing it made its own is ever overwritten.
+ *
+ * `homie-studio new` writes a studio's first files (lib/scaffold.mjs). A studio made on an older version keeps its
+ * old ones: its AGENTS.md lacks the sections the template grew since (the site, the room button, how to upgrade),
+ * a README it never touched is out of date, its .gitignore misses lines. This command compares the studio with
+ * what this version would write for it, and sorts every difference:
+ *
+ *   added      a file, an AGENTS.md section, a .gitignore line or a package.json script the studio does not have;
+ *   updated    a file or an AGENTS.md section the studio never changed since an older template wrote it (its text
+ *              is exactly an earlier version's: lib/template-history.json keeps a fingerprint of every one), so the
+ *              template's newer text replaces it;
+ *   kept       anything the studio changed, or wrote itself: never touched. The plan says it differs, and
+ *              `--diff` prints the difference, so the person can take the template's words by hand.
+ *
+ * Plus the pin: when this CLI is newer than the version package.json pins (run through
+ * `npx -y --package=<the new tarball> homie-studio upgrade`), --apply pins this version (then `npm install`), and
+ * studio.json's `homie.studio` says the version the studio is on.
+ *
+ * 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.
+ */
+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 { studioFiles } from './scaffold.mjs';
+import { readStudio } from './studio.mjs';
+import { STUDIO_VERSION, packageSpec } from './version.mjs';
+
+/** Whole files the template writes and a studio may keep as they are: updated only while the studio never changed them. */
+export const TEMPLATE_FILES = ['AGENTS.md', 'CLAUDE.md', 'README.md', 'games/README.md', 'music/README.md', 'videos/README.md', 'posts/README.md', 'site/README.md', 'site/src/worker.mjs'];
+/** Files the template adds when missing and never changes once they exist (a migration is applied; a manifest is the studio's). */
+export const ADD_ONLY = ['music/manifest.json', 'videos/manifest.json', '.claude/skills/.gitkeep'];
+const MIGRATIONS = /^site\/migrations\/[^/]+\.sql$/;
+/** The name and slug stand-ins the history is fingerprinted with. */
+export const STAND_IN = { name: '{{studio.name}}', slug: '{{studio.slug}}' };
+const INTRO = '(intro)';
+
+/** A text as the template compares it: line ends, trailing spaces and the studio's own name and slug made neutral. */
+export function normalize(text, { name = null, slug = null } = {}) {
+  let t = String(text ?? '').replace(/\r\n?/g, '\n').split('\n').map((l) => l.replace(/[ \t]+$/, '')).join('\n').trim();
+  if (name && name !== STAND_IN.name) t = t.split(name).join(STAND_IN.name);
+  if (slug && slug !== STAND_IN.slug) t = t.split(slug).join(STAND_IN.slug);
+  return t;
+}
+export const fingerprint = (text, who = {}) => createHash('sha256').update(normalize(text, who)).digest('hex').slice(0, 16);
+
+/** AGENTS.md as its sections: the intro (the title and the lines before the first `## `), then each `## ` heading's. */
+export function sections(text) {
+  const out = [];
+  let cur = { heading: INTRO, lines: [] };
+  for (const line of String(text ?? '').replace(/\r\n?/g, '\n').split('\n')) {
+    if (/^## /.test(line)) { out.push(cur); cur = { heading: line.trim(), lines: [line] }; } else cur.lines.push(line);
+  }
+  out.push(cur);
+  return out.map((s) => ({ heading: s.heading, text: s.lines.join('\n') })).filter((s, i) => i > 0 || s.text.trim());
+}
+
+/** What the history keeps of one template: a fingerprint of every whole file and every AGENTS.md section. */
+export function templatePrint(files) {
+  const who = STAND_IN;
+  return {
+    files: Object.fromEntries(TEMPLATE_FILES.filter((f) => f !== 'AGENTS.md' && files[f] !== undefined).map((f) => [f, fingerprint(files[f], who)])),
+    sections: { 'AGENTS.md': Object.fromEntries(sections(files['AGENTS.md']).map((s) => [s.heading, fingerprint(s.text, who)])) },
+  };
+}
+
+export function readHistory() {
+  try { return JSON.parse(readFileSync(new URL('./template-history.json', import.meta.url), 'utf8')); } catch { return { v: 1, versions: {} }; }
+}
+
+/** Every fingerprint an older template wrote, per file and per AGENTS.md section. */
+function known(history) {
+  const files = new Map();
+  const secs = new Map();
+  for (const v of Object.values(history.versions ?? {})) {
+    // A version may hold more than one hash for a file (two templates published under it): a list.
+    for (const [f, h] of Object.entries(v.files ?? {})) for (const x of [h].flat()) (files.get(f) ?? files.set(f, new Set()).get(f)).add(x);
+    for (const [heading, h] of Object.entries(v.sections?.['AGENTS.md'] ?? {})) for (const x of [h].flat()) (secs.get(heading) ?? secs.set(heading, new Set()).get(heading)).add(x);
+  }
+  return { files, secs };
+}
+
+const semver = (v) => (/^(\d+)\.(\d+)\.(\d+)$/.exec(String(v ?? '')) ?? []).slice(1).map(Number);
+const newer = (a, b) => { const x = semver(a); const y = semver(b); for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0); return false; };
+
+/** The @homie-rocks/studio version a package.json spec pins: a homie.rocks tarball, an exact version, or npm:… of one. */
+export function pinnedVersion(spec) {
+  const s = String(spec ?? '');
+  return /homie-studio-(\d+\.\d+\.\d+)\.tgz(?:[?#].*)?$/.exec(s)?.[1] ?? /^(?:npm:@homie-rocks\/studio@)?=?(\d+\.\d+\.\d+)$/.exec(s)?.[1] ?? null;
+}
+/** The same kind of spec, for this version. */
+function specFor(spec, directory) {
+  const s = String(spec ?? '');
+  const tar = /^(https?:\/\/.+\/)homie-studio-\d+\.\d+\.\d+\.tgz$/.exec(s);
+  if (tar) return `${tar[1]}homie-studio-${STUDIO_VERSION}.tgz`;
+  if (/^npm:@homie-rocks\/studio@/.test(s)) return `npm:@homie-rocks/studio@${STUDIO_VERSION}`;
+  if (/^=?\d+\.\d+\.\d+$/.test(s)) return STUDIO_VERSION;
+  return packageSpec(directory);
+}
+
+/** A line diff (the longest common run kept), for the plan: `  ` same, `- ` the studio's, `+ ` the template's. */
+export function lineDiff(a, b, { context = 2, max = 60 } = {}) {
+  const x = String(a ?? '').split('\n');
+  const y = String(b ?? '').split('\n');
+  const n = x.length; const m = y.length;
+  const L = Array.from({ length: n + 1 }, () => new Uint16Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) L[i][j] = x[i] === y[j] ? L[i + 1][j + 1] + 1 : Math.max(L[i + 1][j], L[i][j + 1]);
+  const rows = [];
+  let i = 0; let j = 0;
+  while (i < n || j < m) {
+    if (i < n && j < m && x[i] === y[j]) { rows.push(['  ', x[i]]); i++; j++; } else if (i < n && (j >= m || L[i + 1][j] >= L[i][j + 1])) { rows.push(['- ', x[i]]); i++; } else { rows.push(['+ ', y[j]]); j++; }
+  }
+  // Only the changed lines and a little context around them.
+  const keep = rows.map((r, k) => r[0] !== '  ' || rows.slice(Math.max(0, k - context), k + context + 1).some((q) => q[0] !== '  '));
+  const out = [];
+  let skipped = false;
+  rows.forEach((r, k) => { if (keep[k]) { out.push(`${r[0]}${r[1]}`); skipped = false; } else if (!skipped) { out.push('  …'); skipped = true; } });
+  return out.length > max ? [...out.slice(0, max), `  … (${out.length - max} more lines)`] : out;
+}
+
+const read = (root, rel) => { try { return readFileSync(join(root, rel), 'utf8'); } catch { return null; } };
+
+/** The plan: every change --apply would make, and everything it keeps as the studio wrote it. */
+export function upgradePlan(root, { history = readHistory() } = {}) {
+  const studio = readStudio(root);
+  const name = String(studio.name ?? '').trim();
+  const slug = String(studio.slug ?? '').trim();
+  if (!name || !slug) return { ok: false, command: 'upgrade', why: 'studio.json has no name or slug; this does not look like a studio made with homie-studio new' };
+  const who = { name, slug };
+  const tmpl = studioFiles({ name, slug, homie: studio.homie?.directory ?? 'https://homie.rocks' });
+  const { files: oldFiles, secs: oldSecs } = known(history);
+  const changes = [];
+  const kept = [];
+
+  // package.json: the pin, and the scripts the template's studios have.
+  let pkg = null;
+  try { pkg = JSON.parse(read(root, 'package.json') ?? 'null'); } catch { pkg = null; }
+  const where = pkg?.devDependencies?.['@homie-rocks/studio'] !== undefined ? 'devDependencies' : pkg?.dependencies?.['@homie-rocks/studio'] !== undefined ? 'dependencies' : null;
+  const spec = where ? pkg[where]['@homie-rocks/studio'] : null;
+  const pinned = pinnedVersion(spec);
+  const from = pinned ?? studio.homie?.studio ?? null;
+  if (pinned && newer(pinned, STUDIO_VERSION)) {
+    return { ok: false, command: 'upgrade', from: pinned, to: STUDIO_VERSION, why: `this studio pins @homie-rocks/studio ${pinned}, newer than this ${STUDIO_VERSION}: run its own copy (npx --no-install homie-studio upgrade)` };
+  }
+  if (pkg && where && pinned && newer(STUDIO_VERSION, pinned)) {
+    changes.push({ file: 'package.json', kind: 'pin', what: `pin @homie-rocks/studio ${STUDIO_VERSION} (was ${pinned}); then npm install`, from: spec, to: specFor(spec, studio.homie?.directory) });
+  } else if (pkg && where && !pinned) {
+    kept.push({ file: 'package.json', what: `@homie-rocks/studio is "${String(spec).slice(0, 80)}" (not a published version): left as it is` });
+  }
+  const wantScripts = JSON.parse(tmpl['package.json']).scripts ?? {};
+  const missingScripts = pkg ? Object.fromEntries(Object.entries(wantScripts).filter(([k]) => pkg.scripts?.[k] === undefined)) : {};
+  if (Object.keys(missingScripts).length) changes.push({ file: 'package.json', kind: 'scripts', what: `add scripts: ${Object.keys(missingScripts).join(', ')}`, scripts: missingScripts });
+  if (studio.homie?.studio !== STUDIO_VERSION) changes.push({ file: 'studio.json', kind: 'version', what: `homie.studio ${studio.homie?.studio ?? '(none)'} → ${STUDIO_VERSION}`, to: STUDIO_VERSION });
+
+  // AGENTS.md, section by section; the other template files whole.
+  for (const rel of TEMPLATE_FILES) {
+    const mine = read(root, rel);
+    const want = tmpl[rel];
+    if (want === undefined) continue;
+    if (mine === null) { changes.push({ file: rel, kind: 'add-file', what: 'new file', text: want }); continue; }
+    if (normalize(mine, who) === normalize(want, who)) continue;
+    if (rel !== 'AGENTS.md') {
+      if (oldFiles.get(rel)?.has(fingerprint(mine, who))) changes.push({ file: rel, kind: 'update-file', what: 'the template\'s newer text (the studio never changed it)', from: mine, text: want });
+      else kept.push({ file: rel, what: rel === 'site/src/worker.mjs' ? 'the studio\'s own Worker' : 'changed by the studio', mine, template: want });
+      continue;
+    }
+    const have = sections(mine);
+    const tsecs = sections(want);
+    for (const [k, t] of tsecs.entries()) {
+      const at = have.find((s) => s.heading === t.heading);
+      if (!at) {
+        // After the nearest template section before it that the studio has; else before the first one after it.
+        const before = tsecs.slice(0, k).reverse().find((p) => have.some((s) => s.heading === p.heading));
+        const after = before ? null : tsecs.slice(k + 1).find((p) => have.some((s) => s.heading === p.heading));
+        changes.push({ file: rel, kind: 'add-section', section: t.heading, what: `new section ${t.heading === INTRO ? 'intro' : `"${t.heading}"`}`, after: before?.heading ?? null, before: after?.heading ?? null, text: t.text });
+        continue;
+      }
+      if (normalize(at.text, who) === normalize(t.text, who)) continue;
+      if (oldSecs.get(t.heading)?.has(fingerprint(at.text, who))) changes.push({ file: rel, kind: 'update-section', section: t.heading, what: `section "${t.heading}": the template's newer text (the studio never changed it)`, from: at.text, text: t.text });
+      else kept.push({ file: rel, section: t.heading, what: `section "${t.heading}": changed by the studio`, mine: at.text, template: t.text });
+    }
+  }
+
+  // Files added only when missing: the empty manifests, the skills folder, and any D1 migration the template has.
+  for (const rel of [...ADD_ONLY, ...Object.keys(tmpl).filter((f) => MIGRATIONS.test(f))]) {
+    if (tmpl[rel] !== undefined && read(root, rel) === null) changes.push({ file: rel, kind: 'add-file', what: MIGRATIONS.test(rel) ? 'D1 migration (the next deploy applies it)' : 'new file', text: tmpl[rel] });
+  }
+
+  // .gitignore: every pattern the template ignores and the studio does not, with the comment lines above it.
+  const gi = read(root, '.gitignore');
+  const bare = (l) => l.trim().replace(/^\//, '').replace(/\/$/, '');
+  const have = new Set((gi ?? '').split('\n').map(bare).filter((l) => l && !l.startsWith('#')));
+  const add = [];
+  let notes = [];
+  for (const line of tmpl['.gitignore'].split('\n')) {
+    if (!line.trim()) { notes = []; continue; }
+    if (line.trim().startsWith('#')) { notes.push(line); continue; }
+    // A pattern's comment lines are the ones right above it (they go with the first missing pattern below them).
+    if (!have.has(bare(line))) add.push(...notes, line);
+    notes = [];
+  }
+  if (add.length) changes.push({ file: '.gitignore', kind: 'add-lines', what: `${add.filter((l) => !l.startsWith('#')).length} line(s): ${add.filter((l) => !l.startsWith('#')).join(' ')}`, lines: add });
+
+  const git = spawnSync('git', ['status', '--porcelain'], { cwd: root, encoding: 'utf8' });
+  const dirty = git.status === 0 ? git.stdout.split('\n').filter(Boolean).length : null;
+  return {
+    ok: true, command: 'upgrade', applied: false, root, studio: name, from, to: STUDIO_VERSION,
+    changes, kept,
+    ...(dirty ? { uncommitted: dirty } : {}),
+    next: changes.length ? ['npx --no-install homie-studio upgrade --apply   (after the person agrees)'] : [],
+  };
+}
+
+function writeAtomic(path, text) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.upgrade-${process.pid}`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, path);
+}
+
+/** Apply a plan made a moment ago on the same files (each change checks that what it replaces is still there). */
+export function upgradeApply(root, plan) {
+  if (!plan?.ok) return plan;
+  const done = [];
+  const skipped = [];
+  const byFile = new Map();
+  for (const c of plan.changes) (byFile.get(c.file) ?? byFile.set(c.file, []).get(c.file)).push(c);
+  for (const [rel, list] of byFile) {
+    const path = join(root, rel);
+    let text = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    for (const c of list) {
+      if (c.kind === 'add-file') { if (text === null) { text = c.text; done.push(c); } else skipped.push({ ...c, why: 'it exists now' }); continue; }
+      if (c.kind === 'update-file') { if (text === c.from) { text = c.text; done.push(c); } else skipped.push({ ...c, why: 'it changed since the plan' }); continue; }
+      if (c.kind === 'add-lines') { text = `${text ?? ''}${text && !text.endsWith('\n') ? '\n' : ''}${text ? '\n' : ''}${c.lines.join('\n')}\n`; done.push(c); continue; }
+      if (c.kind === 'update-section' || c.kind === 'add-section') {
+        // Sections joined by line ends are the file byte for byte: only the section that changes changes.
+        const secs = sections(text ?? '');
+        if (c.kind === 'update-section') {
+          const at = secs.find((s) => s.heading === c.section);
+          if (!at || at.text !== c.from) { skipped.push({ ...c, why: 'the section changed since the plan' }); continue; }
+          at.text = `${c.text.replace(/\n+$/, '')}${/\n*$/.exec(at.text)[0]}`;
+        } else {
+          if (secs.some((s) => s.heading === c.section)) { skipped.push({ ...c, why: 'it exists now' }); continue; }
+          // A new section ends with a blank line (before the next heading), and the one above it ends its last line.
+          const item = { heading: c.section, text: `${c.text.replace(/\n+$/, '')}\n` };
+          const i = c.after ? secs.findIndex((s) => s.heading === c.after) : -1;
+          const j = !c.after && c.before ? secs.findIndex((s) => s.heading === c.before) : -1;
+          const at = i >= 0 ? i + 1 : j >= 0 ? j : secs.length;
+          secs.splice(at, 0, item);
+          if (at > 0 && !secs[at - 1].text.endsWith('\n')) secs[at - 1].text += '\n';
+        }
+        text = secs.map((s) => s.text).join('\n');
+        done.push(c);
+        continue;
+      }
+      if (c.kind === 'pin' || c.kind === 'scripts') {
+        const pkg = JSON.parse(text);
+        if (c.kind === 'pin') {
+          const where = pkg.devDependencies?.['@homie-rocks/studio'] !== undefined ? 'devDependencies' : 'dependencies';
+          if (pkg[where]?.['@homie-rocks/studio'] !== c.from) { skipped.push({ ...c, why: 'the pin changed since the plan' }); continue; }
+          pkg[where]['@homie-rocks/studio'] = c.to;
+        } else pkg.scripts = { ...(pkg.scripts ?? {}), ...c.scripts };
+        text = `${JSON.stringify(pkg, null, 2)}\n`;
+        done.push(c);
+        continue;
+      }
+      if (c.kind === 'version') {
+        const s = JSON.parse(text);
+        s.homie = { ...(s.homie ?? {}), studio: c.to };
+        text = `${JSON.stringify(s, null, 2)}\n`;
+        done.push(c);
+      }
+    }
+    if (text !== null && (!existsSync(path) || readFileSync(path, 'utf8') !== text)) writeAtomic(path, text);
+  }
+  const pinned = done.some((c) => c.kind === 'pin');
+  return {
+    ...plan, applied: true, done, skipped,
+    next: [...(pinned ? [`npm install   (fetches @homie-rocks/studio ${STUDIO_VERSION})`] : []), 'npm run build, then look at the site (npm run dev) before the next deploy', 'git diff, then commit the upgrade on its own'],
+  };
+}

package/lib/version.mjs

@@ -8,10 +8,14 @@ import { readFileSync } from 'node:fs';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const STUDIO_VERSION = pkg.version;
 
-/** The pinned tarball of this version, on a Homie directory (homie.rocks by default). */
+/** The pinned tarball of this version, on a Homie directory (homie.rocks by default). Kept for older studios. */
 export function tarballUrl(base = 'https://homie.rocks', version = STUDIO_VERSION) {
   return `${String(base).replace(/\/+$/, '')}/npm/homie-studio-${version}.tgz`;
 }
 
-/** What a studio's package.json names: until @homie-rocks/studio is on the npm registry, its versioned tarball URL. */
-export function packageSpec(base) { return tarballUrl(base); }
+/**
+ * What a studio's package.json names: this exact version, from registry.npmjs.org (package-lock.json keeps its
+ * integrity). The public registry is what Cloudflare's Workers Builds and a Claude Code cloud session reach with
+ * their default network settings; a directory's /npm/ tarball is not.
+ */
+export function packageSpec() { return STUDIO_VERSION; }

package/media/MEDIA.md

@@ -60,6 +60,19 @@ show and why anything is left out.
 - `rights` and `credits` are shown on the page, in plain words. Say what the provider's terms
   say for the plan the file was made on; nothing on the site claims more.
 
+## Covers and posters
+
+Every song's page, its card and the directory's manifest show a cover (a video: a poster), the first of:
+
+1. its own `cover` file (a video's `poster`);
+2. the manifest's own, for every entry without one: `"cover": "music/night-route/cover.jpg"` at the top of
+   `music/manifest.json` (an album's cover; `"poster"` in `videos/manifest.json`), a path in the studio or an
+   `https://` address, served like any file;
+3. the landing still of the game the entry was made for (`for.game`);
+4. the studio's share picture (`site/theme.json` `social`).
+
+homie.rocks shows a cover only from the studio's own site, as a `.jpg`, `.png`, `.webp`, `.avif` or `.gif`.
+
 ## Where the bytes come from
 
 A studio needs no storage for songs and videos: the site serves them itself. For every public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.8.0",
+  "version": "0.10.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.",
   "type": "module",
   "license": "Apache-2.0",

package/site/SITE.md

@@ -11,19 +11,34 @@ and every game gets a landing page. Anything the studio puts in `site/` wins.
 | `/` | Home: the featured game as a full-bleed hero with Play, the live rooms, the games, the latest posts, videos and music | always |
 | `/games/` | Every game, with its cover, pitch, players playing now, Play and About | the studio has a game |
 | `/music/`, `/videos/` | Songs and videos (`media/MEDIA.md`) | the studio has one published |
-| `/rooms/` | Every public room playing now across the studio's games, each with Join (`/api/rooms` is the same as JSON) | the studio has a game |
+| `/rooms/` | Every public room playing now across the studio's games, each with Join (`/api/rooms` is the same as JSON, cacheable for 15 s) | the studio has a game |
 | `/posts/` | The studio's posts, newest first, with `/posts/feed.xml` (Atom) and `/posts/feed.json` (JSON Feed) | the studio has a post |
 
 A section with nothing in it has no tab, and its address answers 404. Every page ends with a
 "Made with Homie" link to https://homie.rocks/studio/. studio.json may add `"tagline"` (one line, on Home and in
 the feeds) and `"site": { "featured": "<game id>" }` (the game on Home; otherwise the first with its own footage).
 
+Every card (Home, Games, Rooms, a post's), every live room's row and the directory's manifest show a game's
+**landing still**: `hero/wide.jpg` (or `landing.hero.image`), else a trailer's poster, else game.json's `cover`.
+
+## What the homie.rocks hub reads
+
+`/.well-known/homie-studio.json` is the studio's manifest: its games (each with its landing still as `cover`),
+songs (each with a `cover`), videos (each with a `poster`), the latest posts, and `rooms`, the address of
+`/api/rooms`, so the hub's Rooms page lists this studio's public rooms. With studio.json `"stats": { "share": true }`
+(`homie-studio stats share on`) it also says "played this week": `played` for the whole studio and each game's own
+(`games[].played`, `{ "days": 7, "plays", "rounds" }`). To keep the studio's rooms off the hub, studio.json takes
+`"rooms": { "share": false }`: the manifest then names no `rooms` (the studio's own pages still list them).
+
 ## A game's landing: `/<id>/`
 
 Made from the game's own files, nothing invented:
 
 - **The hero**, full-bleed: the game's footage when it has some, else its cover (or key art) moving slowly, tinted
-  with the studio's colour so the words read. Footage is looked for in this order: `landing.hero` in game.json;
+  with the studio's colour so the words read. A game whose picture is white or cream (a light arena) takes
+  `"scheme": "light"` in its `landing` block: its landing is drawn light, the hero tinted and shaded with a light
+  background and the words dark, where a dark studio's tint would turn it grey (`"dark"` is the other way round,
+  for a dark game in a light studio). `landing.theme` colours still win, and the rest of the site keeps its look. Footage is looked for in this order: `landing.hero` in game.json;
   `games/<id>/hero/` by the house brands' names (`wide.mp4` and `tall.mp4`, their AV1 cuts `wide.av1.mp4` and
   `tall.av1.mp4`, stills `wide.jpg` and `tall.jpg`); a trailer in `videos/manifest.json` whose `for.game` is the
   game (its 16:9 `video`, 9:16 `vertical` and `poster`). A loop of 8 to 15 s under 3 MB each, muted, plays best.
@@ -55,6 +70,7 @@ game.json's `landing` block, every key optional:
             "alt": "What the footage shows", "focus": "50% 40%", "tint": 30 },
   "credits": [{ "role": "Music", "name": "Low Tide", "url": "https://example.com" }],
   "theme": { "accent": "#ff3bd4", "glow": "#00eaff" },
+  "scheme": "light",
   "tv": true
 }
 ```
@@ -108,16 +124,45 @@ A studio with its own landing in `site/` keeps it: the template never replaces w
 ## The play page
 
 `/<id>/play` puts the visitor in a public room at once and writes the room into the address, so a reload comes
-back to it and a copied address brings a friend into it. A small room button at the edge (game.json
-`"screen": { "share": "top-left" }` moves it off the game's own HUD; top right by default) opens:
-**Invite** (the phone's share sheet, or the link copied), **Big screen** (`/<id>/tv` of this room, on another
-screen) and the room's code. A room code the relay cannot use (1 to 32 letters, digits, `-` or `_`) is refused
+back to it and a copied address brings a friend into it. A small room button at the edge (top right by default)
+opens: **Invite** (the phone's share sheet, or the link copied), **Big screen** (`/<id>/tv` of this room, on
+another screen) and the room's code. It must never cover the game's own HUD, so game.json's `screen.share` puts it
+where the game has room, per device:
+
+```json
+"screen": {
+  "share": {
+    "desk": "bottom-left",
+    "phone": { "at": "top-left", "y": 56 },
+    "sideways": { "at": "top-center", "label": false }
+  }
+}
+```
+
+- A place is `top-left`, `top-center`, `top-right`, `bottom-left` or `bottom-right`; a plain string (`"share":
+  "top-center"`) or an object with `at` is every device, and `desk` (a computer), `phone` (held upright) and
+  `sideways` (a phone turned sideways; else as `phone`) each take their own.
+- `x` and `y` move it in from its side and its edge, in CSS pixels (0 to 600): `"y": 56` puts it under a game's
+  own top line. At `top-center`, `x` moves it right (or left, negative).
+- It shows the room's name ("Room 7") for a few seconds, then shrinks to a round icon until it is touched;
+  `"label": false` keeps it the icon always (the code is in its sheet), for a corner with little room.
+- A button at the bottom left sends the "finding a room" chip to the bottom right.
+
+Look at the play page on a computer and a phone (both ways up) once a round is on: the button must not sit on a
+score, a timer or a bar. A room code the relay cannot use (1 to 32 letters, digits, `-` or `_`) is refused
 on the page, never swapped for a public room. A player who typed no name gets a two-word handle.
 
 The game runs in a sandboxed frame with an opaque origin, which is why its allow list delegates with `*`
 (`fullscreen *; autoplay *; gamepad *`): Safari refuses a bare `gamepad` there (`getGamepads()` throws a
 SecurityError), so a controller would not work.
 
+## The arcade knock
+
+A game made with Homie's arcade controls asks its page's origin for a Homie box (`GET /__homie/call`), and a score
+goes there as a POST. The site answers at its root and under every game with `{ "ok": false, "error":
+"not-a-homie" }` (JSON, CORS-open, 200, a preflight answered), so the game stops asking and plays on its own; no
+studio needs a Worker of its own for it.
+
 ## Headers
 
 Every HTML answer is `no-transform` (a custom domain's edge injects nothing: Web Analytics' automatic beacon