@homie-rocks/studio 0.30.2 → 0.31.1

package/lib/cloudflare.mjs

@@ -19,17 +19,28 @@
  * 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.
+ * before anything happens and changes nothing.
+ *
+ * A studio on a CUSTOM DOMAIN shares that domain with whatever else its owner
+ * runs there. The plan and the deploy read the domain's Worker routes (a read,
+ * with Wrangler's own sign-in) and warn when another site's catch-all or
+ * wildcard covers the studio's hostname: that route is never the studio's to
+ * edit or remove (lib/routes.mjs, zoneCheck below).
  */
 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 { cloudflareAuth } from './brain-probe.mjs';
 import { build } from './build.mjs';
+import { builtGames, compareDeploy, deployWords, lastDeploy, lastDeployRecord, lockDeploy, recordDeploy } from './deploy-state.mjs';
+import { listedHere, publish } from './directory.mjs';
 import { MAX_ASSET_BYTES, R2_COST, mediaPlan, r2OverOf, recordMove, sha256File, sizeOf } from './media.mjs';
+import { whyFailed } from './net.mjs';
 import { repoOf } from './repo.mjs';
+import { keptRoutes, readConfig, readZoneRoutes, routesOf, shadowedDomain, wideRouteRefusal, zoneFinding } from './routes.mjs';
 import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
-import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
+import { LOCAL_STATE, configPath, domainOrigin, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -90,12 +101,66 @@ export function explainCloudflare(out, accountId = null) {
   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.' };
   }
+  // A route in wrangler.jsonc that another Worker of the zone already holds. Wrangler refuses, and so does the
+  // studio: that route is not the studio's to take (lib/routes.mjs).
+  if (/assigned to another worker|already assigned to routes/i.test(text)) {
+    const routes = [...text.matchAll(/^\s*-\s+(\S+)\s*$/gm)].map((m) => m[1]);
+    return { needs: 'cloudflare-routes', ...(routes.length ? { routes } : {}), why: `A route in wrangler.jsonc${routes.length ? ` (${routes.join(', ')})` : ''} already belongs to another Worker on this Cloudflare zone, so Cloudflare refused the deploy and the live site is unchanged. The studio never takes a route from another Worker. If the route is wider than the studio's own hostname (a wildcard, a catch-all), take it out of wrangler.jsonc and give the studio its own: { "pattern": "<its hostname>/*", "zone_name": "<the domain>" }. If it IS the studio's own hostname, ask the person: only they can unassign it from the other Worker, in the zone's Workers Routes in the Cloudflare dashboard.` };
+  }
   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;
 }
 
+/** The studio's custom hostname ("play.example.com"), or null for a studio on its workers.dev address. */
+export function customHost(studio) {
+  const cf = studio?.cloudflare ?? {};
+  const origin = domainOrigin(cf.domain) ?? (cf.url && !isWorkersDev(cf.url) ? domainOrigin(cf.url) : null);
+  return origin ? new URL(origin).hostname : null;
+}
+
+/**
+ * For a studio on a custom domain: what the domain's other Worker routes mean for it (lib/routes.mjs zoneFinding),
+ * read from Cloudflare with the sign-in Wrangler already has (lib/brain-probe.mjs cloudflareAuth: a token in the
+ * environment, else `wrangler auth token`). Null for a studio with no custom domain, which is asked nothing. It
+ * only reads; a list that cannot be read comes back as state 'unmeasured' with the reason. `config` stands in for
+ * wrangler.jsonc (a deploy that is about to add a route), `fetchFn` for the network in tests.
+ */
+export async function zoneCheck(root, { studio = readStudio(root), config = readConfig(root), accountId = null, fetchFn = null } = {}) {
+  const hostname = customHost(studio);
+  if (!hostname) return null;
+  const worker = studio.cloudflare?.worker ?? null;
+  // The toolkit's own tests (HOMIE_STUDIO_WARM=0) with no stand-in network ask nobody, as readLiveSite does.
+  if (!fetchFn && process.env.HOMIE_STUDIO_WARM === '0') return zoneFinding({ hostname, worker, config, zone: { read: false, why: 'not asked' } });
+  const bin = wranglerBin(root);
+  let headers = null;
+  try {
+    const w = bin ? runner(root, accountId ? { CLOUDFLARE_ACCOUNT_ID: accountId } : {}) : null;
+    headers = await cloudflareAuth({
+      env: { ...process.env, ...projectsCloudflareEnv(root) }, bin, cwd: root,
+      exec: async (_bin, args) => { const r = w(args, { cwd: root }); return { code: r.code, stdout: r.stdout }; },
+    });
+  } catch { headers = null; }
+  const zone = await readZoneRoutes({ hostname, config, headers, ...(fetchFn ? { fetchFn } : {}) });
+  return zoneFinding({ hostname, worker, config, zone });
+}
+
+/** A zone finding as a deploy's result and its plan carry it: the state, the routes that are not the studio's, the one line. */
+function zoneView(z) {
+  return {
+    state: z.state, host: z.host, domain: z.zone, foreign: z.foreign.map((r) => ({ pattern: r.pattern, worker: r.script, kind: r.kind })),
+    ...(z.state === 'foreign' || z.state === 'unmeasured' ? { route: z.route, line: z.line } : {}),
+    ...(z.warning ? { warning: z.warning } : {}), ...(z.why ? { why: z.why } : {}),
+  };
+}
+
+/** `deploy --plan` for a studio on a custom domain: the plan, and what the domain's other routes mean for it. */
+export async function zonePlan(root, opts = {}) {
+  const z = await zoneCheck(root, opts);
+  return z ? zoneView(z) : null;
+}
+
 /** What `deploy` will create and what it costs, from studio.json alone. It calls nothing. */
 export function deployPlan(root) {
   const studio = readStudio(root);
@@ -127,10 +192,29 @@ export function deployPlan(root) {
   };
 }
 
