@homie-rocks/studio 0.30.2 → 0.31.1

package/lib/routes.mjs

@@ -0,0 +1,240 @@
+/**
+ * THE ROUTES IN A STUDIO'S WRANGLER CONFIG: WHICH ARE THE STUDIO'S, AND WHICH ARE NOT ITS TO TOUCH.
+ *
+ * A studio on a custom domain shares that domain's Cloudflare zone with whatever else its owner runs there, and a
+ * zone's Worker routes are one list for all of it. Three things went wrong with that:
+ *
+ *   1. `deploy` writes wrangler.jsonc again from studio.json, and it used to write it without `routes`. A studio whose
+ *      owner had added the exact-host route its domain needed lost it at the next deploy, and the domain went back to
+ *      whichever Worker the zone's wildcard route names.
+ *   2. A zone that already has a wildcard route (`*example.com/*`, the router of another site) answers the studio's
+ *      hostname FIRST: a route is matched before a custom domain. The studio deployed fine and its own domain showed
+ *      somebody else's "not found". Nothing said why, or that one exact-host route fixes it.
+ *   3. A config that itself names a catch-all (`*` + `/*`) hands every hostname of the zone to the studio's Worker
+ *      the moment it deploys: another site on the zone stops answering.
+ *
+ * So: the routes the owner wrote for the studio's OWN hostnames (a custom domain, an exact host) are kept across
+ * every rewrite; a wildcard or catch-all route is never deployed by the studio unless studio.json says the zone is
+ * the studio's (`cloudflare.allowWildcardRoutes: true`); and a deploy whose domain answers as something else says
+ * which route is needed.
+ *
+ *   4. The zone ALREADY has another site's catch-all or wildcard route, and the studio's custom domain sits beside
+ *      it. The studio's own config is clean, so nothing above speaks; the route answers the studio's hostname first,
+ *      and the tempting repair (edit or remove that route) takes the other site down. So a deploy and its plan READ
+ *      the zone's Worker routes when the studio has a custom domain (readZoneRoutes: two GETs with the sign-in
+ *      Wrangler already has, never a write) and say, before anything is deployed, that the route is another site's,
+ *      must not be edited or removed, and which one line makes the studio's hostname its own (zoneFinding). A list
+ *      that cannot be read is said as unmeasured, never as fine.
+ *
+ * The studio never changes or removes a route it did not make: a zone's other routes belong to other Workers.
+ */
+import { readFileSync } from 'node:fs';
+import { configPath } from './studio.mjs';
+
+/** wrangler.jsonc as an object (whole-line comments left out, as the toolkit writes it), or null. */
+export function readConfig(root) {
+  try { return JSON.parse(readFileSync(configPath(root), 'utf8').replace(/^\s*\/\/.*$/gm, '')); } catch { return null; }
+}
+
+/** Wrangler takes a route as a string or an object, in `routes` or the older single `route`: one shape for all. */
+export function routesOf(config) {
+  const raw = [...(Array.isArray(config?.routes) ? config.routes : []), ...(config?.route ? [config.route] : [])];
+  return raw.map((r) => (typeof r === 'string' ? { pattern: r } : r)).filter((r) => r && typeof r.pattern === 'string' && r.pattern.trim());
+}
+
+/** The hostname part of a route's pattern ("play.example.com/*" gives "play.example.com"; a scheme is left out). */
+export function routeHost(route) {
+  return String(route?.pattern ?? '').trim().replace(/^[a-z*]+:\/\//i, '').split('/')[0].toLowerCase();
+}
+
+/**
+ * What kind of route it is:
+ *   'custom-domain'  `custom_domain: true`: Cloudflare makes the DNS record and the certificate for that one host
+ *   'exact-host'     one hostname, any path ("play.example.com/*"): only that host's requests
+ *   'catch-all'      every hostname of the zone ("*" + "/*")
+ *   'wildcard'       a `*` in the hostname ("*example.com/*", "*.example.com/*"): many hosts, maybe not the studio's
+ */
+export function routeKind(route) {
+  if (route?.custom_domain === true) return 'custom-domain';
+  const host = routeHost(route);
+  if (host === '*' || host === '') return 'catch-all';
+  return host.includes('*') ? 'wildcard' : 'exact-host';
+}
+
+/** Whether a route's hostname pattern covers a hostname ("*example.com" covers "play.example.com" and "example.com"). */
+export function routeCovers(route, hostname) {
+  const pattern = routeHost(route);
+  if (!pattern) return false;
+  const re = new RegExp(`^${pattern.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
+  return re.test(String(hostname ?? '').toLowerCase());
+}
+
+/**
+ * The config's routes, sorted into the studio's own (kept across every rewrite of wrangler.jsonc, exactly as written)
+ * and the wide ones (a wildcard or a catch-all).
+ */
+export function sortRoutes(config) {
+  const own = [];
+  const wide = [];
+  for (const r of routesOf(config)) (['custom-domain', 'exact-host'].includes(routeKind(r)) ? own : wide).push(r);
+  return { own, wide };
+}
+
+/**
+ * The routes a rewrite of wrangler.jsonc carries over from the one on disk: the studio's own, and the wide ones
+ * only when studio.json says the whole zone is the studio's. Null when there are none, so a studio without routes
+ * gets byte for byte the config it always got.
+ */
+export function keptRoutes(root, studio = null) {
+  const { own, wide } = sortRoutes(readConfig(root));
+  const kept = [...own, ...(studio?.cloudflare?.allowWildcardRoutes === true ? wide : [])];
+  return kept.length ? kept : null;
+}
+
+/**
+ * Why a deploy of this config would reach past the studio, or null. A wide route in the studio's own config makes
+ * its Worker answer for hostnames the studio does not have: said before anything is created or deployed.
+ */
+export function wideRouteRefusal(config, studio = null) {
+  if (studio?.cloudflare?.allowWildcardRoutes === true) return null;
+  const { own, wide } = sortRoutes(config);
+  if (!wide.length) return null;
+  const names = wide.map((r) => `"${r.pattern}"`).join(', ');
+  const all = wide.some((r) => routeKind(r) === 'catch-all');
+  const keep = own.length ? ` Its own route${own.length === 1 ? '' : 's'} (${own.map((r) => `"${r.pattern}"`).join(', ')}) stay${own.length === 1 ? 's' : ''}, and every deploy keeps ${own.length === 1 ? 'it' : 'them'}.` : '';
+  return {
+    needs: 'cloudflare-routes', routes: wide.map((r) => r.pattern),
+    why: `wrangler.jsonc gives this studio's Worker the route${wide.length === 1 ? '' : 's'} ${names}: ${all ? 'a catch-all, which answers for EVERY hostname of the zone' : 'a wildcard, which answers for more hostnames than the studio\'s own'}. Deploying it would take those hostnames away from whatever serves them now (another site on the same domain stops answering), so nothing was deployed or changed on Cloudflare. Take ${wide.length === 1 ? 'that route' : 'those routes'} out of "routes" in wrangler.jsonc: a studio needs only its own hostname, as { "pattern": "<its hostname>", "custom_domain": true } or { "pattern": "<its hostname>/*", "zone_name": "<the domain>" }.${keep} If the whole zone really is this studio's, say so in studio.json ("cloudflare": { "allowWildcardRoutes": true }) and deploy again.`,
+  };
+}
+
+/** The apex a hostname most likely belongs to ("play.example.com" gives "example.com"): a suggestion, never a lookup. */
+export function likelyZone(hostname) {
+  const parts = String(hostname ?? '').toLowerCase().split('.').filter(Boolean);
+  return parts.slice(-2).join('.');
+}
+
+/** The exact-host route that makes a zone's Worker routes send one hostname to this studio's Worker. */
+export function exactRouteFor(hostname, zone = likelyZone(hostname)) {
+  return { pattern: `${String(hostname).toLowerCase()}/*`, zone_name: zone };
+}
+
+/**
+ * The studio's custom domain answered, but not as this studio. With no exact-host route for that hostname in the
+ * config, the likeliest reason is another Worker's route on the zone that covers it (a wildcard, or a catch-all):
+ * a route is matched before a custom domain. Says which route is needed and that the other one is left alone; with
+ * the exact-host route already there, says to wait and what to look at instead.
+ */
+export function shadowedDomain(config, hostname, answer = {}) {
+  const host = String(hostname ?? '').toLowerCase();
+  const own = sortRoutes(config).own;
+  const exact = own.find((r) => routeKind(r) === 'exact-host' && routeHost(r) === host);
+  const said = answer.status ? `answered ${answer.status}${answer.said ? ` ("${answer.said}")` : ''}` : 'answered';
+  if (exact) {
+    return { shadowed: false, why: `https://${host} ${said}, not as this studio, although wrangler.jsonc has its exact-host route ("${exact.pattern}"). A new route can take a minute to apply; if it stays like this, look at the zone's Workers Routes in the Cloudflare dashboard for a more specific route on that hostname.` };
+  }
+  const route = exactRouteFor(host);
+  return {
+    shadowed: true, route,
+    why: `https://${host} ${said}, not as this studio: something else on the domain answers that hostname first. The usual reason is another Worker's route on the same zone that covers it (a wildcard like "*${route.zone_name}/*", or a catch-all): Cloudflare matches a route before a custom domain. The studio does not touch that route (it is not the studio's). Add the studio's own exact-host route to "routes" in wrangler.jsonc, which wins over a wildcard for this one hostname, and deploy again: ${JSON.stringify(route)} (zone_name is the domain as it is named in Cloudflare). Every deploy keeps it.`,
+  };
+}
+
+/* ------------------------------------------------------------------ the zone's routes, beside the studio's domain */
+
+const CF_API = 'https://api.cloudflare.com/client/v4';
+
+/** The zones a hostname may be in, likeliest first: the ones the config's routes name, then each parent of the hostname. */
+export function zoneCandidates(hostname, config = null) {
+  const parts = String(hostname ?? '').toLowerCase().split('.').filter(Boolean);
+  const named = routesOf(config).map((r) => String(r.zone_name ?? '').toLowerCase()).filter(Boolean);
+  const parents = [];
+  for (let i = 0; i <= parts.length - 2; i += 1) parents.push(parts.slice(i).join('.'));
+  return [...new Set([...named, ...parents])].slice(0, 6);
+}
+
+/**
+ * The Worker routes of the zone a hostname is in, READ from Cloudflare (GET /zones?name=…, then GET
+ * /zones/<id>/workers/routes) with headers the toolkit already has (lib/brain-probe.mjs cloudflareAuth: Wrangler's
+ * own sign-in). { read: true, zone: { id, name }, routes: [{ pattern, script }] }, or { read: false, why } when it
+ * could not be read (no sign-in, a sign-in that may not read the zone, no such zone on it, no network). It never
+ * writes. `fetchFn` stands in for the network in tests.
+ */
+export async function readZoneRoutes({ hostname, config = null, headers = null, fetchFn = globalThis.fetch, base = CF_API, ms = 10_000 } = {}) {
+  if (!headers) return { read: false, why: 'this computer has no Cloudflare sign-in to read them with' };
+  const root = String(base).replace(/\/+$/, '');
+  const get = async (path) => {
+    const res = await fetchFn(`${root}${path}`, { headers: { ...headers, accept: 'application/json', 'user-agent': 'homie-studio-deploy' }, signal: AbortSignal.timeout(ms) });
+    let body = null;
+    try { body = await res.json(); } catch { body = null; }
+    return { status: res.status, ok: res.ok && body?.success !== false, result: Array.isArray(body?.result) ? body.result : null };
+  };
+  const refused = (status) => (status === 401 || status === 403 ? 'this Cloudflare sign-in may not read the domain\'s routes' : `Cloudflare answered ${status}`);
+  try {
+    let zone = null;
+    for (const name of zoneCandidates(hostname, config)) {
+      const r = await get(`/zones?name=${encodeURIComponent(name)}`);
+      if (!r.ok || !r.result) return { read: false, why: refused(r.status) };
+      const hit = r.result.find((z) => String(z?.name ?? '').toLowerCase() === name && z?.id);
+      if (hit) { zone = { id: String(hit.id), name }; break; }
+    }
+    if (!zone) return { read: false, why: `no domain that ${String(hostname).toLowerCase()} belongs to is on the Cloudflare account this computer is signed in to` };
+    const r = await get(`/zones/${encodeURIComponent(zone.id)}/workers/routes`);
+    if (!r.ok || !r.result) return { read: false, zone, why: refused(r.status) };
+    return { read: true, zone, routes: r.result.filter((x) => typeof x?.pattern === 'string' && x.pattern.trim()).map((x) => ({ pattern: x.pattern.trim(), script: x.script ? String(x.script) : null })) };
+  } catch (error) {
+    return { read: false, why: error?.name === 'TimeoutError' ? `Cloudflare did not answer in ${Math.round(ms / 1000)} s` : `Cloudflare could not be reached (${String(error?.cause?.code ?? error?.code ?? error?.message ?? error).slice(0, 80)})` };
+  }
+}
+
+const NOT_OURS = 'Never edit or remove a route this studio did not make';
+
+/**
+ * What the zone's routes mean for a studio on a custom domain, in words for the plan, the terminal and the tool
+ * result. `zone` is readZoneRoutes' answer; `worker` the studio's own Worker; `config` its wrangler.jsonc.
+ *   state 'clear'       no other route covers the studio's hostname: nothing to say (`why` is null)
+ *   state 'foreign'     another site's wildcard or catch-all covers it and the studio has no exact-host route of its
+ *                       own: `warning`, with the one line to add (`route`, `line`)
+ *   state 'own-route'   another site's route covers it, and the studio's own exact-host route already wins for its
+ *                       hostname: `why` says to leave the other route alone
+ *   state 'taken'       the studio's own hostname is routed to another Worker: only the person can decide that
+ *   state 'unmeasured'  the list could not be read: said as that, with the reason
+ */
+export function zoneFinding({ hostname, worker = null, config = null, zone = null } = {}) {
+  const host = String(hostname ?? '').toLowerCase();
+  const guess = zone?.zone?.name ?? likelyZone(host);
+  const route = exactRouteFor(host, guess);
+  const line = JSON.stringify(route);
+  const ownInConfig = sortRoutes(config).own.find((r) => routeKind(r) === 'exact-host' && routeHost(r) === host) ?? null;
+  if (!zone?.read) {
+    return {
+      state: 'unmeasured', host, zone: zone?.zone?.name ?? null, foreign: [], route, line,
+      why: `Not checked: whether another site's route on the domain covers ${host} (${zone?.why ?? 'not read'}). That is unmeasured, not a pass. If ${host} answers as something else after a deploy, the fix is the studio's own exact-host route in "routes" in wrangler.jsonc, ${line} (zone_name is the domain as Cloudflare names it), which every deploy keeps. ${NOT_OURS}.`,
+    };
+  }
+  const others = zone.routes.filter((r) => r.script !== worker && routeCovers(r, host)).map((r) => ({ pattern: r.pattern, script: r.script, kind: routeKind(r) }));
+  const taken = others.filter((r) => r.kind === 'exact-host');
+  const wide = others.filter((r) => r.kind !== 'exact-host');
+  const said = (list) => list.map((r) => `"${r.pattern}" (${r.script ? `Worker ${r.script}` : 'no Worker: it turns Workers off for what it covers'})`).join(', ');
+  const base = { host, zone: zone.zone.name, route, line };
+  if (taken.length) {
+    return {
+      ...base, state: 'taken', foreign: others,
+      warning: `${host} itself is routed to another Worker on ${zone.zone.name}: ${said(taken)}. That route is not this studio's, so the studio does not take, edit or remove it, and neither should you: whatever it serves would stop answering. Only the person can decide to hand the hostname over, in the domain's Workers Routes in the Cloudflare dashboard; or give the studio a hostname nothing else uses (studio.json cloudflare.domain).`,
+    };
+  }
+  if (!wide.length) return { ...base, state: 'clear', foreign: [], why: null };
+  const ownLive = zone.routes.find((r) => r.script === worker && routeKind(r) === 'exact-host' && routeHost(r) === host) ?? null;
+  const all = wide.some((r) => r.kind === 'catch-all');
+  const them = `${wide.length === 1 ? 'a route' : 'routes'} that cover${wide.length === 1 ? 's' : ''} ${host} and ${wide.length === 1 ? 'is' : 'are'} not this studio's: ${said(wide)}`;
+  if (ownInConfig || ownLive) {
+    return {
+      ...base, state: 'own-route', foreign: wide,
+      why: `${zone.zone.name} has ${them}. ${wide.length === 1 ? 'It belongs' : 'They belong'} to another site on this domain and must not be edited or removed. The studio's own exact-host route ("${(ownInConfig ?? ownLive).pattern}") wins over ${wide.length === 1 ? 'it' : 'them'} for this one hostname, and every deploy keeps it: nothing to change.`,
+    };
+  }
+  return {
+    ...base, state: 'foreign', foreign: wide,
+    warning: `${zone.zone.name} already has ${them}. ${wide.length === 1 ? 'That route belongs' : 'Those routes belong'} to another site on this domain: ${wide.length === 1 ? 'it' : 'they'} must not be edited or removed, here or in the Cloudflare dashboard, or that site stops answering. Cloudflare matches a route before a custom domain, so ${all ? 'the catch-all' : 'the wildcard'} answers ${host} first and the studio's own domain would show the other site. The one safe fix is the studio's own exact-host route, which wins over a wider route for this one hostname only and which every deploy keeps. Add this line to "routes" in wrangler.jsonc and deploy: ${line} (or \`homie-studio deploy --own-route\`, which adds exactly that line and nothing else).`,
+  };
+}

