incanto 0.69.0 → 0.70.0

package/dist/{behavior-rm8vVzu_.d.ts → behavior-DZExDn9o.d.ts}

@@ -1,4 +1,4 @@
-import { a as Rng, c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-B6ugCV1Q.js";
+import { a as SceneJson, c as JsonValue, o as JsonKind, s as JsonObject, t as Rng } from "./rng-Bb-IutXB.js";
 
 //#region src/core/signal.d.ts
 /**
@@ -85,6 +85,43 @@ declare class SceneTree {
   */
   private readonly _nameIndex;
   /**
+  * group → the ATTACHED nodes in it, maintained the way names are.
+  *
+  * `getNodesInGroup` was an un-indexed full-tree walk that allocated a fresh
+  * array per call, while the sibling name lookup was made O(1) for exactly
+  * this reason. The one engine behavior that calls it every frame —
+  * `FaceTarget`, the documented tower-defence turret — therefore cost
+  * turrets x TOTAL SCENE NODES per frame: a 40-turret map in a 5,000-node
+  * world walked 200,000 nodes a frame to find 40 of them, and allocated 40
+  * arrays doing it.
+  */
+  private readonly _groupIndex;
+  /**
+  * uid → node, maintained the way names are.
+  *
+  * `getNodeByUid` was a depth-first walk of the whole tree, and `restoreState`
+  * calls it once per saved uid plus once per freed uid — so loading a save
+  * was `nodes x saved-keys`. A 3,000-node world with 200 saved behaviors
+  * walked 600,000 nodes to hand back 200 values, on the frame the player is
+  * already waiting through a level load.
+  */
+  private readonly _uidIndex;
+  /**
+  * Templates a spawner has detached, by the path they were detached FROM.
+  *
+  * A spawner takes its prefab out of the live tree so it stops ticking. The
+  * second spawner pointing at the same template then found nothing and
+  * hard-failed the scene:
+  *
+  *   Spawner on '/World/B': "prefab" '../Coin' does not resolve to a template
+  *
+  * One shared coin between two spawners is an ordinary thing to author, so the
+  * tree remembers where each template went. Scene-scoped, like everything
+  * else here — a new scene starts with none.
+  * @internal
+  */
+  readonly _templates: Map<string, Node>;
+  /**
   * Bumped whenever ANY node attaches or detaches — cheap "did the tree
   * change shape?" check for per-step body gathers and similar caches.
   */
@@ -127,6 +164,14 @@ declare class SceneTree {
   get frameId(): number;
   /** @internal Node attach hook. */
   _indexName(node: Node): void;
+  /** @internal A uid was assigned or changed on an ATTACHED node. */
+  _reindexUid(node: Node, oldUid: string | null): void;
+  /** @internal The node carrying this uid, or undefined. */
+  _nodeWithUid(uid: string): Node | undefined;
+  /** @internal A node joined a group, or arrived already in one. */
+  _indexGroup(node: Node, group: string): void;
+  /** @internal A node left a group, or left the tree. */
+  _unindexGroup(node: Node, group: string): void;
   /**
   * @internal A RENAME: same node, same place, different key in the name index.
   *
@@ -151,6 +196,14 @@ declare class SceneTree {
   /** @internal */
   _setEngine(engine: Engine | null): void;
   setRoot(node: Node): void;
+  /**
+  * Has the initial load finished?
+  *
+  * `false` through `setRoot`'s enter/ready pass — where a throw is a load
+  * error and must stay one — and `true` for everything after it.
+  * @internal
+  */
+  _live: boolean;
   update(dt: number): void;
   fixedUpdate(dt: number): void;
   getNodesInGroup(group: string): Node[];
@@ -180,12 +233,6 @@ interface NodeLifecycle {
   update(dt: number): void;
   fixedUpdate(dt: number): void;
 }
-/**
-* Base class of everything in an Incanto scene (Godot's Node model).
-*
-* Pure data + tree structure: no rendering, no DOM, no three.js — renderer
-* adapters subscribe from the outside.
-*/
 declare class Node implements NodeLifecycle {
   static readonly typeName: string;
   /**
@@ -198,9 +245,49 @@ declare class Node implements NodeLifecycle {
   private _name;
   private _parent;
   private readonly _children;
+  /**
+  * child name → how many children carry it. Built on first use, then
+  * MAINTAINED — the whole reason this exists.
+  *
+  * `uniqueSiblingName` used to build a fresh `Set` of every existing sibling's
+  * name on every insert, BEFORE asking whether the requested name was even
+  * taken. Filling one parent therefore costs K(K+1)/2 Set operations, and a
+  * single attach into a horde of 8,000 cost about thirteen times what
+  * simulating that whole tree for a frame costs. A spawner-driven game gets
+  * slower the longer it is played, at the moment it is busiest.
+  *
+  * The three places `_children` changes are the three places this changes:
+  * `addChild`, `removeChild` and the `name` setter. `_children` is private to
+  * this file, so that list is the whole list.
+  */
+  private _childNames;
+  /**
+  * stem → the next trailing number worth TRYING. A hint, never the truth.
+  *
+  * The name index alone left a second quadratic in the same function: eight
+  * thousand children all called `Enemy` means eight thousand collisions, and
+  * `while (taken.has(stem + counter)) counter += 1` restarted at 2 every time.
+  * Measured, 4x the children still cost 16.7x the time. Starting the scan
+  * where the last one finished makes the whole fill linear; the `while` still
+  * runs, so a wrong hint costs a step and never a wrong name.
+  */
+  private _nameCounters;
   private readonly _groups;
   private readonly _signals;
+  /**
+  * Disconnects for connections this node made on OTHER nodes.
+  *
+  * Null until it makes one — most nodes never do, and an empty array per node
+  * is a real cost in a scene with thousands of them.
+  * @internal
+  */
+  _outgoing: Array<() => void> | null;
   private _declared;
+  /**
+  * signal → (the listener a caller gave us) → (the quarantining wrapper Signal
+  * actually holds). Null until this node has a listener, which most never do.
+  */
+  private _wrapped;
   private _tree;
   private _ready;
   /**
@@ -208,7 +295,9 @@ declare class Node implements NodeLifecycle {
   * among siblings) a uid is unique across the whole scene, so scripts and
   * tools can address a node no matter where it moves.
   */
-  uid: string | null;
+  private _uid;
+  get uid(): string | null;
+  set uid(value: string | null);
   /** Free-form JSON identity for game logic (e.g. `{kind: 'ITEM', value: 10}`). */
   tags: Record<string, unknown>;
   /** Behavior attachment blob from scene JSON (resolved by the loader). */
@@ -227,6 +316,9 @@ declare class Node implements NodeLifecycle {
   get tree(): SceneTree | null;
   /** Whether onReady has run (it runs at most once per instance). */
   get isReady(): boolean;
+  /** The sibling-name index, built once per parent and then kept up to date. */
+  private childNames;
+  private nameCounters;
   addChild<T extends Node>(child: T): T;
   removeChild(child: Node): void;
   reparent(newParent: Node): void;
@@ -238,8 +330,33 @@ declare class Node implements NodeLifecycle {
   /** Every node in THIS subtree named `name` — names repeat, so a list. */
   getNodesByName(name: string): Node[];
   getPath(): string;
+  /**
+  * The path of the AUTHORED node this one stands for — `getPath()` with every
+  * cloned ancestor's auto-renamed name put back (`/Game/Foe37/Fx` →
+  * `/Game/Foe/Fx`).
+  *
+  * "Is this AudioPlayer wired?" is a question about the scene, and a wave of
+  * forty enemies is one emitter fired forty times, not forty emitters. The
+  * feedback sets ask it, and answering with the live path made a set the
+  * engine promised would "grow with the SCENE, not with the run" grow by one
+  * entry per spawn, forever, in every shipped game.
+  *
+  * The event LOGS keep the live path: a log names the node that acted.
+  */
+  wiringPath(): string;
   getNode(path: string): Node;
   getNodeOrNull(path: string): Node | null;
+  /**
+  * `parseNodePath`, but the error says WHERE it was written.
+  *
+  * Every other scene-load error appends the offending node — `NODE_NOT_FOUND`
+  * lists the children that do exist, an unknown type ends `(at '/Level')` —
+  * and the six `BAD_NODE_PATH` messages were the only family in the engine
+  * that named neither the node nor anything greppable. A bad path in a
+  * behavior prop printed `[BAD_NODE_PATH] Node path must not be empty.` and
+  * nothing else, so bisecting the scene was the only way to find it.
+  */
+  private parseFrom;
   private resolve;
   addToGroup(group: string): void;
   removeFromGroup(group: string): void;
@@ -254,9 +371,36 @@ declare class Node implements NodeLifecycle {
   signal(name: string): Signal<unknown[]>;
   on(signal: string, fn: SignalListener<unknown[]>, opts?: {
     once?: boolean;
+    owner?: Node;
   }): () => void;
   off(signal: string, fn: SignalListener<unknown[]>): void;
   /**
+  * Wrap a listener so ITS throw stays ITS problem.
+  *
+  * `Signal.emit` calls listeners directly, so an exception from one unwinds
+  * into whoever EMITTED. The node quarantine then blames and disables the
+  * emitter's script, and every OTHER listener on that signal is skipped for
+  * the rest of the emit. Measured on the same broken handler, two wirings:
+  *
+  * ```
+  * wired with node.on()        emitter ticks 1/10   emitter script DISABLED
+  * wired with JSON connections emitter ticks 10/10  emitter script fine
+  * ```
+  *
+  * The JSON half has been quarantined since `quarantineWire` shipped, with a
+  * comment saying why: *"a behavior is your code; the node is the engine's. A
+  * typo in the first must not switch off the second."* `.on()` is the same
+  * category — it is the spelling every skill teaches and five shipped examples
+  * use, including `controller.on('movementStateChanged', …)`, where blaming
+  * the emitter stops the player moving entirely. That is verbatim the defect
+  * `quarantineWire` was written to prevent, reached through the other door.
+  *
+  * The owner node is NOT marked `errored`: its own update is fine, only this
+  * wire is off. That is exactly what `quarantineWire` does, and marking it
+  * would restore the over-punishment this removes.
+  */
+  private quarantined;
+  /**
   * How many listeners this node has on `signal` — 0 for one nobody watches.
   *
   * The engine's own leak test reads it, and so can a game: a handler connected
@@ -272,6 +416,29 @@ declare class Node implements NodeLifecycle {
   queueFree(): void;
   /** Immediately detach and tear down this node and its children. */
   free(): void;
+  /**
+  * Run a structural lifecycle hook, quarantining it the way `update` is.
+  *
+  * Only `update`/`fixedUpdate` were ever quarantined, so a throw from a
+  * RUNTIME-created node's `onReady`/`onEnterTree` unwound into the `update()`
+  * of whatever created it. Measured on one Spawner scene, 120 steps:
+  *
+  *   control A  spawner alone            nodes 20, errors 0
+  *   control B  clone throws in UPDATE   nodes 20, errors 19, each line
+  *                                       correctly named on the clone
+  *   A + B      clone throws in onReady  nodes  2, errors  1,
+  *              log: "behavior 'Spawner' on /World/Spawner threw in update"
+  *
+  * The innocent Spawner was quarantined — spawning stopped permanently — and
+  * the one headline named the wrong node, the wrong script and the wrong hook.
+  * An `onExitTree` throw on a runtime `queueFree` was worse still: it escaped
+  * `engine.step()` entirely, with `stats().errors: 0` and an EMPTY log,
+  * because the free-queue flush is outside behaviour propagation.
+  *
+  * During the initial load the throw is re-raised: `loadScene` is where an
+  * authoring mistake has to hard-fail, and that is stated design.
+  */
+  private _runHook;
   /** @internal */
   _propagateEnterTree(tree: SceneTree): void;
   /** @internal */
@@ -350,6 +517,12 @@ interface AudioEvent {
   name: string;
   /** Node path for a node-driven sound; `engine.music` / `engine.sfx` otherwise. */
   from: string;
+  /**
+  * The AUTHORED node this stands for — `from` with a clone's auto-renamed
+  * ancestors put back (`/Game/Foe37/Snd` → `/Game/Foe/Snd`). Absent = same as
+  * `from`. Only `sources()` reads it; the log keeps the live path.
+  */
+  wiredAs?: string;
   bus: BusName;
   /** `engine.time` when it fired, in seconds. */
   at: number;
@@ -379,10 +552,25 @@ declare class AudioBuses {
   * Bounded (200) — a game running for an hour must not grow a log.
   */
   private readonly events;
+  /**
+  * EVERY node that has sounded, ever — a set of paths, not a window.
+  *
+  * `recent()` is bounded at 200, which is right for a log and wrong for the
+  * question "is this AudioPlayer wired?". A game with one sound firing about
+  * three times a second overflows the window inside a minute, so a 60-second
+  * playtest read the tail and reported correctly-wired feedback as never
+  * fired. This grows with the SCENE, not with the run — which is true only
+  * because it records the AUTHORED path: a clone's own path is new every
+  * spawn, and recording those grew the set by one entry per enemy, forever,
+  * in every shipped game. See `Node.wiringPath`.
+  */
+  private readonly sourcePaths;
   /** @internal Called by the players; games read `recent()`. */
   record(event: AudioEvent): void;
   /** The last `limit` sounds, oldest first. */
   recent(limit?: number): AudioEvent[];
+  /** Every node path that has sounded since the last `clearLog()`. */
+  sources(): string[];
   /** How many times a preset/clip/track sounded — the assertion you want. */
   countOf(name: string): number;
   /** Forget what has sounded so far (between scenes, or between assertions). */
@@ -391,6 +579,7 @@ declare class AudioBuses {
   private _sfx;
   private _music;
   private _muted;
+  private _suspended;
   get master(): number;
   set master(v: number);
   get sfx(): number;
@@ -399,6 +588,21 @@ declare class AudioBuses {
   set music(v: number);
   get muted(): boolean;
   set muted(v: boolean);
+  /**
+  * Silence the game WITHOUT it counting as the player muting it.
+  *
+  * `pause-when-hidden` set `muted = true` when the tab went away, which fires
+  * `changed`, which `Settings.bindAudio` persists. Close the tab while it is
+  * hidden and `muted: true` is on disk: EVERY later session of that game boots
+  * silent, and no shipped starter has an in-game way back.
+  *
+  * A suspension is the engine's, not the player's. It never touches `muted`,
+  * so nothing persists it and unsuspending cannot turn the sound back on for
+  * someone who turned it off.
+  */
+  suspend(on: boolean): void;
+  /** Is the engine holding the sound off (hidden tab), as against the player? */
+  get suspended(): boolean;
   /** Final gain for a sound on `bus` with its own `sourceVolume` (all clamped). */
   effectiveVolume(bus: BusName, sourceVolume: number): number;
   /** Clamp + finite-guard a new value; emit only on a real change. */
@@ -434,6 +638,14 @@ interface MusicTrack {
   * Optional so an existing custom backend keeps compiling.
   */
   playhead?(): number | null;
+  /**
+  * Advance a track that has no clock of its own, by the engine's real dt.
+  *
+  * Optional, and the WebAudio backend does not implement it: an element's own
+  * `currentTime` is the authority whenever there is one. The silent backend
+  * does, so a game charted to a soundtrack has a playhead in the verify VM.
+  */
+  tick?(dt: number): void;
 }
 /** Backend that mints {@link MusicTrack}s — WebAudio-backed in the browser. */
 interface MusicBackend {
@@ -792,10 +1004,24 @@ declare class SfxEngine {
   * The AUDIO clock, in seconds — the one a sound is actually scheduled
   * against, and the only clock that does not drift relative to what you hear.
   *
-  * `0` headless and before the first sound, since there is no context yet.
   * Schedule with a lead: `sfx.play(params, 1, { when: sfx.now + 0.08 })`.
+  *
+  * With no AudioContext — headless, and before the first sound — it is the
+  * engine's own real elapsed time instead of a frozen `0`. A constant made the
+  * documented lookahead scheduler queue the notes inside the first 80 ms and
+  * then nothing ever again: measured on a 21-beat metronome in the verify VM,
+  * **1 of 21 beats**, with no error and no warning. The silent clock runs so
+  * the schedule is reachable; nothing sounds either way.
   */
   get now(): number;
+  /** The clock `now` reports when there is no context to ask. */
+  private silentNow;
+  /**
+  * @internal Advance the silent clock — the engine calls this every frame with
+  * the REAL dt, beside `music.tick`, because the audio does not slow down when
+  * the game does.
+  */
+  _tick(dt: number): void;
   /**
   * Play a preset at `gain` (0..1, already bus-multiplied by the caller). Each
   * call spawns its own source so rapid repeats overlap instead of cutting off.
@@ -836,6 +1062,12 @@ interface EffectEvent {
   name: string;
   /** Node path, or `engine` for the screen-wide ones. */
   from: string;
+  /**
+  * The AUTHORED node this stands for — `from` with a clone's auto-renamed
+  * ancestors put back (`/Game/Foe37/Fx` → `/Game/Foe/Fx`). Absent = same as
+  * `from`. Only `sources()` reads it; the log keeps the live path.
+  */
+  wiredAs?: string;
   /** Particles in the burst, shake magnitude, seconds frozen — the amount. */
   amount: number;
   /** `engine.time` when it fired, in seconds. */
@@ -843,8 +1075,19 @@ interface EffectEvent {
 }
 declare class EffectLog {
   private readonly events;
+  /**
+  * EVERY node that has fired, ever — a set of paths, not a window. See
+  * `AudioBuses.sources`: 200 entries is a log, and "is this emitter wired?"
+  * needs the whole run.
+  *
+  * AUTHORED paths, so it is bounded by the scene: a wave of forty enemies is
+  * one emitter fired forty times. See `Node.wiringPath`.
+  */
+  private readonly sourcePaths;
   /** @internal Called by the effects themselves; games read `recent()`. */
   record(event: EffectEvent): void;
+  /** Every node path that has fired an effect since the last `clearLog()`. */
+  sources(): string[];
   /** The last `limit` effects, oldest first. */
   recent(limit?: number): EffectEvent[];
   /** How many times an effect with this name fired (`explosion`, `#ff0000`). */
@@ -856,18 +1099,24 @@ declare class EffectLog {
 }
 //#endregion
 //#region src/core/input.d.ts
-/**
-* Declarative input from scene JSON `input{}` — DOM-free logic (feed key state
-* via `handleKey`, or wire a browser with `attachKeyboard(window)`).
-*
-* Convention: vector2 follows the 2D y-down space (up = -y). `justPressed` /
-* `justReleased` are one-frame edges, settled by the Engine each tick.
-*/
 declare class InputMap {
   private readonly actions;
   private readonly down;
   private readonly pressedEdge;
   private readonly releasedEdge;
+  private readonly pressedEdgeFixed;
+  private readonly releasedEdgeFixed;
+  /** Which pass is asking. Set by the Engine around each phase. */
+  private phase;
+  /**
+  * Actions something has actually ASKED about since this scene loaded.
+  *
+  * Recorded in the four read methods only — never in `get`/`button`, because
+  * `pressAction` goes through those, and the tool that reports this list is
+  * the same tool that injects presses. Marking an action read because a
+  * playtester pressed it would make the check answer its own question.
+  */
+  private readonly queried;
   private detach;
   /** Load (or extend with) scene-JSON action declarations. Hard-validates shape. */
   declare(decls: Record<string, unknown>): void;
@@ -878,7 +1127,9 @@ declare class InputMap {
   * This is what a click-driven game asks for. `pointerDelta()` answers "how far
   * did the mouse move" — the mouse-look question — and for a whole class of
   * genres that is the wrong question and the only one the engine could answer.
-  * Pair it with `renderer.pick(x, y)` to get the node under the cursor.
+  * Pair it with `engine.pickAt(x, y)` for the node under the cursor and
+  * `engine.pointerWorld()` for the place — both reachable from a Behavior,
+  * which `renderer.pick` / `renderer.worldFromScreen` are not.
   */
   pointerPosition(): {
     x: number;
@@ -895,6 +1146,9 @@ declare class InputMap {
   private readonly injectedDown;
   private readonly injectedPressed;
   private readonly injectedReleased;
+  /** The fixed pass's view of the injected edges — see `pressedEdgeFixed`. */
+  private readonly injectedPressedFixed;
+  private readonly injectedReleasedFixed;
   private readonly injectedPressedNext;
   private readonly injectedReleasedNext;
   /** True between the start of a frame's update pass and `endFrame()`. */
@@ -916,6 +1170,20 @@ declare class InputMap {
     name: string;
     type: "button" | "vector2";
   }>;
+  /**
+  * Declared actions NOTHING has read — a control the scene promises and no
+  * code implements.
+  *
+  * `village-quest-3d` declared `"restart": { "keys": ["KeyR"] }` and not one
+  * line read it, so the game's own control list said R restarts and R did
+  * nothing. The scene is where controls are DECLARED; whether anything
+  * consumes one is invisible there, and a `grep` for the name cannot tell an
+  * engine node's read from a dead string.
+  *
+  * The list is advisory, like `behaviorsWithoutSave`: an action polled only in
+  * a state a run never reached is on it honestly. Read it, do not gate on it.
+  */
+  unreadActions(): string[];
   pressAction(action: string): void;
   /** Release an injected button action (yields one justReleased frame). */
   releaseAction(action: string): void;
@@ -940,7 +1208,21 @@ declare class InputMap {
   private dy;
   private wheel;
   /** Mouse buttons feed the same code space as keys: Mouse0/Mouse1/Mouse2. */
-  handleMouseButton(button: number, isDown: boolean): void;
+  /**
+  * A mouse/pen/finger button.
+  *
+  * `kind` matters on the way UP: a finger that lifts CEASES TO EXIST, while a
+  * cursor stays where you left it. Without it the last-tapped node kept
+  * `hovering: true` for the rest of the session — a permanently highlighted
+  * tile, mole or card on every phone, on a device with no hover at all.
+  *
+  * The position is cleared at `endFrame`, not here: `Clickable` fires on the
+  * release over the node the press started on, so a pointer cleared in the
+  * same frame takes the click with it.
+  */
+  handleMouseButton(button: number, isDown: boolean, kind?: "mouse" | "touch"): void;
+  /** A finger came up this frame — see `endFrame`. */
+  private touchLifted;
   /** Accumulate look deltas (movementX/Y under pointer lock, else move deltas). */
   handlePointerMove(dx: number, dy: number): void;
   handleWheel(deltaY: number): void;
@@ -980,11 +1262,7 @@ declare class InputMap {
   * Poll the browser Gamepad API every frame (the first connected pad).
   * Wire once at boot: `engine.input.attachGamepad(engine)`. Headless no-op.
   */
-  attachGamepad(engine: {
-    updated: {
-      connect(fn: () => void): () => void;
-    };
-  }): () => void;
+  attachGamepad(_engine?: unknown): () => void;
   /**
   * Pointer input from a mouse, a FINGER or a pen — one code path.
   *
@@ -1050,9 +1328,38 @@ declare class InputMap {
   };
   /** Consume one-frame edges. The Engine calls this at the end of every tick. */
   endFrame(): void;
-  /** @internal The engine marks the update phase, so an edge injected inside
-  *  it can be held for the next frame. */
+  /**
+  * @internal Start a tick: poll the devices that have no events of their own,
+  * then open the frame.
+  *
+  * The gamepad used to be polled from an `engine.updated` handler — AFTER both
+  * passes, and nine lines before `endFrame()` cleared what it had just
+  * produced. So a pad's press edge was created and destroyed inside one tick
+  * and `justPressed('jump')` was never true anywhere in the tree:
+  *
+  *   PAD 8 taps -> update() saw justPressed 0, justReleased 0, isPressed 32
+  *   KEY 8 taps -> update() saw justPressed 8, justReleased 8
+  *
+  * A controller could hold but could never press: 0.00 px of jump on Pad0
+  * against 74.33 px on Space, and `HudLayer.focusNavigation` — the built-in
+  * controller-menu feature — moved focus zero times. Polling HERE puts a pad
+  * where a keyboard already is: an edge that exists before the frame opens.
+  */
   beginFrame(): void;
+  /** Devices with no events of their own, polled at the start of every tick. */
+  private readonly pollers;
+  /**
+  * @internal The fixed pass is starting. Edges it has not seen yet are live.
+  */
+  beginFixedStep(): void;
+  /**
+  * @internal The fixed pass is done for this tick — it has now seen the edges.
+  *
+  * Called after the FIRST fixed step only, so an edge reaches `fixedUpdate`
+  * exactly once however many steps a tick runs. A tick that runs none leaves
+  * this view untouched and the next one delivers it.
+  */
+  endFixedStep(): void;
   /**
   * Drop all action declarations and injected action state (physical key
   * state is kept). The Engine calls this on setScene so keybinds never
@@ -1190,6 +1497,19 @@ interface RayHit {
   distance: number;
   normal: number[];
   node: Node | null;
+  /**
+  * WHERE the ray landed, in world units — `origin + dir * distance`.
+  *
+  * The thing every caller actually wants: an impact effect, a decal, a tower
+  * dropped on uneven ground, a waypoint. `incanto-web-integration.md` sends
+  * you here for exactly that case — "`worldFromScreen` lands it on the ground
+  * plane, and `rayFromScreen` hands you the ray when the ground is terrain or
+  * a stack of crates" — and then the hit carried a distance and left the
+  * arithmetic, and the normalization it depends on, to the caller.
+  *
+  * 2 numbers in 2D (pixels), 3 in 3D (metres), like every other position.
+  */
+  point: number[];
 }
 /**
 * The physics world, as core knows it — the QUERIES a behavior asks, with no
@@ -1208,6 +1528,10 @@ interface PhysicsQuery {
   /**
   * Fire a ray and report the first thing it hits, or `null`.
   *
+  * `dir` may be any length — `target - eye` is the usual spelling — and is
+  * normalized, so `distance` and `maxLen` are both in world units (px / m)
+  * rather than multiples of `dir`. A zero-length direction returns `null`.
+  *
   * Sensors never block a ray. Pass `exclude` for the body you are casting from
   * — a ray starting inside its own collider hits itself at distance 0.
   */
@@ -1215,16 +1539,36 @@ interface PhysicsQuery {
     staticOnly?: boolean;
   }): RayHit | null;
   /**
-  * A THICK ray (sphere sweep) — 3D only, hence optional. Use it where skimming
-  * matters: a thin ray that passes 10 cm over a wall reports "clear" while the
-  * wall still fills the frame.
+  * A THICK ray — a sphere sweep in 3D, a circle sweep in 2D.
+  *
+  * Use it where skimming matters: a thin ray that passes 10 cm over a wall
+  * reports "clear" while the wall still fills the frame, and in 2D a shot can
+  * thread a one-pixel gap between two floor tiles. Same filters and the same
+  * direction contract as `castRay`; `distance` is the travel of the CENTRE.
+  *
+  * It was 3D-only, and therefore optional here, until 0.70.
   */
-  castSphere?(origin: readonly number[], dir: readonly number[], radius: number, maxLen: number, exclude?: Node, opts?: {
+  castSphere(origin: readonly number[], dir: readonly number[], radius: number, maxLen: number, exclude?: Node, opts?: {
     staticOnly?: boolean;
   }): {
     distance: number;
     node: Node | null;
   } | null;
+  /**
+  * How fast this body is actually moving, from the SOLVER.
+  *
+  * 2D answers in px/s (y-down), 3D in m/s (y-up). `linearVelocity` on the node
+  * is written back once per step, so a behavior reading it from inside
+  * `fixedUpdate` — after a collision, before the write-back — sees the value
+  * from BEFORE the impact, which is exactly when a game wants to know how hard
+  * it hit something.
+  */
+  velocityOf(node: Node): number[];
+  /**
+  * Mass the solver actually uses — collider-derived unless the body overrides
+  * it. Scale a push by this rather than by the authored `mass` prop.
+  */
+  massOf(node: Node): number;
   /** Tear the world down and detach from the engine. */
   dispose(): void;
 }
@@ -1246,6 +1590,26 @@ interface SaveStore {
   /** Wipe THIS namespace only. */
   clear(): void;
   /**
+  * Every key this namespace holds.
+  *
+  * Optional, so a store a game injected itself keeps compiling. Without it,
+  * the slot layer could only find saves through its own INDEX — and one
+  * corrupt byte in that index made every intact save on the machine
+  * unreachable and then orphaned them for good on the next write. A store
+  * that can be enumerated can be rebuilt.
+  */
+  keys?(): string[];
+  /**
+  * Keys whose stored text is not JSON any more.
+  *
+  * `parse` swallows a syntax error and answers with the fallback — the
+  * RECOVERY is deliberate ("the fallback beats a crash"), the silence was not.
+  * A truncated slot from a power cut is indistinguishable from a slot that was
+  * never written, and a load menu that shows one fewer save than the player
+  * remembers is the worst thing a save system can do quietly.
+  */
+  corrupt?(): string[];
+  /**
   * Does a write here survive the page closing?
   *
   * `false` means this store is a Map that lives as long as the tab does — a
@@ -1304,6 +1668,46 @@ interface RestoreReport {
   expected: number;
   /** Authored nodes the save says the run consumed, and that were freed again. */
   freed: number;
+  /**
+  * Behaviors whose `deserialize` THREW, and what it said.
+  *
+  * They are in `skipped` too, because they took nothing — but a save this
+  * build cannot read and a node that has no `deserialize` at all are different
+  * problems, and `skipped` alone said both.
+  */
+  refused: string[];
+  /**
+  * Behaviors that took their state and then threw out of `announce()`.
+  *
+  * The state IS restored; the SCREEN was not told. That is the difference
+  * between a correct save and a HUD showing zeros over a 1400-coin run, and it
+  * used to be a bare `catch {}` — `restored: 2, expected: 2`, no log, no
+  * error.
+  */
+  unannounced: string[];
+  /**
+  * Authored nodes THIS tree already consumed that the save says should still
+  * be there — the tell that the scene was PLAYED before the restore.
+  *
+  * `#freed` can take nodes away and nothing puts them back, so restoring into
+  * a live scene (a pause-menu Load, a slot menu, the canonical
+  * death→reload-checkpoint wiring) leaves this run's collectibles deleted and
+  * reports fully green. Measured on 3 gems worth 10 with `scoreToWin: 30`:
+  *
+  * ```
+  * CONTROL restartScene then restore → score 10, gems [Gem2,Gem3] → 30, won TRUE
+  * death wired straight to restore   → score 10, gems [Gem3]      → 20, won FALSE
+  * ```
+  *
+  * …and the next autosave writes the hybrid back to the slot, so the
+  * unwinnable run survives a page reload. Every other field is identical
+  * between the two, which is why nothing could tell them apart.
+  *
+  * A node that freed ITSELF on a timer between load and restore lands here
+  * too, which is why this is reported rather than thrown: the caller knows
+  * which of its nodes are transient and the engine does not.
+  */
+  stale: string[];
 }
 /**
 * Every behavior in the tree that has something to say, by uid.
@@ -1316,24 +1720,14 @@ interface RestoreReport {
 * cannot be given back. The editor assigns a uid to every node it touches; a
 * hand-written scene may not have.
 */
-declare function captureBehaviors(root: Node, source?: JsonValue): {
+declare function captureBehaviors(root: Node, source?: JsonValue, authored?: ReadonlySet<string>): {
   state: BehaviorState; /** Paths of nodes that had state to save and no uid to save it under. */
   unaddressable: string[]; /** Behaviors in this tree that have something to save — addressable or not. */
   saveable: number; /** Authored nodes this run consumed that the `#freed` ledger cannot record. */
-  unrecordable: string[];
+  unrecordable: string[]; /** Behaviors whose `serialize()` THREW — their state is not in `state`. */
+  failed: string[];
 };
-/**
-* 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.
-*/
-declare function restoreBehaviors(root: Node, state: BehaviorState): RestoreReport;
+declare function restoreBehaviors(root: Node, state: BehaviorState, authored?: ReadonlySet<string>): RestoreReport;
 /**
 * The slot layer: a named list of saves over the existing store.
 *
@@ -1352,8 +1746,32 @@ declare class SaveSlots {
   * be there tomorrow.
   */
   get persistent(): boolean;
+  /**
+  * The slot index — rebuilt from the store when it cannot be trusted.
+  *
+  * `store.get(INDEX_KEY, [])` falls back to an EMPTY LIST when the stored text
+  * is not JSON, so one corrupt byte in a derived index emptied the whole load
+  * menu while every save on the machine was still perfectly readable — and the
+  * next `write()` then set the index to `[newId]`, orphaning them for good.
+  * The index is a cache of what the store holds, and the store can be asked.
+  */
+  private ids;
   /** Slot ids that have a save, newest first. */
   list(): string[];
+  /**
+  * Slots that EXIST and cannot be read — a truncated write, or a save from a
+  * build that predates this one.
+  *
+  * `read()` answers `null` for both of those and for "no such slot", and
+  * `list()` filters them out, so a save the player made silently disappeared
+  * from the menu. A load screen should render "1 save could not be read"
+  * rather than one fewer row, which is why this is a list and not a warning.
+  */
+  problems(): Array<{
+    id: string;
+    why: "corrupt" | "unreadable";
+  }>;
+  private isCorrupt;
   /** Every slot with its contents — what a load menu actually renders. */
   all(): Array<SaveSlot & {
     id: string;
@@ -1432,8 +1850,32 @@ declare class Scene {
   /** The full source JSON this scene was loaded from — `restartScene` fuel. */
   readonly source: SceneJson;
   constructor(source: SceneJson, root: Node, tree: SceneTree);
+  /**
+  * Every uid this scene had the moment it finished loading.
+  *
+  * The `#freed` ledger's left-hand side: a uid in here that is not in the live
+  * tree is a node this run consumed. Includes nodes inside expanded
+  * `instance:` sub-scenes, which the scene FILE cannot show.
+  */
+  readonly authoredUids: ReadonlySet<string>;
   /** Lossless export. Note: expanded sub-scene instances serialize as full trees in M1. */
   toJSON(): SceneJson;
+  /**
+  * The connections whose BOTH ENDS still exist in the tree being written.
+  *
+  * `toJSON` is what `incanto-play`'s `capture` writes — "your screenshot", the
+  * skills call it — and it wrote every connection the file declared, including
+  * ones pointing at nodes the run had freed. The result was a scene the engine
+  * REFUSES to load:
+  *
+  *   DANGLING_CONNECTION: connection to 'Coin' resolves nowhere
+  *
+  * so a captured game with any collectible in it produced a file no tool could
+  * read back. Dropping a wire whose node is gone is what the tree already did
+  * when it freed the node; this makes the written file say the same thing.
+  */
+  private liveConnections;
+  private resolves;
 }
 //#endregion
 //#region src/core/settings.d.ts
@@ -1817,6 +2259,53 @@ declare class Engine {
   * is a hitch, where the alternative was a game that never simulated at all.
   */
   ensurePhysics(): Promise<void>;
+  /**
+  * The seed this engine was built with — game logic draws from `rng`, and
+  * anything DECORATIVE derives its own stream from this instead.
+  *
+  * A particle emitter used to draw from `rng`, and it spawns a number of
+  * particles that depends on `dt`. Measured on the same scene and seed, the
+  * same simulated two seconds, comparing the world's own draws by update
+  * index:
+  *
+  * ```
+  * particles off:  60fps and 30fps identical
+  * particles ON :  they diverge at update 2
+  * ```
+  *
+  * So a purely visual effect changed the game's random decisions, and the
+  * PLAYER'S FRAME RATE decided them. Derived streams stay reproducible for
+  * replays and screenshots without spending the one the game reads.
+  */
+  readonly seed: number;
+  /**
+  * How to resolve an `instance:` sub-scene, remembered from the boot load.
+  *
+  * `loadScene(json, { engine, resolveScene })` records it here, so the paths
+  * that RELOAD — `restartScene`, `goToScene`, a game-over restart key — can
+  * pass it back. Without that a game using the documented sub-scenes booted
+  * fine and threw `UNRESOLVED_INSTANCE` on its first restart.
+  */
+  resolveScene?: (path: string) => SceneJson;
+  /**
+  * How the current scene was LOADED, for the rebuilds that happen later.
+  *
+  * `duplicateNode` — every `Spawner`, every `NetworkSpawner`, every clone a
+  * game makes — rebuilds a subtree from scene JSON long after `loadScene`
+  * returned, and it did so with no options at all. Under
+  * `stubMissingBehaviors` (how EVERY headless check runs a game whose scripts
+  * are TypeScript it cannot import) the first spawn met the real registry and
+  * threw `UNKNOWN_BEHAVIOR` out of `update`, disabling the spawner for the
+  * rest of the run — a wave game reported with no waves and nothing saying
+  * why.
+  *
+  * Recorded here for the same reason as `resolveScene` above: the engine
+  * outlives the call, and the rebuild paths can reach it.
+  */
+  loadOptions: {
+    stubMissingBehaviors?: boolean;
+    stubAllBehaviors?: boolean;
+  };
   /** Seeded randomness for game logic (deterministic when `seed` is set). */
   readonly rng: Rng;
   /** The engine log channel (debug overlay + headless harness tail this). */
@@ -1831,6 +2320,60 @@ declare class Engine {
   * and cleared on dispose; null when nothing renders (headless).
   */
   picker: ((x: number, y: number) => Node | null) | null;
+  /**
+  * Screen pixel → a point in the WORLD, when a renderer has offered one.
+  *
+  * `picker` answers "which node"; this answers "which place", and a mouse game
+  * needs both — drag-and-launch, drop a tower on the map, steer a cursor unit,
+  * draw the slingshot band. The conversion has always existed
+  * (`Renderer2D.worldFromScreen` / `Renderer3D.worldFromScreen`) and lived
+  * only on the renderer, so a Behavior — which holds a node and an engine and
+  * nothing else — could not call it. Its two workarounds were both forbidden:
+  * stash the renderer in a module global, or hand-roll the projection the 2D
+  * skill says in so many words not to hand-roll.
+  *
+  * The answer is the scene's own units and shape: `[x, y]` in 2D (design
+  * pixels), `[x, y, z]` on the ground plane in 3D — the same array a node's
+  * `position` is, so it goes straight back into one.
+  *
+  * Instance-scoped, set by the renderer on construction and cleared on
+  * dispose. Headless a harness may install a geometric one; null when nothing
+  * has.
+  */
+  toWorld: ((x: number, y: number) => number[] | null) | null;
+  /**
+  * A world point → the screen pixel drawing it. The inverse of `toWorld`, for
+  * pinning DOM to a node or placing a marker over one.
+  *
+  * `behind` is true when the point is behind the camera (3D); a 2D renderer
+  * always reports false.
+  */
+  toScreen: ((world: readonly number[]) => {
+    x: number;
+    y: number;
+    behind: boolean;
+  } | null) | null;
+  /**
+  * Where the cursor is in the world, or null.
+  *
+  * The two-line dance every mouse game writes — read the pointer, convert it —
+  * with the two ways it goes wrong already handled: a pointer nothing has
+  * moved yet is null rather than the origin, and no converter is null rather
+  * than a guess.
+  */
+  /**
+  * Screen pixel → a ray into the world, when a renderer has offered one.
+  *
+  * `toWorld` lands on a plane; this is the general form, and it is what a shot
+  * aimed at what the cursor is OVER needs: feed it straight to
+  * `engine.physics.castRay(origin, dir, …)`. 3D only — a 2D renderer installs
+  * nothing here, since a 2D world has no depth to cast into.
+  */
+  screenRay: ((x: number, y: number) => {
+    origin: number[];
+    dir: number[];
+  } | null) | null;
+  pointerWorld(): number[] | null;
   /** Frames the engine has stepped — monotonic, and the pick cache's key. */
   frameNumber: number;
   /** @internal frame number + answer, so N Clickables cost ONE raycast. */
@@ -1911,7 +2454,24 @@ declare class Engine {
   * (hit-stop / pause). Scales BOTH variable and fixed updates — physics,
   * timers, behaviors all breathe together. See `gameplay` `hitStop()`.
   */
-  timeScale: number;
+  get timeScale(): number;
+  set timeScale(v: number);
+  private _timeScale;
+  private _timeScaleWrites;
+  /**
+  * How many times anyone has written `timeScale` — the clock's ownership tag.
+  *
+  * A temporary freeze cannot tell its own 0 from somebody else's by VALUE.
+  * `hitStop(engine)` then `flow.gameOver()` is the ordinary killing blow, and
+  * both set 0; the freeze then wrote its captured scale back five frames later
+  * and the world started moving again behind a sticky GAME OVER banner —
+  * enemies walking, timers running, the player watching their corpse get shot.
+  *
+  * A counter answers the question the value cannot: *has anyone touched this
+  * since I did?* Cheap (one increment per write, and writes are rare) and it
+  * needs no registry of who holds what.
+  */
+  get timeScaleWrites(): number;
   /**
   * The node the dev overlay has selected (renderers draw its bounding box
   * as an orange outline in the game view so you can SEE what you picked).
@@ -1930,6 +2490,29 @@ declare class Engine {
   /** Elapsed REAL time in seconds since the scene started (ignores timeScale) —
   *  UI animations that must keep moving during slow-mo/pause read this. */
   get unscaledTime(): number;
+  /**
+  * THIS frame's dt in real seconds — the one a paused game still gets.
+  *
+  * `update(dt)` receives the SCALED dt, which is right for anything that is
+  * part of the simulation and wrong for everything that is a presentation of
+  * it. At `timeScale = 0` — which is what `GameFlow.pause()` and, by default,
+  * `gameOver()` set — a scaled countdown does not count:
+  *
+  *   a timed UiBanner still up when the player dies never expires, so the
+  *     flow's own sticky GAME OVER banner is queued behind it and NEVER
+  *     PAINTED — the ending screen shows the last wave toast, forever
+  *   a live CameraShake never settles: `t -= dt` is a no-op while the rest of
+  *     update() re-rolls a full-magnitude offset every rendered frame, and
+  *     with FollowCamera's smoothing that is an unbounded random walk
+  *   a remote player's interpolation stops, so everyone else is a statue while
+  *     their real positions keep arriving
+  *
+  * `hitStop`, `AudioPlayer` and `music.tick` already use the real clock for
+  * exactly this reason. This is the same clock, per frame, so a countdown can
+  * use it without reading `unscaledTime` twice and subtracting.
+  */
+  get unscaledDelta(): number;
+  private _unscaledDelta;
   constructor(opts?: EngineOptions);
   get scene(): Scene | null;
   /** Replace the active scene. The previous scene's root is freed. */
@@ -1970,6 +2553,22 @@ declare class Engine {
   private reportFrameError;
   /** @internal A node quarantined itself; count it for `stats().errors`. */
   _nodeErrored(_node: unknown): void;
+  /**
+  * @internal Something OUTSIDE a frame failed — a replication send that
+  * rejected, a transport that refused. Count it and say it once.
+  *
+  * `stats().errors` is what every harness in the ecosystem ends with, and it
+  * only ever counted things that threw INSIDE a frame. A multiplayer client
+  * whose socket died kept running perfectly on its own screen while every
+  * other player watched it frozen, and `errors: 0` with an empty log said the
+  * game was fine. Repeats are counted and not re-printed, for the reason
+  * `reportFrameError` gives: sixty identical traces a second is how you lose
+  * the first one.
+  */
+  _asyncFailed(what: string, error: unknown): void;
+  private lastAsyncError;
+  /** Re-entrancy guard for `setScene` — an exit hook can now reach the engine. */
+  private swapping;
   private errorCount;
   private lastFrameError;
   /**
@@ -1993,6 +2592,14 @@ declare class Engine {
   * core/save-slots.ts for why a save carries state rather than a tree
   * snapshot.
   */
+  /**
+  * Behaviors whose `serialize()` threw during the LAST `captureState()`.
+  *
+  * A write path that cannot see part of the run must not overwrite the slot
+  * that still can — `SavePoint.save()` reads this and refuses.
+  */
+  get lastCaptureFailures(): readonly string[];
+  private _captureFailures;
   captureState(): BehaviorState;
   /** Give it back, after the scene is loaded and onReady has run. */
   restoreState(state: BehaviorState): RestoreReport;
@@ -2078,6 +2685,14 @@ interface PropRange {
   /** `min` is a bound the value must EXCEED, not reach (`targetHeight > 0`). */
   exclusiveMin?: boolean;
   /**
+  * `max` is a bound the value must stay UNDER, not reach.
+  *
+  * `Camera3D.fov` is the case: 180 is a legal number and a degenerate
+  * frustum — the whole world collapses to a point at screen centre and the
+  * framing instrument still calls it on screen.
+  */
+  exclusiveMax?: boolean;
+  /**
   * Values outside the range that mean something anyway.
   *
   * `metalness: -1` is "keep whatever the GLB authored" — a real value with a
@@ -2094,6 +2709,23 @@ interface PropDef {
   * dropdowns and the generated JSON-Schema enum — keep it exhaustive. */
   options?: readonly string[];
   /**
+  * Every JSON kind this prop accepts, when it accepts more than the default's.
+  * MUST contain the default's own kind — `registerNode` refuses a list that
+  * does not, because that default would be unwritable in a scene.
+  *
+  * A prop typed `boolean | JsonObject` in TypeScript is one kind to the loader:
+  * whatever the default happens to be. `Water3D.underwater` (default `true`)
+  * and `Flowers3D.density` (default `'sparse'`) both wrote a `validateJson`
+  * branch for the other half — checking `underwater.visibility`, budgeting
+  * plants/m² — and neither branch could be reached from a scene, because the
+  * kind gate runs first. Both halves were in the skills; only one loaded.
+  *
+  * When a value's kind is not the default's, the kind gate is all this file
+  * checks: `options`, `range` and the array template describe the DEFAULT's
+  * kind, so the node's own `validateJson` owns the other half's shape.
+  */
+  kinds?: readonly JsonKind[];
+  /**
   * This prop holds a NODE PATH (`%Unique`, `/Absolute/From/Root`, or one
   * relative to the node that owns the prop) resolved with `getNodeOrNull`.
   *
@@ -2135,7 +2767,14 @@ interface PropDef {
   */
   range?: PropRange;
   asset?: {
-    /** The `assets{}` entry `type` a `$ref` here must point at. */kind: "texture" | "spritesheet" | "model" | "animation";
+    /** The `assets{}` entry `type` a `$ref` here must point at. */
+    /**
+    * `audio` has no `assets{}` entry type — `AudioPlayer.src` takes a url and
+    * only a url. It is declared anyway so the prop is VISIBLE to everything
+    * that walks asset props (the editor's picker, `incanto-check`'s
+    * missing-file warning), which is the whole point of the spec.
+    */
+    kind: "texture" | "spritesheet" | "model" | "animation" | "audio";
     /**
     * A value that is not a `$ref` is an error.
     *
@@ -2144,6 +2783,26 @@ interface PropDef {
     * GLB (`ModelInstance3D.animation`).
     */
     refOnly?: boolean;
+    /**
+    * A `$ref` here is an error — this prop takes a raw URL.
+    *
+    * The 3D texture props declared no `asset` spec at all, so
+    * `validateAssetRefs` never looked at them: `"texture": "$hero"` — the
+    * spelling the 2D sibling's own error message teaches — was certified valid
+    * at author time and then fetched as a relative path, 404ing at runtime
+    * with a sprite that simply never appears.
+    */
+    urlOnly?: boolean;
+    /**
+    * The prop is an OBJECT whose values are the references, not a string.
+    *
+    * `CharacterController3D.animations` is the zero-TypeScript way to animate
+    * a character — `{ "idle": "$idle", "run": "$run" }` — and every one of
+    * those values is an asset ref that nothing validated. A typo there is a
+    * character that never animates, with no error anywhere, which is the exact
+    * class of silence the hard-error rule exists to prevent.
+    */
+    mapValues?: boolean;
   };
   /**
   * For an OBJECT-valued prop shaped as a tagged union — `collider`, whose
@@ -2246,7 +2905,17 @@ declare abstract class Behavior {
   static signals?: readonly string[];
   /** The node this behavior is attached to (assigned by the loader). */
   node: Node;
-  /** The running engine, reached through the scene tree. */
+  /**
+  * The running engine, reached through the scene tree.
+  *
+  * The message names the FIX, because there is one and it is one word. Reading
+  * this in `onReady` is the documented pattern — `Wander` draws its first
+  * heading there — and `onReady` runs during `loadScene`, before the tree
+  * belongs to anyone. Every boot path in the engine passes `{ engine }` for
+  * exactly that reason; the two-step boot the skills print did not, so a scene
+  * with one wandering critter in it threw at load and the error said only that
+  * something was not attached.
+  */
   get engine(): Engine;
   /** Shortcut for `this.engine.input`. */
   get input(): InputMap;
@@ -2310,6 +2979,35 @@ declare abstract class Behavior {
   * quietly ignoring a field you renamed is usually the better answer.
   */
   deserialize?(data: JsonValue): void;
+  /**
+  * Tell the world what you were just handed — the seventh hook, and the one
+  * that made "Continue" show the right numbers.
+  *
+  * `deserialize` writes fields. A HUD is wired to SIGNALS (`scoreChanged`,
+  * `healthChanged`, `changed`), because that is what `incanto-hud.md` teaches
+  * and what the editor can wire. Nothing emitted them after a restore, so a
+  * Continue boot measured like this:
+  *
+  * ```
+  * HUD    score="0"    hp=100/100  gems="0"
+  * TRUTH  score=1400   hp=38       gems=7
+  * ```
+  *
+  * with `errors: 0`, an empty log, and a restore report of
+  * `{missing:[], skipped:[], restored:2, expected:2}` — every instrument
+  * green over a screen showing a fresh start. Health was the worst of the
+  * three: its setter is private and early-returns when unchanged, so nothing
+  * a game could call would repaint the bar; it read 100 at 38 HP until the
+  * next hit teleported it to 37.
+  *
+  * `restoreBehaviors` calls this once, after every `deserialize` in the pass,
+  * so a handler that reads a sibling sees restored values there too.
+  *
+  * Emit only what DISPLAYS. Not `died`, not `won`, not `levelUp` — a save is
+  * being read, nothing just happened, and re-firing an outcome signal on load
+  * is how a Continue lands straight on the game-over screen.
+  */
+  announce?(): void;
 }
 /** Explicit registration — never an import side effect (tree-shaking safety). */
 declare function registerBehavior(name: string, ctor: BehaviorCtor, opts?: {