incanto 0.68.0 → 0.70.0

package/dist/{register-3ta-2Xig.js → register-6DYnKZcy.js}

@@ -1,9 +1,8 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { C as ORDER_GROUP_BASE, E as InputMap, O as Node, S as createSaveStore, T as resolveOrderGroups, V as Signal, b as restoreBehaviors, k as diagnose, y as captureBehaviors } from "./loader-BC4PNtJX.js";
+import { o as __exportAll } from "./json-CfTjpvW8.js";
+import { B as TAPPABLE, G as requireText, H as UiBar, K as Node, L as FITS, N as resolveOrderGroups, P as InputMap, R as HudLayer, U as UiText, V as UiBanner, a as restoreBehaviors, i as captureBehaviors, j as ORDER_GROUP_BASE, k as createSaveStore, ot as Signal, q as diagnose, t as ENGINE_STATE_KEY, z as HudWidgetBase } from "./save-slots-BXVg148r.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { t as Rng } from "./rng-DP-SR7eg.js";
-import { l as registerNode } from "./registry-CF70EArN.js";
-import { r as capturePointer } from "./touch-DEAmqGdf.js";
+import { t as Rng } from "./rng-CDOMybym.js";
+import { p as registerNode } from "./touch-BnCyPA0G.js";
 //#region src/core/audio/buses.ts
 const AUDIO_LOG_LIMIT = 200;
 var AudioBuses = class {
@@ -22,15 +21,33 @@ var AudioBuses = class {
 	* Bounded (200) — a game running for an hour must not grow a log.
 	*/
 	events = [];
+	/**
+	* EVERY node that has sounded, ever — a set of paths, not a window.
+	*
+	* `recent()` is bounded at 200, which is right for a log and wrong for the
+	* question "is this AudioPlayer wired?". A game with one sound firing about
+	* three times a second overflows the window inside a minute, so a 60-second
+	* playtest read the tail and reported correctly-wired feedback as never
+	* fired. This grows with the SCENE, not with the run — which is true only
+	* because it records the AUTHORED path: a clone's own path is new every
+	* spawn, and recording those grew the set by one entry per enemy, forever,
+	* in every shipped game. See `Node.wiringPath`.
+	*/
+	sourcePaths = /* @__PURE__ */ new Set();
 	/** @internal Called by the players; games read `recent()`. */
 	record(event) {
 		this.events.push(event);
 		if (this.events.length > AUDIO_LOG_LIMIT) this.events.shift();
+		this.sourcePaths.add(event.wiredAs ?? event.from);
 	}
 	/** The last `limit` sounds, oldest first. */
 	recent(limit = AUDIO_LOG_LIMIT) {
 		return this.events.slice(Math.max(0, this.events.length - limit));
 	}
+	/** Every node path that has sounded since the last `clearLog()`. */
+	sources() {
+		return [...this.sourcePaths];
+	}
 	/** How many times a preset/clip/track sounded — the assertion you want. */
 	countOf(name) {
 		return this.events.reduce((n, e) => e.name === name ? n + 1 : n, 0);
@@ -38,11 +55,13 @@ var AudioBuses = class {
 	/** Forget what has sounded so far (between scenes, or between assertions). */
 	clearLog() {
 		this.events.length = 0;
+		this.sourcePaths.clear();
 	}
 	_master = 1;
 	_sfx = 1;
 	_music = 1;
 	_muted = false;
+	_suspended = false;
 	get master() {
 		return this._master;
 	}
@@ -69,9 +88,30 @@ var AudioBuses = class {
 		this._muted = v;
 		this.changed.emit();
 	}
+	/**
+	* Silence the game WITHOUT it counting as the player muting it.
+	*
+	* `pause-when-hidden` set `muted = true` when the tab went away, which fires
+	* `changed`, which `Settings.bindAudio` persists. Close the tab while it is
+	* hidden and `muted: true` is on disk: EVERY later session of that game boots
+	* silent, and no shipped starter has an in-game way back.
+	*
+	* A suspension is the engine's, not the player's. It never touches `muted`,
+	* so nothing persists it and unsuspending cannot turn the sound back on for
+	* someone who turned it off.
+	*/
+	suspend(on) {
+		if (on === this._suspended) return;
+		this._suspended = on;
+		this.changed.emit();
+	}
+	/** Is the engine holding the sound off (hidden tab), as against the player? */
+	get suspended() {
+		return this._suspended;
+	}
 	/** Final gain for a sound on `bus` with its own `sourceVolume` (all clamped). */
 	effectiveVolume(bus, sourceVolume) {
-		if (this._muted) return 0;
+		if (this._muted || this._suspended) return 0;
 		const busGain = bus === "music" ? this._music : this._sfx;
 		return this._master * busGain * clamp01$3(sourceVolume);
 	}
@@ -241,16 +281,36 @@ var WebAudioMusicBackend = class {
 };
 //#endregion
 //#region src/core/audio/music-manager.ts
-/** Mints silent tracks so the state machine runs with no audio backend. */
+/**
+* Mints silent tracks so the state machine runs with no audio backend.
+*
+* Including its CLOCK. `playhead: () => null` meant that headless — the verify
+* VM, the only place a game is checked automatically — "where is the song" had
+* no answer, so a game charted to a soundtrack could not be tested at all. The
+* silent track carries the same elapsed-seconds counter the fades already run
+* on. It has no duration to wrap at, so it counts up for as long as it plays.
+*/
 const SILENT_BACKEND = {
-	createTrack: (src) => ({
-		src,
-		setGain() {},
-		setLoop() {},
-		play() {},
-		stop() {},
-		playhead: () => null
-	}),
+	createTrack: (src) => {
+		let playing = false;
+		let at = 0;
+		return {
+			src,
+			setGain() {},
+			setLoop() {},
+			play() {
+				playing = true;
+			},
+			stop() {
+				playing = false;
+				at = 0;
+			},
+			tick(dt) {
+				if (playing && Number.isFinite(dt) && dt > 0) at += dt;
+			},
+			playhead: () => playing ? at : null
+		};
+	},
 	unlock() {}
 };
 /**
@@ -373,13 +433,6 @@ var MusicManager = class {
 	* it's a fade-in. Crossfading to the already-current src is a no-op.
 	*/
 	crossfadeTo(src, seconds = 2) {
-		this.buses.record({
-			kind: "music",
-			name: src,
-			from: "engine.music",
-			bus: this._bus,
-			at: 0
-		});
 		const backend = this.ensure();
 		if (this.active && this.active.track.src === src && this.active.phase !== "fadeOut") return;
 		const secs = Math.max(0, seconds);
@@ -387,6 +440,13 @@ var MusicManager = class {
 			this.play(src, { fadeIn: secs });
 			return;
 		}
+		this.buses.record({
+			kind: "music",
+			name: src,
+			from: "engine.music",
+			bus: this._bus,
+			at: 0
+		});
 		this.killOutgoing();
 		this.outgoing = {
 			...this.active,
@@ -446,6 +506,8 @@ var MusicManager = class {
 	}
 	/** Advance fades by `dt` seconds and (re)apply bus×fade gains. Frame-driven. */
 	tick(dt) {
+		this.active?.track.tick?.(dt);
+		this.outgoing?.track.tick?.(dt);
 		if (this.active && (this.active.phase === "fadeIn" || this.active.phase === "crossIn")) {
 			this.active.t += dt;
 			if (this.active.t >= this.active.duration) this.active.phase = "steady";
@@ -1063,11 +1125,27 @@ var SfxEngine = class {
 	* The AUDIO clock, in seconds — the one a sound is actually scheduled
 	* against, and the only clock that does not drift relative to what you hear.
 	*
-	* `0` headless and before the first sound, since there is no context yet.
 	* Schedule with a lead: `sfx.play(params, 1, { when: sfx.now + 0.08 })`.
+	*
+	* With no AudioContext — headless, and before the first sound — it is the
+	* engine's own real elapsed time instead of a frozen `0`. A constant made the
+	* documented lookahead scheduler queue the notes inside the first 80 ms and
+	* then nothing ever again: measured on a 21-beat metronome in the verify VM,
+	* **1 of 21 beats**, with no error and no warning. The silent clock runs so
+	* the schedule is reachable; nothing sounds either way.
 	*/
 	get now() {
-		return this.ctx?.currentTime ?? 0;
+		return this.ctx?.currentTime ?? this.silentNow;
+	}
+	/** The clock `now` reports when there is no context to ask. */
+	silentNow = 0;
+	/**
+	* @internal Advance the silent clock — the engine calls this every frame with
+	* the REAL dt, beside `music.tick`, because the audio does not slow down when
+	* the game does.
+	*/
+	_tick(dt) {
+		if (Number.isFinite(dt) && dt > 0) this.silentNow += dt;
 	}
 	/**
 	* Play a preset at `gain` (0..1, already bus-multiplied by the caller). Each
@@ -1257,728 +1335,28 @@ function translateOn(node, value) {
 	return locale ? locale.resolve(value) : value;
 }
 //#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();
-	}
-	/**
-	* 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);
-	}
-	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();
-	}
-	/**
-	* 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);
-			}
-		}
-	}
-	/**
-	* Focusable widgets under this layer, in tree order — **on screen only**.
-	*
-	* This filtered on each widget's OWN `visible` and recursed into hidden
-	* containers anyway, so arrow-keys walked into closed panels and Enter really
-	* pressed what it found. Measured on a title screen: 23 focus stops, 21 of
-	* them under an ancestor with `visible = false`, and
-	*
-	*   gold before = 150 -> Enter on the hidden Shop/Row0/Buy -> gold 120,
-	*   screen still 'title'
-	*
-	* The layer's own visibility was not a gate either. It is now: a HUD nobody
-	* can see has no ring, and a subtree nobody can see is not walked.
-	*
-	* PUBLIC, because a game that wants to know what its ring contains could not
-	* ask — and "why is focus on that" is exactly the question this answers.
-	*/
-	focusables() {
-		const out = [];
-		if (!this.visible) return out;
-		const walk = (node) => {
-			if (node instanceof HudWidgetBase && !node.visible) return;
-			if (node instanceof HudWidgetBase && node.focusable) 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();
-/** The nearest ancestor widget that actually accepts a drop. */
-function dropTargetFromElement(el) {
-	for (let n = el; n; n = n.parentElement) {
-		const found = widgetOf.get(n);
-		if (found?.dropTarget) return found;
-	}
-	return null;
-}
-function widgetFromElement(el) {
-	for (let n = el; n; n = n.parentElement) {
-		const found = widgetOf.get(n);
-		if (found) return found;
-	}
-	return null;
-}
-/** The drag in flight, if any. One pointer, one drag. */
-let dragging = null;
-/** The drop target the dragged widget came OUT of — putting it back is a no-op. */
-let draggingFrom = 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;
-	}
-	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;
-	/**
-	* @internal Confirm (`dir` 0) or nudge (-1 left / +1 right) — what pressing
-	* A or an arrow ON this widget means. Default: nothing.
-	*/
-	_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.
-	*
-	* 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.
-	*/
-	_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);
-	}
-	/**
-	* Drag and drop, on the DOM the engine already builds.
-	*
-	* 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();
-				capturePointer(el, event.pointerId);
-				dragging = this;
-				draggingFrom = dropTargetFromElement(el.parentElement);
-				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 under = document.elementFromPoint?.(event.clientX, event.clientY) ?? null;
-				const target = dropTargetFromElement(under) ?? widgetFromElement(under);
-				const origin = draggingFrom;
-				dragging = null;
-				draggingFrom = null;
-				if (target && target !== this && target !== origin && 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._followAnchor();
-		this._sync();
-		if (this._element.style.display !== "none") this._shownDisplay = this._element.style.display;
-		this._element.style.display = this.visible ? this._shownDisplay : "none";
-	}
-	/**
-	* The display this widget's own css asks for while shown — `grid` for a grid
-	* panel, `flex` for a row, `''` for a widget that never says.
-	*/
-	_shownDisplay = "";
-	/** Which anchor slot this widget was mounted into. */
-	mountedAnchor = null;
-	/**
-	* Move to the slot the anchor now names.
-	*
-	* `_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.
-	*/
-	_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() {}
-	/**
-	* Resolve a text prop through the engine's locale.
-	*
-	* 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.
-	*/
-	_t(value) {
-		const locale = this.tree?.engine?.locale;
-		return locale ? locale.resolve(value) : value;
-	}
-	/**
-	* A translation with an English wording to fall back to.
-	*
-	* For text the ENGINE supplies — "Music", "Mute", "Unlimited" — where there
-	* is no author string to carry a `@t:` marker. Asks `declares()`, not
-	* `has()`: a key only another locale declares would otherwise come back as
-	* the raw key, which is worse than the English.
-	*/
-	/**
-	* What this widget's label READS as — resolved every frame, never stored.
-	*
-	* `UiVolumeSlider` and `UiMuteToggle` used to compute their auto-label in
-	* `_build()` and write the result back into `this.label`, which broke them
-	* twice over: the per-frame `_t(this.label)` then had a plain string with no
-	* marker left to resolve, and `_build` runs from `onReady` — inside
-	* `loadScene`, BEFORE `setScene` merges the scene's `strings` — so the table
-	* was empty at bake time and the English was permanent even for a game that
-	* boots in another language.
-	*/
-	/**
-	* What this widget actually PAINTS, when that differs from its props.
-	*
-	* A headless capture printed `text="@t:menu.start"` — byte-identical in
-	* every language — so a passing capture proved nothing about localization
-	* and a broken translation was invisible to every check the engine has.
-	* `incanto-frame` reads the WebGL buffer and cannot read DOM text at all.
-	*
-	* `undefined` when the painted words ARE the prop: recording it twice would
-	* be noise on every widget in a game that never localizes anything.
-	*/
-	_paintedText() {}
-	_labelText() {
-		const label = this.label;
-		return typeof label === "string" ? this._t(label) : "";
-	}
-	_tOr(key, fallback) {
-		const locale = this.tree?.engine?.locale;
-		return locale?.declares(key) ? locale.t(key) : fallback;
-	}
-};
-/** 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.
-	*/
-	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);
-	}
-	_paintedText() {
-		const painted = this.shown;
-		return painted === this.text ? void 0 : painted;
-	}
-	_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;
-		}
-	}
-};
-/**
-* A bar fed the wrong argument shows a plausible wrong number forever.
-*
-* 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 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";
-	static props = {
-		...HudWidgetBase.props,
-		value: { default: 100 },
-		max: { default: 100 },
-		width: { default: 180 },
-		height: { default: 14 },
-		color: { default: "#4ade80" },
-		lowColor: { default: "#ef4444" },
-		lowThreshold: { default: .3 },
-		background: { default: "rgba(0,0,0,0.5)" },
-		label: { default: "" }
-	};
-	value = 100;
-	max = 100;
-	width = 180;
-	height = 14;
-	color = "#4ade80";
-	lowColor = "#ef4444";
-	lowThreshold = .3;
-	background = "rgba(0,0,0,0.5)";
-	label = "";
-	fill = null;
-	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;
-	}
-	/**
-	* Drive the bar from a signal — `healthChanged → setValue`.
-	*
-	* 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.
-	*/
-	setValue(value, max) {
-		this.value = requireNumber(value, this, "setValue");
-		if (max !== void 0) this.max = requireNumber(max, this, "setValue");
-	}
-	/** Move the ceiling on its own, leaving the fill where it is. */
-	setMax(max) {
-		this.max = requireNumber(max, this, "setMax");
-	}
-	_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;
-	}
-	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;`;
-	}
-	_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}%`;
-	}
-};
-/**
-* 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,
-			source: text,
-			color: opts?.color ?? "#ffffff",
-			seconds: opts?.seconds ?? this.seconds
-		});
-	}
-	/** 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.current) {
-			const next = this._t(this.current.source);
-			if (next !== this.current.text) {
-				this.current.text = next;
-				if (this._element) this._element.textContent = next;
-			}
-			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;
-		}
-		if (!this.current && this.queue.length > 0) {
-			this.current = this.queue.shift();
-			this.current.text = this._t(this.current.source);
-			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);
-		}
-	}
-};
-//#endregion
 //#region src/core/effects-log.ts
 const EFFECT_LOG_LIMIT = 200;
 var EffectLog = class {
 	events = [];
+	/**
+	* EVERY node that has fired, ever — a set of paths, not a window. See
+	* `AudioBuses.sources`: 200 entries is a log, and "is this emitter wired?"
+	* needs the whole run.
+	*
+	* AUTHORED paths, so it is bounded by the scene: a wave of forty enemies is
+	* one emitter fired forty times. See `Node.wiringPath`.
+	*/
+	sourcePaths = /* @__PURE__ */ new Set();
 	/** @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();
+		this.sourcePaths.add(event.wiredAs ?? event.from);
+	}
+	/** Every node path that has fired an effect since the last `clearLog()`. */
+	sources() {
+		return [...this.sourcePaths];
 	}
 	/** The last `limit` effects, oldest first. */
 	recent(limit = EFFECT_LOG_LIMIT) {
@@ -1995,6 +1373,7 @@ var EffectLog = class {
 	/** Forget what has fired so far (between scenes, or between assertions). */
 	clearLog() {
 		this.events.length = 0;
+		this.sourcePaths.clear();
 	}
 };
 //#endregion
@@ -2031,6 +1410,25 @@ var FrameStatsRing = class {
 		const span = this.spanMs();
 		return span > 0 ? span / (this.count - 1) : 0;
 	}
+	/**
+	* How long ago the newest sample arrived, in ms. `null` with no samples.
+	*
+	* `fps()` is a rate over a WINDOW, so it keeps answering after the frames
+	* stop: a hidden tab, a descheduled loop, a page the browser froze. Measured
+	* on an engine that ticked 40 times and then stopped being ticked:
+	*
+	*   while ticking      : fps 59.9
+	*   after 0 more ticks : fps 59.9      <- the last sample is 668 ms old
+	*
+	* Both numbers are true about the window they describe. What was missing was
+	* any way to ask WHEN that window was, so "60 fps" read the same whether it
+	* was measured 8 ms ago or four seconds ago.
+	*/
+	ageMs(nowMs) {
+		if (this.count === 0) return null;
+		const newest = this.times[(this.head + this.count - 1) % this.capacity];
+		return Math.max(0, nowMs - newest);
+	}
 	/** Forget all samples (engine.stop() — a paused game has no frame rate). */
 	clear() {
 		this.head = 0;
@@ -2387,6 +1785,28 @@ function qualityRendering(tier) {
 //#region src/core/engine.ts
 var engine_exports = /* @__PURE__ */ __exportAll({ Engine: () => Engine });
 const MAX_DT_SECONDS = .25;
+/**
+* The save API, called before the engine has a scene — which is what `onReady`
+* is.
+*
+* `loadScene(json, { engine })` attaches the engine to the TREE so a behavior
+* can use `this.engine` in `onReady`, and the ready pass runs there — before
+* `setScene` assigns `engine.scene`. So the natural place to put "continue my
+* save", the root behavior's own `onReady`, sees `scene === null`, and both
+* halves of the save API used to answer without a word:
+*
+* ```
+* captureState()          {}                            <- an empty slot, written over a good one
+* restoreState(saved)     missing: [every uid], expected: 0
+* ```
+*
+* The second is worse than silence: `missing` is documented as "a save naming a
+* uid this build deleted", so an idle game whose continue quietly did nothing
+* reported the shape of a save format change. Measured on a game built from the
+* tarball for exactly this — every number came back zero and every check was
+* green.
+*/
+const NO_SCENE_YET = (what, consequence) => `[incanto] ${what}() ran before the engine had a scene, and ${consequence}. \`onReady\` fires while the scene is still being loaded — \`engine.scene\` is not assigned until \`setScene\`. Save and restore AFTER the game boots: from the \`sceneChanged\` signal, or after \`createGame2D\`/\`createGame3D\` resolves.`;
 function rafScheduler(cb) {
 	let live = true;
 	let id = requestAnimationFrame(function loop(t) {
@@ -2433,6 +1853,93 @@ var Engine = class {
 	* learns about Rapier or three. From a behavior, prefer `this.physics`.
 	*/
 	physics = null;
+	/**
+	* How to build a physics world for a scene that needs one.
+	*
+	* `createGame2D`/`createGame3D` install this; core never learns what Rapier
+	* is. It exists because `physics: 'auto'` can only look at the scene the game
+	* BOOTED with, and the most universal act of finishing a game is putting a
+	* title screen in front of it:
+	*
+	* ```
+	* after boot on the title  : engine.physics = null
+	* after goToScene into game: engine.physics = null
+	* player y after 2 s       : 0 -> 0
+	* ```
+	*
+	* The game rendered perfectly and was inert — nothing fell, nothing collided,
+	* nothing could be collected or hurt. One scene swap turned a working game
+	* into a diorama, and nothing was logged.
+	*/
+	physicsProvider = null;
+	ensuring = null;
+	/**
+	* Give the current scene a physics world if it needs one and has none.
+	*
+	* Idempotent and safe to call on every swap: the provider decides whether the
+	* incoming tree actually wants physics, and an explicit `physics: false` at
+	* boot installs no provider at all, so opting out stays opted out.
+	*
+	* Asynchronous because the Rapier WASM has to load. The first frames after a
+	* swap therefore run unsimulated — which every AI behaviour already tolerates
+	* (`moveBody` falls back to a direct write when `_physics` is null) and which
+	* is a hitch, where the alternative was a game that never simulated at all.
+	*/
+	ensurePhysics() {
+		if (this.physics || !this.physicsProvider || !this._scene) return Promise.resolve();
+		if (this.ensuring) return this.ensuring;
+		const root = this._scene.root;
+		this.ensuring = this.physicsProvider(root).catch((e) => {
+			this.log.error(`[incanto] could not enable physics for this scene: ${String(e?.message ?? e)}`);
+		}).finally(() => {
+			this.ensuring = null;
+		});
+		return this.ensuring;
+	}
+	/**
+	* The seed this engine was built with — game logic draws from `rng`, and
+	* anything DECORATIVE derives its own stream from this instead.
+	*
+	* A particle emitter used to draw from `rng`, and it spawns a number of
+	* particles that depends on `dt`. Measured on the same scene and seed, the
+	* same simulated two seconds, comparing the world's own draws by update
+	* index:
+	*
+	* ```
+	* particles off:  60fps and 30fps identical
+	* particles ON :  they diverge at update 2
+	* ```
+	*
+	* So a purely visual effect changed the game's random decisions, and the
+	* PLAYER'S FRAME RATE decided them. Derived streams stay reproducible for
+	* replays and screenshots without spending the one the game reads.
+	*/
+	seed;
+	/**
+	* How to resolve an `instance:` sub-scene, remembered from the boot load.
+	*
+	* `loadScene(json, { engine, resolveScene })` records it here, so the paths
+	* that RELOAD — `restartScene`, `goToScene`, a game-over restart key — can
+	* pass it back. Without that a game using the documented sub-scenes booted
+	* fine and threw `UNRESOLVED_INSTANCE` on its first restart.
+	*/
+	resolveScene;
+	/**
+	* How the current scene was LOADED, for the rebuilds that happen later.
+	*
+	* `duplicateNode` — every `Spawner`, every `NetworkSpawner`, every clone a
+	* game makes — rebuilds a subtree from scene JSON long after `loadScene`
+	* returned, and it did so with no options at all. Under
+	* `stubMissingBehaviors` (how EVERY headless check runs a game whose scripts
+	* are TypeScript it cannot import) the first spawn met the real registry and
+	* threw `UNKNOWN_BEHAVIOR` out of `update`, disabling the spawner for the
+	* rest of the run — a wave game reported with no waves and nothing saying
+	* why.
+	*
+	* Recorded here for the same reason as `resolveScene` above: the engine
+	* outlives the call, and the rebuild paths can reach it.
+	*/
+	loadOptions = {};
 	/** Seeded randomness for game logic (deterministic when `seed` is set). */
 	rng;
 	/** The engine log channel (debug overlay + headless harness tail this). */
@@ -2447,6 +1954,57 @@ var Engine = class {
 	* and cleared on dispose; null when nothing renders (headless).
 	*/
 	picker = null;
+	/**
+	* Screen pixel → a point in the WORLD, when a renderer has offered one.
+	*
+	* `picker` answers "which node"; this answers "which place", and a mouse game
+	* needs both — drag-and-launch, drop a tower on the map, steer a cursor unit,
+	* draw the slingshot band. The conversion has always existed
+	* (`Renderer2D.worldFromScreen` / `Renderer3D.worldFromScreen`) and lived
+	* only on the renderer, so a Behavior — which holds a node and an engine and
+	* nothing else — could not call it. Its two workarounds were both forbidden:
+	* stash the renderer in a module global, or hand-roll the projection the 2D
+	* skill says in so many words not to hand-roll.
+	*
+	* The answer is the scene's own units and shape: `[x, y]` in 2D (design
+	* pixels), `[x, y, z]` on the ground plane in 3D — the same array a node's
+	* `position` is, so it goes straight back into one.
+	*
+	* Instance-scoped, set by the renderer on construction and cleared on
+	* dispose. Headless a harness may install a geometric one; null when nothing
+	* has.
+	*/
+	toWorld = null;
+	/**
+	* A world point → the screen pixel drawing it. The inverse of `toWorld`, for
+	* pinning DOM to a node or placing a marker over one.
+	*
+	* `behind` is true when the point is behind the camera (3D); a 2D renderer
+	* always reports false.
+	*/
+	toScreen = null;
+	/**
+	* Where the cursor is in the world, or null.
+	*
+	* The two-line dance every mouse game writes — read the pointer, convert it —
+	* with the two ways it goes wrong already handled: a pointer nothing has
+	* moved yet is null rather than the origin, and no converter is null rather
+	* than a guess.
+	*/
+	/**
+	* Screen pixel → a ray into the world, when a renderer has offered one.
+	*
+	* `toWorld` lands on a plane; this is the general form, and it is what a shot
+	* aimed at what the cursor is OVER needs: feed it straight to
+	* `engine.physics.castRay(origin, dir, …)`. 3D only — a 2D renderer installs
+	* nothing here, since a 2D world has no depth to cast into.
+	*/
+	screenRay = null;
+	pointerWorld() {
+		const at = this.input.pointerPosition();
+		if (!at || !this.toWorld) return null;
+		return this.toWorld(at.x, at.y);
+	}
 	/** Frames the engine has stepped — monotonic, and the pick cache's key. */
 	frameNumber = 0;
 	/** @internal frame number + answer, so N Clickables cost ONE raycast. */
@@ -2535,7 +2093,35 @@ var Engine = class {
 	* (hit-stop / pause). Scales BOTH variable and fixed updates — physics,
 	* timers, behaviors all breathe together. See `gameplay` `hitStop()`.
 	*/
-	timeScale = 1;
+	get timeScale() {
+		return this._timeScale;
+	}
+	set timeScale(v) {
+		if (!Number.isFinite(v)) {
+			diagnose(this, "warn", `[incanto] timeScale must be a finite number, got ${v} — keeping ${this._timeScale}.`);
+			return;
+		}
+		this._timeScale = v;
+		this._timeScaleWrites += 1;
+	}
+	_timeScale = 1;
+	_timeScaleWrites = 0;
+	/**
+	* How many times anyone has written `timeScale` — the clock's ownership tag.
+	*
+	* A temporary freeze cannot tell its own 0 from somebody else's by VALUE.
+	* `hitStop(engine)` then `flow.gameOver()` is the ordinary killing blow, and
+	* both set 0; the freeze then wrote its captured scale back five frames later
+	* and the world started moving again behind a sticky GAME OVER banner —
+	* enemies walking, timers running, the player watching their corpse get shot.
+	*
+	* A counter answers the question the value cannot: *has anyone touched this
+	* since I did?* Cheap (one increment per write, and writes are rare) and it
+	* needs no registry of who holds what.
+	*/
+	get timeScaleWrites() {
+		return this._timeScaleWrites;
+	}
 	/**
 	* 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).
@@ -2558,11 +2144,39 @@ var Engine = class {
 	get unscaledTime() {
 		return this._unscaledTime;
 	}
+	/**
+	* THIS frame's dt in real seconds — the one a paused game still gets.
+	*
+	* `update(dt)` receives the SCALED dt, which is right for anything that is
+	* part of the simulation and wrong for everything that is a presentation of
+	* it. At `timeScale = 0` — which is what `GameFlow.pause()` and, by default,
+	* `gameOver()` set — a scaled countdown does not count:
+	*
+	*   a timed UiBanner still up when the player dies never expires, so the
+	*     flow's own sticky GAME OVER banner is queued behind it and NEVER
+	*     PAINTED — the ending screen shows the last wave toast, forever
+	*   a live CameraShake never settles: `t -= dt` is a no-op while the rest of
+	*     update() re-rolls a full-magnitude offset every rendered frame, and
+	*     with FollowCamera's smoothing that is an unbounded random walk
+	*   a remote player's interpolation stops, so everyone else is a statue while
+	*     their real positions keep arriving
+	*
+	* `hitStop`, `AudioPlayer` and `music.tick` already use the real clock for
+	* exactly this reason. This is the same clock, per frame, so a countdown can
+	* use it without reading `unscaledTime` twice and subtracting.
+	*/
+	get unscaledDelta() {
+		return this._unscaledDelta;
+	}
+	_unscaledDelta = 0;
 	constructor(opts = {}) {
-		this.fixedStep = 1 / (opts.fixedHz ?? 60);
+		const hz = opts.fixedHz ?? 60;
+		if (!Number.isFinite(hz) || hz <= 0) throw new IncantoError("PROP_TYPE_MISMATCH", `fixedHz must be a finite positive rate in Hz, got ${hz}. 60 is the default; 30 halves physics cost.`);
+		this.fixedStep = 1 / hz;
 		this.maxFixedSteps = opts.maxFixedStepsPerTick ?? 5;
 		this.scheduler = opts.scheduler ?? rafScheduler;
-		this.rng = new Rng(opts.seed ?? Math.random() * 4294967295 >>> 0);
+		this.seed = opts.seed ?? Math.random() * 4294967295 >>> 0;
+		this.rng = new Rng(this.seed);
 		this.maxFps = opts.maxFps ?? 0;
 		this.settings = opts.settings instanceof Settings ? opts.settings : new Settings(opts.settings?.namespace ?? "settings");
 		this.sfx._setBuses(this.audio);
@@ -2576,17 +2190,30 @@ var Engine = class {
 	/** 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();
+		const leaving = this._scene;
+		if (this.swapping) {
+			diagnose(this, "error", "[incanto] setScene() was called from inside a scene teardown — ignoring the inner call. Free a scene once; wire the next one from `sceneChanged` instead.");
+			return;
+		}
+		this.swapping = true;
+		try {
+			leaving?.root.free();
+			leaving?.tree._setEngine(null);
+		} finally {
+			this.swapping = false;
+		}
 		this._scene = scene;
 		scene.tree._setEngine(this);
 		this.input.clear();
 		this._time = 0;
 		this._unscaledTime = 0;
 		this.timeScale = 1;
+		this.accumulator = 0;
 		if (scene.input) this.input.declare(scene.input);
 		if (scene.strings) this.locale.load(scene.strings);
 		this.orderGroups = resolveOrderGroups(scene.orderGroups);
+		this.audio.clearLog();
+		this.effects.clearLog();
 		this.sceneChanged.emit(scene);
 	}
 	start() {
@@ -2663,6 +2290,29 @@ var Engine = class {
 	_nodeErrored(_node) {
 		this.errorCount += 1;
 	}
+	/**
+	* @internal Something OUTSIDE a frame failed — a replication send that
+	* rejected, a transport that refused. Count it and say it once.
+	*
+	* `stats().errors` is what every harness in the ecosystem ends with, and it
+	* only ever counted things that threw INSIDE a frame. A multiplayer client
+	* whose socket died kept running perfectly on its own screen while every
+	* other player watched it frozen, and `errors: 0` with an empty log said the
+	* game was fine. Repeats are counted and not re-printed, for the reason
+	* `reportFrameError` gives: sixty identical traces a second is how you lose
+	* the first one.
+	*/
+	_asyncFailed(what, error) {
+		this.errorCount += 1;
+		const line = `${what}: ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`;
+		if (line === this.lastAsyncError) return;
+		this.lastAsyncError = line;
+		this.log.error(`[incanto] ${line}`);
+		console.error(`[incanto] ${line}`);
+	}
+	lastAsyncError = null;
+	/** Re-entrancy guard for `setScene` — an exit hook can now reach the engine. */
+	swapping = false;
 	errorCount = 0;
 	lastFrameError = null;
 	/**
@@ -2688,25 +2338,51 @@ var Engine = class {
 	* core/save-slots.ts for why a save carries state rather than a tree
 	* snapshot.
 	*/
+	/**
+	* Behaviors whose `serialize()` threw during the LAST `captureState()`.
+	*
+	* A write path that cannot see part of the run must not overwrite the slot
+	* that still can — `SavePoint.save()` reads this and refuses.
+	*/
+	get lastCaptureFailures() {
+		return this._captureFailures;
+	}
+	_captureFailures = [];
 	captureState() {
 		const root = this.scene?.root;
-		if (!root) return {};
-		const { state, unaddressable, unrecordable } = captureBehaviors(root, this.scene?.source);
+		if (!root) {
+			diagnose(this, "error", NO_SCENE_YET("captureState", "saved an EMPTY slot"));
+			return {};
+		}
+		const { state, unaddressable, unrecordable, failed } = captureBehaviors(root, this.scene?.source, this.scene?.authoredUids);
 		for (const path of unaddressable) diagnose(this, "warn", `save: ${path} has state to save and no uid to key it under.`);
+		this._captureFailures = failed;
+		if (failed.length > 0) diagnose(this, "error", `[incanto] save: ${failed.length} behavior(s) threw out of serialize(), so their state is NOT in this save: ${failed.slice(0, 4).join("; ")}${failed.length > 4 ? `, +${failed.length - 4} more` : ""}.`);
 		if (unrecordable.length > 0) diagnose(this, "error", `[incanto] save: ${unrecordable.length} authored node(s) this run consumed have no uid, so nothing records that they are gone and LOADING THIS SAVE BRINGS THEM BACK: ${unrecordable.slice(0, 8).join(", ")}${unrecordable.length > 8 ? `, +${unrecordable.length - 8} more` : ""}. Give each one a "uid" from newUid().`);
+		state[ENGINE_STATE_KEY] = { rng: this.rng.position };
 		return state;
 	}
 	/** Give it back, after the scene is loaded and onReady has run. */
 	restoreState(state) {
+		const engineState = state[ENGINE_STATE_KEY];
+		if (typeof engineState?.rng === "number") this.rng.position = engineState.rng;
 		const root = this.scene?.root;
-		if (!root) return {
-			missing: Object.keys(state),
-			skipped: [],
-			restored: 0,
-			expected: 0,
-			freed: 0
-		};
-		return restoreBehaviors(root, state);
+		if (!root) {
+			diagnose(this, "error", NO_SCENE_YET("restoreState", "restored NOTHING"));
+			return {
+				missing: Object.keys(state).filter((k) => k !== ENGINE_STATE_KEY),
+				skipped: [],
+				refused: [],
+				unannounced: [],
+				stale: [],
+				restored: 0,
+				expected: 0,
+				freed: 0
+			};
+		}
+		const report = restoreBehaviors(root, state, this.scene?.authoredUids);
+		if (report.stale.length > 0) diagnose(this, "warn", `[incanto] restore: ${report.stale.length} authored node(s) are missing from this scene and the save does not say they were consumed — this scene has been PLAYED since it loaded, so the restore leaves THIS run's changes in place. Reload the scene first (GameFlow.restart with restoreOnReady, or restartScene(engine) then restore) — note the SavePoint node is a NEW one after a restart. Starting with '${report.stale[0]}'.`);
+		return report;
 	}
 	erroredNodes() {
 		const out = [];
@@ -2756,6 +2432,7 @@ var Engine = class {
 		return {
 			fps: this.frameStats.fps(),
 			frameMs: this.frameStats.frameMs(),
+			lastFrameAgeMs: this.frameStats.ageMs(performance.now()),
 			nodes: this._scene?.tree.root ? countNodes(this._scene.tree.root) : 0,
 			running: this.disposeScheduler !== null,
 			errors: this.errorCount,
@@ -2780,11 +2457,18 @@ var Engine = class {
 	*/
 	dispose() {
 		this.stop();
+		const physics = this.physics;
+		this.physics = null;
+		try {
+			physics?.dispose();
+		} catch (error) {
+			diagnose(this, "warn", "[incanto] teardown: physics failed (continuing)", error);
+		}
 		this.music.dispose();
 		this.sfx.dispose();
 		if (this._scene) {
-			this._scene.tree._setEngine(null);
 			this._scene.root.free();
+			this._scene.tree._setEngine(null);
 			this._scene = null;
 			this.sceneChanged.emit(null);
 		}
@@ -2807,13 +2491,18 @@ var Engine = class {
 		const dt = this.fixedStep * (opts.ignorePause ? 1 : this.timeScale);
 		this._time += dt;
 		this._unscaledTime += this.fixedStep;
+		this._unscaledDelta = this.fixedStep;
 		const startedFixed = performance.now();
+		this.input.beginFrame();
+		this.input.beginFixedStep();
 		scene.tree.fixedUpdate(dt);
 		this.fixedUpdated.emit(dt);
+		this.input.endFixedStep();
 		const startedUpdate = performance.now();
 		this.frameNumber += 1;
 		scene.tree.update(dt);
-		this.music.tick(dt);
+		this.music.tick(this.fixedStep);
+		this.sfx._tick(this.fixedStep);
 		this.updated.emit(dt);
 		const ended = performance.now();
 		const updateMs = Math.max(0, ended - startedUpdate - this.renderMs);
@@ -2828,19 +2517,25 @@ var Engine = class {
 			this.lastMs = nowMs;
 			return;
 		}
-		const rawDt = Math.max(0, Math.min((nowMs - this.lastMs) / 1e3, MAX_DT_SECONDS));
+		const raw = (nowMs - this.lastMs) / 1e3;
+		if (!Number.isFinite(raw)) diagnose(this, "warn", `[incanto] tick() was handed a non-finite timestamp (${nowMs}); this frame is skipped. A NaN here used to stop every fixed step for the life of the engine.`);
+		const rawDt = Number.isFinite(raw) ? Math.max(0, Math.min(raw, MAX_DT_SECONDS)) : 0;
 		const dt = rawDt * this.timeScale;
 		this._time += dt;
 		this._unscaledTime += rawDt;
+		this._unscaledDelta = rawDt;
 		this.lastMs = nowMs;
 		const scene = this._scene;
 		if (!scene) return;
+		this.input.beginFrame();
 		this.accumulator += dt;
 		let steps = 0;
 		const startedFixed = performance.now();
 		while (this.accumulator >= this.fixedStep && steps < this.maxFixedSteps) {
+			this.input.beginFixedStep();
 			scene.tree.fixedUpdate(this.fixedStep);
 			this.fixedUpdated.emit(this.fixedStep);
+			this.input.endFixedStep();
 			this.accumulator -= this.fixedStep;
 			steps += 1;
 		}
@@ -2848,7 +2543,8 @@ var Engine = class {
 		const startedUpdate = performance.now();
 		this.frameNumber += 1;
 		scene.tree.update(dt);
-		this.music.tick(dt);
+		this.music.tick(rawDt);
+		this.sfx._tick(rawDt);
 		this.updated.emit(dt);
 		const ended = performance.now();
 		const updateMs = Math.max(0, ended - startedUpdate - this.renderMs);
@@ -2887,12 +2583,24 @@ var AudioPlayer = class extends Node {
 	static typeName = "AudioPlayer";
 	static signals = ["finished"];
 	static props = {
-		src: { default: "" },
+		src: {
+			default: "",
+			asset: {
+				kind: "audio",
+				urlOnly: true
+			}
+		},
 		preset: {
 			default: "custom",
 			options: ["custom", ...SFX_PRESET_NAMES]
 		},
-		volume: { default: 1 },
+		volume: {
+			default: 1,
+			range: {
+				min: 0,
+				max: 1
+			}
+		},
 		pitch: { default: 1 },
 		seed: { default: 0 },
 		bus: {
@@ -3006,8 +2714,10 @@ var AudioPlayer = class extends Node {
 			kind,
 			name,
 			from: this.getPath(),
+			wiredAs: this.wiringPath(),
 			bus: this.bus === "music" ? "music" : "sfx",
-			at: engine.time
+			at: engine.time,
+			...this.loop ? { loop: true } : {}
 		});
 	}
 	/** Final gain = engine buses × this volume (1 when not in a tree). */
@@ -3040,31 +2750,57 @@ var AudioPlayer = class extends Node {
 		};
 	}
 	/**
-	* Start the sound. `at` schedules it on the AUDIO clock instead of now.
+	* Start the sound, now.
+	*
+	* **Takes no arguments, on purpose.** This is the method scenes wire signals
+	* to — `incanto-audio.md` teaches
+	* `{"signal": "collected", "from": "Player/Collector", "to": "Coin",
+	* "handler": "play"}` — and a signal hands its handler whatever it carries.
+	* `collected` leads with a NUMBER. When this briefly took an optional
+	* scheduling time, that wiring became `play(10)`, which scheduled the pickup
+	* sound at ABSOLUTE audio-clock second 10: inaudible for the first ten
+	* seconds of the game and fine thereafter. The same optional parameter also
+	* made `Function.length` 1, so the engine's own arity checker cried wolf on
+	* the shipped `platformer-2d` template's own harness.
+	*
+	* Scheduling has its own name: {@link playAt}.
+	*/
+	/**
+	* Start the sound at `when` on the AUDIO clock (`engine.sfx.now` + a lead).
 	*
 	* A frame is a 16.67 ms grid at 60 Hz and 33.33 ms at 30, so a sound fired
 	* from `update()` cannot land closer than one frame to where a chart wants
-	* it — measured 0 of 64 notes scheduled on the documented path. Queue it a
-	* lead ahead of `engine.sfx.now` and the same notes land at |mean| 0.000000
-	* ms:
+	* it — measured 0 of 64 notes given a scheduled start. Queue them a lead
+	* ahead and the same notes land at |mean| 0.000000 ms:
 	*
 	* ```ts
-	* const lead = 0.08;                        // schedule this far ahead
-	* for (const note of dueSoon(engine.sfx.now + lead)) {
-	*   hit.play(engine.sfx.now + (note.atSec - songSeconds));
+	* const LEAD = 0.08;
+	* for (const note of dueSoon(engine.sfx.now + LEAD)) {
+	*   hit.playAt(startedAt + note.atSec);
 	* }
 	* ```
 	*
 	* PRESETS only — a `src` clip goes through an `<audio>` element, which has no
-	* scheduling clock, and passing `at` for one is ignored rather than silently
-	* approximated. Everything else is unchanged: the bus gain applies, the sound
-	* lands in `engine.audio.recent()`, and `muted` still silences it, none of
-	* which a hand-rolled `AudioContext` scheduler keeps.
+	* scheduling clock, so `playAt` on one plays immediately rather than being
+	* silently approximated. A time already past plays now (Web Audio's own
+	* rule), so a late scheduler is late, not silent. The bus gain, the
+	* `engine.audio.recent()` entry and `muted` all still apply.
+	*
+	* Separate from {@link play} because `play` is what scenes wire signals to,
+	* and a signal hands its handler whatever it carries.
 	*/
-	play(at) {
+	playAt(when) {
+		if (this.preset !== "custom") {
+			this.note("preset", this.preset);
+			this.playPreset(Number.isFinite(when) ? when : void 0);
+			return;
+		}
+		this.play();
+	}
+	play() {
 		if (this.preset !== "custom") {
 			this.note("preset", this.preset);
-			this.playPreset(at);
+			this.playPreset();
 			return;
 		}
 		if (!this.src) return;
@@ -3231,7 +2967,7 @@ var UiButton = class extends HudWidgetBase {
 	/** 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;`;
+		return `${TAPPABLE}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() {
@@ -3308,7 +3044,9 @@ var UiDialogue = class extends HudWidgetBase {
 		return this.current ? this.current.text.slice(0, Math.floor(this.revealed)) : "";
 	}
 	/** Queue a line; optional `choices` renders buttons after the line types out. */
-	say(speaker, text, choices) {
+	say(speaker, text, choices = void 0) {
+		requireText(speaker, this, "UiDialogue.say (speaker)");
+		requireText(text, this, "UiDialogue.say (text)");
 		const source = {
 			speaker,
 			text,
@@ -3339,6 +3077,16 @@ var UiDialogue = class extends HudWidgetBase {
 	* `dir` is 0 for "activate" and ±1 for a nudge, the same shape `UiSelect`
 	* uses — so one key layout drives a menu, a slider and a conversation.
 	*/
+	/**
+	* A click on the BOX is `advance()`, which refuses to skip a choice.
+	*
+	* The DOM handler is `box.addEventListener('click', () => this.advance())`
+	* and `advance` returns early while `current.choices` is set. Enter is a
+	* different verb — it answers — so a harness clicking the box must not.
+	*/
+	_click() {
+		this.advance();
+	}
 	_activate(dir) {
 		if (!this.active || !this.current) return;
 		const choices = this.current.choices;
@@ -3399,7 +3147,7 @@ var UiDialogue = class extends HudWidgetBase {
 	}
 	_build() {
 		const box = document.createElement("div");
-		box.style.cssText = `pointer-events:auto;width:${this.width}px;max-width:86vw;background:rgba(12,14,22,0.92);border:1px solid rgba(255,255,255,0.2);border-radius:12px;padding:14px 18px;display:none;font:15px/1.5 system-ui,sans-serif;color:#fff;cursor:pointer;user-select:none;`;
+		box.style.cssText = `${TAPPABLE}width:${this.width}px;${FITS}background:rgba(12,14,22,0.92);border:1px solid rgba(255,255,255,0.2);border-radius:12px;padding:14px 18px;display:none;font:15px/1.5 system-ui,sans-serif;color:#fff;cursor:pointer;user-select:none;`;
 		this.speakerEl = document.createElement("div");
 		this.speakerEl.style.cssText = "font-weight:800;color:#ffd166;margin-bottom:4px;font-size:13px;";
 		this.textEl = document.createElement("div");
@@ -3453,7 +3201,7 @@ var UiDialogue = class extends HudWidgetBase {
 			const b = document.createElement("button");
 			b.type = "button";
 			b.textContent = label;
-			b.style.cssText = "pointer-events:auto;cursor:pointer;font:600 13px system-ui,sans-serif;color:#fff;background:rgba(255,255,255,0.12);border:1px solid rgba(255,255,255,0.3);border-radius:8px;padding:6px 14px;";
+			b.style.cssText = `${TAPPABLE}cursor:pointer;font:600 13px system-ui,sans-serif;color:#fff;background:rgba(255,255,255,0.12);border:1px solid rgba(255,255,255,0.3);border-radius:8px;padding:6px 14px;`;
 			b.addEventListener("click", (e) => {
 				e.stopPropagation();
 				this.choose(i);
@@ -3637,14 +3385,27 @@ var Timer = class extends Node {
 	autostart = false;
 	running = false;
 	remaining = 0;
-	start(time) {
-		if (time !== void 0) this.waitTime = time;
+	start(time = this.waitTime) {
+		this.waitTime = time;
 		this.remaining = this.waitTime;
 		this.running = true;
 	}
 	stop() {
 		this.running = false;
 	}
+	/**
+	* Scene-load validation: a period of zero is a timer that never fires.
+	*
+	* `update` guards it — a non-positive period "would spin forever on any dt",
+	* so it calls `stop()` — and the guard is right. Being SILENT about it is
+	* what a load error is for: a scene asking for a tick every zero seconds got
+	* no ticks and no word said. The runtime guard stays, for code that zeroes
+	* the period from a handler.
+	*/
+	static validateJson(node) {
+		const timer = node;
+		if (!(timer.waitTime > 0)) throw new IncantoError("PROP_TYPE_MISMATCH", `Timer '${node.name}': "waitTime" must be > 0, got ${timer.waitTime} — a timer with no period never fires (it stops itself on the first frame).`, { prop: "waitTime" });
+	}
 	onReady() {
 		if (this.autostart) this.start();
 	}
@@ -3665,6 +3426,20 @@ var Timer = class extends Node {
 };
 //#endregion
 //#region src/core/nodes/ui-kit.ts
+/**
+* The widgets a MENU is made of.
+*
+* The HUD kit could say things — text, a bar, a banner, a button — and could not
+* arrange them or take a value back. So every title screen, pause menu, options
+* panel, inventory grid and shop in every game built on this engine was
+* hand-rolled DOM: `star-survivor`'s level-up menu builds its own elements, which
+* drops it out of scene JSON, out of the editor, out of `incanto-check`, and out
+* of every headless verification the agent has.
+*
+* These are the missing pieces, and they are deliberately the SAME kind of thing
+* the existing widgets are — nodes in the tree, props in JSON, DOM built by the
+* engine — so an inventory is a scene, not a component library.
+*/
 function px(n) {
 	return `${n}px`;
 }
@@ -3734,7 +3509,7 @@ var UiPanel = class extends HudWidgetBase {
 		return this._element;
 	}
 	css() {
-		return `${this.layout === "grid" ? `display:grid;grid-template-columns:repeat(${Math.max(1, this.columns)},auto);` : `display:flex;flex-direction:${this.layout};align-items:stretch;`}gap:${px(this.gap)};padding:${px(this.padding)};background:${this.background};border-radius:${px(this.radius)};` + (this.width > 0 ? `width:${px(this.width)};` : "") + (this.height > 0 ? `height:${px(this.height)};` : "") + (this.border ? `border:${this.border};` : "") + "box-sizing:border-box;pointer-events:auto;";
+		return `${this.layout === "grid" ? `display:grid;grid-template-columns:repeat(${Math.max(1, this.columns)},auto);` : `display:flex;flex-direction:${this.layout};align-items:stretch;`}gap:${px(this.gap)};padding:${px(this.padding)};background:${this.background};border-radius:${px(this.radius)};` + (this.width > 0 ? `width:${px(this.width)};` : "") + `${FITS}max-height:calc(100vh - 32px);overflow:auto;` + (this.height > 0 ? `height:${px(this.height)};` : "") + (this.border ? `border:${this.border};` : "") + `box-sizing:border-box;${TAPPABLE}`;
 	}
 	_sync() {
 		const next = this.css();
@@ -3766,7 +3541,13 @@ var UiImage = class extends HudWidgetBase {
 		},
 		/** Multiply the image by a colour: greyed-out items, team tints. */
 		tint: { default: "" },
-		opacity: { default: 1 }
+		opacity: {
+			default: 1,
+			range: {
+				min: 0,
+				max: 1
+			}
+		}
 	};
 	src = "";
 	width = 48;
@@ -3790,7 +3571,7 @@ var UiImage = class extends HudWidgetBase {
 	}
 	css() {
 		const url = this.resolved();
-		return `width:${px(this.width)};height:${px(this.height)};flex:none;` + (url ? `background-image:url("${url}");` : "") + `background-size:${this.fit === "fill" ? "100% 100%" : this.fit};background-position:center;background-repeat:no-repeat;opacity:${this.opacity};` + (this.tint ? `background-color:${this.tint};background-blend-mode:multiply;` : "");
+		return `width:${px(this.width)};height:${px(this.height)};flex:none;${FITS}` + (url ? `background-image:url("${url}");` : "") + `background-size:${this.fit === "fill" ? "100% 100%" : this.fit};background-position:center;background-repeat:no-repeat;opacity:${this.opacity};` + (this.tint ? `background-color:${this.tint};background-blend-mode:multiply;` : "");
 	}
 	_sync() {
 		const next = this.key();
@@ -3843,7 +3624,7 @@ var UiSlider = class extends HudWidgetBase {
 	last = NaN;
 	_build() {
 		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;";
+		wrap.style.cssText = `display:flex;align-items:center;gap:8px;${TAPPABLE}font:600 13px system-ui,-apple-system,'Segoe UI',sans-serif;color:#fff;`;
 		const text = document.createElement("span");
 		text.textContent = this._labelText();
 		const input = document.createElement("input");
@@ -3852,7 +3633,7 @@ var UiSlider = class extends HudWidgetBase {
 		input.max = String(this.max);
 		input.step = String(this.step);
 		input.value = String(this.value);
-		input.style.cssText = `width:${px(this.width)};accent-color:${this.color};`;
+		input.style.cssText = `width:${px(this.width)};accent-color:${this.color};${FITS}`;
 		input.addEventListener("input", () => {
 			this.value = Number(input.value);
 			this.last = this.value;
@@ -3900,7 +3681,7 @@ var UiToggle = class extends HudWidgetBase {
 	last = null;
 	_build() {
 		const wrap = document.createElement("label");
-		wrap.style.cssText = "display:flex;align-items:center;gap:8px;pointer-events:auto;cursor:pointer;font:600 13px system-ui,-apple-system,'Segoe UI',sans-serif;color:#fff;";
+		wrap.style.cssText = `display:flex;align-items:center;gap:8px;${TAPPABLE}cursor:pointer;font:600 13px system-ui,-apple-system,'Segoe UI',sans-serif;color:#fff;`;
 		const input = document.createElement("input");
 		input.type = "checkbox";
 		input.checked = this.value;
@@ -3948,6 +3729,29 @@ var UiSelect = class extends HudWidgetBase {
 	options = "";
 	value = "";
 	focusable = true;
+	/** The options, as the list of values it actually offers. */
+	choices() {
+		return this.options.split(",").map((o) => o.trim()).filter(Boolean);
+	}
+	/**
+	* A value the list cannot show is a setting the game and the screen disagree
+	* about.
+	*
+	* The browser cannot select an option that does not exist, so it shows the
+	* FIRST one — while `node.value` keeps answering with what it was given, and
+	* `changed` only fires when a person moves it, so nothing ever reconciles
+	* them. That is the shape a saved setting has after a patch removes a quality
+	* tier, and it is silent for the rest of the session.
+	*
+	* A hard error at LOAD, like every other enum in this engine. An empty value
+	* is "nothing chosen yet", which is a choice.
+	*/
+	static validateJson(node) {
+		const self = node;
+		const choices = self.choices();
+		if (self.value === "" || choices.length === 0 || choices.includes(self.value)) return;
+		throw new IncantoError("PROP_TYPE_MISMATCH", `UiSelect '${node.name}' has value '${self.value}', which is not one of its options [${choices.join(", ")}] — the browser would show the first one instead, and the game would go on believing the value it was given.`, { prop: "value" });
+	}
 	/** Left/right (and confirm) walk the list — a select has no other gesture. */
 	_activate(dir) {
 		const choices = this.options.split(",").map((o) => o.trim()).filter(Boolean);
@@ -3966,7 +3770,7 @@ var UiSelect = class extends HudWidgetBase {
 	last = "\0";
 	_build() {
 		const wrap = document.createElement("label");
-		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;";
+		wrap.style.cssText = `display:flex;align-items:center;gap:8px;${TAPPABLE}font:600 13px system-ui,-apple-system,'Segoe UI',sans-serif;color:#fff;`;
 		const text = document.createElement("span");
 		this.labelEl = text;
 		const select = document.createElement("select");
@@ -4010,6 +3814,25 @@ var UiSelect = class extends HudWidgetBase {
 		if (this.value) select.value = this.value;
 		this.last = this.value;
 	}
+	/** What was already reported, so a stuck value is said once and not per frame. */
+	complainedAbout = "\0";
+	/**
+	* The runtime half of `validateJson`.
+	*
+	* A behaviour may legitimately write the value first and widen `options`
+	* after — so this reports rather than refuses, and goes quiet again when the
+	* list catches up.
+	*/
+	reportMismatch() {
+		const choices = this.choices();
+		if (!(this.value !== "" && choices.length > 0 && !choices.includes(this.value))) {
+			this.complainedAbout = "\0";
+			return;
+		}
+		if (this.complainedAbout === this.value) return;
+		this.complainedAbout = this.value;
+		diagnose(this.tree?.engine ?? null, "error", `[incanto] UiSelect '${this.getPath()}' has value '${this.value}', which is not one of its options [${choices.join(", ")}]. The menu shows the first one instead, so the game and the screen now disagree about this setting.`);
+	}
 	_sync() {
 		const label = this._t(this.label);
 		if (label !== this.lastLabel && this.labelEl) {
@@ -4022,6 +3845,9 @@ var UiSelect = class extends HudWidgetBase {
 			this.select.value = this.value;
 		}
 	}
+	_pull() {
+		this.reportMismatch();
+	}
 };
 /** Endonyms: `ko` must read as the Korean word to someone who cannot read `Korean`. */
 const ENDONYMS = {
@@ -4067,21 +3893,19 @@ var UiLanguageSelect = class extends UiSelect {
 	label = "Language";
 	/** Last locale we PUSHED into `value`, to tell an engine change from a player one. */
 	lastLocale = "";
-	_sync() {
+	_pull() {
 		const locale = this.tree?.engine?.locale;
-		if (locale) {
-			const available = locale.available();
-			const options = available.join(",");
-			if (options !== this.options) this.options = options;
-			if (locale.locale !== this.lastLocale) {
-				this.lastLocale = locale.locale;
-				this.value = locale.locale;
-			} else if (this.value !== locale.locale && available.includes(this.value)) {
-				locale.locale = this.value;
-				this.lastLocale = this.value;
-			}
+		if (!locale) return;
+		const available = locale.available();
+		const options = available.join(",");
+		if (options !== this.options) this.options = options;
+		if (locale.locale !== this.lastLocale) {
+			this.lastLocale = locale.locale;
+			this.value = locale.locale;
+		} else if (this.value !== locale.locale && available.includes(this.value)) {
+			locale.locale = this.value;
+			this.lastLocale = this.value;
 		}
-		super._sync();
 	}
 	_optionLabel(value) {
 		return ENDONYMS[value] ?? value;
@@ -4112,18 +3936,19 @@ var UiSettingSelect = class extends UiSelect {
 	* `settings.quality.high` is worse than one reading `High`. English is the
 	* base language and the fallback, always.
 	*/
-	_sync() {
+	_pull() {
 		const engine = this._engine();
-		if (engine) {
-			const stored = this._read(engine);
-			if (stored !== this.lastPushed) {
-				this.lastPushed = stored;
-				this.value = stored;
-			} else if (this.value !== stored) {
-				this._write(engine, this.value);
-				this.lastPushed = this._read(engine);
-			}
+		if (!engine) return;
+		const stored = this._read(engine);
+		if (stored !== this.lastPushed) {
+			this.lastPushed = stored;
+			this.value = stored;
+		} else if (this.value !== stored) {
+			this._write(engine, this.value);
+			this.lastPushed = this._read(engine);
 		}
+	}
+	_sync() {
 		super._sync();
 	}
 };
@@ -4286,19 +4111,17 @@ var UiVolumeSlider = class extends UiSlider {
 		const english = VOLUME_LABELS[this.bus] ?? VOLUME_LABELS.master;
 		return this._tOr(`settings.volume.${this.bus}`, english);
 	}
-	_sync() {
+	_pull() {
 		const audio = this.tree?.engine?.audio;
-		if (audio) {
-			const stored = audio[this.bus];
-			if (stored !== this.lastPushed) {
-				this.lastPushed = stored;
-				this.value = stored;
-			} else if (this.value !== stored) {
-				audio[this.bus] = this.value;
-				this.lastPushed = audio[this.bus];
-			}
+		if (!audio) return;
+		const stored = audio[this.bus];
+		if (stored !== this.lastPushed) {
+			this.lastPushed = stored;
+			this.value = stored;
+		} else if (this.value !== stored) {
+			audio[this.bus] = this.value;
+			this.lastPushed = audio[this.bus];
 		}
-		super._sync();
 	}
 };
 /**
@@ -4321,18 +4144,16 @@ var UiMuteToggle = class extends UiToggle {
 	_labelText() {
 		return this.label ? this._t(this.label) : this._tOr("settings.mute", "Mute");
 	}
-	_sync() {
+	_pull() {
 		const audio = this.tree?.engine?.audio;
-		if (audio) {
-			if (audio.muted !== this.lastPushed) {
-				this.lastPushed = audio.muted;
-				this.value = audio.muted;
-			} else if (this.value !== audio.muted) {
-				audio.muted = this.value;
-				this.lastPushed = audio.muted;
-			}
+		if (!audio) return;
+		if (audio.muted !== this.lastPushed) {
+			this.lastPushed = audio.muted;
+			this.value = audio.muted;
+		} else if (this.value !== audio.muted) {
+			audio.muted = this.value;
+			this.lastPushed = audio.muted;
 		}
-		super._sync();
 	}
 };
 //#endregion
@@ -4366,4 +4187,4 @@ function registerCoreNodes() {
 	registerNode(UiMuteToggle);
 }
 //#endregion
-export { UiBanner as A, isAudioContextAvailable as B, qualityRendering as C, EffectLog as D, LogManager as E, T_PREFIX as F, SFX_PRESET_NAMES as G, spatialGain as H, suggestLocale as I, MusicManager as J, sfxDuration as K, translateOn as L, UiText as M, BASE_LOCALE as N, HudLayer as O, Localization as P, AudioBuses as Q, translationKey as R, qualityEnvironment as S, suggestQuality as T, spatialPan as U, ROLLOFF_MODELS as V, SFX_PRESETS as W, crossfadeGains as X, WebAudioMusicBackend as Y, fadeGain as Z, AudioPlayer as _, UiMuteToggle as a, Settings as b, UiRenderScaleSelect as c, UiToggle as d, UiVolumeSlider as f, UiDialogue as g, UiButton as h, UiLanguageSelect as i, UiBar as j, HudWidgetBase as k, UiSelect as l, Respawn as m, UiFrameCapSelect as n, UiPanel as o, Timer as p, synthSfx as q, UiImage as r, UiQualitySelect as s, registerCoreNodes as t, UiSlider as u, Engine as v, readDeviceHints as w, qualityCaps as x, engine_exports as y, SfxEngine as z };
+export { T_PREFIX as A, SFX_PRESET_NAMES as B, qualityRendering as C, EffectLog as D, LogManager as E, isAudioContextAvailable as F, crossfadeGains as G, synthSfx as H, ROLLOFF_MODELS as I, fadeGain as K, spatialGain as L, translateOn as M, translationKey as N, BASE_LOCALE as O, SfxEngine as P, spatialPan as R, qualityEnvironment as S, suggestQuality as T, MusicManager as U, sfxDuration as V, WebAudioMusicBackend as W, AudioPlayer as _, UiMuteToggle as a, Settings as b, UiRenderScaleSelect as c, UiToggle as d, UiVolumeSlider as f, UiDialogue as g, UiButton as h, UiLanguageSelect as i, suggestLocale as j, Localization as k, UiSelect as l, Respawn 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, Engine as v, readDeviceHints as w, qualityCaps as x, engine_exports as y, SFX_PRESETS as z };