incanto 0.67.0 → 0.69.0

package/assets/catalog.json

@@ -5,7 +5,7 @@
     "url": "incanto/assets/characters/2dbasic.png",
     "kind": "character",
     "bytes": 30499,
-    "description": "2dbasic sprite sheet image.anything,base character. (frame size 192x192)",
+    "description": "2dbasic sprite sheet image.anything,base character.",
     "animation": "characters/2dbasic.json",
     "frameWidth": 111,
     "frameHeight": 83
@@ -144,7 +144,7 @@
     "url": "incanto/assets/characters/ghost.png",
     "kind": "character",
     "bytes": 22933,
-    "description": "Ghost character with translucent appearance sprite sheet image (frame size 112x128)",
+    "description": "Ghost character with translucent appearance sprite sheet image",
     "animation": "characters/ghost.json",
     "frameWidth": 112,
     "frameHeight": 128
@@ -155,7 +155,7 @@
     "url": "incanto/assets/characters/goblin.png",
     "kind": "character",
     "bytes": 57994,
-    "description": "Medieval goblin with torch sprite sheet image (frame size 192x192)",
+    "description": "Medieval goblin with torch sprite sheet image",
     "animation": "characters/goblin.json",
     "frameWidth": 192,
     "frameHeight": 192
@@ -286,7 +286,7 @@
     "url": "incanto/assets/characters/medieval-knight.png",
     "kind": "character",
     "bytes": 84367,
-    "description": "(frame size 192x192) Using a medieval-themed SD(Super Deformed) knight sprite sheet image, you can apply idle, move, and attack animations, among others.",
+    "description": "Using a medieval-themed SD(Super Deformed) knight sprite sheet image, you can apply idle, move, and attack animations, among others.",
     "animation": "characters/medieval-knight.json",
     "frameWidth": 192,
     "frameHeight": 192
@@ -297,7 +297,11 @@
     "url": "incanto/assets/tiles/minecraft-tiles.png",
     "kind": "tile",
     "bytes": 10511,
