incanto 0.68.0 → 0.70.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/_behaviors-loader.mjs

@@ -85,3 +85,25 @@ export function behaviorsHelp(file, why) {
       : '\nPass the file that exports your Behavior subclasses, e.g. src/behaviors.ts.')
   );
 }
+
+/**
+ * The files a `--behaviors` value names — one, or several.
+ *
+ * The flag took exactly one module and every bin's help said `FILE`, while the
+ * comment two functions up already knew that authors "split their behaviours
+ * across files — which is most of them, eventually". A game whose bosses live
+ * in `boss.ts` and whose scene table lives in `scenes.ts` had one way through:
+ * write a barrel that re-exports both, for the CLI's benefit and nothing
+ * else's. Comma-separate them instead, or repeat the flag.
+ *
+ * Splitting on the comma is safe on every platform this ships to: a comma is
+ * legal in a POSIX filename and effectively never used in one, and the repeated
+ * form is there for anyone who has managed it.
+ */
+export function behaviorFiles(value) {
+  const many = Array.isArray(value) ? value : [value];
+  return many
+    .flatMap((v) => String(v ?? '').split(','))
+    .map((f) => f.trim())
+    .filter(Boolean);
+}

package/bin/_read-json.mjs

@@ -0,0 +1,28 @@
+/**
+ * Read a JSON file the way every other tool does: without the BOM.
+ *
+ * A UTF-8 byte order mark is legal in a UTF-8 file and meaningless in it, and
+ * `JSON.parse` refuses it. Windows PowerShell 5.1's `Set-Content` writes one by
+ * default, Notepad offers it, and several editors add it on "save as UTF-8" —
+ * so a scene written by a perfectly ordinary tool came back as
+ *
+ *     [BAD_JSON] Unexpected token '', "{ "format"... is not valid JSON
+ *
+ * about a character that is ZERO WIDTH. The author sees valid JSON, an error
+ * pointing at nothing, and no way forward. Node's own `require()` of a .json
+ * file has stripped it for a decade; `JSON.parse` is the one door that does not.
+ *
+ * Every bin reads project JSON through here now, so the answer is the same
+ * wherever a file arrives from.
+ */
+import { readFileSync } from 'node:fs';
+
+/** Strip a leading UTF-8 BOM. Everything else is left exactly as written. */
+export function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/** `JSON.parse` of a file, BOM and all. Throws the parser's own error. */
+export function readJson(file) {
+  return JSON.parse(stripBom(readFileSync(file, 'utf-8')));
+}

package/bin/incanto-assets.mjs

@@ -12,15 +12,16 @@
  * External art still works the usual way (any URL in scene assets{}) — this
  * is the zero-setup starting set.
  */