package/lib/scaffold.mjs

@@ -36,6 +36,11 @@ import { themeFile } from './site.mjs';
 export const COMPAT_DATE = '2026-06-01';
 /** 4.135.0 or later: Worker Previews (`wrangler preview`, a Durable Object namespace per Preview). */
 export const WRANGLER_VERSION = '4.145.0';
+/**
+ * The TypeScript a new studio asks for, so `build --types` (and an editor) has a compiler: the studio's own
+ * devDependency, never one of the toolkit's (a studio that never checks types pays nothing for it at runtime).
+ */
+export const TYPESCRIPT_VERSION = '5.9.3';
 
 export function slugify(name) {
   return String(name ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
@@ -58,7 +63,7 @@ export function slugify(name) {
  * No `database_id` until one is known: Wrangler (4.45.0+) and the Deploy to Cloudflare flow create the database
  * the binding names and keep it linked.
  */
-export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', ai = false }) {
+export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', ai = false, routes = null }) {
   const at = layout === 'site' ? { schema: '../node_modules', main: 'src/worker.mjs', dist: './dist', migrations: 'migrations' }
     : { schema: 'node_modules', main: 'site/src/worker.mjs', dist: './site/dist', migrations: 'site/migrations' };
   const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }];
@@ -73,6 +78,10 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     compatibility_flags: ['global_fetch_strictly_public'],
     workers_dev: true,
     preview_urls: true,
+    // The studio's own custom-domain and exact-host routes, as its owner wrote them: this file is written again by
+    // every deploy, and one written without them sends the studio's domain back to whatever else the zone routes
+    // (lib/routes.mjs). A studio without routes gets no key at all.
+    ...(routes?.length ? { routes } : {}),
     assets: { directory: at.dist, binding: 'ASSETS', run_worker_first: true },
     durable_objects: { bindings: rooms },
     migrations: [{ tag: 'v1', new_sqlite_classes: ['Table', 'Lobby'] }],
@@ -132,7 +141,23 @@ studio's pinned copy, never a registry lookup of the bare name.
   how hard making it multiplayer will be; \`port import\` brings it into \`games/\`, \`port check\` runs the
   owner tests (real touch, a late joiner, a killed host, two browsers finishing a round). The Homie
   plugin's \`port\` skill does the whole job.
-- \`npm run build\` — bundle every game into \`site/dist\`.
+- \`npm run build\` — bundle every game into \`site/dist\`. It builds in a folder of its own and puts the result
+  in place only when all of it is there: a game that does not build fails the command (a non-zero exit) and
+  leaves \`site/dist\` exactly as it was, and nothing running from \`site/dist\` loses its files. Each game's line
+  says \`changed\`, \`unchanged\` or \`new\` (against the build before) and its build hash;
+  \`site/dist/_site/build.json\` keeps the same, and the live site says each game's hash in
+  \`/.well-known/homie-studio.json\` (\`games[].build.hash\`), so "is the live game the one I built?" is one
+  comparison. A game's bundle is named by its content (\`assets/main-<HASH>.js\`; its built \`index.html\` names
+  it, so write \`./assets/main.js\` in the game's own \`index.html\` as always), and \`await import('./later')\` in
+  a game becomes a file of its own that loads when asked for: a 3D game can show its first screen before the
+  rest of its code arrives.
+- \`npx --no-install homie-studio build --types\` — the same, after checking the games' TypeScript (the build
+  itself only strips types; a type error ships otherwise). It uses the studio's own \`typescript\`
+  (\`npm install --save-dev typescript\` if this studio has none), reads a game's own \`tsconfig.json\` when it
+  has one, and a type error in a game's files stops the build.
+- \`npx --no-install homie-studio preview <id>\` — one built game's files at an address on this computer
+  (\`http://127.0.0.1:8788/\`), nothing else: no Wrangler, no rooms, no database. For a capture, a screenshot or
+  a perf script; the game plays offline with its bots. Ctrl-C stops it.
 - \`npm run dev\` — the whole site locally (pages, the netplay relay in a local
   Durable Object, D1): open the printed address in two browsers and they share a room.
   Stop it with \`npx --no-install homie-studio dev --stop\` (this studio's dev server only;
@@ -199,14 +224,18 @@ studio's pinned copy, never a registry lookup of the bare name.
   page is not found.
 - **A new studio goes live with its Home only:** its name and "First game coming soon", with what is on the way
   (games, posts, music and videos), until its first game, song or video is published. A post shows there at once.
-- **Every game gets a landing** at \`/<id>/\`: a full-bleed hero from the game's own footage
-  (\`games/<id>/hero/wide.mp4\` and \`tall.mp4\`, or a trailer in \`videos/\` with \`for.game\`), else its cover
-  with slow motion; the pitch, a big Play button into a public room, phone / computer / TV with the join code,
-  live rooms, how to play, credits, and "Make a game like this". Give it words in game.json's \`landing\` block
+- **Every game gets a landing** at \`/<id>/\`: a full-bleed hero from the game's own files in
+  \`games/<id>/hero/\`: \`wide.jpg\` (16:9, 1280×720 or larger) and \`tall.jpg\` (9:16, 720×1280, what an upright
+  phone gets) for a still, and \`wide.mp4\` and \`tall.mp4\` in the same shapes for footage (a silent loop of 8 to
+  15 s, under 3 MB each); else a trailer in \`videos/\` with \`for.game\`; else its cover with slow motion. Any
+  size is shown, cropped to fill; one file may be 25 MiB at most. Then the pitch, a big Play button into a public room, phone / computer / TV with the join code,
+  live rooms, how to play and credits. Give it words in game.json's \`landing\` block
   (\`pitch\`, \`about\`, \`controls\`, \`howToPlay\`, \`credits\`) and art with the plugin's \`art\` and \`video\` skills.
 - **The look** is \`site/theme.json\` (colours, fonts, corner radius, a logo). Anything in \`site/\` wins: a whole
   page in \`site/pages/\`, a piece of every page in \`site/partials/\`, files in \`site/public/\`, extra CSS in
-  \`site/theme.css\` (\`site/README.md\`). A game whose picture is white or cream gets a light landing with
+  \`site/theme.css\` (\`site/README.md\`). **The order of the games** everywhere (Home, the Games page, the cards,
+  the directory's manifest) is studio.json \`"site": { "order": ["<id>", "<id>"] }\`: those first, as named, the
+  rest by id; \`"site": { "featured": "<id>" }\` picks Home's hero. A game whose picture is white or cream gets a light landing with
   game.json \`"landing": { "scheme": "light" }\` (a dark tint would turn it grey).
 - **Cards and the directory** show each game's landing still (\`hero/wide.jpg\`), else its cover. A song without
   a cover of its own shows the music manifest's \`cover\`, else its game's still.
@@ -243,14 +272,47 @@ studio's pinned copy, never a registry lookup of the bare name.
   Auto cuts to it (\`NETPLAY.md\` section 16). A game that never reads \`viewSeat\` is watched as its overview. A
   game with hidden hands or roles says game.json \`"watch": "overview"\` (the whole room only) or \`false\` (no
   watch door); a private or invite-only game is watched only by those it lets in.
+- **A touch game guards its own page.** The play page refuses text selection, the long-press callout and page
+  gestures around the game's frame, but a long press INSIDE the game (a HUD label, a button's text, the canvas) is
+  the game's own: on a phone it raises copy/paste and the thumb's touch is lost. Call
+  \`guardGestures({ touch: 'canvas, [data-action]' })\` from \`@homie-rocks/studio/netplay\` once, early: no
+  selection, no callout, no pan or pinch on the gameplay surfaces; text fields, links and ordinary buttons keep the
+  browser's own behaviour (\`NETPLAY.md\` section 24). Try it with a real thumb on a real phone: emulated touch
+  does not raise the callout.
+- **The frame has no storage of its own.** The game runs in a sandboxed frame without \`allow-same-origin\` (a
+  stranger's game must never read this site's storage or the owner's session), so \`localStorage\` throws inside it.
+  A setting or a personal best goes in \`net.prefs\` (\`net.prefs.string('quality', 'high')\`, \`net.prefs.number('volume', 0.8, { min: 0, max: 1 })\` after \`await net.prefs.ready\`: the typed readers give your fallback for a missing key, never a null that turns into 0,
+  \`net.prefs.set('quality', 'low')\`: the play page keeps 16 KB a game); progress that must last goes in saves.
+  The play page's \`?debug\` and \`?q=…\` reach the game as \`net.params\`, with any names game.json
+  \`"netplay": { "params": ["seed"] }\` declares (\`NETPLAY.md\` section 24).
+- **game.json \`"netplay"\`** also takes \`"version"\` (the game's revision: bump it when a change makes an
+  already-open tab unable to play with a new one; rooms then run one build at a time and the old tab is told to
+  reload) and \`"stallMs"\` (1500 to 10000: how long a host may send no snapshot before the room is handed on, for
+  a heavy 3D game). \`NETPLAY.md\` sections 22 and 23.
 - Change a game in small steps, build, and look at it (\`dev\`, then \`check\`).
 - A game's id is its URL (\`/<id>/\`); keep it once published.
-- **Remixing.** A public game shares its source at \`/games/<id>/source.json\`, with who made it (the studio, the
-  game, its page) and the licence its owner picks in game.json \`"license"\`: \`"remix-with-credit"\` (the
-  default), \`"remix-freely"\` or \`"no-remix"\`, and \`{ "kind": "…", "spdx": "MIT" }\` to name a licence too.
-  \`npx --no-install homie-studio game remix <source.json> --id <new id>\` brings another studio's game in as a new
-  game here: its game.json \`remixOf\` says "Remix of <game> by <studio>" with a link back, and its landing and
-  credits show it; keep that credit. A game whose licence says no remix is refused.
+- **A game's own licence.** game.json \`"license": "MIT"\` (any SPDX identifier) is said on the game's page; a game
+  that names none says nothing. It is a statement about the game, not an offer of its source: no game is handed
+  over whole. A game.json that still has \`"remix"\`, \`"share"\`, \`landing.make\` or one of the old licence words
+  builds as before with one note (remix was retired; delete them). A game that has \`"remixOf"\` was made from another
+  studio's game: keep it, it is the credit its landing and credits show ("Based on <game> by <studio>").
+- **A 3D game's models.** \`createModels()\` warns in development about a model over 1,500 triangles or 300 KB,
+  which is a small prop's budget. A game whose models are bigger on purpose says so once in its game.json:
+  \`"assets": { "budgets": { "triangles": 8000, "bytes": 1500000 } }\` (per model; \`texturePx\` and \`materials\`
+  too). A game copied from a 3D starter has \`"assets": "library"\` there, which only mattered when it was copied:
+  replace it with the object.
+- **Parts: how games build on each other.** A part is a piece of a game its studio chose to share (a creature, a
+  level generator, a camera, a bot brain, an audio pack), never the whole game. **Before writing a system from
+  scratch, look for one**: the \`@homie-rocks/*\` packages (npm) have the general mechanism (camera, input, audio,
+  effects), and \`parts_find\` searches the pieces other studios shared; packages are not parts. \`part_add\` with
+  \`"<studio site>/<part id>"\` fetches one exact version, checks every file, copies it into \`parts/_vendor/\` where
+  the studio owns and tunes it (its \`tuning.json\` survives a newer version), credits it in the game, and lets npm
+  install the packages it builds on; the game imports it in one line, \`import … from '@parts/<studio site>/<part
+  id>'\`. Write in the game's CODEX (Built from) what came from where. A reusable piece of this studio's own game
+  becomes a part with \`part_new\` (it is lifted out and the game keeps working). **A part is private until the
+  person asks to share it** (\`part_share\`, with an SPDX licence they picked and who to credit); it is live after
+  the next deploy. Without the chat tools, the same jobs are \`npx --no-install homie-studio parts
+  find|add|new|share\`. The design is \`node_modules/@homie-rocks/studio/parts/PARTS.md\`.
 - **Progress that lasts** (a character, unlocks, a collection, days of play) goes in **saves**, never in the room:
   a room forgets everything 60 s after its last player leaves. game.json \`"saves": true\` and
   \`createSaves\` from \`@homie-rocks/studio/saves\` (\`node_modules/@homie-rocks/studio/saves/SAVES.md\`): per
@@ -301,8 +363,7 @@ studio's pinned copy, never a registry lookup of the bare name.
   lean, look-at, crowds; every number a Game Lab tunable); \`game new <id> --from hero-rush-3d\` starts one. The
   plugin's \`animate\` skill has the rest.
 - **Licences**: a public game ships only assets whose licence allows it (CC0, CC BY with credit, the studio's own,
-  generated); \`publish\` refuses an asset with no licence record. A remix gets each redistributable model,
-  checked by SHA-256, and a grey placeholder for the rest.
+  generated); \`publish\` refuses an asset with no licence record.
 
 ## Running live games (the back office)
 
@@ -310,12 +371,12 @@ studio's pinned copy, never a registry lookup of the bare name.
   the owner a one-time sign-in link): every live room of every game, who is in it (handles; accounts once players
   sign in), bots, the round and uptime, refreshing by itself; Kick (that player cannot come back to that room for
   the minutes chosen), Mute (their chat and emotes reach nobody), Announce (one line every player sees), Close a
-  room; and per game: launch state, Remixable, players per room and invites.
+  room; and per game: launch state, players per room and invites.
 - **Launch states:** \`private\` (only the owner, signed in; \`office link --to /<id>/play\` signs the owner's phone
   in), \`invite\` (an invite-only beta: \`office invite <id>\` makes invite links and codes, each for one browser or
   as many as \`--uses\` says), \`public\` (the default; listed). A game that is not public is in no list and not in
   the directory manifest, so the directory drops it the next time it reads the studio. A new game stays private
-  from its first deploy with \`"launch": "private"\` in its game.json. **Remixable** publishes or withdraws its source.
+  from its first deploy with \`"launch": "private"\` in its game.json.
 - The owner is recognised in their own games: signed in, their play page has a small Owner button (tap a player:
   Mute, Kick; Announce). Nobody else's page has it.
 - **From the AI:** \`npx --no-install homie-studio office\` lists who is playing now; \`office announce "<text>"\` and
@@ -428,8 +489,8 @@ chat's card follows the work from then on) and, for a studio still being set up,
   \`"games/*/game.json"\`) and \`"budget"\` (\`{ "usd": <n>, "credits": <n> }\`: the most the studio's media jobs spend
   in all). In Claude Code, the Homie plugin's mod holds an edit to a protected file, a deploy, and a paid call past
   the budget until the person says Proceed, and takes keys out of command output. In Codex the plugin's hooks hold
-  the same calls until the person's own \`proceed <code>\`, once the person has trusted them; in Grok Build nothing
-  holds them yet. \`npx --no-install homie-studio setup status --client codex\` (or \`grok\`) says whether Homie's
+  the same calls until the person's own \`proceed <code>\`, once the person has trusted them, and in Grok Build once
+  the plugin is trusted. \`npx --no-install homie-studio setup status --client codex\` (or \`grok\`) says whether Homie's
   holds are on, and while they are off, ask before each of those yourself. When a call is refused, say what you
   meant to do and why; do not retry it unless the person asks.
 
@@ -485,7 +546,7 @@ That line is all the session is given. The brief (what the person asked for, in
 
 1. \`npm install\` (once per session).
 2. \`npx --no-install homie-studio handoff hb_…\` prints the brief and the steps for this kind of build (a new
-   studio's first session, a new game, a port, a remix or a change). It takes the build once, so the chat's card
+   studio's first session, a new game, a port or a change). It takes the build once, so the chat's card
    follows the work, and for a studio still being set up it checks in from this repository.
 3. If it says this session's network does not reach homie.rocks and the Homie connector's tools are in this session,
    call \`build_progress\` with \`{ "build": "hb_…" }\`: its answer carries the same brief. Otherwise tell the person
@@ -554,7 +615,7 @@ anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site
 | \`theme.json\` | The look: \`bg\`, \`fg\`, \`accent\`, \`glow\` colours, \`display\` and \`text\` fonts (\`fonts\` loads a file from \`public/\`), \`radius\`, \`mark\` (a logo). Or \`palette\`: neon, dock, gold, acid, ember, orchid, tide, candy. |
 | \`theme.css\` | Extra CSS on every page (restyle anything, the "Made with Homie" footer included). |
 | \`partials/<name>.html\` | A piece of every page: \`head\`, \`header\`, \`footer\`, \`home\` (a band on Home), \`game\` (a band on every game's landing), \`game-<id>\` (on one game's), \`post\`. |
-| \`pages/<path>/index.html\` | A whole page at \`/<path>/\`, instead of the generated one (\`pages/<id>/index.html\` replaces a game's landing) or beside them (\`pages/about/index.html\`). It may borrow \`<!-- homie:style -->\`, \`<!-- homie:header -->\`, \`<!-- homie:footer -->\`, \`<!-- homie:script -->\`, and \`<!-- homie:schema -->\` in its \`<head>\` (the page's structured data for search engines). |
+| \`pages/<path>/index.html\` | A whole page at \`/<path>/\`, instead of the generated one (\`pages/<id>/index.html\` replaces a game's landing) or beside them (\`pages/about/index.html\`). It may borrow \`<!-- homie:style -->\`, \`<!-- homie:header -->\`, \`<!-- homie:footer -->\`, \`<!-- homie:script -->\`, and \`<!-- homie:schema -->\` in its \`<head>\` (the page's structured data for search engines). A Home of your own (\`pages/index.html\`) takes the generated hero with \`<!-- homie:home-hero -->\` (the featured game) or \`<!-- homie:home-hero <id> -->\` (that game); a game's own hero files are served at \`/games/<id>/_landing/<file>\` (\`wide.jpg\`, \`tall.jpg\`, \`wide.mp4\`, \`tall.mp4\`) if a page of yours needs one by address (\`/api/games\` says each exactly, in \`landing.hero\`). |
 | \`public/\` | Files served as they are, at the same path (\`public/fonts/x.woff2\` is \`/fonts/x.woff2\`). A \`robots.txt\`, \`sitemap.xml\` or \`llms.txt\` here replaces the one the site makes. |
 
 \`src/worker.mjs\` and \`migrations/\` are the Worker (its config is \`wrangler.jsonc\`, at the studio's root); \`dist/\` is the build (not committed).
@@ -620,7 +681,7 @@ export function studioFiles({ name, slug, homie, template = false }) {
     private: true,
     type: 'module',
     scripts: { dev: 'homie-studio dev', build: 'homie-studio build', deploy: 'homie-studio deploy', check: 'homie-studio check', studio: 'homie-studio' },
-    devDependencies: { '@homie-rocks/studio': packageSpec(homie), wrangler: WRANGLER_VERSION },
+    devDependencies: { '@homie-rocks/studio': packageSpec(homie), typescript: TYPESCRIPT_VERSION, wrangler: WRANGLER_VERSION },
     // What Cloudflare's "Deploy to Cloudflare" form says about each setting (package.json `cloudflare.bindings`).
     cloudflare: {
       label: 'Homie studio',