@joystack/cli 0.0.0-stage → 0.1.43

package/lib/assets-page.mjs

@@ -0,0 +1,184 @@
+// `joystack assets` — the dev stack, opened on the Assets page instead of the
+// game.
+//
+// the assets page is a served page under /shared/, not a separate server: the dev
+// server already mounts the engine's shared tree, so there is nothing new to
+// start and nothing to keep in sync. That also means the assets page still works
+// when the game itself is broken, which is when it is most wanted.
+//
+// It finds the game on its own — the page asks the dev server what it is serving
+// (/__joystack/whoami) — so the URL carries no slug.
+
+import { spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import http from 'node:http';
+import { join } from 'node:path';
+import { findProject } from './project.mjs';
+import {
+  BLOCK_STRIDE, STATIC_PORT_BASE, blockIsRestricted, portInUse, whoIsOn,
+} from './ports.mjs';
+import { readEnv } from './legacy-names.mjs';
+
+export const ASSETS_PAGE_PATH = '/shared/ui/assets/';
+
+// Built from the dev server's OWN url rather than an assumed localhost:8000: a
+// lane runs on its own port base and 8000 may belong to somebody else's server,
+// and an assets page opened on the wrong port inspects the wrong game — or none.
+export function assetsPageUrl(gameUrl, { item } = {}) {
+  const base = new URL(gameUrl);
+  const q = item ? `?_item=${encodeURIComponent(item)}` : '';
+  return `${base.origin}${ASSETS_PAGE_PATH}${q}`;
+}
+
+// Does this game have anything for the assets page to show?
+//
+// The whole answer is `assets.js`, because the list IS the declaration — nothing
+// walks the folder looking for files any more. So this is the same question as
+// "did anyone declare anything", and it is asked for the dev banner: a line that
+// appears on every boot is a line nobody reads by the third one, and the tool it
+// points at is then invisible exactly when it would have helped.
+//
+// The file's CONTENTS are not read. A registry that declares nothing, or one
+// that throws on import, is a case the assets page itself reports far better
+// than a banner line could — and reading it here would mean the dev server
+// evaluating game code to decide how to print a URL.
+export function hasDeclaredAssets(projectDir) {
+  return !!projectDir && existsSync(join(projectDir, 'assets.js'));
+}
+
+// Flags that take a VALUE, so the value is not mistaken for the asset name.
+// `joystack assets --port 8210` is two argv entries, and reading "the first
+// argument that is not a flag" turns 8210 into the thing to open — on the one
+// command whose entire job is opening the right asset.
+// The `--set`, `--tag`, `--out` and `--against` of `joystack assets <id> --sheet`
+// are among them (assets-sheet.mjs).
+export const VALUED_FLAGS = new Set(['--port', '--set', '--tag', '--out', '--against']);
+
+export function itemArg(rest = []) {
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a.startsWith('--')) {
+      if (VALUED_FLAGS.has(a)) i += 1;
+      continue;
+    }
+    return a;
+  }
+  return undefined;
+}
+
+export function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    // Detached and fully ignored: a browser that outlives the CLI, and one that
+    // cannot hold the dev stack's stdio open if it decides to write to it.
+    spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Reusing a running `joystack dev` ───────────────────────────────────────────
+//
+// `joystack assets` next to a `joystack dev` the creator is already using opens the
+// Assets page on that stack. Starting its own would go through dev()'s port
+// takeover, which treats any server for the same game as stale and kills it,
+// and the page would then be served by a stack nobody is watching. Reusing the
+// running one also keeps the agent session that `joystack dev` was started with,
+// so the page's agent channel reaches the same agent.
+//
+// "Running" means healthy, not merely present: the server answers the
+// ownership probe with this game's folder AND serves the Assets page itself.
+// A server for this game that answers the probe but cannot serve the page (an
+// engine folder removed under it, a stuck request handler) is not reused, and
+// the dev() that `joystack assets` then starts reclaims its port as before.
+
+// How long the health probe waits for the page. Generous on purpose: a busy
+// but working server that misses a short deadline would be reclaimed (killed)
+// by the dev() that follows.
+const HEALTH_TIMEOUT_MS = 1500;
+
+// Does the server on `port` answer GET `path` with 200? Loopback only, and
+// with a literal Host, which is what the dev server requires of a local
+// request.
+function serves(port, path, timeoutMs) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path, headers: { Host: `127.0.0.1:${port}` }, timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve(res.statusCode === 200);
+    });
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.on('error', () => resolve(false));
+  });
+}
+
+// One folder reached through different paths (a symlinked temp or home
+// directory) is still one game.
+const real = (dir) => {
+  try { return realpathSync(dir); } catch { return dir; }
+};
+
+// The running, healthy dev stack serving `projectDir`, as `{ port, origin }`,
+// or null. With `port` (an explicit --port) only that port is looked at;
+// otherwise every block `joystack dev` could have taken, in the order it takes
+// them.
+export async function findRunningStack({
+  projectDir, port = null, base = STATIC_PORT_BASE, blocks = 24, timeoutMs = HEALTH_TIMEOUT_MS,
+} = {}) {
+  const candidates = port != null
+    ? [port]
+    : Array.from({ length: blocks }, (_, i) => base + i * BLOCK_STRIDE).filter((p) => !blockIsRestricted(p));
+  for (const p of candidates) {
+    if (!(await portInUse(p))) continue;
+    const owner = await whoIsOn(p, Math.min(timeoutMs, 1000));
+    if (!owner?.projectDir || real(owner.projectDir) !== real(projectDir)) continue;
+    if (!(await serves(p, ASSETS_PAGE_PATH, timeoutMs))) continue;
+    return { port: p, origin: `http://localhost:${p}` };
+  }
+  return null;
+}
+
+// What `joystack assets` runs: reuse the game's running dev stack when there is
+// a healthy one, otherwise start one with `startDev` (dev() in the CLI).
+// Resolves `{ reused, target, handle }`; `handle` is the started stack, null
+// when one was reused (nothing for this process to keep alive or stop).
+export async function openAssets({
+  cwd = process.cwd(), port, item, agentSession = null, startDev,
+  base = STATIC_PORT_BASE, blocks = 24, env = process.env,
+} = {}) {
+  const project = findProject(cwd);
+  const fromEnv = Number(readEnv('JOYSTACK_DEV_PORT', env));
+  const explicit = port ?? (Number.isInteger(fromEnv) && fromEnv > 0 ? fromEnv : null);
+  const live = await findRunningStack({ projectDir: project.dir, port: explicit, base, blocks });
+  if (live) {
+    // The page's agent channel belongs to the stack, so a reused stack reaches
+    // the agent that started IT. When the caller is an agent and the running
+    // stack has none, notes sent from the page would only be filed, and the
+    // caller is told so rather than left waiting for them.
+    const agentUnreachable = !!agentSession && !(await stackAgent(live.port));
+    return { reused: true, target: assetsPageUrl(live.origin, { item }), handle: null, agentUnreachable };
+  }
+  const handle = await startDev({ cwd, port, agentSession });
+  return { reused: false, target: assetsPageUrl(handle.url, { item }), handle, agentUnreachable: false };
+}
+
+// The agent a running stack would wake (`'Claude Code'`), or null when none
+// is listening or the stack cannot say. Loopback only, with the header the
+// status route requires.
+function stackAgent(port, timeoutMs = HEALTH_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    const req = http.get({
+      host: '127.0.0.1', port, path: '/__joystack/agent-inbox/status', timeout: timeoutMs,
+      headers: { Host: `127.0.0.1:${port}`, 'X-Joystack-Agent-UI': '1' },
+    }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (d) => { if (body.length < 65536) body += d; });
+      res.on('end', () => {
+        try { resolve(res.statusCode === 200 ? JSON.parse(body).agent ?? null : null); } catch { resolve(null); }
+      });
+    });
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.on('error', () => resolve(null));
+  });
+}