-export async function deploy(root, { log = () => {}, homie } = {}) {
+/**
+ * `homie-studio deploy`. One at a time for a studio: it holds the studio's deploy lock (lib/deploy-state.mjs) from
+ * before it reads anything until it ends, however it ends. `fetchFn` is the toolkit's own tests' stand-in network.
+ */
+export async function deploy(root, opts = {}) {
+  const lock = lockDeploy(root);
+  if (!lock.ok) return { ok: false, command: 'deploy', needs: lock.needs, why: lock.why };
+  // A deploy that is killed still lets go (a kill -9 cannot; the next deploy sees its process is gone).
+  const onExit = () => lock.release();
+  process.once('exit', onExit);
+  try { return await deployLocked(root, opts); } finally { process.off('exit', onExit); lock.release(); }
+}
+
+async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRoute = false } = {}) {
   const studio = readStudio(root);
   const cf = { r2: null, created: [], ...studio.cloudflare };
   const created = new Set(cf.created ?? []);
+  // A wildcard or catch-all route in the studio's own config would hand other hostnames of the zone to this Worker:
+  // refused before Cloudflare is asked anything (lib/routes.mjs). Read once here; every rewrite below keeps the
+  // studio's own routes exactly as its owner wrote them.
+  const wide = wideRouteRefusal(readConfig(root), studio);
+  if (wide) return { ok: false, command: 'deploy', ...wide };
+  let routes = keptRoutes(root, studio);
   const who = whoami(root);
   if (!who) {
     if (cf.auth === 'stripe-projects') {
@@ -157,6 +241,25 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   };
   const steps = [];
   const step = (what, extra = {}) => { steps.push({ what, ...extra }); log(what); };
+  const notes = [];
+
+  // A studio on a custom domain: is another site's catch-all or wildcard route on the same domain covering its
+  // hostname? Read (never written) and said before Wrangler changes anything: the repair that suggests itself,
+  // editing or removing that route, takes the other site down (lib/routes.mjs). `--own-route` adds the one line
+  // that is the studio's to add, and only when the domain's routes were read and show it is needed.
+  let zone = await zoneCheck(root, { studio, accountId, fetchFn });
+  if (zone) {
+    if (ownRoute && zone.state === 'foreign') {
+      routes = [...(routes ?? []), zone.route];
+      step(`added the studio's own exact-host route to "routes" in wrangler.jsonc: ${zone.line}. It covers ${zone.host} only, and every deploy keeps it; the other site's route was not touched.`, { route: zone.route });
+      const config = readConfig(root) ?? {};
+      zone = await zoneCheck(root, { studio, accountId, fetchFn, config: { ...config, routes: [...routesOf(config), zone.route] } });
+    } else if (ownRoute) {
+      step(`--own-route added nothing: ${zone.state === 'unmeasured' ? 'the domain\'s routes could not be read, so the domain\'s name in Cloudflare is not known for sure' : zone.state === 'taken' ? `${zone.host} is routed to another Worker, which only the person can change` : zone.state === 'own-route' ? 'the studio\'s own exact-host route is already there' : `no other route covers ${zone.host}`}.`);
+    }
+    if (zone.warning) { notes.push(zone.warning); step(`warning: ${zone.warning}`, { needs: 'cloudflare-routes', ...(zone.state === 'foreign' ? { route: zone.route } : {}) }); }
+    else if (zone.why) step(zone.why);
+  } else if (ownRoute) step('--own-route added nothing: this studio has no custom domain (studio.json cloudflare.domain).');
 
   // 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.
@@ -187,6 +290,14 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   // 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}`);
+  if (b.retired) step(`note: ${b.retired}`);
+  // Which games this deploy changes, against what the last deploy from this computer put live, each with the
+  // build's own hash for it (lib/deploy-state.mjs: one hash vocabulary). The record is written only once Wrangler has deployed.
+  const builtNow = builtGames(root, b.catalogue);
+  const delta = compareDeploy(builtNow, lastDeploy(root), lastDeployRecord(root));
+  for (const g of delta.games) step(`${g.id}: ${deployWords(delta.first ? { hash: g.hash } : g)}`, { game: g.id, hash: g.hash, change: g.change });
+  if (delta.first && delta.games.length) step('no earlier deploy from this computer to compare with: the next one says changed or unchanged for each game');
+  for (const id of delta.removed) step(`${id}: no longer in the build; it leaves the site with this deploy`);
 
   // The Worker: never one this studio did not make.
   if (!created.has(`worker:${cf.worker}`)) {
@@ -218,14 +329,15 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   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) }));
+  writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), routes }));
+  if (routes) step(`kept the studio's own route${routes.length === 1 ? '' : 's'} in wrangler.jsonc: ${routes.map((r) => r.pattern).join(', ')}`);
   for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
   if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   step('D1 migrations applied');
   // Workers AI (0.17.0): bound only when a server's AI guides think with it.
   if (needsWorkersAi(root, w, cf.d1)) {
-    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true }));
+    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root), ai: true, routes }));
     step('Workers AI bound (AI): a server\'s AI guides think with it and typed room chat is reviewed with it, each within its day\'s budget (free allocation: 10,000 neurons a day)');
   }
 
