incanto 0.66.0 → 0.68.0

package/bin/_behaviors-loader.mjs

@@ -0,0 +1,87 @@
+/**
+ * Load a `--behaviors` file the way the author WROTE it, from any bin.
+ *
+ * Every template's `behaviors.ts` does `import gameJson from './game.scene.json'`
+ * — the documented way to read your own scene — and node's type stripping
+ * refuses a JSON import without `with { type: 'json' }`. Same for an
+ * extensionless relative import (`from './quest'`), which is what the tsconfig
+ * this package scaffolds asks for. Vite reads both. bun reads both. The bins'
+ * shebang is node.
+ *
+ * `incanto-playtest` grew a bun re-exec for exactly this and **the other four
+ * bins that take `--behaviors` never got it**: `feel`, `play`, `verify` and
+ * `multiplay` all died on the shipped `village-quest-3d`, and the only
+ * invocation the docs give (`incanto-verifying-your-game.md`) is the failing
+ * form. Worse, `verify:templates` — the gate step added specifically to run a
+ * template under node's resolver — runs `incanto-playtest`, the one bin whose
+ * fallback hides the failure. The step built to catch this class was
+ * neutralised by the thing it was built to catch.
+ *
+ * So the fallback lives here, once, and every bin uses it. Set
+ * `INCANTO_NO_BUN_REEXEC=1` to forbid it — that is how the gate exercises the
+ * resolver a user actually gets.
+ */
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Is this node refusing the file, rather than the file being wrong?
+ *
+ * Matched against the SPECIFIER where node gives us one. Node words the
+ * extensionless failure as `Cannot find module '<resolved path>' imported from
+ * '<importer>'`, and a check that reads the importer collapses it into
+ * "(file not found)" naming the file that plainly exists — which is what the
+ * author sees and cannot act on.
+ */
+export function nodeCannotReadIt(why) {
+  return (
+    /import attribute|Unknown file extension|Cannot find module|ERR_MODULE_NOT_FOUND|ERR_UNSUPPORTED_[A-Z_]+/i.test(
+      String(why),
+    ) ||
+    // Node's type stripping ERASES types; it does not transform. Anything that
+    // needs a transform is refused by name, and the wording is nothing like the
+    // resolver's. Measured on the shipped `racing-3d` example:
+    //
+    //   x TypeScript parameter property is not supported in strip-only mode
+    //
+    // `constructor(private root: Node3D)` is ordinary TypeScript that vite and
+    // bun both compile, and the bin gave up with "Pass the file that exports
+    // your Behavior subclasses" — telling the author their correct file was
+    // wrong. Enums and namespaces are refused the same way.
+    /strip-only mode|is not supported in strip|only mode|TypeScript parameter property|Unsupported TypeScript/i.test(
+      String(why),
+    )
+  );
+}
+
+/**
+ * Re-run this bin under bun, once, if node is the reason it failed.
+ *
+ * Never returns when it re-execs. Returns false when it did not (already bun,
+ * already re-execed, forbidden, no bun on PATH, or a real error in the file).
+ */
+export function reexecUnderBun(entryUrl, why) {
+  if (!nodeCannotReadIt(why)) return false;
+  if (process.versions.bun) return false;
+  if (process.env.INCANTO_BUN_REEXEC || process.env.INCANTO_NO_BUN_REEXEC) return false;
+  if (spawnSync('bun', ['--version'], { stdio: 'ignore' }).status !== 0) return false;
+  const here = new URL(entryUrl).pathname;
+  const again = spawnSync('bun', [here, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: { ...process.env, INCANTO_BUN_REEXEC: '1' },
+  });
+  process.exit(again.status ?? 1);
+}
+
+/** The sentence to print when the re-exec was not available. */
+export function behaviorsHelp(file, why) {
+  return (
+    `could not load --behaviors '${file}' (${why}).` +
+    (nodeCannotReadIt(why)
+      ? '\n\nThis is usually node refusing your file rather than a problem with it:' +
+        "\nnode cannot import JSON from a .ts module without `with { type: 'json' }`," +
+        '\nand it will not resolve an extensionless relative import. Both are what' +
+        '\nthe scaffolded tsconfig asks you to write. Run it with bun, which reads' +
+        '\nthe file as written — prefix any incanto command with `bunx --bun`.'
+      : '\nPass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.')
+  );
+}

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-check.mjs

