incanto 0.46.0 → 0.48.0

package/bin/incanto-check.mjs

@@ -106,4 +106,8 @@ if (args.json) {
   }
   console.log(`\n${results.length - failed.length}/${results.length} scene(s) valid`);
 }
-process.exit(failed.length === 0 ? 0 : 1);
+// `exitCode`, never `process.exit()`: stdout to a PIPE is written
+// asynchronously, and exiting discards whatever has not flushed. A --json
+// report read by another program came back truncated — silently, and only
+// when piped, which is the only way a program reads it.
+process.exitCode = failed.length === 0 ? 0 : 1;

package/bin/incanto-feel.mjs

@@ -109,4 +109,8 @@ if (!args.json) {
   }
 }
 
-process.exit(report.player ? 0 : 1);
+// `exitCode`, never `process.exit()`: stdout to a PIPE is written
+// asynchronously, and exiting discards whatever has not flushed. A --json
+// report read by another program came back truncated — silently, and only
+// when piped, which is the only way a program reads it.
+process.exitCode = report.player ? 0 : 1;

package/bin/incanto-frame.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 /**
  * incanto-frame — what is actually on screen, as numbers.
  *
@@ -26,6 +26,7 @@ const { listeningPorts, parseProcNetTcp } = await import(
   pathToFileURL(join(PKG, 'dist', 'vite.js')).href
 );
 const { frameText, diffText } = await import(pathToFileURL(join(PKG, 'dist', '3d.js')).href);
+const { parseDrive } = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
 
 const args = process.argv.slice(2);
 const asJson = args.includes('--json');
@@ -37,6 +38,10 @@ const flag = (name) => {
   return next && !next.startsWith('-') ? next : '';
 };
 const gridArg = flag('--grid');
+const outArg = flag('--out');
+const sizeArg = flag('--size');
+const driveArg = flag('--do');
+const driveFile = flag('--do-file');
 const remember = flag('--remember');
 const diff = flag('--diff');
 const threshold = flag('--threshold');
@@ -45,6 +50,10 @@ if (args.includes('--help') || args.includes('-h')) {
 
   --json          the full report as JSON instead of prose
   --grid WxH      cells across and down (default 16x9)
+  --out FILE      also write the frame as a PNG you can look at
+  --size N        longest side of that PNG (default 512)
+  --do SCRIPT     drive the game first, THEN capture (see below)
+  --do-file FILE  the same script, from a file
   --port N        skip discovery and use this port
 
   --remember [L]  keep this frame as the baseline named L (default "last")
@@ -52,7 +61,25 @@ if (args.includes('--help') || args.includes('-h')) {
   --threshold N   a cell has changed when it moves this far, 0..255 (default 3)
 
 Run your game's dev server and open the preview page first: the pixels live in
-the browser, not in the dev server.
+the browser, not in the dev server. Nothing headless is involved and no browser
+is installed: the page that is already open does the rendering.
+
+The report says whether anything was drawn, where the subject is and how much of
+the frame it fills. When that is not enough, look:
+
+  incanto-frame --out shot.png    # then open it, or read it
+
+Every interesting state in a game is downstream of input, so --do drives the
+running game before capturing — the same words incanto-play takes:
+
+  incanto-frame --do "vector move 0 1; step 3000; vector move 0 0" --out bridge.png
+  incanto-frame --do "press jump; step 400" --out midair.png
+
+  press/release ACTION · vector ACTION X Y · key CODE down|up
+  pointer DX DY · step MS        (semicolons or newlines separate)
+
+step waits on the real clock: this is the live game, with its own loop.
+
 
 The report of ONE frame has a floor: a one-pixel seam is a fraction of a level
 once a cell is averaged, and nothing can tell it apart from a thin rope in the
@@ -100,6 +127,24 @@ function bsdListeningPorts() {
   }
 }
 
+/** The script to run before capturing, from `--do` or `--do-file`. */
+const driveScript = driveFile ? read(driveFile) : driveArg;
+if (driveFile && driveScript === null) {
+  console.error(`cannot read ${driveFile}`);
+  process.exit(1);
+}
+if (driveScript) {
+  const parsed = parseDrive(driveScript);
+  if (parsed.error) {
+    // Refuse here rather than in the page: a bad command that ran nothing would
+    // hand back the boot screen, and nothing about that frame would say so.
+    console.error(
+      `${parsed.error}\n  commands: press/release ACTION · vector ACTION X Y · key CODE down|up · pointer DX DY · step MS`,
+    );
+    process.exit(1);
+  }
+}
+
 const explicit = args.includes('--port') ? Number(args[args.indexOf('--port') + 1]) : null;
 const discovered = explicit ? [explicit] : await listeningPorts({ read });
 const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