@@ -250,11 +362,45 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   // The homie.rocks directory claim: the live site claims itself the first time its manifest is read (0.10.0), so
   // reading it once now is all it takes; nothing is stored by hand.
   const directory = homie || studio.homie?.directory || 'https://homie.rocks';
+  recordDeploy(root, builtNow);
   let claim = null;
   if (url) {
-    claim = await warmClaim(url);
+    const read = await readLiveSite(url, fetchFn ? { fetchFn } : {});
+    claim = read.claim;
     if (claim) step('the site claimed itself in the directory');
-    else step('the directory claim is not there yet (the site claims itself when the directory first reads it)');
+    else if (read.state === 'other' && !isWorkersDev(url)) {
+      // The studio's own domain answered as something else: say which route is needed (lib/routes.mjs). The deploy
+      // itself went through; the zone's other routes are never touched.
+      const s = shadowedDomain(readConfig(root), new URL(url).hostname, read);
+      notes.push(s.why);
+      step(s.why, s.route ? { needs: 'cloudflare-routes', route: s.route } : {});
+    } else if (read.state === 'unreachable') {
+      // This computer could not ask (its own name lookup, no connection): a network preflight failure, never a
+      // verdict on the site that was just deployed.
+      const said = `deployed, but this computer could not read ${url} back to check it: ${read.why}. ${read.preflight === 'dns' ? 'That is this computer\'s name lookup (a browser here may still open the site), not the deploy.' : 'That is this computer\'s connection, not the deploy.'} The site claims itself when the directory first reads it.`;
+      notes.push(said);
+      step(said, { preflight: read.preflight ?? 'network' });
+    } else step('the directory claim is not there yet (the site claims itself when the directory first reads it)');
+  }
+
+  // The deploy before this one came from a toolkit that still had remix, and left games open to be taken whole. No
+  // game's source is served any more, but the directory keeps its old copy of the studio (and its offer of those
+  // games) until it reads the site again, so ask it to, now. ONLY for a studio this computer listed (publish records
+  // it): going online never lists a studio, and a deploy never lists one either. Once: see compareDeploy.
+  let reread = null;
+  if (url && delta.withdrawn.length) {
+    const which = delta.withdrawn.join(', ');
+    const dir = String(directory).replace(/\/+$/, '');
+    if (listedHere(root, { site: url, directory: dir })) {
+      const again = await publish(root, { homie: dir, site: url, ...(fetchFn ? { fetchFn } : {}) });
+      reread = { ok: again.ok, games: delta.withdrawn, ...(again.ok ? {} : { why: again.why }), ...(again.publishes ? { publishes: again.publishes } : {}) };
+      step(again.ok
+        ? `asked the directory to read the studio again: it still offered the source of ${which}, and no game's source is served whole any more${again.publishes?.line ? ` (${again.publishes.line})` : ''}`
+        : `the directory still offers the source of ${which}, which is no longer served, and it did not take the re-read (${String(again.why ?? 'no answer').split('\n')[0]}): it keeps its old copy until the next publish`);
+      if (!again.ok) notes.push(`The directory still offers the source of ${which}, which this site no longer serves: publish again later (homie-studio publish).`);
+    } else {
+      step(`the source of ${which} is no longer served (games build on each other through parts now); this computer has no record of listing the studio in the directory, so the directory was not asked anything (a deploy never lists a studio). If it is listed, publish again and the directory reads the site as it is.`);
+    }
   }
 
   // studio.json keeps what is safe to commit: names, ids, the custom domain; never the workers.dev address.
@@ -264,7 +410,12 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   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 })),
+    games: b.catalogue.map((id) => { const g = delta.games.find((x) => x.id === id); return { id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null, hash: g?.hash ?? null, change: delta.first ? 'first deploy from this computer' : g?.change ?? null }; }),
+    ...(delta.removed.length ? { removed: delta.removed } : {}),
+    ...(routes ? { routes: routes.map((r) => r.pattern) } : {}),
+    ...(zone ? { zone: zoneView(zone) } : {}),
+    ...(notes.length ? { notes } : {}),
+    ...(reread ? { reread } : {}),
     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,
@@ -301,6 +452,44 @@ export function repoVar(root) {
   return repo ? ['--var', `HOMIE_REPO:${repo}`] : [];
 }
 
