incanto 0.69.0 → 0.70.0

package/dist/gameplay.d.ts

@@ -1,5 +1,5 @@
-import { b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, t as Behavior } from "./behavior-rm8vVzu_.js";
-import { c as JsonValue, s as JsonObject } from "./schema-B6ugCV1Q.js";
+import { b as Engine, d as PropSchema, jt as Node, n as BehaviorCtor, t as Behavior } from "./behavior-DZExDn9o.js";
+import { c as JsonValue, s as JsonObject } from "./rng-Bb-IutXB.js";
 
 //#region src/gameplay/chase.d.ts
 /**
@@ -58,6 +58,8 @@ declare class Collector extends Behavior {
   /** How many have been picked up so far. */
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /** The counter on screen. `collect(0)` used to be the only way to repaint it. */
+  override announce(): void;
 }
 //#endregion
 //#region src/gameplay/currency.d.ts
@@ -85,10 +87,21 @@ declare class Currency extends Behavior {
   spend(cost: number): boolean;
   /** Take payment in. */
   earn(gain: number): void;
+  /** What has already been complained about, so a loop says it once. */
+  private complained;
+  /**
+  * A zero is ordinary; a NEGATIVE is a caller that flipped a sign.
+  *
+  * Reported rather than thrown: this is called from game code inside a frame,
+  * and a throw here quarantines the node holding the player's money.
+  */
+  private refuseNonsense;
   /** Set it outright (a shop that grants, a cheat, a restore). */
   setAmount(next: number): void;
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /** The wallet on screen — `setAmount`'s own doc comment already named a restore. */
+  override announce(): void;
 }
 //#endregion
 //#region src/gameplay/health.d.ts