package/lib/assets-sheet.mjs

@@ -0,0 +1,365 @@
+// `joystack assets <id> --sheet` — a view sheet of one 3D asset, drawn by the
+// Assets page in a headless browser and written to disk, for an agent (or a
+// person) to look at without opening anything.
+//
+// The sheet is the page's own (shared/ui/assets/sheet.js, through
+// `window.joystackAssets.sheet()` and headless.mjs `viewSheet`), so the numbers
+// and pictures here are exactly what the page shows. This file only finds a
+// dev stack to open the page on, drives it, and writes the files.
+//
+//   joystack assets ship --sheet                       .joystack/sheets/ship-sheet.png (+ .json)
+//   joystack assets ship --sheet --set height=2,hull=#3366cc --tag tall
+//   joystack assets ship --sheet --against .joystack/sheets/ship-before-sheet.json
+//
+// ── WHAT IS TRUSTED ─────────────────────────────────────────────────────────
+//
+// Everything on the command line is the creator's own. The asset id and the
+// tag become part of a file name, so they are reduced to safe characters
+// before they touch a path. `--against` names a sheet report written earlier;
+// its PNG is found beside it by name, never from anything inside the report,
+// so the report's contents cannot point the command at another file.
+//
+// A game folder may come from somebody else, and the game's own code runs in
+// the page this command drives. So neither file `--against` reads may be a
+// symbolic link (a planted `before-sheet.png` linked to a private file would
+// otherwise be read and handed to that code), the PNG must be a PNG, each
+// sheet is written to a temporary name and renamed into place (a planted link
+// at the destination is replaced, never written through), and the default
+// folder must really be inside the game. Text that came from the page is
+// stripped of control characters before it reaches the terminal.
+
+import { randomBytes } from 'node:crypto';
+import {
+  closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { findProject, resolveEngine } from './project.mjs';
+import { findRunningStack, ASSETS_PAGE_PATH } from './assets-page.mjs';
+import { gpuArgs } from './smoke-gpu-preload.mjs';
+import { printable } from './printable.mjs';
+import { stateDirName } from './legacy-names.mjs';
+
+export const SHEET_HELP = `joystack assets <id> --sheet [--set <k=v,…>] [--tag <name>] [--out <dir>] [--against <sheet.json>]
+
+  Draws a view sheet of one 3D asset: front, side, back and top at one scale
+  with a ruler, a three-quarter view, the in-game view when assets.js declares
+  a camera, the reference images, and the measured stats. Writes
+  <dir>/<id>[-<tag>]-sheet.png and the same name as .json (default
+  dir: .joystack/sheets/).
+
+  --set k=v,…      draw it at these parameter values. A value outside what the
+                   asset declares is an error that names the range; nothing is
+                   drawn at a value it did not ask for.
+  --tag <name>     added to the file names, e.g. --tag before / --tag after
+  --against <f>    an earlier sheet's .json: also writes <id>[-<tag>]-sheet-compare.png,
+                   the two side by side with what moved between them
+  --out <dir>      where to write
+
+  Uses the dev stack already running for this game, or starts one for the
+  length of the command. Needs playwright in the game (npm i -D playwright).`;
+
+// Flags of this mode that take no value. Any other flag is a typo, and is
+// refused rather than skipped: a skipped `--tgs before` would make `before`
+// the asset to draw.
+const SHEET_SWITCHES = new Set(['--sheet', '--no-open', '--help']);
+
+// A file-name-safe version of an id or a tag: letters, digits, dot, dash and
+// underscore, never starting with a dot, never empty.
+export function safeName(text) {
+  const s = String(text ?? '').replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^\.+/, '_').slice(0, 80);
+  return s || '_';
+}
+
+// `k=v,k=v`, possibly given more than once, as { k: 'v' }. Values stay text:
+// the page reads them against the asset's declaration, which is the only
+// thing that knows what type each one is.
+export function parseSet(texts) {
+  const out = {};
+  for (const text of texts) {
+    for (const pair of String(text).split(',')) {
+      const at = pair.indexOf('=');
+      const key = at > 0 ? pair.slice(0, at).trim() : '';
+      if (!key) throw new Error(`--set takes k=v pairs separated by commas; "${pair}" has no name before "="`);
+      out[key] = pair.slice(at + 1).trim();
+    }
+  }
+  return out;
+}
+
+// The arguments after `joystack assets`, read for the sheet mode.
+export function parseSheetArgs(rest = []) {
+  const opts = { id: undefined, sets: [], tag: null, out: null, against: null, port: null };
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    const value = () => {
+      const v = rest[i + 1];
+      if (v == null || v.startsWith('--')) throw new Error(`${a} needs a value.\n\n${SHEET_HELP}`);
+      i += 1;
+      return v;
+    };
+    if (a === '--set') opts.sets.push(value());
+    else if (a === '--tag') opts.tag = value();
+    else if (a === '--out') opts.out = value();
+    else if (a === '--against') opts.against = value();
+    else if (a === '--port') {
+      const p = Number(value());
+      if (!Number.isInteger(p) || p <= 0 || p > 65535) throw new Error('--port needs a port number');
+      opts.port = p;
+    } else if (a.startsWith('--')) {
+      if (!SHEET_SWITCHES.has(a)) throw new Error(`joystack assets --sheet has no option ${a}.\n\n${SHEET_HELP}`);
+    } else if (opts.id === undefined) opts.id = a;
+    else throw new Error(`joystack assets --sheet draws one asset; got "${opts.id}" and "${a}".\n\n${SHEET_HELP}`);
+  }
+  if (!opts.id) throw new Error(`Name the asset: joystack assets <id> --sheet\n\n${SHEET_HELP}`);
+  return { ...opts, values: parseSet(opts.sets) };
+}
+
+// The largest sheet report and sheet picture `--against` will read. A report
+// is a few kilobytes and a sheet a few hundred; anything far larger is not one.
+const REPORT_MAX_BYTES = 2 * 1024 * 1024;
+const PNG_MAX_BYTES = 32 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// A regular file, or a reason it is not one (missing, a link, a folder…).
+function plainFile(path, what, max) {
+  let st;
+  try {
+    st = lstatSync(path);
+  } catch {
+    return `${what} does not exist`;
+  }
+  if (st.isSymbolicLink()) return `${what} is a symbolic link; give the file itself`;
+  if (!st.isFile()) return `${what} is not a file`;
+  if (st.size > max) return `${what} is too large to be one written by joystack assets --sheet`;
+  return null;
+}
+
+// An earlier sheet, from the path of its report: { report, png, pngPath }.
+export function readEarlierSheet(path) {
+  const jsonPath = resolve(path);
+  if (!/\.json$/i.test(jsonPath)) throw new Error(`--against takes the .json written beside a sheet; got ${path}`);
+  if (!existsSync(jsonPath)) throw new Error(`--against: no such file ${path}`);
+  const notJson = plainFile(jsonPath, path, REPORT_MAX_BYTES);
+  if (notJson) throw new Error(`--against: ${notJson}`);
+  let report;
+  try {
+    report = JSON.parse(readFileSync(jsonPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`--against: ${path} is not valid JSON (${err.message})`);
+  }
+  if (report?.kind !== 'joystack-asset-sheet') throw new Error(`--against: ${path} is not a sheet report written by joystack assets --sheet`);
+  const pngPath = jsonPath.replace(/\.json$/i, '.png');
+  if (!existsSync(pngPath)) throw new Error(`--against: the sheet picture ${basename(pngPath)} is missing beside ${basename(jsonPath)}`);
+  const notPng = plainFile(pngPath, `the sheet picture ${basename(pngPath)}`, PNG_MAX_BYTES);
+  if (notPng) throw new Error(`--against: ${notPng}`);
+  const png = readFileSync(pngPath);
+  if (!png.subarray(0, 8).equals(PNG_SIGNATURE)) throw new Error(`--against: ${basename(pngPath)} is not a PNG`);
+  return { report, png, pngPath };
+}
+
+// Written beside its destination under a temporary name, then renamed over
+// it: a rename replaces whatever is at the destination, a link included,
+// where a write would follow the link to its target.
+//
+// The temporary name is random and is created exclusively ('wx'), so a link
+// or file planted at it beforehand makes the write fail instead of being
+// written through. A temporary file this call created is removed if anything
+// after its creation fails; one it did not create is never touched.
+// `suffix` names the temporary file and exists for tests.
+export function writeReplacing(path, data, { suffix = () => randomBytes(8).toString('hex') } = {}) {
+  const tmp = `${path}.${suffix()}.tmp`;
+  const fd = openSync(tmp, 'wx', 0o644);
+  try {
+    try {
+      const bytes = typeof data === 'string' ? Buffer.from(data) : data;
+      for (let at = 0; at < bytes.length;) at += writeSync(fd, bytes, at, bytes.length - at);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tmp, path);
+  } catch (err) {
+    try { unlinkSync(tmp); } catch { /* already gone */ }
+    throw err;
+  }
+}
+
+// The default sheets folder, created inside the game. `.joystack` and
+// `.joystack/sheets` must each be a real folder, never a link (even one that
+// points inside the game today), and the folder must resolve inside the game
+// once it exists.
+export function sheetsDirIn(projectDir) {
+  let dir = projectDir;
+  for (const part of [stateDirName(projectDir), 'sheets']) {
+    dir = join(dir, part);
+    const shown = relative(projectDir, dir);
+    let st = null;
+    try {
+      st = lstatSync(dir);
+    } catch {
+      mkdirSync(dir);
+      st = lstatSync(dir);
+    }
+    if (st.isSymbolicLink()) throw new Error(`${shown} in this game is a symbolic link; remove it, or choose a folder with --out`);
+    if (!st.isDirectory()) throw new Error(`${shown} in this game is not a folder; remove it, or choose a folder with --out`);
+  }
+  const real = realpathSync(dir);
+  const rel = relative(realpathSync(projectDir), real);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`${stateDirName(projectDir)}/sheets in this game leads outside it (to ${printable(real)}); remove the link, or choose a folder with --out`);
+  }
+  return dir;
+}
+
+// The newest engine release whose Assets page driver (shared/ui/assets/
+// headless.mjs) lacks what `joystack assets --json` and `--sheet` call: the
+// list of declared ids, one asset's record, and the view sheet. The CLI is
+// installed separately from a game's engine, so it can meet one this old.
+export const ENGINE_WITHOUT_ASSET_DRIVER = '0.2.32';
+
+// The error for an engine whose page driver lacks what `what` needs, naming
+// the game's installed engine version when it can be read.
+export function engineTooOld(what, projectDir) {
+  let version = null;
+  try {
+    version = resolveEngine(projectDir).version;
+  } catch { /* no engine installed, or no package.json to read */ }
+  const has = version ? ` (this game has ${printable(version)})` : '';
+  return new Error(`${what} needs an engine newer than ${ENGINE_WITHOUT_ASSET_DRIVER}${has}. Run \`joystack update\`, then try again.`);
+}
+
+// The game's Assets page driver. An engine with no headless.mjs at all is
+// older than every engine that has these commands.
+export async function loadDriver(projectDir, what) {
+  const path = join(resolveEngine(projectDir).sharedDir, 'ui', 'assets', 'headless.mjs');
+  if (!existsSync(path)) throw engineTooOld(what, projectDir);
+  return import(pathToFileURL(path).href);
+}
+
+// A number the page measured, for printing: the page's code can hand back
+// anything, so whatever is not a finite number prints as "?".
+const num = (v, digits) => {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return '?';
+  return digits == null ? Math.round(n).toLocaleString('en-US') : n.toFixed(digits);
+};
+
+// printable() lives in printable.mjs; exported here too for the callers of this module.
+export { printable };
+
+// Playwright from the game's own install, the same one its smokes use.
+// `why` finishes the sentence "… is measured in a headless browser".
+export async function loadPlaywright(projectDir, why = 'a view sheet is drawn') {
+  try {
+    const req = createRequire(join(projectDir, 'package.json'));
+    const pkgDir = dirname(req.resolve('playwright/package.json'));
+    const pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+    const entry = typeof pkg.exports?.['.'] === 'object' ? pkg.exports['.'].import ?? pkg.exports['.'].default : null;
+    return await import(pathToFileURL(join(pkgDir, entry ?? pkg.main ?? 'index.js')).href);
+  } catch {
+    throw new Error(`${why} in a headless browser, and this game has no playwright. Run: npm i -D playwright && npx playwright install chromium`);
+  }
+}
+
+const lines = (problems) => problems.map((p) => printable(`  ✗ ${p.key}=${p.requested}: ${p.key} ${p.reason}`)).join('\n');
+
+// Draw one sheet. `startDev` starts a dev stack (dev() in the CLI) when none
+// is running for the game. `origin`, `browser` and `headless` are for a caller
+// that already has them (a test): an origin skips looking for a stack, a
+// browser is used and left open, and `headless` is the page driver's module.
+export async function assetsSheet({
+  cwd = process.cwd(), id, values = {}, tag = null, out = null, against = null, port = null,
+  startDev = null, log = console.log, origin = null, browser = null, headless = null,
+} = {}) {
+  const earlier = against ? readEarlierSheet(resolve(cwd, against)) : null;
+  let project = null;
+  let stack = null;
+  let started = null;
+  if (!origin) {
+    project = findProject(cwd);
+    stack = await findRunningStack({ projectDir: project.dir, port });
+    if (!stack) {
+      if (!startDev) throw new Error('no dev stack is running for this game');
+      const quiet = [];
+      started = await startDev({ cwd, port: port ?? undefined, watch: false, reload: false, noMp: true, log: (l) => quiet.push(l) });
+      stack = { origin: new URL(started.url).origin };
+    }
+    origin = stack.origin;
+  }
+  if (!project && !(headless && browser)) project = findProject(cwd);
+  const base = `${safeName(id)}${tag ? `-${safeName(tag)}` : ''}-sheet`;
+
+  let ownBrowser = null;
+  try {
+    const driver = headless ?? await loadDriver(project.dir, 'joystack assets --sheet');
+    if (typeof driver.viewSheet !== 'function') throw engineTooOld('joystack assets --sheet', project?.dir ?? cwd);
+    if (!browser) {
+      const { chromium } = await loadPlaywright(project.dir);
+      ownBrowser = await chromium.launch({ args: gpuArgs() });
+      browser = ownBrowser;
+    }
+    const url = `${origin}${ASSETS_PAGE_PATH}?_item=${encodeURIComponent(id)}&_thumbs=0`;
+    const insp = await driver.openAssetsPage({ browser, url, viewport: { width: 1280, height: 800 } });
+    try {
+      if (typeof insp.ids !== 'function') throw engineTooOld('joystack assets --sheet', project?.dir ?? cwd);
+      const ids = await insp.ids();
+      if (!Array.isArray(ids) || !ids.includes(id)) {
+        const declared = Array.isArray(ids) ? ids.map(printable).join(', ') : '';
+        throw new Error(`there is no asset "${printable(id)}" in this game's assets.js. Declared: ${declared || '(none)'}`);
+      }
+      const made = await driver.viewSheet(insp, {
+        values,
+        against: earlier ? { report: earlier.report, png: earlier.png } : null,
+      });
+      if (made.problems) {
+        throw new Error(`these values would not apply as given, so no sheet was drawn:\n${lines(made.problems)}`);
+      }
+      let outDir;
+      if (out) {
+        outDir = resolve(cwd, out);
+        mkdirSync(outDir, { recursive: true });
+      } else {
+        outDir = sheetsDirIn(project?.dir ?? cwd);
+      }
+      const png = join(outDir, `${base}.png`);
+      const json = join(outDir, `${base}.json`);
+      writeReplacing(png, made.png);
+      writeReplacing(json, `${JSON.stringify(made.report, null, 2)}\n`);
+      const files = { png, json };
+      if (made.comparison) {
+        files.compare = join(outDir, `${base}-compare.png`);
+        writeReplacing(files.compare, made.comparison.png);
+      }
+      const r = made.report;
+      const missing = (Array.isArray(r.refs) ? r.refs : []).filter((x) => !x?.ok);
+      const shown = (p) => (isAbsolute(p) && project && p.startsWith(project.dir) ? p.slice(project.dir.length + 1) : p);
+      log(`\n  🗂  ${printable(r.label)} (${printable(r.id)}) → ${shown(files.png)}`);
+      log(`     report → ${shown(files.json)}`);
+      if (files.compare) log(`     before/after → ${shown(files.compare)}`);
+      const s = r.stats;
+      log(`     ${num(s?.triangles)} tris · ${num(s?.size?.x, 2)} × ${num(s?.size?.y, 2)} × ${num(s?.size?.z, 2)} u`);
+      if (r.inGame) {
+        const b = r.inGame.box ?? {};
+        const d = r.inGame.drawn;
+        const screen = `${num(r.inGame.camera?.screen?.width)} × ${num(r.inGame.camera?.screen?.height)} screen`;
+        log(b.behind
+          ? '     in game: the camera is inside the model at the declared distance'
+          : `     in game: ${d ? `drawn ${num(d.width)} × ${num(d.height)} px, ` : ''}bounding box ${num(b.width)} × ${num(b.height)} px on a ${screen}${b.fits ? '' : ' (does not fit)'}`);
+      } else {
+        log('     in game: no camera declared in assets.js');
+      }
+      const empty = Object.entries(r.views ?? {}).filter(([, v]) => v?.empty).map(([k]) => k);
+      if (empty.length) log(`     empty views: ${empty.map(printable).join(', ')}`);
+      if (made.comparison) for (const line of made.comparison.changes) log(`     ${printable(line)}`);
+      for (const m of missing) log(`  ✗ reference ${printable(m.src)}: ${printable(m.error)}`);
+      if (insp.errors.length) log(`  ⚠ the page reported: ${printable(insp.errors.join('; '))}`);
+      return { files, report: r, missingRefs: missing };
+    } finally {
+      await insp.close();
+    }
+  } finally {
+    if (ownBrowser) await ownBrowser.close();
+    await started?.stop();
+  }
+}