@@ -155,7 +155,9 @@ 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
+);
 
 /**
  * Every `strings` table in the corpus, unioned.
@@ -176,9 +178,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 +200,8 @@ for (const file of files) {
   }
 }
 
+const instanced = instancedScenes(corpus, (from, ref) => resolve(dirname(from), ref));
+
 const results = files.map((file) => {
   let json;
   try {
@@ -207,7 +218,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-editor.mjs

@@ -200,6 +200,29 @@ async function proxyLibrary(req, res, url) {
   }
 }
 
+/**
+ * What kind of project is this — read from the scenes already in it.
+ *
+ * A 3D game's new scene must not be born 2D, and the only thing that knows
+ * which is which is what is already on disk. Returns null for an empty project,
+ * where there is genuinely nothing to go on.
+ */
+function projectDimension() {
+  let d2 = 0;
+  let d3 = 0;
+  for (const entry of discoverScenes()) {
+    try {
+      const json = JSON.parse(readFileSync(join(ROOT, entry.rel ?? entry), 'utf8'));
+      if (json?.dimension === '3d') d3 += 1;
+      else if (json?.dimension === '2d') d2 += 1;
+    } catch {
+      // not a scene, or unreadable — the scene browser already says so
+    }
+  }
+  if (d3 === 0 && d2 === 0) return null;
+  return d3 > d2 ? '3d' : '2d';
+}
+
 function discoverScenes() {
   const found = [];
   const walk = (dir, depth) => {
@@ -418,12 +441,26 @@ const server = createServer((req, res) => {
           return send(res, 409, JSON.stringify({ error: `already exists: ${wanted}` }));
         }
         const name = basename(abs).replace(/\.scene\.json$|\.json$/, '') || 'Scene';
+        /*
+         * A 3D project's new scene must not be born 2D.
+         *
+         * This hardcoded `dimension: '2d'` / `Node2D` and ignored `body`
+         * entirely, so every scene the editor created in a 3D game was the
+         * wrong kind — and node types are IMMUTABLE by design, so the halfway
+         * state (a 3D header over a Node2D root) is easy to reach through the
+         * header's dimension select and is written back with a 200.
+         *
+         * Asked for explicitly, or guessed from the project: whatever the
+         * sibling scenes are is overwhelmingly what the next one should be.
+         */
+        const asked = body?.dimension === '3d' || body?.dimension === '2d' ? body.dimension : null;
+        const dimension = asked ?? projectDimension() ?? '2d';
         const scene = {
           format: 1,
           type: 'scene',
-          dimension: '2d',
+          dimension,
           name,
-          root: { name, type: 'Node2D' },
+          root: { name, type: dimension === '3d' ? 'Node3D' : 'Node2D' },
         };
         try {
           mkdirSync(dirname(abs), { recursive: true });

package/bin/incanto-feel.mjs

@@ -21,6 +21,7 @@ import { dirname, join, resolve } from 'node:path';
  * wrong for most games.
  */
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -63,7 +64,9 @@ if (args.behaviors) {
   try {
     mod = await import(pathToFileURL(resolve(args.behaviors)).href);
   } catch (e) {
-    console.error(`could not load --behaviors '${args.behaviors}' (${e?.message ?? e}).`);
+    const why = e?.message ?? String(e);
+    reexecUnderBun(import.meta.url, why);
+    console.error(behaviorsHelp(args.behaviors, why));
     process.exit(1);
   }
   for (const [name, value] of Object.entries(mod)) {

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(
@@ -150,11 +151,28 @@ const discovered = explicit ? [explicit] : await listeningPorts({ read });
 const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
 
 let found = null;
+/**
+ * WHOSE dev server answered.
+ *
+ * This scans a port range, so before the ping carried identity, whoever
+ * answered first won — and a passing number from ANOTHER project silently
+ * overrode this one's failing one. Measured: project A on :5188 with a real
+ * page reported "the subject fills almost nothing (0.3%)", while `incanto
+ * verify` scanning from the same directory reported `✓ draws — 37.5%`,
+ * measured on project B. Corroboration from the other direction: four scenes
+ * across two unrelated projects all reported 22.6%.
+ *
+ * So: prefer the server rooted at THIS directory. If several answer and none is
+ * ours, refuse and list them — the same refusal `verify` already makes when a
+ * project has several scenes and guessing would verify the wrong one.
+ */
+const answered = [];
 // BOTH hosts, deliberately: vite binds to ::1 on some machines and 127.0.0.1 on
 // others, and a probe of the wrong one reports "no dev server" while the page
 // is plainly on screen.
 const HOSTS = ['localhost', '127.0.0.1'];
-outer: for (const port of ports) {
+const CWD = process.cwd();
+for (const port of ports) {
   for (const host of HOSTS) {
     try {
       const res = await fetch(`http://${host}:${port}/__incanto/ping`, {
@@ -163,8 +181,8 @@ outer: for (const port of ports) {
       if (!res.ok) continue;
       const body = await res.json();
       if (body?.incanto) {
-        found = { host, port, ...body };
-        break outer;
+        answered.push({ host, port, ...body });
+        break; // one host per port is enough
       }
     } catch {
       // not listening, not ours, or not answering — either way, next
@@ -172,6 +190,22 @@ outer: for (const port of ports) {
   }
 }
 
+if (explicit) {
+  found = answered[0] ?? null;
+} else {
+  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);
+  }
+}
+
 if (!found) {
   console.error(
     'no incanto dev server found.\n' +

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);
@@ -75,7 +76,12 @@ const discovered = explicit ? [explicit] : await listeningPorts({ read });
 const ports = explicit ? discovered : [...new Set([...bsdListeningPorts(), ...discovered])];
 
 let found = null;
-outer: for (const port of ports) {
+// Whose dev server answered — see incanto-frame.mjs for the measurement that
+// made this necessary: a scan takes whoever replies first, and a foreign
+// project's page answered both the frame and the logs request.
+const answered = [];
+const CWD = process.cwd();
+for (const port of ports) {
   for (const host of ['localhost', '127.0.0.1']) {
     try {
       const res = await fetch(`http://${host}:${port}/__incanto/ping`, {
@@ -84,14 +90,28 @@ outer: for (const port of ports) {
       if (!res.ok) continue;
       const body = await res.json();
       if (body?.incanto) {
-        found = { host, port };
-        break outer;
+        answered.push({ host, port, ...body });
+        break;
       }
     } catch {
       // not listening, not ours, or not answering — next
     }
   }
 }
+if (explicit) {
+  found = answered[0] ? { host: answered[0].host, port: answered[0].port } : null;
+} else {
+  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 (refusal) {
+    console.error(refusal);
+    process.exit(1);
+  }
+}
 
 if (!found) {
   console.error(

package/bin/incanto-multiplay.mjs

@@ -20,6 +20,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -36,6 +37,7 @@ if (argv.includes('--help') || argv.includes('-h')) {
   --seconds N        simulated seconds (default 5)
   --seed N           make the match reproducible (default 1)
   --behaviors FILE   your Behavior subclasses (.ts works on bun / node >= 23.6)
+  --server FILE      your Server class (default: server/src/server.ts if present)
   --scenes a=b.json  a scene a NetworkSpawner names, repeatable
   --no-late-join     skip the late-joining client
   --json             machine-readable report
@@ -83,7 +85,9 @@ if (behaviorsFile) {
       }
     }
   } catch (e) {
-    console.error(`could not load --behaviors '${behaviorsFile}' (${e?.message ?? e}).`);
+    const why = e?.message ?? String(e);
+    reexecUnderBun(import.meta.url, why);
+    console.error(behaviorsHelp(behaviorsFile, why));
     process.exit(1);
   }
 }
@@ -122,11 +126,56 @@ for (const name of spawnerScenes) {
   }
 }
 
+/**
+ * Your REAL server class, so `agrees` measures the game you ship.
+ *
+ * `playMultiplayer` has always accepted a `server`, and this bin never passed
+ * one — so the rung ran every match against a bare loopback kernel with no
+ * remote functions. Measured: with no server `roomState` came back `{}`, with
+ * one it came back `{"matchMs": 5983.3}`; a `manager.call('claimRelic')` threw
+ * `BAD_FORMAT: Loopback kernel has no remote function 'claimRelic'` and the
+ * report STILL said `ok=true errors=0 problems=[]`. Moving `server/src/server.ts`
+ * out of the tree changed nothing, which is the whole finding: a ✓ that could
+ * not have been a ✗.
+ *
+ * Found where the templates put it, or named with `--server`.
+ */
+let server;
+const serverFlag = flag('--server', null);
+const serverGuesses = serverFlag
+  ? [resolve(serverFlag)]
+  : ['server/src/server.ts', 'server/src/server.js', 'src/server.ts'].map((g) =>
+      resolve(sceneDir, '..', '..', g),
+    );
+for (const at of serverGuesses) {
+  if (!existsSync(at)) continue;
+  try {
+    const mod = await import(pathToFileURL(at).href);
+    server = mod.Server ?? mod.default;
+    if (server) {
+      if (!argv.includes('--json')) console.log(`· server: ${at} (${server.name || 'default'})`);
+      break;
+    }
+  } catch (e) {
+    // A server that cannot be loaded must not read as a game that has none.
+    console.error(
+      `could not load the server at '${at}' (${e?.message ?? e}). ` +
+        'The agreement check would then measure a game without its own rules; refusing.',
+    );
+    process.exit(1);
+  }
+}
+if (serverFlag && !server) {
+  console.error(`--server '${serverFlag}' exports neither \`Server\` nor a default.`);
+  process.exit(1);
+}
+
 let report;
 try {
   report = await playMultiplayer({
     scene: sceneJson,
     scenes,
+    ...(server ? { server } : {}),
     players: Number(flag('--players', 2)) || 2,
     seconds: Number(flag('--seconds', 5)) || 5,
     seed: Number(flag('--seed', 1)) || 1,

package/bin/incanto-play.mjs

@@ -26,6 +26,7 @@ import { dirname, join, resolve } from 'node:path';
  */
 import { createInterface } from 'node:readline';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -79,6 +80,7 @@ if (args.behaviors) {
   try {
     mod = await import(pathToFileURL(resolve(args.behaviors)).href);
   } catch (e) {
+    reexecUnderBun(import.meta.url, e?.message ?? String(e));
     const reason =
       e?.code === 'ERR_MODULE_NOT_FOUND' && String(e.message).includes(resolve(args.behaviors))
         ? 'file not found'
@@ -88,7 +90,7 @@ if (args.behaviors) {
       cmd: 'behaviors',
       error: {
         code: e?.code ?? 'BEHAVIORS_LOAD_FAILED',
-        message: `could not load --behaviors '${args.behaviors}' (${reason}). Pass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.`,
+        message: behaviorsHelp(args.behaviors, reason),
       },
     });
     process.exit(1);

package/bin/incanto-playtest.mjs

@@ -23,6 +23,7 @@ import { dirname, join, resolve } from 'node:path';
  * Exit code 1 when no run reached a win, so CI can gate on it.
  */
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -92,31 +93,8 @@ if (args.behaviors) {
     // and vite resolve it. It broke `incanto verify` on the shipped
     // `village-quest-3d` starter, and it breaks for any author who splits their
     // behaviours across files — which is most of them, eventually.
-    const nodeCannotReadIt = /import attribute|Unknown file extension|Cannot find module/i.test(
-      why,
-    );
-    if (nodeCannotReadIt && !process.versions.bun && !process.env.INCANTO_BUN_REEXEC) {
-      const { spawnSync } = await import('node:child_process');
-      const hasBun = spawnSync('bun', ['--version'], { stdio: 'ignore' }).status === 0;
-      if (hasBun) {
-        const here = fileURLToPath(import.meta.url);
-        const again = spawnSync('bun', [here, ...process.argv.slice(2)], {
-          stdio: 'inherit',
-          env: { ...process.env, INCANTO_BUN_REEXEC: '1' },
-        });
-        process.exit(again.status ?? 1);
-      }
-    }
-    console.error(
-      `could not load --behaviors '${args.behaviors}' (${why}).` +
-        (nodeCannotReadIt
-          ? '\n\nThis is usually node refusing your file rather than a problem with it:' +
-            "\nnode cannot import JSON from a .ts module without `with { type: 'json' }`," +
-            '\nand it will not resolve an extensionless relative import. Both are what' +
-            '\nthe scaffolded tsconfig asks you to write. Run it with bun, which reads' +
-            '\nthe file as written: `bunx incanto playtest <scene> --behaviors <file>`.'
-          : '\nPass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.'),
-    );
+    reexecUnderBun(import.meta.url, why);
+    console.error(behaviorsHelp(args.behaviors, why));
     process.exit(1);
   }
   for (const [name, value] of Object.entries(mod)) {

package/bin/incanto-verify.mjs

@@ -84,6 +84,19 @@ function findScene() {
 }
 
 const bin = (name) => join(PKG, 'bin', `incanto-${name}.mjs`);
+
+/**
+ * `--port`, passed straight through to the page-reading rungs.
+ *
+ * `draws` and `says` ask a dev server for the browser's answer, and discovery
+ * scans a port range — so with two projects running, this one measured the
+ * OTHER one's page and reported its pass. `incanto-frame`/`incanto-logs` now
+ * refuse a foreign server, and this makes the escape hatch they document
+ * reachable from the rung that actually runs them.
+ */
+const PORT = process.argv.includes('--port')
+  ? ['--port', String(process.argv[process.argv.indexOf('--port') + 1])]
+  : [];
 const run = (name, args) =>
   spawnSync(process.execPath, [bin(name), ...args], {
     encoding: 'utf-8',
@@ -424,7 +437,7 @@ if (rungs[0].status === 'pass') {
 
 // ---- draws ---------------------------------------------------------------
 {
-  const r = run('frame', ['--json']);
+  const r = run('frame', ['--json', ...PORT]);
   const out = safeJson(r.stdout);
   const report = out?.report;
   if (!report) {
@@ -466,7 +479,7 @@ if (rungs[0].status === 'pass') {
  */
 // ---- says ---------------------------------------------------------------
 {
-  const r = run('logs', ['--json']);
+  const r = run('logs', ['--json', ...PORT]);
   const report = safeJson(r.stdout);
   if (!report) {
     rungs.push({

package/dist/2d.d.ts

@@ -1,10 +1,10 @@
-import { P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats } from "./behavior-BXNLfIJk.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 { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-DOrq7sP-.js";
+import { P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, w as GameStats, x as EngineOptions } from "./behavior-DoFPYrgo.js";
+import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-CnIOiyNJ.js";
+import { i as SceneJson, s as JsonObject } from "./schema-B6ugCV1Q.js";
 import { r as FrameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-Cga7FVP4.js";
+import { t as LoadSceneOptions } from "./loader-CcB533FR.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
-import { i as ParticleSim, o as ParticleView, r as SpatialPose } from "./audio-player-_UAcHxnC.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
 
@@ -279,6 +279,16 @@ declare class Physics2D {
   /** Who is currently inside each sensor/body, maintained from the event drain. */
   private readonly overlaps;
   private trackOverlap;
+  /**
+  * Forget every overlap whose node has left the tree.
+  *
+  * The lazy drop inside `overlapping()` only cleans the SETS of a key someone
+  * asks about, and only when they ask. This clears the KEYS, which is where the
+  * dead nodes were pinned.
+  */
+  /** Drop one node from the overlap map, both as a key and as a member. */
+  private forgetOverlaps;
+  private pruneOverlaps;
   /** The bodies currently overlapping `node`. Freed nodes are dropped on read. */
   overlapping(node: PhysicsBody2D): PhysicsBody2D[];
   /**
@@ -386,6 +396,18 @@ interface CreateGame2DOptions {
     createElement(tag: string): HTMLElement;
   };
   seed?: number;
+  /**
+  * Namespace this game's persisted settings — volume, language, quality tier.
+  *
+  * They are keyed `incanto:<namespace>:<key>` in the browser's storage and
+  * defaulted to `settings` for everyone, so two Incanto games on one domain
+  * shared one options screen. Measured: game A's player sets `renderScale
+  * 0.25, muted, quality low`; game B, whose source never mentions settings,
+  * boots at a 480x232 drawing buffer and silent.
+  *
+  * `SaveSlots(namespace)` already takes one for exactly this reason.
+  */
+  settings?: EngineOptions["settings"];
   fixedHz?: number;
   /** Renderer extras (pixelRatio, antialias, custom asset store). */
   pixelRatio?: number;
@@ -425,7 +447,22 @@ interface Game2DRenderer extends GameRenderer {
 }
 interface Game2D {
   engine: Engine;
-  scene: Scene$1;
+  /**
+  * The LIVE scene — a getter over `engine.scene`, not a snapshot.
+  *
+  * This used to be the scene captured at boot. `Engine.setScene` calls
+  * `this._scene?.root.free()`, so after any swap the old handle was not merely
+  * stale, it was EMPTIED — and a single-scene game reaches that through
+  * `flow.restart()`, which `incanto-hud.md` wires to a Start button. Measured:
+  *
+  *   before swap  game.scene.root.children = 2   engine.scene = 2
+  *   after  swap  game.scene.root.children = 0   engine.scene = 2
+  *   game.scene.root.getNode('Flow')  ->  No node at 'Flow'. Children here: [].
+  *
+  * `game.engine.scene` always worked and three skills use it, so there were
+  * two handles with one name and no note saying which was which.
+  */
+  get scene(): Scene$1;
   /**
   * What the last drawn frame actually looks like, as numbers.
   *
@@ -1210,4 +1247,4 @@ declare function parseCells(cells: readonly (string | readonly number[])[], lege
 */
 declare function mergeSolidRects(grid: readonly (readonly number[])[], solid: Set<number>): TileRect[];
 //#endregion
-export { AnimatedSprite2D, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Joint2D, type JointType2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, TileMap2D, type TileRect, type UIAnchor, UILayer, createGame2D, enablePhysics2D, mergeSolidRects, parseCells, registerNodes2D, spriteFromLibraryMeta, syncTree2D };
+export { AnimatedSprite2D, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Joint2D, type JointType2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, TileMap2D, type TileRect, type UIAnchor, UILayer, createGame2D, enablePhysics2D, isWebGLAvailable, mergeSolidRects, parseCells, registerNodes2D, showBootFailure, spriteFromLibraryMeta, syncTree2D };