@@ -116,6 +129,7 @@ declare class Health extends Behavior {
   regenPerSec: number;
   invulnerableFor: number;
   freeOnDeath: boolean;
+  freeParent: boolean;
   /** Current hit points (set to `max` on ready). */
   current: number;
   private invulnTimer;
@@ -194,6 +208,14 @@ declare class Health extends Behavior {
   /** Current HP and whether death already fired — `max` comes back from JSON. */
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /**
+  * Repaint the bar. Not `died` — a save is being read, nobody just died.
+  *
+  * This one needed the hook most: `setCurrent` is private AND early-returns
+  * when the value is unchanged, so no call a game could make would repaint a
+  * restored bar. It read 100 at 38 HP until the next hit teleported it to 37.
+  */
+  override announce(): void;
 }
 //#endregion
 //#region src/gameplay/damage-on-contact.d.ts
@@ -297,6 +319,7 @@ declare class FollowCamera extends Behavior {
   offset: number[];
   smoothing: number;
   deadzone: number;
+  private shakeRng;
   override onReady(): void;
   private shakeMag;
   private shakeT;
@@ -321,6 +344,8 @@ declare class Interactable extends Behavior {
   action: string;
   range: number;
   actorGroup: string;
+  /** Actions already reported missing, so a per-frame read says it once. */
+  private readonly reportedActions;
   override update(): void;
 }
 //#endregion
@@ -466,7 +491,31 @@ declare class Patrol extends Behavior {
   * this one is invisible to it.
   */
   private reportDeadWaypoint;
-  /** Resolve waypoint `i` to a position, reading node paths live. */
+  /**
+  * Resolve waypoint `i` to a position in the MOVER's frame, reading node paths
+  * live.
+  *
+  * A node-path waypoint used to return the marker's raw `position`, which is
+  * parent-relative — and it was then fed to `moveToward(mover.position, …)`,
+  * i.e. read in the MOVER's frame. So a walker and its markers under different
+  * parents walked a shifted copy of the path, silently, with the marker nodes
+  * sitting right there in the scene. Measured on a tower-defence lane
+  * organised the ordinary way (markers under `/root/Path`, spawns under a
+  * container at [-50, 90]): every creep stacked motionless 90 px below and
+  * 72 px short of the keep, `incanto-check` `1/1 scene(s) valid`, zero errors,
+  * zero warnings, and the wave could be neither won nor lost.
+  *
+  * `Chase` has converted through world space since the identical bug was found
+  * there ("comparing two nodes' raw `position` only worked while they happened
+  * to share a parent"), and a `FollowCamera` aimed at a node uses its world
+  * position too. Patrol was the outlier.
+  *
+  * A LITERAL array stays local, because that is the only frame an author can
+  * mean when they type numbers into a behaviour's props.
+  *
+  * `reportDeadWaypoint` could not see this: it fires when a path resolves to
+  * NOTHING, and a path that resolves into the wrong frame resolves fine.
+  */
   private pointAt;
   private advance;
 }
@@ -508,14 +557,58 @@ declare class Pickup extends Behavior {
 * `null` (the engine's "any JSON" escape hatch) and `null` means `'forward'`.
 * `gravity` adds a constant downward (+y, the 2D y-down convention) pull, for
 * lobbed/arcing shots.
+*
+* **Every prop here is live.** `speed` and `direction` re-bake the heading when
+* written, and the heading is resolved on the FIRST STEP rather than at
+* `onReady` — because `onReady` is before the one place a game aims a spawned
+* bullet. `SpawnSource.spawn` ends with `parent.addChild(clone)` and `Spawner`
+* emits `spawned(node)` after that, so a handler that sets a rotation or a
+* direction was always too late. Measured at speed 100 over 60 frames:
+*
+* ```
+* A rotation 0  direction [0,1]     -> pos [  0, 100]   authored: obeyed
+* B rotation 90 direction "forward" -> pos [  0, 100]   authored: obeyed
+* C rotation 90 set after addChild  -> pos [100,   0]   IGNORED
+* D direction [0,1] set after add   -> pos [100,   0]   IGNORED — and it read
+*                                                       back [0,1] while
+*                                                       travelling +x
+* ```
+*
+* What is deliberately NOT live is `rotation` after that first step: a
+* projectile that spins for looks would have its spin become its trajectory.
+* Call `aim()` to re-derive from the current rotation on purpose.
 */
 declare class Projectile extends Behavior {
   static readonly props: PropSchema;
   static readonly signals: readonly string[];
-  speed: number;
-  direction: JsonValue;
+  private _speed;
+  private _direction;
   gravity: number;
+  /** The straight-line part, `direction × speed`. Empty until the first step. */
   private velocity;
+  /**
+  * The +y accumulated by `gravity`, kept APART from `velocity`.
+  *
+  * Re-aiming replaces the straight-line part; the fall is a fact about the
+  * world, not about the shot, so an arrow re-aimed halfway down keeps falling
+  * rather than snapping back to level.
+  */
+  private fall;
+  /** Units per second along `direction`. Writable at any time. */
+  get speed(): number;
+  set speed(value: number);
+  /** A vector (`[x,y(,z)]`) or `'forward'`. Writable at any time. */
+  get direction(): JsonValue;
+  set direction(value: JsonValue);
+  private get armed();
+  /**
+  * Re-derive the heading from `direction` (or, for `'forward'`, from the
+  * node's CURRENT rotation) and bake it into the velocity.
+  *
+  * This is what a `spawned(node)` handler calls after turning the clone, and
+  * the only way a `'forward'` projectile ever re-reads its rotation.
+  */
+  aim(direction?: JsonValue | undefined): void;
   override onReady(): void;
   override update(dt: number): void;
   /** Resolve `direction` to a unit vector, deriving 'forward' from rotation. */
@@ -642,6 +735,14 @@ declare class ScoreKeeper extends Behavior {
   /** The run's progress. `scoreToWin` is balance and comes back from JSON. */
   override serialize(): JsonValue;
   override deserialize(data: JsonValue): void;
+  /**
+  * The score line and the lives counter. NOT `won`/`lost`.
+  *
+  * Re-firing those on load is how a Continue lands straight on the game-over
+  * screen it was loaded to escape — the flags come back through `hasWon` /
+  * `hasLost` and the game reads them, rather than being told again.
+  */
+  override announce(): void;
 }
 //#endregion
 //#region src/gameplay/spawner.d.ts
@@ -679,6 +780,7 @@ declare class Spawner extends Behavior {
   get liveCount(): number;
   /** @internal The detached template node (test/debug only). */
   _templateForTest(): Node;
+  override onEnterTree(): void;
   override onReady(): void;
   /** Begin (or resume) interval spawning. */
   start(): void;
@@ -740,9 +842,27 @@ declare class WaveSpawner extends Behavior {
   private timer;
   private spawnedThisWave;
   private announced;
+  override onEnterTree(): void;
   override onReady(): void;
   /** Start (or restart from) wave 0. */
   start(): void;
+  /**
+  * Which wave you were on — and nothing else.
+  *
+  * `behaviorsWithoutSave` is documented as "the list to read before shipping",
+  * and nobody had read it against this repo's own examples. Five of them put a
+  * `WaveSpawner` at the centre of the game (`fps-3d`, `tps-3d`, `tps-3d-neon`,
+  * `tps-3d-ruins`, `dogfight-3d`), and every one of them saved a run on wave 3
+  * and continued it on wave 1 — silently, because a save reloads the scene
+  * from source and a fresh `onReady` honestly starts at the beginning.
+  *
+  * The wave RESTARTS rather than resuming mid-spawn, which is the same
+  * checkpoint rule the rest of the save system follows: spawned entities are
+  * never restored, so resuming "four enemies into wave 3" would mean resuming
+  * a wave whose enemies do not exist. `waveStarted` fires again for the HUD.
+  */
+  override serialize(): JsonValue;
+  override deserialize(data: JsonValue): void;
   override update(dt: number): void;
   private beginWave;
   private prune;
@@ -834,6 +954,18 @@ declare class DayNight extends Behavior {
   private baseAmbient;
   private baseExposure;
   private captured;
+  /** Said once: there was no sky to move when this first looked. */
+  private reportedNoSky;
+  /**
+  * What time it is. A save that forgets it returns you at dawn.
+  *
+  * `startHour` is the scene's opening, not the run's clock: a fresh `onReady`
+  * cannot know that this player has been out all night. `paused` goes with it
+  * because a game that stops the clock for a cutscene must not resume ticking
+  * on load.
+  */
+  override serialize(): JsonValue;
+  override deserialize(data: JsonValue): void;
   override onReady(): void;
   override update(dt: number): void;
   private applyHour;
@@ -904,6 +1036,25 @@ type GameFlowState = "playing" | "paused" | "gameover" | "won";
 /**
 * Swap to another scene behind a black fade (title→game→next level).
 * Headless (no DOM) the swap is immediate. Restores timeScale to 1.
+*
+* ONE AT A TIME. A door is usually a trigger, and a player who walks along a
+* wall of them fires several inside one fade. Measured on three doorways passed
+* in about a second:
+*
+* ```
+* setScene calls: 3 | order: ["crypt","garden","forge"]
+* final scene   : forge
+* ```
+*
+* Three complete scenes loaded and the player landed in the third — a level
+* they never walked to, from a door they never reached. Further calls while a
+* travel is in flight are IGNORED rather than queued: you already went through
+* a door, and the second one is the same input arriving twice.
+*
+* The outgoing scene also stops while the screen is black. It kept simulating
+* through the fade, so a player who triggered the door mid-fall died in the
+* level they were leaving — and the checkpoint that death wrote was for the
+* level they had left.
 */
 declare function goToScene(engine: Engine, sceneJson: JsonObject, opts?: {
   fadeSeconds?: number;
@@ -961,8 +1112,24 @@ declare class GameFlow extends Behavior {
   state: GameFlowState;
   private frozeScale;
   override onReady(): void;
-  /** The panel follows the state; nothing else may own its visibility. */
+  /**
+  * The panel follows the state; nothing else may own its visibility.
+  *
+  * …and while it is up, the layer it lives on takes ARROW KEYS AND THE PAD.
+  * `HudLayer.focusNavigation` is off by default and rightly so — a game whose
+  * HUD happens to contain a button must not lose its arrow keys the moment one
+  * exists — and `incanto-hud.md` says "turn it on for the screens that ARE
+  * menus and off again when play resumes". A pause panel IS that screen, and
+  * this is the one place in the engine that knows when it opens and closes, so
+  * every game with a pause menu was writing the same two lines or shipping a
+  * menu no controller could reach.
+  *
+  * The layer's own value is remembered and put back: a game that turned
+  * navigation on for its own reasons keeps it after a pause.
+  */
   private syncPausePanel;
+  /** The layer's own `focusNavigation`, while this flow is borrowing it. */
+  private navigationWas;
   gameOver(text?: string, color?: string): void;
   win(text?: string, color?: string): void;
   pause(): void;
@@ -971,7 +1138,7 @@ declare class GameFlow extends Behavior {
   /** Fade to another scene (next level, back to title). */
   goToScene(sceneJson: JsonObject, opts?: {
     fadeSeconds?: number;
-  }): void;
+  } | undefined): void;
   private transition;
   private freeze;
   private thaw;
@@ -1025,6 +1192,19 @@ declare class CameraShake extends Behavior {
   private t;
   private prev;
   /**
+  * Decoration draws from its OWN stream — see `effectRng`.
+  *
+  * A shake drew from `engine.rng`, the stream game logic reads and
+  * `captureState` saves, once per axis per RENDERED frame. So the player's
+  * frame rate decided the game's random numbers, and toggling the
+  * `reduceMotion` accessibility switch changed the rolls: a replay recorded at
+  * 60 fps does not reproduce on a laptop that dropped to 30, and two players
+  * with the same seed diverge because one of them was hit. The particle
+  * siblings were moved off `engine.rng` for exactly this; both camera shakes
+  * were left behind.
+  */
+  private shakeRng;
+  /**
   * Start a shake — unless the player asked for no motion.
   *
   * `settings.reduceMotion` is an accessibility switch, and camera movement the

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { A as DamageOnContact, C as restartScene, D as FaceTarget, E as FloatAway, F as localFromWorld, I as worldPosition, M as Currency, N as Collector, O as DayNight, P as Chase, S as goToScene, T as FollowCamera, _ 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 Health, k as phaseOf, 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-D1KixWK8.js";
+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 };

package/dist/{heightmap-CRK0M4jT.js → heightmap-BYgD5Edk.js}

@@ -1,4 +1,4 @@
-import { t as createNoise2D } from "./noise-CGUMx44x.js";
+import { t as createNoise2D } from "./noise-D3nPpmFg.js";
 //#region src/3d/terrain/heightmap.ts
 /**
 * Pure heightfield + splat-weight math for `Terrain3D` — NO three imports, so

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-C0j2k-yB.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-rm8vVzu_.js";
-import { a as Rng, c as JsonValue, d as jsonKind, i as SceneJson, l as jsonClone, n as NodeJson, o as JsonKind, r as SCENE_FORMAT, s as JsonObject, t as ConnectionJson, u as jsonEquals } from "./schema-B6ugCV1Q.js";
-import { n as loadScene, t as LoadSceneOptions } from "./loader-DadV2QCT.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-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 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 { 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-BQfkX4x7.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";
 
 //#region src/core/audio/crossfade.d.ts
 /**
@@ -109,6 +109,20 @@ type DriveStep = {
   kind: "pointer";
   dx: number;
   dy: number;
+} | {
+  kind: "at";
+  x: number;
+  y: number;
+} | {
+  kind: "atNode";
+  path: string;
+} | {
+  kind: "click";
+  button: number;
+} | {
+  kind: "mouse";
+  button: number;
+  down: boolean;
 } | {
   kind: "step";
   ms: number;
@@ -245,13 +259,26 @@ type RefResult = {
 declare function resolveRefInJson(root: RefNode | undefined, owner: readonly number[], value: string): RefResult;
 /** The problem in English, for `incanto-check` and as the editor's base text. */
 declare function describeRefProblem(problem: RefProblem, value: string): string;
+interface RefWarningOptions {
+  /**
+  * This file is a PREFAB another scene drops in, so a path may legitimately
+  * leave it.
+  *
+  * `/root/Bolts` is the fragment's own root only while the fragment is alone;
+  * attached, it resolves. Four such warnings stood forever on four of five
+  * files of a real project whose main scene audited clean. The verdict is
+  * reworded rather than suppressed: a typo'd path is MOST likely in a file
+  * written away from the scene that gives it meaning, so it still gets named.
+  */
+  fragment?: boolean;
+}
 /**
 * Scene lints for node-path props that point at nothing.
 *
 * An EMPTY value is not reported: `''` is the default of most of these props and
 * means "not set", which is a choice rather than a typo.
 */
-declare function nodeRefWarnings(scene: JsonObject): string[];
+declare function nodeRefWarnings(scene: JsonObject, opts?: RefWarningOptions): string[];
 //#endregion
 //#region src/core/nodes/hud.d.ts
 /**
@@ -305,6 +332,22 @@ declare class HudLayer extends Node {
   override onExitTree(): void;
   override update(): void;
   /**
+  * Is this the layer the keyboard is talking to?
+  *
+  * Keyboard focus is singular by nature — a browser has ONE focused element —
+  * and `focusNavigation` is per LAYER, so a game with a HUD and a modal that
+  * armed both had a single Enter activate the focused widget in EACH: the
+  * pause menu's RESUME and whatever the screen underneath happened to have
+  * focused, which is "the modal does not block the screen behind it" arriving
+  * through the keyboard.
+  *
+  * The TOPMOST armed layer wins — last in document order, which is the one
+  * drawn on top, and the one a modal is. A hidden layer is not armed at all: a
+  * closed menu must not eat the key from the HUD it covers. With one layer,
+  * which is the usual case, this is always true.
+  */
+  private ownsFocus;
+  /**
   * 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
@@ -361,6 +404,19 @@ declare abstract class HudWidgetBase extends Node {
   * A or an arrow ON this widget means. Default: nothing.
   */
   _activate(_dir: number): void;
+  /**
+  * @internal What a MOUSE CLICK on this widget does. Defaults to `_activate`.
+  *
+  * For a button, a toggle and a select the two are the same thing, which is
+  * why one entry point served both for a while. For `UiDialogue` they are
+  * not: Enter on a waiting choice ANSWERS it, and a click on the box does
+  * not — `advance()` returns early while `current.choices` is set, with the
+  * comment "must pick — clicks don't skip choices".
+  *
+  * A harness whose `click:` answered the question would pass a test the real
+  * game fails, which is the one thing the ladder must not do.
+  */
+  _click(): void;
   /** @internal Draw the focus ring. Overridable if a widget wants its own. */
   _paintFocus(): void;
   /** @internal */
@@ -379,6 +435,27 @@ declare abstract class HudWidgetBase extends Node {
   */
   _mountWidget(): void;
   /**
+  * The gesture, without a pointer — the `press()` of drag and drop.
+  *
+  * All four signals lived on `_wireDrag`, which is wired to a DOM element and
+  * therefore does not exist headless. So the one screen the HUD skill says
+  * needs more than a click — an inventory — was the one screen no harness
+  * could drive: `dragStarted`, `droppedOn`, `dropped` and `dragCancelled`
+  * were unreachable from `runScript`, `incanto-playtest` and every check in
+  * the ladder, and a game that moves items between slots could only be tested
+  * by hand in a browser.
+  *
+  * Same rules as the pointer path, so a test that passes here is a test about
+  * the game: a non-`draggable` source does nothing, a target that is not a
+  * `dropTarget` CANCELS, and dropping a thing back where it came from — on
+  * itself, or on the slot it is already in — is not a move.
+  *
+  * Returns whether the drop was taken.
+  */
+  dropOnto(target: HudWidgetBase | null): boolean;
+  /** The slot this widget is sitting in, if any — its origin for a drop. */
+  private dropTargetAbove;
+  /**
   * Drag and drop, on the DOM the engine already builds.
   *
   * An inventory is the one screen where "click it" is not enough, and every
@@ -409,6 +486,12 @@ declare abstract class HudWidgetBase extends Node {
   * did nothing at all, forever.
   */
   private _followAnchor;
+  /**
+  * Follow the engine, and let a change made HERE reach it — with or without a
+  * DOM element. No element access allowed: this is the half that runs
+  * headless.
+  */
+  protected _pull(): void;
   protected _sync(): void;
   /**
   * Resolve a text prop through the engine's locale.
@@ -487,6 +570,20 @@ declare class UiText extends HudWidgetBase {
   * authored opening line. Filling the slot with nothing instead would put
   * `"Gems  / 8"` on screen for every game's first frame, and a score line
   * that starts blank looks broken rather than empty.
+  *
+  * Unless there IS no opening line. `format` alone painted `""`:
+  *
+  * ```
+  * format = 'Gems {} / 8'
+  * shown before setText  ""            <- nothing on screen
+  * shown after  setText  "Gems 3 / 8"
+  * ```
+  *
+  * and the signals a HUD is wired to — `scoreChanged`, `healthChanged` — only
+  * fire on CHANGE, so the row stays invisible through the whole opening of the
+  * game and forever if the value never moves. An empty slot in a visible
+  * template is the lesser of those two: it shows the author what they
+  * declared, where they declared it.
   */
   get shown(): string;
   override _paintedText(): string | undefined;
@@ -522,7 +619,7 @@ declare class UiBar extends HudWidgetBase {
   * already has, so a bar whose ceiling moves (a max-HP upgrade) needs no
   * second wire.
   */
-  setValue(value: number, max?: number): void;
+  setValue(value: number, max?: number | undefined): void;
   /** Move the ceiling on its own, leaving the fill where it is. */
   setMax(max: number): void;
   protected _build(): HTMLElement;
@@ -554,7 +651,7 @@ declare class UiBanner extends HudWidgetBase {
   show(text: string, opts?: {
     color?: string;
     seconds?: number;
-  }): void;
+  } | undefined): void;
   /** Drop everything (scene transitions). */
   clear(): void;
   protected _build(): HTMLElement;
@@ -626,7 +723,7 @@ declare class UiDialogue extends HudWidgetBase {
   /** What the box currently shows (grows while typing) — test-friendly. */
   get showing(): string;
   /** Queue a line; optional `choices` renders buttons after the line types out. */
-  say(speaker: string, text: string, choices?: string[]): void;
+  say(speaker: string, text: string, choices?: string[] | undefined): void;
   /**
   * A dialogue takes focus while it is up.
   *
@@ -647,6 +744,14 @@ declare class UiDialogue extends HudWidgetBase {
   * `dir` is 0 for "activate" and ±1 for a nudge, the same shape `UiSelect`
   * uses — so one key layout drives a menu, a slider and a conversation.
   */
+  /**
+  * A click on the BOX is `advance()`, which refuses to skip a choice.
+  *
+  * The DOM handler is `box.addEventListener('click', () => this.advance())`
+  * and `advance` returns early while `current.choices` is set. Enter is a
+  * different verb — it answers — so a harness clicking the box must not.
+  */
+  override _click(): void;
   override _activate(dir: number): void;
   /** Show which option the keyboard is on — a ring nobody can see is not one. */
   private paintCursor;
@@ -776,6 +881,16 @@ declare class Timer extends Node {
   private remaining;
   start(time?: number): void;
   stop(): void;
+  /**
+  * Scene-load validation: a period of zero is a timer that never fires.
+  *
+  * `update` guards it — a non-positive period "would spin forever on any dt",
+  * so it calls `stop()` — and the guard is right. Being SILENT about it is
+  * what a load error is for: a scene asking for a tick every zero seconds got
+  * no ticks and no word said. The runtime guard stays, for code that zeroes
+  * the period from a handler.
+  */
+  static validateJson(node: Node): void;
   override onReady(): void;
   override update(dt: number): void;
 }
@@ -890,6 +1005,22 @@ declare class UiSelect extends HudWidgetBase {
   options: string;
   value: string;
   override focusable: boolean;
+  /** The options, as the list of values it actually offers. */
+  private choices;
+  /**
+  * A value the list cannot show is a setting the game and the screen disagree
+  * about.
+  *
+  * The browser cannot select an option that does not exist, so it shows the
+  * FIRST one — while `node.value` keeps answering with what it was given, and
+  * `changed` only fires when a person moves it, so nothing ever reconciles
+  * them. That is the shape a saved setting has after a patch removes a quality
+  * tier, and it is silent for the rest of the session.
+  *
+  * A hard error at LOAD, like every other enum in this engine. An empty value
+  * is "nothing chosen yet", which is a choice.
+  */
+  static validateJson(node: Node): void;
   /** Left/right (and confirm) walk the list — a select has no other gesture. */
   override _activate(dir: number): void;
   private select;
@@ -909,7 +1040,18 @@ declare class UiSelect extends HudWidgetBase {
   */
   protected _optionLabel(value: string): string;
   private fillOptions;
+  /** What was already reported, so a stuck value is said once and not per frame. */
+  private complainedAbout;
+  /**
+  * The runtime half of `validateJson`.
+  *
+  * A behaviour may legitimately write the value first and widen `options`
+  * after — so this reports rather than refuses, and goes quiet again when the
+  * list catches up.
+  */
+  private reportMismatch;
   protected override _sync(): void;
+  protected override _pull(): void;
 }
 /**
 * The language picker, done — because every game needs the same one.
@@ -935,7 +1077,7 @@ declare class UiLanguageSelect extends UiSelect {
   override label: string;
   /** Last locale we PUSHED into `value`, to tell an engine change from a player one. */
   private lastLocale;
-  protected override _sync(): void;
+  protected override _pull(): void;
   protected override _optionLabel(value: string): string;
 }
 /**
@@ -967,6 +1109,7 @@ declare abstract class UiSettingSelect extends UiSelect {
   * `settings.quality.high` is worse than one reading `High`. English is the
   * base language and the fallback, always.
   */
+  protected override _pull(): void;
   protected override _sync(): void;
 }
 /**
@@ -1062,7 +1205,7 @@ declare class UiVolumeSlider extends UiSlider {
   /** Last value we PUSHED in, to tell an engine-side change from a player drag. */
   private lastPushed;
   protected override _labelText(): string;
-  protected override _sync(): void;
+  protected override _pull(): void;
 }
 /**
 * The mute switch.
@@ -1079,7 +1222,7 @@ declare class UiMuteToggle extends UiToggle {
   static override readonly props: PropSchema;
   private lastPushed;
   protected override _labelText(): string;
-  protected override _sync(): void;
+  protected override _pull(): void;
 }
 //#endregion
 //#region src/core/noise.d.ts
@@ -1208,7 +1351,7 @@ declare function resolveConstants<T extends JsonValue | undefined>(value: T, con
 * duplicating a uid'd template can never mint colliding ids. Names ARE
 * kept — rename clones you need to look up individually.
 */
-declare function duplicateNode(node: Node): Node;
+declare function duplicateNode(node: Node, opts?: LoadSceneOptions): Node;
 //#endregion
 //#region src/core/scene/serializer.d.ts
 /**