-    "description": "Minecraft-themed tiles sprite sheet image (frame size 16x16)"
+    "description": "Minecraft-themed tiles sprite sheet image",
+    "frameWidth": 16,
+    "frameHeight": 16,
+    "columns": 5,
+    "tiles": 25
   },
   {
     "name": "monster-died",

package/bin/_pick-server.mjs

@@ -0,0 +1,48 @@
+/**
+ * Which of the dev servers that answered is THIS project's — the one decision
+ * `incanto-frame` and `incanto-logs` must never get wrong, in one place.
+ *
+ * They each had their own copy, and each copy had the same hatch: when exactly
+ * one server answered and it did not say whose it was, take it anyway ("an
+ * older incanto that predates the identity field"). A server that will not
+ * identify itself is the ONE kind the check cannot clear, so the hatch let
+ * through precisely what it was written to stop. Measured in an empty temp
+ * directory with one foreign page listening, on a scene with two nodes and no
+ * assets:
+ *
+ *     ✓ draws — subject fills 37.5% of the frame
+ *     ✗ says — asset …/NO-SUCH-TEXTURE.jpg never loaded: 404
+ *
+ * A ✓ measured off another game, and a ✗ naming a texture that appears nowhere
+ * in this project. It surfaced in this repo as an intermittent failure of
+ * `incanto-verify.test.ts`, which is a gate that lies in both directions.
+ *
+ * The real dev server has sent `root` since 0.41 (`frame-endpoint.test.ts`
+ * pins it), so nothing is lost; `--port` still names a server on purpose.
+ */
+
+/** Is `body.root` this directory, an ancestor of it, or inside it? */
+export function sameProject(body, cwd) {
+  if (!body?.root) return false;
+  const root = String(body.root);
+  return root === cwd || cwd.startsWith(`${root}/`) || root.startsWith(`${cwd}/`);
+}
+
+/**
+ * `{ pick }` when one of them is ours, `{ refusal }` when some answered and
+ * none is, `{}` when nothing answered at all (the caller says "no dev server").
+ */
+export function pickServer(answered, cwd, what) {
+  const mine = answered.filter((a) => sameProject(a, cwd));
+  if (mine.length > 0) return { pick: mine[0] };
+  if (answered.length === 0) return {};
+  const listed = answered
+    .map((a) => `  :${a.port}  ${a.project || '(unnamed)'}  ${a.root ?? "doesn't say"}`)
+    .join('\n');
+  return {
+    refusal:
+      `${answered.length} incanto dev server(s) are running and none of them is this ` +
+      `directory (${cwd}):\n${listed}\n\n${what}\n` +
+      "Start this project's dev server, or pass --port.",
+  };
+}

package/bin/incanto-assets.mjs

@@ -40,8 +40,21 @@ if (command === 'list') {
   } else {
     for (const e of entries) {
       const anim = e.animation ? ' [animated]' : '';
+      /*
+       * The GRID, from the fields rather than the prose.
+       *
+       * `list` printed only the description, and a description carrying a frame
+       * size is a second source of truth that drifts: `2dbasic` said
+       * "(frame size 192x192)" against a real grid of 111x83 — 666x664 does not
+       * divide by 192 — and the wrong number was the first one an agent read.
+       * The sizes live in `frameWidth`/`frameHeight` now, and the prose says
+       * what the art IS.
+       */
+      const grid = e.frameWidth
+        ? ` ${e.frameWidth}×${e.frameHeight}${e.tiles ? ` (${e.tiles} tiles)` : ''}`
+        : '';
       console.log(
-        `${e.name.padEnd(20)} ${e.kind.padEnd(10)}${anim.padEnd(11)} ${e.description.slice(0, 80)}`,
+        `${e.name.padEnd(20)} ${e.kind.padEnd(10)}${anim.padEnd(11)}${grid.padEnd(16)} ${e.description.slice(0, 64)}`,
       );
     }
     console.log(`\n${entries.length} built-in asset(s) — incanto-assets info <name> for details`);

package/bin/incanto-check.mjs

@@ -18,14 +18,27 @@ import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const DIST = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist');
 
 function parseArgs(argv) {
-  const args = { files: [], json: false, strict: false, help: false, invalid: false };
-  for (const a of argv) {
+  const args = {
+    files: [],
+    json: false,
+    strict: false,
+    help: false,
+    invalid: false,
+    behaviors: null,
+  };
+  // Indexed, because `--behaviors` takes the NEXT argument. A `for…of` with a
+  // hand-rolled `++i` reads fine and throws `i is not defined` at runtime,
+  // which is a flag that exists in the help and cannot be used.
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
     if (a === '--json') args.json = true;
     else if (a === '--strict-behaviors') args.strict = true;
+    else if (a === '--behaviors') args.behaviors = argv[++i];
     else if (a === '--strict-warnings') args.strictWarnings = true;
     else if (a === '--help' || a === '-h') args.help = true;
     else if (a.startsWith('--')) {
@@ -38,7 +51,7 @@ function parseArgs(argv) {
 
 const args = parseArgs(process.argv.slice(2));
 if (args.help || args.invalid) {
-  console.log(`Usage: npx incanto check [files|dirs...] [--json] [--strict-behaviors] [--strict-warnings]
+  console.log(`Usage: npx incanto check [files|dirs...] [--json] [--behaviors FILE] [--strict-behaviors] [--strict-warnings]
 
 Validates *.scene.json files headlessly with the installed engine.
 With no arguments, scans the current directory recursively
@@ -155,7 +168,33 @@ if (files.length === 0) {
   process.exit(1);
 }
 
-const { auditScene, validateScene } = await import(pathToFileURL(join(DIST, 'test.js')).href);
+const { auditScene, instancedScenes, validateScene } = await import(
+  pathToFileURL(join(DIST, 'test.js')).href
+);
+
+/** Your Behavior subclasses, when you name a file — same contract as the other bins. */
+const behaviors = {};
+if (args.behaviors) {
+  const { Behavior } = await import(pathToFileURL(join(DIST, 'index.js')).href);
+  let mod;
+  try {
+    mod = await import(pathToFileURL(resolve(args.behaviors)).href);
+  } catch (e) {
+    const why = e?.message ?? String(e);
+    // node cannot import the pattern this package teaches (a JSON import
+    // without an attribute, an extensionless relative path); bun can. Same
+    // hand-off as `incanto-playtest`.
+    reexecUnderBun(import.meta.url, why);
+    console.error(behaviorsHelp(args.behaviors, why));
+    process.exit(1);
+  }
+  for (const [name, value] of Object.entries(mod)) {
+    if (typeof value === 'function' && value.prototype instanceof Behavior) behaviors[name] = value;
+  }
+  if (Object.keys(behaviors).length === 0) {
+    console.error(`warning: no Behavior subclasses exported from ${args.behaviors}`);
+  }
+}
 
 /**
  * Every `strings` table in the corpus, unioned.
@@ -176,9 +215,16 @@ const declaredElsewhere = {};
  * part of its project it can.
  */
 const declaredAssets = {};
+/**
+ * Every scene some OTHER scene embeds — the only honest way to tell a fragment
+ * from a first draft. Without it a 3D scene with no camera and no light checked
+ * CLEAN, because "has no camera" was doing double duty as "is a fragment".
+ */
+const corpus = [];
 for (const file of files) {
   try {
     const doc = JSON.parse(readFileSync(file, 'utf-8'));
+    corpus.push({ path: resolve(file), json: doc });
     for (const [locale, entries] of Object.entries(doc?.strings ?? {})) {
       if (typeof entries !== 'object' || entries === null) continue;
       declaredElsewhere[locale] = { ...(declaredElsewhere[locale] ?? {}), ...entries };
@@ -191,6 +237,8 @@ for (const file of files) {
   }
 }
 
+const instanced = instancedScenes(corpus, (from, ref) => resolve(dirname(from), ref));
+
 const results = files.map((file) => {
   let json;
   try {
@@ -200,6 +248,19 @@ const results = files.map((file) => {
   }
   const res = validateScene(json, {
     strictBehaviors: args.strict,
+    /*
+     * `validateScene` has always taken `behaviors`; this bin had no way to pass
+     * any. So `--strict-behaviors` could only ever FAIL on a project with a
+     * behaviour of its own — which is every project past its first hour:
+     *
+     *   [UNKNOWN_BEHAVIOR] Unknown behavior 'Hunter'. … Did you forget
+     *   registerBehavior('Hunter', Hunter)?
+     *   0/1 scene(s) valid                                        EXIT=1
+     *
+     * A flag whose only outcome is failure is a flag nobody uses, and the check
+     * it gates — a script name that resolves nowhere — is worth having.
+     */
+    behaviors,
     declaredAssets,
     resolveScene: (p) => JSON.parse(readFileSync(resolve(dirname(file), p), 'utf-8')),
   });
@@ -207,7 +268,10 @@ const results = files.map((file) => {
     return {
       file,
       ok: true,
-      warnings: [...auditScene(json, { declaredElsewhere }), ...missingArt(file, json)],
+      warnings: [
+        ...auditScene(json, { declaredElsewhere, instanced: instanced.has(resolve(file)) }),
+        ...missingArt(file, json),
+      ],
     };
   }
   return {

package/bin/incanto-frame.mjs

@@ -20,6 +20,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pickServer } from './_pick-server.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const { listeningPorts, parseProcNetTcp } = await import(
@@ -171,11 +172,6 @@ const answered = [];
 // is plainly on screen.
 const HOSTS = ['localhost', '127.0.0.1'];
 const CWD = process.cwd();
-const sameProject = (b) => {
-  if (!b?.root) return false;
-  const r = String(b.root);
-  return r === CWD || CWD.startsWith(`${r}/`) || r.startsWith(`${CWD}/`);
-};
 for (const port of ports) {
   for (const host of HOSTS) {
     try {
@@ -197,26 +193,15 @@ for (const port of ports) {
 if (explicit) {
   found = answered[0] ?? null;
 } else {
-  const mine = answered.filter(sameProject);
-  if (mine.length > 0) {
-    found = mine[0];
-  } else if (answered.length === 1 && answered[0].root === undefined) {
-    // An older dev server that predates the identity field. Take it, but say so.
-    found = answered[0];
-    console.error(
-      `· the dev server on :${found.port} does not report which project it is ` +
-        '(older incanto) — if this reads the wrong game, pass --port.',
-    );
-  } else if (answered.length > 0) {
-    console.error(
-      `${answered.length} incanto dev server(s) are running and NONE of them is this ` +
-        `directory (${CWD}):\n` +
-        answered
-          .map((a) => `  :${a.port}  ${a.project || '(unnamed)'}  ${a.root ?? '?'}`)
-          .join('\n') +
-        "\n\nMeasuring one project on another project's page reports a number that has\n" +
-        "nothing to do with this game. Start this project's dev server, or pass --port.",
-    );
+  const { pick, refusal } = pickServer(
+    answered,
+    CWD,
+    "Measuring one project on another project's page reports a number that has\n" +
+      'nothing to do with this game.',
+  );
+  if (pick) found = pick;
+  else if (refusal) {
+    console.error(refusal);
     process.exit(1);
   }
 }

package/bin/incanto-logs.mjs

@@ -21,6 +21,7 @@ import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pickServer } from './_pick-server.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const { listeningPorts } = await import(pathToFileURL(join(PKG, 'dist', 'vite.js')).href);
@@ -80,11 +81,6 @@ let found = null;
 // project's page answered both the frame and the logs request.
 const answered = [];
 const CWD = process.cwd();
-const sameProject = (b) => {
-  if (!b?.root) return false;
-  const r = String(b.root);
-  return r === CWD || CWD.startsWith(`${r}/`) || r.startsWith(`${CWD}/`);
-};
 for (const port of ports) {
   for (const host of ['localhost', '127.0.0.1']) {
     try {
@@ -105,20 +101,14 @@ for (const port of ports) {
 if (explicit) {
   found = answered[0] ? { host: answered[0].host, port: answered[0].port } : null;
 } else {
-  const mine = answered.filter(sameProject);
-  const pick =
-    mine[0] ?? (answered.length === 1 && answered[0].root === undefined ? answered[0] : null);
+  const { pick, refusal } = pickServer(
+    answered,
+    CWD,
+    "Reading another project's log buffer would report its errors as yours.",
+  );
   if (pick) found = { host: pick.host, port: pick.port };
-  else if (answered.length > 0) {
-    console.error(
-      `${answered.length} incanto dev server(s) are running and none is this directory ` +
-        `(${CWD}):\n` +
-        answered
-          .map((a) => `  :${a.port}  ${a.project || '(unnamed)'}  ${a.root ?? '?'}`)
-          .join('\n') +
-        "\n\nReading another project's log buffer would report its errors as yours.\n" +
-        "Start this project's dev server, or pass --port.",
-    );
+  else if (refusal) {
+    console.error(refusal);
     process.exit(1);
   }
 }

package/bin/incanto-new.mjs

@@ -70,7 +70,11 @@ for (let i = 0; i < argv.length; i++) {
 }
 
 if (!target) {
-  console.error('usage: incanto-new <dir> [--template <name>] | --list');
+  console.error(
+    'usage: incanto-new <dir> [--template <name>] [--local] | --list\n' +
+      '  --local   pin `file:` to the incanto this command is running from,\n' +
+      '            instead of the registry — for verifying a release candidate.',
+  );
   process.exit(1);
 }
 
@@ -93,10 +97,30 @@ const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
 pkg.name = basename(dest)
   .toLowerCase()
   .replace(/[^a-z0-9-]/g, '-');
+
+/*
+ * WHICH incanto this scaffold will install.
+ *
+ * The template pins `^<version>`, so `bun install` resolves the REGISTRY build
+ * — even when the scaffolder itself came from a local tarball. Someone
+ * verifying a release candidate that shares its version with a published one
+ * then measures the published artifact for an hour and never sees a difference:
+ * the version matches, the install succeeds, and a `main.ts` that typechecks
+ * against the candidate does not typecheck against the registry copy.
+ *
+ * `--local` pins the package this bin is running from, and either way the pin
+ * is printed. A silent resolution is the part that cost the hour.
+ */
+const ENGINE_ROOT = PKG;
+if (argv.includes('--local')) {
+  pkg.dependencies = { ...pkg.dependencies, incanto: `file:${ENGINE_ROOT}` };
+}
+const pin = pkg.dependencies?.incanto ?? '(none)';
 writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 
 console.log(`
   ${template} → ${target}
+  incanto ${pin}
 
   cd ${target}
   bun install        # or: npm install
@@ -104,6 +128,10 @@ console.log(`
   bun run verify     # prove it plays, headlessly
   bun run check      # validate the scene JSON
 
+  When it plays, ship it:
+  bun run build      # the artifact a player gets
+  bunx incanto-serve # serve dist/ so verify/frame/logs can see the BUILT game
+
   Vibe-coding? Install the agent skills too:
   bunx incanto-skills claude   # or: opencode
 `);

package/bin/incanto-serve.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, statSync } from 'node:fs';
+/**
+ * Serve a BUILT game, and let the inspect tools see it.
+ *
+ * `incanto-frame` and `incanto-logs` ask a dev server, which asks the page over
+ * vite's HMR channel. A production build has no HMR, so nothing could look at
+ * the artifact an author actually deploys:
+ *
+ *     $ node …/incanto-logs.mjs --port 8791      # dist/ on a static server
+ *     no incanto dev server found.
+ *     $ incanto-verify src/game.scene.json
+ *     ? draws — no incanto dev server found.
+ *     ? says  — no incanto dev server found.
+ *
+ * The boot path is the only code a BUILD adds over a SCENE — `main.ts`, the
+ * loading overlay, the asset base path, everything after `createGame*` resolves
+ * — and it was the one thing no rung could reach.
+ *
+ * This serves `dist/` as plain static files (no bundler, no transform) and adds
+ * exactly two things: the `/__incanto/*` endpoints the CLIs already speak, and
+ * one inline script injected into `index.html` that relays them to the page.
+ * Nothing is added to the files on disk, so what you measure is what you ship.
+ *
+ *     bunx incanto-serve                 # ./dist on :4180
+ *     bunx incanto-serve build --port 5050
+ *     bunx incanto-verify                # now measures the BUILT game
+ */
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PKG = resolve(fileURLToPath(import.meta.url), '../..');
+const DIST = join(PKG, 'dist');
+if (!existsSync(join(DIST, 'vite.js'))) {
+  console.error('incanto: the package is not built (dist/vite.js missing).');
+  process.exit(1);
+}
+const { createStaticInspectHost, serveFrameEndpoints } = await import(
+  pathToFileURL(join(DIST, 'vite.js')).href
+);
+const VERSION = createRequire(import.meta.url)('../package.json').version;
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.error(`Usage: incanto-serve [dir] [--port N] [--host H]
+
+Serve a BUILT game (default ./dist) so \`incanto-frame\`, \`incanto-logs\` and
+\`incanto-verify\` can measure the artifact you actually deploy. Files are served
+byte-for-byte; the inspect client is injected into index.html at serve time and
+never written to disk.`);
+  process.exit(0);
+}
+const flag = (name, fallback) => {
+  const at = args.indexOf(name);
+  return at >= 0 && args[at + 1] ? args[at + 1] : fallback;
+};
+const port = Number(flag('--port', '4180'));
+const host = flag('--host', '127.0.0.1');
+const dir = resolve(
+  args.find(
+    (a) =>
+      !a.startsWith('--') &&
+      args[args.indexOf(a) - 1] !== '--port' &&
+      args[args.indexOf(a) - 1] !== '--host',
+  ) ?? 'dist',
+);
+
+if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+  console.error(
+    `incanto-serve: no such directory: ${dir}\n` +
+      '  Build first (`bun run build`), or name the output directory.',
+  );
+  process.exit(1);
+}
+if (!existsSync(join(dir, 'index.html'))) {
+  console.error(
+    `incanto-serve: ${dir} has no index.html — that is not a built game.\n` +
+      '  Point this at the directory your bundler wrote.',
+  );
+  process.exit(1);
+}
+
+const inspect = createStaticInspectHost(process.cwd());
+serveFrameEndpoints(inspect, VERSION);
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.wasm': 'application/wasm',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+};
+
+/** Inject the relay ahead of everything, so it exists before the game boots. */
+function withInspectClient(html) {
+  const tag = `<script>${inspect.clientScript()}</script>`;
+  if (html.includes('</head>')) return html.replace('</head>', `${tag}</head>`);
+  return tag + html;
+}
+
+const server = createServer((req, res) => {
+  const url = (req.url ?? '/').split('?')[0] ?? '/';
+  if (url.startsWith('/__incanto/')) {
+    // `originalUrl` is what the endpoints read for the query string; connect
+    // strips the mount path off `url` and these were written against that.
+    req.originalUrl = req.url;
+    if (inspect.handleInspect(req, res)) return;
+    res.statusCode = 404;
+    res.end('{}');
+    return;
+  }
+  // A path outside the served directory is a traversal attempt, not a typo.
+  const rel = normalize(decodeURIComponent(url)).replace(/^(\.\.[/\\])+/, '');
+  let file = join(dir, rel);
+  if (!file.startsWith(dir + sep) && file !== dir) file = dir;
+  if (!existsSync(file) || statSync(file).isDirectory()) file = join(dir, 'index.html');
+
+  const type = TYPES[extname(file)] ?? 'application/octet-stream';
+  if (file.endsWith('index.html')) {
+    const html = withInspectClient(readFileSync(file, 'utf8'));
+    res.statusCode = 200;
+    res.setHeader('content-type', TYPES['.html']);
+    res.end(html);
+    return;
+  }
+  res.statusCode = 200;
+  res.setHeader('content-type', type);
+  res.end(readFileSync(file));
+});
+
+server.on('error', (e) => {
+  if (e?.code === 'EADDRINUSE') {
+    console.error(`incanto-serve: port ${port} is already in use — pass --port N.`);
+    process.exit(1);
+  }
+  throw e;
+});
+
+server.listen(port, host, () => {
+  console.log(`incanto-serve  ${dir}`);
+  console.log(`  http://${host}:${port}/`);
+  console.log('  open it, then run `incanto-verify` / `incanto-frame` / `incanto-logs`.');
+});

package/bin/incanto-verify.mjs

@@ -449,6 +449,30 @@ if (rungs[0].status === 'pass') {
         ? '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.hidden) {
+    /*
+     * A hidden page is UNMEASURED, not passed.
+     *
+     * A browser stops animating a page it considers hidden — a window merely
+     * covered by another counts — and the back buffer keeps whatever it last
+     * drew. Measured at one instant, same page:
+     *
+     *   incanto-frame --do   the page is hidden … a frozen game    (exit 1)
+     *   incanto-logs         frame rate not measurable — hidden
+     *   incanto-frame        subject fills 17.5% of frame
+     *   incanto-verify       ✓ draws — subject fills 17.5%
+     *
+     * Two of six rungs reported ✓ off a stale buffer while the engine already
+     * knew, and said elsewhere, that the page was drawing nothing. The skills
+     * state the rule: an unmeasured rung is not a failure, and this is exactly
+     * the unmeasured case.
+     */
+    rungs.push({
+      name: 'draws',
+      status: 'unmeasured',
+      summary: 'the page is HIDDEN — those pixels are whatever it last drew',
+      fix: 'bring the window to the front (one covered by another counts as hidden) and run this again',
+    });
   } else if (report.black) {
     rungs.push({
       name: 'draws',
@@ -464,10 +488,26 @@ if (rungs[0].status === 'pass') {
       fix: 'check the camera: `incanto-frame --out shot.png` and look at what it is aimed at',
     });
   } else {
+    /*
+     * A rung that PASSED can still have something to say, and this one was
+     * dropping it. `incanto-frame` prints `CLIPPED by the frame edge` and
+     * `the subject fills almost nothing` — real observations about a shot that
+     * is technically non-black — and the ladder replaced all of it with one
+     * coverage number. The `loads` rung has carried its tool's warnings since
+     * the day a scene described as "It will render black" came back green.
+     */
+    const notes = [];
+    if (report.subject.clipped) {
+      notes.push('the subject is CLIPPED by the frame edge — part of it is off screen');
+    }
+    if (report.uniform) {
+      notes.push('one flat colour — the camera may be inside geometry, or only the sky is drawn');
+    }
     rungs.push({
       name: 'draws',
       status: 'pass',
       summary: `subject fills ${(report.subject.coverage * 100).toFixed(1)}% of the frame`,
+      ...(notes.length > 0 ? { notes } : {}),
     });
   }
 }

package/bin/incanto.mjs

@@ -40,6 +40,7 @@ const COMMANDS = {
   feel: ['incanto-feel.mjs', 'measure jump height, run speed, facing'],
   frame: ['incanto-frame.mjs', 'what the running page is drawing right now'],
   logs: ['incanto-logs.mjs', 'what the running page has been saying'],
+  serve: ['incanto-serve.mjs', 'serve a BUILT game so the tools can measure it'],
   editor: ['incanto-editor.mjs', 'the visual scene composer'],
   model: ['incanto-model.mjs', "a GLB's real bounds, animations and rig"],
   assets: ['incanto-assets.mjs', 'the built-in art and audio catalog'],