incanto 0.7.0 → 0.8.0

package/dist/{particle-sim-CrTE7c02.js → register-DRPIjrKG.js}

@@ -1,8 +1,7 @@
-import { y as Signal } from "./loader-B4OEXDZ8.js";
+import { f as Node, y as Signal } from "./loader-B4OEXDZ8.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
-import { p as synthSfx } from "./register-Dl_ixIJe.js";
-import { n as jsonEquals } from "./json-BLk7H2Qa.js";
+import { l as registerNode } from "./registry-BVJ2HbCn.js";
 //#region src/core/audio/buses.ts
 /**
 * Global volume state — `master` × `sfx`/`music` gain (0..1) plus a `muted`
@@ -55,17 +54,17 @@ var AudioBuses = class {
 	effectiveVolume(bus, sourceVolume) {
 		if (this._muted) return 0;
 		const busGain = bus === "music" ? this._music : this._sfx;
-		return this._master * busGain * clamp01$2(sourceVolume);
+		return this._master * busGain * clamp01$3(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);
+		const clamped = clamp01$3(next);
 		if (clamped !== current) this.changed.emit();
 		return clamped;
 	}
 };
-function clamp01$2(v) {
+function clamp01$3(v) {
 	if (!Number.isFinite(v)) return 0;
 	return v < 0 ? 0 : v > 1 ? 1 : v;
 }
@@ -91,17 +90,17 @@ function fadeGain(t, duration, dir) {
 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))
+		out: clamp01$2(Math.cos(angle)),
+		in: clamp01$2(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);
+	return clamp01$2(t / duration);
 }
-function clamp01$1(v) {
+function clamp01$2(v) {
 	if (!Number.isFinite(v)) return 0;
 	return v < 0 ? 0 : v > 1 ? 1 : v;
 }
@@ -113,12 +112,12 @@ function createContext$1() {
 	const Ctor = resolveCtor$1();
 	return Ctor ? new Ctor() : null;
 }
-function createElement() {
+function createElement$1() {
 	if (typeof Audio === "undefined") return null;
 	return new Audio();
 }
 /** A no-op track for the headless / missing-backend path. */
