incanto 0.70.0 → 0.72.0

package/dist/{environment-presets-D6Q5BxeE.js → environment-presets-BeHoaGhy.js}

@@ -1,11 +1,11 @@
-import { q as diagnose } from "./save-slots-BXVg148r.js";
-import { M as translateOn, t as registerCoreNodes } from "./register-6DYnKZcy.js";
+import { Y as diagnose } from "./save-slots-CEuJPUle.js";
+import { M as translateOn, t as registerCoreNodes } from "./register-5IYfooAN.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-CDOMybym.js";
 import { c as getNodeSchema, h as didYouMean, p as registerNode } from "./touch-BnCyPA0G.js";
 import { t as createNoise2D } from "./noise-D3nPpmFg.js";
 import { i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, r as validateAnimations, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-CqR2o3SA.js";
-import { B as Area3D, E as effectRng, G as Node3D, H as PhysicsBody3D, I as Water3D, R as WaterCutout3D, U as RigidBody3D, V as CharacterBody3D, W as StaticBody3D, Y as colliderFootDrop, Z as worldPosition, w as tolerateUnknownAction, z as rejectScale } from "./gameplay-BfHkuzVb.js";
+import { B as rejectScale, D as effectRng, G as StaticBody3D, H as CharacterBody3D, K as Node3D, L as Water3D, Q as worldPosition, T as tolerateUnknownAction, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, X as colliderFootDrop, z as WaterCutout3D } from "./gameplay-BlQe-M07.js";
 import { t as checkSheetGrid } from "./sheet-grid-Cea343VO.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-BYgD5Edk.js";
 import { AdditiveBlending, AnimationClip, AnimationMixer, Box3, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, CapsuleGeometry, ClampToEdgeWrapping, Color, ConeGeometry, CylinderGeometry, DataTexture, DirectionalLight, DoubleSide, DynamicDrawUsage, Euler, Group, IcosahedronGeometry, ImageBitmapLoader, InstancedBufferAttribute, InstancedMesh, LinearFilter, LinearMipmapLinearFilter, LoopOnce, LoopRepeat, Matrix4, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshPhysicalMaterial, MeshStandardMaterial, NearestFilter, NoBlending, NoColorSpace, NormalBlending, PerspectiveCamera, PlaneGeometry, PointLight, Points, PointsMaterial, Quaternion, QuaternionKeyframeTrack, RGBADepthPacking, RGBAFormat, RepeatWrapping, SRGBColorSpace, ShaderChunk, ShaderMaterial, SphereGeometry, Texture, TextureLoader, UniformsLib, UniformsUtils, Vector3, Vector4, VectorKeyframeTrack } from "three";

package/dist/{frame-report-Dlq13Gyj.js → frame-report-D-_7YF2G.js}

@@ -177,7 +177,7 @@ const pct = (v) => `${(v * 100).toFixed(1)}%`;
 /** The report a person or an agent reads. Verdict first, numbers after. */
 function frameText(stats) {
 	const lines = [];
-	if (stats.hidden) lines.push("THE PAGE IS HIDDEN — a browser stops animating a window covered by another, so these pixels are whatever it last drew. Bring it to the front and capture again.");
+	if (stats.hidden) lines.push("the page is hidden, so the game is PAUSED — these pixels were rendered for this capture (current), but nothing is moving. A `--do` drive needs the window in front.");
 	if (stats.black) lines.push("BLACK SCREEN — nothing was drawn (no light, no camera, or nothing in view)");
 	else if (stats.uniform) lines.push("one flat colour — the camera may be inside geometry, or only the sky is drawn");
 	else if (!stats.subject) lines.push("nothing but background — the camera is pointed away from everything in the scene");

package/dist/{gameplay-BfHkuzVb.js → gameplay-BlQe-M07.js}

@@ -1,5 +1,5 @@
 import { t as jsonClone } from "./json-CfTjpvW8.js";
-import { K as Node, M as effectiveOrder, Q as Behavior, R as HudLayer, W as requireNumber, it as registerBehavior, n as SaveSlots, p as loadScene, q as diagnose, s as duplicateNode, u as rebuildOptions } from "./save-slots-BXVg148r.js";
+import { B as HudLayer, J as Node, K as requireNumber, P as effectiveOrder, Y as diagnose, d as rebuildOptions, et as Behavior, f as rememberAuthoredPath, h as loadScene, n as SaveSlots, ot as registerBehavior, s as duplicateNode } from "./save-slots-CEuJPUle.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-CDOMybym.js";
 import { h as didYouMean } from "./touch-BnCyPA0G.js";
@@ -6984,6 +6984,103 @@ function findCollector(node, group) {
 	return null;
 }
 //#endregion
+//#region src/gameplay/prefab-shelf.ts
+/**
+* A shelf of templates the GAME clones itself — towers, bolts, damage numbers.
+*
+* `Spawner` detaches its one prefab at enter, so a spawned enemy's whole
+* subtree is live and nobody has to think about it. A game that clones on its
+* own terms — a tower the player places, a bolt that tower fires — has no
+* spawner, so its templates sat in the tree as LIVE nodes: their behaviours
+* ticked, their turrets shot, and `visible: false` hid a node without switching
+* it off. The documented answer was to author every template `"enabled": false`
+* and wake the clone with `clone.behavior?.enable()`.
+*
+* That wakes ONE node, and the same docs teach that a node carries one
+* behaviour — so a prefab's parts live on children, and every one of those
+* stays asleep, silently and for good, because `enabled` is a pause switch that
+* never complains. Measured on a shipped tower defense: the bolt's
+* `Projectile` was woken and its sibling `Lifetime` was not, so every bolt that
+* MISSED flew forever — five still in the tree at 69 seconds, in a game that
+* passed its harness, its audit and every rung of the ladder.
+*
+* ```json
+* { "name": "Prefabs", "type": "Node2D", "script": { "name": "PrefabShelf" },
+*   "children": [ { "name": "Tower", "type": "Node2D", "children": [] } ] }
+* ```
+* ```ts
+* const shelf = this.node.getNode('/Game/Prefabs').behavior as PrefabShelf;
+* const tower = shelf.make('Tower');       // detached, like `duplicateNode`
+* tower.position = at;                     // set it up BEFORE it readies
+* this.node.getNode('/Game/Towers').addChild(tower);
+* ```
+*
+* The children never ENTER the tree, so nothing has to be asleep, nothing has
+* to be hidden, and `make()` hands back a clone that is awake all the way down.
+*/
+var PrefabShelf = class extends Behavior {
+	static props = { 
+	/**
+	* Which children to take, comma-separated. Empty (the default) takes them
+	* ALL, which is what a shelf is; name them when the node doubles as
+	* something else and only some of its children are templates.
+	*/
+prefabs: { default: "" } };
+	static signals = [];
+	prefabs = "";
+	/** Templates, in the order they were authored. */
+	held = /* @__PURE__ */ new Map();
+	onEnterTree() {
+		this.claim();
+	}
+	/** A shelf attached at runtime never saw `onEnterTree`; idempotent. */
+	onReady() {
+		this.claim();
+	}
+	claim() {
+		const wanted = this.prefabs.split(",").map((name) => name.trim()).filter((name) => name !== "");
+		const from = wanted.length > 0 ? wanted : [...this.node.children].map((child) => child.name);
+		for (const name of from) {
+			if (this.held.has(name)) continue;
+			const template = this.node.children.find((child) => child.name === name);
+			if (!template) throw new IncantoError("NODE_NOT_FOUND", `PrefabShelf on '${this.node.getPath()}': "prefabs" names '${name}', which is not a child of this node. It holds: ${this.childNames() || "(nothing)"}.`, {
+				prop: "prefabs",
+				path: this.node.getPath()
+			});
+			rememberAuthoredPath(template);
+			this.node.removeChild(template);
+			this.held.set(name, template);
+		}
+	}
+	/** What this shelf holds, in authored order. */
+	names() {
+		return [...this.held.keys()];
+	}
+	/**
+	* A live clone of one template, DETACHED — `addChild` it yourself.
+	*
+	* Detached for the same reason `duplicateNode` is, and it is not a
+	* formality: `onReady` fires on attach, and a behaviour that reads its node
+	* there (`FloatAway` banks its starting position) would bank the wrong one.
+	* Set the clone up, then attach it.
+	*
+	* The clone is VISIBLE even if the template was authored hidden (a scene
+	* migrating off the old `visible: false` shelf keeps working), and every
+	* behaviour in it is however it was authored: awake unless the template
+	* itself asks to sleep, which is now only ever a state machine's own doing.
+	*/
+	make(name) {
+		const template = this.held.get(name);
+		if (!template) throw new IncantoError("NODE_NOT_FOUND", `PrefabShelf on '${this.node.getPath()}': no template named '${name}'. This shelf holds: ${this.childNames() || "(nothing)"}.`, { path: this.node.getPath() });
+		const clone = duplicateNode(template, rebuildOptions(this.node));
+		if (typeof clone.visible === "boolean") clone.visible = true;
+		return clone;
+	}
+	childNames() {
+		return this.names().join(", ");
+	}
+};
+//#endregion
 //#region src/gameplay/projectile.ts
 /**
 * Constant-velocity motion in a straight line — bullets, arrows, thrown rocks.
@@ -7282,7 +7379,7 @@ var SavePoint = class extends Behavior {
 			return;
 		}
 		const report = this.engine.restoreState(slot.state);
-		const here = this.engine?.scene?.name;
+		const here = this.scene || this.engine?.scene?.source.name;
 		if (here && slot.scene && slot.scene !== here) diagnose(this.engine, "error", `[incanto] SavePoint '${this.slot}': this slot was saved in scene '${slot.scene}' and you are in '${here}'. Load that scene first — a save is restored INTO the scene it came from (incanto-save-slots.md).`);
 		else if (report.expected > 0 && report.restored === 0) diagnose(this.engine, "error", `[incanto] SavePoint '${this.slot}': restored 0 of ${report.expected} saveable behaviour(s)` + (report.missing.length > 0 ? ` — ${report.missing.length} uid(s) in the save are not in this scene, starting with '${report.missing[0]}'. That save is from an older build, or from another scene.` : ". Nothing in the save matched a node here."));
 		this.emit("restored", report.restored);
@@ -7437,6 +7534,7 @@ var SpawnSource = class {
 			});
 		}
 		if (claim) node.tree?._templates.set(claim, template);
+		rememberAuthoredPath(template);
 		if (template.parent) template.parent.removeChild(template);
 		this.detached.set(prefab, template);
 		return template;
@@ -7669,8 +7767,9 @@ var Wander = class extends Behavior {
 * every `interval` seconds, then waits until they're ALL cleared (freed) before
 * starting the next wave.
 *
-* Signals: `waveStarted(i)` when a wave begins spawning, `waveCleared(i)` when
-* its last instance frees, `allCleared` after the final wave clears.
+* Signals: `spawned(node)` per clone, `waveStarted(i)` when a wave begins
+* spawning, `waveCleared(i)` when its last instance frees, `allCleared` after
+* the final wave clears.
 */
 var WaveSpawner = class extends Behavior {
 	static props = {
@@ -7683,6 +7782,7 @@ var WaveSpawner = class extends Behavior {
 		autoStart: { default: true }
 	};
 	static signals = [
+		"spawned",
 		"waveStarted",
 		"waveCleared",
 		"allCleared"
@@ -7768,6 +7868,7 @@ var WaveSpawner = class extends Behavior {
 				const clone = this.source.spawn(this.source.resolveTemplate(wave.prefab));
 				this.live.add(clone);
 				this.spawnedThisWave += 1;
+				this.emit("spawned", clone);
 				this.timer += wave.interval;
 			}
 			if (this.spawnedThisWave >= wave.count) this.phase = "clearing";
@@ -8024,7 +8125,8 @@ const GAMEPLAY_BEHAVIORS = {
 	WaveSpawner,
 	Projectile,
 	Buoyancy,
-	FloatAway
+	FloatAway,
+	PrefabShelf
 };
 /**
 * Register all built-in gameplay behaviors. Idempotent and hot-reload tolerant
@@ -8036,4 +8138,4 @@ function registerGameplayBehaviors(opts) {
 	for (const [name, ctor] of Object.entries(GAMEPLAY_BEHAVIORS)) registerBehavior(name, ctor, { replace });
 }
 //#endregion
-export { phaseOf as A, Area3D as B, restartScene as C, FloatAway as D, effectRng as E, Chase as F, Node3D as G, PhysicsBody3D as H, Water3D as I, WATER_MAX_RIPPLES as J, validateCollider3D as K, WATER_CUTOUT_MAX as L, Health as M, Currency as N, FaceTarget as O, Collector as P, WaterCutout3D as R, goToScene as S, FollowCamera as T, RigidBody3D as U, CharacterBody3D as V, StaticBody3D as W, localFromWorld as X, colliderFootDrop as Y, worldPosition as Z, Cooldown as _, Wander as a, Interactable as b, SavePoint as c, Patrol as d, PathFollow as f, CameraShake as g, Lifetime as h, WaveSpawner as i, DamageOnContact as j, DayNight as k, Projectile as l, MoveTo as m, registerGameplayBehaviors as n, Spawner as o, Oscillate as p, createCausticsQuad as q, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Pickup as u, hitStop as v, tolerateUnknownAction as w, GameFlow as x, screenFlash as y, rejectScale as z };
+export { DayNight as A, rejectScale as B, goToScene as C, effectRng as D, FollowCamera as E, Collector as F, StaticBody3D as G, CharacterBody3D as H, Chase as I, createCausticsQuad as J, Node3D as K, Water3D as L, DamageOnContact as M, Health as N, FloatAway as O, Currency as P, worldPosition as Q, WATER_CUTOUT_MAX as R, GameFlow as S, tolerateUnknownAction as T, PhysicsBody3D as U, Area3D as V, RigidBody3D as W, colliderFootDrop as X, WATER_MAX_RIPPLES as Y, localFromWorld as Z, CameraShake as _, Wander as a, screenFlash as b, SavePoint as c, Pickup as d, Patrol as f, Lifetime as g, MoveTo as h, WaveSpawner as i, phaseOf as j, FaceTarget as k, Projectile as l, Oscillate as m, registerGameplayBehaviors as n, Spawner as o, PathFollow as p, validateCollider3D as q, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, PrefabShelf as u, Cooldown as v, restartScene as w, Interactable as x, hitStop as y, WaterCutout3D as z };

package/dist/gameplay.d.ts

@@ -1,4 +1,4 @@
-import { b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, t as Behavior } from "./behavior-DZExDn9o.js";
+import { b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, t as Behavior } from "./behavior-Bf9P9oB2.js";
 import { c as JsonValue, s as JsonObject } from "./rng-Bb-IutXB.js";
 
 //#region src/gameplay/chase.d.ts
@@ -826,8 +826,9 @@ declare class Wander extends Behavior {
 * every `interval` seconds, then waits until they're ALL cleared (freed) before
 * starting the next wave.
 *
-* Signals: `waveStarted(i)` when a wave begins spawning, `waveCleared(i)` when
-* its last instance frees, `allCleared` after the final wave clears.
+* Signals: `spawned(node)` per clone, `waveStarted(i)` when a wave begins
+* spawning, `waveCleared(i)` when its last instance frees, `allCleared` after
+* the final wave clears.
 */
 declare class WaveSpawner extends Behavior {
   static readonly props: PropSchema;
@@ -1265,6 +1266,69 @@ declare class PathFollow extends Behavior {
   override update(dt: number): void;
 }
 //#endregion
+//#region src/gameplay/prefab-shelf.d.ts
+/**
+* A shelf of templates the GAME clones itself — towers, bolts, damage numbers.
+*
+* `Spawner` detaches its one prefab at enter, so a spawned enemy's whole
+* subtree is live and nobody has to think about it. A game that clones on its
+* own terms — a tower the player places, a bolt that tower fires — has no
+* spawner, so its templates sat in the tree as LIVE nodes: their behaviours
+* ticked, their turrets shot, and `visible: false` hid a node without switching
+* it off. The documented answer was to author every template `"enabled": false`
+* and wake the clone with `clone.behavior?.enable()`.
+*
+* That wakes ONE node, and the same docs teach that a node carries one
+* behaviour — so a prefab's parts live on children, and every one of those
+* stays asleep, silently and for good, because `enabled` is a pause switch that
+* never complains. Measured on a shipped tower defense: the bolt's
+* `Projectile` was woken and its sibling `Lifetime` was not, so every bolt that
+* MISSED flew forever — five still in the tree at 69 seconds, in a game that
+* passed its harness, its audit and every rung of the ladder.
+*
+* ```json
+* { "name": "Prefabs", "type": "Node2D", "script": { "name": "PrefabShelf" },
+*   "children": [ { "name": "Tower", "type": "Node2D", "children": [] } ] }
+* ```
+* ```ts
+* const shelf = this.node.getNode('/Game/Prefabs').behavior as PrefabShelf;
+* const tower = shelf.make('Tower');       // detached, like `duplicateNode`
+* tower.position = at;                     // set it up BEFORE it readies
+* this.node.getNode('/Game/Towers').addChild(tower);
+* ```
+*
+* The children never ENTER the tree, so nothing has to be asleep, nothing has
+* to be hidden, and `make()` hands back a clone that is awake all the way down.
+*/
+declare class PrefabShelf extends Behavior {
+  static readonly props: PropSchema;
+  static readonly signals: readonly string[];
+  prefabs: string;
+  /** Templates, in the order they were authored. */
+  private readonly held;
+  override onEnterTree(): void;
+  /** A shelf attached at runtime never saw `onEnterTree`; idempotent. */
+  override onReady(): void;
+  private claim;
+  /** What this shelf holds, in authored order. */
+  names(): string[];
+  /**
+  * A live clone of one template, DETACHED — `addChild` it yourself.
+  *
+  * Detached for the same reason `duplicateNode` is, and it is not a
+  * formality: `onReady` fires on attach, and a behaviour that reads its node
+  * there (`FloatAway` banks its starting position) would bank the wrong one.
+  * Set the clone up, then attach it.
+  *
+  * The clone is VISIBLE even if the template was authored hidden (a scene
+  * migrating off the old `visible: false` shelf keeps working), and every
+  * behaviour in it is however it was authored: awake unless the template
+  * itself asks to sleep, which is now only ever a state machine's own doing.
+  */
+  make(name: string): Node;
+  private childNames;
+}
+//#endregion
 //#region src/gameplay/spatial.d.ts
 /**
 * A node's position with every spatial ancestor's added in.
@@ -1311,4 +1375,4 @@ declare function registerGameplayBehaviors(opts?: {
   replace?: boolean;
 }): void;
 //#endregion
-export { CameraShake, Chase, Collector, Cooldown, Currency, DamageOnContact, DayNight, type DayPhase, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };
+export { CameraShake, Chase, Collector, Cooldown, Currency, DamageOnContact, DayNight, type DayPhase, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, PrefabShelf, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { A as phaseOf, C as restartScene, D as FloatAway, F as Chase, M as Health, N as Currency, O as FaceTarget, P as Collector, S as goToScene, T as FollowCamera, X as localFromWorld, Z as worldPosition, _ as Cooldown, a as Wander, b as Interactable, c as SavePoint, d as Patrol, f as PathFollow, g as CameraShake, h as Lifetime, i as WaveSpawner, j as DamageOnContact, k as DayNight, l as Projectile, m as MoveTo, n as registerGameplayBehaviors, o as Spawner, p as Oscillate, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Pickup, v as hitStop, x as GameFlow, y as screenFlash } from "./gameplay-BfHkuzVb.js";
-export { CameraShake, Chase, Collector, Cooldown, Currency, DamageOnContact, DayNight, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };
+import { A as DayNight, C as goToScene, E as FollowCamera, F as Collector, I as Chase, M as DamageOnContact, N as Health, O as FloatAway, P as Currency, Q as worldPosition, S as GameFlow, Z as localFromWorld, _ as CameraShake, a as Wander, b as screenFlash, c as SavePoint, d as Pickup, f as Patrol, g as Lifetime, h as MoveTo, i as WaveSpawner, j as phaseOf, k as FaceTarget, l as Projectile, m as Oscillate, n as registerGameplayBehaviors, o as Spawner, p as PathFollow, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as PrefabShelf, v as Cooldown, w as restartScene, x as Interactable, y as hitStop } from "./gameplay-BlQe-M07.js";
+export { CameraShake, Chase, Collector, Cooldown, Currency, DamageOnContact, DayNight, FaceTarget, FloatAway, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, PrefabShelf, Projectile, SavePoint, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, localFromWorld, phaseOf, registerGameplayBehaviors, restartScene, screenFlash, worldPosition };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { a as ParticleSimConfig, c as showBootFailure, i as ParticleSim, n as AudioPlayer, o as ParticleView, s as isWebGLAvailable, t as AudioElementLike } from "./audio-player-DaMxqfNE.js";
-import { $ as T_PREFIX, A as SettingsValues, At as BusName, B as captureBehaviors, C as EngineStats, Ct as sfxDuration, Dt as MusicTrack, E as DeviceHints, Et as MusicManager, F as BehaviorState, Ft as LogLevel, G as ORDER_GROUP_BASE, H as savesWithoutUid, I as RestoreReport, It as LogManager, J as effectiveOrder, K as OrderGroup, L as SaveSlot, Lt as Signal, M as readDeviceHints, Mt as NodeLifecycle, N as suggestQuality, Nt as SceneTree, O as QualityTier, Ot as PlayMusicOptions, P as Scene, Pt as LogEntry, Q as Localization, R as SaveSlots, Rt as SignalListener, S as Scheduler, St as SynthOptions, T as RendererStats, Tt as MusicBackend, U as SaveStore, V as restoreBehaviors, W as createSaveStore, X as BASE_LOCALE, Y as resolveOrderGroups, Z as LocaleTables, _ as mergeStaticSignals, _t as spatialPan, a as clearBehaviors, at as EffectLog, b as Engine, bt as SfxParams, c as registeredBehaviors, ct as isAudioContextAvailable, d as PropSchema, dt as Listener, et as suggestLocale, f as clearRegistry, ft as ROLLOFF_MODELS, g as getNodeType, gt as spatialGain, h as getNodeSignals, ht as Vec3, i as behaviorSignals, it as EffectKind, j as qualityEnvironment, jt as Node, k as Settings, kt as AudioBuses, l as NodeCtor, lt as Voice, m as getNodeSchema, mt as SpatialParams, n as BehaviorCtor, nt as InputMap, o as getBehavior, ot as SfxEngine, p as createNode, pt as RolloffModel, q as OrderGroupTable, r as behaviorSchema, rt as EffectEvent, s as registerBehavior, st as SfxPlayOptions, t as Behavior, tt as translationKey, u as PropDef, ut as VoicePreset, v as registerNode, vt as SFX_PRESETS, w as GameStats, wt as synthSfx, x as EngineOptions, xt as SfxWave, y as registeredTypes, yt as SFX_PRESET_NAMES, z as behaviorsWithoutSave } from "./behavior-DZExDn9o.js";
+import { a as ParticleSimConfig, c as showBootFailure, i as ParticleSim, n as AudioPlayer, o as ParticleView, s as isWebGLAvailable, t as AudioElementLike } from "./audio-player-ioZ7VKC6.js";
+import { $ as T_PREFIX, A as SettingsValues, At as BusName, B as captureBehaviors, C as EngineStats, Ct as sfxDuration, Dt as MusicTrack, E as DeviceHints, Et as MusicManager, F as BehaviorState, Ft as LogLevel, G as ORDER_GROUP_BASE, H as savesWithoutUid, I as RestoreReport, It as LogManager, J as effectiveOrder, K as OrderGroup, L as SaveSlot, Lt as Signal, M as readDeviceHints, Mt as NodeLifecycle, N as suggestQuality, Nt as SceneTree, O as QualityTier, Ot as PlayMusicOptions, P as Scene, Pt as LogEntry, Q as Localization, R as SaveSlots, Rt as SignalListener, S as Scheduler, St as SynthOptions, T as RendererStats, Tt as MusicBackend, U as SaveStore, V as restoreBehaviors, W as createSaveStore, X as BASE_LOCALE, Y as resolveOrderGroups, Z as LocaleTables, _ as mergeStaticSignals, _t as spatialPan, a as clearBehaviors, at as EffectLog, b as Engine, bt as SfxParams, c as registeredBehaviors, ct as isAudioContextAvailable, d as PropSchema, dt as Listener, et as suggestLocale, f as clearRegistry, ft as ROLLOFF_MODELS, g as getNodeType, gt as spatialGain, h as getNodeSignals, ht as Vec3, i as behaviorSignals, it as EffectKind, j as qualityEnvironment, jt as Node, k as Settings, kt as AudioBuses, l as NodeCtor, lt as Voice, m as getNodeSchema, mt as SpatialParams, n as BehaviorCtor, nt as InputMap, o as getBehavior, ot as SfxEngine, p as createNode, pt as RolloffModel, q as OrderGroupTable, r as behaviorSchema, rt as EffectEvent, s as registerBehavior, st as SfxPlayOptions, t as Behavior, tt as translationKey, u as PropDef, ut as VoicePreset, v as registerNode, vt as SFX_PRESETS, w as GameStats, wt as synthSfx, x as EngineOptions, xt as SfxWave, y as registeredTypes, yt as SFX_PRESET_NAMES, z as behaviorsWithoutSave } from "./behavior-Bf9P9oB2.js";
 import { a as SceneJson, c as JsonValue, d as jsonKind, i as SCENE_FORMAT, l as jsonClone, n as ConnectionJson, o as JsonKind, r as NodeJson, s as JsonObject, t as Rng, u as jsonEquals } from "./rng-Bb-IutXB.js";
-import { n as loadScene, t as LoadSceneOptions } from "./loader-Cff09LMm.js";
+import { n as loadScene, t as LoadSceneOptions } from "./loader-CBfQzB6S.js";
 import { i as resolveFrames, n as AnimationEntry, r as resolveAnimation, t as AnimationDef } from "./sprite-animation-CMr6f1K2.js";
 import { i as gridFromRows, n as PathGrid, r as findPath, t as FindPathOptions } from "./pathfinding-_fGrCFmH.js";
-import { a as startRecording, c as IncantoErrorDetails, i as replay, l as auditScene, n as ReplayEvent, o as IncantoError, r as ReplayJson, s as IncantoErrorCode, t as Recorder } from "./replay-Dmw-PKQu.js";
+import { a as startRecording, c as IncantoErrorDetails, i as replay, l as auditScene, n as ReplayEvent, o as IncantoError, r as ReplayJson, s as IncantoErrorCode, t as Recorder } from "./replay-CBEChqXq.js";
 
 //#region src/core/audio/crossfade.d.ts
 /**
@@ -973,6 +973,17 @@ declare class UiSlider extends HudWidgetBase {
   override focusable: boolean;
   /** Left/right nudge by one step — the only sane thing a d-pad can mean here. */
   override _activate(dir: number): void;
+  /**
+  * Move it as a PERSON would: set the value and say so.
+  *
+  * `UiButton` has `press()` and the value widgets had nothing, because
+  * assigning `.value` deliberately does not emit (restoring a saved setting
+  * must not fire the handler that saved it). So a harness — or a game driving
+  * its own menu: a preset button, "reset to defaults", a tutorial that moves a
+  * slider for you — had one route to "the player changed this", and it was
+  * `_activate`, which is internal and takes a direction rather than a value.
+  */
+  choose(value: number): void;
   private input;
   private text;
   private last;
@@ -989,6 +1000,8 @@ declare class UiToggle extends HudWidgetBase {
   override focusable: boolean;
   /** Confirm flips it; left/right set it explicitly, which reads better on a pad. */
   override _activate(dir: number): void;
+  /** Flip it as a PERSON would: set the value and say so. See `UiSlider.choose`. */
+  choose(value: boolean): void;
   private input;
   private last;
   protected _build(): HTMLElement;
@@ -1023,6 +1036,16 @@ declare class UiSelect extends HudWidgetBase {
   static validateJson(node: Node): void;
   /** Left/right (and confirm) walk the list — a select has no other gesture. */
   override _activate(dir: number): void;
+  /**
+  * Pick an option as a PERSON would: set the value and say so. See
+  * `UiSlider.choose`.
+  *
+  * An option the list does not offer is refused, for the reason
+  * `validateJson` refuses it in the file: the browser would show the first one
+  * while the node kept answering with what it was given, and nothing would
+  * ever reconcile them.
+  */
+  choose(value: string): void;
   private select;
   private labelEl;
   private lastLabel;

package/dist/index.js

@@ -1,13 +1,13 @@
 import { n as jsonEquals, r as jsonKind, t as jsonClone } from "./json-CfTjpvW8.js";
-import { C as isConstRef, D as newUid, E as resolveViewport, H as UiBar, J as describeRefProblem, K as Node, M as effectiveOrder, N as resolveOrderGroups, O as SceneTree, P as InputMap, Q as Behavior, R as HudLayer, S as CONST_REF_KEY, T as computeViewport, U as UiText, V as UiBanner, X as resolveRefInJson, Y as nodeRefWarnings, Z as parseNodePath, _ as SCENE_FORMAT, a as restoreBehaviors, at as registeredBehaviors, et as behaviorSchema, g as serializeNode, h as Scene, i as captureBehaviors, it as registerBehavior, j as ORDER_GROUP_BASE, k as createSaveStore, n as SaveSlots, nt as clearBehaviors, o as savesWithoutUid, ot as Signal, p as loadScene, r as behaviorsWithoutSave, rt as getBehavior, s as duplicateNode, tt as behaviorSignals, w as resolveConstants } from "./save-slots-BXVg148r.js";
-import { A as T_PREFIX, B as SFX_PRESET_NAMES, D as EffectLog, E as LogManager, F as isAudioContextAvailable, G as crossfadeGains, H as synthSfx, I as ROLLOFF_MODELS, K as fadeGain, L as spatialGain, N as translationKey, O as BASE_LOCALE, P as SfxEngine, R as spatialPan, S as qualityEnvironment, T as suggestQuality, U as MusicManager, V as sfxDuration, W as WebAudioMusicBackend, _ as AudioPlayer, a as UiMuteToggle, b as Settings, c as UiRenderScaleSelect, d as UiToggle, f as UiVolumeSlider, g as UiDialogue, h as UiButton, i as UiLanguageSelect, j as suggestLocale, k as Localization, l as UiSelect, m as Respawn, n as UiFrameCapSelect, o as UiPanel, p as Timer, q as AudioBuses, r as UiImage, s as UiQualitySelect, t as registerCoreNodes, u as UiSlider, v as Engine, w as readDeviceHints, z as SFX_PRESETS } from "./register-6DYnKZcy.js";
+import { $ as parseNodePath, A as SceneTree, B as HudLayer, D as computeViewport, E as resolveConstants, F as resolveOrderGroups, G as UiText, I as InputMap, J as Node, N as ORDER_GROUP_BASE, O as resolveViewport, P as effectiveOrder, Q as resolveRefInJson, T as isConstRef, U as UiBanner, W as UiBar, X as describeRefProblem, Z as nodeRefWarnings, _ as Scene, a as restoreBehaviors, at as getBehavior, ct as Signal, et as Behavior, h as loadScene, i as captureBehaviors, it as clearBehaviors, j as createSaveStore, k as newUid, n as SaveSlots, nt as behaviorSchema, o as savesWithoutUid, ot as registerBehavior, r as behaviorsWithoutSave, rt as behaviorSignals, s as duplicateNode, st as registeredBehaviors, v as serializeNode, w as CONST_REF_KEY, y as SCENE_FORMAT } from "./save-slots-CEuJPUle.js";
+import { A as T_PREFIX, B as SFX_PRESET_NAMES, D as EffectLog, E as LogManager, F as isAudioContextAvailable, G as crossfadeGains, H as synthSfx, I as ROLLOFF_MODELS, K as fadeGain, L as spatialGain, N as translationKey, O as BASE_LOCALE, P as SfxEngine, R as spatialPan, S as qualityEnvironment, T as suggestQuality, U as MusicManager, V as sfxDuration, W as WebAudioMusicBackend, _ as AudioPlayer, a as UiMuteToggle, b as Settings, c as UiRenderScaleSelect, d as UiToggle, f as UiVolumeSlider, g as UiDialogue, h as UiButton, i as UiLanguageSelect, j as suggestLocale, k as Localization, l as UiSelect, m as Respawn, n as UiFrameCapSelect, o as UiPanel, p as Timer, q as AudioBuses, r as UiImage, s as UiQualitySelect, t as registerCoreNodes, u as UiSlider, v as Engine, w as readDeviceHints, z as SFX_PRESETS } from "./register-5IYfooAN.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-CDOMybym.js";
 import { c as getNodeSchema, f as mergeStaticSignals, i as joystickVector, l as getNodeSignals, m as registeredTypes, n as attachTouchControls, o as clearRegistry, p as registerNode, s as createNode, t as TouchControls, u as getNodeType } from "./touch-BnCyPA0G.js";
-import { n as startRecording, r as auditScene, t as replay } from "./replay-DjAkAzMq.js";
+import { n as startRecording, r as auditScene, t as replay } from "./replay-datiAE-b.js";
 import { t as showBootFailure } from "./boot-failure-CKYrEcGF.js";
 import { a as logText, i as logReport, o as parseDrive, r as resolveRendering, t as isWebGLAvailable } from "./webgl-unavailable-C8aDbGmR.js";
 import { t as createNoise2D } from "./noise-D3nPpmFg.js";
 import { a as PARTICLE_PRESETS, i as ParticleSim, n as resolveFrames, o as PARTICLE_PRESET_NAMES, s as applyParticlePreset, t as resolveAnimation } from "./sprite-animation-CqR2o3SA.js";
-import { a as findPath, i as preloadUrls, n as assetUrls, o as gridFromRows, r as preloadSceneAssets, t as VERSION } from "./src-Cxfiv1Hg.js";
+import { a as findPath, i as preloadUrls, n as assetUrls, o as gridFromRows, r as preloadSceneAssets, t as VERSION } from "./src-DRSsRleD.js";
 export { AudioBuses, AudioPlayer, BASE_LOCALE, Behavior, CONST_REF_KEY, EffectLog, Engine, HudLayer, IncantoError, InputMap, Localization, LogManager, MusicManager, Node, ORDER_GROUP_BASE, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Respawn, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, SaveSlots, Scene, SceneTree, Settings, SfxEngine, Signal, T_PREFIX, Timer, TouchControls, UiBanner, UiBar, UiButton, UiDialogue, UiFrameCapSelect, UiImage, UiLanguageSelect, UiMuteToggle, UiPanel, UiQualitySelect, UiRenderScaleSelect, UiSelect, UiSlider, UiText, UiToggle, UiVolumeSlider, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, behaviorSchema, behaviorSignals, behaviorsWithoutSave, captureBehaviors, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, describeRefProblem, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, isWebGLAvailable, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, logReport, logText, mergeStaticSignals, newUid, nodeRefWarnings, parseDrive, parseNodePath, preloadSceneAssets, preloadUrls, qualityEnvironment, readDeviceHints, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveAnimation, resolveConstants, resolveFrames, resolveOrderGroups, resolveRefInJson, resolveRendering, resolveViewport, restoreBehaviors, savesWithoutUid, serializeNode, sfxDuration, showBootFailure, spatialGain, spatialPan, startRecording, suggestLocale, suggestQuality, synthSfx, translationKey };

package/dist/{loader-Cff09LMm.d.ts → loader-CBfQzB6S.d.ts}

@@ -1,10 +1,17 @@
-import { P as Scene, b as Engine } from "./behavior-DZExDn9o.js";
+import { P as Scene, b as Engine } from "./behavior-Bf9P9oB2.js";
 import { a as SceneJson } from "./rng-Bb-IutXB.js";
 
 //#region src/core/scene/loader.d.ts
 interface LoadSceneOptions {
-  /** Resolve a sub-scene path referenced by `{instance: '<path>'}`. */
-  resolveScene?: (path: string) => SceneJson;
+  /**
+  * Resolve a sub-scene path referenced by `{instance: '<path>'}`.
+  *
+  * Returning nothing is a real answer — "I do not have that one" — and the
+  * loader turns it into `UNRESOLVED_INSTANCE` naming the node and the path.
+  * The type said `=> SceneJson`, so the one recipe a game actually writes
+  * (`prefabs[path] ?? null` over a bundler's eager glob) did not typecheck.
+  */
+  resolveScene?: (path: string) => SceneJson | null | undefined;
   /**
   * Assets declared ELSEWHERE in the project, for `$ref` validation.
   *

package/dist/net.d.ts

@@ -1,6 +1,6 @@
-import { d as PropSchema, jt as Node } from "./behavior-DZExDn9o.js";
+import { d as PropSchema, jt as Node } from "./behavior-Bf9P9oB2.js";
 import { t as DiagnosticSink } from "./diagnostics-Cu85N3tL.js";
-import { a as NetworkManagerOptions, c as LocalGameServer, d as ServerClass, f as createLocalGameServer, g as Unsubscribe, h as NetworkTransport, i as NetworkManager, l as LocalGameServerOptions, m as LoopbackTransport, n as SplitScreenPlayer, o as applySyncPatch, p as LoopbackHub, r as createSplitScreen, s as CollectionOptions, t as SplitScreenOptions, u as LocalGameServerTransport } from "./split-screen--k-XpBjr.js";
+import { a as NetworkManagerOptions, c as LocalGameServer, d as ServerClass, f as createLocalGameServer, g as Unsubscribe, h as NetworkTransport, i as NetworkManager, l as LocalGameServerOptions, m as LoopbackTransport, n as SplitScreenPlayer, o as applySyncPatch, p as LoopbackHub, r as createSplitScreen, s as CollectionOptions, t as SplitScreenOptions, u as LocalGameServerTransport } from "./split-screen-DkqLng6q.js";
 
 //#region src/net/agent8.d.ts
 /**

package/dist/net.js

@@ -1,3 +1,3 @@
-import { n as createAgent8Server } from "./agent8-CmNF01gA.js";
-import { a as NetworkManager, d as createLocalGameServer, f as LoopbackHub, l as LocalGameServer, n as registerNodesNet, o as applySyncPatch, p as LoopbackTransport, r as NetworkSpawner, t as createSplitScreen, u as LocalGameServerTransport } from "./split-screen-PL78oVXP.js";
+import { n as createAgent8Server } from "./agent8-BqZ0_O1u.js";
+import { a as NetworkManager, d as createLocalGameServer, f as LoopbackHub, l as LocalGameServer, n as registerNodesNet, o as applySyncPatch, p as LoopbackTransport, r as NetworkSpawner, t as createSplitScreen, u as LocalGameServerTransport } from "./split-screen-Bm5DTElG.js";
 export { LocalGameServer, LocalGameServerTransport, LoopbackHub, LoopbackTransport, NetworkManager, NetworkSpawner, applySyncPatch, createAgent8Server, createLocalGameServer, createSplitScreen, registerNodesNet };

package/dist/{physics-2d-CE0Qvy3V.js → physics-2d-DrIgTlLk.js}

@@ -1,7 +1,7 @@
 import { o as __exportAll } from "./json-CfTjpvW8.js";
-import { q as diagnose } from "./save-slots-BXVg148r.js";
+import { Y as diagnose } from "./save-slots-CEuJPUle.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-Bkk0wSDB.js";
+import { _ as RigidBody2D, b as validateCollider2D, g as PhysicsBody2D, h as CharacterBody2D, m as Area2D, p as Joint2D, y as Node2D } from "./register-C8HuRkOf.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 import { n as jointContacts, t as withoutRapierInitNoise } from "./quiet-rapier-C6fW4zcW.js";
 //#region src/2d/physics/physics-2d.ts

package/dist/{physics-3d-CpH-2gn5.js → physics-3d-BzOCw1VS.js}

@@ -1,10 +1,10 @@
 import { o as __exportAll } from "./json-CfTjpvW8.js";
-import { q as diagnose } from "./save-slots-BXVg148r.js";
+import { Y as diagnose } from "./save-slots-CEuJPUle.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { B as Area3D, G as Node3D, H as PhysicsBody3D, K as validateCollider3D, U as RigidBody3D, V as CharacterBody3D } from "./gameplay-BfHkuzVb.js";
+import { H as CharacterBody3D, K as Node3D, U as PhysicsBody3D, V as Area3D, W as RigidBody3D, q as validateCollider3D } from "./gameplay-BlQe-M07.js";
 import { n as registerDebugSource } from "./debug-draw-BM3DsvtT.js";
 import { n as jointContacts, t as withoutRapierInitNoise } from "./quiet-rapier-C6fW4zcW.js";
-import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-D6Q5BxeE.js";
+import { A as Terrain3D, F as InstancedMesh3D, L as buildMeshGeometry, P as Joint3D } from "./environment-presets-BeHoaGhy.js";
 import { Euler, Matrix4, Quaternion, Vector3 } from "three";
 //#region src/3d/physics/collider-lines.ts
 /**

package/dist/{picking-CQJ_PJKh.js → picking-C9McVJrO.js}

@@ -1,7 +1,7 @@
-import { _ as AudioPlayer } from "./register-6DYnKZcy.js";
+import { _ as AudioPlayer } from "./register-5IYfooAN.js";
 import { i as logReport, o as parseDrive } from "./webgl-unavailable-C8aDbGmR.js";
-import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-Dlq13Gyj.js";
-import { Z as worldPosition } from "./gameplay-BfHkuzVb.js";
+import { a as frameSignature, i as frameImage, o as frameStats } from "./frame-report-D-_7YF2G.js";
+import { Q as worldPosition } from "./gameplay-BlQe-M07.js";
 //#region src/core/audio-errors.ts
 /** Every AudioPlayer under `root` whose source could not be played. */
 function audioErrors(root) {

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { P as Scene, b as Engine, n as BehaviorCtor } from "./behavior-DZExDn9o.js";
+import { P as Scene, b as Engine, n as BehaviorCtor } from "./behavior-Bf9P9oB2.js";
 import { c as JsonValue } from "./rng-Bb-IutXB.js";
 import { CSSProperties, ReactNode } from "react";
 

package/dist/react.js

@@ -156,7 +156,7 @@ function IncantoCanvas(props) {
 				pointer: latest.pointer,
 				...keyboard !== void 0 ? { keyboard } : {}
 			};
-			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-C7ffQWW7.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-Bwvh6q8A.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-CmFAtLZp.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-C9rWqqAC.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;

package/dist/{register-6DYnKZcy.js → register-5IYfooAN.js}

@@ -1,5 +1,5 @@
 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 { B as HudLayer, F as resolveOrderGroups, G as UiText, H as TAPPABLE, I as InputMap, J as Node, N as ORDER_GROUP_BASE, U as UiBanner, V as HudWidgetBase, W as UiBar, Y as diagnose, a as restoreBehaviors, ct as Signal, i as captureBehaviors, j as createSaveStore, q as requireText, t as ENGINE_STATE_KEY, z as FITS } from "./save-slots-CEuJPUle.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { t as Rng } from "./rng-CDOMybym.js";
 import { p as registerNode } from "./touch-BnCyPA0G.js";
@@ -2470,7 +2470,11 @@ var Engine = class {
 			this._scene.root.free();
 			this._scene.tree._setEngine(null);
 			this._scene = null;
-			this.sceneChanged.emit(null);
+			try {
+				this.sceneChanged.emit(null);
+			} catch (error) {
+				diagnose(this, "warn", "[incanto] teardown: a `sceneChanged` listener threw (continuing) — it fires with NULL here, so a handler that reads the scene has to check for it", error);
+			}
 		}
 		this.input.dispose();
 		this.input.clear();
@@ -3612,7 +3616,20 @@ var UiSlider = class extends HudWidgetBase {
 	/** 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));
+		this.choose(this.value + dir * this.step);
+	}
+	/**
+	* Move it as a PERSON would: set the value and say so.
+	*
+	* `UiButton` has `press()` and the value widgets had nothing, because
+	* assigning `.value` deliberately does not emit (restoring a saved setting
+	* must not fire the handler that saved it). So a harness — or a game driving
+	* its own menu: a preset button, "reset to defaults", a tutorial that moves a
+	* slider for you — had one route to "the player changed this", and it was
+	* `_activate`, which is internal and takes a direction rather than a value.
+	*/
+	choose(value) {
+		const next = Math.min(this.max, Math.max(this.min, value));
 		if (next === this.value) return;
 		this.value = next;
 		this.last = next;
@@ -3670,12 +3687,15 @@ var UiToggle = class extends HudWidgetBase {
 	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);
+		this.choose(dir === 0 ? !this.value : dir > 0);
+	}
+	/** Flip it as a PERSON would: set the value and say so. See `UiSlider.choose`. */
+	choose(value) {
+		if (value === this.value) return;
+		this.value = value;
+		this.last = value;
+		if (this.input) this.input.checked = value;
+		this.emit("changed", value);
 	}
 	input = null;
 	last = null;
@@ -3754,14 +3774,28 @@ var UiSelect = class extends HudWidgetBase {
 	}
 	/** 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);
+		const choices = this.choices();
 		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);
+		if (next) this.choose(next);
+	}
+	/**
+	* Pick an option as a PERSON would: set the value and say so. See
+	* `UiSlider.choose`.
+	*
+	* An option the list does not offer is refused, for the reason
+	* `validateJson` refuses it in the file: the browser would show the first one
+	* while the node kept answering with what it was given, and nothing would
+	* ever reconcile them.
+	*/
+	choose(value) {
+		const choices = this.choices();
+		if (choices.length > 0 && !choices.includes(value)) throw new IncantoError("PROP_TYPE_MISMATCH", `UiSelect '${this.name}': choose('${value}') is not one of its options [${choices.join(", ")}].`, { prop: "value" });
+		if (value === this.value) return;
+		this.value = value;
+		this.last = value;
+		if (this.select) this.select.value = value;
+		this.emit("changed", value);
 	}
 	select = null;
 	labelEl = null;