-import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { copyFileSync, mkdirSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const ASSETS = join(PKG, 'assets');
 
 function catalog() {
-  return JSON.parse(readFileSync(join(ASSETS, 'catalog.json'), 'utf-8'));
+  return readJson(join(ASSETS, 'catalog.json'));
 }
 
 const [command, ...rest] = process.argv.slice(2);
@@ -40,8 +41,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`);
@@ -63,7 +77,7 @@ if (command === 'list') {
   if (command === 'info') {
     console.log(JSON.stringify(entry, null, 2));
     if (entry.animation) {
-      const meta = JSON.parse(readFileSync(join(ASSETS, entry.animation), 'utf-8'));
+      const meta = readJson(join(ASSETS, entry.animation));
       console.log('\nanimations:', Object.keys(meta.animations ?? {}).join(', '));
     }
     process.exitCode = 0; // see the list note — exit() truncates piped stdout
@@ -85,7 +99,7 @@ if (command === 'list') {
       const { spriteFromLibraryMeta } = await import(
         pathToFileURL(join(PKG, 'dist', '2d.js')).href
       );
-      const meta = JSON.parse(readFileSync(join(ASSETS, entry.animation), 'utf-8'));
+      const meta = readJson(join(ASSETS, entry.animation));
       const { asset, props } = spriteFromLibraryMeta(meta, { url, assetKey: entry.name });
       console.log(`\nscene assets entry:\n  "${entry.name}": ${JSON.stringify(asset)}`);
       console.log(

package/bin/incanto-check.mjs

@@ -14,18 +14,33 @@
  * that needs no TypeScript. Sub-scene `instance` paths resolve relative to
  * each scene file.
  */
-import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, lstatSync, readdirSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { behaviorFiles, behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { readJson } from './_read-json.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;
+    // Repeatable: behaviours legitimately live in more than one file.
+    else if (a === '--behaviors') args.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 +53,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[,FILE...]] [--strict-behaviors] [--strict-warnings]
 
 Validates *.scene.json files headlessly with the installed engine.
 With no arguments, scans the current directory recursively
@@ -73,12 +88,31 @@ function collectScenes(entry) {
  */
 function missingArt(file, json) {
   const assets = json && typeof json === 'object' ? json.assets : null;
-  if (!assets || typeof assets !== 'object') return [];
   const sceneDir = dirname(file);
   const root = projectRoot(sceneDir);
   const out = [];
-  for (const [key, decl] of Object.entries(assets)) {
-    const url = decl && typeof decl === 'object' ? decl.url : null;
+  /*
+   * A url is named in TWO places, and this only ever looked at one.
+   *
+   * `assets{}` is where the 2D sprite props and `ModelInstance3D` point; the
+   * 3D texture props, `AudioPlayer.src`, `material.map` and a raw-url
+   * `UiImage.src` take the url DIRECTLY, and for three of them a url is the
+   * only spelling accepted. None of those was ever checked, while
+   * `incanto-verify` reported "its assets resolve" over the top of them.
+   */
+  const named = [
+    ...Object.entries(assets && typeof assets === 'object' ? assets : {}).map(([key, decl]) => ({
+      what: `$${key}`,
+      kind: decl && typeof decl === 'object' ? decl.type : '',
+      url: decl && typeof decl === 'object' ? decl.url : null,
+    })),
+    ...sceneAssetUrls(json).map((u) => ({
+      what: `${u.path}.${u.prop}`,
+      kind: u.kind,
+      url: u.url,
+    })),
+  ];
+  for (const { what, kind, url } of named) {
     if (typeof url !== 'string' || url === '') continue;
     // Remote and inline are not this command's business to guess about.
     if (/^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('//')) continue;
@@ -100,9 +134,9 @@ function missingArt(file, json) {
     // warned about art that works.
     if (resolvesAsPackageAsset(url, sceneDir)) continue;
     out.push(
-      `$${key} → ${url} is not in the project ` +
+      `${what} → ${url} is not in the project ` +
         `(looked in ${relativeish(root, join(root, 'public'))}, ${relativeish(root, root)}` +
-        `, and beside the scene). It will draw nothing.`,
+        `, and beside the scene). It will ${kind === 'audio' ? 'be silent' : 'draw nothing'}.`,
     );
   }
   return out;
@@ -155,9 +189,39 @@ if (files.length === 0) {
   process.exit(1);
 }
 
-const { auditScene, instancedScenes, validateScene } = await import(
-  pathToFileURL(join(DIST, 'test.js')).href
-);
+const { auditScene, instancedScenes, registerAllNodes, sceneAssetUrls, validateScene } =
+  await import(pathToFileURL(join(DIST, 'test.js')).href);
+// `sceneAssetUrls` reads the node registry to know which props name a resource.
+registerAllNodes();
+
+/** Your Behavior subclasses, when you name a file — same contract as the other bins. */
+const behaviors = {};
+const behaviorSources = behaviorFiles(args.behaviors);
+if (behaviorSources.length > 0) {
+  const { Behavior } = await import(pathToFileURL(join(DIST, 'index.js')).href);
+  for (const file of behaviorSources) {
+    let mod;
+    try {
+      mod = await import(pathToFileURL(resolve(file)).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(file, 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 ${behaviorSources.join(', ')}`);
+  }
+}
 
 /**
  * Every `strings` table in the corpus, unioned.
@@ -186,7 +250,7 @@ const declaredAssets = {};
 const corpus = [];
 for (const file of files) {
   try {
-    const doc = JSON.parse(readFileSync(file, 'utf-8'));
+    const doc = readJson(file);
     corpus.push({ path: resolve(file), json: doc });
     for (const [locale, entries] of Object.entries(doc?.strings ?? {})) {
       if (typeof entries !== 'object' || entries === null) continue;
@@ -205,14 +269,27 @@ const instanced = instancedScenes(corpus, (from, ref) => resolve(dirname(from),
 const results = files.map((file) => {
   let json;
   try {
-    json = JSON.parse(readFileSync(file, 'utf-8'));
+    json = readJson(file);
   } catch (e) {
     return { file, ok: false, code: 'BAD_JSON', message: String(e?.message ?? e) };
   }
   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')),
+    resolveScene: (p) => readJson(resolve(dirname(file), p)),
   });
   if (res.ok) {
     return {

package/bin/incanto-editor.mjs

@@ -31,9 +31,11 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSy
 import { createServer } from 'node:http';
 import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readJson } from './_read-json.mjs';
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const EDITOR_DIR = join(PKG_ROOT, 'editor');
+const ASSETS_DIR = join(PKG_ROOT, 'assets');
 
 // Biome-compatible JSON layout — same algorithm as the editor's
 // src/format-json.ts (inline when the one-line form fits 80 cols).
@@ -100,10 +102,39 @@ const MODE = args.input ? 'single' : 'project';
 const ROOT = resolve('.');
 const INPUT = args.input ? resolve(args.input) : null;
 const OUTPUT = args.input ? resolve(args.output ?? args.input) : null;
-const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8')).version;
+const VERSION = readJson(join(PKG_ROOT, 'package.json')).version;
 
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage']);
 
+/*
+ * A named scene that is not there is a typo, and the banner used to congratulate
+ * you on it:
+ *
+ *   $ incanto-editor typo.scene.json
+ *   incanto-editor v0.69.0
+ *     scene:  /private/tmp/ed/typo.scene.json
+ *     url:    http://127.0.0.1:5399/
+ *
+ * The server started, the terminal reported success, and the failure waited in
+ * the browser — where it reads as the editor being broken rather than as the
+ * path being wrong. Project mode is the mode that CREATES scenes; naming one is
+ * a request to edit a file that exists.
+ */
+if (MODE === 'single' && !existsSync(INPUT)) {
+  console.error(`no such scene: ${INPUT}`);
+  const near = discoverScenes()
+    .filter((f) => !f.notScene)
+    .slice(0, 5);
+  if (near.length > 0) {
+    console.error('\nscenes in this project:');
+    for (const f of near) console.error(`  ${f.rel}`);
+    console.error('\nor run `incanto-editor` with no file to browse them all.');
+  } else {
+    console.error('\nrun `incanto-editor` with no file to browse this project.');
+  }
+  process.exit(1);
+}
+
 // --- agent8 asset library -------------------------------------------------
 const LIBRARY_URL =
   process.env.INCANTO_LIBRARY_URL ?? 'https://agent8-backend.verse8.io/api/resources';