+/**
+ * The live site's manifest, read back after a deploy, and what the answer was:
+ *   state 'studio'       it answered as a studio; `claim` is its directory claim (null until it has one)
+ *   state 'other'        the address answered, and not as a studio (another Worker's page, a 404 that is not ours):
+ *                        `status`, and `said`, the first words of what it said
+ *   state 'unreachable'  this computer could not ask: `why`, and `preflight` ('dns' for a name it could not look up)
+ *   state 'skipped'      the toolkit's own tests (HOMIE_STUDIO_WARM=0) with no stand-in network
+ * Reading it is also what makes a 0.10.0 site claim itself. A fresh deploy can take a few seconds to answer
+ * everywhere, so a site that does not yet answer as a studio is asked three times.
+ */
+export async function readLiveSite(site, { tries = 3, wait = 2500, fetchFn = null } = {}) {
+  if (!fetchFn && process.env.HOMIE_STUDIO_WARM === '0') return { state: 'skipped', claim: null };
+  const ask = fetchFn ?? globalThis.fetch;
+  const base = String(site).replace(/\/+$/, '');
+  let last = { state: 'unreachable', claim: null, why: 'no answer' };
+  for (let i = 0; i < tries; i++) {
+    try {
+      const res = await ask(`${base}/.well-known/homie-studio.json`, { headers: { accept: 'application/json', 'user-agent': 'homie-studio-deploy' }, signal: AbortSignal.timeout(15_000) });
+      const text = await res.text();
+      let body = null;
+      try { body = JSON.parse(text); } catch { body = null; }
+      const studio = res.ok && body && typeof body === 'object' && ('claim' in body || Array.isArray(body.games));
+      if (studio) {
+        const claim = /^[a-f0-9]{16,128}$/.test(body.claim ?? '') ? body.claim : null;
+        if (claim) return { state: 'studio', claim };
+        last = { state: 'studio', claim: null };
+      } else last = { state: 'other', claim: null, status: res.status, said: String(body?.error ?? body?.message ?? text ?? '').replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) };
+    } catch (error) {
+      const w = whyFailed(error, base);
+      last = { state: 'unreachable', claim: null, why: w.why, code: w.code ?? null, ...(w.preflight ? { preflight: w.preflight } : {}) };
+      // A name this computer cannot look up does not start resolving in five seconds: say so now.
+      if (w.preflight === 'dns') return last;
+    }
+    if (i < tries - 1) await new Promise((r) => setTimeout(r, wait));
+  }
+  return last;
+}
+
 /**
  * Read the live site's manifest once, which makes a 0.10.0 site claim itself in its directory. Returns the claim it
  * serves, or null (the directory did not answer, the site is not reachable yet, or it is a Preview). A fresh deploy
@@ -378,10 +567,13 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   step(claim ? 'the site claimed itself in the directory' : 'no directory claim yet (the site claims itself when the directory first reads it)');
   let games = [];
   try { games = JSON.parse(readFileSync(join(root, 'site', 'dist', 'games.json'), 'utf8')).games.map((g) => g.id); } catch { games = []; }
+  const hashes = builtGames(root, games);
+  for (const id of games) if (hashes[id]?.hash) step(`${id}: ${deployWords(hashes[id])}`);
   return {
     ok: true, command: 'deploy', ci: true, url, worker: names.worker, d1: names.d1, r2: null, steps, announced: [],
     commit: process.env.WORKERS_CI_COMMIT_SHA ?? null, branch: process.env.WORKERS_CI_BRANCH ?? null,
-    games: games.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null })), songs: [], videos: [],
+    // A CI checkout has no earlier deploy to compare with: each game's content hash only (lib/deploy-state.mjs).
+    games: games.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null, hash: hashes[id]?.hash ?? null })), songs: [], videos: [],
     claim: Boolean(claim),
   };
 }
@@ -429,7 +621,8 @@ export async function storageAdd(root, { log = () => {} } = {}) {
   const next = { ...readStudio(root), cloudflare: { ...readStudio(root).cloudflare, accountId, r2: bucket, created: [...created].sort() } };
   writeStudio(root, next);
   if (next.cloudflare.d1Id) {
-    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root) }));
+    // The studio's own routes stay through this rewrite too (lib/routes.mjs).
+    writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: next.cloudflare.d1Id, r2: bucket, layout: layoutOf(root), routes: keptRoutes(root, studio) }));
   }
   log(`created R2 ${bucket}`);
   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)'] };

package/lib/codex.mjs

@@ -702,6 +702,12 @@ ${game.blurb ?? ''}
 
 <!-- The theme's mood and tempo, the sounds that matter (pick-up, hit, win), and whether songs come from the free synth or ElevenLabs. -->
 
+## Built from
+
+<!-- What this game is made of, looked for BEFORE writing (the plan tool says how: \`parts find\` for each system, and the @homie-rocks/* packages). One line each:
+     packages (camera, input, audio, effects… from npm); parts from other games (which part, the game and studio it came from, its licence);
+     and what was written here from scratch, and why nothing that exists fitted. -->
+
 ## Milestones
 
 ${game.planned ? `- [ ] The plan (this codex)

package/lib/collision.mjs

@@ -0,0 +1,245 @@
+/**
+ * `homie-studio collision`: a model that can be drawn becomes a model that can be stood on, and stays that way.
+ *
+ *   homie-studio collision bake <game> <model.glb> [--cell 0.25] [--side top|under] [--max-y <m>]
+ *   homie-studio collision check <game> [<model.glb>]
+ *
+ * Importing a model records what it looks like and where it came from. Nothing in that says where a figure may walk
+ * on it, so the first playable version of a generated landmark is one figures fall through. `bake` reads the
+ * model's triangles (every node's transform applied, in metres) and writes two files beside it:
+ *
+ *   <model>.collision.json   the height grid (@homie-rocks/heightfield MeshBake), the SHA-256 of the model file and
+ *                            a checksum of its triangles, and three things a person AUTHORS and a re-bake keeps:
+ *                            "proxies" (boxes, cylinders and ramps for what a figure walks around), "mover" (the
+ *                            body that must fit: radius, height, step, arrival radius) and "routes" (ways a bot
+ *                            should be able to walk, as lists of points)
+ *   <model>.collision.svg    the plan at true scale (40 px to the metre, a metre grid, a scale bar): the grid shaded
+ *                            by height, the proxies outlined, the routes drawn, and a mark where a route fails
+ *
+ * `check` is the gate: the model file is the one that was baked (a changed file is "stale: bake it again", by name),
+ * the proxies are well formed, and a body of the mover's size both passes the static route check and walks every
+ * route to its end. It answers ok: false with a row for each thing wrong, so it can stand in a build script.
+ *
+ * The game loads the JSON with `unpackBake` and `bakeField` and calls `bakeStale` against the mesh it loaded.
+ *
+ * The arithmetic is @homie-rocks/heightfield's, not a copy of it. It is not installed with the toolkit (a pinned
+ * version of it that is not on npm yet would stop every new studio's install): the studio's own copy is used, else one
+ * beside the toolkit, else the answer says the one install to run, which an AI with a shell runs itself.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { modelTools } from './optimise.mjs';
+import { listGames } from './studio.mjs';
+
+/** The body that must fit when a file names none: a person, in metres. */
+export const DEFAULT_MOVER = Object.freeze({ radius: 0.35, height: 1.8, step: 0.3, maxDrop: 0.5, arrival: 1, speed: 4 });
+const PX = 40;
+/** How a walk that did not arrive reads in a sentence after "the bot". */
+const ENDED = { fell: 'fell', blocked: 'was blocked', headroom: 'ran out of headroom', 'wrong level': 'reached the wrong level', timeout: 'ran out of time' };
+
+/** @homie-rocks/heightfield's modules, from the studio's own install first, then from beside this toolkit. */
+export async function heightfieldModules(root) {
+  const names = ['MeshBake', 'Proxy', 'Levels', 'Route'];
+  const from = [];
+  if (root) { try { const req = createRequire(join(root, 'package.json')); from.push((n) => import(pathToFileURL(req.resolve(`@homie-rocks/heightfield/${n}.js`)).href)); } catch { /* not a package: the toolkit's own */ } }
+  from.push((n) => import(`@homie-rocks/heightfield/${n}.js`));
+  for (const load of from) {
+    try { const [bake, proxy, levels, route] = await Promise.all(names.map(load)); if (bake.bakeMesh && route.traverse) return { ...bake, ...proxy, ...levels, ...route }; } catch { /* the next place */ }
+  }
+  return null;
+}
+const NEEDS = { ok: false, needs: 'heightfield', why: 'collision needs the package @homie-rocks/heightfield (0.2.0 or later, for its MeshBake module) in this studio, and found none', instead: 'npm install --save-exact @homie-rocks/heightfield   (in the studio folder; then ask again)' };
+
+/** Every triangle of a model, in the scene's own space (each node's transform applied): { positions, indices }. */
+export async function modelTriangles(bytes) {
+  const { io } = await modelTools();
+  const doc = await io.readBinary(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+  const positions = []; const indices = [];
+  const scenes = doc.getRoot().listScenes();
+  const scene = doc.getRoot().getDefaultScene() ?? scenes[0];
+  if (!scene) return { positions: new Float32Array(0), indices: new Uint32Array(0) };
+  scene.traverse((node) => {
+    const mesh = node.getMesh();
+    if (!mesh) return;
+    const m = node.getWorldMatrix();
+    for (const prim of mesh.listPrimitives()) {
+      // 4 is TRIANGLES. Lines and points are not something to stand on; strips and fans are not what an optimiser writes.
+      if (prim.getMode() !== 4) continue;
+      const pos = prim.getAttribute('POSITION');
+      if (!pos) continue;
+      const base = positions.length / 3; const el = [0, 0, 0];
+      for (let i = 0; i < pos.getCount(); i += 1) {
+        pos.getElement(i, el);
+        positions.push(m[0] * el[0] + m[4] * el[1] + m[8] * el[2] + m[12], m[1] * el[0] + m[5] * el[1] + m[9] * el[2] + m[13], m[2] * el[0] + m[6] * el[1] + m[10] * el[2] + m[14]);
+      }
+      const ix = prim.getIndices();
+      if (ix) for (let i = 0; i < ix.getCount(); i += 1) indices.push(base + ix.getScalar(i));
+      else for (let i = 0; i < pos.getCount(); i += 1) indices.push(base + i);
+    }
+  });
+  return { positions: new Float32Array(positions), indices: new Uint32Array(indices) };
+}
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+
+/**
+ * The plan at true scale, as SVG text: 40 px to the metre, north (-z) up. `problems` are points to mark.
+ * A text file on purpose: it diffs, and a person can open it beside the lineup.
+ */
+export function collisionSvg(bake, { proxies = [], routes = [], problems = [], title = '' } = {}) {
+  const { nx, nz, x0, z0, cell, heights, covered } = bake;
+  const pad = 1; // metres of margin
+  const w = ((nx - 1) * cell + pad * 2) * PX; const h = ((nz - 1) * cell + pad * 2) * PX + 30;
+  const sx = (x) => ((x - x0 + pad) * PX).toFixed(1); const sz = (z) => ((z - z0 + pad) * PX).toFixed(1);
+  let lo = Infinity; let hi = -Infinity;
+  for (let k = 0; k < heights.length; k += 1) if (covered[k]) { lo = Math.min(lo, heights[k]); hi = Math.max(hi, heights[k]); }
+  const out = [`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w.toFixed(0)} ${h.toFixed(0)}" width="${w.toFixed(0)}" height="${h.toFixed(0)}" font-family="system-ui, sans-serif" font-size="12">`,
+    `<title>${esc(title || 'collision plan')}</title>`, `<rect width="100%" height="100%" fill="#101418"/>`];
+  // Sixteen shades of height, runs of one shade along a row merged into one rectangle.
+  for (let j = 0; j < nz; j += 1) {
+    let run = -1; let shade = -1;
+    const flush = (i) => { if (run >= 0) { const v = 60 + shade * 12; out.push(`<rect x="${sx(x0 + (run - 0.5) * cell)}" y="${sz(z0 + (j - 0.5) * cell)}" width="${((i - run) * cell * PX).toFixed(1)}" height="${(cell * PX).toFixed(1)}" fill="rgb(${v},${v + 8},${v + 14})"/>`); } run = -1; };
+    for (let i = 0; i <= nx; i += 1) {
+      const k = j * nx + i;
+      const s = i < nx && covered[k] ? Math.min(15, Math.floor(((heights[k] - lo) / Math.max(1e-6, hi - lo)) * 16)) : -1;
+      if (s !== shade) { flush(i); shade = s; if (s >= 0) run = i; }
+    }
+  }
+  for (let x = Math.ceil(x0 - pad); x <= x0 + (nx - 1) * cell + pad; x += 1) out.push(`<line x1="${sx(x)}" y1="0" x2="${sx(x)}" y2="${(h - 30).toFixed(0)}" stroke="#ffffff" stroke-opacity="${x === 0 ? 0.35 : 0.08}"/>`);
+  for (let z = Math.ceil(z0 - pad); z <= z0 + (nz - 1) * cell + pad; z += 1) out.push(`<line x1="0" y1="${sz(z)}" x2="${w.toFixed(0)}" y2="${sz(z)}" stroke="#ffffff" stroke-opacity="${z === 0 ? 0.35 : 0.08}"/>`);
+  for (const p of proxies) {
+    if (p.kind === 'cylinder') { out.push(`<circle cx="${sx(p.x)}" cy="${sz(p.z)}" r="${(p.r * PX).toFixed(1)}" fill="none" stroke="#ff7a59" stroke-width="2"><title>${esc(p.id ?? p.kind)}: ${p.h} m high</title></circle>`); continue; }
+    const yaw = p.yaw ?? 0; const c = Math.cos(yaw); const s = Math.sin(yaw);
+    const pts = [[-p.hx, -p.hz], [p.hx, -p.hz], [p.hx, p.hz], [-p.hx, p.hz]].map(([ax, az]) => `${sx(p.x + ax * c + az * s)},${sz(p.z - ax * s + az * c)}`).join(' ');
+    out.push(`<polygon points="${pts}" fill="none" stroke="#ff7a59" stroke-width="2"${p.kind === 'ramp' ? ' stroke-dasharray="6 3"' : ''}><title>${esc(p.id ?? p.kind)}: ${p.h} m high</title></polygon>`);
+  }
+  for (const r of routes) out.push(`<polyline points="${(r.path ?? []).map((q) => `${sx(q.x)},${sz(q.z)}`).join(' ')}" fill="none" stroke="#5ec8ff" stroke-width="2"><title>${esc(r.name ?? 'route')}</title></polyline>`);
+  for (const q of problems) out.push(`<circle cx="${sx(q.x)}" cy="${sz(q.z)}" r="7" fill="none" stroke="#ff3355" stroke-width="3"><title>${esc(q.why ?? '')}</title></circle>`);
+  out.push(`<line x1="20" y1="${(h - 14).toFixed(0)}" x2="${20 + PX}" y2="${(h - 14).toFixed(0)}" stroke="#fff" stroke-width="3"/>`,
+    `<text x="${28 + PX}" y="${(h - 10).toFixed(0)}" fill="#fff">1 m · ${esc(title)} · ${cell} m cell · heights ${Number.isFinite(lo) ? `${lo.toFixed(2)} to ${hi.toFixed(2)} m` : 'none'}</text>`, '</svg>');
+  return `${out.join('\n')}\n`;
+}
+
+const gameDir = (root, id) => listGames(root).find((g) => g.id === id)?.dir ?? null;
+/** Every file under a game's folder whose name passes `want`, sorted (no dot folders, no node_modules). */
+function filesUnder(dir, want) {
+  const out = [];
+  const walk = (d) => { for (const e of readdirSync(d, { withFileTypes: true })) { if (e.name === 'node_modules' || e.name.startsWith('.')) continue; const p = join(d, e.name); if (e.isDirectory()) walk(p); else if (want(e.name)) out.push(p); } };
+  walk(dir);
+  return out.sort();
+}
+/** A model named on the command line: a path from the game's folder or from here, or a bare file name anywhere in the game. */
+function modelPath(dir, file) {
+  const direct = isAbsolute(file) ? file : [join(dir, file), resolve(file)].find((p) => existsSync(p));
+  if (direct && existsSync(direct)) return direct;
+  return file === basename(file) ? filesUnder(dir, (n) => n === file)[0] ?? null : null;
+}
+const sidecar = (model) => model.replace(/\.(glb|gltf)$/i, '') + '.collision.json';
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+
+/** Check one sidecar against its model: rows of { label, ok, note }, and the points where a route failed. */
+async function checkOne(H, model, file) {
+  const rows = []; const marks = [];
+  const row = (label, ok, note = '') => rows.push({ label, ok, note });
+  const side = readJson(file);
+  if (!side || side.v !== 1 || !side.bake) { row('collision file', false, 'not a version 1 collision file: bake it again'); return { rows, marks, side: null, bake: null }; }
+  let bake = null;
+  try { bake = H.unpackBake(side.bake); } catch (e) { row('height grid', false, e.message); return { rows, marks, side, bake }; }
+  if (!existsSync(model)) { row('model', false, `${basename(model)} is not beside its collision file`); return { rows, marks, side, bake }; }
+  const bytes = readFileSync(model);
+  if (sha256(bytes) === side.sha256) row('model', true, 'the file that was baked');
+  else {
+    // The file changed. Whether the SURFACE changed is the mesh checksum's question: a re-export with new textures
+    // and the same triangles is still the same collider.
+    const why = H.bakeStale(bake, await modelTriangles(bytes));
+    row('model', !why, why ? `stale: ${why}` : 'the file changed, its triangles did not');
+  }
+  const proxies = Array.isArray(side.proxies) ? side.proxies : [];
+  const bad = H.checkProxies(proxies);
+  row('proxies', bad.length === 0, bad.length ? bad.join('; ') : `${proxies.length} authored`);
+  const mover = { ...DEFAULT_MOVER, ...(side.mover ?? {}) };
+  const world = H.createWorld({ ground: H.bakeField(bake), proxies: bad.length ? [] : proxies });
+  const routes = Array.isArray(side.routes) ? side.routes : [];
+  if (!routes.length) row('routes', true, 'none authored: add "routes" to the collision file to have a bot walk it');
+  for (const r of routes) {
+    const name = `route ${r.name ?? routes.indexOf(r) + 1}`;
+    const path = Array.isArray(r.path) ? r.path : [];
+    if (path.length < 2) { row(name, false, 'a route is { "name", "path": [{ "x", "y", "z" }, …] } with at least two points'); continue; }
+    const found = H.checkRoute(world, path, mover);
+    const run = H.traverse(world, path, mover);
+    for (const p of found) marks.push({ x: p.at.x, z: p.at.z, why: `${name}: ${p.why}` });
+    if (!run.ok) marks.push({ x: run.at.x, z: run.at.z, why: `${name}: the bot ${ENDED[run.why] ?? run.why} here` });
+    const first = found[0];
+    row(name, found.length === 0 && run.ok, found.length === 0 && run.ok ? `walked ${run.metres.toFixed(1)} m in ${run.seconds.toFixed(1)} s with a ${mover.arrival} m arrival radius`
+      : [first ? `${first.part} ${first.index}: ${first.why} (at ${first.at.x.toFixed(2)}, ${first.at.z.toFixed(2)})${found.length > 1 ? ` and ${found.length - 1} more` : ''}` : null, run.ok ? null : `the bot ${ENDED[run.why] ?? run.why} at ${run.at.x.toFixed(2)}, ${run.at.z.toFixed(2)} heading for point ${run.index}`].filter(Boolean).join('; '));
+  }
+  return { rows, marks, side, bake };
+}
+
+/** `collision bake`: the grid, the checksums and the plan, beside the model. Authored proxies, mover and routes are kept. */
+export async function collisionBake(root, id, file, { cell = 0.25, side = 'top', maxY, minY } = {}) {
+  const command = 'collision bake';
+  const dir = gameDir(root, id);
+  if (!dir) return { ok: false, command, why: `no game ${id} in this studio` };
+  const model = file ? modelPath(dir, file) : null;
+  if (!model) return { ok: false, command, why: `which model? ${file ? `${file} is not in games/${id}` : `homie-studio collision bake ${id} <model.glb>`}` };
+  if (!(Number(cell) > 0)) return { ok: false, command, why: '--cell is metres between posts, a positive number (0.25 suits a walkway)' };
+  const H = await heightfieldModules(root);
+  if (!H) return { ...NEEDS, command };
+  const bytes = readFileSync(model);
+  let bake;
+  try { bake = H.bakeMesh(await modelTriangles(bytes), { cell: Number(cell), side: side === 'under' ? 'under' : 'top', ...(maxY !== undefined ? { maxY: Number(maxY) } : {}), ...(minY !== undefined ? { minY: Number(minY) } : {}) }); } catch (e) { return { ok: false, command, why: e.message }; }
+  const out = sidecar(model);
+  const before = readJson(out) ?? {};
+  const doc = { v: 1, model: basename(model), sha256: sha256(bytes), bake: H.packBake(bake), proxies: Array.isArray(before.proxies) ? before.proxies : [], mover: { ...DEFAULT_MOVER, ...(before.mover ?? {}) }, routes: Array.isArray(before.routes) ? before.routes : [] };
+  writeFileSync(out, `${JSON.stringify(doc)}\n`);
+  const checked = await checkOne(H, model, out);
+  const svg = out.replace(/\.json$/, '.svg');
+  writeFileSync(svg, collisionSvg(bake, { proxies: doc.proxies, routes: doc.routes, problems: checked.marks, title: doc.model }));
+  const cover = bake.covered.reduce((n, c) => n + c, 0);
+  const rel = (p) => relative(root, p).split('\\').join('/');
+  return {
+    ok: true, command, game: id, model: rel(model), file: rel(out), plan: rel(svg), cell: bake.cell, posts: [bake.nx, bake.nz], covered: cover, triangles: bake.source.triangles, checksum: bake.source.checksum, rows: checked.rows,
+    lines: [`Baked ${rel(model)}: ${bake.nx} x ${bake.nz} posts at ${bake.cell} m (${(bake.nx - 1) * bake.cell} m by ${(bake.nz - 1) * bake.cell} m), ${cover} over the model, from ${bake.source.triangles} triangles.`,
+      `  ${rel(out)}  (authored "proxies", "mover" and "routes" in it are kept by a re-bake)`, `  ${rel(svg)}  the plan at true scale, 40 px to the metre`,
+      ...checked.rows.map((r) => `  ${r.ok ? 'ok  ' : 'FAIL'} ${r.label}${r.note ? `: ${r.note}` : ''}`)],
+  };
+}
+
+/** `collision check`: every collision file of a game (or one model's) against its model, its proxies and its routes. */
+export async function collisionCheck(root, id, file) {
+  const command = 'collision check';
+  const dir = gameDir(root, id);
+  if (!dir) return { ok: false, command, why: `no game ${id} in this studio` };
+  const H = await heightfieldModules(root);
+  if (!H) return { ...NEEDS, command };
+  let files;
+  if (file) { const model = modelPath(dir, file); if (!model || !existsSync(sidecar(model))) return { ok: false, command, why: `${file} has no collision file: homie-studio collision bake ${id} ${file}` }; files = [sidecar(model)]; }
+  else files = filesUnder(dir, (n) => n.endsWith('.collision.json'));
+  const rel = (p) => relative(root, p).split('\\').join('/');
+  const models = []; const lines = [];
+  for (const f of files) {
+    const side = readJson(f);
+    const model = join(dirname(f), side?.model ?? `${basename(f, '.collision.json')}.glb`);
+    const one = await checkOne(H, model, f);
+    if (one.bake) writeFileSync(f.replace(/\.json$/, '.svg'), collisionSvg(one.bake, { proxies: one.side?.proxies ?? [], routes: one.side?.routes ?? [], problems: one.marks, title: basename(model) }));
+    models.push({ file: rel(f), ok: one.rows.every((r) => r.ok), rows: one.rows });
+    lines.push(`${rel(f)}`, ...one.rows.map((r) => `  ${r.ok ? 'ok  ' : 'FAIL'} ${r.label}${r.note ? `: ${r.note}` : ''}`));
+  }
+  if (!files.length) lines.push(`No collision files in games/${id}. homie-studio collision bake ${id} <model.glb> makes one.`);
+  const failed = models.filter((m) => !m.ok);
+  return { ok: failed.length === 0, command, game: id, models, lines, ...(failed.length ? { why: `${lines.join('\n')}\n${failed.length} of ${models.length} collision file(s) need attention` } : {}) };
+}
+
+/** The CLI's `collision` command (bin/homie-studio.mjs hands it over whole). */
+export async function collisionCommand(root, sub, positional, flags) {
+  const id = positional[2] ?? (listGames(root).length === 1 ? listGames(root)[0].id : null);
+  const usage = 'homie-studio collision bake <game> <model.glb> [--cell 0.25] [--side top|under] [--max-y <m>] | collision check <game> [<model.glb>]';
+  if (!id || !['bake', 'check'].includes(sub)) return { ok: false, command: 'collision', why: usage };
+  if (sub === 'check') return collisionCheck(root, id, positional[3]);
+  return collisionBake(root, id, positional[3], { cell: flags.get('cell') ?? 0.25, side: flags.get('side') ?? 'top', maxY: flags.get('max-y'), minY: flags.get('min-y') });
+}

package/lib/decisions.mjs

@@ -12,7 +12,7 @@
  * Each change bumps the decision's `rev`; every asset records the revisions it was made under (assets/manifest.json
  * `made.under`), so a changed decision makes exactly those assets stale: listed and priced, never remade by itself.
  *