@@ -138,19 +183,40 @@ if (!found) {
 
 const params = new URLSearchParams();
 if (gridArg !== null) params.set('grid', gridArg);
+if (outArg) params.set('image', sizeArg || '512');
+if (driveScript) {
+  params.set('drive', driveScript);
+  // Tell the server how long to wait: the script runs in real time.
+  const totalMs = parseDrive(driveScript).totalMs;
+  params.set('driveMs', String(totalMs));
+}
 if (remember !== null) params.set('remember', remember);
 if (diff !== null) params.set('diff', diff);
 if (threshold) params.set('threshold', threshold);
 const q = params.toString();
 const res = await fetch(`http://${found.host}:${found.port}/__incanto/frame${q ? `?${q}` : ''}`, {
-  signal: AbortSignal.timeout(10_000),
+  // Outlast the server's own budget, or the CLI gives up on an answer that
+  // was on its way.
+  signal: AbortSignal.timeout(15_000 + (driveScript ? parseDrive(driveScript).totalMs * 2 : 0)),
 });
 const body = await res.json().catch(() => null);
 
+if (body?.error === 'page-not-drawing') {
+  console.error(
+    `the page on :${found.port} is connected but not drawing.\n` +
+      '  A frame is captured inside a render, and a browser stops rendering a tab it\n' +
+      '  considers hidden — including a window covered by another one. Bring the\n' +
+      '  preview to the front and run this again.',
+  );
+  process.exit(1);
+}
 if (res.status === 504 || body?.error === 'no-page-connected') {
   console.error(
-    `the dev server is running on :${found.port}, but no page is connected.\n` +
-      '  Open the preview in a browser — the pixels are there, not in the server.',
+    `the dev server is running on :${found.port}, but no page answered.\n` +
+      '  Open the preview in a browser — the pixels are there, not in the server.\n' +
+      '  If it IS open: a window covered by another one counts as hidden, and a\n' +
+      '  hidden tab gets no animation frames — such a page never finishes loading\n' +
+      '  and cannot draw. Bring it to the front.',
   );
   process.exit(1);
 }
@@ -160,15 +226,53 @@ if (!res.ok || !body?.report) {
 }
 
 const report = body.report;
+// A drive that advanced no frames moved nothing: the inputs landed on a game
+// the browser had frozen, and the frame that came back is the one from before.
+// Saying nothing here would be handing over a picture that quietly lies.
+if (driveScript && report.droveFrames === 0) {
+  console.error(
+    'the drive ran but the game never advanced — 0 frames drawn.\n' +
+      '  The page is hidden (a window covered by another counts) and the browser\n' +
+      '  stops animating it, so the inputs landed on a frozen game and this frame\n' +
+      '  is unchanged. Bring the preview to the front and try again.',
+  );
+  process.exit(1);
+}
 if (report.error) {
   console.error(`the page could not capture a frame: ${report.error}`);
   process.exit(1);
 }
 
+/** The picture, if one was asked for. Written before anything is printed, so a
+ *  report that mentions the file is a report whose file exists. */
+let wroteImage = null;
+if (outArg) {
+  const dataUrl = typeof report.image === 'string' ? report.image : null;
+  const base64 = dataUrl?.slice(dataUrl.indexOf(',') + 1);
+  if (!base64) {
+    console.error(
+      'the page returned no image — it is running an engine older than this CLI,\n' +
+        '  or its renderer cannot capture frames.',
+    );
+  } else {
+    writeFileSync(outArg, Buffer.from(base64, 'base64'));
+    wroteImage = outArg;
+  }
+}
+
 if (asJson) {
-  process.stdout.write(`${JSON.stringify(body, null, 2)}\n`);
+  // The base64 image is for the file, not for a terminal — the path is the
+  // useful part and a megabyte of it in a pipe is not.
+  const { image: _image, ...rest } = report;
+  process.stdout.write(
+    `${JSON.stringify({ ...body, report: rest, ...(wroteImage ? { image: wroteImage } : {}) }, null, 2)}\n`,
+  );
 } else {
   const lines = [frameText(report)];
+  if (typeof report.droveFrames === 'number') {
+    lines.push(`drove ${report.droveFrames} frames before capturing`);
+  }
+  if (wroteImage) lines.push(`wrote ${wroteImage} — open it, or read it`);
   if (body.diffError === 'no-baseline') {
     lines.push(
       `no baseline named "${diff || 'last'}" — run \`incanto-frame --remember${diff ? ` ${diff}` : ''}\` first,\n` +
@@ -183,6 +287,10 @@ if (asJson) {
   process.stdout.write(`${lines.join('\n')}\n`);
 }
 // A missing baseline is a usage error, not a picture: fail so a script notices.
-process.exit(report.black || body.diffError ? 1 : 0);
+// `exitCode`, never `process.exit()`: stdout to a PIPE is written
+// asynchronously, and exiting discards whatever has not flushed. A --json
+// report read by another program came back truncated — silently, and only
+// when piped, which is the only way a program reads it.
+process.exitCode = report.black || body.diffError ? 1 : 0;
 
 void parseProcNetTcp; // re-exported for tests; referenced so bundlers keep it

package/bin/incanto-logs.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * incanto-logs — what the RUNNING game is saying.
+ *
+ *   bunx incanto-logs
+ *   bunx incanto-logs --json
+ *
+ * `incanto-frame` gets the pixels out of the browser; this gets the WORDS. The
+ * engine writes diagnostics for exactly this purpose — a model whose fit came
+ * out at 934x, an asset that 404'd, a node that quarantined itself — and until
+ * now every one of them reached a human only, in the debug overlay's logs
+ * panel. An agent could see a game and not hear it.
+ *
+ * Unlike a frame this needs no render, so it answers from a tab the browser has
+ * stopped drawing.
+ *
+ * Exit 1 when the game reports something wrong: an error logged, an error
+ * swallowed to keep it alive, or an asset that never loaded.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const { listeningPorts } = await import(pathToFileURL(join(PKG, 'dist', 'vite.js')).href);
+const { logText } = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+if (args.includes('--help') || args.includes('-h')) {
+  console.error(`Usage: incanto-logs [--json] [--port N]
+
+What the running game is saying: its warnings and errors, the errors it
+swallowed to keep going, the assets that never loaded, and its frame rate.
+
+Run your game's dev server and open the page first — the log buffer is in the
+browser, not in the dev server. This needs no render, so a page the browser has
+stopped drawing still answers.
+
+Exit 1 when something is wrong.`);
+  process.exit(0);
+}
+
+const read = (path) => {
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+};
+
+/** Ports listening on a machine with no `/proc` (macOS, BSD) — see incanto-frame. */
+function bsdListeningPorts() {
+  try {
+    const { execFileSync } = createRequire(import.meta.url)('node:child_process');
+    const out = execFileSync('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN'], {
+      encoding: 'utf-8',
+      timeout: 1500,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const ports = new Set();
+    for (const line of out.split('\n')) {
+      const m = line.match(/:(\d+)\s*\(LISTEN\)/);
+      if (m) ports.add(Number(m[1]));
+    }
+    return [...ports];
+  } catch {
+    return [];
+  }
+}
+
+const explicit = args.includes('--port') ? Number(args[args.indexOf('--port') + 1]) : null;
+const discovered = explicit ? [explicit] : await listeningPorts({ read });
+const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
+
+let found = null;
+outer: for (const port of ports) {
+  for (const host of ['localhost', '127.0.0.1']) {
+    try {
+      const res = await fetch(`http://${host}:${port}/__incanto/ping`, {
+        signal: AbortSignal.timeout(300),
+      });
+      if (!res.ok) continue;
+      const body = await res.json();
+      if (body?.incanto) {
+        found = { host, port };
+        break outer;
+      }
+    } catch {
+      // not listening, not ours, or not answering — next
+    }
+  }
+}
+
+if (!found) {
+  console.error(
+    'no incanto dev server found.\n' +
+      '  Start your game (the dev server) and try again — the log buffer lives in\n' +
+      '  the running page, so there has to be one.',
+  );
+  process.exit(1);
+}
+
+const res = await fetch(`http://${found.host}:${found.port}/__incanto/logs`, {
+  signal: AbortSignal.timeout(10_000),
+});
+const body = await res.json().catch(() => null);
+
+if (res.status === 504 || body?.error === 'no-page-connected') {
+  console.error(
+    `the dev server is running on :${found.port}, but no page answered.\n` +
+      '  Open the preview in a browser — the log buffer is there, not in the server.',
+  );
+  process.exit(1);
+}
+if (!res.ok || !body?.report || body.report.error) {
+  console.error(
+    `could not read the game's logs: ${body?.report?.error ?? body?.error ?? res.status}`,
+  );
+  process.exit(1);
+}
+
+console.log(asJson ? JSON.stringify(body.report, null, 2) : logText(body.report));
+// `exitCode`, never `process.exit()` — stdout to a pipe is written
+// asynchronously and exiting discards what has not flushed.
+process.exitCode = body.report.ok ? 0 : 1;

package/bin/incanto-model.mjs

@@ -9,14 +9,25 @@
  *
  * Bounding boxes come from glTF POSITION accessor min/max transformed through
  * each node's TRS chain — for skinned meshes that is the BIND pose.
+ *
+ * A URL works anywhere a path does. Finding an asset is the agent8 library's
+ * job (its vector search matches meaning, which no filename filter can); this
+ * answers the question that search cannot — what will this file DO in a scene.
  */
 import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const { modelVerdict, verdictText } = await import(pathToFileURL(join(PKG, 'dist', '3d.js')).href);
 
 function parseArgs(argv) {
-  const args = { file: undefined, json: false };
-  for (const a of argv) {
+  const args = { file: undefined, json: false, key: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
     if (a === '--json') args.json = true;
     else if (a === '--help' || a === '-h') args.help = true;
+    else if (a === '--key') args.key = argv[++i];
     else if (!a.startsWith('-') && !args.file) args.file = a;
     else {
       console.error(`unknown argument: ${a}`);
@@ -26,19 +37,49 @@ function parseArgs(argv) {
   return args;
 }
 
+const isUrl = (s) => /^https?:\/\//i.test(s ?? '');
+
+/** A key from a url or path: `.../goblin_king.glb` → `goblin_king`. */
+function keyFrom(source) {
+  const file = (source.split(/[?#]/)[0] ?? '').split('/').pop() ?? '';
+  return (
+    file
+      .replace(/\.[^.]+$/, '')
+      .replace(/[^a-zA-Z0-9_-]+/g, '_')
+      .replace(/_{2,}/g, '_')
+      .replace(/^_+|_+$/g, '')
+      .toLowerCase() || 'model'
+  );
+}
+
 const args = parseArgs(process.argv.slice(2));
 if (args.help || args.error || !args.file) {
-  console.log(`Usage: npx incanto-model <file.glb|.gltf|.vrm> [--json]
+  console.log(`Usage: npx incanto-model <file.glb|.gltf|.vrm|URL> [--json] [--key NAME]
 
 Reports hierarchy, mesh stats, scene bounding box, animations, and VRM meta —
-the numbers you need to size and place a model in a scene.`);
+the numbers you need to size and place a model in a scene — then says what the
+file will DO in an incanto scene:
+
+  will the 3d/animations clips play on it (bone names decide, and a mismatch
+    keeps the bind pose with only a console warning)
+  is it a character's size, or authored in centimetres
+  does it stand on its own origin, or will a node at [0,0,0] put it in the sky
+
+and prints the scene JSON to paste. A URL works anywhere a path does, so an
+asset the agent8 library found can be checked before it is used.`);
   process.exit(args.help && !args.error ? 0 : 1);
 }
 
 // ---- container parsing --------------------------------------------------------------
 
-function readGltfJson(file) {
-  const data = readFileSync(file);
+async function bytesOf(source) {
+  if (!isUrl(source)) return readFileSync(source);
+  const res = await fetch(source);
+  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${source}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+function readGltfJson(data) {
   if (data.length >= 12 && data.readUInt32LE(0) === 0x46546c67) {
     // GLB container: header(12) then chunks [len][type][payload]
     let offset = 12;
@@ -186,11 +227,19 @@ function analyze(json) {
     if (node.skin !== undefined) entry.skinned = true;
     nodes.push(entry);
     const mesh = node.mesh !== undefined ? meshes[node.mesh] : null;
+    // A SKINNED mesh is placed by its joint matrices, not by the node it hangs
+    // off — the node's own TRS is ignored at draw time and is routinely a
+    // hundredth-scale leftover from the export. Measured on the stock
+    // `base-model.glb`: transforming through the chain reported a 1.5-unit
+    // character as 0.003 units tall, because its root carries scale 0.01. Take
+    // the vertices as authored for those, and the transformed corners for
+    // everything else, where the chain IS the placement.
+    const identity = node.skin !== undefined;
     if (mesh?.localMin && mesh.localMax) {
       for (const x of [mesh.localMin[0], mesh.localMax[0]]) {
         for (const y of [mesh.localMin[1], mesh.localMax[1]]) {
           for (const z of [mesh.localMin[2], mesh.localMax[2]]) {
-            const p = transformPoint(mat, [x, y, z]);
+            const p = identity ? [x, y, z] : transformPoint(mat, [x, y, z]);
             sceneMin = sceneMin ? sceneMin.map((v, i) => Math.min(v, p[i])) : [...p];
             sceneMax = sceneMax ? sceneMax.map((v, i) => Math.max(v, p[i])) : [...p];
           }
@@ -246,21 +295,30 @@ function analyze(json) {
 // ---- output --------------------------------------------------------------------------
 
 let report;
+let verdict;
 try {
-  const json = readGltfJson(args.file);
+  const data = await bytesOf(args.file);
+  const json = readGltfJson(data);
   if (!json.asset?.version) throw new Error('missing glTF asset header');
   report = {
     file: args.file,
-    format: readFileSync(args.file).readUInt32LE(0) === 0x46546c67 ? 'glb' : 'gltf',
+    format: data.readUInt32LE(0) === 0x46546c67 ? 'glb' : 'gltf',
     ...analyze(json),
   };
+  verdict = modelVerdict(
+    { ...report, meshes: report.meshes.length },
+    {
+      url: isUrl(args.file) ? args.file : args.file,
+      key: args.key ?? keyFrom(args.file),
+    },
+  );
 } catch (error) {
   console.error(`not a glTF/GLB/VRM file: ${String(error.message ?? error)}`);
   process.exit(1);
 }
 
 if (args.json) {
-  console.log(JSON.stringify(report, null, 2));
+  console.log(JSON.stringify({ ...report, verdict }, null, 2));
 } else {
   const out = [];
   out.push(`${report.file} (${report.format}${report.vrm ? ` · VRM ${report.vrm.spec}` : ''})`);
@@ -292,5 +350,16 @@ if (args.json) {
   for (const anim of report.animations) {
     out.push(`  anim ${anim.name}: ${anim.duration}s`);
   }
+  // The verdict is the part you act on, so it goes last — closest to the
+  // prompt, where a reader stops.
+  out.push('', verdictText(verdict));
+  if (verdict.sceneJson) {
+    const { assets, node } = verdict.sceneJson;
+    out.push(
+      '',
+      'paste into your scene:',
+      JSON.stringify(node ? { assets, node } : { assets }, null, 2),
+    );
+  }
   console.log(out.join('\n'));
 }

package/bin/incanto-playtest.mjs

@@ -133,4 +133,8 @@ if (!args.noReplays && !args.json) {
   }
 }
 
-process.exit(report.runs.some((r) => r.outcome === 'won') ? 0 : 1);
+// `exitCode`, never `process.exit()`: stdout to a PIPE is written
+// asynchronously, and exiting discards whatever has not flushed. A --json
+// report read by another program came back truncated — silently, and only
+// when piped, which is the only way a program reads it.
+process.exitCode = report.runs.some((r) => r.outcome === 'won') ? 0 : 1;