@homie-rocks/studio 0.30.1 → 0.31.0

package/lib/mcp-tools.mjs

@@ -2,7 +2,7 @@
  * THE LOCAL MCP SERVER'S TOOLS (`homie-studio mcp`, lib/mcp.mjs): the studio toolkit as MCP tools, so the Claude
  * desktop app (through the Homie extension), Claude Code or any MCP client builds games in the SAME chat that shows
  * the cards. Where a tool overlaps the remote Homie MCP (homie.rocks/mcp) it has the same name and the same input
- * shape: studio_scaffold, studio_card, game_make, game_remix, game_port, preview_run, studio_deploy,
+ * shape: studio_scaffold, studio_card, game_make, game_port, preview_run, studio_deploy,
  * studio_publish, build_open, build_progress, build_stop. The remote ones say what to run; these run it, here.
  *
  * Long work never holds a tool call: a check, a playtest, a deploy or an npm install starts as a job (lib/jobs.mjs)
@@ -28,7 +28,10 @@ import { cliJob, findNode, getJob, installJob, installed, jobView, runningJobs,
 import { Feed, currentId, publicFeed, readFeed, startProgress } from './progress.mjs';
 import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
-import { GAME_ID, PACKAGE_ROOT, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
+import { GAME_ID, PACKAGE_ROOT, findStudio, listGames, readLocal, readStudio, siteUrl } from './studio.mjs';
+import { runningDev } from './dev.mjs';
+import { deployWords } from './deploy-state.mjs';
+import { beforeLine, partsForListing, publishesSoFar } from './directory.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { compareVersions, whatsNew, whatsNewLines } from './changelog.mjs';
 import { pinnedVersion } from './upgrade.mjs';
@@ -37,6 +40,9 @@ import { detectLocalAi } from './local-ai.mjs';
 import { LAB_PORT, runningLab } from './lab.mjs';
 import { pictureFor } from './pictures.mjs';
 import { ART_UI, artToolDefs } from './art-tools.mjs';
+// GAME PARTS (parts/PARTS.md): parts_find, part_add, part_new and part_share are lib/parts-tools.mjs.
+import { PARTS_FIRST, partsToolDefs } from './parts-tools.mjs';
+import { partsPlanLines } from './parts-build.mjs';
 import { FEEDBACK_APPS, FEEDBACK_KINDS, FEEDBACK_LIMITS, appOf, cleanNote, draftId, noteBlock, sendNote, withLine } from './feedback.mjs';
 
 export const UI = Object.freeze({
@@ -285,12 +291,9 @@ function coverData(dir) {
   return null;
 }
 
+/** This studio's dev server when it really runs (lib/dev.mjs: a stale record, or a recycled process id, is not one). */
 function devOf(root) {
-  try {
-    const rec = JSON.parse(readFileSync(join(workerDir(root), '.wrangler', 'homie-dev.json'), 'utf8'));
-    process.kill(rec.pid, 0);
-    return { url: `http://127.0.0.1:${rec.port}`, port: rec.port, pid: rec.pid };
-  } catch { return null; }
+  try { return runningDev(root); } catch { return null; }
 }
 
 function published(root, kind) {
@@ -419,6 +422,10 @@ function buildCard(ctx, root, found) {
     feed.error ? `Last error: ${feed.error}` : null,
     ...(run?.look ? [`Pictures of the site (file_read shows one): ${run.look.join(', ')}`] : []),
     ...jobs.filter((j) => j.state === 'failed').map((j) => `${j.label} failed: ${j.result?.why ?? j.tail.slice(-2).join(' ')}`),
+    // A deploy that went through: which games it changed with each one's content hash, and anything it had to say
+    // about the studio's domain or the directory (lib/cloudflare.mjs).
+    ...jobs.filter((j) => j.result?.command === 'deploy' && j.result?.ok && (j.result.games ?? []).some((g) => g.hash)).map((j) => `Deployed: ${j.result.games.map((g) => `${g.id} ${deployWords(g)}`).join('; ')}.`),
+    ...jobs.filter((j) => j.result?.command === 'deploy').flatMap((j) => (j.result.notes ?? []).map((n) => `Note: ${n}`)),
     feed.state === 'running' ? 'The card on screen follows it live; you need not call this again to watch it.' : null,
   ].filter(Boolean).join('\n');
   // A check, playtest or deploy inside a build the person opened (build_open) ends before the build does: say so.
@@ -857,7 +864,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'game_make', title: 'Make a multiplayer game',
-      description: 'Make a game in the studio from a multiplayer starter, under the id you choose, to change into the person\'s game: gem-rush (an arena: every browser renders, one hosts the rules, bots fill empty seats, rounds restart), gem-rush-3d (the same arena in three.js, dressed with free CC0 models through @homie-rocks/studio/assets: the start for a 3D game), hero-rush-3d (the arena with animated CC0 heroes that run, jump and swing through @homie-rocks/studio/animate, a shared clip library per skeleton, a jump and a swing tuned in the Game Lab: the start for a 3D game with characters) or ember-vale (a hero who lasts for days, with cloud saves: for persistent games). In a new studio only once their game is planned (game_plan), or when they ask for a copy of a working starter; never as a first step. A planned game\'s codex stays.',
+      description: 'Make a game in the studio from a multiplayer starter, under the id you choose, to change into the person\'s game: gem-rush (an arena: every browser renders, one hosts the rules, bots fill empty seats, rounds restart), gem-rush-3d (the same arena in three.js, dressed with free CC0 models through @homie-rocks/studio/assets: the start for a 3D game), hero-rush-3d (the arena with animated CC0 heroes that run, jump and swing through @homie-rocks/studio/animate, a shared clip library per skeleton, a jump and a swing tuned in the Game Lab: the start for a 3D game with characters) or ember-vale (a hero who lasts for days, with cloud saves: for persistent games). In a new studio only once their game is planned (game_plan), or when they ask for a copy of a working starter; never as a first step. A planned game\'s codex stays. Before writing one of its systems from scratch, look for a piece of an existing game that does it (parts_find; part_add brings it in), and for the general mechanism in the @homie-rocks/* packages.',
       inputSchema: { type: 'object', properties: { id: str('The game\'s id (lowercase, digits, hyphens): its address'), name: str('The game\'s display name'), from: str('Starter id (default gem-rush)'), ...STUDIO_ARG }, required: ['id', 'name'] },
       annotations: { title: 'Make a game', ...RW },
       run: async (a) => {
@@ -883,24 +890,6 @@ export function toolDefs(ctx, avail = {}) {
         return ok(`games/${a.id} is ${a.name}, from the ${a.from ?? 'gem-rush'} starter (${(r.result?.files ?? []).length} files).${got}${install} Change it in games/${a.id}/src/main.ts: file_read it once (a long file in two or three reads), decide every change, and make them in ONE file_edit with an edits list (never a call per change: twenty single edits use up a turn before the game is checked); then build and preview_run; check proves two browsers finish a round.`, { kind: 'game', ...r.result });
       },
     },
-    {
-      name: 'game_remix', title: 'Remix a shared game',
-      description: 'Bring a game another studio shared in the Homie directory into this studio as a new game of its own. The original stays credited: game.json remixOf says "Remix of <game> by <studio>" with a link back, shown on the new game\'s landing and in its credits. A game whose owner\'s licence says no remix is refused.',
-      inputSchema: { type: 'object', properties: { game: str('The directory game: "<studio site>/<game id>" or its play URL'), id: str('The new game id in this studio'), name: str('Optional: its new name'), ...STUDIO_ARG }, required: ['game', 'id'] },
-      annotations: { title: 'Remix a game', ...RW, openWorldHint: true },
-      run: async (a) => {
-        const root = ctx.root(a.studio);
-        let site; let gameId;
-        try { const u = new URL(String(a.game ?? '')); site = u.origin; gameId = u.pathname.split('/').filter(Boolean)[0]; } catch { return fail('game is "<studio site>/<game id>" or its play URL'); }
-        if (!/^https:\/\//.test(site) || !GAME_ID.test(String(gameId ?? '')) || !GAME_ID.test(String(a.id ?? ''))) return fail('game is "https://<studio site>/<game id>", and id a new lowercase id');
-        const source = `${site}/games/${gameId}/source.json`;
-        const r = await cli(ctx, root, `game remix ${a.id}`, ['game', 'remix', source, '--id', a.id, ...(a.name ? ['--name', String(a.name).slice(0, 60)] : [])]);
-        if (!r.ended) return stillRunning(r.job, 'The remix');
-        if (r.job.code !== 0) return fail(`Not remixed: ${whyOf(r.job)}`);
-        const credit = r.result?.credit ? ` Its game.json credits the original: "${r.result.credit}"${r.result.page ? ` (${r.result.page})` : ''}, on its landing and in its credits; keep it.` : '';
-        return ok(`games/${a.id} is a remix of ${site}/${gameId} (${(r.result?.files ?? []).length} files).${credit}`, { kind: 'game', ...r.result });
-      },
-    },
     {
       name: 'game_port', title: 'Make an existing game multiplayer',
       description: 'Read an existing single-player web game on this computer and grade how hard making it multiplayer will be (easy, medium, hard, not a fit, with its risks); with id, also bring it into the studio as games/<id>/ for the port. studio_guide { "topic": "port" } has the whole job; check (and studio_run ["port","check",…]) proves it.',
@@ -928,7 +917,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'game_plan', title: 'Plan a game (its Game Codex)',
-      description: 'Step 4: start the game\'s Game Codex (games/<id>/CODEX.md, every section) and get the plan interview to run with the person: two or three questions a message, each with options and your pick, about game type and genre, style, devices, players and rooms, art and film, music and sound, and scope. A game is planned before it is made: with no game <id> yet, this starts its folder with only the codex. Fill CODEX.md from their answers in one call (file_write of the whole file, or one file_edit with an edits list), then game_codex shows it.',
+      description: 'Step 4: start the game\'s Game Codex (games/<id>/CODEX.md, every section) and get the plan interview to run with the person: two or three questions a message, each with options and your pick, about game type and genre, style, devices, players and rooms, art and film, music and sound, and scope. A game is planned before it is made: with no game <id> yet, this starts its folder with only the codex. Fill CODEX.md from their answers in one call (file_write of the whole file, or one file_edit with an edits list), then game_codex shows it. While planning, run `parts find` (the parts_find tool) for each system the game needs, so the plan starts from pieces of existing games and the @homie-rocks/* packages rather than from nothing; the codex\'s Built from section records what was found.',
       inputSchema: { type: 'object', properties: { id: str('The game\'s id (lowercase, digits, hyphens)'), name: str('Its name, when the game is not made yet'), ...STUDIO_ARG }, required: ['id'] },
       annotations: { title: 'Plan a game', ...RW },
       run: async (a) => {
@@ -943,6 +932,7 @@ export function toolDefs(ctx, avail = {}) {
         return ok([
           made ? `Wrote games/${a.id}/CODEX.md (every section${made.planned ? '; the game is planned here before it is made' : ''}).` : `games/${a.id}/CODEX.md is there already: change it, never replace it.`,
           'Now the interview: two or three questions a message, each with concrete options and your pick, so "yes" is an answer. Say back what you heard in one line before the next. Stop after three or four rounds; "just build it" means fill the rest with your own choices and list them under Open questions. Then fill CODEX.md in one call (file_read it once; then file_write the whole file, or one file_edit whose edits list has every section) and show it with game_codex.',
+          '', PARTS_FIRST,
           ...(guide ? ['', guide] : []),
         ].join('\n'), { kind: 'plan', id: a.id, file: `games/${a.id}/CODEX.md`, created: Boolean(made) });
       },
@@ -977,7 +967,8 @@ export function toolDefs(ctx, avail = {}) {
         if (!r.ended) return stillRunning(r.job, 'The build');
         if (r.job.code !== 0) return fail(`The build failed: ${whyOf(r.job)}`);
         const g = r.result?.games ?? [];
-        return ok(`Built ${g.length ? g.map((x) => `${x.id} (${Math.round(x.bytes / 1024)} KB)`).join(', ') : 'the home page (no game yet)'}.${devOf(root) ? ' Reload the preview to see it.' : ''}`, { kind: 'built', ...r.result });
+        // Each game's build hash, in the words the terminal prints: the hash a deploy reports and the live site answers with.
+        return ok(`Built ${g.length ? g.map((x) => `${x.id} (${Math.round(x.bytes / 1024)} KB${x.hash ? `, ${x.changed ?? 'new'}${x.changed && x.changed !== 'new' ? ' since the last build here' : ''}, build ${x.hash}` : ''})`).join(', ') : 'the home page (no game yet)'}.${devOf(root) ? ' Reload the preview to see it.' : ''}`, { kind: 'built', ...r.result });
       },
     },
     {
@@ -1008,7 +999,9 @@ export function toolDefs(ctx, avail = {}) {
       run: async (a) => {
         const root = ctx.root(a.studio);
         const r = await cli(ctx, root, 'dev --stop', ['dev', '--stop'], { wait: 20_000 });
-        return ok(r.result?.stopped?.length ? 'Stopped the studio\'s site here.' : 'It was not running.', { kind: 'preview', stopped: r.result?.stopped ?? [] });
+        // What a server stopped another way left behind is cleaned up and said (lib/dev.mjs).
+        const note = r.result?.why && (r.result?.stale || r.result?.stopped?.length) ? ` ${r.result.why[0].toUpperCase()}${r.result.why.slice(1)}.` : '';
+        return ok(`${r.result?.stopped?.length ? 'Stopped the studio\'s site here.' : 'It was not running.'}${note}`, { kind: 'preview', stopped: r.result?.stopped ?? [], ...(r.result?.stale ? { stale: true } : {}) });
       },
     },
     {
@@ -1102,7 +1095,7 @@ export function toolDefs(ctx, avail = {}) {
           if (!r.ended) return stillRunning(r.job, 'The deploy plan');
           if (r.job.code !== 0) return fail(whyOf(r.job));
           const p = r.result;
-          return ok([`What going online does for ${p.studio}:`, ...p.cloudflare.map((x) => `  ${x.kind}${x.name ? ` ${x.name}` : ''}: ${x.what} [${x.state}]`), `Cost: ${p.cost}`, `Sign-in: ${p.login}`, `The directory stores: ${p.directory?.stores ?? ''}`, 'The card on screen shows this plan (nothing is made yet): tell the person its gist in two or three lines, then go on.'].join('\n'), { kind: 'deploy-plan', ...p });
+          return ok([`What going online does for ${p.studio}:`, ...p.cloudflare.map((x) => `  ${x.kind}${x.name ? ` ${x.name}` : ''}: ${x.what} [${x.state}]`), `Cost: ${p.cost}`, `Sign-in: ${p.login}`, `The directory stores: ${p.directory?.stores ?? ''}`, ...(p.parts ? partsPlanLines(p.parts) : []), 'The card on screen shows this plan (nothing is made yet): tell the person its gist in two or three lines, then go on.'].join('\n'), { kind: 'deploy-plan', ...p });
         }
         const studio = readStudio(root);
         return startRun(ctx, root, { kind: 'deploy', game: null, title: `${studio.name}: online`, steps: [{ label: 'deploy', args: ['deploy'] }] });
@@ -1126,15 +1119,22 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_publish', title: 'List the studio in the Homie directory',
-      description: 'List a deployed studio\'s games, songs and videos in the homie.rocks directory, with their Play links (at most 12 games per studio in the beta).',
-      inputSchema: { type: 'object', properties: { site: str('Optional: the live site address (default: the one deploy got)'), ...STUDIO_ARG } },
+      description: 'List a deployed studio\'s games, songs and videos in the homie.rocks directory, with their Play links (at most 12 games per studio in the beta). The beta also caps how many times a studio may publish in a day: the answer says how many are left when the directory gives the number, and before: true only says what this computer knows (how many it has sent today, what the directory last said was left) without publishing.',
+      inputSchema: { type: 'object', properties: { site: str('Optional: the live site address (default: the one deploy got)'), before: { type: 'boolean', description: 'Only say how many publishes this computer has sent today and what the directory last said was left; publish nothing' }, ...STUDIO_ARG } },
       annotations: { title: 'List in the directory', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       run: async (a) => {
         const root = ctx.root(a.studio);
+        // What this computer knows of the day's cap, before anything is sent (lib/directory.mjs).
+        const soFar = beforeLine(publishesSoFar(root));
+        // The parts in the games a listing shows, in the deploy plan's own lines (licences, credits, and plainly when
+        // two cannot be combined): said before the studio is listed, and again with the answer.
+        const partsNow = partsForListing(root);
+        const partsSaid = partsPlanLines(partsNow, { at: 'publish' });
+        if (a.before === true) return ok([`${soFar.replace(/^Publishing to the directory: /, 'Not published. ')} A publish from another computer or from the Homie connector is not counted here.`, ...partsSaid].join('\n'), { kind: 'publish-count', ...publishesSoFar(root), ...(partsSaid.length ? { parts: partsNow } : {}) });
         const r = await cli(ctx, root, 'publish', ['publish', ...(a.site ? ['--site', String(a.site)] : [])]);
         if (!r.ended) return stillRunning(r.job, 'Listing');
-        if (r.job.code !== 0) return fail(`Not listed: ${whyOf(r.job)}`);
-        return ok(`Listed: ${r.result?.studioPage ?? r.result?.directory ?? ''}\n${(r.result?.games ?? []).map((g) => `  ${g.name}: ${g.play}`).join('\n')}`, { kind: 'publish', ...r.result });
+        if (r.job.code !== 0) return fail(`Not listed: ${whyOf(r.job)}`, r.result?.publishes ? { kind: 'publish', ok: false, needs: r.result.needs ?? null, publishes: r.result.publishes } : undefined);
+        return ok(`Listed: ${r.result?.studioPage ?? r.result?.directory ?? ''}\n${(r.result?.games ?? []).map((g) => `  ${g.name}: ${g.play}`).join('\n')}${r.result?.publishes?.line ? `\n${r.result.publishes.line}` : ''}${partsSaid.length ? `\n${partsSaid.join('\n')}` : ''}`, { kind: 'publish', ...r.result });
       },
     },
     {
@@ -1184,7 +1184,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_run', title: 'Run a studio command',
-      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job. ["upgrade"] runs with THIS Homie\'s toolkit when the studio pins an older one (that is how a studio moves up to it): it says what is new since the studio\'s version and what would change, and changes nothing; ["upgrade","--apply"] only after the person agrees, then studio_install.',
+      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["shoot","<id>","--preview"], ["build","--types"], ["assets","use","<id>","<asset>","unused"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job. ["upgrade"] runs with THIS Homie\'s toolkit when the studio pins an older one (that is how a studio moves up to it): it says what is new since the studio\'s version and what would change, and changes nothing; ["upgrade","--apply"] only after the person agrees, then studio_install.',
       inputSchema: { type: 'object', properties: { args: { type: 'array', items: { type: 'string' }, description: 'The command\'s words after `homie-studio`' }, ...STUDIO_ARG }, required: ['args'] },
       annotations: { title: 'Run a studio command', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       run: async (a) => {
@@ -1361,6 +1361,7 @@ export function toolDefs(ctx, avail = {}) {
   ];
   // Art direction, the cast, the starter library, generated props, checks, the lineup and the rights (lib/art-tools.mjs).
   tools.push(...artToolDefs(ctx, { ok, fail, cli, stillRunning, whyOf, needsInstall, ui, str, STUDIO_ARG, RO, RW, pictureFor, findNode, startJob, waitJob }));
+  tools.push(...partsToolDefs(ctx, { ok, fail, str, STUDIO_ARG, RO, RW }));
   const topics = guideTopics(ctx);
   if (topics.length) {
     tools.push({

package/lib/mcp.mjs

@@ -38,7 +38,7 @@ A new studio follows one checklist, in order and never ahead. Show it in your fi
 1. The studio (studio_scaffold): it has NO game; its home page says "First game coming soon".
 2. See a working game (game_demo): a live game on Homie Arcade with its Play link, nothing copied in. Copy a starter in (game_make) only if they ask.
 3. One small change from one sentence of theirs: to the copied game, or to the studio's home (site/theme.json colours, a tagline in studio.json, a first post in posts/). Then build and preview_run, and they reload.
-4. Plan their game (game_plan): a short interview, two or three questions a message with options and your pick; then fill games/<id>/CODEX.md and show it (game_codex).
+4. Plan their game (game_plan): a short interview, two or three questions a message with options and your pick; then fill games/<id>/CODEX.md and show it (game_codex). Look for pieces first: the @homie-rocks/* packages for general mechanisms, and parts_find for pieces other studios shared (part_add brings one in).
 5. Build it: build_open, then game_make under the planned id (the codex stays), file edits (few and large: one file_edit carries every change to a file in its edits list, never a call per change), build, preview_run, check. The card follows every build.
 6. Playtest it (playtest), then put it online: studio_deploy with plan: true first (say what it creates and costs, free), cloudflare_login when not signed in (they approve once in their browser), studio_deploy, then studio_publish.
 If they ask for everything at once, show the list, make your own choices for steps 2 to 4 in one line each, and go on.

package/lib/net.mjs

@@ -76,6 +76,14 @@ export function restartWithProxy({ argv = process.argv, env = process.env, execA
   });
 }
 
+/**
+ * The error codes that mean "this computer could not look the name up" (the resolver's, never the site's). ONE list:
+ * every command that works against a site reads it through `whyFailed`, and the plugin's own preflight
+ * (skills/playtest/scripts/lib/preflight.mjs, which cannot import this file: it runs against whatever studio is
+ * installed) keeps the same list, held equal by a test that feeds both the same errors.
+ */
+export const DNS_CODES = ['ENOTFOUND', 'EAI_AGAIN', 'EAI_NODATA', 'EAI_NONAME', 'ESERVFAIL'];
+
 const hostOf = (url) => { try { return new URL(String(url)).host; } catch { return String(url); } };
 const oneLine = (text, max = 200) => String(text ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
 
@@ -104,7 +112,9 @@ export function whyFailed(error, url, { env = process.env, execArgv = process.ex
   if (refused) return { why: `the network proxy (${proxy?.variable ?? 'HTTPS_PROXY'}) answered ${refused[1]} when asked to connect to ${host}`, code: `PROXY_${refused[1]}` };
   const via = proxy ? (used ? ` (through the proxy in ${proxy.variable})` : ` (directly: this machine's proxy in ${proxy.variable} was not used${canUseProxy() ? '' : `, because Node.js ${process.versions.node} cannot use it; Node.js 22.21 or newer can`})`) : '';
   if (code === 'TIMEOUT' || code === 'UND_ERR_CONNECT_TIMEOUT' || code === 'ETIMEDOUT') return { why: `no answer from ${host} in time${via}`, code: code ?? 'TIMEOUT' };
-  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return { why: `could not look up ${host} (${code})${via}`, code };
+  // A name this process could not look up is this computer's network, never the site's fault: `preflight` says so
+  // to callers that would otherwise read "did not answer" as a broken site or game (see `reachSite`).
+  if (DNS_CODES.includes(code)) return { why: `could not look up ${host} (${code})${via}`, code, preflight: 'dns' };
   if (code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'EHOSTUNREACH' || code === 'ENETUNREACH') return { why: `could not connect to ${host} (${code})${via}`, code };
   if (/CERT|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER/i.test(code ?? '') || /certificate/i.test(words)) {
     return { why: `the TLS certificate ${host} presented is not trusted here (${code ?? words})${via}; when a proxy inspects traffic, its CA belongs in NODE_EXTRA_CA_CERTS`, code: code ?? 'CERT' };
@@ -132,6 +142,75 @@ export async function request(url, init = {}, { timeout = 10_000, fetchFn = glob
   } catch (error) { return { ok: false, ...whyFailed(error, url) }; }
   let body = null;
   try { body = text ? JSON.parse(text) : null; } catch { body = null; }
-  if (!res.ok || body?.ok === false) return { ok: false, body, ...whyRefused(res, body, text, url) };
+  if (!res.ok || body?.ok === false) return { ok: false, body, headers: res.headers, ...whyRefused(res, body, text, url) };
   return { ok: true, status: res.status, body, headers: res.headers };
 }
+
+/** Whether an address is this computer's own (a dev site): never a network question. */
+export function isLoopback(url) {
+  try { const h = new URL(String(url)).hostname.toLowerCase(); return LOOPBACK.includes(h) || h.endsWith('.localhost'); } catch { return false; }
+}
+
+/*
+ * NODE'S DNS IS NOT THE BROWSER'S. On one computer the public studio opened in Chrome while Node's fetch() could
+ * not look its hostname up at all (a browser may use its own secure DNS, a VPN's or a cached answer; Node asks the
+ * system resolver and nothing else). A check against the public address stopped before it opened a game, and what
+ * it printed read as the site, or the game, being down.
+ *
+ * `reachSite` is the one preflight for a command that is about to work against a site: it asks once, and a failure
+ * says what kind it is.
+ *   { ok: true, status }                                   the site answered (any status is an answer)
+ *   { ok: false, preflight: 'dns', why, instead, ... }     THIS COMPUTER could not look the name up: a network
+ *                                                          preflight failure, with local testing offered instead
+ *   { ok: false, preflight: 'network', why, instead, ... } no connection, a timeout, a certificate, a proxy refusal
+ *   { ok: false, preflight: 'site', status, why }          it answered, and the answer is an error (5xx)
+ * It never says a game is broken: it has not opened one.
+ */
+export const LOCAL_INSTEAD = 'To test without this computer\'s network in the way: run the site here (`npx --no-install homie-studio dev`, as a background task) and give the command --url http://127.0.0.1:8787 (or leave --url out where the command finds the dev site itself).';
+
+export async function reachSite(url, { fetchFn = globalThis.fetch, timeout = 10_000, path = '/', env = process.env, execArgv = process.execArgv } = {}) {
+  const base = String(url ?? '').replace(/\/+$/, '');
+  const host = hostOf(base);
+  let res;
+  try { res = await fetchFn(`${base}${path}`, { method: 'GET', redirect: 'manual', headers: { accept: '*/*' }, signal: AbortSignal.timeout(timeout) }); } catch (error) {
+    const w = whyFailed(error, base, { env, execArgv });
+    if (isLoopback(base)) return { ok: false, preflight: 'local', code: w.code ?? null, why: `${base} does not answer (${w.code ?? 'no connection'}): the site is not running here. Start it (npx --no-install homie-studio dev, as a background task) or check the port.` };
+    if (w.preflight === 'dns') {
+      return {
+        ok: false, preflight: 'dns', code: w.code, needs: 'network-preflight',
+        why: `network preflight failed, before any page or game was opened: this computer's Node.js ${w.why}. A browser on the same computer may still open ${host} (browsers can use their own DNS), so this says nothing about the site or the game: it is this computer's name lookup.`,
+        instead: LOCAL_INSTEAD,
+      };
+    }
+    return { ok: false, preflight: 'network', code: w.code ?? null, needs: w.needs ?? 'network-preflight', why: `network preflight failed, before any page or game was opened: ${w.why}. That is the connection from this computer to ${host}, not a result about the game.`, instead: LOCAL_INSTEAD };
+  }
+  try { await res.body?.cancel?.(); } catch { /* nothing to drop */ }
+  if (res.status >= 500) return { ok: false, preflight: 'site', status: res.status, why: `${host} answered ${res.status}: the site itself is failing (not this computer's network).` };
+  return { ok: true, status: res.status };
+}
+
+/**
+ * WHAT A COMMAND SAYS WHEN `reachSite` DID NOT FIND THE PLAY PAGE: one classification and one sentence for `check`,
+ * `perf`, `shoot` and `port check` (and, word for word in its DNS case, the playtest and perf skills' scripts), so
+ * the same failure is never "the site does not answer" from one command and "network preflight" from the next.
+ *
+ *   null                                the page answered: go on
+ *   preflight 'local'                   this computer's own address has nothing listening: start the site
+ *   preflight 'site'                    it answered, with an error (a 5xx, or a 4xx: a wrong address or game id)
+ *   preflight 'dns' | 'network'         BLOCKED: this computer could not ask. Nothing was measured, nothing is said
+ *                                       about the site or the game, and local testing is offered instead.
+ *
+ * A command that only drives a browser (check, shoot) may still try on a BLOCKED one, because a browser can open a
+ * site this process cannot look up; if the browser then fails too, this is what it reports.
+ */
+export function siteRefusal(reach, { command, play }) {
+  if (reach?.ok) {
+    return reach.status >= 400 ? { ok: false, command, preflight: 'site', status: reach.status, why: `${play} answered ${reach.status}: start the site (npm run dev, as a background task) or check the address and the game's id` } : null;
+  }
+  if (reach?.preflight === 'local') return { ok: false, command, preflight: 'local', why: `${play} does not answer: start the site (npm run dev, as a background task that outlives this command) or check the address` };
+  if (reach?.preflight === 'site') return { ok: false, command, preflight: 'site', status: reach.status ?? null, why: reach.why };
+  return {
+    ok: false, command, blocked: true, verdict: 'BLOCKED', preflight: reach?.preflight ?? 'network', ...(reach?.code ? { code: reach.code } : {}), needs: reach?.needs ?? 'network-preflight', instead: reach?.instead ?? LOCAL_INSTEAD,
+    why: `BLOCKED ${reach?.why ?? 'network preflight failed, before any page or game was opened.'} Nothing was measured. ${reach?.instead ?? LOCAL_INSTEAD}`,
+  };
+}

package/lib/node-version.mjs

@@ -0,0 +1,40 @@
+/**
+ * THE NODE.JS THIS TOOLKIT NEEDS, SAID BEFORE ANYTHING ELSE RUNS.
+ *
+ * `@homie-rocks/studio` needs Node.js 22 or newer (package.json `engines`), and npm only warns about that. On an
+ * older Node the commands did not say so: `homie-studio dev` under Node 20 ended with no word at all, and the person
+ * was left to guess. So the CLI imports this file FIRST. An ES module's imports are evaluated in order, so this
+ * runs before any other file of the toolkit does, and on a Node that is too old the command ends here, with the
+ * version it found, the version it needs and how to get it.
+ *
+ * This file is read by the old Node it complains about, so it stays plain: no syntax or built-in newer than Node 14.
+ * (A file the old Node cannot even parse fails before any code runs; nothing in this package's own code is known to
+ * do that on Node 18 or 20, and if one ever does, Node prints its own syntax error, which is not silent either.)
+ */
+export const NODE_MIN = 22;
+
+/** What is wrong with this Node.js version for the toolkit, as one sentence, or null when it is new enough. */
+export function nodeProblem(version) {
+  var found = String(version === undefined ? process.versions.node : version);
+  var major = Number(found.split('.')[0]);
+  if (major >= NODE_MIN) return null;
+  return 'homie-studio needs Node.js ' + NODE_MIN + ' or newer, and this is Node.js ' + (found || 'of an unknown version') + '. '
+    + 'Install Node.js ' + NODE_MIN + ' (https://nodejs.org, or `nvm install ' + NODE_MIN + '` / `fnm install ' + NODE_MIN + '`), '
+    + 'make it the one this terminal runs (`node --version` says which), then run the command again. Nothing was started or changed.';
+}
+
+/**
+ * End the command now when this Node.js is too old. `--json` gets the same refusal as JSON on stdout, like every
+ * other refusal of the CLI; a person gets one line on stderr. Exit status 1 either way.
+ */
+export function requireNode(version, argv) {
+  var why = nodeProblem(version);
+  if (!why) return;
+  var args = argv === undefined ? process.argv.slice(2) : argv;
+  if (args.indexOf('--json') >= 0) process.stdout.write(JSON.stringify({ ok: false, needs: 'node', why: why }, null, 2) + '\n');
+  else process.stderr.write('homie-studio: ' + why + '\n');
+  process.exit(1);
+}
+
+// HOMIE_STUDIO_NODE: the toolkit's own tests say which version to judge (no machine here has an old Node to run).
+requireNode(process.env.HOMIE_STUDIO_NODE || undefined);

package/lib/office.mjs

@@ -8,7 +8,7 @@
  *                                                      room_kick, room_announce, room_close, game_launch_state)
  *   homie-studio office announce "<text>" [--game <id>] [--room <code>] [--seconds 30]
  *   homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1] [--days <n>]
- *   homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]
+ *   homie-studio office launch <game> private|invite|public [--max <n>|game]
  *   homie-studio office kick <game> <room> <seat number | name> [--minutes 10]
  *   homie-studio office mute <game> <room> <seat number | name> [--minutes 10] [--off]
  *   homie-studio office close <game> <room> [--minutes 10] [--reopen]
@@ -16,7 +16,7 @@
  *
  * THE PROOF OF OWNERSHIP IS THE STUDIO'S OWN CLOUDFLARE LOGIN, as for the stats: a key is minted here and only its
  * SHA-256 goes into the studio's D1. Looking, announcing and inviting happen at once. Kick, mute, closing a room and
- * a game's launch state, remix switch or room size are only ASKED for here: the answer is a one-time sign-in link
+ * a game's launch state or room size are only ASKED for here: the answer is a one-time sign-in link
  * that opens the ask in the owner's own browser, where one tap does it (the AI that ran this cannot).
  */
 import { readStudio } from './studio.mjs';
@@ -113,11 +113,11 @@ export async function officeInvite(root, game, { url, label, uses, count, days,
   return { ok: true, command: 'office invite', game, launch: r.launch, invites: r.invites, note: server || r.launch === 'invite' ? null : `${game} is ${r.launch} now: invites let people in once it is an invite-only beta (homie-studio office launch ${game} invite).` };
 }
 
-export async function officeLaunch(root, game, state, { url, remixable, max } = {}) {
+export async function officeLaunch(root, game, state, { url, max } = {}) {
   if (!GAME.test(String(game ?? '')) || (state !== undefined && state !== null && !['private', 'invite', 'public'].includes(state))) {
-    return { ok: false, command: 'office launch', why: 'usage: homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]' };
+    return { ok: false, command: 'office launch', why: 'usage: homie-studio office launch <game> private|invite|public [--max <n>|game]' };
   }
-  const body = { game, ...(state ? { launch: state } : {}), ...(remixable !== undefined ? { remix: remixable === 'on' || remixable === true } : {}), ...(max !== undefined ? { maxPlayers: max === 'game' ? null : Number(max) } : {}) };
+  const body = { game, ...(state ? { launch: state } : {}), ...(max !== undefined ? { maxPlayers: max === 'game' ? null : Number(max) } : {}) };
   const r = await withKey(root, url, (call) => call('/_studio/api/game', body));
   return askedFor(root, url, r, 'office launch');
 }
@@ -181,7 +181,7 @@ export function officeLines(r) {
   const now = r.now ?? Date.now();
   const mins = (ms) => `${Math.max(0, Math.round(ms / 60000))} min`;
   for (const g of r.games ?? []) {
-    lines.push(`  ${g.name} (${g.id}): ${g.launch}${g.launch === 'public' ? '' : ' (not listed)'}, ${g.remix ? 'remixable' : 'source closed'}, rooms of ${g.maxPlayers}${g.maxSet ? ` (the game's own: ${g.seats})` : ''}`);
+    lines.push(`  ${g.name} (${g.id}): ${g.launch}${g.launch === 'public' ? '' : ' (not listed)'}, rooms of ${g.maxPlayers}${g.maxSet ? ` (the game's own: ${g.seats})` : ''}`);
     for (const i of (g.invites ?? []).filter((x) => x.open)) lines.push(`    invite ${i.code}${i.label ? ` (${i.label})` : ''}: ${i.uses}${i.maxUses ? ` of ${i.maxUses}` : ''} used · ${i.link}`);
     if (!g.rooms.length) lines.push('    no live rooms');
     for (const rm of g.rooms) {

package/lib/optimise.mjs

@@ -6,6 +6,10 @@
  *       bottom centre, scaled to its size in metres, welded and simplified to its triangle budget (meshoptimizer),
  *       pictures resized and re-encoded as WebP (sharp), meshopt geometry, nothing unused. Raw files are never
  *       changed; the result says what each step did, before and after.
+ *       `lo: { ratio }` also writes `<name>_lo.glb` beside it: the same model through the same steps (the same
+ *       height, pivot, palette and pictures, so the two line up) with `ratio` of the shipped triangles, for the far
+ *       band of @homie-rocks/render's LodProps. A rigged model is skipped (its skin is one mesh with its bones).
+ *       The result's `lo` is { path, triangles, bytes, sha256 }, or null with the reason in `warnings`.
  *   inspectModel(input)                       triangles, vertices, draw calls, materials, pictures and their GPU memory,
  *       bones and clips, the bounding box in metres, the Khronos glTF-Validator's errors, and the file's own safety
  *       check (assets/safety.mjs).
@@ -312,7 +316,10 @@ const linearToSrgb255 = (v) => { const c = Math.max(0, Math.min(1, v)); return M
  *              usually says metallic 1 and leaves the rest to its texture)
  * Returns { ok, glb (the bytes), bytes (their count), sha256, out, before, after, ops, warnings }.
  */
-export async function optimiseModel(input, { out = null, triangles = 1500, texture = 512, height = null, quality = 82, rigged = false, metal = false, log = () => {} } = {}) {
+/** Where a model's low copy goes: `<name>_lo.glb` beside it. */
+export const loPathOf = (out) => String(out).replace(/(\.glb)?$/i, '_lo.glb');
+
+export async function optimiseModel(input, { out = null, triangles = 1500, texture = 512, height = null, quality = 82, rigged = false, metal = false, lo = null, log = () => {} } = {}) {
   const t = await modelTools();
   const { fn, mo, sharp, io } = t;
   const raw = await selfContained(input, LIMITS.import);
@@ -410,7 +417,35 @@ export async function optimiseModel(input, { out = null, triangles = 1500, textu
   if (!safe.ok) warnings.push(...safe.problems.map((p) => `the result: ${p}`));
   if (out) { mkdirSync(dirname(out), { recursive: true }); writeFileSync(out, bytes); }
   log(`optimised: ${before.triangles} -> ${after.triangles} triangles, ${Math.round(raw.byteLength / 1024)} -> ${Math.round(bytes.byteLength / 1024)} KB`);
-  return { ok: safe.ok, out, glb: bytes, bytes: bytes.byteLength, sha256: sha256(bytes), rawBytes: raw.byteLength, rawSha256: sha256(raw), before, after, ops, warnings, tool: `@gltf-transform/functions ${await toolVersion()}` };
+
+  /*
+   * THE LOW COPY (`lo: { ratio }`), for the far band of a prop drawn at two levels of detail (@homie-rocks/render
+   * LodProps: the full model near, this one far). It is the SAME raw file through the SAME steps with a smaller
+   * triangle budget, never a second recipe: the same scale to the card's height, the same pivot, the same palette
+   * and pictures, so the two models sit on each other exactly and share a material. A rigged model has none: its
+   * skin is one mesh bound to its bones, and a character is not scattered by the hundred.
+   */
+  let low = null;
+  if (lo) {
+    const ratio = Number(lo.ratio);
+    if (!(ratio > 0 && ratio < 1)) warnings.push(`no low copy: lo.ratio is the share of the shipped triangles to keep, between 0 and 1 (0.2 keeps a fifth), not ${JSON.stringify(lo.ratio)}`);
+    else if (hasRig) warnings.push('no low copy: a rigged model is one skinned mesh with its bones, and is not drawn at two levels of detail');
+    else {
+      const want = Math.max(4, Math.round(after.triangles * ratio));
+      const loOut = out ? loPathOf(out) : null;
+      const r = await optimiseModel(raw, { out: null, triangles: want, texture, height, quality, rigged: false, metal });
+      if (r.after.triangles >= after.triangles) warnings.push(`no low copy: the shape would not simplify below its ${after.triangles} triangles`);
+      else if (!r.ok) warnings.push(`no low copy: ${r.warnings.join('; ')}`);
+      else {
+        if (loOut) writeFileSync(loOut, r.glb);
+        low = { path: loOut, triangles: r.after.triangles, bytes: r.bytes, sha256: r.sha256, ratio, glb: r.glb };
+        ops.push(`low copy at ${ratio} (${after.triangles} to ${r.after.triangles} triangles)`);
+        if (r.after.triangles > want * 1.25) warnings.push(`the low copy has ${r.after.triangles} triangles, not the ${want} asked (ratio ${ratio}): the shape resists`);
+        log(`low copy: ${r.after.triangles} triangles, ${Math.round(r.bytes / 1024)} KB`);
+      }
+    }
+  }
+  return { ok: safe.ok, out, glb: bytes, bytes: bytes.byteLength, sha256: sha256(bytes), rawBytes: raw.byteLength, rawSha256: sha256(raw), before, after, ops, warnings, ...(lo ? { lo: low } : {}), tool: `@gltf-transform/functions ${await toolVersion()}` };
 }
 
 let version = null;
@@ -427,8 +462,8 @@ async function toolVersion() {
 }
 
 /**
- * A grey box .glb of `size` metres (x, y, z), its pivot at the bottom centre: what a remix gets in place of an asset
- * it may not carry, and what a refused model is drawn as.
+ * A grey box .glb of `size` metres (x, y, z), its pivot at the bottom centre: what a refused model is drawn as,
+ * and a stand-in for one that is not there yet.
  */
 export async function placeholderGlb(size = [0.5, 0.5, 0.5], { name = 'placeholder', colour = [0.54, 0.56, 0.6, 1] } = {}) {
   const { core, io } = await modelTools();