incanto 0.69.0 → 0.71.0

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);
@@ -76,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
@@ -98,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,11 +14,12 @@
  * 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 { behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { behaviorFiles, behaviorsHelp, reexecUnderBun } from './_behaviors-loader.mjs';
+import { readJson } from './_read-json.mjs';
 
 const DIST = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist');
 
@@ -38,7 +39,8 @@ function parseArgs(argv) {
     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];
+    // 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('--')) {
@@ -51,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] [--behaviors FILE] [--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
@@ -86,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;
@@ -113,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;
@@ -168,31 +189,37 @@ 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 = {};
-if (args.behaviors) {
+const behaviorSources = behaviorFiles(args.behaviors);
+if (behaviorSources.length > 0) {
   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;
+  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 ${args.behaviors}`);
+    console.error(`warning: no Behavior subclasses exported from ${behaviorSources.join(', ')}`);
   }
 }
 
@@ -223,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;
@@ -242,7 +269,7 @@ 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) };
   }
@@ -262,7 +289,7 @@ const results = files.map((file) => {
      */
     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 {

package/bin/incanto-frame.mjs

@@ -75,10 +75,17 @@ running game before capturing — the same words incanto-play takes:
 
   incanto-frame --do "vector move 0 1; step 3000; vector move 0 0" --out bridge.png
   incanto-frame --do "press jump; step 400" --out midair.png
+  incanto-frame --do "at %Coin; click; step 300" --out collected.png
 
   press/release ACTION · vector ACTION X Y · key CODE down|up
+  at X Y | at NODE-PATH · click [left|middle|right] · mouse BUTTON down|up
   pointer DX DY · step MS        (semicolons or newlines separate)
 
+'at' puts the CURSOR somewhere — a canvas pixel, or wherever a node is on
+screen — and 'click' presses and releases there. That is the whole input of a
+match-3, a tower defense, a card game or a point-and-click, and this language
+could not say it: 'pointer' is a delta, which is the mouse-LOOK question.
+
 step waits on the real clock: this is the live game, with its own loop.
 
 
@@ -140,7 +147,7 @@ if (driveScript) {
     // Refuse here rather than in the page: a bad command that ran nothing would
     // hand back the boot screen, and nothing about that frame would say so.
     console.error(
-      `${parsed.error}\n  commands: press/release ACTION · vector ACTION X Y · key CODE down|up · pointer DX DY · step MS`,
+      `${parsed.error}\n  commands: press/release ACTION · vector ACTION X Y · key CODE down|up · at X Y | at NODE-PATH · click [left|middle|right] · mouse BUTTON down|up · pointer DX DY · step MS`,
     );
     process.exit(1);
   }