incanto 0.56.0 → 0.57.0

package/dist/{register-p48lHE2o.js → register-Ch70uByv.js}

@@ -1,4 +1,4 @@
-import { C as diagnose, M as Signal, S as InputMap, f as Node, g as restoreBehaviors, h as captureBehaviors, v as createSaveStore, x as resolveOrderGroups, y as ORDER_GROUP_BASE } from "./loader-BTkHYrQn.js";
+import { C as diagnose, M as Signal, S as Node, _ as createSaveStore, b as resolveOrderGroups, h as restoreBehaviors, m as captureBehaviors, v as ORDER_GROUP_BASE, x as InputMap } from "./loader-BcrRSjxB.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { l as registerNode } from "./registry-C7u42TID.js";
@@ -153,10 +153,15 @@ const INERT$1 = {
 var WebAudioTrack = class {
 	src;
 	el;
+	onError;
 	gainNode;
-	constructor(src, el, ctx) {
+	constructor(src, el, ctx, onError) {
 		this.src = src;
 		this.el = el;
+		this.onError = onError;
+		el.addEventListener?.("error", () => {
+			this.fail(`could not load ${src}`);
+		});
 		try {
 			el.crossOrigin = "anonymous";
 		} catch {}
@@ -173,8 +178,18 @@ var WebAudioTrack = class {
 		this.el.loop = loop;
 	}
 	play() {
-		this.el.play().catch(() => {});
+		this.el.play().catch((error) => {
+			const name = error?.name ?? "";
+			if (name === "NotSupportedError") this.fail(`${name}: ${this.src}`);
+		});
+	}
+	/** Report ONCE — a track that cannot play must not spam a per-frame tick. */
+	fail(reason) {
+		if (this.failed) return;
+		this.failed = true;
+		this.onError?.(this.src, reason);
 	}
+	failed = false;
 	stop() {
 		this.el.pause();
 		this.el.currentTime = 0;
@@ -194,6 +209,9 @@ var WebAudioMusicBackend = class {
 		}
 		return this.ctx;
 	}
+	/** Told when a track will never play. Set by the manager, which knows the
+	*  engine that owns the log. */
+	onTrackError = null;
 	createTrack(src) {
 		const ctx = this.ensure();
 		const el = createElement$1();
@@ -202,7 +220,7 @@ var WebAudioMusicBackend = class {
 			src
 		};
 		if (ctx.state === "suspended") ctx.resume();
-		return new WebAudioTrack(src, el, ctx);
+		return new WebAudioTrack(src, el, ctx, (s, reason) => this.onTrackError?.(s, reason));
 	}
 	unlock() {
 		const ctx = this.ensure();
@@ -280,10 +298,19 @@ var MusicManager = class {
 		if (!this.resolved) {
 			const b = new WebAudioMusicBackend();
 			this.backend = b && b.available === false ? null : b;
+			const withErrors = this.backend;
+			if (withErrors && "onTrackError" in withErrors) withErrors.onTrackError = (src, reason) => {
+				this.onTrackError?.(src, reason);
+			};
 			this.resolved = true;
 		}
 		return this.backend ?? SILENT_BACKEND;
 	}
+	/**
+	* Where a track that will never play gets reported. The engine sets this; a
+	* bare MusicManager (tests) stays quiet.
+	*/
+	onTrackError = null;
 	/** Resume a gesture-suspended context + (re)start any pending track. */
 	unlock() {
 		this.ensure()?.unlock();
@@ -1156,1669 +1183,1733 @@ function suggestLocale(available, languages) {
 	return "en";
 }
 //#endregion
-//#region src/core/effects-log.ts
-const EFFECT_LOG_LIMIT = 200;
-var EffectLog = class {
-	events = [];
-	/** @internal Called by the effects themselves; games read `recent()`. */
-	record(event) {
-		this.events.push(event);
-		if (this.events.length > EFFECT_LOG_LIMIT) this.events.shift();
-	}
-	/** The last `limit` effects, oldest first. */
-	recent(limit = EFFECT_LOG_LIMIT) {
-		return this.events.slice(Math.max(0, this.events.length - limit));
-	}
-	/** How many times an effect with this name fired (`explosion`, `#ff0000`). */
-	countOf(name) {
-		return this.events.reduce((n, e) => e.name === name ? n + 1 : n, 0);
-	}
-	/** How many effects this node fired — the question a wiring check has. */
-	countFrom(path) {
-		return this.events.reduce((n, e) => e.from === path ? n + 1 : n, 0);
-	}
-	/** Forget what has fired so far (between scenes, or between assertions). */
-	clearLog() {
-		this.events.length = 0;
-	}
+//#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;"
 };
-//#endregion
-//#region src/core/frame-stats.ts
+const FONT = "600 14px system-ui, -apple-system, 'Segoe UI', sans-serif";
+function hasDom() {
+	return typeof document !== "undefined";
+}
 /**
-* 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.
+* 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 FrameStatsRing = class {
-	capacity;
-	times;
-	head = 0;
-	count = 0;
-	constructor(capacity = 60) {
-		this.capacity = capacity;
-		this.times = new Array(capacity);
+var HudLayer = class extends Node {
+	static typeName = "HudLayer";
+	static props = {
+		zIndex: { default: 100 },
+		visible: { default: true },
+		/**
+		* Arrow keys / d-pad move focus between the focusable widgets under this
+		* layer, Enter / A activates. OFF by default — a game whose HUD has a
+		* button must not lose its arrow keys the moment one exists.
+		*/
+		focusNavigation: { default: false }
+	};
+	zIndex = 100;
+	visible = true;
+	focusNavigation = false;
+	/** @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};`;
+		this._element = el;
+		this._mount();
 	}
-	/** 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;
+	/**
+	* Put the overlay where the page's owner says UI goes: `engine.uiHost`, or
+	* the window when nobody claims it (a game — a HUD covers the screen).
+	*
+	* Re-checked every frame because a scene's tree is BUILT before it is handed
+	* to an engine: at onEnterTree there is no engine to ask yet, so the first
+	* update is where the answer actually arrives. appendChild moves the element
+	* if it already landed somewhere else, so the HUD follows the host across a
+	* scene swap into a differently-hosted engine (game → editor) instead of
+	* being stranded on document.body over the inspector.
+	*/
+	_mount() {
+		const el = this._element;
+		if (!el) return;
+		const host = this.tree?.engine?.uiHost ?? document.body;
+		if (el.parentElement === host) return;
+		el.style.position = host === document.body ? "fixed" : "absolute";
+		host.appendChild(el);
 	}
-	/** 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;
+	onExitTree() {
+		this._element?.remove();
+		this._element = null;
+		this.slots.clear();
 	}
-	/** 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;
+	update() {
+		if (this._element) {
+			this._mount();
+			this._element.style.display = this.visible ? "" : "none";
+		}
+		if (this.focusNavigation) this.stepFocus();
 	}
-	/** Forget all samples (engine.stop() — a paused game has no frame rate). */
-	clear() {
-		this.head = 0;
-		this.count = 0;
+	/**
+	* Arrow keys / d-pad move the focus, Enter / A activates it.
+	*
+	* Off by default: a game whose HUD has a button must not lose its arrow keys
+	* to a menu the moment one exists. Turn it on for the screens that ARE menus
+	* (`"focusNavigation": true` on the pause panel's layer), and off again when
+	* play resumes.
+	*/
+	stepFocus() {
+		const engine = this.tree?.engine;
+		if (!engine) return;
+		const items = this.focusables();
+		if (items.length === 0) return;
+		const input = engine.input;
+		const down = input.keyJustPressed("ArrowDown") || input.keyJustPressed("Pad13");
+		const up = input.keyJustPressed("ArrowUp") || input.keyJustPressed("Pad12");
+		const left = input.keyJustPressed("ArrowLeft") || input.keyJustPressed("Pad14");
+		const right = input.keyJustPressed("ArrowRight") || input.keyJustPressed("Pad15");
+		const confirm = input.keyJustPressed("Enter") || input.keyJustPressed("Pad0");
+		let index = items.findIndex((w) => w._focused);
+		if (index === -1 && (down || up || confirm)) index = 0;
+		else if (down) index = (index + 1) % items.length;
+		else if (up) index = (index - 1 + items.length) % items.length;
+		if (index !== -1) {
+			for (const w of items) {
+				const next = w === items[index];
+				if (next !== w._focused) {
+					w._focused = next;
+					w._paintFocus();
+				}
+			}
+			const focused = items[index];
+			if (focused) {
+				if (confirm) focused._activate(0);
+				else if (left) focused._activate(-1);
+				else if (right) focused._activate(1);
+			}
+		}
 	}
-	spanMs() {
-		if (this.count < 2) return 0;
-		const oldest = this.times[this.head];
-		return this.times[(this.head + this.count - 1) % this.capacity] - oldest;
+	/** Focusable widgets under this layer, in tree order. */
+	focusables() {
+		const out = [];
+		const walk = (node) => {
+			if (node instanceof HudWidgetBase && node.focusable && node.visible) out.push(node);
+			for (const child of node.children) walk(child);
+		};
+		walk(this);
+		return out;
+	}
+	/** Move focus to a widget by hand — opening a menu should start somewhere. */
+	focus(widget) {
+		for (const w of this.focusables()) {
+			const next = w === widget;
+			if (next !== w._focused) {
+				w._focused = next;
+				w._paintFocus();
+			}
+		}
+	}
+	/** @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;
 	}
 };
-//#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.
+* The widget an element belongs to.
+*
+* A pick lands on whatever div is under the cursor — usually a CHILD of the
+* widget (an icon inside a slot), so the walk upward is the point.
 */
-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);
+const widgetOf = /* @__PURE__ */ new WeakMap();
+function widgetFromElement(el) {
+	for (let n = el; n; n = n.parentElement) {
+		const found = widgetOf.get(n);
+		if (found) return found;
 	}
-	warn(...parts) {
-		this.push("warn", parts);
+	return null;
+}
+/** The drag in flight, if any. One pointer, one drag. */
+let dragging = null;
+/** Shared plumbing: mount into the parent HudLayer's anchor slot. */
+var HudWidgetBase = class extends Node {
+	/**
+	* Wireable visibility: `noSave → Continue.hide`.
+	*
+	* `visible` is a prop, and a `connections[]` handler has to be a METHOD — the
+	* same wall that kept a score off the screen until widgets grew `setText`. A
+	* title screen greying out its own Continue button is the case that asked.
+	*/
+	show(..._args) {
+		this.visible = true;
 	}
-	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/phase-timing.ts
-const EMPTY = {
-	fixedMs: 0,
-	updateMs: 0,
-	renderMs: 0,
-	otherMs: 0
-};
-var PhaseTimings = class {
-	capacity;
-	fixed = [];
-	update = [];
-	render = [];
-	head = 0;
-	constructor(capacity = 60) {
-		this.capacity = capacity;
-	}
-	/** Bank one frame's engine-side work. */
-	push(fixedMs, updateMs, renderMs) {
-		const i = this.head % this.capacity;
-		this.fixed[i] = fixedMs;
-		this.update[i] = updateMs;
-		this.render[i] = renderMs;
-		this.head += 1;
-	}
-	/** Means over the window; `frameMs` (0 headless) fills in `otherMs`. */
-	read(frameMs) {
-		const n = Math.min(this.head, this.capacity);
-		if (n === 0) return { ...EMPTY };
-		const fixedMs = mean(this.fixed, n);
-		const updateMs = mean(this.update, n);
-		const renderMs = mean(this.render, n);
-		return {
-			fixedMs,
-			updateMs,
-			renderMs,
-			otherMs: Math.max(0, frameMs - fixedMs - updateMs - renderMs)
-		};
-	}
-	clear() {
-		this.fixed.length = 0;
-		this.update.length = 0;
-		this.render.length = 0;
-		this.head = 0;
-	}
-};
-function mean(values, n) {
-	let total = 0;
-	for (let i = 0; i < n; i++) total += values[i] ?? 0;
-	return total / n;
-}
-//#endregion
-//#region src/core/settings.ts
-const DEFAULTS = {
-	master: 1,
-	sfx: 1,
-	music: 1,
-	muted: false,
-	quality: "high",
-	sensitivity: 1,
-	invertY: false,
-	reduceMotion: false,
-	language: "en",
-	qualityChosen: false,
-	maxFps: 0,
-	renderScale: 1
-};
-const TIERS = [
-	"low",
-	"medium",
-	"high"
-];
-/**
-* A default tier from what the browser will admit to.
-*
-* Deliberately crude: this picks a STARTING point, and the options menu is the
-* real answer. A phone that reports four cores and a coarse pointer should not
-* open on the setting tuned for a desktop GPU.
-*/
-function suggestQuality(hints) {
-	const cores = hints.hardwareConcurrency ?? 8;
-	const memory = hints.deviceMemory ?? 8;
-	if (hints.coarsePointer && (cores <= 6 || memory <= 4)) return "low";
-	if (cores <= 4 || memory <= 4 || (hints.maxTextureSize ?? 8192) < 8192) return "low";
-	if (cores <= 8 || memory <= 8) return "medium";
-	return "high";
-}
-/** Read what this environment will tell us, safely, without touching WebGL. */
-function readDeviceHints() {
-	const nav = globalThis.navigator;
-	const mm = globalThis.matchMedia;
-	const out = {};
-	if (typeof nav?.hardwareConcurrency === "number") out.hardwareConcurrency = nav.hardwareConcurrency;
-	if (typeof nav?.deviceMemory === "number") out.deviceMemory = nav.deviceMemory;
-	try {
-		if (mm) out.coarsePointer = mm("(pointer: coarse)").matches;
-	} catch {}
-	return out;
-}
-var Settings = class {
-	/** Fires after any change, with the key that changed. */
-	changed = new Signal();
-	store;
-	values;
-	constructor(namespace = "settings", store) {
-		this.store = store ?? createSaveStore(namespace);
-		this.values = { ...DEFAULTS };
-		for (const key of Object.keys(DEFAULTS)) {
-			const saved = this.store.get(key, DEFAULTS[key]);
-			this.values[key] = saved;
-		}
-		if (!TIERS.includes(this.values.quality)) this.values.quality = DEFAULTS.quality;
-	}
-	get(key) {
-		return this.values[key];
-	}
-	set(key, value) {
-		if (this.values[key] === value) return;
-		this.values[key] = value;
-		this.store.set(key, value);
-		this.changed.emit(key);
-	}
-	/** Every value at once — for an options screen, or a save-file dump. */
-	all() {
-		return { ...this.values };
-	}
-	/** Back to defaults, on disk too. */
-	reset() {
-		for (const key of Object.keys(DEFAULTS)) this.set(key, DEFAULTS[key]);
+	hide() {
+		this.visible = false;
 	}
+	static props = {
+		anchor: {
+			default: "topLeft",
+			options: [
+				"topLeft",
+				"top",
+				"topRight",
+				"left",
+				"center",
+				"right",
+				"bottomLeft",
+				"bottom",
+				"bottomRight"
+			]
+		},
+		visible: { default: true },
+		/**
+		* Can menu navigation land on this? Interactive widgets default to true.
+		*
+		* A menu you can only click is not playable on a controller, and "add
+		* gamepad support" is not a thing a JSON scene could express at all.
+		*/
+		focusable: { default: false },
+		/**
+		* Can the player pick this up and drop it somewhere? An inventory item is
+		* a `draggable` widget; a slot is a `dropTarget`.
+		*/
+		draggable: { default: false },
+		/** Can something be dropped ON this? */
+		dropTarget: { default: false }
+	};
+	static signals = [
+		"dragStarted",
+		"dragCancelled",
+		"droppedOn",
+		"dropped"
+	];
+	anchor = "topLeft";
+	visible = true;
+	focusable = false;
+	draggable = false;
+	dropTarget = false;
+	/** @internal Set by the owning HudLayer while this widget has focus. */
+	_focused = false;
 	/**
-	* Choose a starting tier from the device, ONCE.
-	*
-	* Only on a first visit: after someone has picked a tier, re-detecting on
-	* every launch would silently undo their choice — which is the behaviour every
-	* player experiences as "the settings do not save".
+	* @internal Confirm (`dir` 0) or nudge (-1 left / +1 right) — what pressing
+	* A or an arrow ON this widget means. Default: nothing.
 	*/
-	autoQuality(hints = readDeviceHints()) {
-		if (!this.values.qualityChosen) this.values.quality = suggestQuality(hints);
-		return this.values.quality;
+	_activate(_dir) {}
+	/** @internal Draw the focus ring. Overridable if a widget wants its own. */
+	_paintFocus() {
+		if (!this._element) return;
+		this._element.style.outline = this._focused ? "2px solid #6ee7dc" : "";
+		this._element.style.outlineOffset = this._focused ? "2px" : "";
 	}
-	/** Record that the tier came from a person, not from the device probe. */
-	chooseQuality(tier) {
-		this.set("quality", tier);
-		this.set("qualityChosen", 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;
+		this._mountWidget();
 	}
 	/**
-	* Apply the saved quality tier to a live scene, and keep applying it.
+	* @internal Build and attach, once a host exists.
 	*
-	* The same shape as `bindAudio` and `bindLocale`. Until 0.38 this did not
-	* exist: `settings.quality` was written to disk and read by NOBODY, and
-	* `qualityEnvironment` — the function that turns a tier into something the
-	* renderer understands — emitted patches the environment parser rejects, for
-	* all three tiers. Both were public, documented and never once called.
+	* A widget inside a UiPanel mounts into the PANEL, not the layer's anchor
+	* slot — that is what turns structure in the tree into structure on screen,
+	* and it is what a menu is. Ready order does not decide it: the panel builds
+	* on demand when a child asks (`_container`), and `update` retries for
+	* anything attached at runtime before its host existed.
 	*/
-	bindQuality(apply) {
-		apply(qualityEnvironment(this.values.quality));
-		return this.changed.connect((key) => {
-			if (key === "quality") apply(qualityEnvironment(this.values.quality));
-		});
+	_mountWidget() {
+		if (this._element || !hasDom()) return;
+		const host = this.host() ?? this.layer()?._slot(this.anchor);
+		if (!host) return;
+		this._element = this._build();
+		widgetOf.set(this._element, this);
+		if (this.draggable || this.dropTarget) this._wireDrag(this._element);
+		host.appendChild(this._element);
 	}
 	/**
-	* Apply the saved frame cap, and again whenever it changes.
+	* Drag and drop, on the DOM the engine already builds.
 	*
-	* Separate from `bindQuality` because it is not a tier: a player caps the
-	* frame rate to keep a phone cool or a battery alive, on the highest visual
-	* settings the device can hold, and those two choices do not belong on one
-	* slider. 0 means uncapped. Returns the unsubscribe.
-	*/
-	bindFrameCap(apply) {
-		apply(this.values.maxFps);
-		return this.changed.connect((key) => {
-			if (key === "maxFps") apply(this.values.maxFps);
-		});
+	* An inventory is the one screen where "click it" is not enough, and every
+	* game that wanted one dropped out of scene JSON to hand-roll pointer
+	* handlers. The whole gesture is four signals and no new node type: a
+	* `draggable` widget emits `dragStarted` and, if it lands on one,
+	* `droppedOn(target)`; a `dropTarget` emits `dropped(source)`. Who owns the
+	* ITEM is the game's business — this reports the gesture, not a model.
+	*/
+	_wireDrag(el) {
+		el.style.touchAction = "none";
+		if (this.draggable) {
+			el.style.cursor = "grab";
+			el.addEventListener("pointerdown", (event) => {
+				if (!this.draggable) return;
+				event.preventDefault();
+				el.setPointerCapture?.(event.pointerId);
+				dragging = this;
+				el.style.opacity = "0.6";
+				this.emit("dragStarted", this);
+			});
+			el.addEventListener("pointerup", (event) => {
+				if (dragging !== this) return;
+				el.style.opacity = "";
+				el.releasePointerCapture?.(event.pointerId);
+				const target = widgetFromElement(document.elementFromPoint?.(event.clientX, event.clientY) ?? null);
+				dragging = null;
+				if (target && target !== this && target.dropTarget) {
+					this.emit("droppedOn", target);
+					target.emit("dropped", this);
+				} else this.emit("dragCancelled", this);
+			});
+		}
+	}
+	/** The nearest ancestor that holds widgets itself (a UiPanel). */
+	host() {
+		for (let p = this.parent; p; p = p.parent) {
+			const holder = p;
+			if (typeof holder._container === "function") return holder._container();
+			if (p instanceof HudLayer) return null;
+		}
+		return null;
+	}
+	onExitTree() {
+		this._element?.remove();
+		this._element = null;
+	}
+	update(_dt) {
+		if (!this._element) {
+			this._mountWidget();
+			if (!this._element) return;
+		}
+		this._element.style.display = this.visible ? "" : "none";
+		this._followAnchor();
+		this._sync();
 	}
+	/** Which anchor slot this widget was mounted into. */
+	mountedAnchor = null;
 	/**
-	* Apply the saved resolution multiplier, and again whenever it changes.
+	* Move to the slot the anchor now names.
 	*
-	* The lever that buys the most frames per unit of ugliness on a weak GPU —
-	* shading 44% of the pixels at 0.66 costs a soft image and nothing else,
-	* while dropping a quality tier costs shadows entirely.
+	* `_mountWidget` read `anchor` once and `_element` is nulled only on
+	* `onExitTree`, so moving a widget from topLeft to bottomRight — from a
+	* behavior or from the editor's inspector, which live-patches string props —
+	* did nothing at all, forever.
 	*/
-	bindRenderScale(apply) {
-		apply(this.values.renderScale);
-		return this.changed.connect((key) => {
-			if (key === "renderScale") apply(this.values.renderScale);
-		});
+	_followAnchor() {
+		if (this.host()) return;
+		if (this.mountedAnchor === null) this.mountedAnchor = this.anchor;
+		if (this.mountedAnchor === this.anchor) return;
+		const slot = this.layer()?._slot(this.anchor);
+		if (!slot || !this._element) return;
+		this.mountedAnchor = this.anchor;
+		slot.appendChild(this._element);
 	}
+	_sync() {}
 	/**
-	* Apply the saved language, and keep it in step both ways.
+	* Resolve a text prop through the engine's locale.
 	*
-	* The same shape as `bindAudio`: a game that writes
-	* `engine.locale.locale = 'ko'` from an options menu has already persisted it
-	* without knowing this class exists. Returns the unsubscribe.
+	* Called every frame from `_sync`, which is what makes switching language
+	* repaint with nothing to invalidate: widgets already re-read their props, so
+	* the new string simply appears on the next frame. A plain string costs one
+	* `startsWith` and is returned untouched.
 	*/
-	bindLocale(locale) {
-		locale.locale = this.values.language;
-		return locale.changed.connect((next) => {
-			this.set("language", next);
-		});
+	_t(value) {
+		const locale = this.tree?.engine?.locale;
+		return locale ? locale.resolve(value) : value;
 	}
+};
+/** A text line (score, timer, hints). Set `.text` from behaviors. */
+var UiText = class extends HudWidgetBase {
+	static typeName = "UiText";
+	static props = {
+		...HudWidgetBase.props,
+		text: { default: "" },
+		format: { default: "" },
+		size: { default: 16 },
+		color: { default: "#ffffff" },
+		shadow: { default: true }
+	};
+	text = "";
 	/**
-	* Push the saved volumes into the engine's buses, and keep writing them back
-	* whenever anything changes them.
+	* A template with a `{}` slot that `setText` fills — `"Gems {} / 8"`.
 	*
-	* The subscription is the point: a game that sets `engine.audio.music = 0.4`
-	* from a slider has already persisted it, without knowing this class exists.
+	* Empty (the default) means `setText` replaces the whole line. Resolved at
+	* PAINT like `text`, so `"@t:hud.gems"` works and changing locale re-reads
+	* it: the value lives here, the words live in the strings table.
 	*/
-	bindAudio(audio) {
-		audio.master = this.values.master;
-		audio.sfx = this.values.sfx;
-		audio.music = this.values.music;
-		audio.muted = this.values.muted;
-		return audio.changed.connect(() => {
-			this.set("master", audio.master);
-			this.set("sfx", audio.sfx);
-			this.set("music", audio.music);
-			this.set("muted", audio.muted);
-		});
+	format = "";
+	size = 16;
+	color = "#ffffff";
+	shadow = true;
+	last = "\0";
+	/** null until something has actually set a value — see `shown`. */
+	slot = null;
+	/**
+	* Put a signal's value on screen — `scoreChanged → setText`.
+	*
+	* A `connections[]` handler must be a METHOD and `text` is a property, so the
+	* one wire every game needs (score to screen) could not be declared: every
+	* HUD began with a behavior whose whole job was one assignment.
+	*/
+	setText(value) {
+		this.slot = String(value ?? "");
+		if (!this.format) this.text = this.slot;
+	}
+	/**
+	* What it actually paints, after the template and the locale.
+	*
+	* Before the first value arrives, a formatted widget shows `text` — its
+	* authored opening line. Filling the slot with nothing instead would put
+	* `"Gems  / 8"` on screen for every game's first frame, and a score line
+	* that starts blank looks broken rather than empty.
+	*/
+	get shown() {
+		if (this.format && this.slot !== null) return this._t(this.format).replace("{}", this.slot);
+		return this._t(this.text);
+	}
+	_build() {
+		const el = document.createElement("div");
+		el.style.cssText = this.look();
+		this.lastLook = this.look();
+		return el;
+	}
+	/** The whole appearance as one string, so re-applying is one comparison. */
+	look() {
+		return `font-size:${this.size}px;color:${this.color};${this.shadow ? "text-shadow:0 1px 3px rgba(0,0,0,.7);" : ""}white-space:pre;`;
+	}
+	lastLook = "";
+	_sync() {
+		const shown = this.shown;
+		if (shown !== this.last && this._element) {
+			this.last = shown;
+			this._element.textContent = shown;
+		}
+		const look = this.look();
+		if (look !== this.lastLook && this._element) {
+			this.lastLook = look;
+			this._element.style.cssText = look;
+		}
 	}
 };
 /**
-* What a quality tier MEANS, as a LIVE environment patch.
-*
-* Only the levers that actually cost: shadows, post, bloom and clouds.
-* Deliberately an `environment` patch, because `setEnvironment3D(engine, patch)`
-* already applies one live and validated — this is not a second rendering
-* pipeline, it is three presets for the one that exists.
-*
-* The `off` spelling matters and got this wrong for three releases: every tier
-* emitted `{ enabled: false }`, which the environment parser rejects
-* (`environment.bloom has unknown key 'enabled'`). Nothing called this function,
-* so nothing found out. In a live patch `null` DELETES a key — that is how a
-* stage is turned off — and `shadows` alone takes a real `false`.
-*
-* Antialiasing and pixel ratio are NOT here: `antialias` is a WebGL context
-* attribute and cannot change without rebuilding the renderer. See
-* `qualityRendering`.
-*/
-function qualityEnvironment(tier) {
-	if (tier === "low") return {
-		shadows: false,
-		bloom: null,
-		post: null,
-		clouds: null
-	};
-	if (tier === "medium") return {
-		shadows: { static: true },
-		bloom: {},
-		post: null
-	};
-	return {
-		shadows: true,
-		bloom: {},
-		post: {}
-	};
-}
-const QUALITY_CAPS = Object.freeze({
-	low: Object.freeze({
-		fancyWater: false,
-		waterMirror: false,
-		minReflectionIntervalMs: 2e3
-	}),
-	medium: Object.freeze({
-		fancyWater: true,
-		waterMirror: false,
-		minReflectionIntervalMs: 2e3
-	}),
-	high: Object.freeze({
-		fancyWater: true,
-		waterMirror: true,
-		minReflectionIntervalMs: 0
-	})
-});
-/**
-* The caps for a tier — the same frozen object every call.
+* A bar fed the wrong argument shows a plausible wrong number forever.
 *
-* This is read once per water node per frame, so it must not allocate.
+* The trap is one signal away: `Health.damaged` is `(amount, current)`, so
+* wiring it to `setValue` paints the DAMAGE as the health and looks like a
+* working health bar. Say which signal has the shape a bar wants.
 */
-function qualityCaps(tier) {
-	return QUALITY_CAPS[tier] ?? QUALITY_CAPS.high;
+function requireNumber(value, node, method) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	throw new IncantoError("PROP_TYPE_MISMATCH", `UiBar '${node.getPath()}'.${method} needs a number, got ${JSON.stringify(value)}. Check what the wired signal passes FIRST — 'damaged' is (amount, current), 'healthChanged' is (current, max), which is the shape a bar wants.`);
 }
-function qualityRendering(tier) {
-	const device = Math.min(globalThis.devicePixelRatio ?? 1, 2);
-	if (tier === "low") return {
-		antialias: false,
-		pixelRatio: 1
-	};
-	if (tier === "medium") return {
-		antialias: true,
-		pixelRatio: Math.min(device, 1.5)
-	};
-	return {
-		antialias: true,
-		pixelRatio: device
+/** 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: "" }
 	};
-}
-//#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();
-	/**
-	* Screen pixel → the node under it, when a renderer has offered one.
-	*
-	* The raycast has always existed (`Renderer3D.pick` / `Renderer2D.pick`) and
-	* was reachable only from whoever held the renderer — so a Behavior, which
-	* holds a node, could not use it. Every mouse-driven genre needs exactly this
-	* and had no way to ask. Instance-scoped, set by the renderer on construction
-	* and cleared on dispose; null when nothing renders (headless).
-	*/
-	picker = null;
-	/** Global volume buses — `master` × `sfx`/`music` gain + `muted`. AudioPlayer
-	*  routes its volume through this; games set it for global volume/mute. */
-	audio = new AudioBuses();
-	/**
-	* What SHOWED — the visual half of the audio record. Particle bursts, camera
-	* shake, screen flash and freeze frames land here, so "did the explosion
-	* fire?" is answerable in a run with no renderer.
-	*/
-	effects = new EffectLog();
-	/**
-	* Persisted player settings — volume, quality, sensitivity.
-	*
-	* `createSaveStore` was good and had zero callers, so every game's volume
-	* reset on reload. Reading it here costs nothing (localStorage, once) and
-	* `bindAudio` makes the volumes write themselves.
-	*/
-	settings = new Settings();
-	/**
-	* Translations, and the locale in force. English is the base and the default;
-	* anything a locale does not declare falls back to it silently.
-	*/
-	locale = new Localization();
-	/**
-	* Draw-order bands in force: the six built in, plus whatever the current
-	* scene declares. Read by `Node2D`/`Node3D.effectiveRenderOrder`.
-	*/
-	orderGroups = ORDER_GROUP_BASE;
-	/** 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);
+	value = 100;
+	max = 100;
+	width = 180;
+	height = 14;
+	color = "#4ade80";
+	lowColor = "#ef4444";
+	lowThreshold = .3;
+	background = "rgba(0,0,0,0.5)";
+	label = "";
+	fill = null;
+	tag = null;
+	lastLabel = "\0";
+	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;
+	}
 	/**
-	* Where nodes that build DOM (HudLayer and its widgets) mount their elements.
+	* Drive the bar from a signal — `healthChanged → setValue`.
 	*
-	* `null` — the default — means `document.body` with `position: fixed`, i.e. a
-	* game's HUD covers the window, which is what a game wants. A host that only
-	* OWNS PART of the page sets this to its own (positioned) container so the
-	* HUD stays inside it: the scene editor points it at the viewport pane, which
-	* is why an edited scene's HUD no longer floats over the inspector.
-	*/
-	uiHost = null;
-	fixedStep;
-	maxFixedSteps;
-	scheduler;
-	_scene = null;
-	lastMs = null;
-	accumulator = 0;
-	disposeScheduler = null;
-	frameStats = new FrameStatsRing();
-	/** Where each frame's time went — the breakdown `frameMs` alone cannot give. */
-	phaseTimings = new PhaseTimings();
-	/** This frame's render cost, as reported by whoever renders. */
-	renderMs = 0;
-	/**
-	* Game-time multiplier: 1 = realtime, 0.5 = slow motion, 0 = frozen
-	* (hit-stop / pause). Scales BOTH variable and fixed updates — physics,
-	* 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;
-	/**
-	* Elapsed GAME time in seconds since the scene started — the sum of every
-	* scaled dt (freezes at timeScale 0, crawls in slow motion). Unity's
-	* `Time.time`. Resets on `setScene`.
+	* Takes the max as a second argument because that is the shape the signal
+	* already has, so a bar whose ceiling moves (a max-HP upgrade) needs no
+	* second wire.
 	*/
-	get time() {
-		return this._time;
+	setValue(value, max) {
+		this.value = requireNumber(value, this, "setValue");
+		if (max !== void 0) this.max = requireNumber(max, this, "setValue");
 	}
-	/** Elapsed REAL time in seconds since the scene started (ignores timeScale) —
-	*  UI animations that must keep moving during slow-mo/pause read this. */
-	get unscaledTime() {
-		return this._unscaledTime;
+	/** Move the ceiling on its own, leaving the fill where it is. */
+	setMax(max) {
+		this.max = requireNumber(max, this, "setMax");
 	}
-	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);
-		this.maxFps = opts.maxFps ?? 0;
-		this.sfx._setBuses(this.audio);
+	_build() {
+		const wrap = document.createElement("div");
+		wrap.style.cssText = "display:flex;align-items:center;gap:6px;";
+		const tag = document.createElement("span");
+		tag.style.cssText = "color:#fff;font-size:12px;text-shadow:0 1px 3px rgba(0,0,0,.7);";
+		this.tag = tag;
+		wrap.appendChild(tag);
+		this.track = document.createElement("div");
+		this.track.style.cssText = this.trackLook();
+		this.lastTrackLook = this.trackLook();
+		this.fill = document.createElement("div");
+		this.fill.style.cssText = `height:100%;width:100%;background:${this.color};border-radius:inherit;transition:width .15s;`;
+		this.track.appendChild(this.fill);
+		wrap.appendChild(this.track);
+		return wrap;
 	}
-	get scene() {
-		return this._scene;
+	track = null;
+	lastTrackLook = "";
+	lastFillColor = "";
+	/** The track's whole appearance, so re-applying is one comparison. */
+	trackLook() {
+		return `width:${this.width}px;height:${this.height}px;background:${this.background};border-radius:${this.height / 2}px;overflow:hidden;`;
 	}
-	/** 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();
-		this._time = 0;
-		this._unscaledTime = 0;
-		if (scene.input) this.input.declare(scene.input);
-		if (scene.strings) this.locale.load(scene.strings);
-		this.orderGroups = resolveOrderGroups(scene.orderGroups);
-		this.sceneChanged.emit(scene);
+	_sync() {
+		const label = this._t(this.label);
+		if (label !== this.lastLabel && this.tag) {
+			this.lastLabel = label;
+			this.tag.textContent = label;
+			this.tag.style.display = label ? "" : "none";
+		}
+		const look = this.trackLook();
+		if (look !== this.lastTrackLook && this.track) {
+			this.lastTrackLook = look;
+			this.track.style.cssText = look;
+		}
+		const r = this.ratio;
+		if (!this.fill) return;
+		const colour = r <= this.lowThreshold ? this.lowColor : this.color;
+		if (colour !== this.lastFillColor) {
+			this.lastFillColor = colour;
+			this.fill.style.background = colour;
+		}
+		if (r === this.lastRatio) return;
+		this.lastRatio = r;
+		this.fill.style.width = `${r * 100}%`;
 	}
-	start() {
-		if (this.disposeScheduler) return;
-		this.disposeScheduler = this.scheduler((now) => {
-			if (!this.frameIsDue(now)) return;
-			try {
-				this.tick(now);
-			} catch (error) {
-				this.reportFrameError(error);
-			}
+};
+/**
+* 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)`.
+*/
+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
 		});
 	}
-	/**
-	* The frame cap: fps, or 0 for "as fast as the display goes" (the default).
-	*
-	* Live — a settings menu writes it mid-game. It gates the whole frame, not
-	* just the render: an uncapped loop on a 144 Hz phone burns battery running
-	* game logic nobody sees.
-	*
-	* `tick()` is deliberately NOT gated. A headless harness driving its own
-	* clock asked for that frame; the cap is about the real-time loop.
-	*/
-	maxFps = 0;
-	nextFrameAt = 0;
-	lastOfferedAt = null;
-	displayPeriodMs = 0;
-	/**
-	* Should this display frame run?
-	*
-	* The obvious `if (now - last < interval) return` is wrong in a way that only
-	* shows up between the round numbers: a 45 fps cap on a 60 Hz display misses
-	* every other deadline by a fraction of a millisecond, waits a whole display
-	* frame more, and delivers 30 — asking for 45 makes the game slower than not
-	* capping at all. The fix is to allow a frame that is within half a display
-	* period of its deadline, and to advance the deadline by the interval rather
-	* than from `now`, so the error does not accumulate.
-	*/
-	frameIsDue(now) {
-		const prev = this.lastOfferedAt;
-		this.lastOfferedAt = now;
-		if (prev !== null) {
-			const delta = now - prev;
-			if (delta > 0 && delta < 500) this.displayPeriodMs = this.displayPeriodMs === 0 ? delta : this.displayPeriodMs * .9 + delta * .1;
+	/** 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;
+	}
+	/** The whole look, so re-applying is one comparison. `size` was baked in at
+	*  build, and a banner could never be resized. */
+	look() {
+		return `font-size:${this.size}px;font-weight:800;color:#fff;text-shadow:0 2px 12px rgba(0,0,0,.8);transition:opacity .25s;text-align:center;`;
+	}
+	lastLook = "";
+	update(dt) {
+		super.update(dt);
+		const look = this.look();
+		if (look !== this.lastLook && this._element) {
+			this.lastLook = look;
+			const opacity = this._element.style.opacity;
+			this._element.style.cssText = look;
+			this._element.style.opacity = opacity;
 		}
-		if (!(this.maxFps > 0)) {
-			this.nextFrameAt = 0;
-			return true;
+		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 interval = 1e3 / this.maxFps;
-		if (this.nextFrameAt === 0) {
-			this.nextFrameAt = now + interval;
-			return true;
+		if (!this.current && this.queue.length > 0) {
+			this.current = this.queue.shift();
+			this.current.text = this._t(this.current.text);
+			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";
+			}
+			this.emit("bannerShown", this.current.text);
 		}
-		if (now < this.nextFrameAt - this.displayPeriodMs * .5) return false;
-		this.nextFrameAt = Math.max(now, this.nextFrameAt + interval);
-		return true;
 	}
-	/**
-	* A frame threw somewhere outside a single node (a renderer, physics, a
-	* signal handler). Report the first one and count the rest: a broken frame
-	* repeats sixty times a second, and sixty identical traces a second is how
-	* you lose the first one.
-	*/
-	reportFrameError(error) {
-		this.errorCount += 1;
-		const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-		if (text === this.lastFrameError) return;
-		this.lastFrameError = text;
-		this.log.error("[incanto] a frame threw — the loop keeps running:", error);
-		console.error("[incanto] a frame threw — the loop keeps running:", error);
+};
+//#endregion
+//#region src/core/effects-log.ts
+const EFFECT_LOG_LIMIT = 200;
+var EffectLog = class {
+	events = [];
+	/** @internal Called by the effects themselves; games read `recent()`. */
+	record(event) {
+		this.events.push(event);
+		if (this.events.length > EFFECT_LOG_LIMIT) this.events.shift();
+	}
+	/** The last `limit` effects, oldest first. */
+	recent(limit = EFFECT_LOG_LIMIT) {
+		return this.events.slice(Math.max(0, this.events.length - limit));
+	}
+	/** How many times an effect with this name fired (`explosion`, `#ff0000`). */
+	countOf(name) {
+		return this.events.reduce((n, e) => e.name === name ? n + 1 : n, 0);
+	}
+	/** How many effects this node fired — the question a wiring check has. */
+	countFrom(path) {
+		return this.events.reduce((n, e) => e.from === path ? n + 1 : n, 0);
+	}
+	/** Forget what has fired so far (between scenes, or between assertions). */
+	clearLog() {
+		this.events.length = 0;
+	}
+};
+//#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/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);
 	}
-	/** @internal A node quarantined itself; count it for `stats().errors`. */
-	_nodeErrored(_node) {
-		this.errorCount += 1;
+	error(...parts) {
+		this.push("error", parts);
 	}
-	errorCount = 0;
-	lastFrameError = null;
-	/**
-	* Every node with something quarantined — its own update, its script, or
-	* both — so a tool can list them and put them back. Walks on demand; there is
-	* no per-frame bookkeeping for this.
-	*/
-	/**
-	* The string for `key` in the current locale — English if this locale does not
-	* declare it, the key itself if nothing does.
-	*
-	* The short form of `engine.locale.t`, because a behavior reaching for a
-	* translated string is the common case:
-	* `banner.show(this.engine.t('wave.start', { n: wave }))`.
-	*/
-	t(key, params) {
-		return this.locale.t(key, params);
+	/** Buffered entries, oldest first (capped at capacity). */
+	entries() {
+		return this.buffer;
 	}
-	/**
-	* Every behavior's state, ready to put in a save slot.
-	*
-	* Pairs with `restoreState` after the scene has RELOADED — see
-	* core/save-slots.ts for why a save carries state rather than a tree
-	* snapshot.
-	*/
-	captureState() {
-		const root = this.scene?.root;
-		if (!root) return {};
-		const { state, unaddressable } = captureBehaviors(root, this.scene?.source);
-		for (const path of unaddressable) diagnose(this, "warn", `save: ${path} has state to save and no uid to key it under.`);
-		return state;
+	/** Empty the buffer. The sequence keeps counting (entries stay unique). */
+	clear() {
+		this.buffer.length = 0;
 	}
-	/** Give it back, after the scene is loaded and onReady has run. */
-	restoreState(state) {
-		const root = this.scene?.root;
-		if (!root) return {
-			missing: Object.keys(state),
-			skipped: [],
-			restored: 0,
-			expected: 0,
-			freed: 0
+	push(level, parts) {
+		this.seq += 1;
+		const entry = {
+			seq: this.seq,
+			timeMs: globalThis.performance?.now() ?? 0,
+			level,
+			parts
 		};
-		return restoreBehaviors(root, state);
+		this.buffer.push(entry);
+		if (this.buffer.length > this.capacity) this.buffer.splice(0, this.buffer.length - this.capacity);
+		this.added.emit(entry);
 	}
-	erroredNodes() {
-		const out = [];
-		const walk = (node) => {
-			if (node.errored || node.behaviorErrored) out.push(node);
-			for (const child of node.children) walk(child);
+};
+//#endregion
+//#region src/core/phase-timing.ts
+const EMPTY = {
+	fixedMs: 0,
+	updateMs: 0,
+	renderMs: 0,
+	otherMs: 0
+};
+var PhaseTimings = class {
+	capacity;
+	fixed = [];
+	update = [];
+	render = [];
+	head = 0;
+	constructor(capacity = 60) {
+		this.capacity = capacity;
+	}
+	/** Bank one frame's engine-side work. */
+	push(fixedMs, updateMs, renderMs) {
+		const i = this.head % this.capacity;
+		this.fixed[i] = fixedMs;
+		this.update[i] = updateMs;
+		this.render[i] = renderMs;
+		this.head += 1;
+	}
+	/** Means over the window; `frameMs` (0 headless) fills in `otherMs`. */
+	read(frameMs) {
+		const n = Math.min(this.head, this.capacity);
+		if (n === 0) return { ...EMPTY };
+		const fixedMs = mean(this.fixed, n);
+		const updateMs = mean(this.update, n);
+		const renderMs = mean(this.render, n);
+		return {
+			fixedMs,
+			updateMs,
+			renderMs,
+			otherMs: Math.max(0, frameMs - fixedMs - updateMs - renderMs)
 		};
-		if (this._scene?.root) walk(this._scene.root);
-		return out;
 	}
-	/** Un-skip every quarantined node — the "try again" after you fix the code. */
-	resumeErroredNodes() {
-		const nodes = this.erroredNodes();
-		for (const node of nodes) {
-			node.errored = false;
-			node.behaviorErrored = false;
+	clear() {
+		this.fixed.length = 0;
+		this.update.length = 0;
+		this.render.length = 0;
+		this.head = 0;
+	}
+};
+function mean(values, n) {
+	let total = 0;
+	for (let i = 0; i < n; i++) total += values[i] ?? 0;
+	return total / n;
+}
+//#endregion
+//#region src/core/settings.ts
+const DEFAULTS = {
+	master: 1,
+	sfx: 1,
+	music: 1,
+	muted: false,
+	quality: "high",
+	sensitivity: 1,
+	invertY: false,
+	reduceMotion: false,
+	language: "en",
+	qualityChosen: false,
+	maxFps: 0,
+	renderScale: 1
+};
+const TIERS = [
+	"low",
+	"medium",
+	"high"
+];
+/**
+* A default tier from what the browser will admit to.
+*
+* Deliberately crude: this picks a STARTING point, and the options menu is the
+* real answer. A phone that reports four cores and a coarse pointer should not
+* open on the setting tuned for a desktop GPU.
+*/
+function suggestQuality(hints) {
+	const cores = hints.hardwareConcurrency ?? 8;
+	const memory = hints.deviceMemory ?? 8;
+	if (hints.coarsePointer && (cores <= 6 || memory <= 4)) return "low";
+	if (cores <= 4 || memory <= 4 || (hints.maxTextureSize ?? 8192) < 8192) return "low";
+	if (cores <= 8 || memory <= 8) return "medium";
+	return "high";
+}
+/** Read what this environment will tell us, safely, without touching WebGL. */
+function readDeviceHints() {
+	const nav = globalThis.navigator;
+	const mm = globalThis.matchMedia;
+	const out = {};
+	if (typeof nav?.hardwareConcurrency === "number") out.hardwareConcurrency = nav.hardwareConcurrency;
+	if (typeof nav?.deviceMemory === "number") out.deviceMemory = nav.deviceMemory;
+	try {
+		if (mm) out.coarsePointer = mm("(pointer: coarse)").matches;
+	} catch {}
+	return out;
+}
+var Settings = class {
+	/** Fires after any change, with the key that changed. */
+	changed = new Signal();
+	store;
+	values;
+	constructor(namespace = "settings", store) {
+		this.store = store ?? createSaveStore(namespace);
+		this.values = { ...DEFAULTS };
+		for (const key of Object.keys(DEFAULTS)) {
+			const saved = this.store.get(key, DEFAULTS[key]);
+			this.values[key] = saved;
 		}
-		this.lastFrameError = null;
-		return nodes.length;
+		if (!TIERS.includes(this.values.quality)) this.values.quality = DEFAULTS.quality;
+	}
+	get(key) {
+		return this.values[key];
+	}
+	set(key, value) {
+		if (this.values[key] === value) return;
+		this.values[key] = value;
+		this.store.set(key, value);
+		this.changed.emit(key);
+	}
+	/** Every value at once — for an options screen, or a save-file dump. */
+	all() {
+		return { ...this.values };
+	}
+	/** Back to defaults, on disk too. */
+	reset() {
+		for (const key of Object.keys(DEFAULTS)) this.set(key, DEFAULTS[key]);
 	}
 	/**
-	* How long the last render took, in ms — called by whoever renders.
+	* Choose a starting tier from the device, ONCE.
 	*
-	* The engine does not render, so this is the one slice it cannot measure for
-	* itself; without it the cost lands in `otherMs` beside the GC and the two
-	* are indistinguishable, which is the confusion this whole breakdown exists
-	* to end.
+	* Only on a first visit: after someone has picked a tier, re-detecting on
+	* every launch would silently undo their choice — which is the behaviour every
+	* player experiences as "the settings do not save".
 	*/
-	noteRenderMs(ms) {
-		this.renderMs = ms;
+	autoQuality(hints = readDeviceHints()) {
+		if (!this.values.qualityChosen) this.values.quality = suggestQuality(hints);
+		return this.values.quality;
 	}
-	stop() {
-		this.disposeScheduler?.();
-		this.disposeScheduler = null;
-		this.lastMs = null;
-		this.accumulator = 0;
-		this.frameStats.clear();
-		this.phaseTimings.clear();
+	/** Record that the tier came from a person, not from the device probe. */
+	chooseQuality(tier) {
+		this.set("quality", tier);
+		this.set("qualityChosen", true);
 	}
 	/**
-	* 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()`.
+	* Apply the saved quality tier to a live scene, and keep applying it.
+	*
+	* The same shape as `bindAudio` and `bindLocale`. Until 0.38 this did not
+	* exist: `settings.quality` was written to disk and read by NOBODY, and
+	* `qualityEnvironment` — the function that turns a tier into something the
+	* renderer understands — emitted patches the environment parser rejects, for
+	* all three tiers. Both were public, documented and never once called.
 	*/
-	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,
-			errors: this.errorCount,
-			phases: this.phaseTimings.read(this.frameStats.frameMs())
-		};
+	bindQuality(apply) {
+		apply(qualityEnvironment(this.values.quality));
+		return this.changed.connect((key) => {
+			if (key === "quality") apply(qualityEnvironment(this.values.quality));
+		});
+	}
+	/**
+	* Apply the saved frame cap, and again whenever it changes.
+	*
+	* Separate from `bindQuality` because it is not a tier: a player caps the
+	* frame rate to keep a phone cool or a battery alive, on the highest visual
+	* settings the device can hold, and those two choices do not belong on one
+	* slider. 0 means uncapped. Returns the unsubscribe.
+	*/
+	bindFrameCap(apply) {
+		apply(this.values.maxFps);
+		return this.changed.connect((key) => {
+			if (key === "maxFps") apply(this.values.maxFps);
+		});
 	}
 	/**
-	* 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.
+	* Apply the saved resolution multiplier, and again whenever it changes.
+	*
+	* The lever that buys the most frames per unit of ugliness on a weak GPU —
+	* shading 44% of the pixels at 0.66 costs a soft image and nothing else,
+	* while dropping a quality tier costs shadows entirely.
 	*/
-	get interpolationAlpha() {
-		return this.fixedStep > 0 ? Math.min(this.accumulator / this.fixedStep, 1) : 1;
+	bindRenderScale(apply) {
+		apply(this.values.renderScale);
+		return this.changed.connect((key) => {
+			if (key === "renderScale") apply(this.values.renderScale);
+		});
 	}
 	/**
-	* 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().
+	* Apply the saved language, and keep it in step both ways.
+	*
+	* The same shape as `bindAudio`: a game that writes
+	* `engine.locale.locale = 'ko'` from an options menu has already persisted it
+	* without knowing this class exists. Returns the unsubscribe.
 	*/
-	dispose() {
-		this.stop();
-		this.music.dispose();
-		this.sfx.dispose();
-		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();
+	bindLocale(locale) {
+		locale.locale = this.values.language;
+		return locale.changed.connect((next) => {
+			this.set("language", next);
+		});
 	}
 	/**
-	* Advance exactly ONE fixed step and one variable update (both dt = the
-	* fixed step scaled by `timeScale`), 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.
+	* Push the saved volumes into the engine's buses, and keep writing them back
+	* whenever anything changes them.
 	*
-	* `ignorePause: true` steps a frame at full scale even while the game is
-	* paused — the debug overlay's single-step button, and nothing else.
+	* The subscription is the point: a game that sets `engine.audio.music = 0.4`
+	* from a slider has already persisted it, without knowing this class exists.
 	*/
-	step(opts = {}) {
-		const scene = this._scene;
-		if (!scene) return;
-		const dt = this.fixedStep * (opts.ignorePause ? 1 : this.timeScale);
-		this._time += dt;
-		this._unscaledTime += this.fixedStep;
-		const startedFixed = performance.now();
-		scene.tree.fixedUpdate(dt);
-		this.fixedUpdated.emit(dt);
-		const startedUpdate = performance.now();
-		scene.tree.update(dt);
-		this.music.tick(dt);
-		this.updated.emit(dt);
-		const ended = performance.now();
-		const updateMs = Math.max(0, ended - startedUpdate - this.renderMs);
-		this.phaseTimings.push(startedUpdate - startedFixed, updateMs, this.renderMs);
-		this.renderMs = 0;
-		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 rawDt = Math.max(0, Math.min((nowMs - this.lastMs) / 1e3, MAX_DT_SECONDS));
-		const dt = rawDt * this.timeScale;
-		this._time += dt;
-		this._unscaledTime += rawDt;
-		this.lastMs = nowMs;
-		const scene = this._scene;
-		if (!scene) return;
-		this.accumulator += dt;
-		let steps = 0;
-		const startedFixed = performance.now();
-		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;
-		const startedUpdate = performance.now();
-		scene.tree.update(dt);
-		this.music.tick(dt);
-		this.updated.emit(dt);
-		const ended = performance.now();
-		const updateMs = Math.max(0, ended - startedUpdate - this.renderMs);
-		this.phaseTimings.push(startedUpdate - startedFixed, updateMs, this.renderMs);
-		this.renderMs = 0;
-		this.input.endFrame();
+	bindAudio(audio) {
+		audio.master = this.values.master;
+		audio.sfx = this.values.sfx;
+		audio.music = this.values.music;
+		audio.muted = this.values.muted;
+		return audio.changed.connect(() => {
+			this.set("master", audio.master);
+			this.set("sfx", audio.sfx);
+			this.set("music", audio.music);
+			this.set("muted", audio.muted);
+		});
 	}
 };
-function countNodes(root) {
-	let n = 1;
-	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.
+* What a quality tier MEANS, as a LIVE environment patch.
 *
-* 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.
+* Only the levers that actually cost: shadows, post, bloom and clouds.
+* Deliberately an `environment` patch, because `setEnvironment3D(engine, patch)`
+* already applies one live and validated — this is not a second rendering
+* pipeline, it is three presets for the one that exists.
 *
-* Volume routes through the engine's buses: `engine.audio.master × bus(sfx|music)
-* × volume`. Set `engine.audio.master`/`sfx`/`music`/`muted` for global control.
+* The `off` spelling matters and got this wrong for three releases: every tier
+* emitted `{ enabled: false }`, which the environment parser rejects
+* (`environment.bloom has unknown key 'enabled'`). Nothing called this function,
+* so nothing found out. In a live patch `null` DELETES a key — that is how a
+* stage is turned off — and `shadows` alone takes a real `false`.
+*
+* Antialiasing and pixel ratio are NOT here: `antialias` is a WebGL context
+* attribute and cannot change without rebuilding the renderer. See
+* `qualityRendering`.
 */
-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]
-		}
+function qualityEnvironment(tier) {
+	if (tier === "low") return {
+		shadows: false,
+		bloom: null,
+		post: null,
+		clouds: null
+	};
+	if (tier === "medium") return {
+		shadows: { static: true },
+		bloom: {},
+		post: null
+	};
+	return {
+		shadows: true,
+		bloom: {},
+		post: {}
+	};
+}
+const QUALITY_CAPS = Object.freeze({
+	low: Object.freeze({
+		fancyWater: false,
+		waterMirror: false,
+		minReflectionIntervalMs: 2e3
+	}),
+	medium: Object.freeze({
+		fancyWater: true,
+		waterMirror: false,
+		minReflectionIntervalMs: 2e3
+	}),
+	high: Object.freeze({
+		fancyWater: true,
+		waterMirror: true,
+		minReflectionIntervalMs: 0
+	})
+});
+/**
+* The caps for a tier — the same frozen object every call.
+*
+* This is read once per water node per frame, so it must not allocate.
+*/
+function qualityCaps(tier) {
+	return QUALITY_CAPS[tier] ?? QUALITY_CAPS.high;
+}
+function qualityRendering(tier) {
+	const device = Math.min(globalThis.devicePixelRatio ?? 1, 2);
+	if (tier === "low") return {
+		antialias: false,
+		pixelRatio: 1
+	};
+	if (tier === "medium") return {
+		antialias: true,
+		pixelRatio: Math.min(device, 1.5)
+	};
+	return {
+		antialias: true,
+		pixelRatio: device
+	};
+}
+//#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);
 	};
-	/** 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;
+}
+/**
+* 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();
 	/**
-	* 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.
+	* 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.
 	*/
-	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;
+	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();
 	/**
-	* Why this player is silent, when the reason is the FILE rather than the
-	* autoplay gate. Read by `game.assetErrors()`.
+	* Screen pixel → the node under it, when a renderer has offered one.
+	*
+	* The raycast has always existed (`Renderer3D.pick` / `Renderer2D.pick`) and
+	* was reachable only from whoever held the renderer — so a Behavior, which
+	* holds a node, could not use it. Every mouse-driven genre needs exactly this
+	* and had no way to ask. Instance-scoped, set by the renderer on construction
+	* and cleared on dispose; null when nothing renders (headless).
 	*/
-	loadError = null;
-	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;
-	}
+	picker = null;
+	/** Global volume buses — `master` × `sfx`/`music` gain + `muted`. AudioPlayer
+	*  routes its volume through this; games set it for global volume/mute. */
+	audio = new AudioBuses();
 	/**
-	* @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.
+	* What SHOWED — the visual half of the audio record. Particle bursts, camera
+	* shake, screen flash and freeze frames land here, so "did the explosion
+	* fire?" is answerable in a run with no renderer.
 	*/
-	_setSpatialPose(pose) {
-		this._spatialPose = pose;
-	}
+	effects = new EffectLog();
 	/**
-	* Write this sound into the engine's audio record.
+	* Persisted player settings — volume, quality, sensitivity.
 	*
-	* The CALL happens even where the backend does not (headless, the verify VM),
-	* which is exactly why the record is worth keeping: it answers "did the coin
-	* sound fire when the coin was collected" in places no sound can be heard.
+	* `createSaveStore` was good and had zero callers, so every game's volume
+	* reset on reload. Reading it here costs nothing (localStorage, once) and
+	* `bindAudio` makes the volumes write themselves.
 	*/
-	note(kind, name) {
-		const engine = this.tree?.engine;
-		engine?.audio.record({
-			kind,
-			name,
-			from: this.getPath(),
-			bus: this.bus === "music" ? "music" : "sfx",
-			at: engine.time
-		});
-	}
-	/** 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.note("preset", this.preset);
-			this.playPreset();
-			return;
-		}
-		if (!this.src) return;
-		this.note("src", this.src);
-		if (!this.element) {
-			this.element = createElement();
-			if (!this.element) return;
-			this.element.addEventListener("ended", () => {
-				if (this.loop) return;
-				this._playing = false;
-				this.emit("finished");
-			});
-			this.element.addEventListener("error", () => {
-				this._playing = false;
-				if (this.loadError) return;
-				this.loadError = `could not load ${this.src}`;
-				diagnose(this.tree?.engine ?? null, "error", `[incanto] AudioPlayer '${this.name}' could not load '${this.src}' — it is silent.`);
-			});
-		}
-		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((error) => {
-			this._playing = false;
-			const name = error?.name ?? "";
-			if (name !== "NotSupportedError") {
-				this.pendingGesture = true;
-				return;
-			}
-			this.loadError = `${name}: ${this.src}`;
-			diagnose(this.tree?.engine ?? null, "error", `[incanto] AudioPlayer '${this.name}' cannot play '${this.src}' (${name}) — it is silent.`);
-		});
-	}
+	settings = new Settings();
 	/**
-	* 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.
+	* Translations, and the locale in force. English is the base and the default;
+	* anything a locale does not declare falls back to it silently.
 	*/
-	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()
-		});
-	}
+	locale = new Localization();
+	/**
+	* Draw-order bands in force: the six built in, plus whatever the current
+	* scene declares. Read by `Node2D`/`Node3D.effectiveRenderOrder`.
+	*/
+	orderGroups = ORDER_GROUP_BASE;
+	/** 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);
+	/**
+	* Where nodes that build DOM (HudLayer and its widgets) mount their elements.
+	*
+	* `null` — the default — means `document.body` with `position: fixed`, i.e. a
+	* game's HUD covers the window, which is what a game wants. A host that only
+	* OWNS PART of the page sets this to its own (positioned) container so the
+	* HUD stays inside it: the scene editor points it at the viewport pane, which
+	* is why an edited scene's HUD no longer floats over the inspector.
+	*/
+	uiHost = null;
+	fixedStep;
+	maxFixedSteps;
+	scheduler;
+	_scene = null;
+	lastMs = null;
+	accumulator = 0;
+	disposeScheduler = null;
+	frameStats = new FrameStatsRing();
+	/** Where each frame's time went — the breakdown `frameMs` alone cannot give. */
+	phaseTimings = new PhaseTimings();
+	/** This frame's render cost, as reported by whoever renders. */
+	renderMs = 0;
+	/**
+	* Game-time multiplier: 1 = realtime, 0.5 = slow motion, 0 = frozen
+	* (hit-stop / pause). Scales BOTH variable and fixed updates — physics,
+	* 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;
 	/**
-	* A destroyed node goes SILENT.
-	*
-	* Nothing used to stop a sound on teardown, so a level's looping background
-	* clip kept playing over the level after it — the node was freed, so nobody
-	* had a handle to stop it with either. Being MOVED is deliberately not this:
-	* reparenting a node is not destroying it, and a sound that survives the move
-	* is what a scene graph should do.
+	* Elapsed GAME time in seconds since the scene started — the sum of every
+	* scaled dt (freezes at timeScale 0, crawls in slow motion). Unity's
+	* `Time.time`. Resets on `setScene`.
 	*/
-	free() {
-		this.stop();
-		super.free();
+	get time() {
+		return this._time;
 	}
-	stop() {
-		if (this.element) {
-			this.element.pause();
-			this.element.currentTime = 0;
-		}
-		this._playing = false;
-		this.pendingGesture = false;
+	/** Elapsed REAL time in seconds since the scene started (ignores timeScale) —
+	*  UI animations that must keep moving during slow-mo/pause read this. */
+	get unscaledTime() {
+		return this._unscaledTime;
 	}
-	/** Replay a gesture-blocked play (wired to the first user gesture). */
-	retryPending() {
-		if (this.pendingGesture) this.play();
+	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);
+		this.maxFps = opts.maxFps ?? 0;
+		this.sfx._setBuses(this.audio);
+		this.music.onTrackError = (src, reason) => {
+			diagnose(this, "error", `[incanto] music '${src}' will not play — ${reason}.`);
+		};
 	}
-	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;
-		}
+	get scene() {
+		return this._scene;
 	}
-};
-//#endregion
-//#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;"
-};
-const FONT = "600 14px system-ui, -apple-system, 'Segoe UI', sans-serif";
-function hasDom() {
-	return typeof document !== "undefined";
-}
-/**
-* 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 },
-		/**
-		* Arrow keys / d-pad move focus between the focusable widgets under this
-		* layer, Enter / A activates. OFF by default — a game whose HUD has a
-		* button must not lose its arrow keys the moment one exists.
-		*/
-		focusNavigation: { default: false }
-	};
-	zIndex = 100;
-	visible = true;
-	focusNavigation = false;
-	/** @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};`;
-		this._element = el;
-		this._mount();
+	/** 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();
+		this._time = 0;
+		this._unscaledTime = 0;
+		if (scene.input) this.input.declare(scene.input);
+		if (scene.strings) this.locale.load(scene.strings);
+		this.orderGroups = resolveOrderGroups(scene.orderGroups);
+		this.sceneChanged.emit(scene);
+	}
+	start() {
+		if (this.disposeScheduler) return;
+		this.disposeScheduler = this.scheduler((now) => {
+			if (!this.frameIsDue(now)) return;
+			try {
+				this.tick(now);
+			} catch (error) {
+				this.reportFrameError(error);
+			}
+		});
 	}
 	/**
-	* Put the overlay where the page's owner says UI goes: `engine.uiHost`, or
-	* the window when nobody claims it (a game — a HUD covers the screen).
+	* The frame cap: fps, or 0 for "as fast as the display goes" (the default).
 	*
-	* Re-checked every frame because a scene's tree is BUILT before it is handed
-	* to an engine: at onEnterTree there is no engine to ask yet, so the first
-	* update is where the answer actually arrives. appendChild moves the element
-	* if it already landed somewhere else, so the HUD follows the host across a
-	* scene swap into a differently-hosted engine (game → editor) instead of
-	* being stranded on document.body over the inspector.
+	* Live — a settings menu writes it mid-game. It gates the whole frame, not
+	* just the render: an uncapped loop on a 144 Hz phone burns battery running
+	* game logic nobody sees.
+	*
+	* `tick()` is deliberately NOT gated. A headless harness driving its own
+	* clock asked for that frame; the cap is about the real-time loop.
 	*/
-	_mount() {
-		const el = this._element;
-		if (!el) return;
-		const host = this.tree?.engine?.uiHost ?? document.body;
-		if (el.parentElement === host) return;
-		el.style.position = host === document.body ? "fixed" : "absolute";
-		host.appendChild(el);
-	}
-	onExitTree() {
-		this._element?.remove();
-		this._element = null;
-		this.slots.clear();
-	}
-	update() {
-		if (this._element) {
-			this._mount();
-			this._element.style.display = this.visible ? "" : "none";
-		}
-		if (this.focusNavigation) this.stepFocus();
-	}
+	maxFps = 0;
+	nextFrameAt = 0;
+	lastOfferedAt = null;
+	displayPeriodMs = 0;
 	/**
-	* Arrow keys / d-pad move the focus, Enter / A activates it.
+	* Should this display frame run?
 	*
-	* Off by default: a game whose HUD has a button must not lose its arrow keys
-	* to a menu the moment one exists. Turn it on for the screens that ARE menus
-	* (`"focusNavigation": true` on the pause panel's layer), and off again when
-	* play resumes.
+	* The obvious `if (now - last < interval) return` is wrong in a way that only
+	* shows up between the round numbers: a 45 fps cap on a 60 Hz display misses
+	* every other deadline by a fraction of a millisecond, waits a whole display
+	* frame more, and delivers 30 — asking for 45 makes the game slower than not
+	* capping at all. The fix is to allow a frame that is within half a display
+	* period of its deadline, and to advance the deadline by the interval rather
+	* than from `now`, so the error does not accumulate.
 	*/
-	stepFocus() {
-		const engine = this.tree?.engine;
-		if (!engine) return;
-		const items = this.focusables();
-		if (items.length === 0) return;
-		const input = engine.input;
-		const down = input.keyJustPressed("ArrowDown") || input.keyJustPressed("Pad13");
-		const up = input.keyJustPressed("ArrowUp") || input.keyJustPressed("Pad12");
-		const left = input.keyJustPressed("ArrowLeft") || input.keyJustPressed("Pad14");
-		const right = input.keyJustPressed("ArrowRight") || input.keyJustPressed("Pad15");
-		const confirm = input.keyJustPressed("Enter") || input.keyJustPressed("Pad0");
-		let index = items.findIndex((w) => w._focused);
-		if (index === -1 && (down || up || confirm)) index = 0;
-		else if (down) index = (index + 1) % items.length;
-		else if (up) index = (index - 1 + items.length) % items.length;
-		if (index !== -1) {
-			for (const w of items) {
-				const next = w === items[index];
-				if (next !== w._focused) {
-					w._focused = next;
-					w._paintFocus();
-				}
-			}
-			const focused = items[index];
-			if (focused) {
-				if (confirm) focused._activate(0);
-				else if (left) focused._activate(-1);
-				else if (right) focused._activate(1);
-			}
-		}
-	}
-	/** Focusable widgets under this layer, in tree order. */
-	focusables() {
-		const out = [];
-		const walk = (node) => {
-			if (node instanceof HudWidgetBase && node.focusable && node.visible) out.push(node);
-			for (const child of node.children) walk(child);
-		};
-		walk(this);
-		return out;
-	}
-	/** Move focus to a widget by hand — opening a menu should start somewhere. */
-	focus(widget) {
-		for (const w of this.focusables()) {
-			const next = w === widget;
-			if (next !== w._focused) {
-				w._focused = next;
-				w._paintFocus();
-			}
-		}
-	}
-	/** @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;
-	}
-};
-/**
-* The widget an element belongs to.
-*
-* A pick lands on whatever div is under the cursor — usually a CHILD of the
-* widget (an icon inside a slot), so the walk upward is the point.
-*/
-const widgetOf = /* @__PURE__ */ new WeakMap();
-function widgetFromElement(el) {
-	for (let n = el; n; n = n.parentElement) {
-		const found = widgetOf.get(n);
-		if (found) return found;
+	frameIsDue(now) {
+		const prev = this.lastOfferedAt;
+		this.lastOfferedAt = now;
+		if (prev !== null) {
+			const delta = now - prev;
+			if (delta > 0 && delta < 500) this.displayPeriodMs = this.displayPeriodMs === 0 ? delta : this.displayPeriodMs * .9 + delta * .1;
+		}
+		if (!(this.maxFps > 0)) {
+			this.nextFrameAt = 0;
+			return true;
+		}
+		const interval = 1e3 / this.maxFps;
+		if (this.nextFrameAt === 0) {
+			this.nextFrameAt = now + interval;
+			return true;
+		}
+		if (now < this.nextFrameAt - this.displayPeriodMs * .5) return false;
+		this.nextFrameAt = Math.max(now, this.nextFrameAt + interval);
+		return true;
 	}
-	return null;
-}
-/** The drag in flight, if any. One pointer, one drag. */
-let dragging = null;
-/** Shared plumbing: mount into the parent HudLayer's anchor slot. */
-var HudWidgetBase = class extends Node {
 	/**
-	* Wireable visibility: `noSave → Continue.hide`.
-	*
-	* `visible` is a prop, and a `connections[]` handler has to be a METHOD — the
-	* same wall that kept a score off the screen until widgets grew `setText`. A
-	* title screen greying out its own Continue button is the case that asked.
+	* A frame threw somewhere outside a single node (a renderer, physics, a
+	* signal handler). Report the first one and count the rest: a broken frame
+	* repeats sixty times a second, and sixty identical traces a second is how
+	* you lose the first one.
 	*/
-	show(..._args) {
-		this.visible = true;
+	reportFrameError(error) {
+		this.errorCount += 1;
+		const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+		if (text === this.lastFrameError) return;
+		this.lastFrameError = text;
+		this.log.error("[incanto] a frame threw — the loop keeps running:", error);
+		console.error("[incanto] a frame threw — the loop keeps running:", error);
 	}
-	hide() {
-		this.visible = false;
+	/** @internal A node quarantined itself; count it for `stats().errors`. */
+	_nodeErrored(_node) {
+		this.errorCount += 1;
 	}
-	static props = {
-		anchor: {
-			default: "topLeft",
-			options: [
-				"topLeft",
-				"top",
-				"topRight",
-				"left",
-				"center",
-				"right",
-				"bottomLeft",
-				"bottom",
-				"bottomRight"
-			]
-		},
-		visible: { default: true },
-		/**
-		* Can menu navigation land on this? Interactive widgets default to true.
-		*
-		* A menu you can only click is not playable on a controller, and "add
-		* gamepad support" is not a thing a JSON scene could express at all.
-		*/
-		focusable: { default: false },
-		/**
-		* Can the player pick this up and drop it somewhere? An inventory item is
-		* a `draggable` widget; a slot is a `dropTarget`.
-		*/
-		draggable: { default: false },
-		/** Can something be dropped ON this? */
-		dropTarget: { default: false }
-	};
-	static signals = [
-		"dragStarted",
-		"dragCancelled",
-		"droppedOn",
-		"dropped"
-	];
-	anchor = "topLeft";
-	visible = true;
-	focusable = false;
-	draggable = false;
-	dropTarget = false;
-	/** @internal Set by the owning HudLayer while this widget has focus. */
-	_focused = false;
+	errorCount = 0;
+	lastFrameError = null;
 	/**
-	* @internal Confirm (`dir` 0) or nudge (-1 left / +1 right) — what pressing
-	* A or an arrow ON this widget means. Default: nothing.
+	* Every node with something quarantined — its own update, its script, or
+	* both — so a tool can list them and put them back. Walks on demand; there is
+	* no per-frame bookkeeping for this.
 	*/
-	_activate(_dir) {}
-	/** @internal Draw the focus ring. Overridable if a widget wants its own. */
-	_paintFocus() {
-		if (!this._element) return;
-		this._element.style.outline = this._focused ? "2px solid #6ee7dc" : "";
-		this._element.style.outlineOffset = this._focused ? "2px" : "";
-	}
-	/** @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;
-		this._mountWidget();
-	}
 	/**
-	* @internal Build and attach, once a host exists.
+	* The string for `key` in the current locale — English if this locale does not
+	* declare it, the key itself if nothing does.
 	*
-	* A widget inside a UiPanel mounts into the PANEL, not the layer's anchor
-	* slot — that is what turns structure in the tree into structure on screen,
-	* and it is what a menu is. Ready order does not decide it: the panel builds
-	* on demand when a child asks (`_container`), and `update` retries for
-	* anything attached at runtime before its host existed.
+	* The short form of `engine.locale.t`, because a behavior reaching for a
+	* translated string is the common case:
+	* `banner.show(this.engine.t('wave.start', { n: wave }))`.
 	*/
-	_mountWidget() {
-		if (this._element || !hasDom()) return;
-		const host = this.host() ?? this.layer()?._slot(this.anchor);
-		if (!host) return;
-		this._element = this._build();
-		widgetOf.set(this._element, this);
-		if (this.draggable || this.dropTarget) this._wireDrag(this._element);
-		host.appendChild(this._element);
+	t(key, params) {
+		return this.locale.t(key, params);
 	}
 	/**
-	* Drag and drop, on the DOM the engine already builds.
+	* Every behavior's state, ready to put in a save slot.
 	*
-	* An inventory is the one screen where "click it" is not enough, and every
-	* game that wanted one dropped out of scene JSON to hand-roll pointer
-	* handlers. The whole gesture is four signals and no new node type: a
-	* `draggable` widget emits `dragStarted` and, if it lands on one,
-	* `droppedOn(target)`; a `dropTarget` emits `dropped(source)`. Who owns the
-	* ITEM is the game's business — this reports the gesture, not a model.
+	* Pairs with `restoreState` after the scene has RELOADED — see
+	* core/save-slots.ts for why a save carries state rather than a tree
+	* snapshot.
 	*/
-	_wireDrag(el) {
-		el.style.touchAction = "none";
-		if (this.draggable) {
-			el.style.cursor = "grab";
-			el.addEventListener("pointerdown", (event) => {
-				if (!this.draggable) return;
-				event.preventDefault();
-				el.setPointerCapture?.(event.pointerId);
-				dragging = this;
-				el.style.opacity = "0.6";
-				this.emit("dragStarted", this);
-			});
-			el.addEventListener("pointerup", (event) => {
-				if (dragging !== this) return;
-				el.style.opacity = "";
-				el.releasePointerCapture?.(event.pointerId);
-				const target = widgetFromElement(document.elementFromPoint?.(event.clientX, event.clientY) ?? null);
-				dragging = null;
-				if (target && target !== this && target.dropTarget) {
-					this.emit("droppedOn", target);
-					target.emit("dropped", this);
-				} else this.emit("dragCancelled", this);
-			});
-		}
+	captureState() {
+		const root = this.scene?.root;
+		if (!root) return {};
+		const { state, unaddressable } = captureBehaviors(root, this.scene?.source);
+		for (const path of unaddressable) diagnose(this, "warn", `save: ${path} has state to save and no uid to key it under.`);
+		return state;
 	}
-	/** The nearest ancestor that holds widgets itself (a UiPanel). */
-	host() {
-		for (let p = this.parent; p; p = p.parent) {
-			const holder = p;
-			if (typeof holder._container === "function") return holder._container();
-			if (p instanceof HudLayer) return null;
-		}
-		return null;
+	/** Give it back, after the scene is loaded and onReady has run. */
+	restoreState(state) {
+		const root = this.scene?.root;
+		if (!root) return {
+			missing: Object.keys(state),
+			skipped: [],
+			restored: 0,
+			expected: 0,
+			freed: 0
+		};
+		return restoreBehaviors(root, state);
 	}
-	onExitTree() {
-		this._element?.remove();
-		this._element = null;
+	erroredNodes() {
+		const out = [];
+		const walk = (node) => {
+			if (node.errored || node.behaviorErrored) out.push(node);
+			for (const child of node.children) walk(child);
+		};
+		if (this._scene?.root) walk(this._scene.root);
+		return out;
 	}
-	update(_dt) {
-		if (!this._element) {
-			this._mountWidget();
-			if (!this._element) return;
+	/** Un-skip every quarantined node — the "try again" after you fix the code. */
+	resumeErroredNodes() {
+		const nodes = this.erroredNodes();
+		for (const node of nodes) {
+			node.errored = false;
+			node.behaviorErrored = false;
 		}
-		this._element.style.display = this.visible ? "" : "none";
-		this._sync();
+		this.lastFrameError = null;
+		return nodes.length;
 	}
-	_sync() {}
 	/**
-	* Resolve a text prop through the engine's locale.
+	* How long the last render took, in ms — called by whoever renders.
 	*
-	* Called every frame from `_sync`, which is what makes switching language
-	* repaint with nothing to invalidate: widgets already re-read their props, so
-	* the new string simply appears on the next frame. A plain string costs one
-	* `startsWith` and is returned untouched.
+	* The engine does not render, so this is the one slice it cannot measure for
+	* itself; without it the cost lands in `otherMs` beside the GC and the two
+	* are indistinguishable, which is the confusion this whole breakdown exists
+	* to end.
 	*/
-	_t(value) {
-		const locale = this.tree?.engine?.locale;
-		return locale ? locale.resolve(value) : value;
+	noteRenderMs(ms) {
+		this.renderMs = ms;
+	}
+	stop() {
+		this.disposeScheduler?.();
+		this.disposeScheduler = null;
+		this.lastMs = null;
+		this.accumulator = 0;
+		this.frameStats.clear();
+		this.phaseTimings.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,
+			errors: this.errorCount,
+			phases: this.phaseTimings.read(this.frameStats.frameMs())
+		};
 	}
-};
-/** A text line (score, timer, hints). Set `.text` from behaviors. */
-var UiText = class extends HudWidgetBase {
-	static typeName = "UiText";
-	static props = {
-		...HudWidgetBase.props,
-		text: { default: "" },
-		format: { default: "" },
-		size: { default: 16 },
-		color: { default: "#ffffff" },
-		shadow: { default: true }
-	};
-	text = "";
 	/**
-	* A template with a `{}` slot that `setText` fills — `"Gems {} / 8"`.
-	*
-	* Empty (the default) means `setText` replaces the whole line. Resolved at
-	* PAINT like `text`, so `"@t:hud.gems"` works and changing locale re-reads
-	* it: the value lives here, the words live in the strings table.
+	* 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.
 	*/
-	format = "";
-	size = 16;
-	color = "#ffffff";
-	shadow = true;
-	last = "\0";
-	/** null until something has actually set a value — see `shown`. */
-	slot = null;
+	get interpolationAlpha() {
+		return this.fixedStep > 0 ? Math.min(this.accumulator / this.fixedStep, 1) : 1;
+	}
 	/**
-	* Put a signal's value on screen — `scoreChanged → setText`.
-	*
-	* A `connections[]` handler must be a METHOD and `text` is a property, so the
-	* one wire every game needs (score to screen) could not be declared: every
-	* HUD began with a behavior whose whole job was one assignment.
+	* 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().
 	*/
-	setText(value) {
-		this.slot = String(value ?? "");
-		if (!this.format) this.text = this.slot;
+	dispose() {
+		this.stop();
+		this.music.dispose();
+		this.sfx.dispose();
+		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();
 	}
 	/**
-	* What it actually paints, after the template and the locale.
+	* Advance exactly ONE fixed step and one variable update (both dt = the
+	* fixed step scaled by `timeScale`), 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.
 	*
-	* Before the first value arrives, a formatted widget shows `text` — its
-	* authored opening line. Filling the slot with nothing instead would put
-	* `"Gems  / 8"` on screen for every game's first frame, and a score line
-	* that starts blank looks broken rather than empty.
+	* `ignorePause: true` steps a frame at full scale even while the game is
+	* paused — the debug overlay's single-step button, and nothing else.
 	*/
-	get shown() {
-		if (this.format && this.slot !== null) return this._t(this.format).replace("{}", this.slot);
-		return this._t(this.text);
-	}
-	_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;
+	step(opts = {}) {
+		const scene = this._scene;
+		if (!scene) return;
+		const dt = this.fixedStep * (opts.ignorePause ? 1 : this.timeScale);
+		this._time += dt;
+		this._unscaledTime += this.fixedStep;
+		const startedFixed = performance.now();
+		scene.tree.fixedUpdate(dt);
+		this.fixedUpdated.emit(dt);
+		const startedUpdate = performance.now();
+		scene.tree.update(dt);
+		this.music.tick(dt);
+		this.updated.emit(dt);
+		const ended = performance.now();
+		const updateMs = Math.max(0, ended - startedUpdate - this.renderMs);
+		this.phaseTimings.push(startedUpdate - startedFixed, updateMs, this.renderMs);
+		this.renderMs = 0;
+		this.input.endFrame();
 	}
-	_sync() {
-		const shown = this.shown;
-		if (shown !== this.last && this._element) {
-			this.last = shown;
-			this._element.textContent = shown;
+	/** 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 rawDt = Math.max(0, Math.min((nowMs - this.lastMs) / 1e3, MAX_DT_SECONDS));
+		const dt = rawDt * this.timeScale;
+		this._time += dt;
+		this._unscaledTime += rawDt;
+		this.lastMs = nowMs;
+		const scene = this._scene;
+		if (!scene) return;
+		this.accumulator += dt;
+		let steps = 0;
+		const startedFixed = performance.now();
+		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;
+		const startedUpdate = performance.now();
+		scene.tree.update(dt);
+		this.music.tick(dt);
+		this.updated.emit(dt);
+		const ended = performance.now();
+		const updateMs = Math.max(0, ended - startedUpdate - this.renderMs);
+		this.phaseTimings.push(startedUpdate - startedFixed, updateMs, this.renderMs);
+		this.renderMs = 0;
+		this.input.endFrame();
 	}
 };
+function countNodes(root) {
+	let n = 1;
+	for (const child of root.children) n += countNodes(child);
+	return n;
+}
+function createElement() {
+	if (typeof Audio === "undefined") return null;
+	return new Audio();
+}
 /**
-* A bar fed the wrong argument shows a plausible wrong number forever.
+* 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.
 *
-* The trap is one signal away: `Health.damaged` is `(amount, current)`, so
-* wiring it to `setValue` paints the DAMAGE as the health and looks like a
-* working health bar. Say which signal has the shape a bar wants.
+* 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.
 */
-function requireNumber(value, node, method) {
-	if (typeof value === "number" && Number.isFinite(value)) return value;
-	throw new IncantoError("PROP_TYPE_MISMATCH", `UiBar '${node.getPath()}'.${method} needs a number, got ${JSON.stringify(value)}. Check what the wired signal passes FIRST — 'damaged' is (amount, current), 'healthChanged' is (current, max), which is the shape a bar wants.`);
-}
-/** A labeled progress bar (health, stamina, reload, boss HP). */
-var UiBar = class extends HudWidgetBase {
-	static typeName = "UiBar";
+var AudioPlayer = class extends Node {
+	static typeName = "AudioPlayer";
+	static signals = ["finished"];
 	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: "" }
+		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]
+		}
 	};
-	value = 100;
-	max = 100;
-	width = 180;
-	height = 14;
-	color = "#4ade80";
-	lowColor = "#ef4444";
-	lowThreshold = .3;
-	background = "rgba(0,0,0,0.5)";
-	label = "";
-	fill = null;
-	tag = null;
-	lastLabel = "\0";
-	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;
+	/** 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;
 	/**
-	* Drive the bar from a signal — `healthChanged → setValue`.
+	* Why this player is silent, when the reason is the FILE rather than the
+	* autoplay gate. Read by `game.assetErrors()`.
+	*/
+	loadError = null;
+	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;
+	}
+	/**
+	* Write this sound into the engine's audio record.
 	*
-	* Takes the max as a second argument because that is the shape the signal
-	* already has, so a bar whose ceiling moves (a max-HP upgrade) needs no
-	* second wire.
+	* The CALL happens even where the backend does not (headless, the verify VM),
+	* which is exactly why the record is worth keeping: it answers "did the coin
+	* sound fire when the coin was collected" in places no sound can be heard.
 	*/
-	setValue(value, max) {
-		this.value = requireNumber(value, this, "setValue");
-		if (max !== void 0) this.max = requireNumber(max, this, "setValue");
+	note(kind, name) {
+		const engine = this.tree?.engine;
+		engine?.audio.record({
+			kind,
+			name,
+			from: this.getPath(),
+			bus: this.bus === "music" ? "music" : "sfx",
+			at: engine.time
+		});
 	}
-	/** Move the ceiling on its own, leaving the fill where it is. */
-	setMax(max) {
-		this.max = requireNumber(max, this, "setMax");
+	/** 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;
 	}
-	_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.style.cssText = "color:#fff;font-size:12px;text-shadow:0 1px 3px rgba(0,0,0,.7);";
-			this.tag = tag;
-			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;
+	/** 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
+		});
 	}
-	_sync() {
-		const label = this._t(this.label);
-		if (label !== this.lastLabel && this.tag) {
-			this.lastLabel = label;
-			this.tag.textContent = label;
-		}
-		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;
+	/** 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
+		};
 	}
-};
-/**
-* 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)`.
-*/
-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 ?? "";
+	play() {
+		if (this.preset !== "custom") {
+			this.note("preset", this.preset);
+			this.playPreset();
+			return;
+		}
+		if (!this.src) return;
+		this.note("src", this.src);
+		if (!this.element) {
+			this.element = createElement();
+			if (!this.element) return;
+			this.element.addEventListener("ended", () => {
+				if (this.loop) return;
+				this._playing = false;
+				this.emit("finished");
+			});
+			this.element.addEventListener("error", () => {
+				this._playing = false;
+				if (this.loadError) return;
+				this.loadError = `could not load ${this.src}`;
+				diagnose(this.tree?.engine ?? null, "error", `[incanto] AudioPlayer '${this.name}' could not load '${this.src}' — it is silent.`);
+			});
+		}
+		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((error) => {
+			this._playing = false;
+			const name = error?.name ?? "";
+			if (name !== "NotSupportedError") {
+				this.pendingGesture = true;
+				return;
+			}
+			this.loadError = `${name}: ${this.src}`;
+			diagnose(this.tree?.engine ?? null, "error", `[incanto] AudioPlayer '${this.name}' cannot play '${this.src}' (${name}) — it is silent.`);
+		});
 	}
-	show(text, opts) {
-		this.queue.push({
-			text,
-			color: opts?.color ?? "#ffffff",
-			seconds: opts?.seconds ?? this.seconds
+	/**
+	* 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()
 		});
 	}
-	/** Drop everything (scene transitions). */
-	clear() {
-		this.queue.length = 0;
-		this.current = null;
-		this.remaining = 0;
-		if (this._element) this._element.style.opacity = "0";
+	/**
+	* A destroyed node goes SILENT.
+	*
+	* Nothing used to stop a sound on teardown, so a level's looping background
+	* clip kept playing over the level after it — the node was freed, so nobody
+	* had a handle to stop it with either. Being MOVED is deliberately not this:
+	* reparenting a node is not destroying it, and a sound that survives the move
+	* is what a scene graph should do.
+	*/
+	free() {
+		this.stop();
+		super.free();
 	}
-	_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;
+	stop() {
+		if (this.element) {
+			this.element.pause();
+			this.element.currentTime = 0;
+		}
+		this._playing = false;
+		this.pendingGesture = false;
 	}
-	update(dt) {
-		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;
+	/** 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.current && this.queue.length > 0) {
-			this.current = this.queue.shift();
-			this.current.text = this._t(this.current.text);
-			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";
-			}
-			this.emit("bannerShown", this.current.text);
+		if (this.element && this._playing) {
+			this.element.volume = this.gain() * this.spatialElementGain();
+			this.element.loop = this.loop;
 		}
 	}
 };
@@ -2862,7 +2953,8 @@ var UiButton = class extends HudWidgetBase {
 	_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.style.cssText = this.look();
+		this.lastLook = this.look();
 		el.addEventListener("mouseenter", () => {
 			if (!this.disabled) el.style.background = "rgba(255,255,255,0.24)";
 		});
@@ -2878,8 +2970,19 @@ var UiButton = class extends HudWidgetBase {
 		el.addEventListener("click", () => this.press());
 		return el;
 	}
+	/** The whole look, so re-applying is one comparison. `size`/`color` were baked
+	*  in at build, and a button could never be restyled afterwards. */
+	look() {
+		return `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;`;
+	}
+	lastLook = "";
 	_sync() {
 		if (!this._element) return;
+		const look = this.look();
+		if (look !== this.lastLook) {
+			this.lastLook = look;
+			this._element.style.cssText = look;
+		}
 		const shown = this._t(this.text);
 		if (shown !== this.lastText) {
 			this.lastText = shown;
@@ -3274,7 +3377,7 @@ var UiSlider = class extends HudWidgetBase {
 		const wrap = document.createElement("div");
 		wrap.style.cssText = "display:flex;align-items:center;gap:8px;pointer-events:auto;font:600 13px system-ui,-apple-system,'Segoe UI',sans-serif;color:#fff;";
 		const text = document.createElement("span");
-		text.textContent = this.label;
+		text.textContent = this._t(this.label);
 		const input = document.createElement("input");
 		input.type = "range";
 		input.min = String(this.min);
@@ -3299,7 +3402,8 @@ var UiSlider = class extends HudWidgetBase {
 			this.last = this.value;
 			this.input.value = String(this.value);
 		}
-		if (this.text && this.text.textContent !== this.label) this.text.textContent = this.label;
+		const label = this._t(this.label);
+		if (this.text && this.text.textContent !== label) this.text.textContent = label;
 	}
 };
 /** An on/off switch — mute, invert-Y, fullscreen. Emits `changed(boolean)`. */
@@ -3338,17 +3442,26 @@ var UiToggle = class extends HudWidgetBase {
 			this.emit("changed", this.value);
 		});
 		const text = document.createElement("span");
-		text.textContent = this.label;
+		text.textContent = this._t(this.label);
+		this.tag = text;
+		this.lastLabel = this._t(this.label);
 		wrap.append(input, text);
 		this.input = input;
 		this.last = this.value;
 		return wrap;
 	}
+	tag = null;
+	lastLabel = "";
 	_sync() {
 		if (this.input && this.value !== this.last) {
 			this.last = this.value;
 			this.input.checked = this.value;
 		}
+		const label = this._t(this.label);
+		if (this.tag && label !== this.lastLabel) {
+			this.lastLabel = label;
+			this.tag.textContent = label;
+		}
 	}
 };
 /** One of several — quality, resolution, language. Emits `changed(value)`. */
@@ -3781,4 +3894,4 @@ function registerCoreNodes() {
 	registerNode(UiMuteToggle);
 }
 //#endregion
-export { BASE_LOCALE as A, SFX_PRESETS as B, qualityCaps as C, suggestQuality as D, readDeviceHints as E, SfxEngine as F, crossfadeGains as G, synthSfx as H, isAudioContextAvailable as I, fadeGain as K, ROLLOFF_MODELS as L, T_PREFIX as M, suggestLocale as N, LogManager as O, translationKey as P, spatialGain as R, Settings as S, qualityRendering as T, MusicManager as U, SFX_PRESET_NAMES as V, WebAudioMusicBackend as W, UiBanner as _, UiMuteToggle as a, AudioPlayer as b, UiRenderScaleSelect as c, UiToggle as d, UiVolumeSlider as f, HudLayer as g, UiDialogue as h, UiLanguageSelect as i, Localization as j, EffectLog as k, UiSelect as l, UiButton as m, UiFrameCapSelect as n, UiPanel as o, Timer as p, AudioBuses as q, UiImage as r, UiQualitySelect as s, registerCoreNodes as t, UiSlider as u, UiBar as v, qualityEnvironment as w, Engine as x, UiText as y, spatialPan as z };
+export { UiText as A, spatialPan as B, suggestQuality as C, HudWidgetBase as D, HudLayer as E, translationKey as F, WebAudioMusicBackend as G, SFX_PRESET_NAMES as H, SfxEngine as I, AudioBuses as J, crossfadeGains as K, isAudioContextAvailable as L, Localization as M, T_PREFIX as N, UiBanner as O, suggestLocale as P, ROLLOFF_MODELS as R, readDeviceHints as S, EffectLog as T, synthSfx as U, SFX_PRESETS as V, MusicManager as W, Engine as _, UiMuteToggle as a, qualityEnvironment as b, UiRenderScaleSelect as c, UiToggle as d, UiVolumeSlider as f, AudioPlayer as g, UiDialogue as h, UiLanguageSelect as i, BASE_LOCALE as j, UiBar as k, UiSelect as l, UiButton as m, UiFrameCapSelect as n, UiPanel as o, Timer as p, fadeGain as q, UiImage as r, UiQualitySelect as s, registerCoreNodes as t, UiSlider as u, Settings as v, LogManager as w, qualityRendering as x, qualityCaps as y, spatialGain as z };