incanto 0.1.0

package/dist/particle-sim-DYuSUxvK.js

@@ -0,0 +1,1319 @@
+import { y as Signal } from "./loader-CGs_G-r0.js";
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { t as Rng } from "./rng-DP-SR7eg.js";
+import { l as synthSfx } from "./register-BuUV1_KB.js";
+import { n as jsonEquals } from "./json-BLk7H2Qa.js";
+//#region src/core/audio/buses.ts
+/**
+* Global volume state — `master` × `sfx`/`music` gain (0..1) plus a `muted`
+* flag. PURE state (no WebAudio): games and AI set it to control overall
+* loudness/mute; the renderer reads `effectiveVolume()` when it actually plays
+* a sound. Lives on the engine as `engine.audio` (instance-scoped, no
+* singletons). The WebAudio wiring is in the adapter; this just holds the
+* numbers so they're fully testable in `node`.
+*
+* ```ts
+* engine.audio.master = 0.8;   // dim everything
+* engine.audio.music = 0.4;    // quieter background music
+* engine.audio.muted = true;   // mute toggle
+* ```
+*/
+var AudioBuses = class {
+	/** Fires whenever any value changes (drives live re-gain of playing sounds). */
+	changed = new Signal();
+	_master = 1;
+	_sfx = 1;
+	_music = 1;
+	_muted = false;
+	get master() {
+		return this._master;
+	}
+	set master(v) {
+		this._master = this.assign(this._master, v);
+	}
+	get sfx() {
+		return this._sfx;
+	}
+	set sfx(v) {
+		this._sfx = this.assign(this._sfx, v);
+	}
+	get music() {
+		return this._music;
+	}
+	set music(v) {
+		this._music = this.assign(this._music, v);
+	}
+	get muted() {
+		return this._muted;
+	}
+	set muted(v) {
+		if (v === this._muted) return;
+		this._muted = v;
+		this.changed.emit();
+	}
+	/** Final gain for a sound on `bus` with its own `sourceVolume` (all clamped). */
+	effectiveVolume(bus, sourceVolume) {
+		if (this._muted) return 0;
+		const busGain = bus === "music" ? this._music : this._sfx;
+		return this._master * busGain * clamp01$2(sourceVolume);
+	}
+	/** Clamp + finite-guard a new value; emit only on a real change. */
+	assign(current, next) {
+		if (!Number.isFinite(next)) return current;
+		const clamped = clamp01$2(next);
+		if (clamped !== current) this.changed.emit();
+		return clamped;
+	}
+};
+function clamp01$2(v) {
+	if (!Number.isFinite(v)) return 0;
+	return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+//#endregion
+//#region src/core/audio/crossfade.ts
+/**
+* PURE crossfade / fade envelope math for the music manager. No WebAudio: just
+* the gain curves over time, so the loudness behaviour is unit-testable in
+* `node` and the headless music state machine can be validated without a backend.
+* The adapter applies these gains to real GainNodes / element volumes each frame.
+*/
+/** Linear 0→1 (`in`) or 1→0 (`out`) over `duration` seconds at elapsed `t`. */
+function fadeGain(t, duration, dir) {
+	const p = progress(t, duration);
+	return dir === "in" ? p : 1 - p;
+}
+/**
+* Equal-power crossfade gains at elapsed `t` over `seconds`. The outgoing track
+* fades cos(¼π·p) and the incoming sin(¼π·p) so `out² + in² ≈ 1` throughout —
+* constant perceived loudness, no mid-fade dip (the classic equal-power law).
+* `p` is `t/seconds` clamped to [0,1]; a zero-second fade swaps instantly.
+*/
+function crossfadeGains(t, seconds) {
+	const angle = progress(t, seconds) * Math.PI / 2;
+	return {
+		out: clamp01$1(Math.cos(angle)),
+		in: clamp01$1(Math.sin(angle))
+	};
+}
+/** Normalized progress 0..1; a non-positive duration is instantly complete. */
+function progress(t, duration) {
+	if (!Number.isFinite(t)) return 1;
+	if (duration <= 0) return 1;
+	return clamp01$1(t / duration);
+}
+function clamp01$1(v) {
+	if (!Number.isFinite(v)) return 0;
+	return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+function resolveCtor$1() {
+	const g = globalThis;
+	return g.AudioContext ?? g.webkitAudioContext ?? null;
+}
+function createContext$1() {
+	const Ctor = resolveCtor$1();
+	return Ctor ? new Ctor() : null;
+}
+function createElement() {
+	if (typeof Audio === "undefined") return null;
+	return new Audio();
+}
+/** A no-op track for the headless / missing-backend path. */
+const INERT = {
+	src: "",
+	setGain() {},
+	setLoop() {},
+	play() {},
+	stop() {}
+};
+var WebAudioTrack = class {
+	src;
+	el;
+	gainNode;
+	constructor(src, el, ctx) {
+		this.src = src;
+		this.el = el;
+		try {
+			el.crossOrigin = "anonymous";
+		} catch {}
+		el.src = src;
+		const source = ctx.createMediaElementSource(el);
+		this.gainNode = ctx.createGain();
+		source.connect(this.gainNode);
+		this.gainNode.connect(ctx.destination);
+	}
+	setGain(gain) {
+		this.gainNode.gain.value = gain;
+	}
+	setLoop(loop) {
+		this.el.loop = loop;
+	}
+	play() {
+		this.el.play().catch(() => {});
+	}
+	stop() {
+		this.el.pause();
+		this.el.currentTime = 0;
+	}
+};
+var WebAudioMusicBackend = class {
+	ctx = null;
+	resolved = false;
+	/** True once a backend is present (lazily created on first use). */
+	get available() {
+		return this.ensure() !== null;
+	}
+	ensure() {
+		if (!this.resolved) {
+			this.ctx = createContext$1();
+			this.resolved = true;
+		}
+		return this.ctx;
+	}
+	createTrack(src) {
+		const ctx = this.ensure();
+		const el = createElement();
+		if (!ctx || !el) return {
+			...INERT,
+			src
+		};
+		if (ctx.state === "suspended") ctx.resume();
+		return new WebAudioTrack(src, el, ctx);
+	}
+	unlock() {
+		const ctx = this.ensure();
+		if (ctx && ctx.state === "suspended") ctx.resume();
+	}
+};
+/**
+* Single-track background-music manager: plays ONE music track, crossfading to
+* a new one (equal-power) or fading in/out. Lives on the engine as
+* `engine.music`; routes through `engine.audio` (the music bus by default) so
+* the global volume/mute sliders dim it for free.
+*
+* The state machine (current/outgoing track, fade phase + timer) is fully
+* testable headlessly via an injected backend; the real backend is WebAudio +
+* HTMLAudio and a no-op when there's no AudioContext. Drive `tick(dt)` once per
+* frame to advance fades (the engine wires this to `updated`).
+*
+* ```ts
+* engine.music.play('incanto/assets/audio/theme.mp3');     // loop, full
+* engine.music.crossfadeTo('boss.mp3', 3);                  // 3s equal-power swap
+* engine.music.stop(2);                                     // fade out over 2s
+* engine.music.setVolume(0.5);                              // per-manager volume
+* ```
+*/
+var MusicManager = class {
+	buses;
+	backend = null;
+	resolved = false;
+	/** The current (incoming) track; an outgoing one lives during a fade. */
+	active = null;
+	outgoing = null;
+	_bus = "music";
+	_volume = 1;
+	constructor(buses) {
+		this.buses = buses;
+	}
+	/** Source of the logically-current track, or null when nothing is playing. */
+	get current() {
+		return this.active?.track.src ?? null;
+	}
+	/** Per-manager volume (0..1), on top of the bus gain. */
+	get volume() {
+		return this._volume;
+	}
+	ensure() {
+		if (!this.resolved) {
+			const b = new WebAudioMusicBackend();
+			this.backend = b && b.available === false ? null : b;
+			this.resolved = true;
+		}
+		return this.backend;
+	}
+	/** Resume a gesture-suspended context + (re)start any pending track. */
+	unlock() {
+		this.ensure()?.unlock();
+		this.active?.track.play();
+	}
+	/** Play a single track (replacing any current one immediately, no fade). */
+	play(src, opts = {}) {
+		const backend = this.ensure();
+		if (!backend) return;
+		this.killOutgoing();
+		this.active?.track.stop();
+		this._bus = opts.bus ?? "music";
+		const track = backend.createTrack(src);
+		track.setLoop(opts.loop ?? true);
+		const fadeIn = Math.max(0, opts.fadeIn ?? 0);
+		this.active = {
+			track,
+			phase: fadeIn > 0 ? "fadeIn" : "steady",
+			t: 0,
+			duration: fadeIn,
+			freeOnEnd: false
+		};
+		track.setGain(fadeIn > 0 ? 0 : this.busGain());
+		track.play();
+	}
+	/**
+	* Equal-power crossfade to a new track over `seconds`. With no current track
+	* it's a fade-in. Crossfading to the already-current src is a no-op.
+	*/
+	crossfadeTo(src, seconds = 2) {
+		const backend = this.ensure();
+		if (!backend) return;
+		if (this.active && this.active.track.src === src && this.active.phase !== "fadeOut") return;
+		const secs = Math.max(0, seconds);
+		if (!this.active) {
+			this.play(src, { fadeIn: secs });
+			return;
+		}
+		this.killOutgoing();
+		this.outgoing = {
+			...this.active,
+			phase: "crossOut",
+			t: 0,
+			duration: secs,
+			freeOnEnd: true
+		};
+		const track = backend.createTrack(src);
+		track.setLoop(true);
+		track.setGain(0);
+		track.play();
+		this.active = {
+			track,
+			phase: "crossIn",
+			t: 0,
+			duration: secs,
+			freeOnEnd: false
+		};
+		this.applyGains();
+	}
+	/** Stop the current track, optionally fading out over `fadeOut` seconds. */
+	stop(fadeOut = 0) {
+		this.killOutgoing();
+		const a = this.active;
+		this.active = null;
+		if (!a) return;
+		const secs = Math.max(0, fadeOut);
+		if (secs <= 0) {
+			a.track.stop();
+			return;
+		}
+		this.outgoing = {
+			...a,
+			phase: "fadeOut",
+			t: 0,
+			duration: secs,
+			freeOnEnd: true
+		};
+		this.applyGains();
+	}
+	/** Set the per-manager volume (re-applied to live tracks on the next tick). */
+	setVolume(v) {
+		this._volume = clamp01(v);
+	}
+	/** Advance fades by `dt` seconds and (re)apply bus×fade gains. Frame-driven. */
+	tick(dt) {
+		if (this.active && (this.active.phase === "fadeIn" || this.active.phase === "crossIn")) {
+			this.active.t += dt;
+			if (this.active.t >= this.active.duration) this.active.phase = "steady";
+		}
+		if (this.outgoing) {
+			this.outgoing.t += dt;
+			if (this.outgoing.t >= this.outgoing.duration) {
+				this.outgoing.track.setGain(0);
+				this.outgoing.track.stop();
+				this.outgoing = null;
+			}
+		}
+		this.applyGains();
+	}
+	/** Effective bus gain for THIS manager (master × bus × manager volume). */
+	busGain() {
+		return this.buses.effectiveVolume(this._bus, this._volume);
+	}
+	/** Push the current fade-derived gains onto both tracks. */
+	applyGains() {
+		const base = this.busGain();
+		if (this.active?.phase === "crossIn" && this.outgoing?.phase === "crossOut") {
+			const g = crossfadeGains(this.active.t, this.active.duration);
+			this.active.track.setGain(base * g.in);
+			this.outgoing.track.setGain(base * g.out);
+			return;
+		}
+		if (this.active) {
+			const g = this.active.phase === "fadeIn" ? fadeGain(this.active.t, this.active.duration, "in") : 1;
+			this.active.track.setGain(base * g);
+		}
+		if (this.outgoing) {
+			const g = this.outgoing.phase === "fadeOut" || this.outgoing.phase === "crossOut" ? fadeGain(this.outgoing.t, this.outgoing.duration, "out") : 0;
+			this.outgoing.track.setGain(base * g);
+		}
+	}
+	killOutgoing() {
+		this.outgoing?.track.stop();
+		this.outgoing = null;
+	}
+};
+function clamp01(v) {
+	if (!Number.isFinite(v)) return 0;
+	return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+//#endregion
+//#region src/core/audio/webaudio-sfx.ts
+/** Position a WebAudio AudioListener from a pose (modern AudioParam or legacy). */
+function applyListenerPose(ctxListener, pose) {
+	const [px, py, pz] = pose.position;
+	const [fx, fy, fz] = pose.forward;
+	const [ux, uy, uz] = pose.up;
+	const l = ctxListener;
+	if (l.positionX && l.forwardX && l.upX) {
+		l.positionX.value = px;
+		if (l.positionY) l.positionY.value = py;
+		if (l.positionZ) l.positionZ.value = pz;
+		l.forwardX.value = fx;
+		if (l.forwardY) l.forwardY.value = fy;
+		if (l.forwardZ) l.forwardZ.value = fz;
+		l.upX.value = ux;
+		if (l.upY) l.upY.value = uy;
+		if (l.upZ) l.upZ.value = uz;
+	} else {
+		l.setPosition?.(px, py, pz);
+		l.setOrientation?.(fx, fy, fz, ux, uy, uz);
+	}
+}
+/** Position a PannerNode at an emitter (modern AudioParam or legacy). */
+function applyPannerPosition(panner, pos) {
+	const p = panner;
+	if (p.positionX) {
+		p.positionX.value = pos[0];
+		if (p.positionY) p.positionY.value = pos[1];
+		if (p.positionZ) p.positionZ.value = pos[2];
+	} else p.setPosition?.(pos[0], pos[1], pos[2]);
+}
+function resolveCtor() {
+	const g = globalThis;
+	return g.AudioContext ?? g.webkitAudioContext ?? null;
+}
+/** True when a real (or injected) AudioContext backend exists. */
+function isAudioContextAvailable() {
+	return resolveCtor() !== null;
+}
+function createContext() {
+	const Ctor = resolveCtor();
+	if (!Ctor) return null;
+	return new Ctor();
+}
+/** Cache key for a synthesized waveform (params identity + variation knobs). */
+function cacheKey(params, opts, sampleRate) {
+	return `${params.wave}|${params.baseFreq}|${params.freqRamp}|${params.attack}|${params.sustain}|${params.decay}|${params.duty}|${params.vibratoDepth}|${params.vibratoRate}|${params.volume}|${opts.pitch ?? 1}|${opts.seed ?? 0}|${sampleRate}`;
+}
+/**
+* One AudioContext + a PCM cache. Instance-scoped (held by the renderer's game
+* instance, not a singleton). `play()` synthesizes (cached) and fires a
+* one-shot source at the given gain.
+*/
+var SfxEngine = class {
+	ctx = null;
+	resolved = false;
+	pcmCache = /* @__PURE__ */ new Map();
+	/** True once a backend is present (lazily created on first use). */
+	get available() {
+		return this.ensure() !== null;
+	}
+	ensure() {
+		if (!this.resolved) {
+			this.ctx = createContext();
+			this.resolved = true;
+		}
+		return this.ctx;
+	}
+	/** Resume a gesture-suspended context (wired to the first user gesture). */
+	unlock() {
+		const ctx = this.ensure();
+		if (ctx && ctx.state === "suspended") ctx.resume();
+	}
+	/**
+	* 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.
+	*/
+	play(params, gain, opts = {}) {
+		const ctx = this.ensure();
+		if (!ctx) return;
+		if (ctx.state === "suspended") ctx.resume();
+		if (gain <= 0) return;
+		const sampleRate = ctx.sampleRate || 44100;
+		const synthOpts = {
+			sampleRate,
+			pitch: opts.pitch,
+			seed: opts.seed
+		};
+		const key = cacheKey(params, synthOpts, sampleRate);
+		let pcm = this.pcmCache.get(key);
+		if (!pcm) {
+			pcm = synthSfx(params, synthOpts);
+			this.pcmCache.set(key, pcm);
+		}
+		const buffer = ctx.createBuffer(1, pcm.length, sampleRate);
+		buffer.getChannelData(0).set(pcm);
+		const gainNode = ctx.createGain();
+		gainNode.gain.value = gain;
+		if (opts.spatial && typeof ctx.createPanner === "function") {
+			const s = opts.spatial;
+			const panner = ctx.createPanner();
+			panner.panningModel = "HRTF";
+			panner.distanceModel = s.rolloff;
+			panner.refDistance = Math.max(0, s.refDistance);
+			panner.maxDistance = Math.max(s.refDistance, s.maxDistance);
+			panner.rolloffFactor = s.rolloffFactor ?? 1;
+			applyPannerPosition(panner, s.position);
+			if (ctx.listener) applyListenerPose(ctx.listener, s.listener);
+			gainNode.connect(panner);
+			panner.connect(ctx.destination);
+		} else gainNode.connect(ctx.destination);
+		const source = ctx.createBufferSource();
+		source.buffer = buffer;
+		source.connect(gainNode);
+		source.start();
+	}
+};
+//#endregion
+//#region src/core/frame-stats.ts
+/**
+* Rolling window of REAL frame timestamps — the math behind `engine.stats()`
+* fps/frameMs. Pure and renderer-free: push tick times in, read averages out.
+*
+* Only `Engine.tick(nowMs)` feeds it; headless `step()` advances sim time
+* without wall-clock frames, so stepped runs honestly report 0 fps.
+*/
+var FrameStatsRing = class {
+	capacity;
+	times;
+	head = 0;
+	count = 0;
+	constructor(capacity = 60) {
+		this.capacity = capacity;
+		this.times = new Array(capacity);
+	}
+	/** Record one frame timestamp (ms). Evicts the oldest at capacity. */
+	push(nowMs) {
+		this.times[(this.head + this.count) % this.capacity] = nowMs;
+		if (this.count < this.capacity) this.count += 1;
+		else this.head = (this.head + 1) % this.capacity;
+	}
+	/** Frames per second over the window — 0 with fewer than two samples. */
+	fps() {
+		const span = this.spanMs();
+		return span > 0 ? (this.count - 1) / span * 1e3 : 0;
+	}
+	/** Mean delta between frames in ms — 0 with fewer than two samples. */
+	frameMs() {
+		const span = this.spanMs();
+		return span > 0 ? span / (this.count - 1) : 0;
+	}
+	/** Forget all samples (engine.stop() — a paused game has no frame rate). */
+	clear() {
+		this.head = 0;
+		this.count = 0;
+	}
+	spanMs() {
+		if (this.count < 2) return 0;
+		const oldest = this.times[this.head];
+		return this.times[(this.head + this.count - 1) % this.capacity] - oldest;
+	}
+};
+//#endregion
+//#region src/core/input.ts
+/** Keys typed into editable elements belong to the page UI, not the game. */
+function isEditableTarget(target) {
+	const el = target;
+	return !!el && (el.isContentEditable === true || el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SELECT");
+}
+/**
+* Declarative input from scene JSON `input{}` — DOM-free logic (feed key state
+* via `handleKey`, or wire a browser with `attachKeyboard(window)`).
+*
+* Convention: vector2 follows the 2D y-down space (up = -y). `justPressed` /
+* `justReleased` are one-frame edges, settled by the Engine each tick.
+*/
+var InputMap = class {
+	actions = /* @__PURE__ */ new Map();
+	down = /* @__PURE__ */ new Set();
+	pressedEdge = /* @__PURE__ */ new Set();
+	releasedEdge = /* @__PURE__ */ new Set();
+	detach = null;
+	/** Load (or extend with) scene-JSON action declarations. Hard-validates shape. */
+	declare(decls) {
+		for (const [name, raw] of Object.entries(decls)) {
+			const decl = raw;
+			if (decl.type === "button") {
+				const keys = decl.keys;
+				if (!Array.isArray(keys) || keys.some((k) => typeof k !== "string")) throw new IncantoError("BAD_FORMAT", `Input action '${name}': button "keys" must be an array of KeyboardEvent.code strings.`);
+				if (decl.touch !== void 0 && decl.touch !== "button") throw new IncantoError("BAD_FORMAT", `Input action '${name}': button "touch" must be 'button', got ${JSON.stringify(decl.touch)}.`);
+				this.actions.set(name, {
+					type: "button",
+					keys: [...keys],
+					...decl.touch === "button" ? { touch: "button" } : {}
+				});
+			} else if (decl.type === "vector2") {
+				const dirs = decl.keys;
+				for (const dir of [
+					"up",
+					"down",
+					"left",
+					"right"
+				]) if (!Array.isArray(dirs?.[dir])) throw new IncantoError("BAD_FORMAT", `Input action '${name}': vector2 "keys" needs arrays for up/down/left/right.`);
+				if (decl.touch !== void 0 && decl.touch !== "joystick") throw new IncantoError("BAD_FORMAT", `Input action '${name}': vector2 "touch" must be 'joystick', got ${JSON.stringify(decl.touch)}.`);
+				const d = dirs;
+				this.actions.set(name, {
+					type: "vector2",
+					keys: {
+						up: [...d.up],
+						down: [...d.down],
+						left: [...d.left],
+						right: [...d.right]
+					},
+					...decl.touch === "joystick" ? { touch: "joystick" } : {}
+				});
+			} else throw new IncantoError("BAD_FORMAT", `Input action '${name}': "type" must be 'button' or 'vector2', got ${JSON.stringify(decl.type)}.`);
+		}
+	}
+	/** Feed a key state change (code = KeyboardEvent.code, e.g. 'Space', 'KeyW'). */
+	handleKey(code, isDown) {
+		if (isDown) {
+			if (!this.down.has(code)) {
+				this.down.add(code);
+				this.pressedEdge.add(code);
+			}
+		} else if (this.down.has(code)) {
+			this.down.delete(code);
+			this.releasedEdge.add(code);
+		}
+	}
+	injectedDown = /* @__PURE__ */ new Set();
+	injectedPressed = /* @__PURE__ */ new Set();
+	injectedReleased = /* @__PURE__ */ new Set();
+	injectedVectors = /* @__PURE__ */ new Map();
+	/**
+	* Press a button ACTION directly — no key codes involved. This is how
+	* scripted gameplay tests and touch buttons drive the game by intent
+	* (`press('jump')`) instead of reverse-engineering keybinds.
+	*/
+	pressAction(action) {
+		this.button(action);
+		if (!this.injectedDown.has(action)) {
+			this.injectedDown.add(action);
+			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);
+	}
+	/**
+	* Feed an analog direction for a vector2 ACTION — virtual joysticks and
+	* scripted runs. Persists until replaced; (0, 0) clears the injection.
+	* Combines with key state in getVector (clamped to unit length).
+	*/
+	setActionVector(action, x, y) {
+		if (this.get(action).type !== "vector2") throw new IncantoError("BAD_FORMAT", `Input action '${action}' is a button — use pressAction/releaseAction, not setActionVector.`);
+		if (!Number.isFinite(x) || !Number.isFinite(y)) throw new IncantoError("BAD_FORMAT", `setActionVector('${action}') needs finite numbers, got (${x}, ${y}).`);
+		if (x === 0 && y === 0) this.injectedVectors.delete(action);
+		else this.injectedVectors.set(action, {
+			x,
+			y
+		});
+	}
+	/**
+	* Actions the scene wants on-screen touch controls for, in declaration
+	* order (`"touch": "joystick"` on vector2, `"touch": "button"` on buttons).
+	* The touch overlay (core/touch.ts) renders these.
+	*/
+	touchControls() {
+		const out = [];
+		for (const [name, def] of this.actions) if (def.touch) out.push({
+			action: name,
+			kind: def.touch
+		});
+		return out;
+	}
+	/** Drop all injected action state (held buttons, vectors, pending edges). */
+	clearInjected() {
+		this.injectedDown.clear();
+		this.injectedPressed.clear();
+		this.injectedReleased.clear();
+		this.injectedVectors.clear();
+	}
+	dx = 0;
+	dy = 0;
+	wheel = 0;
+	/** Mouse buttons feed the same code space as keys: Mouse0/Mouse1/Mouse2. */
+	handleMouseButton(button, isDown) {
+		this.handleKey(`Mouse${button}`, isDown);
+	}
+	/** Accumulate look deltas (movementX/Y under pointer lock, else move deltas). */
+	handlePointerMove(dx, dy) {
+		this.dx += dx;
+		this.dy += dy;
+	}
+	handleWheel(deltaY) {
+		this.wheel += deltaY;
+	}
+	/** Drain the accumulated pointer delta (read once per frame). */
+	pointerDelta() {
+		const d = {
+			x: this.dx,
+			y: this.dy
+		};
+		this.dx = 0;
+		this.dy = 0;
+		return d;
+	}
+	/** Drain the accumulated wheel delta. */
+	wheelDelta() {
+		const w = this.wheel;
+		this.wheel = 0;
+		return w;
+	}
+	/**
+	* Wire browser pointer events on a canvas: buttons → Mouse0/1/2 codes,
+	* movement → pointerDelta (movementX/Y so pointer lock just works),
+	* wheel → wheelDelta. `lockOnClick` requests pointer lock on mousedown
+	* (the FPS pattern).
+	*/
+	attachPointer(target, opts) {
+		let buttonsHeld = 0;
+		const onDown = (e) => {
+			buttonsHeld++;
+			this.handleMouseButton(e.button, true);
+			if (opts?.lockOnClick && document.pointerLockElement !== target) target.requestPointerLock?.();
+		};
+		const onUp = (e) => {
+			buttonsHeld = Math.max(0, buttonsHeld - 1);
+			this.handleMouseButton(e.button, false);
+		};
+		const onMove = (e) => {
+			if (document.pointerLockElement === target || buttonsHeld > 0) this.handlePointerMove(e.movementX, e.movementY);
+		};
+		const onWheel = (e) => {
+			e.preventDefault();
+			this.handleWheel(e.deltaY);
+		};
+		const onContext = (e) => e.preventDefault();
+		target.addEventListener("mousedown", onDown);
+		window.addEventListener("mouseup", onUp);
+		window.addEventListener("mousemove", onMove);
+		target.addEventListener("wheel", onWheel, { passive: false });
+		target.addEventListener("contextmenu", onContext);
+		const detach = () => {
+			target.removeEventListener("mousedown", onDown);
+			window.removeEventListener("mouseup", onUp);
+			window.removeEventListener("mousemove", onMove);
+			target.removeEventListener("wheel", onWheel);
+			target.removeEventListener("contextmenu", onContext);
+		};
+		const prev = this.detach;
+		this.detach = () => {
+			prev?.();
+			detach();
+		};
+		return detach;
+	}
+	/**
+	* Wire browser keyboard events. Returns (and chains into dispose()) a detach
+	* function.
+	*
+	* By default the browser default is prevented for keys BOUND to a declared
+	* action — an embedded game must not scroll its host page on Space/arrows.
+	* Keys typed into editable elements (inputs, textareas, contenteditable)
+	* are ignored entirely so DOM UI overlays keep working.
+	*/
+	attachKeyboard(target, opts) {
+		const mode = opts?.preventDefault ?? "bound";
+		const onDown = (e) => {
+			if (isEditableTarget(e.target)) return;
+			if ((e.ctrlKey || e.metaKey) && !e.code.startsWith("Control") && !e.code.startsWith("Meta")) return;
+			if (mode === "bound" && this.codeIsBound(e.code)) e.preventDefault?.();
+			if (!e.repeat) this.handleKey(e.code, true);
+		};
+		const onUp = (e) => {
+			if (isEditableTarget(e.target)) return;
+			this.handleKey(e.code, false);
+		};
+		target.addEventListener("keydown", onDown);
+		target.addEventListener("keyup", onUp);
+		const detach = () => {
+			target.removeEventListener("keydown", onDown);
+			target.removeEventListener("keyup", onUp);
+		};
+		const prev = this.detach;
+		this.detach = () => {
+			prev?.();
+			detach();
+		};
+		return detach;
+	}
+	/** Whether any declared action binds this key code. */
+	codeIsBound(code) {
+		for (const action of this.actions.values()) if (action.type === "button") {
+			if (action.keys.includes(code)) return true;
+		} else {
+			const k = action.keys;
+			if (k.up.includes(code) || k.down.includes(code) || k.left.includes(code) || k.right.includes(code)) return true;
+		}
+		return false;
+	}
+	dispose() {
+		this.detach?.();
+		this.detach = null;
+	}
+	isPressed(action) {
+		return this.button(action).keys.some((k) => this.down.has(k)) || this.injectedDown.has(action);
+	}
+	justPressed(action) {
+		return this.button(action).keys.some((k) => this.pressedEdge.has(k)) || this.injectedPressed.has(action);
+	}
+	justReleased(action) {
+		return this.button(action).keys.some((k) => this.releasedEdge.has(k)) || this.injectedReleased.has(action);
+	}
+	/** Normalized direction for a vector2 action (y-down: up = -y). */
+	getVector(action) {
+		const def = this.get(action);
+		if (def.type !== "vector2") throw new IncantoError("BAD_FORMAT", `Input action '${action}' is a button — use isPressed/justPressed, not getVector.`);
+		const active = (codes) => codes.some((k) => this.down.has(k)) ? 1 : 0;
+		let x = active(def.keys.right) - active(def.keys.left);
+		let y = active(def.keys.down) - active(def.keys.up);
+		const injected = this.injectedVectors.get(action);
+		if (injected) {
+			x += injected.x;
+			y += injected.y;
+		}
+		const len = Math.hypot(x, y);
+		if (len > 1) {
+			x /= len;
+			y /= len;
+		}
+		return {
+			x,
+			y
+		};
+	}
+	/** Consume one-frame edges. The Engine calls this at the end of every tick. */
+	endFrame() {
+		this.pressedEdge.clear();
+		this.releasedEdge.clear();
+		this.injectedPressed.clear();
+		this.injectedReleased.clear();
+	}
+	/**
+	* Drop all action declarations and injected action state (physical key
+	* state is kept). The Engine calls this on setScene so keybinds never
+	* bleed between scenes.
+	*/
+	clear() {
+		this.actions.clear();
+		this.pressedEdge.clear();
+		this.releasedEdge.clear();
+		this.clearInjected();
+	}
+	get(action) {
+		const def = this.actions.get(action);
+		if (!def) throw new IncantoError("BAD_FORMAT", `Unknown input action '${action}'. Declared actions: [${[...this.actions.keys()].join(", ")}].`);
+		return def;
+	}
+	button(action) {
+		const def = this.get(action);
+		if (def.type !== "button") throw new IncantoError("BAD_FORMAT", `Input action '${action}' is a vector2 — use getVector, not button queries.`);
+		return def;
+	}
+};
+//#endregion
+//#region src/core/log.ts
+/**
+* The engine's log channel (`engine.log`, `this.log` in a Behavior): a ring
+* buffer plus a live `added` signal, so debug overlays and headless test
+* harnesses can tail game logs without scraping the browser console.
+*/
+var LogManager = class {
+	/** Fires once per entry, after it is buffered. */
+	added = new Signal();
+	buffer = [];
+	capacity;
+	seq = 0;
+	constructor(capacity = 1e3) {
+		this.capacity = capacity;
+	}
+	debug(...parts) {
+		this.push("debug", parts);
+	}
+	info(...parts) {
+		this.push("info", parts);
+	}
+	warn(...parts) {
+		this.push("warn", parts);
+	}
+	error(...parts) {
+		this.push("error", parts);
+	}
+	/** Buffered entries, oldest first (capped at capacity). */
+	entries() {
+		return this.buffer;
+	}
+	/** Empty the buffer. The sequence keeps counting (entries stay unique). */
+	clear() {
+		this.buffer.length = 0;
+	}
+	push(level, parts) {
+		this.seq += 1;
+		const entry = {
+			seq: this.seq,
+			timeMs: globalThis.performance?.now() ?? 0,
+			level,
+			parts
+		};
+		this.buffer.push(entry);
+		if (this.buffer.length > this.capacity) this.buffer.splice(0, this.buffer.length - this.capacity);
+		this.added.emit(entry);
+	}
+};
+//#endregion
+//#region src/core/engine.ts
+const MAX_DT_SECONDS = .25;
+function rafScheduler(cb) {
+	let live = true;
+	let id = requestAnimationFrame(function loop(t) {
+		if (!live) return;
+		cb(t);
+		id = requestAnimationFrame(loop);
+	});
+	return () => {
+		live = false;
+		cancelAnimationFrame(id);
+	};
+}
+/**
+* The game loop: drives a Scene's tree with fixed-timestep `fixedUpdate`
+* (physics/network window) and variable `update` (everything else).
+*
+* Instance-scoped by design — multiple engines can coexist. Headless-testable
+* via the injectable scheduler and the public `tick(nowMs)`.
+*/
+var Engine = class {
+	/** Emitted after the tree's variable update each frame, with dt seconds. */
+	updated = new Signal();
+	/** Emitted after each fixed step, with the fixed dt seconds. */
+	fixedUpdated = new Signal();
+	/**
+	* Emitted after a scene swap completes (input map redeclared) with the new
+	* scene, and with null on dispose — overlays (touch controls, debug panels)
+	* rebuild themselves here.
+	*/
+	sceneChanged = new Signal();
+	/** Declarative input — scene `input{}` declarations load on setScene. */
+	input = new InputMap();
+	/** Seeded randomness for game logic (deterministic when `seed` is set). */
+	rng;
+	/** The engine log channel (debug overlay + headless harness tail this). */
+	log = new LogManager();
+	/** Global volume buses — `master` × `sfx`/`music` gain + `muted`. AudioPlayer
+	*  routes its volume through this; games set it for global volume/mute. */
+	audio = new AudioBuses();
+	/** Low-latency procedural-SFX player (WebAudio, headless-safe). AudioPlayer
+	*  presets play through it; games may call `engine.sfx.play(...)` directly. */
+	sfx = new SfxEngine();
+	/** Single-track background-music manager (crossfade/loop, headless-safe).
+	*  `engine.music.play(src)` / `crossfadeTo(src, secs)` / `stop(fadeOut)`;
+	*  routes through the music bus and is advanced each frame by the loop. */
+	music = new MusicManager(this.audio);
+	fixedStep;
+	maxFixedSteps;
+	scheduler;
+	_scene = null;
+	lastMs = null;
+	accumulator = 0;
+	disposeScheduler = null;
+	frameStats = new FrameStatsRing();
+	constructor(opts = {}) {
+		this.fixedStep = 1 / (opts.fixedHz ?? 60);
+		this.maxFixedSteps = opts.maxFixedStepsPerTick ?? 5;
+		this.scheduler = opts.scheduler ?? rafScheduler;
+		this.rng = new Rng(opts.seed ?? Math.random() * 4294967295 >>> 0);
+	}
+	get scene() {
+		return this._scene;
+	}
+	/** Replace the active scene. The previous scene's root is freed. */
+	setScene(scene) {
+		if (scene === this._scene) return;
+		this._scene?.tree._setEngine(null);
+		this._scene?.root.free();
+		this._scene = scene;
+		scene.tree._setEngine(this);
+		this.input.clear();
+		if (scene.input) this.input.declare(scene.input);
+		this.sceneChanged.emit(scene);
+	}
+	start() {
+		if (this.disposeScheduler) return;
+		this.disposeScheduler = this.scheduler((now) => this.tick(now));
+	}
+	stop() {
+		this.disposeScheduler?.();
+		this.disposeScheduler = null;
+		this.lastMs = null;
+		this.accumulator = 0;
+		this.frameStats.clear();
+	}
+	/**
+	* Live performance counters, queryable at ANY time. fps/frameMs come from a
+	* rolling window of REAL `tick` timestamps — headless `step()` runs report 0.
+	* Node count walks the active tree on demand. Renderer counters (triangles,
+	* draw calls) live on `renderer.stats()` / the merged `game.stats()`.
+	*/
+	stats() {
+		return {
+			fps: this.frameStats.fps(),
+			frameMs: this.frameStats.frameMs(),
+			nodes: this._scene?.tree.root ? countNodes(this._scene.tree.root) : 0,
+			running: this.disposeScheduler !== null
+		};
+	}
+	/**
+	* Render interpolation factor in [0,1]: how far the wall clock has advanced
+	* INTO the next fixed step. Renderers lerp physics bodies between their last
+	* two fixed-step transforms by this much so motion looks smooth even when the
+	* display refresh doesn't divide evenly into the 60Hz fixed step (the classic
+	* fixed-timestep judder). Only meaningful in the real-time `tick()` loop;
+	* the headless `step()` path doesn't bank wall-clock time.
+	*/
+	get interpolationAlpha() {
+		return this.fixedStep > 0 ? Math.min(this.accumulator / this.fixedStep, 1) : 1;
+	}
+	/**
+	* Full teardown in one call: stop the loop, free the scene tree, detach
+	* every input listener. The single-unmount story for SPA embedding —
+	* renderers own GPU resources and keep their own dispose().
+	*/
+	dispose() {
+		this.stop();
+		if (this._scene) {
+			this._scene.tree._setEngine(null);
+			this._scene.root.free();
+			this._scene = null;
+			this.sceneChanged.emit(null);
+		}
+		this.input.dispose();
+		this.input.clear();
+	}
+	/**
+	* Advance exactly ONE fixed step and one variable update (both dt = the
+	* fixed step), bypassing the wall-clock accumulator entirely. Drift-free
+	* by construction — the unit of time for headless harnesses (incanto/test
+	* runScript): every input edge is visible to BOTH fixedUpdate and update
+	* exactly once.
+	*/
+	step() {
+		const scene = this._scene;
+		if (!scene) return;
+		scene.tree.fixedUpdate(this.fixedStep);
+		this.fixedUpdated.emit(this.fixedStep);
+		scene.tree.update(this.fixedStep);
+		this.music.tick(this.fixedStep);
+		this.updated.emit(this.fixedStep);
+		this.input.endFrame();
+	}
+	/** Advance the loop manually. First call after (re)start only primes the clock. */
+	tick(nowMs) {
+		this.frameStats.push(nowMs);
+		if (this.lastMs === null) {
+			this.lastMs = nowMs;
+			return;
+		}
+		const dt = Math.min((nowMs - this.lastMs) / 1e3, MAX_DT_SECONDS);
+		this.lastMs = nowMs;
+		const scene = this._scene;
+		if (!scene) return;
+		this.accumulator += dt;
+		let steps = 0;
+		while (this.accumulator >= this.fixedStep && steps < this.maxFixedSteps) {
+			scene.tree.fixedUpdate(this.fixedStep);
+			this.fixedUpdated.emit(this.fixedStep);
+			this.accumulator -= this.fixedStep;
+			steps += 1;
+		}
+		if (this.accumulator >= this.fixedStep) this.accumulator %= this.fixedStep;
+		scene.tree.update(dt);
+		this.music.tick(dt);
+		this.updated.emit(dt);
+		this.input.endFrame();
+	}
+};
+function countNodes(root) {
+	let n = 1;
+	for (const child of root.children) n += countNodes(child);
+	return n;
+}
+//#endregion
+//#region src/core/particle-presets.ts
+const PARTICLE_PRESETS = {
+	fire: {
+		rate: 60,
+		lifetime: [.4, .9],
+		speed: [30, 70],
+		directionDeg: -90,
+		spreadDeg: 35,
+		gravity: [0, -30],
+		sizeStart: 14,
+		sizeEnd: 3,
+		colorStart: "#ffcf5a",
+		colorEnd: "#e8401f",
+		alphaStart: .9,
+		alphaEnd: 0,
+		blend: "add"
+	},
+	smoke: {
+		rate: 20,
+		lifetime: [1.5, 2.5],
+		speed: [10, 25],
+		directionDeg: -90,
+		spreadDeg: 40,
+		gravity: [0, -12],
+		sizeStart: 10,
+		sizeEnd: 26,
+		colorStart: "#8a8a8a",
+		colorEnd: "#3a3a3a",
+		alphaStart: .35,
+		alphaEnd: 0,
+		blend: "normal"
+	},
+	sparks: {
+		rate: 80,
+		lifetime: [.3, .7],
+		speed: [120, 260],
+		spreadDeg: 360,
+		gravity: [0, 240],
+		drag: 1,
+		sizeStart: 4,
+		sizeEnd: 1,
+		colorStart: "#fff3b0",
+		colorEnd: "#ff9d2e",
+		blend: "add"
+	},
+	fireworks: {
+		rate: 0,
+		burst: 120,
+		lifetime: [.8, 1.6],
+		speed: [80, 240],
+		spreadDeg: 360,
+		gravity: [0, 90],
+		drag: .6,
+		sizeStart: 5,
+		sizeEnd: 1,
+		colorStart: "#9ad8ff",
+		colorEnd: "#ff5ad8",
+		blend: "add"
+	},
+	explosion: {
+		rate: 0,
+		burst: 60,
+		lifetime: [.25, .6],
+		speed: [150, 420],
+		spreadDeg: 360,
+		drag: 3,
+		sizeStart: 16,
+		sizeEnd: 2,
+		colorStart: "#ffe08a",
+		colorEnd: "#ff3b1f",
+		blend: "add"
+	},
+	flash: {
+		rate: 0,
+		burst: 8,
+		lifetime: [.08, .16],
+		speed: [0, 30],
+		spreadDeg: 360,
+		sizeStart: 64,
+		sizeEnd: 96,
+		colorStart: "#ffffff",
+		colorEnd: "#ffffff",
+		alphaStart: 1,
+		alphaEnd: 0,
+		blend: "add"
+	},
+	lightning: {
+		rate: 90,
+		lifetime: [.05, .12],
+		speed: [400, 900],
+		directionDeg: -90,
+		spreadDeg: 14,
+		sizeStart: 6,
+		sizeEnd: 2,
+		colorStart: "#eaf2ff",
+		colorEnd: "#7fb4ff",
+		blend: "add"
+	},
+	rain: {
+		rate: 160,
+		lifetime: [.8, 1.2],
+		speed: [300, 420],
+		directionDeg: 90,
+		spreadDeg: 6,
+		sizeStart: 3,
+		sizeEnd: 3,
+		colorStart: "#9ec8ff",
+		colorEnd: "#9ec8ff",
+		alphaStart: .5,
+		alphaEnd: .2,
+		blend: "normal"
+	},
+	snow: {
+		rate: 40,
+		lifetime: [3, 5],
+		speed: [20, 50],
+		directionDeg: 90,
+		spreadDeg: 30,
+		drag: .2,
+		sizeStart: 5,
+		sizeEnd: 4,
+		colorStart: "#ffffff",
+		colorEnd: "#ffffff",
+		alphaStart: .9,
+		alphaEnd: .6,
+		blend: "normal"
+	},
+	magic: {
+		rate: 50,
+		lifetime: [.6, 1.4],
+		speed: [20, 80],
+		spreadDeg: 360,
+		gravity: [0, -20],
+		sizeStart: 7,
+		sizeEnd: 1,
+		colorStart: "#9dffe8",
+		colorEnd: "#7a5cff",
+		blend: "add"
+	}
+};
+const PARTICLE_PRESET_NAMES = Object.keys(PARTICLE_PRESETS);
+/**
+* Apply the delta rule across three layers: schema default < preset < the
+* scene's explicit props. A prop still equal to its SCHEMA default is
+* considered "unset" and takes the preset value.
+*/
+function applyParticlePreset(target, presetName, schema) {
+	if (presetName === "custom") return;
+	const preset = PARTICLE_PRESETS[presetName];
+	if (!preset) return;
+	for (const [key, presetValue] of Object.entries(preset)) {
+		const def = schema[key]?.default;
+		const current = target[key];
+		if (def !== void 0 && jsonEquals(current, def)) target[key] = Array.isArray(presetValue) ? [...presetValue] : presetValue;
+	}
+}
+//#endregion
+//#region src/core/particle-sim.ts
+const FIELDS = 9;
+var ParticleSim = class {
+	config;
+	rng;
+	data;
+	alive = 0;
+	spawnAccumulator = 0;
+	everSpawned = false;
+	constructor(config, rng) {
+		this.config = config;
+		this.rng = rng;
+		this.data = new Float64Array(Math.max(1, config.maxParticles) * FIELDS);
+	}
+	get count() {
+		return this.alive;
+	}
+	/** True when nothing is alive and at least one particle has ever spawned. */
+	get done() {
+		return this.everSpawned && this.alive === 0;
+	}
+	/** Spawn n particles immediately (fireworks, explosions, flashes). */
+	burst(n) {
+		for (let i = 0; i < n; i++) this.spawn();
+	}
+	update(dt) {
+		if (this.config.rate > 0) {
+			this.spawnAccumulator += this.config.rate * dt;
+			while (this.spawnAccumulator >= 1) {
+				this.spawnAccumulator -= 1;
+				this.spawn();
+			}
+		}
+		const d = this.data;
+		const [gx, gy, gz] = this.config.gravity;
+		const damp = this.config.drag > 0 ? Math.exp(-this.config.drag * dt) : 1;
+		let i = 0;
+		while (i < this.alive) {
+			const base = i * FIELDS;
+			const age = d[base + 6] + dt;
+			if (age >= d[base + 7]) {
+				this.kill(i);
+				continue;
+			}
+			d[base + 6] = age;
+			d[base + 3] = (d[base + 3] + gx * dt) * damp;
+			d[base + 4] = (d[base + 4] + gy * dt) * damp;
+			d[base + 5] = (d[base + 5] + gz * dt) * damp;
+			d[base + 0] = d[base + 0] + d[base + 3] * dt;
+			d[base + 1] = d[base + 1] + d[base + 4] * dt;
+			d[base + 2] = d[base + 2] + d[base + 5] * dt;
+			i += 1;
+		}
+	}
+	forEach(fn) {
+		const d = this.data;
+		for (let i = 0; i < this.alive; i++) {
+			const base = i * FIELDS;
+			const age = d[base + 6];
+			const life = d[base + 7];
+			fn({
+				x: d[base + 0],
+				y: d[base + 1],
+				z: d[base + 2],
+				vx: d[base + 3],
+				vy: d[base + 4],
+				vz: d[base + 5],
+				age,
+				life,
+				t: life > 0 ? age / life : 1,
+				seed: d[base + 8]
+			});
+		}
+	}
+	spawn() {
+		if (this.alive >= this.config.maxParticles) return;
+		const base = this.alive * FIELDS;
+		const d = this.data;
+		const c = this.config;
+		const angle = (c.directionDeg + (this.rng.next() - .5) * c.spreadDeg) * Math.PI / 180;
+		const speed = c.speed[0] + this.rng.next() * (c.speed[1] - c.speed[0]);
+		const zTilt = c.spreadZ ? (this.rng.next() - .5) * (c.spreadDeg * Math.PI / 180) : 0;
+		const planar = Math.cos(zTilt);
+		d[base + 0] = 0;
+		d[base + 1] = 0;
+		d[base + 2] = 0;
+		d[base + 3] = Math.cos(angle) * speed * planar;
+		d[base + 4] = Math.sin(angle) * speed * planar;
+		d[base + 5] = Math.sin(zTilt) * speed;
+		d[base + 6] = 0;
+		d[base + 7] = c.lifetime[0] + this.rng.next() * (c.lifetime[1] - c.lifetime[0]);
+		d[base + 8] = this.rng.next();
+		this.alive += 1;
+		this.everSpawned = true;
+	}
+	kill(index) {
+		const last = this.alive - 1;
+		if (index !== last) this.data.copyWithin(index * FIELDS, last * FIELDS, last * FIELDS + FIELDS);
+		this.alive = last;
+	}
+};
+//#endregion
+export { Engine as a, SfxEngine as c, WebAudioMusicBackend as d, crossfadeGains as f, applyParticlePreset as i, isAudioContextAvailable as l, AudioBuses as m, PARTICLE_PRESETS as n, LogManager as o, fadeGain as p, PARTICLE_PRESET_NAMES as r, InputMap as s, ParticleSim as t, MusicManager as u };