-const INERT = {
+const INERT$1 = {
 	src: "",
 	setGain() {},
 	setLoop() {},
@@ -171,9 +170,9 @@ var WebAudioMusicBackend = class {
 	}
 	createTrack(src) {
 		const ctx = this.ensure();
-		const el = createElement();
+		const el = createElement$1();
 		if (!ctx || !el) return {
-			...INERT,
+			...INERT$1,
 			src
 		};
 		if (ctx.state === "suspended") ctx.resume();
@@ -311,7 +310,7 @@ var MusicManager = class {
 	}
 	/** Set the per-manager volume (re-applied to live tracks on the next tick). */
 	setVolume(v) {
-		this._volume = clamp01(v);
+		this._volume = clamp01$1(v);
 	}
 	/** Advance fades by `dt` seconds and (re)apply bus×fade gains. Frame-driven. */
 	tick(dt) {
@@ -356,11 +355,436 @@ var MusicManager = class {
 		this.outgoing = null;
 	}
 };
-function clamp01(v) {
+function clamp01$1(v) {
 	if (!Number.isFinite(v)) return 0;
 	return v < 0 ? 0 : v > 1 ? 1 : v;
 }
 //#endregion
+//#region src/core/audio/sfx-presets.ts
+/**
+* A tasteful, distinct set of common game sounds. Pick one via
+* `AudioPlayer.preset`. Tuned by ear for crisp arcade feel; `seed`/`pitch`
+* props add free variation so repeated sounds don't feel robotic.
+*/
+const SFX_PRESETS = {
+	coin: {
+		wave: "square",
+		baseFreq: 988,
+		freqRamp: 1800,
+		attack: 0,
+		sustain: .04,
+		decay: .18,
+		duty: .5,
+		volume: .4
+	},
+	pickup: {
+		wave: "sine",
+		baseFreq: 660,
+		freqRamp: 900,
+		attack: .005,
+		sustain: .05,
+		decay: .12,
+		volume: .45
+	},
+	jump: {
+		wave: "square",
+		baseFreq: 320,
+		freqRamp: 600,
+		attack: 0,
+		sustain: .03,
+		decay: .12,
+		duty: .35,
+		volume: .4
+	},
+	hurt: {
+		wave: "sawtooth",
+		baseFreq: 380,
+		freqRamp: -520,
+		attack: 0,
+		sustain: .05,
+		decay: .16,
+		volume: .5
+	},
+	hit: {
+		wave: "noise",
+		baseFreq: 600,
+		freqRamp: -400,
+		attack: 0,
+		sustain: .02,
+		decay: .1,
+		volume: .55
+	},
+	explosion: {
+		wave: "noise",
+		baseFreq: 420,
+		freqRamp: -360,
+		attack: 0,
+		sustain: .12,
+		decay: .5,
+		volume: .6
+	},
+	powerup: {
+		wave: "square",
+		baseFreq: 440,
+		freqRamp: 1200,
+		attack: .01,
+		sustain: .18,
+		decay: .22,
+		duty: .5,
+		vibratoDepth: .08,
+		vibratoRate: 18,
+		volume: .4
+	},
+	laser: {
+		wave: "sawtooth",
+		baseFreq: 1400,
+		freqRamp: -2600,
+		attack: 0,
+		sustain: .03,
+		decay: .14,
+		volume: .4
+	},
+	shoot: {
+		wave: "square",
+		baseFreq: 900,
+		freqRamp: -1400,
+		attack: 0,
+		sustain: .02,
+		decay: .1,
+		duty: .25,
+		volume: .45
+	},
+	blip: {
+		wave: "square",
+		baseFreq: 760,
+		freqRamp: 0,
+		attack: 0,
+		sustain: .015,
+		decay: .04,
+		duty: .5,
+		volume: .35
+	},
+	select: {
+		wave: "triangle",
+		baseFreq: 520,
+		freqRamp: 420,
+		attack: .002,
+		sustain: .04,
+		decay: .08,
+		volume: .4
+	},
+	step: {
+		wave: "noise",
+		baseFreq: 220,
+		freqRamp: -120,
+		attack: 0,
+		sustain: .01,
+		decay: .05,
+		volume: .3
+	},
+	win: {
+		wave: "square",
+		baseFreq: 523,
+		freqRamp: 900,
+		attack: .01,
+		sustain: .35,
+		decay: .3,
+		duty: .5,
+		vibratoDepth: .05,
+		vibratoRate: 10,
+		volume: .42
+	},
+	lose: {
+		wave: "sawtooth",
+		baseFreq: 392,
+		freqRamp: -300,
+		attack: .01,
+		sustain: .3,
+		decay: .4,
+		volume: .45
+	}
+};
+const SFX_PRESET_NAMES = Object.keys(SFX_PRESETS);
+const TWO_PI = Math.PI * 2;
+/**
+* Render a preset to mono PCM in [-1, 1]. PURE: identical inputs → identical
+* output (the only randomness is the seeded noise generator), so determinism is
+* unit-testable headlessly. Length = ceil((attack+sustain+decay) * sampleRate).
+*/
+function synthSfx(params, opts = {}) {
+	const sampleRate = opts.sampleRate ?? 44100;
+	const pitch = opts.pitch ?? 1;
+	const rng = new Rng((opts.seed ?? 0) ^ 42405);
+	const total = params.attack + params.sustain + params.decay;
+	const length = Math.max(1, Math.ceil(total * sampleRate));
+	const out = new Float32Array(length);
+	const duty = params.duty ?? .5;
+	const vibDepth = params.vibratoDepth ?? 0;
+	const vibRate = params.vibratoRate ?? 0;
+	let phase = 0;
+	let lastNoise = rng.range(-1, 1);
+	let noiseHold = 0;
+	for (let i = 0; i < length; i++) {
+		const t = i / sampleRate;
+		let env;
+		if (t < params.attack) env = params.attack > 0 ? t / params.attack : 1;
+		else if (t < params.attack + params.sustain) env = 1;
+		else {
+			const d = t - params.attack - params.sustain;
+			env = params.decay > 0 ? Math.max(0, 1 - d / params.decay) : 0;
+		}
+		let freq = (params.baseFreq + params.freqRamp * t) * pitch;
+		if (vibDepth > 0 && vibRate > 0) freq += freq * vibDepth * Math.sin(TWO_PI * vibRate * t);
+		freq = Math.max(0, freq);
+		phase += freq / sampleRate;
+		phase -= Math.floor(phase);
+		let sample;
+		switch (params.wave) {
+			case "square":
+				sample = phase < duty ? 1 : -1;
+				break;
+			case "sawtooth":
+				sample = 2 * phase - 1;
+				break;
+			case "triangle":
+				sample = 4 * Math.abs(phase - .5) - 1;
+				break;
+			case "sine":
+				sample = Math.sin(TWO_PI * phase);
+				break;
+			default:
+				noiseHold -= freq / sampleRate;
+				if (noiseHold <= 0) {
+					lastNoise = rng.range(-1, 1);
+					noiseHold += 1;
+				}
+				sample = lastNoise;
+				break;
+		}
+		out[i] = clamp$1(sample * env * params.volume);
+	}
+	return out;
+}
+function clamp$1(v) {
+	return v < -1 ? -1 : v > 1 ? 1 : v;
+}
+//#endregion
+//#region src/core/audio/spatial.ts
+const ROLLOFF_MODELS = [
+	"inverse",
+	"linear",
+	"exponential"
+];
+/**
+* Gain (0..1) for a source `distance` units from the listener, per the chosen
+* model. Identical to the WebAudio PannerNode formulas so the headless number
+* matches the browser panner:
+*
+* - inverse:     ref / (ref + factor·(clamp(d) − ref))
+* - linear:      1 − factor·(clamp(d) − ref) / (max − ref)
+* - exponential: (clamp(d) / ref)^(−factor)
+*
+* where `clamp(d)` is `d` clamped to `[ref, max]`. Always full inside
+* `refDistance`; monotonic non-increasing out to `maxDistance`. Non-finite or
+* degenerate inputs return a safe finite gain.
+*/
+function spatialGain(distance, params) {
+	const ref = Math.max(0, params.refDistance);
+	const max = Math.max(ref, params.maxDistance);
+	const factor = params.rolloffFactor ?? 1;
+	if (!Number.isFinite(distance)) return 1;
+	const d = clamp(distance, ref, max);
+	if (d <= ref) return 1;
+	let g;
+	switch (params.rolloff) {
+		case "linear": {
+			const span = max - ref;
+			g = span <= 0 ? 1 : 1 - factor * (d - ref) / span;
+			break;
+		}
+		case "exponential":
+			g = ref <= 0 ? 1 : (d / ref) ** -factor;
+			break;
+		default:
+			g = ref / (ref + factor * (d - ref));
+			break;
+	}
+	if (!Number.isFinite(g)) return 0;
+	return clamp01(g);
+}
+const scratchToSource = [
+	0,
+	0,
+	0
+];
+/**
+* Stereo pan (−1 left … 0 center … +1 right) for a source at `sourcePos`,
+* relative to the listener's orientation. Projects the listener→source vector
+* onto the listener's RIGHT axis (forward × up) and normalizes by its length —
+* sign tells left/right, magnitude tells how far off-axis. A source at the
+* listener position (or dead ahead) is centered. Result clamped to [−1, 1].
+*
+* This is the CPU twin of what HRTF/equalpower panning does to the azimuth; the
+* real PannerNode does the full spatialization, but exposing the sign here makes
+* the geometry unit-testable and lets the 2D fallback pan by the same rule.
+*/
+function spatialPan(sourcePos, listener) {
+	const dx = sourcePos[0] - listener.position[0];
+	const dy = sourcePos[1] - listener.position[1];
+	const dz = sourcePos[2] - listener.position[2];
+	const len = Math.hypot(dx, dy, dz);
+	if (len < 1e-6) return 0;
+	scratchToSource[0] = dx / len;
+	scratchToSource[1] = dy / len;
+	scratchToSource[2] = dz / len;
+	const [fx, fy, fz] = listener.forward;
+	const [ux, uy, uz] = listener.up;
+	const rx = fy * uz - fz * uy;
+	const ry = fz * ux - fx * uz;
+	const rz = fx * uy - fy * ux;
+	const rLen = Math.hypot(rx, ry, rz);
+	if (rLen < 1e-6) return 0;
+	return clamp((scratchToSource[0] * rx + scratchToSource[1] * ry + scratchToSource[2] * rz) / rLen, -1, 1);
+}
+function clamp(v, lo, hi) {
+	return v < lo ? lo : v > hi ? hi : v;
+}
+function clamp01(v) {
+	return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+//#endregion
+//#region src/core/audio/voice.ts
+const SPECS = {
+	engine: {
+		oscillators: [[
+			"sawtooth",
+			55,
+			0
+		], [
+			"sawtooth",
+			55,
+			12
+		]],
+		noise: null,
+		lowpassHz: 900
+	},
+	wind: {
+		oscillators: [],
+		noise: [
+			700,
+			.6,
+			1
+		],
+		lowpassHz: 4e3
+	},
+	hum: {
+		oscillators: [[
+			"sine",
+			110,
+			0
+		], [
+			"triangle",
+			110,
+			5
+		]],
+		noise: null,
+		lowpassHz: 1200
+	},
+	noise: {
+		oscillators: [],
+		noise: [
+			1200,
+			.3,
+			1
+		],
+		lowpassHz: 6e3
+	}
+};
+const INERT = {
+	set: () => {},
+	stop: () => {},
+	stopped: true
+};
+/** @internal Build a live voice on a context (SfxEngine wraps this). */
+function createVoice(ctx, preset, gain) {
+	const spec = SPECS[preset] ?? SPECS.hum;
+	const out = ctx.createGain();
+	out.gain.value = 0;
+	out.connect(ctx.destination);
+	const master = gain;
+	const lowpass = ctx.createBiquadFilter();
+	lowpass.type = "lowpass";
+	lowpass.frequency.value = spec.lowpassHz;
+	lowpass.connect(out);
+	const oscs = [];
+	for (const [type, hz, cents] of spec.oscillators) {
+		const osc = ctx.createOscillator();
+		osc.type = type;
+		osc.frequency.value = hz;
+		osc.detune.value = cents;
+		osc.connect(lowpass);
+		osc.start();
+		oscs.push(osc);
+	}
+	let noiseSrc = null;
+	let noiseBand = null;
+	if (spec.noise) {
+		const [center, q, noiseGain] = spec.noise;
+		const buffer = ctx.createBuffer(1, ctx.sampleRate * 2, ctx.sampleRate);
+		const data = buffer.getChannelData(0);
+		let seed = 987654321;
+		for (let i = 0; i < data.length; i++) {
+			seed = seed * 1664525 + 1013904223 >>> 0;
+			data[i] = seed / 4294967295 * 2 - 1;
+		}
+		noiseSrc = ctx.createBufferSource();
+		noiseSrc.buffer = buffer;
+		noiseSrc.loop = true;
+		noiseBand = ctx.createBiquadFilter();
+		noiseBand.type = "bandpass";
+		noiseBand.frequency.value = center;
+		noiseBand.Q.value = q;
+		const ng = ctx.createGain();
+		ng.gain.value = noiseGain;
+		noiseSrc.connect(noiseBand);
+		noiseBand.connect(ng);
+		ng.connect(lowpass);
+		noiseSrc.start();
+	}
+	const baseFreqs = spec.oscillators.map(([, hz]) => hz);
+	const noiseCenter = spec.noise?.[0] ?? 0;
+	let stopped = false;
+	const now = () => ctx.currentTime;
+	out.gain.setTargetAtTime(.4 * master, now(), .05);
+	return {
+		get stopped() {
+			return stopped;
+		},
+		set({ pitch, volume }) {
+			if (stopped) return;
+			if (pitch !== void 0) {
+				const p = Math.max(.05, pitch);
+				oscs.forEach((osc, i) => {
+					osc.frequency.setTargetAtTime(baseFreqs[i] * p, now(), .03);
+				});
+				if (noiseBand) noiseBand.frequency.setTargetAtTime(noiseCenter * p, now(), .03);
+			}
+			if (volume !== void 0) out.gain.setTargetAtTime(Math.max(0, Math.min(1, volume)) * master, now(), .04);
+		},
+		stop(seconds = .15) {
+			if (stopped) return;
+			stopped = true;
+			out.gain.setTargetAtTime(0, now(), Math.max(.01, seconds / 3));
+			setTimeout(() => {
+				for (const osc of oscs) osc.stop();
+				noiseSrc?.stop();
+				out.disconnect();
+			}, seconds * 1e3 + 120);
+		}
+	};
+}
+const INERT_VOICE = INERT;
+//#endregion
 //#region src/core/audio/webaudio-sfx.ts
 /** Position a WebAudio AudioListener from a pose (modern AudioParam or legacy). */
 function applyListenerPose(ctxListener, pose) {
@@ -429,6 +853,17 @@ var SfxEngine = class {
 		}
 		return this.ctx;
 	}
+	/**
+	* Start a continuous parametric voice (engine hum, wind, thrusters) —
+	* retune it per frame with `voice.set({ pitch, volume })`, `stop()` when
+	* done. Headless returns an inert handle (same call sites, no ifs).
+	*/
+	startVoice(preset, gain = 1) {
+		const ctx = this.ensure();
+		if (!ctx) return INERT_VOICE;
+		if (ctx.state === "suspended") ctx.resume();
+		return createVoice(ctx, preset, gain);
+	}
 	/** Resume a gesture-suspended context (wired to the first user gesture). */
 	unlock() {
 		const ctx = this.ensure();
@@ -1011,6 +1446,13 @@ var Engine = class {
 	* timers, behaviors all breathe together. See `gameplay` `hitStop()`.
 	*/
 	timeScale = 1;
+	/**
+	* The node the dev overlay has selected (renderers draw its bounding box
+	* as an orange outline in the game view so you can SEE what you picked).
+	* Null when nothing is selected; cleared automatically when it leaves the
+	* tree. Set by the debug overlay — games normally never touch this.
+	*/
+	debugSelection = null;
 	_time = 0;
 	_unscaledTime = 0;
 	/**
@@ -1151,284 +1593,749 @@ function countNodes(root) {
 	for (const child of root.children) n += countNodes(child);
 	return n;
 }
+function createElement() {
+	if (typeof Audio === "undefined") return null;
+	return new Audio();
+}
+/**
+* One sound. `play()` (or `autoplay: true`) starts it; `finished` fires when
+* it ends. Browsers block audio before the first user gesture — a blocked
+* play marks `pendingGesture`; `createGame` retries pending players on the
+* first pointer/key gesture automatically.
+*
+* Two playback modes:
+* - `preset: 'custom'` (default) → plays the audio file at `src` via an HTMLAudio
+*   element (good for music / long clips; supports `loop`).
+* - `preset: 'coin' | 'jump' | …` (a procedural SFX preset) → synthesizes a
+*   zero-asset sound through WebAudio: instant, deterministic, overlap-friendly
+*   for rapid-fire SFX. `pitch`/`seed` vary it. The art-free audio analog of the
+*   particle presets. See `incanto-audio.md` for the full preset list.
+*
+* Volume routes through the engine's buses: `engine.audio.master × bus(sfx|music)
+* × volume`. Set `engine.audio.master`/`sfx`/`music`/`muted` for global control.
+*/
+var AudioPlayer = class extends Node {
+	static typeName = "AudioPlayer";
+	static signals = ["finished"];
+	static props = {
+		src: { default: "" },
+		preset: {
+			default: "custom",
+			options: ["custom", ...SFX_PRESET_NAMES]
+		},
+		volume: { default: 1 },
+		pitch: { default: 1 },
+		seed: { default: 0 },
+		bus: {
+			default: "sfx",
+			options: ["sfx", "music"]
+		},
+		loop: { default: false },
+		autoplay: { default: false },
+		spatial: { default: false },
+		refDistance: { default: 1 },
+		maxDistance: { default: 50 },
+		rolloff: {
+			default: "inverse",
+			options: [...ROLLOFF_MODELS]
+		}
+	};
+	/** Audio file url (same resolution rules as scene asset urls). Used when
+	*  `preset === 'custom'`; ignored for procedural presets. */
+	src = "";
+	/** A procedural SFX preset name (zero-asset), or 'custom' to use `src`. */
+	preset = "custom";
+	volume = 1;
+	/** Pitch multiplier for procedural presets (1 = unchanged). */
+	pitch = 1;
+	/** Variation seed for noisy presets (e.g. explosion/hit/step). */
+	seed = 0;
+	/** Which volume bus this routes through. */
+	bus = "sfx";
+	loop = false;
+	/** Start on the first frame in the tree (subject to the gesture policy). */
+	autoplay = false;
+	/**
+	* 3D positional audio: in a 3D scene the sound pans + attenuates by the
+	* emitter's world position relative to the active Camera3D (the listener).
+	* Default false → identical non-spatial behavior (back-compat). In a 2D scene
+	* spatial is currently ignored (the adapter feeds no pose) — see incanto-audio.
+	*/
+	spatial = false;
+	/** Distance at which spatial gain is full; closer never gets louder. */
+	refDistance = 1;
+	/** Distance past which spatial gain stops falling. */
+	maxDistance = 50;
+	/** Spatial attenuation curve: 'inverse' | 'linear' | 'exponential'. */
+	rolloff = "inverse";
+	/** Loader hook: unknown presets / buses fail at LOAD (agents self-correct). */
+	static validateJson(node) {
+		const a = node;
+		if (a.preset !== "custom" && !SFX_PRESET_NAMES.includes(a.preset)) throw new IncantoError("BAD_FORMAT", `AudioPlayer '${node.name}' preset must be 'custom' or one of [${SFX_PRESET_NAMES.join(", ")}], got '${a.preset}'.`, {
+			prop: "preset",
+			validOptions: SFX_PRESET_NAMES
+		});
+		if (a.bus !== "sfx" && a.bus !== "music") throw new IncantoError("BAD_FORMAT", `AudioPlayer '${node.name}' bus must be 'sfx' or 'music', got '${a.bus}'.`, {
+			prop: "bus",
+			validOptions: ["sfx", "music"]
+		});
+		if (!ROLLOFF_MODELS.includes(a.rolloff)) throw new IncantoError("BAD_FORMAT", `AudioPlayer '${node.name}' rolloff must be one of [${ROLLOFF_MODELS.join(", ")}], got '${a.rolloff}'.`, {
+			prop: "rolloff",
+			validOptions: [...ROLLOFF_MODELS]
+		});
+	}
+	/** A play() was blocked by the browser's autoplay policy. */
+	pendingGesture = false;
+	element = null;
+	_playing = false;
+	autoplayed = false;
+	/** Last spatial pose pushed by the 3D adapter (null until/unless spatial). */
+	_spatialPose = null;
+	get playing() {
+		return this._playing;
+	}
+	/**
+	* @internal Per-frame spatial feed from the 3D adapter (detected structurally
+	* by syncTree). Stores the emitter world position + listener pose; ignored
+	* unless `spatial` is on. Headless / 2D scenes never call this.
+	*/
+	_setSpatialPose(pose) {
+		this._spatialPose = pose;
+	}
+	/** Final gain = engine buses × this volume (1 when not in a tree). */
+	gain() {
+		const buses = this.tree?.engine?.audio;
+		return buses ? buses.effectiveVolume(this.bus, this.volume) : this.volume;
+	}
+	/** Distance gain for the src/element path (1 when not spatial / no pose). */
+	spatialElementGain() {
+		if (!this.spatial || !this._spatialPose) return 1;
+		const { position, listener } = this._spatialPose;
+		const dx = position[0] - listener.position[0];
+		const dy = position[1] - listener.position[1];
+		const dz = position[2] - listener.position[2];
+		return spatialGain(Math.hypot(dx, dy, dz), {
+			refDistance: this.refDistance,
+			maxDistance: this.maxDistance,
+			rolloff: this.rolloff
+		});
+	}
+	/** The `spatial` option for the SFX path, or undefined when not spatial. */
+	spatialPlay() {
+		if (!this.spatial || !this._spatialPose) return void 0;
+		return {
+			position: this._spatialPose.position,
+			listener: this._spatialPose.listener,
+			refDistance: this.refDistance,
+			maxDistance: this.maxDistance,
+			rolloff: this.rolloff
+		};
+	}
+	play() {
+		if (this.preset !== "custom") {
+			this.playPreset();
+			return;
+		}
+		if (!this.src) return;
+		if (!this.element) {
+			this.element = createElement();
+			if (!this.element) return;
+			this.element.addEventListener("ended", () => {
+				if (this.loop) return;
+				this._playing = false;
+				this.emit("finished");
+			});
+		}
+		const el = this.element;
+		el.src = this.src;
+		el.volume = this.gain() * this.spatialElementGain();
+		el.loop = this.loop;
+		this._playing = true;
+		this.pendingGesture = false;
+		el.play().catch(() => {
+			this._playing = false;
+			this.pendingGesture = true;
+		});
+	}
+	/**
+	* Procedural-SFX path: synthesize the preset and fire it through WebAudio
+	* (low-latency, overlap-friendly). Fire-and-forget — no `finished`/`playing`
+	* tracking (these are short one-shots, not the element-driven `src` clip).
+	* Headless (no AudioContext) → silent no-op. WebAudio also needs a gesture;
+	* a suspended context is resumed by the same unlock listener as `src` players.
+	*/
+	playPreset() {
+		const params = SFX_PRESETS[this.preset];
+		if (!params) return;
+		const sfx = this.tree?.engine?.sfx;
+		if (!sfx) return;
+		sfx.play(params, this.gain(), {
+			pitch: this.pitch,
+			seed: this.seed,
+			spatial: this.spatialPlay()
+		});
+	}
+	stop() {
+		if (this.element) {
+			this.element.pause();
+			this.element.currentTime = 0;
+		}
+		this._playing = false;
+		this.pendingGesture = false;
+	}
+	/** Replay a gesture-blocked play (wired to the first user gesture). */
+	retryPending() {
+		if (this.pendingGesture) this.play();
+	}
+	update(_dt) {
+		if (this.autoplay && !this.autoplayed) {
+			this.autoplayed = true;
+			this.play();
+		}
+		if (this.element && this._playing) {
+			this.element.volume = this.gain() * this.spatialElementGain();
+			this.element.loop = this.loop;
+		}
+	}
+};
 //#endregion
-//#region src/core/order-groups.ts
-const ORDER_GROUP_BASE = {
-	background: -2e3,
-	terrain: -1e3,
-	default: 0,
-	characters: 1e3,
-	effects: 2e3,
-	overlay: 3e3
+//#region src/core/nodes/hud.ts
+const ANCHOR_CSS = {
+	topLeft: "left:16px;top:16px;align-items:flex-start;",
+	top: "left:50%;top:16px;transform:translateX(-50%);align-items:center;",
+	topRight: "right:16px;top:16px;align-items:flex-end;",
+	left: "left:16px;top:50%;transform:translateY(-50%);align-items:flex-start;",
+	center: "left:50%;top:50%;transform:translate(-50%,-50%);align-items:center;",
+	right: "right:16px;top:50%;transform:translateY(-50%);align-items:flex-end;",
+	bottomLeft: "left:16px;bottom:16px;align-items:flex-start;",
+	bottom: "left:50%;bottom:16px;transform:translateX(-50%);align-items:center;",
+	bottomRight: "right:16px;bottom:16px;align-items:flex-end;"
 };
-/** base + fine offset (unknown group names fall back to `default`). */
-function effectiveOrder(group, renderOrder) {
-	return (ORDER_GROUP_BASE[group] ?? 0) + renderOrder;
+const FONT = "600 14px system-ui, -apple-system, 'Segoe UI', sans-serif";
+function hasDom() {
+	return typeof document !== "undefined";
 }
-//#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"
+/**
+* The overlay container. One per scene is plenty; widgets mount into its
+* anchor slots. `zIndex` lifts it above game canvases; the layer never eats
+* pointer events (widgets that need clicks opt in individually).
+*/
+var HudLayer = class extends Node {
+	static typeName = "HudLayer";
+	static props = {
+		zIndex: { default: 100 },
+		visible: { default: true }
+	};
+	zIndex = 100;
+	visible = true;
+	/** @internal root overlay element (null headless). */
+	_element = null;
+	slots = /* @__PURE__ */ new Map();
+	onEnterTree() {
+		if (!hasDom()) return;
+		const el = document.createElement("div");
+		el.dataset.incantoHud = this.name;
+		el.style.cssText = `position:fixed;inset:0;pointer-events:none;z-index:${this.zIndex};font:${FONT};`;
+		document.body.appendChild(el);
+		this._element = el;
+	}
+	onExitTree() {
+		this._element?.remove();
+		this._element = null;
+		this.slots.clear();
+	}
+	update() {
+		if (this._element) this._element.style.display = this.visible ? "" : "none";
+	}
+	/** @internal Widgets mount into per-anchor flex columns. */
+	_slot(anchor) {
+		if (!this._element) return null;
+		let slot = this.slots.get(anchor);
+		if (!slot) {
+			slot = document.createElement("div");
+			slot.style.cssText = `position:absolute;display:flex;flex-direction:column;gap:8px;${ANCHOR_CSS[anchor] ?? ANCHOR_CSS.topLeft}`;
+			this._element.appendChild(slot);
+			this.slots.set(anchor, slot);
+		}
+		return slot;
+	}
+};
+/** Shared plumbing: mount into the parent HudLayer's anchor slot. */
+var HudWidgetBase = class extends Node {
+	static props = {
+		anchor: {
+			default: "topLeft",
+			options: [
+				"topLeft",
+				"top",
+				"topRight",
+				"left",
+				"center",
+				"right",
+				"bottomLeft",
+				"bottom",
+				"bottomRight"
+			]
+		},
+		visible: { default: true }
+	};
+	anchor = "topLeft";
+	visible = true;
+	/** @internal */
+	_element = null;
+	layer() {
+		for (let p = this.parent; p; p = p.parent) if (p instanceof HudLayer) return p;
+		return null;
+	}
+	onReady() {
+		if (!hasDom()) return;
+		const slot = this.layer()?._slot(this.anchor);
+		if (!slot) return;
+		this._element = this._build();
+		slot.appendChild(this._element);
+	}
+	onExitTree() {
+		this._element?.remove();
+		this._element = null;
+	}
+	update(_dt) {
+		if (!this._element) return;
+		this._element.style.display = this.visible ? "" : "none";
+		this._sync();
+	}
+	_sync() {}
+};
+/** A text line (score, timer, hints). Set `.text` from behaviors. */
+var UiText = class extends HudWidgetBase {
+	static typeName = "UiText";
+	static props = {
+		...HudWidgetBase.props,
+		text: { default: "" },
+		size: { default: 16 },
+		color: { default: "#ffffff" },
+		shadow: { default: true }
+	};
+	text = "";
+	size = 16;
+	color = "#ffffff";
+	shadow = true;
+	last = "\0";
+	_build() {
+		const el = document.createElement("div");
+		el.style.cssText = `font-size:${this.size}px;color:${this.color};${this.shadow ? "text-shadow:0 1px 3px rgba(0,0,0,.7);" : ""}white-space:pre;`;
+		return el;
+	}
+	_sync() {
+		if (this.text !== this.last && this._element) {
+			this.last = this.text;
+			this._element.textContent = this.text;
+		}
+	}
+};
+/** A labeled progress bar (health, stamina, reload, boss HP). */
+var UiBar = class extends HudWidgetBase {
+	static typeName = "UiBar";
+	static props = {
+		...HudWidgetBase.props,
+		value: { default: 100 },
+		max: { default: 100 },
+		width: { default: 180 },
+		height: { default: 14 },
+		color: { default: "#4ade80" },
+		lowColor: { default: "#ef4444" },
+		lowThreshold: { default: .3 },
+		background: { default: "rgba(0,0,0,0.5)" },
+		label: { default: "" }
+	};
+	value = 100;
+	max = 100;
+	width = 180;
+	height = 14;
+	color = "#4ade80";
+	lowColor = "#ef4444";
+	lowThreshold = .3;
+	background = "rgba(0,0,0,0.5)";
+	label = "";
+	fill = null;
+	lastRatio = -1;
+	/** Current fill ratio 0..1 (what the bar shows). */
+	get ratio() {
+		return this.max > 0 ? Math.min(1, Math.max(0, this.value / this.max)) : 0;
+	}
+	_build() {
+		const wrap = document.createElement("div");
+		wrap.style.cssText = "display:flex;align-items:center;gap:6px;";
+		if (this.label) {
+			const tag = document.createElement("span");
+			tag.textContent = this.label;
+			tag.style.cssText = "color:#fff;font-size:12px;text-shadow:0 1px 3px rgba(0,0,0,.7);";
+			wrap.appendChild(tag);
+		}
+		const track = document.createElement("div");
+		track.style.cssText = `width:${this.width}px;height:${this.height}px;background:${this.background};border-radius:${this.height / 2}px;overflow:hidden;`;
+		this.fill = document.createElement("div");
+		this.fill.style.cssText = `height:100%;width:100%;background:${this.color};border-radius:inherit;transition:width .15s;`;
+		track.appendChild(this.fill);
+		wrap.appendChild(track);
+		return wrap;
+	}
+	_sync() {
+		const r = this.ratio;
+		if (r === this.lastRatio || !this.fill) return;
+		this.lastRatio = r;
+		this.fill.style.width = `${r * 100}%`;
+		this.fill.style.background = r <= this.lowThreshold ? this.lowColor : this.color;
 	}
 };
-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.
+* Center-screen announcements ("WAVE 2", "YOU DIED", "LEVEL UP") with fade
+* in/out and a queue — call `.show(text, { color, seconds })`; `sticky:true`
+* (seconds: 0) keeps it until the next show(). Emits `bannerShown(text)`.
 */
-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;
+var UiBanner = class extends HudWidgetBase {
+	static typeName = "UiBanner";
+	static signals = ["bannerShown"];
+	static props = {
+		...HudWidgetBase.props,
+		anchor: {
+			default: "center",
+			options: [
+				"topLeft",
+				"top",
+				"topRight",
+				"left",
+				"center",
+				"right",
+				"bottomLeft",
+				"bottom",
+				"bottomRight"
+			]
+		},
+		size: { default: 42 },
+		seconds: { default: 2 }
+	};
+	anchor = "center";
+	size = 42;
+	/** Default display time (per-show override via options). */
+	seconds = 2;
+	queue = [];
+	current = null;
+	remaining = 0;
+	/** What the banner is showing right now ('' when idle) — test-friendly. */
+	get showing() {
+		return this.current?.text ?? "";
+	}
+	show(text, opts) {
+		this.queue.push({
+			text,
+			color: opts?.color ?? "#ffffff",
+			seconds: opts?.seconds ?? this.seconds
+		});
 	}
-}
-//#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);
-	}
-	/** Change the emission rate LIVE (particles/sec; 0 pauses emission) — lets an
-	* emitter toggle on/off at runtime (drift smoke, throttle flames). */
-	setRate(rate) {
-		this.config.rate = rate;
-		if (rate <= 0) this.spawnAccumulator = 0;
-	}
-	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();
+	/** Drop everything (scene transitions). */
+	clear() {
+		this.queue.length = 0;
+		this.current = null;
+		this.remaining = 0;
+		if (this._element) this._element.style.opacity = "0";
+	}
+	_build() {
+		const el = document.createElement("div");
+		el.style.cssText = `font-size:${this.size}px;font-weight:800;color:#fff;text-shadow:0 2px 12px rgba(0,0,0,.8);opacity:0;transition:opacity .25s;text-align:center;`;
+		return el;
 	}
 	update(dt) {
-		if (this.config.rate > 0) {
-			this.spawnAccumulator += this.config.rate * dt;
-			while (this.spawnAccumulator >= 1) {
-				this.spawnAccumulator -= 1;
-				this.spawn();
-			}
+		super.update(dt);
+		if (this.current) {
+			if (this.current.seconds > 0) {
+				this.remaining -= dt;
+				if (this.remaining <= 0) {
+					this.current = null;
+					if (this._element) this._element.style.opacity = "0";
+				}
+			} else if (this.queue.length > 0) this.current = null;
 		}
-		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;
+		if (!this.current && this.queue.length > 0) {
+			this.current = this.queue.shift();
+			this.remaining = this.current.seconds;
+			if (this._element) {
+				this._element.textContent = this.current.text;
+				this._element.style.color = this.current.color;
+				this._element.style.opacity = "1";
 			}
-			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;
+			this.emit("bannerShown", this.current.text);
 		}
 	}
-	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]
-			});
+};
+//#endregion
+//#region src/core/nodes/dialogue.ts
+/**
+* Interactive HUD: clickable buttons and a typewriter dialogue box — the
+* storytelling layer RPG/adventure games kept hand-rolling in DOM.
+* Same family as the other HUD widgets: children of a HudLayer, DOM-backed,
+* silent no-ops headless.
+*/
+/** A clickable button (menus, "START", dialog choices). Emits `pressed`. */
+var UiButton = class extends HudWidgetBase {
+	static typeName = "UiButton";
+	static signals = ["pressed"];
+	static props = {
+		...HudWidgetBase.props,
+		text: { default: "OK" },
+		size: { default: 16 },
+		color: { default: "#ffffff" },
+		background: { default: "rgba(255,255,255,0.14)" },
+		disabled: { default: false }
+	};
+	text = "OK";
+	size = 16;
+	color = "#ffffff";
+	background = "rgba(255,255,255,0.14)";
+	disabled = false;
+	lastText = "";
+	/** Programmatic press — same path as a click (tests, gamepad menus). */
+	press() {
+		if (this.disabled) return;
+		this.emit("pressed");
+	}
+	_build() {
+		const el = document.createElement("button");
+		el.type = "button";
+		el.style.cssText = `pointer-events:auto;cursor:pointer;font:600 ${this.size}px system-ui,sans-serif;color:${this.color};background:${this.background};border:1px solid rgba(255,255,255,0.25);border-radius:8px;padding:8px 18px;transition:transform .08s, background .15s;`;
+		el.addEventListener("mouseenter", () => {
+			if (!this.disabled) el.style.background = "rgba(255,255,255,0.24)";
+		});
+		el.addEventListener("mouseleave", () => {
+			el.style.background = this.background;
+		});
+		el.addEventListener("pointerdown", () => {
+			if (!this.disabled) el.style.transform = "scale(0.95)";
+		});
+		el.addEventListener("pointerup", () => {
+			el.style.transform = "";
+		});
+		el.addEventListener("click", () => this.press());
+		return el;
+	}
+	_sync() {
+		if (!this._element) return;
+		if (this.text !== this.lastText) {
+			this.lastText = this.text;
+			this._element.textContent = this.text;
+		}
+		this._element.disabled = this.disabled;
+		this._element.style.opacity = this.disabled ? "0.45" : "1";
+	}
+};
+/**
+* A typewriter dialogue box with a queue and choices:
+*
+*   const talk = node.getNode('%Dialogue') as UiDialogue;
+*   talk.say('Elder', 'Welcome to Lumina Village...');
+*   talk.say('Elder', 'Will you help us?', ['Yes', 'No']);
+*   talk.on('choiceMade', (index) => { ... });
+*
+* Click / `advance()` reveals the full line, then advances. Emits
+* `lineShown(text)`, `choiceMade(index)`, `dialogueFinished()`.
+*/
+var UiDialogue = class extends HudWidgetBase {
+	static typeName = "UiDialogue";
+	static signals = [
+		"lineShown",
+		"choiceMade",
+		"dialogueFinished"
+	];
+	static props = {
+		...HudWidgetBase.props,
+		anchor: {
+			default: "bottom",
+			options: [
+				"topLeft",
+				"top",
+				"topRight",
+				"left",
+				"center",
+				"right",
+				"bottomLeft",
+				"bottom",
+				"bottomRight"
+			]
+		},
+		charsPerSecond: { default: 40 },
+		width: { default: 520 }
+	};
+	anchor = "bottom";
+	/** Typewriter speed; 0 = instant lines. */
+	charsPerSecond = 40;
+	width = 520;
+	queue = [];
+	current = null;
+	revealed = 0;
+	speakerEl = null;
+	textEl = null;
+	choicesEl = null;
+	hintEl = null;
+	/** True while a conversation is on screen (pause player input on this). */
+	get active() {
+		return this.current !== null || this.queue.length > 0;
+	}
+	/** What the box currently shows (grows while typing) — test-friendly. */
+	get showing() {
+		return this.current ? this.current.text.slice(0, Math.floor(this.revealed)) : "";
+	}
+	/** Queue a line; optional `choices` renders buttons after the line types out. */
+	say(speaker, text, choices) {
+		this.queue.push({
+			speaker,
+			text,
+			choices: choices ?? null
+		});
+	}
+	/**
+	* Player pressed "next": mid-typing reveals the whole line; a fully-typed
+	* line without choices advances (choice lines wait for `choose`).
+	*/
+	advance() {
+		if (!this.current) return;
+		if (this.revealed < this.current.text.length) {
+			this.revealed = this.current.text.length;
+			return;
+		}
+		if (this.current.choices) return;
+		this.next();
+	}
+	/** Pick a choice on the current line (buttons call this). */
+	choose(index) {
+		if (!this.current?.choices) return;
+		if (index < 0 || index >= this.current.choices.length) return;
+		this.emit("choiceMade", index);
+		this.next();
+	}
+	/** Drop the conversation (cutscene interrupts). */
+	clear() {
+		this.queue.length = 0;
+		this.current = null;
+		this.revealed = 0;
+		if (this._element) this._element.style.display = "none";
+	}
+	next() {
+		this.current = null;
+		this.revealed = 0;
+		if (this.queue.length === 0) {
+			if (this._element) this._element.style.display = "none";
+			this.emit("dialogueFinished");
 		}
 	}
-	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;
+	_build() {
+		const box = document.createElement("div");
+		box.style.cssText = `pointer-events:auto;width:${this.width}px;max-width:86vw;background:rgba(12,14,22,0.92);border:1px solid rgba(255,255,255,0.2);border-radius:12px;padding:14px 18px;display:none;font:15px/1.5 system-ui,sans-serif;color:#fff;cursor:pointer;user-select:none;`;
+		this.speakerEl = document.createElement("div");
+		this.speakerEl.style.cssText = "font-weight:800;color:#ffd166;margin-bottom:4px;font-size:13px;";
+		this.textEl = document.createElement("div");
+		this.textEl.style.cssText = "min-height:3em;white-space:pre-wrap;";
+		this.choicesEl = document.createElement("div");
+		this.choicesEl.style.cssText = "display:flex;gap:8px;margin-top:10px;flex-wrap:wrap;";
+		this.hintEl = document.createElement("div");
+		this.hintEl.textContent = "▼";
+		this.hintEl.style.cssText = "text-align:right;opacity:0.5;font-size:11px;animation:none;";
+		box.append(this.speakerEl, this.textEl, this.choicesEl, this.hintEl);
+		box.addEventListener("click", () => this.advance());
+		return box;
+	}
+	update(dt) {
+		super.update(dt);
+		if (!this.current && this.queue.length > 0) {
+			this.current = this.queue.shift();
+			this.revealed = this.charsPerSecond <= 0 ? this.current.text.length : 0;
+			this.emit("lineShown", this.current.text);
+			if (this._element) {
+				this._element.style.display = "block";
+				if (this.speakerEl) this.speakerEl.textContent = this.current.speaker;
+				if (this.choicesEl) this.choicesEl.replaceChildren();
+			}
+		}
+		if (!this.current) return;
+		const wasTyping = this.revealed < this.current.text.length;
+		if (wasTyping) this.revealed = Math.min(this.current.text.length, this.revealed + this.charsPerSecond * dt);
+		const doneTyping = this.revealed >= this.current.text.length;
+		if (this.textEl) this.textEl.textContent = this.showing;
+		if (this.hintEl) this.hintEl.style.visibility = doneTyping && !this.current.choices ? "visible" : "hidden";
+		if (doneTyping && wasTyping && this.current.choices && this.choicesEl) this.current.choices.forEach((label, i) => {
+			const b = document.createElement("button");
+			b.type = "button";
+			b.textContent = label;
+			b.style.cssText = "pointer-events:auto;cursor:pointer;font:600 13px system-ui,sans-serif;color:#fff;background:rgba(255,255,255,0.12);border:1px solid rgba(255,255,255,0.3);border-radius:8px;padding:6px 14px;";
+			b.addEventListener("click", (e) => {
+				e.stopPropagation();
+				this.choose(i);
+			});
+			this.choicesEl?.appendChild(b);
+		});
 	}
 };
 //#endregion
-export { ORDER_GROUP_BASE as a, LogManager as c, isAudioContextAvailable as d, MusicManager as f, AudioBuses as g, fadeGain as h, applyParticlePreset as i, InputMap as l, crossfadeGains as m, PARTICLE_PRESETS as n, effectiveOrder as o, WebAudioMusicBackend as p, PARTICLE_PRESET_NAMES as r, Engine as s, ParticleSim as t, SfxEngine as u };
+//#region src/core/nodes/timer.ts
+/**
+* The canonical serializable game clock — never `setTimeout` in game logic.
+* Emits `timeout` every `waitTime` seconds (once with `oneShot`).
+*/
+var Timer = class extends Node {
+	static typeName = "Timer";
+	static signals = ["timeout"];
+	static props = {
+		waitTime: { default: 1 },
+		oneShot: { default: false },
+		autostart: { default: false }
+	};
+	/** Seconds between timeouts. */
+	waitTime = 1;
+	oneShot = false;
+	autostart = false;
+	running = false;
+	remaining = 0;
+	start(time) {
+		if (time !== void 0) this.waitTime = time;
+		this.remaining = this.waitTime;
+		this.running = true;
+	}
+	stop() {
+		this.running = false;
+	}
+	onReady() {
+		if (this.autostart) this.start();
+	}
+	update(dt) {
+		if (!this.running) return;
+		if (this.waitTime <= 0) {
+			this.stop();
+			return;
+		}
+		this.remaining -= dt;
+		while (this.remaining <= 0 && this.running) {
+			this.emit("timeout");
+			if (this.oneShot) this.stop();
+			else if (this.waitTime <= 0) this.stop();
+			else this.remaining += this.waitTime;
+		}
+	}
+};
+//#endregion
+//#region src/core/register.ts
+/**
+* Register the core node types. Call once in your game entry before loading
+* scenes. Registration is explicit — never an import-time side effect — so
+* bundler tree-shaking can never silently drop node types.
+*/
+function registerCoreNodes() {
+	registerNode(Node);
+	registerNode(Timer);
+	registerNode(AudioPlayer);
+	registerNode(HudLayer);
+	registerNode(UiText);
+	registerNode(UiBar);
+	registerNode(UiBanner);
+	registerNode(UiButton);
+	registerNode(UiDialogue);
+}
+//#endregion
+export { crossfadeGains as C, WebAudioMusicBackend as S, AudioBuses as T, spatialPan as _, HudLayer as a, synthSfx as b, UiText as c, LogManager as d, InputMap as f, spatialGain as g, ROLLOFF_MODELS as h, UiDialogue as i, AudioPlayer as l, isAudioContextAvailable as m, Timer as n, UiBanner as o, SfxEngine as p, UiButton as r, UiBar as s, registerCoreNodes as t, Engine as u, SFX_PRESETS as v, fadeGain as w, MusicManager as x, SFX_PRESET_NAMES as y };