incanto 0.56.0 → 0.58.0

package/dist/{behavior-CyQoSu4n.d.ts → behavior-l08AEbq9.d.ts}

@@ -465,6 +465,11 @@ declare class MusicManager {
   * With an inert backend the state machine runs identically and nothing plays.
   */
   private ensure;
+  /**
+  * Where a track that will never play gets reported. The engine sets this; a
+  * bare MusicManager (tests) stays quiet.
+  */
+  onTrackError: ((src: string, reason: string) => void) | null;
   /** Resume a gesture-suspended context + (re)start any pending track. */
   unlock(): void;
   /** Play a single track (replacing any current one immediately, no fade). */

package/dist/{create-game-YvaNWhe6.js → create-game-BZwWJIns.js}

@@ -1,13 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.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-p48lHE2o.js";
+import { A as registerBehavior, C as diagnose, n as loadScene, o as computeViewport, s as resolveViewport } from "./loader-BcrRSjxB.js";
+import { _ as Engine, g as AudioPlayer } from "./register-Ch70uByv.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.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-C7uVSJvx.js";
-import { n as registerGameplayBehaviors } from "./gameplay-C_SPzmUe.js";
-import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-en63AEZO.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-DESwnpOc.js";
+import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-Cs113S9F.js";
+import { o as frameStats } from "./frame-report-BSMny7oe.js";
+import { n as registerGameplayBehaviors } from "./gameplay-BVphcxmE.js";
+import { g as PhysicsBody2D, n as UILayer, t as registerNodes2D, u as Camera2D, y as Node2D } from "./register-C6ZBFRjd.js";
 import { t as debugSources } from "./debug-draw-BM3DsvtT.js";
-import { n as enablePhysics2D } from "./physics-2d-CfWAggJ1.js";
+import { n as enablePhysics2D } from "./physics-2d-EqA-jddf.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
 /**
@@ -276,6 +277,8 @@ function prune(obj, visited) {
 * (center/zoom/limits), then a screen-space UI pass for UILayer subtrees.
 * 1 unit = 1 px, (0,0) top-left, +y down.
 */
+/** How long to wait for the game's own loop before drawing a frame ourselves. */
+const CAPTURE_NUDGE_MS = 120;
 var Renderer2D = class {
 	/**
 	* When set, the world pass frames THIS view instead of the scene's active
@@ -284,6 +287,76 @@ var Renderer2D = class {
 	*/
 	viewOverride = null;
 	webgl;
+	/**
+	* The pixels of the next drawn frame — how `incanto-frame` sees a 2D game.
+	*
+	* Mirrors Renderer3D exactly: read inside the render, so
+	* `preserveDrawingBuffer` can stay off, and nudge a frame ourselves after a
+	* moment because a browser stops handing rAF to a tab it thinks is hidden —
+	* including a window merely covered by another one. Without the nudge the
+	* promise never settles and the CLI reports "no page connected" about a page
+	* that is right there.
+	*/
+	captureFrame() {
+		return new Promise((resolve, reject) => {
+			this.pendingCaptures.push({
+				resolve,
+				reject
+			});
+			setTimeout(() => {
+				if (this.pendingCaptures.length > 0) try {
+					this.render();
+				} catch (error) {
+					const e = error instanceof Error ? error : new Error(String(error));
+					for (const w of this.pendingCaptures.splice(0)) w.reject(e);
+				}
+			}, CAPTURE_NUDGE_MS);
+		});
+	}
+	pendingCaptures = [];
+	/** Hand the waiting captures this frame's pixels. Called at the end of render. */
+	drainFrameCapture() {
+		if (this.pendingCaptures.length === 0) return;
+		const waiting = this.pendingCaptures;
+		this.pendingCaptures = [];
+		try {
+			const gl = this.webgl.getContext();
+			const width = this.webgl.domElement.width;
+			const height = this.webgl.domElement.height;
+			const pixels = new Uint8Array(width * height * 4);
+			this.webgl.setRenderTarget(null);
+			gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+			for (let y = 0; y < Math.floor(height / 2); y++) {
+				const top = y * width * 4;
+				const bottom = (height - 1 - y) * width * 4;
+				for (let i = 0; i < width * 4; i++) {
+					const t = pixels[top + i];
+					pixels[top + i] = pixels[bottom + i];
+					pixels[bottom + i] = t;
+				}
+			}
+			for (const w of waiting) w.resolve({
+				pixels,
+				width,
+				height
+			});
+		} catch (error) {
+			const e = error instanceof Error ? error : new Error(String(error));
+			for (const w of waiting) w.reject(e);
+		}
+	}
+	/** The pixel ratio the scene asked for, before any render-scale setting. */
+	basePixelRatio = 1;
+	/**
+	* Fewer pixels for the same world — the cheapest frames on a weak device.
+	*
+	* `settings.renderScale` persisted and was applied by the 3D boot only, so a
+	* 2D game's resolution slider saved a number and changed nothing, forever.
+	*/
+	setRenderScale(scale) {
+		const clamped = Number.isFinite(scale) && scale > 0 ? Math.min(2, Math.max(.25, scale)) : 1;
+		this.webgl.setPixelRatio(this.basePixelRatio * clamped);
+	}
 	worldScene = new Scene();
 	syncScratch = createSync2DScratch();
 	/** Editors set this: keep syncing `static: true` subtrees every frame. */
@@ -313,6 +386,7 @@ var Renderer2D = class {
 		});
 		this.webgl.info.autoReset = false;
 		this.engine.picker = (x, y) => this.pick(x, y);
+		this.basePixelRatio = rendering.pixelRatio;
 		this.webgl.setPixelRatio(rendering.pixelRatio);
 		this.webgl.info.autoReset = false;
 		this.debugLines = new LineSegments(new BufferGeometry(), new LineBasicMaterial({
@@ -447,6 +521,7 @@ var Renderer2D = class {
 		this.webgl.autoClear = false;
 		this.webgl.render(this.uiScene, this.uiCam);
 		this.webgl.autoClear = true;
+		this.drainFrameCapture();
 	}
 	/** UI-pass extent from the last render — the space HUD nodes are posed in. */
 	lastUi = {
@@ -663,6 +738,64 @@ async function createGame2D(opts) {
 		...opts.pixelRatio !== void 0 ? { pixelRatio: opts.pixelRatio } : {},
 		...opts.antialias !== void 0 ? { antialias: opts.antialias } : {}
 	});
+	cleanups.push(engine.settings.bindFrameCap((fps) => {
+		engine.maxFps = fps;
+	}));
+	cleanups.push(engine.settings.bindRenderScale((scale) => {
+		renderer.setRenderScale?.(scale);
+	}));
+	/**
+	* Feed the running game a drive script and count the frames it drew.
+	*
+	* Same as the 3D boot: the count travels with the report because a browser
+	* stops handing rAF to a hidden tab, and inputs landing on a game that never
+	* advances produce an UNCHANGED capture that says nothing about why.
+	*/
+	const applyDrive = async (steps) => {
+		let frames = 0;
+		let watching = true;
+		const tick = () => {
+			if (!watching) return;
+			frames += 1;
+			requestAnimationFrame(tick);
+		};
+		if (typeof requestAnimationFrame === "function") requestAnimationFrame(tick);
+		for (const step of steps) switch (step.kind) {
+			case "press":
+				engine.input.pressAction(step.action);
+				break;
+			case "release":
+				engine.input.releaseAction(step.action);
+				break;
+			case "vector":
+				engine.input.setActionVector(step.action, step.x, step.y);
+				break;
+			case "key":
+				engine.input.handleKey(step.code, step.down);
+				break;
+			case "pointer":
+				engine.input.handlePointerMove(step.dx, step.dy);
+				break;
+			case "step":
+				await new Promise((r) => setTimeout(r, step.ms));
+				break;
+		}
+		watching = false;
+		return frames;
+	};
+	cleanups.push(...wireDevChannel({
+		engine,
+		applyDrive,
+		captureFramePixels: () => {
+			const capture = renderer.captureFrame;
+			if (!capture) return Promise.reject(new IncantoError("TREE_VIOLATION", "this renderer cannot capture frames"));
+			return capture.call(renderer);
+		},
+		rendererStats: () => renderer.stats?.(),
+		assetErrors: () => {
+			return [...renderer.assets?.errors() ?? [], ...audioErrors(engine.scene?.tree.root)];
+		}
+	}));
 	const wantDebug = opts.debug ?? false;
 	const wantEditor = opts.editor ?? wantDebug;
 	const editorSwitch = wantEditor === true ? {} : wantEditor ? wantEditor : null;
@@ -727,6 +860,12 @@ async function createGame2D(opts) {
 		pick(x, y) {
 			return engine.picker?.(x, y) ?? null;
 		},
+		async frame(frameOpts) {
+			const capture = renderer.captureFrame;
+			if (!capture) throw new IncantoError("TREE_VIOLATION", "this renderer cannot capture frames");
+			const shot = await capture.call(renderer);
+			return frameStats(shot.pixels, shot.width, shot.height, frameOpts);
+		},
 		assetErrors() {
 			return [...renderer.assets?.errors() ?? [], ...audioErrors(engine.scene?.tree.root)];
 		},

package/dist/{create-game-CqJkfMzm.js → create-game-D10bU5_J.js}

@@ -1,15 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.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-p48lHE2o.js";
+import { A as registerBehavior, C as diagnose, n as loadScene } from "./loader-BcrRSjxB.js";
+import { _ as Engine, g as AudioPlayer, x as qualityRendering, y as qualityCaps } from "./register-Ch70uByv.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.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-C7uVSJvx.js";
-import { B as Node3D, H as createCausticsQuad, L as PhysicsBody3D, n as registerGameplayBehaviors } from "./gameplay-C_SPzmUe.js";
+import { i as resolveRendering, n as attachTouchControls } from "./touch-DESwnpOc.js";
+import { a as openBundledEditor, c as claimCanvasGestures, i as devServerLibrary, l as audioErrors, n as pauseWhenHidden, o as poseFromRenderer, r as crossFade, s as wireDevChannel, t as teardown } from "./teardown-Cs113S9F.js";
+import { o as frameStats } from "./frame-report-BSMny7oe.js";
+import { R as PhysicsBody3D, U as createCausticsQuad, V as Node3D, n as registerGameplayBehaviors } from "./gameplay-BVphcxmE.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-DLHqgNAF.js";
-import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-njybhZon.js";
-import { n as enablePhysics3D } from "./physics-3d-NzDwWPrF.js";
+import { E as Camera3D, U as TextureCache3D, g as ModelInstance3D, n as registerNodes3D, t as resolveEnvironmentHdri, v as DirectionalLight3D } from "./environment-presets-CvvQr_bJ.js";
+import { n as enablePhysics3D } from "./physics-3d-Dnz4fsXX.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";
@@ -174,6 +173,59 @@ var AssetStore3D = class {
 	}
 };
 //#endregion
+//#region src/core/yield-frame.ts
+/**
+* Give the browser a chance to paint, and come back either way.
+*
+* Boot work that runs in slices — compiling shaders a few materials at a time,
+* reporting progress — yields between slices so the page stays responsive and
+* the loading bar can move. The obvious way to write that yield is
+* `requestAnimationFrame`, and it is a trap: **a browser does not run rAF for
+* a tab it considers hidden**, and "hidden" includes a background tab, a
+* minimized window, and a window fully covered by another one. Not slowly —
+* not at all. An `await` on rAF alone in that tab never returns.
+*
+* That is what happened to `createGame3D`: the shader warm-up hung mid-boot,
+* so the promise never resolved, the game's own `#loading` overlay was never
+* removed, and the dev channel — wired on the line after the one that hung —
+* never answered `incanto-frame` or `incanto-logs`. `incanto-verify` reported
+* `draws` and `says` as unmeasurable and told the reader to bring the window
+* to the front, which was true but sounded like a browser limitation. It was
+* ours, and it made two of the five verification rungs unreachable to anything
+* that cannot focus a window.
+*
+* So: race the frame against a timer. When frames are coming the frame wins
+* (~16 ms) and the behaviour is what it always was. When none is coming the
+* timer wins and the boot finishes — slower, because a hidden tab also clamps
+* timers to about a second, but finished beats hung.
+*/
+/** How long to wait for a paint that may never come. */
+const DEFAULT_MAX_WAIT_MS = 50;
+/**
+* Resolve on the next painted frame, or after `maxWaitMs`, whichever is first.
+*
+* @param maxWaitMs how long to wait for a frame before giving up on one
+* @param raf injected for tests; defaults to the global
+*/
+function yieldToFrame(maxWaitMs = DEFAULT_MAX_WAIT_MS, raf = typeof requestAnimationFrame === "function" ? requestAnimationFrame : void 0) {
+	return new Promise((resolve) => {
+		let done = false;
+		const finish = () => {
+			if (done) return;
+			done = true;
+			resolve();
+		};
+		const timer = setTimeout(finish, Math.max(0, maxWaitMs));
+		if (!raf) return;
+		raf(() => {
+			setTimeout(() => {
+				clearTimeout(timer);
+				finish();
+			}, 0);
+		});
+	});
+}
+//#endregion
 //#region src/3d/environment.ts
 const SKY_KEYS = [
 	"type",
@@ -1014,6 +1066,9 @@ var Environment3D = class {
 	/** Underwater fog/tint, created lazily the first time the camera submerges. */
 	underwaterFog = null;
 	underwaterBg = new Color();
+	/** Told when the scene's HDRI/preset lighting fails to arrive. Set by the
+	*  renderer, which is the piece that knows the engine and the asset store. */
+	onHdriError = null;
 	constructor(scene) {
 		this.scene = scene;
 		this.scene.add(this.ambient);
@@ -1161,6 +1216,8 @@ var Environment3D = class {
 			}
 			texture.mapping = EquirectangularReflectionMapping;
 			this.hdriTexture = texture;
+		}, void 0, (error) => {
+			this.onHdriError?.(url, error);
 		});
 	}
 	applySky(sky, gl) {
@@ -1575,7 +1632,14 @@ var Renderer3D = class {
 	};
 	webgl;
 	threeScene = new Scene();
-	environment = new Environment3D(this.threeScene);
+	environment = (() => {
+		const env = new Environment3D(this.threeScene);
+		env.onHdriError = (url, error) => {
+			this.assets.textures.noteError(url, error);
+			diagnose(this.engine, "error", `[incanto] the scene's lighting (${url}) could not be loaded — nothing else lights it.`);
+		};
+		return env;
+	})();
 	engine;
 	disconnect;
 	canvas;
@@ -1793,9 +1857,7 @@ var Renderer3D = class {
 				for (let k = i * per; k < Math.min((i + 1) * per, hidden.length); k++) hidden[k].visible = true;
 				this.webgl.compile(this.threeScene, camera);
 				onProgress?.((i + 1) / slices);
-				if (typeof requestAnimationFrame === "function") await new Promise((resolve) => {
-					requestAnimationFrame(() => setTimeout(resolve, 0));
-				});
+				await yieldToFrame();
 			}
 		} finally {
 			for (const obj of hidden) obj.visible = true;
@@ -2322,10 +2384,7 @@ async function createGame3D(opts) {
 	const report = async (fraction, label) => {
 		if (!opts.onProgress) return;
 		opts.onProgress(fraction, label);
-		if (typeof requestAnimationFrame !== "function") return;
-		await new Promise((resolve) => {
-			requestAnimationFrame(() => setTimeout(resolve, 0));
-		});
+		await yieldToFrame();
 	};
 	registerNodes3D();
 	if (opts.gameplay ?? true) registerGameplayBehaviors();
@@ -2500,67 +2559,13 @@ async function createGame3D(opts) {
 		watching = false;
 		return frames;
 	};
-	const hot = import.meta.hot;
-	if (hot) {
-		const onFrameRequest = (data) => {
-			const request = data;
-			const id = request?.id;
-			hot.send("incanto:frame-ack", { id });
-			const drive = request?.drive ? parseDrive(request.drive) : null;
-			if (drive?.error) {
-				hot.send("incanto:frame-report", {
-					id,
-					report: { error: drive.error }
-				});
-				return;
-			}
-			let droveFrames = null;
-			(drive ? applyDrive(drive.steps) : Promise.resolve(null)).then((frames) => {
-				droveFrames = frames;
-				return captureFramePixels();
-			}).then((shot) => hot.send("incanto:frame-report", {
-				id,
-				report: {
-					...frameStats(shot.pixels, shot.width, shot.height, { grid: request?.grid }),
-					signature: frameSignature(shot.pixels, shot.width, shot.height),
-					...droveFrames === null ? {} : { droveFrames },
-					...request?.image ? { image: frameImage(shot.pixels, shot.width, shot.height, (w, h) => Object.assign(document.createElement("canvas"), {
-						width: w,
-						height: h
-					}), request.image) } : {}
-				}
-			})).catch((error) => hot.send("incanto:frame-report", {
-				id,
-				report: { error: error instanceof Error ? error.message : String(error) }
-			}));
-		};
-		hot.on("incanto:frame-request", onFrameRequest);
-		cleanups.push(() => hot.off?.("incanto:frame-request", onFrameRequest));
-		const onLogsRequest = (data) => {
-			const id = data?.id;
-			try {
-				hot.send("incanto:logs-report", {
-					id,
-					report: logReport({
-						entries: engine.log.entries(),
-						stats: {
-							...engine.stats(),
-							...renderer.stats?.() ?? {}
-						},
-						assetErrors: renderer.assets?.errors() ?? [],
-						hidden: typeof document !== "undefined" && document.hidden
-					})
-				});
-			} catch (error) {
-				hot.send("incanto:logs-report", {
-					id,
-					report: { error: error instanceof Error ? error.message : String(error) }
-				});
-			}
-		};
-		hot.on("incanto:logs-request", onLogsRequest);
-		cleanups.push(() => hot.off?.("incanto:logs-request", onLogsRequest));
-	}
+	cleanups.push(...wireDevChannel({
+		engine,
+		applyDrive,
+		captureFramePixels,
+		rendererStats: () => renderer.stats?.(),
+		assetErrors: () => renderer.assets?.errors() ?? []
+	}));
 	cleanups.push(pauseWhenHidden(engine));
 	await report(1, "ready");
 	function disposeGame() {

package/dist/debug.d.ts

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

package/dist/{duplicate-MNLMAcbz.js → duplicate-BPLZDZpd.js}

@@ -1,4 +1,4 @@
-import { i as serializeNode, t as buildNodeJson } from "./loader-BTkHYrQn.js";
+import { i as serializeNode, t as buildNodeJson } from "./loader-BcrRSjxB.js";
 //#region src/core/scene/duplicate.ts
 function stripUids(json) {
 	const { uid: _uid, ...rest } = json;

package/dist/{environment-presets-DLHqgNAF.js → environment-presets-CvvQr_bJ.js}

@@ -1,10 +1,12 @@
-import { t as registerCoreNodes } from "./register-p48lHE2o.js";
+import { C as diagnose } from "./loader-BcrRSjxB.js";
+import { t as registerCoreNodes } from "./register-Ch70uByv.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { i as getNodeSchema, l as registerNode } from "./registry-C7u42TID.js";
 import { t as createNoise2D } from "./noise-CGUMx44x.js";
-import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-7qvUxF6Z.js";
-import { B as Node3D, F as Area3D, I as CharacterBody3D, L as PhysicsBody3D, M as Water3D, P as WaterCutout3D, R as RigidBody3D, W as colliderFootDrop, z as StaticBody3D } from "./gameplay-C_SPzmUe.js";
+import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimationAliases, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-C0wXLBZJ.js";
+import { B as StaticBody3D, F as WaterCutout3D, G as colliderFootDrop, I as Area3D, L as CharacterBody3D, N as Water3D, R as PhysicsBody3D, V as Node3D, w as tolerateUnknownAction, z as RigidBody3D } from "./gameplay-BVphcxmE.js";
+import { t as checkSheetGrid } from "./sheet-grid-BT6N_Bjs.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CRK0M4jT.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";
 import { clone } from "three/addons/utils/SkeletonUtils.js";
@@ -2175,8 +2177,41 @@ var AnimatedSprite3D = class extends Sprite3D {
 		}
 		this.currentFrame = this.frameList[this.frameIndex] ?? 0;
 	}
+	/**
+	* Does the grid fit the image, and does any animation run off the end?
+	*
+	* The same floor-division as the 2D twin, and for a long time the same
+	* division with none of its checking — the checker sat one directory away in
+	* 2d/ where this node could not see it.
+	*/
+	checkGrid(width, height) {
+		if (this.gridChecked === this.sheet) return;
+		this.gridChecked = this.sheet;
+		let highest = 0;
+		for (const [name, entry] of Object.entries(this.animations)) {
+			if (typeof entry === "string") continue;
+			try {
+				for (const frame of resolveFrames(entry.frames, name)) if (frame > highest) highest = frame;
+			} catch {
+				return;
+			}
+		}
+		const problem = checkSheetGrid(this.sheet, this.frameWidth, this.frameHeight, width, height, highest);
+		if (problem) diagnose(this.tree?.engine ?? null, "error", problem);
+	}
+	/** Reported once per sheet, so a bad grid says so on the first draw only. */
+	gridChecked = "";
+	/** Reported once, so a sheet with no frame size does not shout every frame. */
+	sizeReported = false;
 	resolveTexture(assets) {
-		if (!this.sheet || this.frameWidth <= 0 || this.frameHeight <= 0) return null;
+		if (!this.sheet) return null;
+		if (this.frameWidth <= 0 || this.frameHeight <= 0) {
+			if (!this.sizeReported) {
+				this.sizeReported = true;
+				diagnose(this.tree?.engine ?? null, "error", `[incanto] AnimatedSprite3D '${this.name}' has a sheet ('${this.sheet}') but frameWidth/frameHeight are 0 — it draws nothing. Set both to one frame's pixel size (bunx incanto-assets info <name> prints it for a built-in).`);
+			}
+			return null;
+		}
 		if (this.loadedSheetRef !== this.sheet) {
 			this.sheetTexture?.dispose();
 			this.loadedSheetRef = this.sheet;
@@ -2186,6 +2221,7 @@ var AnimatedSprite3D = class extends Sprite3D {
 		if (!tex) return null;
 		const image = tex.image;
 		if (!image?.width || !image.height) return tex;
+		this.checkGrid(image.width, image.height);
 		const cols = Math.max(1, Math.floor(image.width / this.frameWidth));
 		const col = this.currentFrame % cols;
 		const row = Math.floor(this.currentFrame / cols);
@@ -2319,10 +2355,14 @@ var BoneAttachment3D = class extends Node3D {
 			this.lookedUpFor = key;
 			this.boneObj = null;
 			const source = this.getNodeOrNull(this.target);
+			this.source = source;
 			if (source && typeof source.findBone === "function") this.boneObj = source.findBone(this.bone);
 		}
 		const boneObj = this.boneObj;
-		if (!boneObj) return;
+		if (!boneObj) {
+			this.reportMissingBone();
+			return;
+		}
 		const obj = this._ensureObject3D();
 		const parent = obj.parent;
 		if (!parent) return;
@@ -2339,6 +2379,28 @@ var BoneAttachment3D = class extends Node3D {
 		this.boneObj = null;
 		super.free();
 	}
+	/** The model this attachment last looked in. */
+	source = null;
+	reportedBone = "";
+	/**
+	* Say when the bone NAME is wrong, without accusing a model that is still
+	* loading.
+	*
+	* The lookup retries every frame on purpose — a GLB mounts async — so the
+	* node can never conclude on its own that the name is bad. But once the model
+	* HAS bones and this one is not among them, it is a typo, and the list that
+	* would fix it is sitting in `boneNames()` right next to `findBone`. Until
+	* now a misspelled bone left the sword at the mount node's authored position
+	* while the character animated away from it, forever, in silence.
+	*/
+	reportMissingBone() {
+		if (this.reportedBone === this.bone) return;
+		const names = this.source?.boneNames?.() ?? [];
+		if (names.length === 0) return;
+		this.reportedBone = this.bone;
+		const shown = names.slice(0, 8).join(", ");
+		diagnose(this.tree?.engine ?? null, "error", `[incanto] ${this.getPath()}: '${this.target}' has no bone '${this.bone}'. It has ${names.length}: [${shown}${names.length > 8 ? ", …" : ""}].`);
+	}
 };
 const offsetScratch = new Matrix4();
 const boneScratch = new Matrix4();
@@ -2506,6 +2568,11 @@ const DRAG_DAMPING = .15;
 const SPRING_K = 1.2;
 const SPRING_DAMPING = .08;
 const FALLING_MAX_VEL = -20;
+/** The schema's own default for an action prop — never a second copy of it. */
+function defaultActionOf(prop) {
+	const schema = CharacterController3D.props[prop];
+	return typeof schema?.default === "string" ? schema.default : "";
+}
 const LOOK_SPEED = .002;
 const RAD2DEG = 180 / Math.PI;
 /** Spring-arm camera collision: keep the camera this far in front of an obstacle. */
@@ -2706,8 +2773,10 @@ var CharacterController3D = class extends Node3D {
 			const len = Math.hypot(dir[0], dir[2]) || 1;
 			mx = dir[0] / len;
 			mz = dir[2] / len;
-		} catch {}
-		const sprinting = safePressed(input, this.sprintAction);
+		} catch (error) {
+			this.reportMissingAction("moveAction", error, "The character will not move.");
+		}
+		const sprinting = this.readAction("sprintAction", () => input.isPressed(this.sprintAction), false, "Sprint will never engage.");
 		const intensity = keyboardIntensity(moving, sprinting);
 		const speedMultiplier = 1 + (this.sprintMultiplier - 1) * intensity;
 		const targetSpeed = moving ? this.maxSpeed * speedMultiplier : 0;
@@ -2741,7 +2810,7 @@ var CharacterController3D = class extends Node3D {
 			this.coyoteLeft = Math.max(0, this.coyoteLeft - dt);
 			if (!this.grounded && this.coyoteLeft <= 0 && this.jumpsUsed === 0) this.jumpsUsed = 1;
 		}
-		const pressedJump = safeJustPressed(input, this.jumpAction);
+		const pressedJump = this.readAction("jumpAction", () => input.justPressed(this.jumpAction), false, "The character will never jump.");
 		if (pressedJump) this.bufferLeft = Math.max(this.jumpBufferSeconds, 0);
 		else this.bufferLeft = Math.max(0, this.bufferLeft - dt);
 		if ((this.bufferLeft > 0 || pressedJump) && (footed || this.coyoteLeft > 0 || this.jumpsUsed < this.maxJumps)) {
@@ -2761,7 +2830,7 @@ var CharacterController3D = class extends Node3D {
 		}
 		if (this.rising) {
 			if ((vel[1] ?? 0) <= 0) this.rising = false;
-			else if (this.jumpCutMultiplier < 1 && !safePressed(input, this.jumpAction)) {
+			else if (this.jumpCutMultiplier < 1 && !this.readAction("jumpAction", () => input.isPressed(this.jumpAction), false, "The character will never jump.")) {
 				const cut = (vel[1] ?? 0) * this.jumpCutMultiplier;
 				body.linearVelocity = [
 					vel[0],
@@ -2806,6 +2875,31 @@ var CharacterController3D = class extends Node3D {
 			}
 		}
 	}
+	/** Actions already reported missing, so a per-frame read says it once. */
+	reportedActions = /* @__PURE__ */ new Set();
+	/**
+	* Read an input action this controller is allowed to be missing.
+	*
+	* Tolerated because a game may declare no sprint key and no jump; reported
+	* because otherwise a TYPO looks exactly like a deliberate omission, and the
+	* engine has already thrown the sentence that fixes it.
+	*/
+	readAction(prop, read, fallback, consequence) {
+		const action = this[prop];
+		return tolerateUnknownAction({
+			engine: this.tree?.engine,
+			who: this.getPath(),
+			reported: this.reportedActions,
+			consequence,
+			authored: action !== defaultActionOf(prop)
+		}, action, read, fallback);
+	}
+	/** Report a throw the caller already caught (the move read has its own try). */
+	reportMissingAction(prop, error, consequence) {
+		this.readAction(prop, () => {
+			throw error;
+		}, void 0, consequence);
+	}
 	update(dt) {
 		const input = this.tree?.engine?.input;
 		if (!input) return;
@@ -2921,28 +3015,14 @@ function worldOf(node) {
 		z
 	];
 }
-function safePressed(input, action) {
-	try {
-		return input.isPressed(action);
-	} catch {
-		return false;
-	}
-}
 /**
 * The EDGE, not the level.
 *
 * Jump used to read `isPressed`, so holding the button re-jumped on every frame
 * the raycast found ground — an auto-hop nobody asked for, and one that makes
 * coyote time incoherent (a held button would re-fire through the whole
-* window). Same undeclared-action tolerance as `safePressed`.
+* window). Undeclared actions are tolerated, and reported once.
 */
-function safeJustPressed(input, action) {
-	try {
-		return input.justPressed(action);
-	} catch {
-		return false;
-	}
-}
 //#endregion
 //#region src/3d/vegetation/grass-placement.ts
 const NOISE_SCALE = .15;
@@ -3668,6 +3748,7 @@ var Flowers3D = class extends Node3D {
 			this.height,
 			this.clustering,
 			this.drape,
+			this.avoidWater,
 			this.terrain
 		]);
 		if (key === this.fieldKey) return;
@@ -5222,6 +5303,7 @@ var Foliage3D = class Foliage3D extends Node3D {
 			this.colorA,
 			this.colorB,
 			this.coverage,
+			this.avoidWater,
 			this.flowers,
 			this.seed,
 			this.drape,