@homie-rocks/studio 0.30.2 → 0.31.1

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();

package/lib/parts-build.mjs

@@ -0,0 +1,169 @@
+/**
+ * GAME PARTS IN THE BUILD (parts/PARTS.md). Three small things lib/build.mjs and the deploy plan call, so the build
+ * itself stays one line longer in each place:
+ *
+ *   partsPlugin(root, game)     esbuild resolves `@parts/<host>/<id>` (a part brought in) and `@parts/<id>` (one of
+ *                               the studio's own) to the part's entry, so adding a part and one import line is a
+ *                               running piece. A game that imports a brought-in part is recorded against it and
+ *                               credited (the existing credits.json), whether or not the add named the game.
+ *   buildParts(root, dist)      site/dist/parts/: every packed version of every SHARED part, byte for byte as
+ *                               hashed, and index.json, what the Worker answers /.well-known/homie-parts.json from.
+ *                               What is shared is sharedPartsOf() and nothing else. A private part is never copied:
+ *                               what is not in dist cannot be served.
+ *   partsPublishReport(root)    before a game that uses parts goes online: each part's licence and attribution, and
+ *                               plainly where licences cannot be combined.
+ */
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  assetRecords, licenceIssues, licenseOfPart, listOwnParts, packPart, packedDir, packedVersions, publicPart, readOrigins, readPart, safePath, shareProblems,
+  sharedPartsOf, syncPartCredits, vendorDir, verifyFiles, writeOrigins,
+} from './parts.mjs';
+import { gameFacts, partItems } from './parts-store.mjs';
+
+/* ------------------------------------------------------------------ importing a part */
+
+/**
+ * Where `@parts/…` points: { path } or { error }. `@parts/<host>/<id>[/<file>]` is a part the lock names;
+ * `@parts/<id>[/<file>]` is one of the studio's own. With no file it is the part's `entry`.
+ */
+export function resolvePartImport(root, spec, lock = readOrigins(root)) {
+  const segs = String(spec).replace(/^@parts\//, '').split('/').filter(Boolean);
+  let dir = null; let rest = []; let ref = null; let vendored = false;
+  if (segs.length >= 2 && lock.parts[`${segs[0]}/${segs[1]}`]) { ref = `${segs[0]}/${segs[1]}`; dir = vendorDir(root, ref); rest = segs.slice(2); vendored = true; }
+  else if (segs.length >= 1 && existsSync(join(root, 'parts', segs[0], 'part.json'))) { ref = segs[0]; dir = join(root, 'parts', segs[0]); rest = segs.slice(1); }
+  if (!dir) return { error: `'${spec}' names a part this studio does not have. Parts here: ${[...Object.keys(lock.parts), ...listOwnParts(root).map((o) => o.id)].join(', ') || 'none'}. Bring one in with part_add ("<studio site>/<part id>").` };
+  if (!existsSync(dir)) return { error: `'${spec}': parts/origins.json names ${ref} but its files are gone. Add it again (${ref}@${lock.parts[ref].version}).` };
+  if (rest.length) {
+    const file = rest.join('/');
+    if (!safePath(file) || !existsSync(join(dir, file))) return { error: `'${spec}': the ${ref} part has no file ${file}` };
+    return { path: join(dir, file), ref, vendored };
+  }
+  let part;
+  try { part = readPart(dir); } catch (error) { return { error: `'${spec}': ${error.message}` }; }
+  if (!part.entry) return { error: `'${spec}': the ${ref} part has no code to import (it is ${part.kind}: files only). Name a file: '@parts/${ref}/<path>'.` };
+  if (!existsSync(join(dir, part.entry))) return { error: `'${spec}': the ${ref} part's entry ${part.entry} is missing` };
+  return { path: join(dir, part.entry), ref, vendored };
+}
+
+/** The esbuild plugin (lib/build.mjs passes it to every game's bundle). `game`: the game being bundled, to credit. */
+export function partsPlugin(root, game = null) {
+  return {
+    name: 'homie-parts',
+    setup(build) {
+      const used = new Set();
+      let lock = null;
+      build.onStart(() => { used.clear(); lock = null; });
+      build.onResolve({ filter: /^@parts\// }, (args) => {
+        try { lock ??= readOrigins(root); } catch (error) { return { errors: [{ text: error.message }] }; }
+        const r = resolvePartImport(root, args.path, lock);
+        if (r.error) return { errors: [{ text: r.error }] };
+        if (r.vendored) used.add(r.ref);
+        return { path: r.path };
+      });
+      // A brought-in part a game imports is that game's to credit, even when it was added without naming the game.
+      build.onEnd(() => {
+        if (!game || !used.size || !existsSync(join(root, 'games', game))) return;
+        try {
+          const now = readOrigins(root);
+          let changed = false;
+          for (const ref of used) { const e = now.parts[ref]; if (e && !(e.games ?? []).includes(game)) { e.games = [...(e.games ?? []), game].sort(); changed = true; } }
+          if (changed) writeOrigins(root, now);
+          syncPartCredits(root, game, now);
+        } catch { /* a credit line is never worth a failed bundle; the publish report says what is missing */ }
+      });
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ the site's parts */
+
+/**
+ * site/dist/parts/: the shared parts and their index. Returns { shared: [{ id, versions }], kept: <private count> }.
+ * A part marked shared that cannot be (someone set `share` by hand past the checks) STOPS the build with the
+ * reasons: publishing a file of unknown rights quietly is the one thing this must never do.
+ */
+export function buildParts(root, dist, { studio = {}, log = () => {} } = {}) {
+  const out = join(dist, 'parts');
+  rmSync(out, { recursive: true, force: true });
+  const own = listOwnParts(root);
+  const records = assetRecords(root);
+  for (const o of own) {
+    if (o.part?.share !== true) continue;
+    const problems = shareProblems(o.part, { dir: o.dir, records }).filter((p) => !(p.field === 'files' && /^the files differ/.test(p.problem)));
+    if (problems.length) throw new Error(`parts/${o.id} is marked shared but cannot be: ${problems.map((p) => `${p.field}: ${p.problem}`).slice(0, 4).join('; ')}. Fix it, or stop sharing it (part_share with share: false); the site was not built with it.`);
+    // Edited since it was packed: the packed version is what is public; the edit needs a version of its own.
+    if (!verifyFiles(o.dir, o.part).ok || !packedVersions(root, o.id).includes(o.part.version)) {
+      const packed = verifyFiles(o.dir, o.part).ok ? packPart(root, o.id) : { ok: false };
+      if (!packed.ok) log(`warning: parts/${o.id} changed since version ${packedVersions(root, o.id).at(-1) ?? '(none)'} was shared; the site shares that version. To share the change, raise "version" in its part.json and share it again.`);
+    }
+  }
+  // The one answer to "what does this studio share".
+  const sharing = sharedPartsOf(root);
+  const names = new Map();
+  const index = [];
+  for (const { id, versions, part } of sharing) {
+    for (const v of versions) {
+      const src = packedDir(root, id, v);
+      const packed = readPart(src);
+      if (!verifyFiles(src, packed).ok) throw new Error(`parts/_packed/${id}/${v} no longer matches its hashes: a shared version never changes. Restore it from git.`);
+      const dest = join(out, id, v);
+      for (const f of packed.files) { mkdirSync(dirname(join(dest, f.path)), { recursive: true }); cpSync(join(src, f.path), join(dest, f.path)); }
+      writeFileSync(join(dest, 'part.json'), `${JSON.stringify(publicPart({ ...packed, share: true }))}\n`);
+    }
+    // The game it came out of, by the name the studio gives it.
+    const g = part.from?.game;
+    if (g && !names.has(g)) names.set(g, gameFacts(root, g).name);
+    index.push({ ...part, ...(g ? { from: { ...part.from, name: names.get(g) } } : {}), url: `/parts/${id}/${versions.at(-1)}/`, page: `/parts/${id}/`, versions });
+    log(`shared part ${id} (${versions.join(', ')})`);
+  }
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, 'index.json'), `${JSON.stringify({ v: 1, studio: { name: studio.name ?? null }, parts: index.sort((a, b) => a.id.localeCompare(b.id)) })}\n`);
+  return { shared: sharing.map(({ id, versions }) => ({ id, versions })), kept: own.length - sharing.length };
+}
+
+/* ------------------------------------------------------------------ before going online */
+
+/**
+ * What a deploy plan shows about parts, and changes nothing:
+ *
+ *   games     each game that uses brought-in parts: every part's licence, what it asks, its attribution and the game
+ *             it came from, and plainly where licences cannot be combined (licenceIssues)
+ *   sharing   the studio's own parts this deploy makes live (sharedPartsOf)
+ *   ok        false when a game's licences cannot be combined: the caller decides whether that stops it
+ *
+ * `partsPlanLines(report)` is the same in plain lines: said before a deploy (its plan) and before a studio is listed
+ * (`publish`, lib/directory.mjs), in the same words.
+ */
+export function partsPublishReport(root) {
+  let lock;
+  try { lock = readOrigins(root); } catch (error) { return { ok: false, games: [], sharing: [], why: error.message }; }
+  const byGame = new Map();
+  for (const [ref, e] of Object.entries(lock.parts)) for (const g of e.games ?? []) { if (!byGame.has(g)) byGame.set(g, []); byGame.get(g).push([ref, e]); }
+  const games = [];
+  for (const [game, list] of [...byGame].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!existsSync(join(root, 'games', game, 'game.json'))) continue;
+    const issues = licenceIssues(partItems(root, { game }), { game: gameFacts(root, game) });
+    games.push({
+      game,
+      parts: list.sort(([a], [b]) => a.localeCompare(b)).map(([ref, e]) => { const lic = licenseOfPart(e.license); return { ref, name: e.name, version: e.version, license: lic?.id ?? null, asks: lic?.asks ?? 'nothing is known: it names no licence', attribution: e.attribution || null, from: e.from ?? null }; }),
+      issues, ok: !issues.some((i) => i.level === 'conflict'),
+    });
+  }
+  const sharing = sharedPartsOf(root).map(({ id, versions, part }) => ({ id, version: versions.at(-1), license: part.license ?? null, from: part.from ?? null }));
+  return { ok: games.every((g) => g.ok), games, sharing };
+}
+
+export function partsPlanLines(report, { at = 'deploy' } = {}) {
+  const L = [];
+  if (report.why) L.push(`Parts: ${report.why}`);
+  for (const g of report.games) {
+    L.push(`Parts in ${g.game} from other studios (their licences travel with the game):`);
+    for (const p of g.parts) L.push(`  ${p.name} ${p.version} (${p.ref})${p.from?.name || p.from?.game ? `, from ${p.from.name ?? p.from.game}` : ''}: ${p.license ?? 'NO LICENCE'}; asks ${p.asks}${p.attribution ? `; credit: ${p.attribution}` : ''}`);
+    for (const i of g.issues) L.push(`  ${i.level === 'conflict' ? 'CANNOT BE COMBINED' : i.level === 'warn' ? 'look' : 'note'} ${i.parts.join(' + ')}: ${i.problem}${i.fix ? ` (${i.fix})` : ''}`);
+    if (!g.issues.length) L.push('  Their licences can be combined, and each is credited in the game\'s credits.');
+  }
+  // The same lines before a deploy and before a listing; only where a shared part becomes visible differs.
+  if (report.sharing.length) L.push(`Parts this studio shares (${at === 'publish' ? 'the parts catalog shows them once the studio is listed' : 'live with this deploy'}): ${report.sharing.map((s) => `${s.id} ${s.version} (${s.license})`).join(', ')}`);
+  return L;
+}

package/lib/parts-cli.mjs

@@ -0,0 +1,104 @@
+/**
+ * `homie-studio parts …`: the plumbing behind the four chat tools (lib/parts-tools.mjs; parts/PARTS.md). A creator
+ * works in chat and never types these; an agent with a shell and no MCP connection may.
+ *
+ *   parts find <words> [--kind <kind>] [--tag <tag>] [--license <SPDX>] [--builds <package or rig>]
+ *   parts new <id> [--kind <kind>] [--name "<Name>"] [--from <game> <paths in the game…>]
+ *   parts add <host>/<id>[@<version>] [--game <id>] [--overwrite] [--no-install]     (again: the newer version)
+ *       --no-install: bring the part in and install nothing. package.json and package-lock.json are not touched and
+ *       npm is only asked what the studio has (`npm ls`). Each package the part builds on that is missing is named
+ *       "NOT INSTALLED" with the one npm command that installs it. The part will not build until that is run.
+ *   parts share <id>      parts unshare <id>      (live after the studio's next deploy)
+ *   parts check [<id>]                             (what stands in the way of sharing; rewrites the hashes)
+ */
+import { newPart } from './parts.mjs';
+import { addPart, checkParts, findParts, sharePart } from './parts-store.mjs';
+
+export const PARTS_VERBS = ['find', 'new', 'add', 'share', 'unshare', 'check'];
+
+/**
+ * What `parts add` takes, in the words the command prints when it is not given a part. `--no-install` is said as
+ * what it does: nothing is installed and package.json is not written (npm writes it, when npm installs). A test
+ * runs the flag through the real command and holds these words to what happened.
+ */
+export const PARTS_ADD_USAGE = 'homie-studio parts add <studio site>/<part id>[@<version>] [--game <id>] [--overwrite] [--no-install]\n  --no-install: install nothing and leave package.json as it is; a package the part builds on that this studio does not have is named NOT INSTALLED with the npm command that installs it (the part will not build until then).';
+
+export async function partsCommand(root, sub, positional, flags, { log = () => {}, fetch, npm } = {}) {
+  const arg = positional[2];
+  const str = (k) => (typeof flags.get(k) === 'string' ? flags.get(k) : null);
+  switch (sub ?? 'find') {
+    case 'find': return findParts(root, positional.slice(2).join(' '), { kind: str('kind'), tag: str('tag'), license: str('license'), builds: str('builds'), fetch, hub: str('hub') });
+    case 'new': return newPart(root, arg, { kind: str('kind') ?? 'mechanic', name: str('name'), from: str('from'), paths: positional.slice(3) });
+    case 'check': return checkParts(root, arg ?? null, { write: true });
+    case 'share': return arg ? sharePart(root, arg, true) : { ok: false, command: 'parts share', why: 'name the part to share' };
+    case 'unshare': return arg ? sharePart(root, arg, false) : { ok: false, command: 'parts unshare', why: 'name the part to stop sharing' };
+    case 'add': return arg ? addPart(root, arg, { fetch, ...(npm ? { npm } : {}), install: !flags.has('no-install'), say: log, game: str('game'), overwrite: flags.has('overwrite') }) : { ok: false, command: 'parts add', why: `name the part: "<studio site>/<part id>"\n${PARTS_ADD_USAGE}` };
+    default: return { ok: false, command: 'parts', why: `"${sub}" is not a parts command: ${PARTS_VERBS.join(', ')}` };
+  }
+}
+
+/* ------------------------------------------------------------------ plain lines */
+
+const costWords = (c) => { const b = []; if (Number.isFinite(c?.bytes)) b.push(`${Math.max(1, Math.round(c.bytes / 1024))} KB`); if (Number.isFinite(c?.triangles)) b.push(`${c.triangles} triangles`); if (Number.isFinite(c?.drawCalls)) b.push(`${c.drawCalls} draws`); if (Number.isFinite(c?.textureMB)) b.push(`${c.textureMB} MB textures`); return b.join(', '); };
+const buildsWords = (r) => [...Object.keys(r?.packages && typeof r.packages === 'object' ? r.packages : {}), ...(Array.isArray(r?.parts) ? r.parts.map((x) => `the part ${x}`) : [])].join(', ');
+const issueLines = (issues) => issues.map((i) => `  ${i.level === 'conflict' ? 'CANNOT BE COMBINED' : i.level === 'warn' ? 'look' : 'note'} ${i.parts.join(' + ')}: ${i.problem}${i.fix ? `\n      ${i.fix}` : ''}`);
+const packageLines = (rows) => rows.filter((p) => p.state !== 'ok').map((p) => (p.state === 'installed' ? `  npm installed ${p.name}@${p.range}, for ${p.by}` : p.state === 'missing' ? `  NOT INSTALLED ${p.name}@${p.range}: ${p.why} npm installs it with: ${p.command}` : `  ${p.state === 'pinned' ? 'PACKAGE DOES NOT FIT' : 'NPM FAILED'}: ${p.why}`));
+
+function addLines(r) {
+  const L = [];
+  if (r.was && r.same) L.push(`${r.ref} ${r.version} is already here and unchanged.`);
+  else if (r.was) L.push(`${r.ref}: ${r.was} → ${r.version}. ${[r.changes.changed.length ? `changed: ${r.changes.changed.join(', ')}` : '', r.changes.added.length ? `new: ${r.changes.added.join(', ')}` : '', r.changes.removed.length ? `gone: ${r.changes.removed.join(', ')}` : ''].filter(Boolean).join('; ') || 'the same files'}. Your tuning.json was kept${r.replaced?.length ? `; REPLACED your edited ${r.replaced.join(', ')} as asked` : ''}.`);
+  else L.push(`${r.name} ${r.version} (${r.kind}) from ${r.host} is in ${r.dir}: ${r.files} files, every one checked against its SHA-256. It is this studio's to tune now.`);
+  if (r.from?.name || r.from?.game) L.push(`  It came out of ${r.from.name ?? r.from.game}${r.from.studio ? ` by ${r.from.studio}` : ''}.`);
+  L.push(`  Licence: ${r.license ?? 'NONE NAMED'} (asks ${r.asks ?? 'unknown'})${r.attribution ? `; credit: ${r.attribution}` : ''}`);
+  if (r.credits?.length) L.push(`  Credited in ${r.credits.join(', ')}.`);
+  else if (!r.game) L.push('  It is credited in a game\'s credits when that game imports it (the build does it).');
+  if (r.import) L.push(`  Use it: import … from '${r.import}'`);
+  L.push(...packageLines(r.packages ?? []));
+  for (const n of r.needs ?? []) L.push(`  It needs another part, ${n.ref}: ${n.add}`);
+  L.push(...issueLines(r.licences ?? []));
+  return L;
+}
+
+export function partsLines(r) {
+  const L = [];
+  switch (r.command) {
+    case 'parts find': {
+      if (!r.hub.ok) L.push(r.hub.why, '');
+      if (!r.results.length) L.push(r.hub.ok ? `No shared part matches${r.query ? ` "${r.query}"` : ''} (${r.searched.hub} in the catalogue, ${r.searched.here} in this studio). Write it; if it turns out reusable, it can become a part.` : 'Nothing in this studio matches.');
+      for (const p of r.results) {
+        L.push(`${p.name} (${p.kind}) ${p.version ?? ''} · ${p.license ?? 'no licence named'} · ${p.where === 'hub' ? p.ref : p.where === 'here' ? `${p.ref} (already here)` : `${p.id} (this studio's own${p.share ? ', shared' : ', private'})`}`);
+        if (p.summary) L.push(`  ${p.summary}`);
+        if (p.from?.name || p.from?.game) L.push(`  from ${p.from.name ?? p.from.game}${p.from.studio ? ` by ${p.from.studio}` : ''}`);
+        const bits = [costWords(p.cost) && `costs ${costWords(p.cost)}`, buildsWords(p.requires) && `builds on ${buildsWords(p.requires)}`, p.rig && `rig ${p.rig}`, p.netplay && `in a room: ${p.netplay}`].filter(Boolean);
+        if (bits.length) L.push(`  ${bits.join(' · ')}`);
+        L.push(`  ${p.say}`);
+      }
+      break;
+    }
+    case 'parts new':
+      L.push(`parts/${r.id} is a new ${r.kind} part (private).${r.lifted ? ` Lifted out of games/${r.from}: ${r.lifted.moved.length} module(s) moved${r.lifted.copied.length ? `, ${r.lifted.copied.length} other file(s) copied` : ''}.` : ''}`, ...r.next.map((n) => `  ${n}`));
+      break;
+    case 'parts check':
+      for (const row of r.rows) {
+        L.push(`${row.id}${row.version ? ` ${row.version}` : ''}: ${row.ok ? 'reads fine' : 'NOT A PART YET'}${row.share ? ', shared' : row.shareable ? ', could be shared' : ', private'}`);
+        for (const p of row.problems) L.push(`  ${p.level === 'refuse' ? 'FIX ' : 'look'} ${p.field}: ${p.problem}${p.fix ? `\n      ${p.fix}` : ''}`);
+        if (!row.shareable) { L.push('  Before it can be shared:'); for (const p of row.sharing) L.push(`    ${p.field}: ${p.problem}${p.fix ? `\n        ${p.fix}` : ''}`); }
+      }
+      for (const b of r.brought) L.push(`${b.ref}${b.version ? ` ${b.version}` : ''}: ${b.ok ? (b.edited.length ? `edited here (${b.edited.join(', ')}); a newer version will not replace them without being told to` : 'as fetched') : b.problem ?? `missing ${b.missing.join(', ')}`}${b.fix ? `\n      ${b.fix}` : ''}`);
+      if (!r.rows.length && !r.brought.length) L.push('No parts here yet.');
+      break;
+    case 'parts share':
+      L.push(`parts/${r.id} ${r.version} is shared under ${r.license} (asks ${r.asks}).`, r.effect);
+      break;
+    case 'parts unshare':
+      L.push(`parts/${r.id} is private.`, r.effect);
+      break;
+    case 'parts add':
+      L.push(...addLines(r));
+      break;
+    default:
+      L.push(JSON.stringify(r));
+  }
+  return L;
+}