incanto 0.46.0 → 0.47.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.
  *
@@ -37,6 +37,8 @@ const flag = (name) => {
   return next && !next.startsWith('-') ? next : '';
 };
 const gridArg = flag('--grid');
+const outArg = flag('--out');
+const sizeArg = flag('--size');
 const remember = flag('--remember');
 const diff = flag('--diff');
 const threshold = flag('--threshold');
@@ -45,6 +47,8 @@ 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)
   --port N        skip discovery and use this port
 
   --remember [L]  keep this frame as the baseline named L (default "last")
@@ -52,7 +56,14 @@ 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
+
 
 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
@@ -138,6 +149,7 @@ if (!found) {
 
 const params = new URLSearchParams();
 if (gridArg !== null) params.set('grid', gridArg);
+if (outArg) params.set('image', sizeArg || '512');
 if (remember !== null) params.set('remember', remember);
 if (diff !== null) params.set('diff', diff);
 if (threshold) params.set('threshold', threshold);
@@ -147,10 +159,22 @@ const res = await fetch(`http://${found.host}:${found.port}/__incanto/frame${q ?
 });
 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);
 }
@@ -165,10 +189,33 @@ if (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 (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 +230,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-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;

package/bin/incanto-verify.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * incanto-verify — the whole ladder, one command, one next action.
+ *
+ *   bunx incanto-verify                      # finds your scene
+ *   bunx incanto-verify src/game.scene.json --behaviors src/behaviors.ts
+ *
+ * The rungs already existed and were used one at a time, because using them
+ * together means knowing three things nobody writes down: the order, that the
+ * first red rung makes the ones above it meaningless, and that "no dev server"
+ * is a question unasked rather than a failing game.
+ *
+ *   loads   incanto-check     the scene is legal and every asset resolves
+ *   plays   incanto-playtest  a seeded run can actually finish it
+ *   draws   incanto-frame     the GPU drew something, and the subject is in shot
+ *
+ * Exit 1 when a rung FAILED. An unmeasured rung is not a failure — it prints
+ * what to arrange, and says so in the summary.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
+const { ladderText, ladderVerdict } = await import(
+  pathToFileURL(join(PKG, 'dist', 'test.js')).href
+);
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const flag = (name) => {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : null;
+};
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log(`Usage: incanto-verify [scene.json] [--behaviors FILE] [--json]
+
+Walks the whole ladder and tells you the ONE thing to do next:
+
+  loads   the scene is legal and every asset resolves       (incanto-check)
+  plays   a seeded run can actually finish it               (incanto-playtest)
+  draws   the GPU drew something and the subject is in shot (incanto-frame)
+
+Without a scene it looks for one *.scene.json under the current directory.
+"draws" needs a dev server with the page open; without one it is reported as
+NOT MEASURED rather than failed — a missing measurement is not a broken game.`);
+  process.exit(0);
+}
+
+/** The scene to verify: the one named, or the only one that can be found. */
+function findScene() {
+  const named = argv.find((a) => !a.startsWith('-') && a.endsWith('.json'));
+  if (named) return named;
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 4 || found.length > 8) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full, depth + 1);
+      else if (entry.name.endsWith('.scene.json')) found.push(full);
+    }
+  };
+  try {
+    walk(process.cwd(), 0);
+  } catch {
+    /* unreadable tree — the caller can always name the file */
+  }
+  return { scene: found.length === 1 ? found[0] : null, candidates: found };
+}
+
+const bin = (name) => join(PKG, 'bin', `incanto-${name}.mjs`);
+const run = (name, args) =>
+  spawnSync(process.execPath, [bin(name), ...args], {
+    encoding: 'utf-8',
+    timeout: 180_000,
+    // A playtest report carries a replay per losing run; the 1MB default
+    // truncates it and a truncated report is indistinguishable from a tool
+    // that would not start.
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+const { scene, candidates } = findScene();
+if (!scene) {
+  const report = ladderVerdict([], { candidates });
+  console.log(asJson ? JSON.stringify(report, null, 2) : ladderText(report));
+  process.exit(0);
+}
+if (!existsSync(scene) || !statSync(scene).isFile()) {
+  console.error(`no such scene: ${scene}`);
+  process.exit(1);
+}
+
+const behaviors = flag('--behaviors');
+const rungs = [];
+
+// ---- loads ---------------------------------------------------------------
+{
+  const r = run('check', [scene, '--json']);
+  const out = safeJson(r.stdout);
+  const problems = out?.files?.flatMap((f) => f.problems ?? []) ?? [];
+  rungs.push(
+    r.status === 0
+      ? { name: 'loads', status: 'pass', summary: 'the scene is legal and its assets resolve' }
+      : {
+          name: 'loads',
+          status: 'fail',
+          summary: problems[0]?.why ?? firstLine(r.stdout || r.stderr) ?? 'incanto-check failed',
+          fix: `fix that, then run again — nothing above this rung means anything until it is green (\`incanto-check ${scene}\` for the detail)`,
+        },
+  );
+}
+
+// ---- plays ---------------------------------------------------------------
+if (rungs[0].status === 'pass') {
+  const args = [scene, '--json', '--runs', '8'];
+  if (behaviors) args.push('--behaviors', behaviors);
+  const r = run('playtest', args);
+  const out = safeJson(r.stdout);
+  const won = out?.runs?.filter((x) => x.outcome === 'won').length ?? 0;
+  const total = out?.runs?.length ?? 0;
+  // A scene that declares no win is not a scene that cannot be won: a
+  // walkabout template has no end, and calling that a failure sends its author
+  // hunting a bug that was never there.
+  const noGoal = out && out.declaresWin === false;
+  rungs.push(
+    r.status === 0
+      ? { name: 'plays', status: 'pass', summary: `${won} of ${total} seeded runs finished it` }
+      : noGoal
+        ? {
+            name: 'plays',
+            status: 'unmeasured',
+            summary: `nothing declares a win — ${total} runs played without error, and there was no end to reach`,
+            fix: 'if it is meant to be finishable, emit `won` (GameFlow, ScoreKeeper, or your own behaviour)',
+          }
+        : {
+            name: 'plays',
+            status: 'fail',
+            summary:
+              total > 0 ? `no run finished it (${total} tried)` : 'the playtest could not run',
+            fix: behaviors
+              ? `see which runs stalled and where: \`incanto-playtest ${scene} --behaviors ${behaviors}\``
+              : `run it with your behaviours — without them the structure plays and your game logic does not: \`incanto-playtest ${scene} --behaviors src/behaviors.ts\``,
+          },
+  );
+} else {
+  rungs.push({ name: 'plays', status: 'skipped', summary: 'not run — the scene does not load' });
+}
+
+// ---- draws ---------------------------------------------------------------
+{
+  const r = run('frame', ['--json']);
+  const out = safeJson(r.stdout);
+  const report = out?.report;
+  if (!report) {
+    rungs.push({
+      name: 'draws',
+      status: 'unmeasured',
+      summary: firstLine(r.stderr) ?? 'no dev server with a page open',
+      fix: /not drawing/.test(r.stderr ?? '')
+        ? 'bring the preview window to the front — a hidden tab does not render, and a frame is captured inside a render'
+        : 'start your dev server, open the page, and run this again — the pixels are in the browser',
+    });
+  } else if (report.black) {
+    rungs.push({
+      name: 'draws',
+      status: 'fail',
+      summary: 'BLACK SCREEN — nothing was drawn',
+      fix: 'no light, no current camera, or nothing in view: `incanto-frame --out shot.png` and look',
+    });
+  } else if (!report.subject) {
+    rungs.push({
+      name: 'draws',
+      status: 'fail',
+      summary: 'nothing but background — the camera is pointed away from the scene',
+      fix: 'check the camera: `incanto-frame --out shot.png` and look at what it is aimed at',
+    });
+  } else {
+    rungs.push({
+      name: 'draws',
+      status: 'pass',
+      summary: `subject fills ${(report.subject.coverage * 100).toFixed(1)}% of the frame`,
+    });
+  }
+}
+
+/**
+ * The JSON in `text`, past whatever a dependency printed first. Rapier's
+ * deprecation notice lands on stdout ahead of the report, and treating that as
+ * "the tool could not run" is how this reported a healthy scene as broken.
+ */
+function safeJson(text) {
+  const raw = text ?? '';
+  const start = raw.indexOf('{');
+  if (start < 0) return null;
+  try {
+    return JSON.parse(raw.slice(start));
+  } catch {
+    return null;
+  }
+}
+function firstLine(text) {
+  const line = (text ?? '').split('\n').find((l) => l.trim());
+  return line ? line.trim() : null;
+}
+
+const verdict = ladderVerdict(rungs);
+console.log(asJson ? JSON.stringify({ scene, ...verdict }, null, 2) : ladderText(verdict));
+// `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 = verdict.ok ? 0 : 1;

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
 import { D as QualityCaps, Et as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-62q0HWBO.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
-import { i as SceneJson, s as JsonObject } from "./schema-CFeioQRE.js";
+import { i as SceneJson$1, s as JsonObject } from "./schema-CFeioQRE.js";
 import { t as LoadSceneOptions } from "./loader-CeyU_bm1.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
-import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-Ct8XgsmV.js";
+import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DZ70IY26.js";
 import { n as PathGrid, s as SpatialPose } from "./pathfinding-C49JSNNq.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";
@@ -633,7 +633,7 @@ interface Game3D {
   * make "edit the scene" mean "edit wherever the simulation happens to be",
   * so the source is kept beside the game and handed over unchanged.
   */
-  sourceJson: SceneJson;
+  sourceJson: SceneJson$1;
   renderer: GameRenderer;
   physics: Physics3D | null;
   /**
@@ -931,6 +931,91 @@ declare class Environment3D {
 */
 declare function setEnvironment3D(engine: Engine, patch: JsonObject): void;
 //#endregion
+//#region src/3d/model-verdict.d.ts
+/**
+* What a GLB will DO in an incanto scene, judged from what is in the file.
+*
+* Finding an asset is somebody else's job and they do it better: the agent8
+* service has a vector search over the same library, and matching "a stocky
+* dwarf blacksmith" to a URL is not something a filename filter should attempt.
+* What no search can answer is whether the thing it found will work HERE —
+*
+*   will the library's animation clips play on it? (bone NAMES decide, and a
+*     rig that does not match keeps its bind pose with only a console warning)
+*   how tall is it? (a model authored in centimetres dwarfs the scene)
+*   does it stand on its own origin? (`monster_trumble_mega` sits ten units
+*     above its root, so a node at [0,0,0] puts it in the sky — `targetHeight`
+*     normalises SIZE, not position, which cost a day of this repo's time)
+*
+* Every one of those is in the file, and every one of them was learned the
+* expensive way. Pure arithmetic over an already-parsed report: no three, no
+* network, no GPU.
+*/
+/** The parts of `incanto-model`'s report this judges. */
+interface ModelFacts {
+  nodes: Array<{
+    name: string;
+  }>;
+  bbox: {
+    size: [number, number, number];
+    center: [number, number, number];
+    min: [number, number, number];
+    max: [number, number, number];
+  } | null;
+  animations: Array<{
+    name: string;
+    duration: number;
+  }>;
+  /** Meshes in the file. Zero means there is nothing to draw — see `kind`. */
+  meshes: number;
+  /** glTF skins. Zero means a prop, not a character. */
+  skins: number;
+  vrm: {
+    humanBones: number;
+  } | null;
+}
+type Rig = "mixamorig" | "vrm-humanoid" | "other" | "none";
+interface SceneJson {
+  assets: Record<string, {
+    type: "model" | "animation";
+    url: string;
+  }>;
+  /** Null for a clip: it is played BY a model, it is not one. */
+  node: {
+    name: string;
+    type: "ModelInstance3D";
+    props: Record<string, unknown>;
+  } | null;
+}
+interface ModelVerdict {
+  /**
+  * What the file IS. A clip is a `.glb` with a rig and no mesh — declared as a
+  * model it renders nothing at all, with no error, and every other signal
+  * about it says "character".
+  */
+  kind: "model" | "animation";
+  rig: Rig;
+  /** The `3d/animations` shelf plays on this as-is. */
+  takesLibraryClips: boolean;
+  /** Height in the file's own units (0 when there is no geometry to measure). */
+  height: number;
+  /** Where the model sits relative to its own origin: bottom-centre, in units. */
+  originOffset: [number, number, number];
+  /** Standing on its own origin — a node at [0,0,0] puts its feet on the floor. */
+  groundedAtOrigin: boolean;
+  /** Clip names baked into the file itself (playable by name, no asset entry). */
+  embeddedClips: string[];
+  sceneJson: SceneJson | null;
+}
+interface VerdictTarget {
+  url: string;
+  /** Scene asset key. Also names the node. */
+  key: string;
+}
+declare function modelVerdict(facts: ModelFacts, target?: VerdictTarget): ModelVerdict;
+/** The verdict as sentences: what to do, and what will bite if you do not. */
+declare function verdictText(v: ModelVerdict): string;
+//#endregion
 //#region src/3d/nodes/billboard-3d.d.ts
 /** Valid `Billboard3D.mode` values — drives the prop options AND validateJson. */
 declare const BILLBOARD_GROUP_MODES: readonly ["screen", "y", "none"];
@@ -3621,4 +3706,4 @@ declare function createNavDebugNode(nav: TerrainNav, opts?: {
   name?: string;
 }): InstancedMesh3D;
 //#endregion
-export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameDiff, type FrameSignature, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath };
+export { Area3D, AssetStore3D, type BedSampler, Billboard3D, type BillboardGroupMode, BoneAttachment3D, BoneLookAt3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, type DownhillTraceOptions, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type FrameDiff, type FrameSignature, type FrameStats, type FrameStatsOptions, type Game3D, type GridCell, type HeightSampler, type Heightmap, type HeightmapOptions, InstancedMesh3D, Joint3D, type JointType3D, LoftMesh3D, type LoftSection, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, type ModelFacts, ModelInstance3D, type ModelVerdict, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type Rig, type RigView, RigidBody3D, type Ripple, River3D, type RiverCarveOptions, type RiverCoverageGap, type RiverHit, type RiverRing, type RiverRingOptions, SIGNATURE_GRID, type SceneJson, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainNav, type TerrainNavOptions, type TerrainTheme, TextureCache3D, type TextureSpec, Trail3D, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_CUTOUT_MAX, WATER_MAX_RIPPLES, Water3D, WaterCutout3D, acquireOwnTexture, acquireTexture, buildHeightmap, buildRiverRings, buildTerrainNav, cameraRelative, createGame3D, createNavDebugNode, diffSignatures, diffText, enablePhysics3D, findRiverCoverageGaps, frameSignature, frameStats, frameText, horizonColorFromSky, keyboardIntensity, modelVerdict, movementState, parseEnvironment3D, projectToRiver, registerNodes3D, resolveFlowerDensity, rigPose, riverCarveChannels, riverStepFor, setEnvironment3D, smoothCourse, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers, traceDownhillPath, verdictText };