@homie-rocks/studio 0.30.2 → 0.31.0

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;
+}