incanto 0.33.0 → 0.35.0

package/dist/{register-CscIzJEO.js → register-BFLg0-_i.js}

@@ -1,4 +1,4 @@
-import { f as Node, h as InputMap, x as Signal } from "./loader-Buk8Bu1h.js";
+import { C as Signal, _ as behaviorSchema, f as Node, h as diagnose, m as InputMap } from "./loader-Mig5fY4n.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";
@@ -924,6 +924,120 @@ var SfxEngine = class {
 	}
 };
 //#endregion
+//#region src/core/localization.ts
+/** The base locale. Every other locale falls back to it, one key at a time. */
+const BASE_LOCALE = "en";
+/**
+* The marker that makes a string prop translatable: `"@t:hud.score"`.
+*
+* A prefix rather than an object wrapper, matching the `"$assetKey"` reference
+* already in the engine — the prop is declared a string, so its value should
+* stay a string. It also stays authorable by hand:
+*
+* ```json
+* { "type": "UiText", "props": { "text": "@t:hud.score" } }
+* ```
+*/
+const T_PREFIX = "@t:";
+/** The key a `"@t:…"` value names, or null for an ordinary string. */
+function translationKey(value) {
+	return value.startsWith("@t:") ? value.slice(3) : null;
+}
+/** `Hello, {name}` + `{name: 'Ada'}` → `Hello, Ada`. Unknown slots stay put. */
+function interpolate(text, params) {
+	if (!params) return text;
+	return text.replace(/\{(\w+)\}/g, (whole, name) => name in params ? String(params[name]) : whole);
+}
+var Localization = class {
+	/** Fires with the new locale after it changes — for anything that caches. */
+	changed = new Signal();
+	tables = {};
+	current = "en";
+	constructor(tables, locale) {
+		if (tables) this.load(tables);
+		if (locale) this.locale = locale;
+	}
+	/**
+	* Merge a scene's `strings` table in.
+	*
+	* Merged rather than replaced: a game's shared UI strings live in the scene it
+	* boots from, and a level that adds three lines of its own should not wipe
+	* them. Per-key, so a level CAN override one string.
+	*/
+	load(tables) {
+		for (const [locale, entries] of Object.entries(tables)) {
+			this.tables[locale] ??= {};
+			const target = this.tables[locale];
+			for (const [key, text] of Object.entries(entries)) if (typeof text === "string") target[key] = text;
+		}
+	}
+	get locale() {
+		return this.current;
+	}
+	/**
+	* Switch language. Setting one nobody declared is not an error — it simply
+	* resolves everything through the base locale, which is the correct outcome
+	* for a player whose browser reports a language this game does not ship.
+	*/
+	set locale(next) {
+		if (next === this.current || next === "") return;
+		this.current = next;
+		this.changed.emit(next);
+	}
+	/** Every locale with at least one string — what a language picker offers. */
+	available() {
+		const out = new Set(["en"]);
+		for (const [locale, entries] of Object.entries(this.tables)) if (Object.keys(entries).length > 0) out.add(locale);
+		return [...out];
+	}
+	/**
+	* The string for `key`: current locale, else English, else the key itself.
+	*
+	* Returning the key rather than an empty string is deliberate — a screen
+	* reading `menu.credits` tells an author exactly what to add, where a blank
+	* one tells them nothing and looks like a rendering bug.
+	*/
+	t(key, params) {
+		const own = this.tables[this.current]?.[key];
+		if (own !== void 0) return interpolate(own, params);
+		const base = this.tables["en"]?.[key];
+		if (base !== void 0) return interpolate(base, params);
+		return key;
+	}
+	/**
+	* Resolve a prop value: `"@t:key"` translates, anything else passes through.
+	*
+	* This is what every text-bearing widget calls, every frame. A plain string is
+	* returned untouched, so a game that never localizes anything pays a
+	* `startsWith` per widget per frame and nothing else.
+	*/
+	resolve(value, params) {
+		const key = translationKey(value);
+		return key === null ? value : this.t(key, params);
+	}
+	/** Whether any locale declares this key — for the audit, not for the runtime. */
+	has(key) {
+		for (const entries of Object.values(this.tables)) if (entries[key] !== void 0) return true;
+		return false;
+	}
+};
+/**
+* The player's language, if the browser will say and the game ships it.
+*
+* A starting point only — the language setting is the real answer, exactly as
+* `suggestQuality` is a starting point for the quality tier.
+*/
+function suggestLocale(available, languages) {
+	const nav = globalThis.navigator;
+	const wanted = languages ?? nav?.languages ?? [];
+	for (const tag of wanted) {
+		const base = tag.split("-")[0] ?? "";
+		const hit = available.find((a) => a === tag || a === base);
+		if (hit) return hit;
+	}
+	return "en";
+}
+//#endregion
 //#region src/core/frame-stats.ts
 /**
 * Rolling window of REAL frame timestamps — the math behind `engine.stats()`
@@ -1071,6 +1185,214 @@ function storageOrNull() {
 	}
 }
 //#endregion
+//#region src/core/save-slots.ts
+/**
+* Save slots — "continue where you left off", which no game on this engine could
+* do.
+*
+* `createSaveStore` has been here a long time and `Scene.toJSON()` round-trips a
+* live tree, so two thirds of the work existed. The missing third was that
+* BEHAVIOR state had nowhere to go: `Behavior` declared `onEnterTree`, `onReady`,
+* `onExitTree`, `update` and `fixedUpdate` and nothing for "write yourself down",
+* so `Health.current`, `ScoreKeeper.score` and every quest flag were
+* unrecoverable. Both quest templates this repo ships were RPGs you could not
+* resume.
+*
+* ## What a save is, and what it deliberately is NOT
+*
+* A save is **which scene, plus every behavior's state, keyed by node uid**. It
+* is not a snapshot of the live tree.
+*
+* That is a design decision, not a shortcut. Restoring a live tree by walking
+* paths breaks on this engine specifically:
+*
+* - `Spawner.onReady` DETACHES its prefab template from the tree (see
+*   `SpawnSource.resolveTemplate`), so a captured tree and a freshly booted one
+*   legitimately disagree about which nodes exist, every time.
+*   Every scene with a spawner would report phantom removals.
+* - A spawned enemy carrying its own spawner has already lost ITS template, so
+*   re-adding that subtree runs `onReady` against a node that is not there and
+*   throws — and `onReady` is not quarantined, so it kills the whole load.
+* - Prop deltas cannot be applied with `applySchemaProps`, which resets every
+*   prop to its default before writing.
+*
+* Reloading the scene from source sidesteps all three: the structure comes from
+* the file (which is authoritative and already validated), and the save carries
+* only what the file cannot know. A fresh boot detaches the same templates the
+* captured one did, so there is nothing to reconcile.
+*
+* The cost, stated plainly so nobody discovers it: **spawned enemies and
+* mid-level positions are not restored.** You resume at the scene's start with
+* your stats, inventory, unlocks and quest flags intact. That is what a
+* checkpoint save is, and it is what both quest templates need. A game that
+* wants a position saves it — `serialize()` can return anything.
+*
+* Node uids are the join key because they are the one identifier the engine
+* already promises survives a rename or a reparent.
+*/
+/**
+* Every behavior in the tree that has something to say, by uid.
+*
+* A behavior with no `serialize` contributes nothing — the hook is optional in
+* exactly the way the other five are, so adding save support to a game is
+* additive and a game that never saves pays nothing.
+*
+* A node with no `uid` is skipped and reported, because state keyed by nothing
+* cannot be given back. The editor assigns a uid to every node it touches; a
+* hand-written scene may not have.
+*/
+function captureBehaviors(root) {
+	const state = {};
+	const unaddressable = [];
+	const walk = (node) => {
+		const behavior = node.behavior;
+		if (behavior && typeof behavior.serialize === "function") {
+			const value = behavior.serialize();
+			if (value !== void 0) if (node.uid) state[node.uid] = value;
+			else unaddressable.push(node.getPath());
+		}
+		for (const child of node.children) walk(child);
+	};
+	walk(root);
+	return {
+		state,
+		unaddressable
+	};
+}
+/**
+* Hand each behavior its state back.
+*
+* Call this AFTER the scene has loaded and `onReady` has run: `onReady` is where
+* a behavior sets its starting values, so restoring first would be overwritten
+* by the fresh start.
+*
+* Never throws on a mismatch. A save from an older build of the game will name
+* uids that no longer exist, and refusing to load it would mean a patch that
+* moves one node deletes everyone's progress. It reports instead.
+*/
+function restoreBehaviors(root, state) {
+	const report = {
+		missing: [],
+		skipped: [],
+		restored: 0
+	};
+	for (const [uid, value] of Object.entries(state)) {
+		const node = root.getNodeByUid(uid);
+		if (!node) {
+			report.missing.push(uid);
+			continue;
+		}
+		const behavior = node.behavior;
+		if (!behavior || typeof behavior.deserialize !== "function") {
+			report.skipped.push(uid);
+			continue;
+		}
+		try {
+			behavior.deserialize(value);
+			report.restored += 1;
+		} catch {
+			report.skipped.push(uid);
+		}
+	}
+	return report;
+}
+/** Slot ids, so a "3 save slots" menu is a list and not a naming convention. */
+const INDEX_KEY = "slots";
+/**
+* The slot layer: a named list of saves over the existing store.
+*
+* Slot ids are yours (`'auto'`, `'1'`, `'2'`, `'3'`) — the engine does not
+* decide how many you have or whether one of them autosaves.
+*/
+var SaveSlots = class {
+	store;
+	constructor(namespace = "saves", store) {
+		this.store = store ?? createSaveStore(namespace);
+	}
+	/** Slot ids that have a save, newest first. */
+	list() {
+		const rows = this.store.get(INDEX_KEY, []).map((id) => ({
+			id,
+			slot: this.read(id)
+		})).filter((row) => row.slot !== null);
+		rows.sort((a, b) => b.slot.savedAt - a.slot.savedAt);
+		return rows.map((row) => row.id);
+	}
+	/** Every slot with its contents — what a load menu actually renders. */
+	all() {
+		return this.list().map((id) => ({
+			id,
+			...this.read(id)
+		}));
+	}
+	read(id) {
+		const raw = this.store.get(key(id), null);
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+		const slot = raw;
+		if (typeof slot.scene !== "string" || typeof slot.state !== "object" || slot.state === null) return null;
+		return {
+			scene: slot.scene,
+			state: slot.state,
+			label: typeof slot.label === "string" ? slot.label : "",
+			savedAt: typeof slot.savedAt === "number" ? slot.savedAt : 0,
+			playtime: typeof slot.playtime === "number" ? slot.playtime : 0,
+			data: slot.data ?? {}
+		};
+	}
+	/**
+	* Write a slot.
+	*
+	* `savedAt` is a parameter rather than `Date.now()` so a test can assert an
+	* ordering without sleeping, and so a game that wants server time can use it.
+	*/
+	write(id, slot) {
+		const full = {
+			scene: slot.scene,
+			state: slot.state,
+			label: slot.label ?? "",
+			savedAt: slot.savedAt ?? 0,
+			playtime: slot.playtime ?? 0,
+			data: slot.data ?? {}
+		};
+		this.store.set(key(id), full);
+		const ids = this.store.get(INDEX_KEY, []);
+		if (!ids.includes(id)) this.store.set(INDEX_KEY, [...ids, id]);
+	}
+	remove(id) {
+		this.store.remove(key(id));
+		this.store.set(INDEX_KEY, this.store.get(INDEX_KEY, []).filter((other) => other !== id));
+	}
+	/** Wipe every slot — a "delete all data" button, and test isolation. */
+	clear() {
+		for (const id of this.store.get(INDEX_KEY, [])) this.store.remove(key(id));
+		this.store.set(INDEX_KEY, []);
+	}
+};
+function key(id) {
+	return `slot:${id}`;
+}
+/**
+* Behaviors in this tree that hold state and cannot save it — the audit's
+* question, answerable before a player loses an hour.
+*
+* A behavior with props but no `serialize` is not necessarily wrong (an
+* `Oscillate` derives everything from time), so this reports rather than warns,
+* and the caller decides.
+*/
+function behaviorsWithoutSave(root) {
+	const out = [];
+	const walk = (node) => {
+		const behavior = node.behavior;
+		const name = node.script?.name;
+		if (behavior && typeof name === "string" && typeof behavior.serialize !== "function") {
+			if (Object.keys(behaviorSchema(name)).length > 0) out.push(`${node.getPath()} (${name})`);
+		}
+		for (const child of node.children) walk(child);
+	};
+	walk(root);
+	return out;
+}
+//#endregion
 //#region src/core/settings.ts
 const DEFAULTS = {
 	master: 1,
@@ -1080,7 +1402,8 @@ const DEFAULTS = {
 	quality: "high",
 	sensitivity: 1,
 	invertY: false,
-	reduceMotion: false
+	reduceMotion: false,
+	language: "en"
 };
 const TIERS = [
 	"low",
@@ -1146,6 +1469,19 @@ var Settings = class {
 		for (const key of Object.keys(DEFAULTS)) this.set(key, DEFAULTS[key]);
 	}
 	/**
+	* Apply the saved language, and keep it in step both ways.
+	*
+	* The same shape as `bindAudio`: a game that writes
+	* `engine.locale.locale = 'ko'` from an options menu has already persisted it
+	* without knowing this class exists. Returns the unsubscribe.
+	*/
+	bindLocale(locale) {
+		locale.locale = this.values.language;
+		return locale.changed.connect((next) => {
+			this.set("language", next);
+		});
+	}
+	/**
 	* Push the saved volumes into the engine's buses, and keep writing them back
 	* whenever anything changes them.
 	*
@@ -1267,6 +1603,11 @@ var Engine = class {
 	* `bindAudio` makes the volumes write themselves.
 	*/
 	settings = new Settings();
+	/**
+	* Translations, and the locale in force. English is the base and the default;
+	* anything a locale does not declare falls back to it silently.
+	*/
+	locale = new Localization();
 	/** Low-latency procedural-SFX player (WebAudio, headless-safe). AudioPlayer
 	*  presets play through it; games may call `engine.sfx.play(...)` directly. */
 	sfx = new SfxEngine();
@@ -1340,6 +1681,7 @@ var Engine = class {
 		this._time = 0;
 		this._unscaledTime = 0;
 		if (scene.input) this.input.declare(scene.input);
+		if (scene.strings) this.locale.load(scene.strings);
 		this.sceneChanged.emit(scene);
 	}
 	start() {
@@ -1377,6 +1719,41 @@ var Engine = class {
 	* both — so a tool can list them and put them back. Walks on demand; there is
 	* no per-frame bookkeeping for this.
 	*/
+	/**
+	* The string for `key` in the current locale — English if this locale does not
+	* declare it, the key itself if nothing does.
+	*
+	* The short form of `engine.locale.t`, because a behavior reaching for a
+	* translated string is the common case:
+	* `banner.show(this.engine.t('wave.start', { n: wave }))`.
+	*/
+	t(key, params) {
+		return this.locale.t(key, params);
+	}
+	/**
+	* Every behavior's state, ready to put in a save slot.
+	*
+	* Pairs with `restoreState` after the scene has RELOADED — see
+	* core/save-slots.ts for why a save carries state rather than a tree
+	* snapshot.
+	*/
+	captureState() {
+		const root = this.scene?.root;
+		if (!root) return {};
+		const { state, unaddressable } = captureBehaviors(root);
+		for (const path of unaddressable) diagnose(this, "warn", `save: ${path} has state to save and no uid to key it under.`);
+		return state;
+	}
+	/** Give it back, after the scene is loaded and onReady has run. */
+	restoreState(state) {
+		const root = this.scene?.root;
+		if (!root) return {
+			missing: Object.keys(state),
+			skipped: [],
+			restored: 0
+		};
+		return restoreBehaviors(root, state);
+	}
 	erroredNodes() {
 		const out = [];
 		const walk = (node) => {
@@ -1727,10 +2104,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();
@@ -1771,6 +2155,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) {
@@ -1785,6 +2229,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 = {
@@ -1802,10 +2262,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() {
@@ -1830,8 +2326,45 @@ var HudWidgetBase = class extends Node {
 		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();
+				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) {
@@ -1854,6 +2387,18 @@ var HudWidgetBase = class extends Node {
 		this._sync();
 	}
 	_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 text line (score, timer, hints). Set `.text` from behaviors. */
 var UiText = class extends HudWidgetBase {
@@ -1876,9 +2421,10 @@ var UiText = class extends HudWidgetBase {
 		return el;
 	}
 	_sync() {
-		if (this.text !== this.last && this._element) {
-			this.last = this.text;
-			this._element.textContent = this.text;
+		const shown = this._t(this.text);
+		if (shown !== this.last && this._element) {
+			this.last = shown;
+			this._element.textContent = shown;
 		}
 	}
 };
@@ -1907,6 +2453,8 @@ var UiBar = class extends HudWidgetBase {
 	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() {
@@ -1917,8 +2465,8 @@ var UiBar = class extends HudWidgetBase {
 		wrap.style.cssText = "display:flex;align-items:center;gap:6px;";
 		if (this.label) {
 			const tag = document.createElement("span");
-			tag.textContent = this.label;
 			tag.style.cssText = "color:#fff;font-size:12px;text-shadow:0 1px 3px rgba(0,0,0,.7);";
+			this.tag = tag;
 			wrap.appendChild(tag);
 		}
 		const track = document.createElement("div");
@@ -1930,6 +2478,11 @@ var UiBar = class extends HudWidgetBase {
 		return wrap;
 	}
 	_sync() {
+		const label = this._t(this.label);
+		if (label !== this.lastLabel && this.tag) {
+			this.lastLabel = label;
+			this.tag.textContent = label;
+		}
 		const r = this.ratio;
 		if (r === this.lastRatio || !this.fill) return;
 		this.lastRatio = r;
@@ -2007,6 +2560,7 @@ var UiBanner = class extends HudWidgetBase {
 		}
 		if (!this.current && this.queue.length > 0) {
 			this.current = this.queue.shift();
+			this.current.text = this._t(this.current.text);
 			this.remaining = this.current.seconds;
 			if (this._element) {
 				this._element.textContent = this.current.text;
@@ -2035,13 +2589,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() {
@@ -2069,9 +2629,10 @@ var UiButton = class extends HudWidgetBase {
 	}
 	_sync() {
 		if (!this._element) return;
-		if (this.text !== this.lastText) {
-			this.lastText = this.text;
-			this._element.textContent = this.text;
+		const shown = this._t(this.text);
+		if (shown !== this.lastText) {
+			this.lastText = shown;
+			this._element.textContent = shown;
 		}
 		this._element.disabled = this.disabled;
 		this._element.style.opacity = this.disabled ? "0.45" : "1";
@@ -2196,6 +2757,9 @@ var UiDialogue = class extends HudWidgetBase {
 		super.update(dt);
 		if (!this.current && this.queue.length > 0) {
 			this.current = this.queue.shift();
+			this.current.text = this._t(this.current.text);
+			this.current.speaker = this._t(this.current.speaker);
+			if (this.current.choices) this.current.choices = this.current.choices.map((c) => this._t(c));
 			this.revealed = this.charsPerSecond <= 0 ? this.current.text.length : 0;
 			this.emit("lineShown", this.current.text);
 			if (this._element) {
@@ -2419,9 +2983,10 @@ var UiSlider = class extends HudWidgetBase {
 		max: { default: 1 },
 		step: { default: .01 },
 		width: { default: 180 },
-		color: { default: "#6ee7dc" }
+		color: { default: "#6ee7dc" },
+		focusable: { default: true }
 	};
-	static signals = ["changed"];
+	static signals = [...HudWidgetBase.signals, "changed"];
 	label = "";
 	value = .5;
 	min = 0;
@@ -2429,6 +2994,17 @@ var UiSlider = class extends HudWidgetBase {
 	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;
@@ -2470,11 +3046,22 @@ var UiToggle = class extends HudWidgetBase {
 	static props = {
 		...HudWidgetBase.props,
 		label: { default: "" },
-		value: { default: false }
+		value: { default: false },
+		focusable: { default: true }
 	};
-	static signals = ["changed"];
+	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() {
@@ -2510,20 +3097,35 @@ var UiSelect = class extends HudWidgetBase {
 		label: { default: "" },
 		/** Comma-separated choices: `"low,medium,high"`. */
 		options: { default: "" },
-		value: { default: "" }
+		value: { default: "" },
+		focusable: { default: true }
 	};
-	static signals = ["changed"];
+	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;
+	labelEl = null;
+	lastLabel = "x";
 	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;
+		this.labelEl = text;
 		const select = document.createElement("select");
 		select.addEventListener("change", () => {
 			this.value = select.value;
@@ -2536,6 +3138,10 @@ var UiSelect = class extends HudWidgetBase {
 		this.fillOptions();
 		return wrap;
 	}
+	/** Override point: what an option READS as, when it differs from its value. */
+	_optionLabel(value) {
+		return value;
+	}
 	fillOptions() {
 		const select = this.select;
 		if (!select || this.options === this.lastOptions) return;
@@ -2546,13 +3152,18 @@ var UiSelect = class extends HudWidgetBase {
 			if (!value) continue;
 			const option = document.createElement("option");
 			option.value = value;
-			option.textContent = value;
+			option.textContent = this._optionLabel(value);
 			select.appendChild(option);
 		}
 		if (this.value) select.value = this.value;
 		this.last = this.value;
 	}
 	_sync() {
+		const label = this._t(this.label);
+		if (label !== this.lastLabel && this.labelEl) {
+			this.lastLabel = label;
+			this.labelEl.textContent = label;
+		}
 		this.fillOptions();
 		if (this.select && this.value !== this.last) {
 			this.last = this.value;
@@ -2560,6 +3171,70 @@ var UiSelect = class extends HudWidgetBase {
 		}
 	}
 };
+/** Endonyms: `ko` must read as the Korean word to someone who cannot read `Korean`. */
+const ENDONYMS = {
+	en: "English",
+	ko: "한국어",
+	ja: "日本語",
+	"zh-CN": "简体中文",
+	"zh-TW": "繁體中文",
+	es: "Español",
+	fr: "Français",
+	de: "Deutsch",
+	pt: "Português",
+	ru: "Русский",
+	it: "Italiano",
+	th: "ไทย",
+	vi: "Tiếng Việt",
+	id: "Bahasa Indonesia"
+};
+/**
+* The language picker, done — because every game needs the same one.
+*
+* A plain `UiSelect` bound to the locale would take a behavior, a signal
+* connection, and the knowledge that `Settings` persists it: three things an
+* agent has to get right to ship a feature the engine already has. This is one
+* node.
+*
+* ```json
+* { "name": "Language", "type": "UiLanguageSelect",
+*   "props": { "label": "@t:settings.language" } }
+* ```
+*
+* Options are the locales the SCENE declares, so a game shipping only English
+* shows only English and the widget quietly costs nothing. Each is labeled with
+* its own endonym, because a player who cannot read the language currently on
+* screen still has to be able to find theirs.
+*/
+var UiLanguageSelect = class extends UiSelect {
+	static typeName = "UiLanguageSelect";
+	static props = {
+		...UiSelect.props,
+		label: { default: "Language" }
+	};
+	label = "Language";
+	/** Last locale we PUSHED into `value`, to tell an engine change from a player one. */
+	lastLocale = "";
+	_sync() {
+		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;
+			}
+		}
+		super._sync();
+	}
+	_optionLabel(value) {
+		return ENDONYMS[value] ?? value;
+	}
+};
 //#endregion
 //#region src/core/register.ts
 /**
@@ -2582,6 +3257,7 @@ function registerCoreNodes() {
 	registerNode(UiSlider);
 	registerNode(UiToggle);
 	registerNode(UiSelect);
+	registerNode(UiLanguageSelect);
 }
 //#endregion
-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 };
+export { translationKey as A, WebAudioMusicBackend as B, restoreBehaviors as C, Localization as D, BASE_LOCALE as E, spatialPan as F, fadeGain as H, SFX_PRESETS as I, SFX_PRESET_NAMES as L, isAudioContextAvailable as M, ROLLOFF_MODELS as N, T_PREFIX as O, spatialGain as P, synthSfx as R, captureBehaviors as S, LogManager as T, AudioBuses as U, crossfadeGains as V, qualityEnvironment as _, UiSlider as a, SaveSlots as b, UiButton as c, UiBanner as d, UiBar as f, Settings as g, Engine as h, UiSelect as i, SfxEngine as j, suggestLocale 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, createSaveStore as w, behaviorsWithoutSave as x, suggestQuality as y, MusicManager as z };