@@ -212,7 +243,7 @@ function projectDimension() {
   let d3 = 0;
   for (const entry of discoverScenes()) {
     try {
-      const json = JSON.parse(readFileSync(join(ROOT, entry.rel ?? entry), 'utf8'));
+      const json = readJson(join(ROOT, entry.rel ?? entry));
       if (json?.dimension === '3d') d3 += 1;
       else if (json?.dimension === '2d') d2 += 1;
     } catch {
@@ -294,7 +325,7 @@ function inspectJson(abs, size) {
   if (size > 16_000_000) return { notScene: 'too large to check without opening it' };
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync(abs, 'utf-8'));
+    parsed = readJson(abs);
   } catch (error) {
     return { notScene: `not valid JSON: ${String(error.message ?? error)}` };
   }
@@ -334,6 +365,15 @@ const MIME = {
   '.json': 'application/json; charset=utf-8',
   '.svg': 'image/svg+xml',
   '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json',
   '.wasm': 'application/wasm',
 };
 
@@ -521,6 +561,46 @@ const server = createServer((req, res) => {
             }),
           );
         }
+        /*
+         * REFUSE to overwrite a file that is not already a scene.
+         *
+         * The body check above asks "is this a scene"; nothing asked what it
+         * was about to land on. `?file=` accepts any `.json` under the project
+         * on purpose — the browser lists every JSON and the LOAD decides, which
+         * is how a scene saved as `level.json` still opens — so the write path
+         * was one query parameter away from destroying a manifest:
+         *
+         *   $ curl -X PUT -d '{…a valid scene…}' '…/api/scene?file=package.json'
+         *   {"ok":true,"output":"/private/tmp/repro/package.json"}   [200]
+         *   $ cat package.json
+         *   {"format":1,"type":"scene",…}
+         *
+         * And the GET on the same server already refuses a non-scene WITH the
+         * reason, so the two halves of one endpoint disagreed about the rule.
+         *
+         * A file that does not exist yet is fine: that is `create`.
+         */
+        if (existsSync(target.output)) {
+          let existing = null;
+          try {
+            existing = readJson(target.output);
+          } catch {
+            // Unparseable: not a scene, and not ours to replace either.
+          }
+          const already =
+            existing === null ? { ok: false, why: 'it is not JSON' } : sceneFacts(existing);
+          if (!already.ok) {
+            return send(
+              res,
+              409,
+              JSON.stringify({
+                error:
+                  `refusing to overwrite ${target.output} — ${already.why}. ` +
+                  'The editor only replaces scenes, and only creates new files.',
+              }),
+            );
+          }
+        }
         try {
           // Write the client's bytes verbatim — the editor formats scenes
           // biome-compatibly; re-stringifying here would undo that.
@@ -535,6 +615,39 @@ const server = createServer((req, res) => {
     return send(res, 405, JSON.stringify({ error: 'method not allowed' }));
   }
 
+  /*
+   * The BUILT-IN art, at the path the scenes already name.
+   *
+   * `incanto-assets` prints `incanto/assets/items/coin.png` as an asset's url
+   * and three shipped 2D templates carry exactly that — a BUNDLER specifier,
+   * which the game's vite resolves and a browser cannot. In the game the
+   * template's `main.ts` overwrites each url with the import; the editor loads
+   * the scene JSON as written, so it asked this server for
+   * `/incanto/assets/characters/medieval-knight.png` and got 404. Every sprite
+   * in `platformer-2d`, `star-survivor` and `topdown-rpg` was a blank quad in
+   * the composer they ship with.
+   *
+   * Serving the package's own `assets/` here makes the written url resolve, so
+   * the art is live in the editor without any scene change and without the
+   * runtime injection having to know about the editor.
+   */
+  if (url.pathname.startsWith('/incanto/assets/')) {
+    const asset = normalize(join(ASSETS_DIR, url.pathname.slice('/incanto/assets/'.length)));
+    if (!asset.startsWith(ASSETS_DIR + sep)) {
+      return send(res, 403, JSON.stringify({ error: 'forbidden' }));
+    }
+    try {
+      return send(
+        res,
+        200,
+        readFileSync(asset),
+        MIME[extname(asset)] ?? 'application/octet-stream',
+      );
+    } catch {
+      return send(res, 404, JSON.stringify({ error: `no built-in asset: ${url.pathname}` }));
+    }
+  }
+
   // static editor assets (path-traversal guarded)
   const rel = url.pathname === '/' ? '/index.html' : url.pathname;
   const file = normalize(join(EDITOR_DIR, rel));
@@ -559,9 +672,19 @@ server.listen(args.port, args.host, () => {
   if (MODE === 'single') {
     console.log(`  scene:  ${INPUT}${OUTPUT === INPUT ? '' : `\n  output: ${OUTPUT}`}`);
   } else {
-    const scenes = discoverScenes();
+    /*
+     * `discoverScenes()` returns every `.json` in the project — that is the
+     * point, because the BROWSER lists them all and marks which ones are
+     * scenes. Counting the list and calling the total "scene files" made the
+     * banner say `4 scene files` about a project holding one scene,
+     * `package.json`, `tsconfig.json` and `biome.json`.
+     */
+    const found = discoverScenes();
+    const scenes = found.filter((f) => !f.notScene);
+    const other = found.length - scenes.length;
     console.log(
-      `  project: ${ROOT} (${scenes.length} scene file${scenes.length === 1 ? '' : 's'})`,
+      `  project: ${ROOT} (${scenes.length} scene${scenes.length === 1 ? '' : 's'}` +
+        `${other > 0 ? `, ${other} other .json file${other === 1 ? '' : 's'} listed` : ''})`,
     );
   }
   console.log(

package/bin/incanto-env.mjs

@@ -15,9 +15,10 @@
  * generateScatter is library-only (`import {generateScatter} from
  * 'incanto/env'`) — its item templates don't fit CLI flags.
  */
-import { readFileSync, writeFileSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -128,7 +129,7 @@ const countNodes = (n) => 1 + (n.children ?? []).reduce((sum, c) => sum + countN
 if (flags.has('--into')) {
   const file = resolve(flags.get('--into'));
   const at = flags.get('--at');
-  const scene = JSON.parse(readFileSync(file, 'utf-8'));
+  const scene = readJson(file);
   const out = env.insertIntoScene(scene, node, at);
   writeFileSync(file, `${JSON.stringify(out, null, 2)}\n`);
   console.log(

package/bin/incanto-feel.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+
 import { dirname, join, resolve } from 'node:path';
 /**
  * incanto-feel — what your controls actually FEEL like, as numbers.
@@ -21,7 +21,8 @@ import { dirname, join, resolve } from 'node:path';
  * wrong for most games.
  */
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { behaviorFiles, behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { readJson } from './_read-json.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -29,13 +30,19 @@ function parseArgs(argv) {
   const args = {};
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--behaviors') args.behaviors = argv[++i];
+    // Repeatable: behaviours legitimately live in more than one file.
+    if (a === '--behaviors') args.behaviors = [...(args.behaviors ?? []), argv[++i]];
     else if (a === '--move') args.move = argv[++i];
     else if (a === '--jump') args.jump = argv[++i];
     else if (a === '--json') args.json = true;
     else if (a === '--help' || a === '-h') args.help = true;
     else if (a.startsWith('--')) {
+      // `invalid`, not `help`: printing usage and exiting 0 told an agent its
+      // typo was a request. `--runs=4`, `--behaviours`, `--no-replay` all landed
+      // here and looked like success — and with `--json` the machine path was
+      // literally silent (0 bytes on stdout).
       console.error(`unknown flag: ${a}`);
+      args.invalid = true;
       args.help = true;
     } else if (!args.scene) args.scene = a;
   }
@@ -47,10 +54,13 @@ if (args.help || !args.scene) {
   console.error(`Usage: incanto-feel <scene.json> [options]
 
   --behaviors FILE  your Behavior subclasses (.ts works on node >= 23.6 / bun)
-  --move ACTION     the vector action to move with (default: the first vector2)
+                    comma-separate or repeat for several files
+  --move ACTION     the vector action to move with, and ONLY that one
+                    (default: the first vector2, then every other one, each
+                    pushed +x/-y/+y/-x until the player moves)
   --jump ACTION     the button to jump with (default: "jump")
   --json            the report as JSON instead of prose`);
-  process.exit(args.help && args.scene !== undefined ? 0 : 1);
+  process.exit(!args.invalid && args.help && args.scene !== undefined ? 0 : 1);
 }
 
 const { facingReport, facingText, feelReport, feelText } = await import(
@@ -59,14 +69,15 @@ const { facingReport, facingText, feelReport, feelText } = await import(
 const incanto = await import(pathToFileURL(join(PKG, 'dist', 'index.js')).href);
 
 const behaviors = {};
-if (args.behaviors) {
+const behaviorSources = behaviorFiles(args.behaviors);
+for (const file of behaviorSources) {
   let mod;
   try {
-    mod = await import(pathToFileURL(resolve(args.behaviors)).href);
+    mod = await import(pathToFileURL(resolve(file)).href);
   } catch (e) {
     const why = e?.message ?? String(e);
     reexecUnderBun(import.meta.url, why);
-    console.error(behaviorsHelp(args.behaviors, why));
+    console.error(behaviorsHelp(file, why));
     process.exit(1);
   }
   for (const [name, value] of Object.entries(mod)) {
@@ -78,16 +89,16 @@ if (args.behaviors) {
 
 const scenePath = resolve(args.scene);
 const sceneDir = dirname(scenePath);
-const sceneJson = JSON.parse(readFileSync(scenePath, 'utf-8'));
+const sceneJson = readJson(scenePath);
 
 let report;
 try {
   report = await feelReport(sceneJson, {
     behaviors,
-    stubMissingBehaviors: !args.behaviors,
+    stubMissingBehaviors: behaviorSources.length === 0,
     ...(args.move ? { moveAction: args.move } : {}),
     ...(args.jump ? { jumpAction: args.jump } : {}),
-    resolveScene: (p) => JSON.parse(readFileSync(resolve(sceneDir, p), 'utf-8')),
+    resolveScene: (p) => readJson(resolve(sceneDir, p)),
   });
 } catch (e) {
   console.error(`feel failed: ${e?.message ?? e}`);
@@ -103,8 +114,8 @@ if (!args.json) {
   try {
     const facing = await facingReport(sceneJson, {
       behaviors,
-      stubMissingBehaviors: !args.behaviors,
-      resolveScene: (p) => JSON.parse(readFileSync(resolve(sceneDir, p), 'utf-8')),
+      stubMissingBehaviors: behaviorSources.length === 0,
+      resolveScene: (p) => readJson(resolve(sceneDir, p)),
     });
     if (facing.skin) process.stdout.write(`${facingText(facing)}\n`);
   } catch {