incanto 0.32.0 → 0.34.0

package/dist/{register-Dzkd6-os.js → register-G3edsjJ2.js}

@@ -1,4 +1,4 @@
-import { f as Node, h as InputMap, x as Signal } from "./loader-BlaRQGaA.js";
+import { f as Node, h as InputMap, x as Signal } from "./loader-BwR0DxeM.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-DP-SR7eg.js";
 import { l as registerNode } from "./registry-CJdGpT2V.js";
@@ -28,19 +28,19 @@ var AudioBuses = class {
 		return this._master;
 	}
 	set master(v) {
-		this._master = this.assign(this._master, v);
+		this.assign("_master", v);
 	}
 	get sfx() {
 		return this._sfx;
 	}
 	set sfx(v) {
-		this._sfx = this.assign(this._sfx, v);
+		this.assign("_sfx", v);
 	}
 	get music() {
 		return this._music;
 	}
 	set music(v) {
-		this._music = this.assign(this._music, v);
+		this.assign("_music", v);
 	}
 	get muted() {
 		return this._muted;
@@ -57,11 +57,20 @@ var AudioBuses = class {
 		return this._master * busGain * clamp01$3(sourceVolume);
 	}
 	/** Clamp + finite-guard a new value; emit only on a real change. */
-	assign(current, next) {
-		if (!Number.isFinite(next)) return current;
+	/**
+	* Write THEN emit.
+	*
+	* This used to emit from inside the expression assigning the field, so every
+	* listener of `changed` read the OLD value — including the thing the signal
+	* exists for ("live re-gain of playing sounds"), which therefore re-gained to
+	* the volume you just left.
+	*/
+	assign(key, next) {
+		if (!Number.isFinite(next)) return;
 		const clamped = clamp01$3(next);
-		if (clamped !== current) this.changed.emit();
-		return clamped;
+		if (clamped === this[key]) return;
+		this[key] = clamped;
+		this.changed.emit();
 	}
 };
 function clamp01$3(v) {
@@ -1009,6 +1018,196 @@ var LogManager = class {
 	}
 };
 //#endregion
+//#region src/core/save.ts
+const memoryStores = /* @__PURE__ */ new Map();
+function createSaveStore(namespace) {
+	const prefix = `incanto:${namespace}:`;
+	const local = storageOrNull();
+	if (!local) {
+		let mem = memoryStores.get(namespace);
+		if (!mem) {
+			mem = /* @__PURE__ */ new Map();
+			memoryStores.set(namespace, mem);
+		}
+		const backing = mem;
+		return {
+			get: (key, fallback) => parse(backing.get(key), fallback),
+			set: (key, value) => void backing.set(key, JSON.stringify(value)),
+			remove: (key) => void backing.delete(key),
+			clear: () => backing.clear()
+		};
+	}
+	return {
+		get: (key, fallback) => parse(local.getItem(prefix + key) ?? void 0, fallback),
+		set: (key, value) => local.setItem(prefix + key, JSON.stringify(value)),
+		remove: (key) => local.removeItem(prefix + key),
+		clear: () => {
+			const doomed = [];
+			for (let i = 0; i < local.length; i++) {
+				const k = local.key(i);
+				if (k?.startsWith(prefix)) doomed.push(k);
+			}
+			for (const k of doomed) local.removeItem(k);
+		}
+	};
+}
+function parse(raw, fallback) {
+	if (raw === void 0 || raw === null) return fallback;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return fallback;
+	}
+}
+function storageOrNull() {
+	try {
+		if (typeof localStorage === "undefined") return null;
+		const probe = "__incanto_probe__";
+		localStorage.setItem(probe, "1");
+		localStorage.removeItem(probe);
+		return localStorage;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/core/settings.ts
+const DEFAULTS = {
+	master: 1,
+	sfx: 1,
+	music: 1,
+	muted: false,
+	quality: "high",
+	sensitivity: 1,
+	invertY: false,
+	reduceMotion: false
+};
+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]);
+	}
+	/**
+	* Push the saved volumes into the engine's buses, and keep writing them back
+	* whenever anything changes them.
+	*
+	* 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.
+	*/
+	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);
+		});
+	}
+};
+/**
+* What a quality tier MEANS, as an environment patch.
+*
+* Only the levers that actually cost: shadows, post, clouds, and the resolution
+* the renderer draws at. 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.
+*/
+function qualityEnvironment(tier) {
+	if (tier === "low") return {
+		shadows: { enabled: false },
+		bloom: { enabled: false },
+		post: { enabled: false },
+		clouds: { enabled: false },
+		rendering: {
+			antialias: false,
+			pixelRatio: 1
+		}
+	};
+	if (tier === "medium") return {
+		shadows: {
+			enabled: true,
+			static: true
+		},
+		bloom: { enabled: true },
+		post: { enabled: false },
+		rendering: {
+			antialias: true,
+			pixelRatio: 1
+		}
+	};
+	return {
+		shadows: { enabled: true },
+		bloom: { enabled: true },
+		post: { enabled: true },
+		rendering: {
+			antialias: true,
+			pixelRatio: "device"
+		}
+	};
+}
+//#endregion
 //#region src/core/engine.ts
 const MAX_DT_SECONDS = .25;
 function rafScheduler(cb) {
@@ -1047,9 +1246,27 @@ var Engine = class {
 	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();
+	/**
+	* 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();
 	/** Low-latency procedural-SFX player (WebAudio, headless-safe). AudioPlayer
 	*  presets play through it; games may call `engine.sfx.play(...)` directly. */
 	sfx = new SfxEngine();
@@ -1510,10 +1727,17 @@ var HudLayer = class extends Node {
 	static typeName = "HudLayer";
 	static props = {
 		zIndex: { default: 100 },
-		visible: { default: true }
+		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();
@@ -1554,6 +1778,66 @@ var HudLayer = class extends Node {
 			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. */
+	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) {
@@ -1568,6 +1852,22 @@ var HudLayer = class extends Node {
 		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;
+	}
+	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 {
 	static props = {
@@ -1585,10 +1885,46 @@ var HudWidgetBase = class extends Node {
 				"bottomRight"
 			]
 		},
-		visible: { default: true }
+		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() {
@@ -1597,17 +1933,79 @@ var HudWidgetBase = class extends Node {
 	}
 	onReady() {
 		if (!hasDom()) return;
-		const slot = this.layer()?._slot(this.anchor);
-		if (!slot) 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();
-		slot.appendChild(this._element);
+		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();
+				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) return;
+		if (!this._element) {
+			this._mountWidget();
+			if (!this._element) return;
+		}
 		this._element.style.display = this.visible ? "" : "none";
 		this._sync();
 	}
@@ -1793,13 +2191,19 @@ var UiButton = class extends HudWidgetBase {
 		size: { default: 16 },
 		color: { default: "#ffffff" },
 		background: { default: "rgba(255,255,255,0.14)" },
-		disabled: { default: false }
+		disabled: { default: false },
+		focusable: { default: true }
 	};
 	text = "OK";
 	size = 16;
 	color = "#ffffff";
 	background = "rgba(255,255,255,0.14)";
 	disabled = false;
+	focusable = true;
+	/** Enter / A on a focused button is a press. */
+	_activate(_dir) {
+		this.press();
+	}
 	lastText = "";
 	/** Programmatic press — same path as a click (tests, gamepad menus). */
 	press() {
@@ -2028,6 +2432,333 @@ var Timer = class extends Node {
 	}
 };
 //#endregion
+//#region src/core/nodes/ui-kit.ts
+function px(n) {
+	return `${n}px`;
+}
+/**
+* A box that holds other widgets — the thing a menu actually is.
+*
+* Widgets normally mount into their HudLayer's anchor slot, which is why a
+* "menu" used to be a flat pile of anchored items with no way to sit them in a
+* panel, space them, or lay them out in a grid. A `UiPanel` becomes the parent
+* for every widget under it, so structure in the TREE is structure on SCREEN.
+*
+* ```json
+* { "name": "Pause", "type": "UiPanel", "props": { "anchor": "center", "layout": "column", "gap": 12 },
+*   "children": [
+*     { "name": "Title", "type": "UiText", "props": { "text": "PAUSED", "size": 28 } },
+*     { "name": "Resume", "type": "UiButton", "props": { "label": "Resume" } }
+*   ] }
+* ```
+*/
+var UiPanel = class extends HudWidgetBase {
+	static typeName = "UiPanel";
+	static props = {
+		...HudWidgetBase.props,
+		layout: {
+			default: "column",
+			options: [
+				"column",
+				"row",
+				"grid"
+			]
+		},
+		/** Columns when `layout: "grid"` — an inventory is a grid of slots. */
+		columns: { default: 4 },
+		gap: { default: 8 },
+		padding: { default: 12 },
+		background: { default: "rgba(0,0,0,0.55)" },
+		radius: { default: 10 },
+		/** 0 = size to the contents. */
+		width: { default: 0 },
+		height: { default: 0 },
+		border: { default: "" }
+	};
+	layout = "column";
+	columns = 4;
+	gap = 8;
+	padding = 12;
+	background = "rgba(0,0,0,0.55)";
+	radius = 10;
+	width = 0;
+	height = 0;
+	border = "";
+	lastKey = "";
+	_build() {
+		const el = document.createElement("div");
+		el.style.cssText = this.css();
+		this.lastKey = this.css();
+		return el;
+	}
+	/**
+	* @internal Children mount HERE, not in the layer's anchor slot.
+	*
+	* Builds on demand: a child asking for its host must not depend on whose
+	* `onReady` the tree happened to run first.
+	*/
+	_container() {
+		if (!this._element) this._mountWidget();
+		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;";
+	}
+	_sync() {
+		const next = this.css();
+		if (next !== this.lastKey && this._element) {
+			this.lastKey = next;
+			this._element.style.cssText = next;
+		}
+	}
+};
+/** A picture: an item icon, a portrait, a logo. `src` takes a url or `$assetKey`. */
+var UiImage = class extends HudWidgetBase {
+	static typeName = "UiImage";
+	static props = {
+		...HudWidgetBase.props,
+		src: { default: "" },
+		width: { default: 48 },
+		height: { default: 48 },
+		/** How the picture fills its box — `contain` never crops. */
+		fit: {
+			default: "contain",
+			options: [
+				"contain",
+				"cover",
+				"fill"
+			]
+		},
+		/** Multiply the image by a colour: greyed-out items, team tints. */
+		tint: { default: "" },
+		opacity: { default: 1 }
+	};
+	src = "";
+	width = 48;
+	height = 48;
+	fit = "contain";
+	tint = "";
+	opacity = 1;
+	last = "\0";
+	_build() {
+		const el = document.createElement("div");
+		el.style.cssText = this.css();
+		this.last = this.key();
+		return el;
+	}
+	resolved() {
+		if (!this.src.startsWith("$")) return this.src;
+		return (this.tree?.engine?.scene?.assets)?.[this.src.slice(1)]?.url ?? "";
+	}
+	key() {
+		return `${this.resolved()}|${this.width}|${this.height}|${this.fit}|${this.tint}|${this.opacity}`;
+	}
+	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;` : "");
+	}
+	_sync() {
+		const next = this.key();
+		if (next !== this.last && this._element) {
+			this.last = next;
+			this._element.style.cssText = this.css();
+		}
+	}
+};
+/**
+* A value the player sets — volume, sensitivity, difficulty.
+*
+* Emits `changed(value)`. `incanto-audio.md` promised "a settings slider needs
+* no extra wiring" while no slider existed; this is that slider.
+*/
+var UiSlider = class extends HudWidgetBase {
+	static typeName = "UiSlider";
+	static props = {
+		...HudWidgetBase.props,
+		label: { default: "" },
+		value: { default: .5 },
+		min: { default: 0 },
+		max: { default: 1 },
+		step: { default: .01 },
+		width: { default: 180 },
+		color: { default: "#6ee7dc" },
+		focusable: { default: true }
+	};
+	static signals = [...HudWidgetBase.signals, "changed"];
+	label = "";
+	value = .5;
+	min = 0;
+	max = 1;
+	step = .01;
+	width = 180;
+	color = "#6ee7dc";
+	focusable = true;
+	/** Left/right nudge by one step — the only sane thing a d-pad can mean here. */
+	_activate(dir) {
+		if (dir === 0) return;
+		const next = Math.min(this.max, Math.max(this.min, this.value + dir * this.step));
+		if (next === this.value) return;
+		this.value = next;
+		this.last = next;
+		if (this.input) this.input.value = String(next);
+		this.emit("changed", next);
+	}
+	input = null;
+	text = null;
+	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;";
+		const text = document.createElement("span");
+		text.textContent = this.label;
+		const input = document.createElement("input");
+		input.type = "range";
+		input.min = String(this.min);
+		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.addEventListener("input", () => {
+			this.value = Number(input.value);
+			this.last = this.value;
+			this.emit("changed", this.value);
+		});
+		if (this.label) wrap.appendChild(text);
+		wrap.appendChild(input);
+		this.input = input;
+		this.text = text;
+		this.last = this.value;
+		return wrap;
+	}
+	_sync() {
+		if (this.input && this.value !== this.last) {
+			this.last = this.value;
+			this.input.value = String(this.value);
+		}
+		if (this.text && this.text.textContent !== this.label) this.text.textContent = this.label;
+	}
+};
+/** An on/off switch — mute, invert-Y, fullscreen. Emits `changed(boolean)`. */
+var UiToggle = class extends HudWidgetBase {
+	static typeName = "UiToggle";
+	static props = {
+		...HudWidgetBase.props,
+		label: { default: "" },
+		value: { default: false },
+		focusable: { default: true }
+	};
+	static signals = [...HudWidgetBase.signals, "changed"];
+	label = "";
+	value = false;
+	focusable = true;
+	/** Confirm flips it; left/right set it explicitly, which reads better on a pad. */
+	_activate(dir) {
+		const next = dir === 0 ? !this.value : dir > 0;
+		if (next === this.value) return;
+		this.value = next;
+		this.last = next;
+		if (this.input) this.input.checked = next;
+		this.emit("changed", next);
+	}
+	input = null;
+	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;";
+		const input = document.createElement("input");
+		input.type = "checkbox";
+		input.checked = this.value;
+		input.addEventListener("change", () => {
+			this.value = input.checked;
+			this.last = this.value;
+			this.emit("changed", this.value);
+		});
+		const text = document.createElement("span");
+		text.textContent = this.label;
+		wrap.append(input, text);
+		this.input = input;
+		this.last = this.value;
+		return wrap;
+	}
+	_sync() {
+		if (this.input && this.value !== this.last) {
+			this.last = this.value;
+			this.input.checked = this.value;
+		}
+	}
+};
+/** One of several — quality, resolution, language. Emits `changed(value)`. */
+var UiSelect = class extends HudWidgetBase {
+	static typeName = "UiSelect";
+	static props = {
+		...HudWidgetBase.props,
+		label: { default: "" },
+		/** Comma-separated choices: `"low,medium,high"`. */
+		options: { default: "" },
+		value: { default: "" },
+		focusable: { default: true }
+	};
+	static signals = [...HudWidgetBase.signals, "changed"];
+	label = "";
+	options = "";
+	value = "";
+	focusable = true;
+	/** 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);
+		if (choices.length === 0) return;
+		const next = choices[(Math.max(0, choices.indexOf(this.value)) + (dir === 0 ? 1 : dir) + choices.length) % choices.length];
+		if (!next || next === this.value) return;
+		this.value = next;
+		this.last = next;
+		if (this.select) this.select.value = next;
+		this.emit("changed", next);
+	}
+	select = null;
+	lastOptions = "\0";
+	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;";
+		const text = document.createElement("span");
+		text.textContent = this.label;
+		const select = document.createElement("select");
+		select.addEventListener("change", () => {
+			this.value = select.value;
+			this.last = this.value;
+			this.emit("changed", this.value);
+		});
+		if (this.label) wrap.appendChild(text);
+		wrap.appendChild(select);
+		this.select = select;
+		this.fillOptions();
+		return wrap;
+	}
+	fillOptions() {
+		const select = this.select;
+		if (!select || this.options === this.lastOptions) return;
+		this.lastOptions = this.options;
+		select.textContent = "";
+		for (const raw of this.options.split(",")) {
+			const value = raw.trim();
+			if (!value) continue;
+			const option = document.createElement("option");
+			option.value = value;
+			option.textContent = value;
+			select.appendChild(option);
+		}
+		if (this.value) select.value = this.value;
+		this.last = this.value;
+	}
+	_sync() {
+		this.fillOptions();
+		if (this.select && this.value !== this.last) {
+			this.last = this.value;
+			this.select.value = this.value;
+		}
+	}
+};
+//#endregion
 //#region src/core/register.ts
 /**
 * Register the core node types. Call once in your game entry before loading
@@ -2044,6 +2775,11 @@ function registerCoreNodes() {
 	registerNode(UiBanner);
 	registerNode(UiButton);
 	registerNode(UiDialogue);
+	registerNode(UiPanel);
+	registerNode(UiImage);
+	registerNode(UiSlider);
+	registerNode(UiToggle);
+	registerNode(UiSelect);
 }
 //#endregion
-export { fadeGain as C, crossfadeGains as S, SFX_PRESETS as _, HudLayer as a, MusicManager as b, UiText as c, LogManager as d, SfxEngine as f, spatialPan as g, spatialGain as h, UiDialogue as i, AudioPlayer as l, ROLLOFF_MODELS as m, Timer as n, UiBanner as o, isAudioContextAvailable as p, UiButton as r, UiBar as s, registerCoreNodes as t, Engine as u, SFX_PRESET_NAMES as v, AudioBuses as w, WebAudioMusicBackend as x, synthSfx as y };
+export { MusicManager as A, isAudioContextAvailable as C, SFX_PRESETS as D, spatialPan as E, crossfadeGains as M, fadeGain as N, SFX_PRESET_NAMES as O, AudioBuses as P, SfxEngine as S, spatialGain as T, qualityEnvironment as _, UiSlider as a, createSaveStore as b, UiButton as c, UiBanner as d, UiBar as f, Settings as g, Engine as h, UiSelect as i, WebAudioMusicBackend as j, synthSfx as k, UiDialogue as l, AudioPlayer as m, UiImage as n, UiToggle as o, UiText as p, UiPanel as r, Timer as s, registerCoreNodes as t, HudLayer as u, readDeviceHints as v, ROLLOFF_MODELS as w, LogManager as x, suggestQuality as y };