incanto 0.67.0 → 0.69.0

package/dist/{loader-KZESOZmE.js → loader-DZE7B07H.js}

@@ -1087,6 +1087,10 @@ var InputMap = class {
 	injectedDown = /* @__PURE__ */ new Set();
 	injectedPressed = /* @__PURE__ */ new Set();
 	injectedReleased = /* @__PURE__ */ new Set();
+	injectedPressedNext = /* @__PURE__ */ new Set();
+	injectedReleasedNext = /* @__PURE__ */ new Set();
+	/** True between the start of a frame's update pass and `endFrame()`. */
+	inFrame = false;
 	injectedVectors = /* @__PURE__ */ new Map();
 	/**
 	* Press a button ACTION directly — no key codes involved. This is how
@@ -1112,13 +1116,13 @@ var InputMap = class {
 		this.button(action);
 		if (!this.injectedDown.has(action)) {
 			this.injectedDown.add(action);
-			this.injectedPressed.add(action);
+			(this.inFrame ? this.injectedPressedNext : this.injectedPressed).add(action);
 		}
 	}
 	/** Release an injected button action (yields one justReleased frame). */
 	releaseAction(action) {
 		this.button(action);
-		if (this.injectedDown.delete(action)) this.injectedReleased.add(action);
+		if (this.injectedDown.delete(action)) (this.inFrame ? this.injectedReleasedNext : this.injectedReleased).add(action);
 	}
 	/**
 	* Feed an analog direction for a vector2 ACTION — virtual joysticks and
@@ -1152,6 +1156,8 @@ var InputMap = class {
 		this.injectedDown.clear();
 		this.injectedPressed.clear();
 		this.injectedReleased.clear();
+		this.injectedPressedNext.clear();
+		this.injectedReleasedNext.clear();
 		this.injectedVectors.clear();
 	}
 	dx = 0;
@@ -1448,6 +1454,16 @@ var InputMap = class {
 		this.releasedEdge.clear();
 		this.injectedPressed.clear();
 		this.injectedReleased.clear();
+		for (const a of this.injectedPressedNext) this.injectedPressed.add(a);
+		for (const a of this.injectedReleasedNext) this.injectedReleased.add(a);
+		this.injectedPressedNext.clear();
+		this.injectedReleasedNext.clear();
+		this.inFrame = false;
+	}
+	/** @internal The engine marks the update phase, so an edge injected inside
+	*  it can be held for the next frame. */
+	beginFrame() {
+		this.inFrame = true;
 	}
 	/**
 	* Drop all action declarations and injected action state (physical key
@@ -1570,10 +1586,16 @@ function effectiveOrder(group, renderOrder, table = ORDER_GROUP_BASE) {
 //#endregion
 //#region src/core/save.ts
 const memoryStores = /* @__PURE__ */ new Map();
+/** Namespaces already warned about, so a per-frame save cannot spam the console. */
+const warnedVolatile = /* @__PURE__ */ new Set();
 function createSaveStore(namespace) {
 	const prefix = `incanto:${namespace}:`;
 	const local = storageOrNull();
 	if (!local) {
+		if (typeof localStorage !== "undefined" && !warnedVolatile.has(namespace)) {
+			warnedVolatile.add(namespace);
+			console.warn(`[incanto] this browser refused localStorage, so saves for '${namespace}' live in memory and are lost when the page closes (private window, storage disabled, or quota exhausted). Check \`store.persistent\` and tell the player.`);
+		}
 		let mem = memoryStores.get(namespace);
 		if (!mem) {
 			mem = /* @__PURE__ */ new Map();
@@ -1581,6 +1603,7 @@ function createSaveStore(namespace) {
 		}
 		const backing = mem;
 		return {
+			persistent: false,
 			get: (key, fallback) => parse(backing.get(key), fallback),
 			set: (key, value) => void backing.set(key, JSON.stringify(value)),
 			remove: (key) => void backing.delete(key),
@@ -1588,6 +1611,7 @@ function createSaveStore(namespace) {
 		};
 	}
 	return {
+		persistent: true,
 		get: (key, fallback) => parse(local.getItem(prefix + key) ?? void 0, fallback),
 		set: (key, value) => local.setItem(prefix + key, JSON.stringify(value)),
 		remove: (key) => local.removeItem(prefix + key),
@@ -1834,6 +1858,17 @@ var SaveSlots = class {
 	constructor(namespace = "saves", store) {
 		this.store = store ?? createSaveStore(namespace);
 	}
+	/**
+	* Will these slots survive the page closing?
+	*
+	* `false` in a private window, with storage disabled, or headless — every
+	* write still succeeds and every read still answers, for as long as the tab
+	* lives. A load menu should say so instead of offering a slot that will not
+	* be there tomorrow.
+	*/
+	get persistent() {
+		return this.store.persistent !== false;
+	}
 	/** Slot ids that have a save, newest first. */
 	list() {
 		const rows = this.store.get(INDEX_KEY, []).map((id) => ({
@@ -2850,6 +2885,8 @@ var Scene = class {
 	orderGroups;
 	/** Physics config (gravity etc. — interpreted by the physics modules). */
 	physics;
+	/** Declared piece of another scene — see `SceneJson.fragment`. */
+	fragment;
 	/** Multiplayer config (room etc. — interpreted by incanto/net). */
 	multiplayer;
 	/** Design-resolution viewport (consumed by renderers via resolveViewport). */
@@ -2869,6 +2906,7 @@ var Scene = class {
 		this.orderGroups = source.orderGroups ? { ...source.orderGroups } : void 0;
 		this.strings = source.strings ? jsonClone(source.strings) : void 0;
 		this.physics = source.physics ? jsonClone(source.physics) : void 0;
+		this.fragment = source.fragment === true ? true : void 0;
 		this.multiplayer = source.multiplayer ? jsonClone(source.multiplayer) : void 0;
 		this.environment = source.environment ? jsonClone(source.environment) : void 0;
 		this.viewport = source.viewport ? jsonClone(source.viewport) : void 0;
@@ -2887,6 +2925,7 @@ var Scene = class {
 			...this.orderGroups ? { orderGroups: { ...this.orderGroups } } : {},
 			...this.strings ? { strings: jsonClone(this.strings) } : {},
 			...this.physics ? { physics: jsonClone(this.physics) } : {},
+			...this.fragment ? { fragment: true } : {},
 			...this.multiplayer ? { multiplayer: jsonClone(this.multiplayer) } : {},
 			...this.environment ? { environment: jsonClone(this.environment) } : {},
 			...this.viewport ? { viewport: jsonClone(this.viewport) } : {},
@@ -3063,6 +3102,7 @@ function validateHeader(json) {
 	if (json.format !== 1) throw new IncantoError("BAD_FORMAT", `Unsupported scene format ${JSON.stringify(json.format)}; this engine reads format 1.`);
 	if (json.type !== "scene") throw new IncantoError("BAD_FORMAT", `Expected "type": "scene", got ${JSON.stringify(json.type)}.`);
 	if (typeof json.name !== "string" || json.name === "") throw new IncantoError("BAD_FORMAT", "Scene \"name\" must be a non-empty string.");
+	if (json.fragment !== void 0 && typeof json.fragment !== "boolean") throw new IncantoError("BAD_FORMAT", `Scene "fragment" must be true or false, got ${JSON.stringify(json.fragment)}.`);
 	if (json.dimension !== void 0 && json.dimension !== "2d" && json.dimension !== "3d") throw new IncantoError("BAD_FORMAT", `Scene "dimension" must be "2d" or "3d", got ${JSON.stringify(json.dimension)}.`);
 	if (typeof json.root !== "object" || json.root === null) throw new IncantoError("BAD_FORMAT", "Scene \"root\" must be a node object.");
 	resolveViewport(json.viewport);
@@ -3154,10 +3194,11 @@ const SCENE_KEYS = [
 	"environment",
 	"strings",
 	"physics",
+	"fragment",
 	"root",
 	"connections"
 ];
-/** Closest known key by edit distance — only a genuinely близкая one. */
+/** Closest known key by edit distance — only a genuinely near one. */
 function nearestKey(key, known) {
 	const lower = key.toLowerCase();
 	let best = null;
@@ -3196,7 +3237,7 @@ function buildNode(nj, opts, stack, parentPath, constants, bands = []) {
 		if (nj.instance !== void 0) return buildInstance(nj, opts, stack, path, constants, bands);
 		if (nj.type === void 0) throw new IncantoError("BAD_FORMAT", `Node '${nj.name}' must declare either "type" or "instance".`);
 		const node = createNode(nj.type, resolveConstants(nj.props, constants), { orderGroup: bands });
-		applyCommon(node, nj, opts);
+		applyCommon(node, nj, opts, constants);
 		node.constructor.validateJson?.(node);
 		for (const childJson of nj.children ?? []) node.addChild(buildNode(childJson, opts, stack, path, constants, bands));
 		return node;
@@ -3222,7 +3263,7 @@ function buildInstance(nj, opts, stack, path, constants, bands) {
 		...nj,
 		type: void 0,
 		props: void 0
-	}, opts);
+	}, opts, constants);
 	for (const childJson of nj.children ?? []) node.addChild(buildNode(childJson, opts, stack, path, constants, bands));
 	wireConnections(node, sub.connections ?? [], opts?.declareConnectionSignals);
 	return node;
@@ -3235,7 +3276,7 @@ function parentOf(path) {
 function propsFor(node) {
 	return mergeStaticProps(node.constructor);
 }
-function applyCommon(node, nj, opts) {
+function applyCommon(node, nj, opts, constants) {
 	if (typeof nj.uid === "string" && nj.uid !== "") node.uid = nj.uid;
 	node.name = nj.name;
 	for (const g of nj.groups ?? []) node.addToGroup(g);
@@ -3244,7 +3285,7 @@ function applyCommon(node, nj, opts) {
 		node.script = jsonClone(nj.script);
 		const name = nj.script.name;
 		if (typeof name !== "string" || name === "") throw new IncantoError("BAD_FORMAT", `Node '${nj.name}': "script" needs a non-empty "name" (a registered behavior).`);
-		const behavior = opts?.stubAllBehaviors || opts?.stubMissingBehaviors && !hasBehavior(name) ? new class extends StubBehavior {}() : createBehavior(name, nj.script.props);
+		const behavior = opts?.stubAllBehaviors || opts?.stubMissingBehaviors && !hasBehavior(name) ? new class extends StubBehavior {}() : createBehavior(name, resolveConstants(nj.script.props, constants));
 		behavior.node = node;
 		node.behavior = behavior;
 		for (const s of mergeStaticSignals(behavior.constructor)) node.declareSignal(s);

package/dist/{loader-DyT30ArB.d.ts → loader-DadV2QCT.d.ts}

@@ -1,5 +1,5 @@
-import { P as Scene, b as Engine } from "./behavior-ZnfzKDo3.js";
-import { i as SceneJson } from "./schema-CFeioQRE.js";
+import { P as Scene, b as Engine } from "./behavior-rm8vVzu_.js";
+import { i as SceneJson } from "./schema-B6ugCV1Q.js";
 
 //#region src/core/scene/loader.d.ts
 interface LoadSceneOptions {

package/dist/net.d.ts

@@ -1,5 +1,5 @@
-import { d as PropSchema, jt as Node } from "./behavior-ZnfzKDo3.js";
-import { a as NetworkManagerOptions, c as LocalGameServer, d as ServerClass, f as createLocalGameServer, g as Unsubscribe, h as NetworkTransport, i as NetworkManager, l as LocalGameServerOptions, m as LoopbackTransport, n as SplitScreenPlayer, o as applySyncPatch, p as LoopbackHub, r as createSplitScreen, s as CollectionOptions, t as SplitScreenOptions, u as LocalGameServerTransport } from "./split-screen-DD5eYIgW.js";
+import { d as PropSchema, jt as Node } from "./behavior-rm8vVzu_.js";
+import { a as NetworkManagerOptions, c as LocalGameServer, d as ServerClass, f as createLocalGameServer, g as Unsubscribe, h as NetworkTransport, i as NetworkManager, l as LocalGameServerOptions, m as LoopbackTransport, n as SplitScreenPlayer, o as applySyncPatch, p as LoopbackHub, r as createSplitScreen, s as CollectionOptions, t as SplitScreenOptions, u as LocalGameServerTransport } from "./split-screen-Cg76MCV5.js";
 
 //#region src/net/agent8.d.ts
 /**

package/dist/net.js

@@ -1,3 +1,3 @@
 import { n as createAgent8Server } from "./agent8-CvsfVskX.js";
-import { a as NetworkManager, d as createLocalGameServer, f as LoopbackHub, l as LocalGameServer, n as registerNodesNet, o as applySyncPatch, p as LoopbackTransport, r as NetworkSpawner, t as createSplitScreen, u as LocalGameServerTransport } from "./split-screen-DS8RaUV_.js";
+import { a as NetworkManager, d as createLocalGameServer, f as LoopbackHub, l as LocalGameServer, n as registerNodesNet, o as applySyncPatch, p as LoopbackTransport, r as NetworkSpawner, t as createSplitScreen, u as LocalGameServerTransport } from "./split-screen-CauMwu6y.js";
 export { LocalGameServer, LocalGameServerTransport, LoopbackHub, LoopbackTransport, NetworkManager, NetworkSpawner, applySyncPatch, createAgent8Server, createLocalGameServer, createSplitScreen, registerNodesNet };

package/dist/{physics-2d-_B6zj3zU.js → physics-2d-CF5yyjbj.js}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { k as diagnose } from "./loader-KZESOZmE.js";
+import { k as diagnose } from "./loader-DZE7B07H.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-vIxU3Xbv.js";
+import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-DbVArsns.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 import { n as jointContacts, t as withoutRapierInitNoise } from "./quiet-rapier-C6fW4zcW.js";
 //#region src/2d/physics/physics-2d.ts

package/dist/{physics-3d-i1IeAY0F.js → physics-3d-DbYaEcZy.js}

@@ -1,10 +1,10 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { k as diagnose } from "./loader-KZESOZmE.js";
+import { k as diagnose } from "./loader-DZE7B07H.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { H as CharacterBody3D, K as Node3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, q as validateCollider3D } from "./gameplay-CGSv-9XR.js";
+import { H as CharacterBody3D, K as Node3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, q as validateCollider3D } from "./gameplay-D1KixWK8.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 import { n as jointContacts, t as withoutRapierInitNoise } from "./quiet-rapier-C6fW4zcW.js";
-import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-C-5g2pMh.js";
+import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-BO-7XoFV.js";
 import { Euler, Matrix4, Quaternion, Vector3 } from "three";
 //#region src/3d/physics/collider-lines.ts
 /**

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { P as Scene, b as Engine, n as BehaviorCtor } from "./behavior-ZnfzKDo3.js";
-import { c as JsonValue } from "./schema-CFeioQRE.js";
+import { P as Scene, b as Engine, n as BehaviorCtor } from "./behavior-rm8vVzu_.js";
+import { c as JsonValue } from "./schema-B6ugCV1Q.js";
 import { CSSProperties, ReactNode } from "react";
 
 //#region src/react/index.d.ts

package/dist/react.js

@@ -156,7 +156,7 @@ function IncantoCanvas(props) {
 				pointer: latest.pointer,
 				...keyboard !== void 0 ? { keyboard } : {}
 			};
-			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-FAXdHta3.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-DMetd3vR.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-CvJ1wSRP.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CwxEDlCm.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;

package/dist/{register-vIxU3Xbv.js → register-DbVArsns.js}

@@ -1,11 +1,11 @@
-import { O as Node, k as diagnose, w as effectiveOrder } from "./loader-KZESOZmE.js";
-import { L as translateOn, t as registerCoreNodes } from "./register-Cs53CY7s.js";
+import { O as Node, k as diagnose, w as effectiveOrder } from "./loader-DZE7B07H.js";
+import { L as translateOn, t as registerCoreNodes } from "./register-mmfugpaQ.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-CF70EArN.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-CY-mrr1L.js";
-import { F as localFromWorld, I as worldPosition } from "./gameplay-CGSv-9XR.js";
-import { t as checkSheetGrid } from "./sheet-grid-BT6N_Bjs.js";
+import { F as localFromWorld, I as worldPosition } from "./gameplay-D1KixWK8.js";
+import { t as checkSheetGrid } from "./sheet-grid-Cea343VO.js";
 import { AdditiveBlending, BufferAttribute, BufferGeometry, CanvasTexture, Color, DynamicDrawUsage, Group, InstancedMesh, MathUtils, Matrix4, Mesh, MeshBasicMaterial, NearestFilter, NormalBlending, Object3D, PlaneGeometry, SRGBColorSpace } from "three";
 //#region src/2d/physics/collider-validate.ts
 /**
@@ -1443,9 +1443,11 @@ var TileMap2D = class extends Node2D {
 	_solid = [];
 	/** Rebuild flags — raised when the map-shaping props are REPLACED. */
 	geometryDirty = true;
-	/** 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. */
 	gridChecked = "";
 	collidersDirty = true;
+	/** The `scale` the colliders were last built for — see `rebuildColliders`. */
+	builtScale = [1, 1];
 	/** Replace the whole array to change the map (mutations are not watched). */
 	get cells() {
 		return this._cells;
@@ -1487,19 +1489,23 @@ var TileMap2D = class extends Node2D {
 		this.rebuildColliders();
 	}
 	update(_dt) {
+		const [sx = 1, sy = 1] = this.scale;
+		if (sx !== this.builtScale[0] || sy !== this.builtScale[1]) this.collidersDirty = true;
 		if (this.collidersDirty) this.rebuildColliders();
 	}
 	rebuildColliders() {
 		this.collidersDirty = false;
 		for (const child of [...this.children]) if (child.name.startsWith("__tileSolid")) child.free();
+		this.builtScale = [this.scale[0] ?? 1, this.scale[1] ?? 1];
 		if (this._solid.length === 0) return;
 		const ts = this.tileSize;
+		const [sx, sy] = this.builtScale;
 		mergeSolidRects(this.grid(), new Set(this._solid)).forEach((r, i) => {
 			const body = new StaticBody2D(`__tileSolid${i}`);
-			body.position = [(r.x + r.w / 2) * ts, (r.y + r.h / 2) * ts];
+			body.position = [(r.x + r.w / 2) * ts * sx, (r.y + r.h / 2) * ts * sy];
 			body.collider = {
 				shape: "rect",
-				size: [r.w * ts, r.h * ts]
+				size: [r.w * ts * sx, r.h * ts * sy]
 			};
 			this.addChild(body);
 		});
@@ -1543,9 +1549,12 @@ var TileMap2D = class extends Node2D {
 			mat.needsUpdate = true;
 			this.geometryDirty = true;
 		}
-		if (this.gridChecked !== this.texture) {
-			this.gridChecked = this.texture;
-			const problem = checkSheetGrid(this.texture, this.tileSize, this.tileSize, image.width, image.height);
+		let highestAsked = -1;
+		for (const row of this.grid()) for (const tile of row) if (tile > highestAsked) highestAsked = tile;
+		const checkKey = `${this.texture}|${highestAsked}`;
+		if (this.gridChecked !== checkKey) {
+			this.gridChecked = checkKey;
+			const problem = checkSheetGrid(this.texture, this.tileSize, this.tileSize, image.width, image.height, highestAsked >= 0 ? highestAsked : void 0, "tile");
 			if (problem) diagnose(this.tree?.engine ?? null, "error", problem);
 		}
 		const columns = this.columns > 0 ? this.columns : Math.max(1, Math.floor(image.width / this.tileSize));

package/dist/{register-Cs53CY7s.js → register-mmfugpaQ.js}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { C as ORDER_GROUP_BASE, E as InputMap, O as Node, S as createSaveStore, T as resolveOrderGroups, V as Signal, b as restoreBehaviors, k as diagnose, y as captureBehaviors } from "./loader-KZESOZmE.js";
+import { C as ORDER_GROUP_BASE, E as InputMap, O as Node, S as createSaveStore, T as resolveOrderGroups, V as Signal, b as restoreBehaviors, k as diagnose, y as captureBehaviors } from "./loader-DZE7B07H.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { l as registerNode } from "./registry-CF70EArN.js";
@@ -179,6 +179,11 @@ var WebAudioTrack = class {
 	setLoop(loop) {
 		this.el.loop = loop;
 	}
+	/** The element's own playhead — the clock the sound is actually on. */
+	playhead() {
+		const at = this.el.currentTime;
+		return typeof at === "number" && Number.isFinite(at) ? at : null;
+	}
 	play() {
 		this.el.play().catch((error) => {
 			const name = error?.name ?? "";
@@ -243,7 +248,8 @@ const SILENT_BACKEND = {
 		setGain() {},
 		setLoop() {},
 		play() {},
-		stop() {}
+		stop() {},
+		playhead: () => null
 	}),
 	unlock() {}
 };
@@ -283,6 +289,24 @@ var MusicManager = class {
 	get current() {
 		return this.active?.track.src ?? null;
 	}
+	/**
+	* Seconds into the current track — the playhead of the thing you can HEAR.
+	*
+	* `null` when nothing is playing, or when the backend has no clock (headless,
+	* or a custom backend that does not implement it).
+	*
+	* A game charted to a soundtrack needs this and there was no way to get it:
+	* `current` gave the src and the backend was private, so the only option was
+	* an `engine.time` counter started next to `music.play()` — a different clock
+	* from the one the audio is on, and one that keeps counting through a
+	* gesture-block, a stall or a seek. This is the audio's own answer.
+	*
+	* It is the RAW element time, so a looping track wraps to 0 at each pass:
+	* that is a loop boundary you can chart against, not a fault.
+	*/
+	get playhead() {
+		return this.active?.track.playhead?.() ?? null;
+	}
 	/** Per-manager volume (0..1), on top of the bus gain. */
 	get volume() {
 		return this._volume;
@@ -1036,6 +1060,16 @@ var SfxEngine = class {
 		if (ctx && ctx.state === "suspended") ctx.resume();
 	}
 	/**
+	* The AUDIO clock, in seconds — the one a sound is actually scheduled
+	* against, and the only clock that does not drift relative to what you hear.
+	*
+	* `0` headless and before the first sound, since there is no context yet.
+	* Schedule with a lead: `sfx.play(params, 1, { when: sfx.now + 0.08 })`.
+	*/
+	get now() {
+		return this.ctx?.currentTime ?? 0;
+	}
+	/**
 	* Play a preset at `gain` (0..1, already bus-multiplied by the caller). Each
 	* call spawns its own source so rapid repeats overlap instead of cutting off.
 	* Headless → no-op.
@@ -1077,7 +1111,7 @@ var SfxEngine = class {
 		const source = ctx.createBufferSource();
 		source.buffer = buffer;
 		source.connect(gainNode);
-		source.start();
+		source.start(opts.when === void 0 ? 0 : Math.max(0, opts.when));
 	}
 };
 //#endregion
@@ -1997,6 +2031,25 @@ var FrameStatsRing = class {
 		const span = this.spanMs();
 		return span > 0 ? span / (this.count - 1) : 0;
 	}
+	/**
+	* How long ago the newest sample arrived, in ms. `null` with no samples.
+	*
+	* `fps()` is a rate over a WINDOW, so it keeps answering after the frames
+	* stop: a hidden tab, a descheduled loop, a page the browser froze. Measured
+	* on an engine that ticked 40 times and then stopped being ticked:
+	*
+	*   while ticking      : fps 59.9
+	*   after 0 more ticks : fps 59.9      <- the last sample is 668 ms old
+	*
+	* Both numbers are true about the window they describe. What was missing was
+	* any way to ask WHEN that window was, so "60 fps" read the same whether it
+	* was measured 8 ms ago or four seconds ago.
+	*/
+	ageMs(nowMs) {
+		if (this.count === 0) return null;
+		const newest = this.times[(this.head + this.count - 1) % this.capacity];
+		return Math.max(0, nowMs - newest);
+	}
 	/** Forget all samples (engine.stop() — a paused game has no frame rate). */
 	clear() {
 		this.head = 0;
@@ -2399,6 +2452,49 @@ var Engine = class {
 	* learns about Rapier or three. From a behavior, prefer `this.physics`.
 	*/
 	physics = null;
+	/**
+	* How to build a physics world for a scene that needs one.
+	*
+	* `createGame2D`/`createGame3D` install this; core never learns what Rapier
+	* is. It exists because `physics: 'auto'` can only look at the scene the game
+	* BOOTED with, and the most universal act of finishing a game is putting a
+	* title screen in front of it:
+	*
+	* ```
+	* after boot on the title  : engine.physics = null
+	* after goToScene into game: engine.physics = null
+	* player y after 2 s       : 0 -> 0
+	* ```
+	*
+	* The game rendered perfectly and was inert — nothing fell, nothing collided,
+	* nothing could be collected or hurt. One scene swap turned a working game
+	* into a diorama, and nothing was logged.
+	*/
+	physicsProvider = null;
+	ensuring = null;
+	/**
+	* Give the current scene a physics world if it needs one and has none.
+	*
+	* Idempotent and safe to call on every swap: the provider decides whether the
+	* incoming tree actually wants physics, and an explicit `physics: false` at
+	* boot installs no provider at all, so opting out stays opted out.
+	*
+	* Asynchronous because the Rapier WASM has to load. The first frames after a
+	* swap therefore run unsimulated — which every AI behaviour already tolerates
+	* (`moveBody` falls back to a direct write when `_physics` is null) and which
+	* is a hitch, where the alternative was a game that never simulated at all.
+	*/
+	ensurePhysics() {
+		if (this.physics || !this.physicsProvider || !this._scene) return Promise.resolve();
+		if (this.ensuring) return this.ensuring;
+		const root = this._scene.root;
+		this.ensuring = this.physicsProvider(root).catch((e) => {
+			this.log.error(`[incanto] could not enable physics for this scene: ${String(e?.message ?? e)}`);
+		}).finally(() => {
+			this.ensuring = null;
+		});
+		return this.ensuring;
+	}
 	/** Seeded randomness for game logic (deterministic when `seed` is set). */
 	rng;
 	/** The engine log channel (debug overlay + headless harness tail this). */
@@ -2722,6 +2818,7 @@ var Engine = class {
 		return {
 			fps: this.frameStats.fps(),
 			frameMs: this.frameStats.frameMs(),
+			lastFrameAgeMs: this.frameStats.ageMs(performance.now()),
 			nodes: this._scene?.tree.root ? countNodes(this._scene.tree.root) : 0,
 			running: this.disposeScheduler !== null,
 			errors: this.errorCount,
@@ -2774,6 +2871,7 @@ var Engine = class {
 		this._time += dt;
 		this._unscaledTime += this.fixedStep;
 		const startedFixed = performance.now();
+		this.input.beginFrame();
 		scene.tree.fixedUpdate(dt);
 		this.fixedUpdated.emit(dt);
 		const startedUpdate = performance.now();
@@ -2801,6 +2899,7 @@ var Engine = class {
 		this.lastMs = nowMs;
 		const scene = this._scene;
 		if (!scene) return;
+		this.input.beginFrame();
 		this.accumulator += dt;
 		let steps = 0;
 		const startedFixed = performance.now();
@@ -2973,7 +3072,8 @@ var AudioPlayer = class extends Node {
 			name,
 			from: this.getPath(),
 			bus: this.bus === "music" ? "music" : "sfx",
-			at: engine.time
+			at: engine.time,
+			...this.loop ? { loop: true } : {}
 		});
 	}
 	/** Final gain = engine buses × this volume (1 when not in a tree). */
@@ -3005,6 +3105,54 @@ var AudioPlayer = class extends Node {
 			rolloff: this.rolloff
 		};
 	}
+	/**
+	* 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 given a scheduled start. Queue them a lead
+	* ahead and the same notes land at |mean| 0.000000 ms:
+	*
+	* ```ts
+	* 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, 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.
+	*/
+	playAt(when) {
+		if (this.preset !== "custom") {
+			this.note("preset", this.preset);
+			this.playPreset(Number.isFinite(when) ? when : void 0);
+			return;
+		}
+		this.play();
+	}
 	play() {
 		if (this.preset !== "custom") {
 			this.note("preset", this.preset);
@@ -3052,7 +3200,7 @@ var AudioPlayer = class extends Node {
 	* the length is arithmetic, not a device. WebAudio needs a gesture; a
 	* suspended context is resumed by the same unlock listener as `src` players.
 	*/
-	playPreset() {
+	playPreset(at) {
 		const params = SFX_PRESETS[this.preset];
 		if (!params) return;
 		const engine = this.tree?.engine;
@@ -3063,7 +3211,8 @@ var AudioPlayer = class extends Node {
 		sfx.play(params, this.gain(), {
 			pitch: this.pitch,
 			seed: this.seed,
-			spatial: this.spatialPlay()
+			spatial: this.spatialPlay(),
+			when: at
 		});
 	}
 	/**
@@ -3099,6 +3248,10 @@ var AudioPlayer = class extends Node {
 		}
 		if (this.presetEndsAt !== null) {
 			if ((this.tree?.engine?.unscaledTime ?? 0) >= this.presetEndsAt) {
+				if (this.loop) {
+					this.playPreset();
+					return;
+				}
 				this.presetEndsAt = null;
 				this._playing = false;
 				this.emit("finished");

package/dist/{replay-BkpDV51O.js → replay-BEHLDcQV.js}

@@ -1,5 +1,5 @@
-import { D as handlerShadowWarnings, j as nodeRefWarnings } from "./loader-KZESOZmE.js";
-import { R as translationKey, k as HudWidgetBase } from "./register-Cs53CY7s.js";
+import { D as handlerShadowWarnings, j as nodeRefWarnings } from "./loader-DZE7B07H.js";
+import { R as translationKey, k as HudWidgetBase } from "./register-mmfugpaQ.js";
 import { o as getNodeType } from "./registry-CF70EArN.js";
 //#region src/core/audit.ts
 const ANIMATED_TYPES = new Set([
@@ -104,6 +104,28 @@ function transformOf(props) {
 	if (scaled) return "scale";
 	return null;
 }
+/**
+* Which files in a corpus some OTHER scene embeds with `instance`.
+*
+* A fragment cannot be recognised by looking at itself — `enemy.scene.json` and
+* a broken first level are the same file shape. It is recognised by the project
+* around it, which every tool that audits more than one scene already walks.
+*
+* `resolveRef(fromFile, ref)` turns a scene-relative `instance` path into the
+* same spelling the corpus uses for that file, so the caller owns all path
+* logic and this stays runnable in a browser.
+*/
+function instancedScenes(corpus, resolveRef) {
+	const instanced = /* @__PURE__ */ new Set();
+	const walk = (node, from) => {
+		if (!node || typeof node !== "object") return;
+		const ref = node.instance;
+		if (typeof ref === "string" && ref) instanced.add(resolveRef(from, ref));
+		for (const child of node.children ?? []) walk(child, from);
+	};
+	for (const { path, json } of corpus) walk(json.root, path);
+	return instanced;
+}
 function auditScene(scene, opts = {}) {
 	const warnings = [];
 	const root = scene.root;
@@ -166,8 +188,9 @@ function auditScene(scene, opts = {}) {
 	if (cameraDrivers.length > 0 && followedCameras.length > 0) warnings.push(`${followedCameras.join(", ")}: a FollowCamera writes this camera's position every frame, and so does the CharacterController3D at ${cameraDrivers.join(", ")} — the controller owns the camera in every view it has. Drop one of them: use the controller's own \`view\`/\`camDistance\`, or take the controller off the camera duty.`);
 	if (cameras > 0 && currentCameras === 0) warnings.push("no camera has \"current\": true — the screen renders from a default view, probably not what you framed.");
 	if (currentCameras > 1) warnings.push(`${currentCameras} cameras claim "current": true — only the first found wins.`);
-	const isFragment = cameras === 0;
-	if (scene.dimension === "3d" && !isFragment && lights === 0 && !isLit(scene.environment)) warnings.push("nothing lights this 3D scene — no light node, no environment sky/hdri, and no ambient intensity. It will render black. Add a DirectionalLight3D, or an \"environment\": { \"sky\": { \"type\": \"atmosphere\" } } / { \"preset\": \"...\" }.");
+	const isFragment = opts.instanced === true || scene.fragment === true;
+	if (scene.dimension === "3d" && !isFragment && cameras === 0) warnings.push("this 3D scene has no camera — the screen renders from a default view, which is almost never the shot you want. Add a Camera3D with \"current\": true, or set \"fragment\": true in the scene header if this file is a prefab another scene drops in.");
+	if (scene.dimension === "3d" && !isFragment && lights === 0 && !isLit(scene.environment)) warnings.push("nothing lights this 3D scene — no light node, no environment sky/hdri, and no ambient intensity. It will render black. Add a DirectionalLight3D, or an \"environment\": { \"sky\": { \"type\": \"atmosphere\" } } / { \"preset\": \"...\" } — or set \"fragment\": true if another scene lights this one.");
 	if (damageGroups.length > 0) {
 		const hurtable = hurtableGroups(root);
 		for (const { path, group } of damageGroups) {
@@ -359,4 +382,4 @@ function replay(engine, recording, opts) {
 	}
 }
 //#endregion
-export { startRecording as n, auditScene as r, replay as t };
+export { instancedScenes as i, startRecording as n, auditScene as r, replay as t };