- * The file is private like CODEX.md: the remix source and a static game's served copy skip the whole codex/ folder.
+ * The file is private like CODEX.md: a static game's served copy skips the whole codex/ folder.
  * games/<id>/style.json (public, tiny) carries the palette and fonts a game, its landing and its title cards draw with.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
@@ -207,7 +207,7 @@ export const CATALOGUE = Object.freeze([
   ['cast.tiers', 'cast', 'What may each asset cost on a phone?', ['style.camera', 'game.devices'], (ctx) => {
     const big = ctx.players > 8;
     const v = { hero: { triangles: big ? 5000 : 8000, texturePx: 1024, kb: 1536, bones: 48 }, npc: { triangles: 3000, texturePx: 512, kb: 600, bones: 32 }, prop: { triangles: 1500, texturePx: 512, kb: 300 }, signature: { triangles: 5000, texturePx: 1024, kb: 800 }, kit: { triangles: 1000, texturePx: 512, kb: 200 }, scene: { drawCalls: 100, triangles: 150_000, textureMB: 48, firstPlayMB: 5 } };
-    return { value: v, label: `hero ${v.hero.triangles.toLocaleString('en-US')} · prop 1,500 · scene 150k triangles, 100 draws, 48 MB textures, 5 MB first play`, why: `phone first${big ? `; rooms of ${ctx.players} make heroes lighter` : ''}`, options: [] };
+    return { value: v, label: `hero ${v.hero.triangles.toLocaleString('en-US')} · prop 1,500 · scene 150k triangles, 100 draws, 48 MB textures, 5 MB shipped payload`, why: `phone first${big ? `; rooms of ${ctx.players} make heroes lighter` : ''}`, options: [] };
   }],
   ['cast.variation', 'cast', 'How many looks per character from one model?', [], (ctx) => ({ value: { paletteSwaps: Math.min(4, Math.max(2, ctx.players)), partSwaps: false, decals: false }, label: '4 palette swaps of the hero', why: 'team colours without another model', options: [] })],