incanto 0.51.0 → 0.53.0

package/dist/2d.d.ts

@@ -1,7 +1,7 @@
-import { Dt as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-rZNfzVbH.js";
+import { Dt as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-Do0Da56m.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 { t as LoadSceneOptions } from "./loader-Dkbn56KC.js";
+import { t as LoadSceneOptions } from "./loader-Cu_7kJDy.js";
 import { n as AnimationEntry } from "./sprite-animation-CMr6f1K2.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
@@ -36,6 +36,19 @@ declare class AssetStore2D {
   constructor(loader?: (url: string, callbacks?: TextureLoadCallbacks) => Texture, engine?: DiagnosticSink | null);
   /** Load (or extend with) a scene's `assets` declarations. Hard-validates each entry. */
   load(assets: Record<string, JsonObject>): void;
+  /**
+  * Every declared asset that FAILED to load, `$ref` and url included.
+  *
+  * The 3D store has answered this since 0.32.0 — the 2D one only tracked a
+  * per-key status, which the console printed and nothing else could read. A
+  * 404'd texture is invisible, and "invisible" is the one symptom an author
+  * cannot tell apart from "I put it in the wrong place".
+  */
+  errors(): Array<{
+    ref: string;
+    url: string;
+    error: string;
+  }>;
   /** Load status of a declared asset KEY (no '$'), or undefined if unknown. */
   status(key: string): AssetStatus | undefined;
   getTexture(ref: string): Texture;
@@ -291,7 +304,21 @@ interface CreateGame2DOptions {
   * false disables. They overlay `touchContainer` (default: the canvas's
   * parent element — give it position: relative).
   */
+  /**
+  * Attach pointer input (mouse, finger or pen) to the canvas: positions for
+  * `input.pointerPosition()`, buttons for `input.mousePressed()`.
+  * `{ lockOnClick: true }` captures the cursor — rare in 2D, so it is off.
+  */
+  pointer?: boolean | {
+    lockOnClick?: boolean;
+  };
   touch?: "auto" | boolean;
+  /**
+  * Leave the browser's touch gestures (scroll/zoom/pull-to-refresh) on the
+  * canvas. Default false: the GAME owns them, or a drag on a phone scrolls
+  * the page instead of playing.
+  */
+  pageGestures?: boolean;
   touchContainer?: HTMLElement;
   /** @internal Test seam — replaces `document` for the touch overlay. */
   _touchDoc?: {
@@ -331,10 +358,32 @@ interface CreateGame2DOptions {
   _scheduler?: Scheduler;
 }
 /** What createGame needs from a renderer (stats is optional for test stubs). */
+/** What a renderer must do for the engine. The test seam supplies this much. */
 interface GameRenderer {
   dispose(): void;
   stats?(): RendererStats;
 }
+/**
+* What a GAME can ask its renderer for.
+*
+* The two coordinate conversions live here rather than only on `Renderer2D`,
+* because `game.renderer` is what a consumer holds: a tap needs screen→world
+* and a pinned DOM element needs world→screen, both are documented in the
+* skills, and neither typechecked through the narrow interface. Found by
+* following my own documentation in a fresh project.
+*/
+interface Game2DRenderer extends GameRenderer {
+  /** Canvas px → world px, through the design viewport and the camera. */
+  worldFromScreen(sx: number, sy: number): {
+    x: number;
+    y: number;
+  };
+  /** World px → canvas px (pin DOM to a node). */
+  screenFromWorld(wx: number, wy: number): {
+    x: number;
+    y: number;
+  };
+}
 interface Game2D {
   engine: Engine;
   scene: Scene$1;
@@ -343,13 +392,25 @@ interface Game2D {
   * A running tree has moved; the editor gets what was written down.
   */
   sourceJson: SceneJson;
-  renderer: GameRenderer;
+  renderer: Game2DRenderer;
   physics: Physics2D | null;
   /**
   * The node under a screen pixel, or null. The raycast the renderer already
   * does — reachable now without holding the renderer.
   */
   pick(x: number, y: number): Node | null;
+  /**
+  * Assets that did not arrive — a texture that 404'd, a sound that cannot be
+  * played — with the ref and the reason.
+  *
+  * The verify loop names this as one of its four signals, and 2D never had it:
+  * a 2D game could not ask the question at all.
+  */
+  assetErrors(): Array<{
+    ref: string;
+    url: string;
+    error: string;
+  }>;
   /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
   stats(): GameStats;
   /**
@@ -841,6 +902,8 @@ declare class Renderer2D {
   private syncSelectionOutline;
   private syncDebugLines;
   private render;
+  /** UI-pass extent from the last render — the space HUD nodes are posed in. */
+  private lastUi;
   private lastViewport;
   private lastView;
   /** The world view used by the LAST render (center/zoom/canvas size). */
@@ -863,6 +926,26 @@ declare class Renderer2D {
   * Hits resolve through `userData.incantoNode` and prefer higher renderOrder.
   */
   pick(sx: number, sy: number): Node | null;
+  private hit;
+  /** Does the UI pass draw this node (i.e. is it under a UILayer)? */
+  isUiNode(node: Node): boolean;
+  /**
+  * UI-space px → canvas px.
+  *
+  * A UILayer's children are posed in the UI pass's own space (origin top-left,
+  * `uiW × uiH`), NOT in world space — so mapping them with `screenFromWorld`
+  * puts them wherever the game camera happens to be looking.
+  */
+  screenFromUi(ux: number, uy: number): {
+    x: number;
+    y: number;
+  };
+  /** Canvas px → UI-space px (the inverse of `screenFromUi`). */
+  uiFromScreen(sx: number, sy: number): {
+    x: number;
+    y: number;
+  };
+  private uiView;
   /**
   * Canvas-pixel AABB of a node's rendered world-pass objects, or null when it
   * has no renderable extent (plain Nodes, empty containers).

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CkzKZ4v5.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-B_BaaGx-.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-Ccq2L9R0.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-9D87XaiX.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-DROK2l7J.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-BhZZ-HAp.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,10 +1,10 @@
-import { D as QualityCaps, Dt as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-rZNfzVbH.js";
+import { D as QualityCaps, Dt as Node, P as Scene$1, S as Scheduler, T as RendererStats, b as Engine, d as PropSchema, n as BehaviorCtor, w as GameStats } from "./behavior-Do0Da56m.js";
 import { n as DiagnosticSink, t as EditorSwitchOptions } from "./editor-switch-DAvWQeld.js";
 import { i as SceneJson$1, s as JsonObject } from "./schema-CFeioQRE.js";
-import { t as LoadSceneOptions } from "./loader-Dkbn56KC.js";
+import { t as LoadSceneOptions } from "./loader-Cu_7kJDy.js";
 import { t as ParticleSim } from "./particle-sim-BzJ1yxoE.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-DZ70IY26.js";
-import { n as PathGrid, s as SpatialPose } from "./pathfinding-Bz34pvQD.js";
+import { n as PathGrid, s as SpatialPose } from "./pathfinding-HNGFqGUZ.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";
 import { Sky } from "three/examples/jsm/objects/Sky.js";
@@ -563,6 +563,12 @@ interface CreateGame3DOptions {
   * parent element — give it position: relative).
   */
   touch?: "auto" | boolean;
+  /**
+  * Leave the browser's touch gestures (scroll/zoom/pull-to-refresh) on the
+  * canvas. Default false: the GAME owns them, or a drag on a phone scrolls
+  * the page instead of playing.
+  */
+  pageGestures?: boolean;
   touchContainer?: HTMLElement;
   /** @internal Test seam — replaces `document` for the touch overlay. */
   _touchDoc?: {

package/dist/3d.js

@@ -1,9 +1,9 @@
-import { F as CharacterBody3D, H as WATER_MAX_RIPPLES, I as PhysicsBody3D, L as RigidBody3D, M as WATER_CUTOUT_MAX, N as WaterCutout3D, P as Area3D, R as StaticBody3D, j as Water3D, z as Node3D } from "./gameplay-bStgtZBV.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-C08pOC6H.js";
-import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-BNaOC3Px.js";
+import { F as CharacterBody3D, H as WATER_MAX_RIPPLES, I as PhysicsBody3D, L as RigidBody3D, M as WATER_CUTOUT_MAX, N as WaterCutout3D, P as Area3D, R as StaticBody3D, j as Water3D, z as Node3D } from "./gameplay-CRYw_Q-T.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-SkGanr2s.js";
+import { a as Environment3D, c as parseEnvironment3D, d as AssetStore3D, i as syncTree, l as sunDirectionFromElevationAzimuth, o as setEnvironment3D, r as Renderer3D, s as horizonColorFromSky, t as createGame3D, u as sunDirectionFromSky } from "./create-game-CDJ1lVqK.js";
 import { a as frameSignature, n as diffSignatures, o as frameStats, r as diffText, s as frameText, t as SIGNATURE_GRID } from "./frame-report-njybhZon.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-B2c5KNYh.js";
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DmyO2oaN.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/{behavior-rZNfzVbH.d.ts → behavior-Do0Da56m.d.ts}

@@ -325,9 +325,42 @@ type BusName = "sfx" | "music";
 * engine.audio.muted = true;   // mute toggle
 * ```
 */
+/** One thing that sounded (or would have, headless). */
+interface AudioEvent {
+  /** `preset` (procedural one-shot), `src` (a clip), `music`, or `voice`. */
+  kind: "preset" | "src" | "music" | "voice";
+  /** The preset name, the clip url, or the voice preset. */
+  name: string;
+  /** Node path for a node-driven sound; `engine.music` / `engine.sfx` otherwise. */
+  from: string;
+  bus: BusName;
+  /** `engine.time` when it fired, in seconds. */
+  at: number;
+}
 declare class AudioBuses {
   /** Fires whenever any value changes (drives live re-gain of playing sounds). */
   readonly changed: Signal<[]>;
+  /**
+  * What has sounded, most recent last.
+  *
+  * Audio is a no-op headless, which left "did the coin sound actually fire
+  * when the coin was collected?" unanswerable — the audio skill's own advice
+  * was to *"assert `play()` doesn't throw and check your gameplay logic
+  * instead"*, which checks something else. The CALL still happens with no
+  * backend, so recording it answers the wiring question everywhere: in the
+  * verify VM, in a playtest, in a test.
+  *
+  * Bounded (200) — a game running for an hour must not grow a log.
+  */
+  private readonly events;
+  /** @internal Called by the players; games read `recent()`. */
+  record(event: AudioEvent): void;
+  /** The last `limit` sounds, oldest first. */
+  recent(limit?: number): AudioEvent[];
+  /** How many times a preset/clip/track sounded — the assertion you want. */
+  countOf(name: string): number;
+  /** Forget what has sounded so far (between scenes, or between assertions). */
+  clearLog(): void;
   private _master;
   private _sfx;
   private _music;
@@ -377,6 +410,8 @@ interface MusicBackend {
   createTrack(src: string): MusicTrack;
   /** Resume a gesture-suspended context (wired to the first user gesture). */
   unlock(): void;
+  /** Release the context it owns (optional — teardown). */
+  dispose?(): void;
 }
 interface PlayMusicOptions {
   /** Loop the track (default true — music usually loops). */
@@ -420,6 +455,15 @@ declare class MusicManager {
   get current(): string | null;
   /** Per-manager volume (0..1), on top of the bus gain. */
   get volume(): number;
+  /**
+  * The backend, or an INERT one that mints silent tracks.
+  *
+  * Never null, on purpose: the manager used to return before touching its
+  * state when there was no backend, so `current` stayed null forever in every
+  * headless run — including the verify VM, which is the only place a game is
+  * checked automatically. "Did the boss music start?" had no answer anywhere.
+  * With an inert backend the state machine runs identically and nothing plays.
+  */
   private ensure;
   /** Resume a gesture-suspended context + (re)start any pending track. */
   unlock(): void;
@@ -432,6 +476,13 @@ declare class MusicManager {
   crossfadeTo(src: string, seconds?: number): void;
   /** Stop the current track, optionally fading out over `fadeOut` seconds. */
   stop(fadeOut?: number): void;
+  /**
+  * Stop instantly and release the backend — music must not outlive the game.
+  *
+  * `dispose()` is the one call that tears an SPA-mounted game down, and it used
+  * to leave the track playing with the engine that owned it gone.
+  */
+  dispose(): void;
   /** Set the per-manager volume (re-applied to live tracks on the next tick). */
   setVolume(v: number): void;
   /** Advance fades by `dt` seconds and (re)apply bus×fade gains. Frame-driven. */
@@ -588,6 +639,14 @@ interface Voice {
 //#endregion
 //#region src/core/audio/webaudio-sfx.d.ts
 /** A spatial emitter: where the sound is + where the listener is. */
+/** The shape `AudioBuses.record` takes (structural — no import cycle). */
+interface AudioRecord {
+  kind: "preset" | "src" | "music" | "voice";
+  name: string;
+  from: string;
+  bus: "sfx" | "music";
+  at: number;
+}
 interface SpatialPlay {
   /** Emitter world position. */
   position: Vec3;
@@ -615,6 +674,19 @@ declare class SfxEngine {
   private ctx;
   private resolved;
   private readonly pcmCache;
+  /**
+  * The engine's buses, when this SfxEngine belongs to one — so a continuous
+  * voice lands in the same audio record as everything else. A record that
+  * covered only SOME sounds would answer "did the engine hum start?" with a
+  * confident no.
+  */
+  private buses;
+  /** Live continuous voices, so teardown can silence the ones nobody stopped. */
+  private readonly voices;
+  /** @internal Engine wiring. */
+  _setBuses(buses: {
+    record(event: AudioRecord): void;
+  }): void;
   /** True once a backend is present (lazily created on first use). */
   get available(): boolean;
   private ensure;
@@ -624,6 +696,18 @@ declare class SfxEngine {
   * done. Headless returns an inert handle (same call sites, no ifs).
   */
   startVoice(preset: VoicePreset, gain?: number): Voice;
+  /** How many continuous voices are still running (teardown/leak checks). */
+  get liveVoiceCount(): number;
+  /** Silence every continuous voice — the hum must not outlive the game. */
+  stopAll(seconds?: number): void;
+  /**
+  * Silence everything and release the AudioContext.
+  *
+  * A browser allows only a handful of contexts per page, so an SPA that mounts
+  * the game a few times must hand this one back — `dispose()` is documented as
+  * the call that tears everything down.
+  */
+  dispose(): void;
   /** Resume a gesture-suspended context (wired to the first user gesture). */
   unlock(): void;
   /**
@@ -760,6 +844,20 @@ declare class InputMap {
       connect(fn: () => void): () => void;
     };
   }): () => void;
+  /**
+  * Pointer input from a mouse, a FINGER or a pen — one code path.
+  *
+  * This used to bind `mousedown`/`mousemove`/`mouseup`, which on a phone only
+  * arrive as COMPATIBILITY events: delayed until the browser has decided the
+  * touch is not a scroll, never fired for drags or multi-touch, and suppressed
+  * outright once the surface claims its gestures with `touch-action: none`.
+  * So every genre the comment below lists — match-3, tower defense, card,
+  * point-and-click, RTS — was mouse-only on the device most of them are played
+  * on. Pointer events cover all three input kinds and fire immediately.
+  *
+  * Only the PRIMARY pointer drives it: a second finger (the one on the virtual
+  * stick) must not also swing the camera.
+  */
   attachPointer(target: HTMLElement, opts?: {
     lockOnClick?: boolean;
   }): () => void;
@@ -1581,6 +1679,16 @@ interface PropDef {
   */
   nodePath?: boolean;
   /**
+  * The prop must be given a value — an empty string is not a configuration.
+  *
+  * `Chase.target` and `FollowCamera.target` threw for this in `onReady`, which
+  * is the browser, at the moment the level starts. Declared here it is a LOAD
+  * error instead: `incanto-check` reports it while you are still writing the
+  * scene, and the editor knows not to "unlink" a prop whose emptiness the
+  * engine refuses.
+  */
+  required?: boolean;
+  /**
   * For an OBJECT-valued prop shaped as a tagged union — `collider`, whose
   * `shape` decides which other keys are required. One declaration gives an
   * inspector both the dropdown AND something valid to write when the tag

package/dist/{create-game-CkzKZ4v5.js → create-game-9D87XaiX.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { A as registerBehavior, n as loadScene, o as computeViewport, s as resolveViewport, w as diagnose } from "./loader-B2asghWa.js";
-import { h as Engine, m as AudioPlayer } from "./register-CGq-Hee8.js";
+import { A as registerBehavior, C as diagnose, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-BTkHYrQn.js";
+import { b as AudioPlayer, x as Engine } from "./register-BTomIiYG.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
-import { a as openBundledEditor, i as devServerLibrary, n as pauseWhenHidden, r as crossFade, t as teardown } from "./teardown-BKTCzLek.js";
-import { n as registerGameplayBehaviors } from "./gameplay-bStgtZBV.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-B_BaaGx-.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-BnMyy9tr.js";
+import { a as openBundledEditor, c as audioErrors, i as devServerLibrary, n as pauseWhenHidden, r as crossFade, s as claimCanvasGestures, t as teardown } from "./teardown-Bw2aeyGI.js";
+import { n as registerGameplayBehaviors } from "./gameplay-CRYw_Q-T.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-DROK2l7J.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-Ccq2L9R0.js";
+import { n as enablePhysics2D } from "./physics-2d-BhZZ-HAp.js";
 import { Box3, BufferAttribute, BufferGeometry, Color, LineBasicMaterial, LineSegments, LinearFilter, NearestFilter, OrthographicCamera, Raycaster, SRGBColorSpace, Scene, TextureLoader, Vector2, Vector3, WebGLRenderer } from "three";
 //#region src/2d/assets.ts
 /**
@@ -50,6 +50,7 @@ var AssetStore2D = class {
 				},
 				onError: (err) => {
 					state.status = "error";
+					state.error = err instanceof Error ? err.message : `could not load ${decl.url}`;
 					diagnose(this.engine, "error", `[incanto] failed to load texture '${key}' (${decl.url}):`, err);
 				}
 			});
@@ -66,10 +67,31 @@ var AssetStore2D = class {
 				type,
 				frameWidth,
 				frameHeight,
+				url: decl.url,
 				state
 			});
 		}
 	}
+	/**
+	* Every declared asset that FAILED to load, `$ref` and url included.
+	*
+	* The 3D store has answered this since 0.32.0 — the 2D one only tracked a
+	* per-key status, which the console printed and nothing else could read. A
+	* 404'd texture is invisible, and "invisible" is the one symptom an author
+	* cannot tell apart from "I put it in the wrong place".
+	*/
+	errors() {
+		const out = [];
+		for (const [key, entry] of this.entries) {
+			if (entry.state.status !== "error") continue;
+			out.push({
+				ref: `$${key}`,
+				url: entry.url,
+				error: entry.state.error ?? `could not load ${entry.url}`
+			});
+		}
+		return out;
+	}
 	/** Load status of a declared asset KEY (no '$'), or undefined if unknown. */
 	status(key) {
 		return this.entries.get(key)?.state.status;
@@ -107,6 +129,18 @@ function worldFromScreen(view, sx, sy) {
 		y: (sy - view.h / 2) / view.zoom + view.cy
 	};
 }
+function screenFromUi(v, ux, uy) {
+	return {
+		x: v.offsetX + ux / v.uiW * v.contentW,
+		y: v.offsetY + uy / v.uiH * v.contentH
+	};
+}
+function uiFromScreen(v, sx, sy) {
+	return {
+		x: (sx - v.offsetX) / v.contentW * v.uiW,
+		y: (sy - v.offsetY) / v.contentH * v.uiH
+	};
+}
 //#endregion
 //#region src/2d/selection-outline.ts
 /** 2D twin of the 3D selection outline: a world-space (px, y-down) rectangle
@@ -355,6 +389,10 @@ var Renderer2D = class {
 		const view = vp ? computeViewport(w, h, vp) : null;
 		const uiW = view ? view.viewW : w;
 		const uiH = view ? view.viewH : h;
+		this.lastUi = {
+			w: uiW,
+			h: uiH
+		};
 		const { activeCamera } = syncTree2D(scene.root, this.worldScene, this.uiScene, this.assets, {
 			width: uiW,
 			height: uiH
@@ -406,6 +444,11 @@ var Renderer2D = class {
 		this.webgl.render(this.uiScene, this.uiCam);
 		this.webgl.autoClear = true;
 	}
+	/** UI-pass extent from the last render — the space HUD nodes are posed in. */
+	lastUi = {
+		w: 1,
+		h: 1
+	};
 	lastViewport = null;
 	lastView = {
 		cx: 0,
@@ -448,8 +491,13 @@ var Renderer2D = class {
 		const cw = this.lastViewport?.contentW ?? w;
 		const ch = this.lastViewport?.contentH ?? h;
 		pickNdc.set((sx - ox) / cw * 2 - 1, -((sy - oy) / ch * 2 - 1));
-		raycaster.setFromCamera(pickNdc, this.worldCam);
-		const hits = raycaster.intersectObjects(this.worldScene.children, true);
+		const ui = this.hit(this.uiScene, this.uiCam);
+		if (ui) return ui;
+		return this.hit(this.worldScene, this.worldCam);
+	}
+	hit(scene, cam) {
+		raycaster.setFromCamera(pickNdc, cam);
+		const hits = raycaster.intersectObjects(scene.children, true);
 		let best = null;
 		for (const hit of hits) {
 			let obj = hit.object;
@@ -464,6 +512,39 @@ var Renderer2D = class {
 		}
 		return best?.node ?? null;
 	}
+	/** Does the UI pass draw this node (i.e. is it under a UILayer)? */
+	isUiNode(node) {
+		let obj = node._object2D ?? node._group ?? null;
+		while (obj) {
+			if (obj === this.uiScene) return true;
+			obj = obj.parent;
+		}
+		return false;
+	}
+	/**
+	* UI-space px → canvas px.
+	*
+	* A UILayer's children are posed in the UI pass's own space (origin top-left,
+	* `uiW × uiH`), NOT in world space — so mapping them with `screenFromWorld`
+	* puts them wherever the game camera happens to be looking.
+	*/
+	screenFromUi(ux, uy) {
+		return screenFromUi(this.uiView(), ux, uy);
+	}
+	/** Canvas px → UI-space px (the inverse of `screenFromUi`). */
+	uiFromScreen(sx, sy) {
+		return uiFromScreen(this.uiView(), sx, sy);
+	}
+	uiView() {
+		return {
+			offsetX: this.lastViewport?.offsetX ?? 0,
+			offsetY: this.lastViewport?.offsetY ?? 0,
+			contentW: this.lastViewport?.contentW ?? this.lastView.w,
+			contentH: this.lastViewport?.contentH ?? this.lastView.h,
+			uiW: this.lastUi.w,
+			uiH: this.lastUi.h
+		};
+	}
 	/**
 	* Canvas-pixel AABB of a node's rendered world-pass objects, or null when it
 	* has no renderable extent (plain Nodes, empty containers).
@@ -476,8 +557,9 @@ var Renderer2D = class {
 		if (boundsScratch.isEmpty()) return null;
 		boundsScratch.getSize(sizeScratch3);
 		if (sizeScratch3.x === 0 && sizeScratch3.y === 0) return null;
-		const a = this.screenFromWorld(boundsScratch.min.x, -boundsScratch.max.y);
-		const b = this.screenFromWorld(boundsScratch.max.x, -boundsScratch.min.y);
+		const map = this.isUiNode(node) ? (x, y) => this.screenFromUi(x, y) : (x, y) => this.screenFromWorld(x, y);
+		const a = map(boundsScratch.min.x, -boundsScratch.max.y);
+		const b = map(boundsScratch.max.x, -boundsScratch.min.y);
 		return {
 			x: a.x,
 			y: a.y,
@@ -543,10 +625,15 @@ async function createGame2D(opts) {
 	const cleanups = [];
 	const keyboard = opts.keyboard ?? (typeof window !== "undefined" ? window : false);
 	if (keyboard) engine.input.attachKeyboard(keyboard);
+	if (opts.pointer) {
+		const lockOnClick = typeof opts.pointer === "object" ? opts.pointer.lockOnClick ?? false : false;
+		engine.input.attachPointer(opts.canvas, { lockOnClick });
+	}
 	cleanups.push(wireAudioUnlock(engine, scene.root, opts.canvas));
 	cleanups.push(engine.settings.bindAudio(engine.audio));
 	cleanups.push(pauseWhenHidden(engine));
 	cleanups.push(engine.settings.bindLocale(engine.locale));
+	if (!opts.pageGestures) claimCanvasGestures(opts.canvas);
 	const touchMode = opts.touch ?? "auto";
 	if (touchMode !== false) {
 		const host = opts.touchContainer ?? opts.canvas.parentElement ?? null;
@@ -636,6 +723,9 @@ async function createGame2D(opts) {
 		pick(x, y) {
 			return engine.picker?.(x, y) ?? null;
 		},
+		assetErrors() {
+			return [...renderer.assets?.errors() ?? [], ...audioErrors(engine.scene?.tree.root)];
+		},
 		stats() {
 			return {
 				triangles: 0,
@@ -673,10 +763,17 @@ function wireAudioUnlock(engine, root, canvas) {
 		target: canvasTarget,
 		type: "pointerdown"
 	});
-	if (typeof window !== "undefined") sources.push({
-		target: window,
-		type: "keydown"
-	});
+	if (typeof window !== "undefined") {
+		const win = window;
+		sources.push({
+			target: win,
+			type: "keydown"
+		});
+		sources.push({
+			target: win,
+			type: "pointerdown"
+		});
+	}
 	if (sources.length === 0) return () => {};
 	function detachAll() {
 		for (const s of sources) s.target.removeEventListener?.(s.type, unlock);

package/dist/{create-game-BNaOC3Px.js → create-game-CDJ1lVqK.js}

@@ -1,15 +1,15 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { A as registerBehavior, n as loadScene, w as diagnose } from "./loader-B2asghWa.js";
-import { _ as qualityCaps, h as Engine, m as AudioPlayer, y as qualityRendering } from "./register-CGq-Hee8.js";
+import { A as registerBehavior, C as diagnose, n as loadScene } from "./loader-BTkHYrQn.js";
+import { C as qualityCaps, T as qualityRendering, b as AudioPlayer, x as Engine } from "./register-BTomIiYG.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { r as parseDrive, t as logReport } from "./log-report-lxrQY9cH.js";
-import { i as resolveRendering, n as attachTouchControls } from "./touch-BoNg_MnF.js";
-import { a as openBundledEditor, i as devServerLibrary, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, t as teardown } from "./teardown-BKTCzLek.js";
-import { I as PhysicsBody3D, V as createCausticsQuad, n as registerGameplayBehaviors, z as Node3D } from "./gameplay-bStgtZBV.js";
+import { r as parseDrive, t as logReport } from "./log-report-CPFm4OXf.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-BnMyy9tr.js";
+import { a as openBundledEditor, c as audioErrors, i as devServerLibrary, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, s as claimCanvasGestures, t as teardown } from "./teardown-Bw2aeyGI.js";
+import { I as PhysicsBody3D, V as createCausticsQuad, n as registerGameplayBehaviors, z as Node3D } from "./gameplay-CRYw_Q-T.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-C08pOC6H.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-SkGanr2s.js";
 import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-njybhZon.js";
-import { n as enablePhysics3D } from "./physics-3d-B2c5KNYh.js";
+import { n as enablePhysics3D } from "./physics-3d-DmyO2oaN.js";
 import { ACESFilmicToneMapping, AmbientLight, Box3, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, HalfFloatType, LineBasicMaterial, LineSegments, Matrix4, Mesh, PCFShadowMap, PMREMGenerator, PerspectiveCamera, PlaneGeometry, Quaternion, Raycaster, Scene, ShaderMaterial, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
 import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
@@ -2349,6 +2349,7 @@ async function createGame3D(opts) {
 		engine.input.attachPointer(opts.canvas, { lockOnClick });
 	}
 	cleanups.push(wireAudioUnlock(engine, scene.root, opts.canvas));
+	if (!opts.pageGestures) claimCanvasGestures(opts.canvas);
 	const touchMode = opts.touch ?? "auto";
 	if (touchMode !== false) {
 		const host = opts.touchContainer ?? opts.canvas.parentElement ?? null;
@@ -2575,7 +2576,7 @@ async function createGame3D(opts) {
 		renderer,
 		physics,
 		assetErrors() {
-			return renderer.assets?.errors() ?? [];
+			return [...renderer.assets?.errors() ?? [], ...audioErrors(engine.scene?.tree.root)];
 		},
 		async frame(frameOpts) {
 			const capture = renderer.captureFrame;
@@ -2623,10 +2624,17 @@ function wireAudioUnlock(engine, root, canvas) {
 		target: canvasTarget,
 		type: "pointerdown"
 	});
-	if (typeof window !== "undefined") sources.push({
-		target: window,
-		type: "keydown"
-	});
+	if (typeof window !== "undefined") {
+		const win = window;
+		sources.push({
+			target: win,
+			type: "keydown"
+		});
+		sources.push({
+			target: win,
+			type: "pointerdown"
+		});
+	}
 	if (sources.length === 0) return () => {};
 	function detachAll() {
 		for (const s of sources) s.target.removeEventListener?.(s.type, unlock);

package/dist/debug.d.ts

@@ -1,4 +1,4 @@
-import { T as RendererStats, b as Engine, jt as LogLevel } from "./behavior-rZNfzVbH.js";
+import { T as RendererStats, b as Engine, jt as LogLevel } from "./behavior-Do0Da56m.js";
 
 //#region src/debug/panel.d.ts
 /** Minimal document surface the overlay needs (injectable for tests). */

package/dist/debug.js

@@ -1,5 +1,5 @@
 import { t as jsonClone } from "./json-BLk7H2Qa.js";
-import { s as mergeStaticProps } from "./registry-IyWCGe4q.js";
+import { s as mergeStaticProps } from "./registry-C7u42TID.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
 //#region src/debug/capture.ts
 /**