incanto 0.68.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/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
@@ -159,6 +172,30 @@ 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.
  *
@@ -211,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')),
   });

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'],

package/dist/2d.d.ts

@@ -1,9 +1,9 @@
-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 { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-C0j2k-yB.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-rm8vVzu_.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-CcB533FR.js";
+import { r as FrameStats } from "./frame-report-DNxDAb1w.js";
+import { t as LoadSceneOptions } from "./loader-DadV2QCT.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
@@ -972,9 +972,11 @@ declare class TileMap2D extends Node2D {
   private _solid;
   /** Rebuild flags — raised when the map-shaping props are REPLACED. */
   private geometryDirty;
-  /** Reported once per atlas, so a bad grid says so on the first build only. */
+  /** `texture|highestTile` already reported, so a bad grid says so once. */
   private gridChecked;
   private collidersDirty;
+  /** The `scale` the colliders were last built for — see `rebuildColliders`. */
+  private builtScale;
   /** Replace the whole array to change the map (mutations are not watched). */
   get cells(): (string | number[])[];
   set cells(value: (string | number[])[]);

package/dist/2d.js

@@ -1,9 +1,9 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as showBootFailure } from "./boot-failure-CKYrEcGF.js";
-import { t as isWebGLAvailable } from "./webgl-unavailable-N9nQqesw.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-IZIydDwI.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-ibCjm-wH.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-B7Y6dPZO.js";
+import { t as isWebGLAvailable } from "./webgl-unavailable-Z5_g8x9H.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CwxEDlCm.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-DbVArsns.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CF5yyjbj.js";
 //#region src/2d/library-sprite.ts
 /**
 * What a `CharacterController2D`/`3D` will ask a skin to play, and the clip in

package/dist/3d.d.ts

@@ -1,9 +1,9 @@
-import { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-DOrq7sP-.js";
-import { D as QualityCaps, 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 { c as showBootFailure, i as ParticleSim, o as ParticleView, r as SpatialPose, s as isWebGLAvailable } from "./audio-player-C0j2k-yB.js";
+import { D as QualityCaps, 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-rm8vVzu_.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-CnIOiyNJ.js";
 import { i as SceneJson$1, s as JsonObject } from "./schema-B6ugCV1Q.js";
-import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DCnHFmto.js";
-import { t as LoadSceneOptions } from "./loader-CcB533FR.js";
+import { a as GridCell, c as diffText, d as frameText, i as FrameStatsOptions, l as frameSignature, n as FrameSignature, o as SIGNATURE_GRID, r as FrameStats, s as diffSignatures, t as FrameDiff, u as frameStats } from "./frame-report-DNxDAb1w.js";
+import { t as LoadSceneOptions } from "./loader-DadV2QCT.js";
 import { n as PathGrid } from "./pathfinding-_fGrCFmH.js";
 import { AnimationClip, AnimationMixer, BufferGeometry, Color, DirectionalLight, Group, InstancedMesh, Mesh, MeshPhysicalMaterial, Object3D, PerspectiveCamera, Scene, ShaderMaterial, Texture, Vector3, WebGLRenderer } from "three";
 import { VRM } from "@pixiv/three-vrm";

package/dist/3d.js

@@ -1,12 +1,12 @@
-import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-BC4PNtJX.js";
+import { c as parseEnvironment3D, l as sunDirectionFromElevationAzimuth, s as horizonColorFromSky, u as sunDirectionFromSky } from "./loader-DZE7B07H.js";
 import { t as showBootFailure } from "./boot-failure-CKYrEcGF.js";
-import { t as isWebGLAvailable } from "./webgl-unavailable-N9nQqesw.js";
-import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-BSMny7oe.js";
-import { G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, R as WATER_CUTOUT_MAX, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, Y as WATER_MAX_RIPPLES, z as WaterCutout3D } from "./gameplay-DM1eu_cV.js";
-import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-CybQXNqS.js";
-import { a as Environment3D, c as AssetStore3D, i as syncTree, o as applyQualityTier3D, r as Renderer3D, s as setEnvironment3D, t as createGame3D } from "./create-game-DbWtVTxD.js";
+import { t as isWebGLAvailable } from "./webgl-unavailable-Z5_g8x9H.js";
+import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-Dlq13Gyj.js";
+import { G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, R as WATER_CUTOUT_MAX, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, Y as WATER_MAX_RIPPLES, z as WaterCutout3D } from "./gameplay-D1KixWK8.js";
+import { A as Terrain3D, B as keyboardIntensity, C as resolveFlowerDensity, D as BoneLookAt3D, E as Camera3D, F as InstancedMesh3D, G as acquireTexture, H as rigPose, I as MeshInstance3D, M as TERRAIN_THEMES, N as terrainThemeLayers, O as BoneAttachment3D, P as Joint3D, R as QUARTER_PITCH, S as Flowers3D, T as CharacterController3D, U as TextureCache3D, V as movementState, W as acquireOwnTexture, _ as LoftMesh3D, a as Tree3D, b as Foliage3D, c as buildRiverRings, d as riverCarveChannels, f as riverStepFor, g as ModelInstance3D, h as Particles3D, i as VoxelGrid3D, j as DEFAULT_TERRAIN_TEXTURE_BASE, k as Billboard3D, l as findRiverCoverageGaps, m as traceDownhillPath, n as registerNodes3D, o as Trail3D, p as smoothCourse, r as VOXEL_PALETTE, s as River3D, u as projectToRiver, v as DirectionalLight3D, w as FLOWER_VARIETIES, x as DENSITY_PRESETS, y as OmniLight3D, z as cameraRelative } from "./environment-presets-BO-7XoFV.js";
+import { a as Environment3D, c as AssetStore3D, i as syncTree, o as applyQualityTier3D, r as Renderer3D, s as setEnvironment3D, t as createGame3D } from "./create-game-CvJ1wSRP.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-bG3n70Ky.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DbYaEcZy.js";
 //#region src/3d/model-verdict.ts
 /** Mixamo exports every bone as `mixamorigX`; the retargeter binds by that name. */
 const MIXAMO = /^mixamorig[:_]?/i;

package/dist/{audio-player-DOrq7sP-.d.ts → audio-player-C0j2k-yB.d.ts}

@@ -1,4 +1,4 @@
-import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-DoFPYrgo.js";
+import { d as PropSchema, dt as Listener, jt as Node } from "./behavior-rm8vVzu_.js";
 import { a as Rng } from "./schema-B6ugCV1Q.js";
 
 //#region src/core/boot-failure.d.ts
@@ -234,28 +234,47 @@ declare class AudioPlayer extends Node {
   /** The `spatial` option for the SFX path, or undefined when not spatial. */
   private spatialPlay;
   /**
-  * Start the sound. `at` schedules it on the AUDIO clock instead of now.
+  * Start the sound, now.
+  *
+  * **Takes no arguments, on purpose.** This is the method scenes wire signals
+  * to — `incanto-audio.md` teaches
+  * `{"signal": "collected", "from": "Player/Collector", "to": "Coin",
+  * "handler": "play"}` — and a signal hands its handler whatever it carries.
+  * `collected` leads with a NUMBER. When this briefly took an optional
+  * scheduling time, that wiring became `play(10)`, which scheduled the pickup
+  * sound at ABSOLUTE audio-clock second 10: inaudible for the first ten
+  * seconds of the game and fine thereafter. The same optional parameter also
+  * made `Function.length` 1, so the engine's own arity checker cried wolf on
+  * the shipped `platformer-2d` template's own harness.
+  *
+  * Scheduling has its own name: {@link playAt}.
+  */
+  /**
+  * Start the sound at `when` on the AUDIO clock (`engine.sfx.now` + a lead).
   *
   * A frame is a 16.67 ms grid at 60 Hz and 33.33 ms at 30, so a sound fired
   * from `update()` cannot land closer than one frame to where a chart wants
-  * it — measured 0 of 64 notes scheduled on the documented path. Queue it a
-  * lead ahead of `engine.sfx.now` and the same notes land at |mean| 0.000000
-  * ms:
+  * it — measured 0 of 64 notes given a scheduled start. Queue them a lead
+  * ahead and the same notes land at |mean| 0.000000 ms:
   *
   * ```ts
-  * const lead = 0.08;                        // schedule this far ahead
-  * for (const note of dueSoon(engine.sfx.now + lead)) {
-  *   hit.play(engine.sfx.now + (note.atSec - songSeconds));
+  * const LEAD = 0.08;
+  * for (const note of dueSoon(engine.sfx.now + LEAD)) {
+  *   hit.playAt(startedAt + note.atSec);
   * }
   * ```
   *
   * PRESETS only — a `src` clip goes through an `<audio>` element, which has no
-  * scheduling clock, and passing `at` for one is ignored rather than silently
-  * approximated. Everything else is unchanged: the bus gain applies, the sound
-  * lands in `engine.audio.recent()`, and `muted` still silences it, none of
-  * which a hand-rolled `AudioContext` scheduler keeps.
+  * scheduling clock, so `playAt` on one plays immediately rather than being
+  * silently approximated. A time already past plays now (Web Audio's own
+  * rule), so a late scheduler is late, not silent. The bus gain, the
+  * `engine.audio.recent()` entry and `muted` all still apply.
+  *
+  * Separate from {@link play} because `play` is what scenes wire signals to,
+  * and a signal hands its handler whatever it carries.
   */
-  play(at?: number): void;
+  playAt(when: number): void;
+  play(): void;
   /**
   * Procedural-SFX path: synthesize the preset and fire it through WebAudio
   * (low-latency, overlap-friendly). Headless (no AudioContext) plays nothing —