incanto 0.7.0 → 0.8.0

package/dist/debug.js

@@ -328,6 +328,7 @@ var DebugOverlay = class {
 		}
 	}
 	dispose() {
+		this.engine.debugSelection = null;
 		this.setConsoleCapture(false);
 		for (const cleanup of this.cleanups) cleanup();
 		for (const id of [...this.panels.keys()]) this.close(id);
@@ -471,6 +472,7 @@ var DebugOverlay = class {
 			}
 			row.addEventListener("click", () => {
 				this.selected = node;
+				this.engine.debugSelection = node;
 				this.open("inspector");
 				this.renderExplorer();
 				this.renderInspector();
@@ -496,6 +498,7 @@ var DebugOverlay = class {
 		let node = this.selected;
 		if (node && node.tree === null) {
 			this.selected = null;
+			this.engine.debugSelection = null;
 			node = null;
 		}
 		if (!node) {

package/dist/{errors-BMFaY68Q.d.ts → errors-1dXlIwoR.d.ts}

@@ -1,3 +1,9 @@
+import { s as JsonObject } from "./schema-CcoWb32N.js";
+
+//#region src/core/audit.d.ts
+/** Human-readable warnings (empty = clean). Pure JSON walk, no registry. */
+declare function auditScene(scene: JsonObject): string[];
+//#endregion
 //#region src/core/errors.d.ts
 /**
 * Stable error codes for every hard failure in the engine.
@@ -30,4 +36,4 @@ declare class IncantoError extends Error {
   constructor(code: IncantoErrorCode, message: string, details?: IncantoErrorDetails);
 }
 //#endregion
-export { IncantoErrorCode as n, IncantoErrorDetails as r, IncantoError as t };
+export { auditScene as i, IncantoErrorCode as n, IncantoErrorDetails as r, IncantoError as t };

package/dist/{gameplay-CDFgSG6z.js → gameplay-DPMgZk9W.js}

@@ -480,6 +480,39 @@ function restartScene(engine) {
 	engine.setScene(loadScene(jsonClone(source)));
 }
 /**
+* Swap to another scene behind a black fade (title→game→next level).
+* Headless (no DOM) the swap is immediate. Restores timeScale to 1.
+*/
+function goToScene(engine, sceneJson, opts) {
+	const fade = opts?.fadeSeconds ?? .4;
+	const swap = () => {
+		engine.timeScale = 1;
+		engine.setScene(loadScene(jsonClone(sceneJson)));
+	};
+	if (typeof document === "undefined" || fade <= 0) {
+		swap();
+		return;
+	}
+	const id = "incanto-scene-fade";
+	let el = document.getElementById(id);
+	if (!el) {
+		el = document.createElement("div");
+		el.id = id;
+		el.style.cssText = "position:fixed;inset:0;z-index:10001;background:#000;opacity:0;pointer-events:none;";
+		document.body.appendChild(el);
+	}
+	el.style.transition = `opacity ${fade / 2}s`;
+	el.style.opacity = "1";
+	setTimeout(() => {
+		swap();
+		const out = document.getElementById(id);
+		if (out) {
+			out.style.opacity = "0";
+			setTimeout(() => out.remove(), fade * 500 + 60);
+		}
+	}, fade * 500 + 30);
+}
+/**
 * The win/lose/restart state machine 6+ examples hand-rolled as `over`/`win`
 * booleans. Attach to any node (the scene root is natural):
 *
@@ -531,6 +564,11 @@ var GameFlow = class extends Behavior {
 		this.thaw();
 		restartScene(this.engine);
 	}
+	/** Fade to another scene (next level, back to title). */
+	goToScene(sceneJson, opts) {
+		this.thaw();
+		goToScene(this.engine, sceneJson, opts);
+	}
 	transition(state, text, color) {
 		if (this.state === "gameover" || this.state === "won") return;
 		this.state = state;
@@ -986,6 +1024,74 @@ var Oscillate = class extends Behavior {
 	}
 };
 //#endregion
+//#region src/gameplay/path-follow.ts
+/**
+* Walk a list of waypoints at a constant speed, then stop — the delivery
+* end of `findPath`:
+*
+*   const cells = findPath(grid, start, goal);
+*   (npc.behavior as PathFollow).setPath(cells.map(([cx, cy]) => [cx * TILE, cy * TILE]));
+*
+* Waypoints are world positions in the node's own units (2D px / 3D m; use
+* [x, y] or [x, y, z] to match the node). Emits `waypointReached(index)`
+* per point and `arrived()` at the end. `loop: true` patrols the ring.
+*/
+var PathFollow = class extends Behavior {
+	static signals = ["waypointReached", "arrived"];
+	static props = {
+		speed: { default: 120 },
+		loop: { default: false }
+	};
+	/** Units per second (px in 2D, meters in 3D). */
+	speed = 120;
+	loop = false;
+	waypoints = [];
+	index = 0;
+	/** True while there is somewhere left to go. */
+	get moving() {
+		return this.index < this.waypoints.length;
+	}
+	setPath(waypoints) {
+		this.waypoints = waypoints.map((w) => [...w]);
+		this.index = 0;
+	}
+	/** Stop in place (keeps the node where it is). */
+	stop() {
+		this.waypoints = [];
+		this.index = 0;
+	}
+	update(dt) {
+		if (!this.moving) return;
+		const node = requirePosition(this);
+		let budget = this.speed * dt;
+		while (budget > 0 && this.index < this.waypoints.length) {
+			const target = this.waypoints[this.index];
+			const step = moveToward(node.position, target, budget);
+			const travelled = distanceBetween(node.position, step.position);
+			node.position = step.position;
+			budget -= travelled;
+			if (step.reached) {
+				this.node.emit("waypointReached", this.index);
+				this.index += 1;
+				if (this.index >= this.waypoints.length) if (this.loop && this.waypoints.length > 1) this.index = 0;
+				else {
+					this.node.emit("arrived");
+					return;
+				}
+			} else return;
+		}
+	}
+};
+function distanceBetween(a, b) {
+	let sum = 0;
+	const n = Math.max(a.length, b.length);
+	for (let i = 0; i < n; i++) {
+		const d = (b[i] ?? 0) - (a[i] ?? 0);
+		sum += d * d;
+	}
+	return Math.sqrt(sum);
+}
+//#endregion
 //#region src/gameplay/patrol.ts
 /**
 * Walk the node along a fixed list of waypoints at constant speed — guards,
@@ -1739,6 +1845,7 @@ var ZombieAI = class extends Behavior {
 const GAMEPLAY_BEHAVIORS = {
 	CameraShake,
 	GameFlow,
+	PathFollow,
 	Health,
 	Lifetime,
 	ScoreKeeper,
@@ -1767,4 +1874,4 @@ function registerGameplayBehaviors(opts) {
 	for (const [name, ctor] of Object.entries(GAMEPLAY_BEHAVIORS)) registerBehavior(name, ctor, { replace });
 }
 //#endregion
-export { Health as C, DamageOnContact as S, Chase as T, screenFlash as _, Wander as a, restartScene as b, Projectile as c, Oscillate as d, MoveTo as f, hitStop as g, Cooldown as h, WaveSpawner as i, Pickup as l, CameraShake as m, registerGameplayBehaviors as n, Spawner as o, Lifetime as p, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Patrol as u, Interactable as v, Collector as w, FollowCamera as x, GameFlow as y };
+export { FollowCamera as C, Chase as D, Collector as E, restartScene as S, Health as T, hitStop as _, Wander as a, GameFlow as b, Projectile as c, PathFollow as d, Oscillate as f, Cooldown as g, CameraShake as h, WaveSpawner as i, Pickup as l, Lifetime as m, registerGameplayBehaviors as n, Spawner as o, MoveTo as p, ZombieAI as r, ScoreKeeper as s, GAMEPLAY_BEHAVIORS as t, Patrol as u, screenFlash as v, DamageOnContact as w, goToScene as x, Interactable as y };

package/dist/gameplay.d.ts

@@ -1,5 +1,5 @@
-import { c as JsonValue } from "./schema-CcoWb32N.js";
-import { T as Node, l as PropSchema, n as BehaviorCtor, t as Behavior, v as Engine } from "./behavior-e3kAmPGC.js";
+import { c as JsonValue, s as JsonObject } from "./schema-CcoWb32N.js";
+import { $ as Node, l as PropSchema, n as BehaviorCtor, t as Behavior, v as Engine } from "./behavior-Bod1AyJS.js";
 
 //#region src/gameplay/chase.d.ts
 /**
@@ -541,6 +541,13 @@ declare class ZombieAI extends Behavior {
 declare function restartScene(engine: Engine): void;
 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.
+*/
+declare function goToScene(engine: Engine, sceneJson: JsonObject, opts?: {
+  fadeSeconds?: number;
+}): void;
+/**
 * The win/lose/restart state machine 6+ examples hand-rolled as `over`/`win`
 * booleans. Attach to any node (the scene root is natural):
 *
@@ -573,6 +580,10 @@ declare class GameFlow extends Behavior {
   pause(): void;
   resume(): void;
   restart(): void;
+  /** Fade to another scene (next level, back to title). */
+  goToScene(sceneJson: JsonObject, opts?: {
+    fadeSeconds?: number;
+  }): void;
   private transition;
   private freeze;
   private thaw;
@@ -639,6 +650,36 @@ declare function screenFlash(color?: string, opacity?: number, seconds?: number)
 */
 declare function hitStop(engine: Engine, seconds?: number): void;
 //#endregion
+//#region src/gameplay/path-follow.d.ts
+/**
+* Walk a list of waypoints at a constant speed, then stop — the delivery
+* end of `findPath`:
+*
+*   const cells = findPath(grid, start, goal);
+*   (npc.behavior as PathFollow).setPath(cells.map(([cx, cy]) => [cx * TILE, cy * TILE]));
+*
+* Waypoints are world positions in the node's own units (2D px / 3D m; use
+* [x, y] or [x, y, z] to match the node). Emits `waypointReached(index)`
+* per point and `arrived()` at the end. `loop: true` patrols the ring.
+*/
+declare class PathFollow extends Behavior {
+  static readonly signals: readonly string[];
+  static readonly props: Record<string, {
+    default: number | boolean;
+  }>;
+  /** Units per second (px in 2D, meters in 3D). */
+  speed: number;
+  loop: boolean;
+  private waypoints;
+  private index;
+  /** True while there is somewhere left to go. */
+  get moving(): boolean;
+  setPath(waypoints: readonly (readonly number[])[]): void;
+  /** Stop in place (keeps the node where it is). */
+  stop(): void;
+  override update(dt: number): void;
+}
+//#endregion
 //#region src/gameplay/index.d.ts
 /** Every built-in gameplay behavior, keyed by its registration name. */
 declare const GAMEPLAY_BEHAVIORS: Readonly<Record<string, BehaviorCtor>>;
@@ -651,4 +692,4 @@ declare function registerGameplayBehaviors(opts?: {
   replace?: boolean;
 }): void;
 //#endregion
-export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, hitStop, registerGameplayBehaviors, restartScene, screenFlash };
+export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, type GameFlowState, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, registerGameplayBehaviors, restartScene, screenFlash };

package/dist/gameplay.js

@@ -1,2 +1,2 @@
-import { C as Health, S as DamageOnContact, T as Chase, _ as screenFlash, a as Wander, b as restartScene, c as Projectile, d as Oscillate, f as MoveTo, g as hitStop, h as Cooldown, i as WaveSpawner, l as Pickup, m as CameraShake, n as registerGameplayBehaviors, o as Spawner, p as Lifetime, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as Interactable, w as Collector, x as FollowCamera, y as GameFlow } from "./gameplay-CDFgSG6z.js";
-export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, hitStop, registerGameplayBehaviors, restartScene, screenFlash };
+import { C as FollowCamera, D as Chase, E as Collector, S as restartScene, T as Health, _ as hitStop, a as Wander, b as GameFlow, c as Projectile, d as PathFollow, f as Oscillate, g as Cooldown, h as CameraShake, i as WaveSpawner, l as Pickup, m as Lifetime, n as registerGameplayBehaviors, o as Spawner, p as MoveTo, r as ZombieAI, s as ScoreKeeper, t as GAMEPLAY_BEHAVIORS, u as Patrol, v as screenFlash, w as DamageOnContact, x as goToScene, y as Interactable } from "./gameplay-DPMgZk9W.js";
+export { CameraShake, Chase, Collector, Cooldown, DamageOnContact, FollowCamera, GAMEPLAY_BEHAVIORS, GameFlow, Health, Interactable, Lifetime, MoveTo, Oscillate, PathFollow, Patrol, Pickup, Projectile, ScoreKeeper, Spawner, Wander, WaveSpawner, ZombieAI, goToScene, hitStop, registerGameplayBehaviors, restartScene, screenFlash };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 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-CcoWb32N.js";
-import { $ as BusName, A as LogManager, B as spatialGain, C as RendererStats, D as SceneTree, E as NodeLifecycle, F as Listener, G as SfxWave, H as SFX_PRESETS, I as ROLLOFF_MODELS, J as MusicBackend, K as SynthOptions, L as RolloffModel, M as SfxEngine, N as SfxPlayOptions, O as LogEntry, P as isAudioContextAvailable, Q as AudioBuses, R as SpatialParams, S as GameStats, T as Node, U as SFX_PRESET_NAMES, V as spatialPan, W as SfxParams, X as MusicTrack, Y as MusicManager, Z as PlayMusicOptions, _ as registeredTypes, a as registerBehavior, b as Scheduler, c as PropDef, d as createNode, et as Signal, f as getNodeSchema, g as registerNode, h as mergeStaticSignals, i as getBehavior, j as InputMap, k as LogLevel, l as PropSchema, m as getNodeType, n as BehaviorCtor, o as registeredBehaviors, p as getNodeSignals, q as synthSfx, r as clearBehaviors, s as NodeCtor, t as Behavior, tt as SignalListener, u as clearRegistry, v as Engine, w as Scene, x as EngineStats, y as EngineOptions, z as Vec3 } from "./behavior-e3kAmPGC.js";
-import { n as loadScene, t as LoadSceneOptions } from "./loader-y_X4zYO0.js";
+import { $ as Node, A as SfxPlayOptions, B as spatialPan, C as RendererStats, D as LogManager, E as LogLevel, F as ROLLOFF_MODELS, G as SynthOptions, H as SFX_PRESET_NAMES, I as RolloffModel, J as MusicManager, K as synthSfx, L as SpatialParams, M as Voice, N as VoicePreset, O as InputMap, P as Listener, Q as BusName, R as Vec3, S as GameStats, T as LogEntry, U as SfxParams, V as SFX_PRESETS, W as SfxWave, X as PlayMusicOptions, Y as MusicTrack, Z as AudioBuses, _ as registeredTypes, a as registerBehavior, b as Scheduler, c as PropDef, d as createNode, et as NodeLifecycle, f as getNodeSchema, g as registerNode, h as mergeStaticSignals, i as getBehavior, j as isAudioContextAvailable, k as SfxEngine, l as PropSchema, m as getNodeType, n as BehaviorCtor, nt as SignalListener, o as registeredBehaviors, p as getNodeSignals, q as MusicBackend, r as clearBehaviors, rt as SceneTree, s as NodeCtor, t as Behavior, tt as Signal, u as clearRegistry, v as Engine, w as Scene, x as EngineStats, y as EngineOptions, z as spatialGain } from "./behavior-Bod1AyJS.js";
+import { n as loadScene, t as LoadSceneOptions } from "./loader-BcUDfNHn.js";
 import { n as ParticleSimConfig, r as ParticleView, t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
-import { n as AudioPlayer, t as AudioElementLike } from "./audio-player-VSjk_vG8.js";
-import { n as IncantoErrorCode, r as IncantoErrorDetails, t as IncantoError } from "./errors-BMFaY68Q.js";
+import { n as AudioPlayer, t as AudioElementLike } from "./audio-player-Dyjg5k92.js";
+import { i as auditScene, n as IncantoErrorCode, r as IncantoErrorDetails, t as IncantoError } from "./errors-1dXlIwoR.js";
 
 //#region src/core/audio/crossfade.d.ts
 /**
@@ -114,7 +114,7 @@ declare class HudLayer extends Node {
   _slot(anchor: HudAnchor): HTMLElement | null;
 }
 /** Shared plumbing: mount into the parent HudLayer's anchor slot. */
-declare abstract class HudWidget extends Node {
+declare abstract class HudWidgetBase extends Node {
   static readonly props: PropSchema;
   anchor: HudAnchor;
   visible: boolean;
@@ -128,7 +128,7 @@ declare abstract class HudWidget extends Node {
   protected _sync(): void;
 }
 /** A text line (score, timer, hints). Set `.text` from behaviors. */
-declare class UiText extends HudWidget {
+declare class UiText extends HudWidgetBase {
   static override readonly typeName: string;
   static override readonly props: PropSchema;
   text: string;
@@ -140,7 +140,7 @@ declare class UiText extends HudWidget {
   protected override _sync(): void;
 }
 /** A labeled progress bar (health, stamina, reload, boss HP). */
-declare class UiBar extends HudWidget {
+declare class UiBar extends HudWidgetBase {
   static override readonly typeName: string;
   static override readonly props: PropSchema;
   value: number;
@@ -164,7 +164,7 @@ declare class UiBar extends HudWidget {
 * in/out and a queue — call `.show(text, { color, seconds })`; `sticky:true`
 * (seconds: 0) keeps it until the next show(). Emits `bannerShown(text)`.
 */
-declare class UiBanner extends HudWidget {
+declare class UiBanner extends HudWidgetBase {
   static override readonly typeName: string;
   static readonly signals: string[];
   static override readonly props: PropSchema;
@@ -187,6 +187,75 @@ declare class UiBanner extends HudWidget {
   override update(dt: number): void;
 }
 //#endregion
+//#region src/core/nodes/dialogue.d.ts
+/**
+* Interactive HUD: clickable buttons and a typewriter dialogue box — the
+* storytelling layer RPG/adventure games kept hand-rolling in DOM.
+* Same family as the other HUD widgets: children of a HudLayer, DOM-backed,
+* silent no-ops headless.
+*/
+/** A clickable button (menus, "START", dialog choices). Emits `pressed`. */
+declare class UiButton extends HudWidgetBase {
+  static override readonly typeName: string;
+  static readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  text: string;
+  size: number;
+  color: string;
+  background: string;
+  disabled: boolean;
+  private lastText;
+  /** Programmatic press — same path as a click (tests, gamepad menus). */
+  press(): void;
+  protected _build(): HTMLElement;
+  protected override _sync(): void;
+}
+/**
+* A typewriter dialogue box with a queue and choices:
+*
+*   const talk = node.getNode('%Dialogue') as UiDialogue;
+*   talk.say('Elder', 'Welcome to Lumina Village...');
+*   talk.say('Elder', 'Will you help us?', ['Yes', 'No']);
+*   talk.on('choiceMade', (index) => { ... });
+*
+* Click / `advance()` reveals the full line, then advances. Emits
+* `lineShown(text)`, `choiceMade(index)`, `dialogueFinished()`.
+*/
+declare class UiDialogue extends HudWidgetBase {
+  static override readonly typeName: string;
+  static readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  override anchor: HudAnchor;
+  /** Typewriter speed; 0 = instant lines. */
+  charsPerSecond: number;
+  width: number;
+  private queue;
+  private current;
+  private revealed;
+  private speakerEl;
+  private textEl;
+  private choicesEl;
+  private hintEl;
+  /** True while a conversation is on screen (pause player input on this). */
+  get active(): boolean;
+  /** 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;
+  /**
+  * Player pressed "next": mid-typing reveals the whole line; a fully-typed
+  * line without choices advances (choice lines wait for `choose`).
+  */
+  advance(): void;
+  /** Pick a choice on the current line (buttons call this). */
+  choose(index: number): void;
+  /** Drop the conversation (cutscene interrupts). */
+  clear(): void;
+  private next;
+  protected _build(): HTMLElement;
+  override update(dt: number): void;
+}
+//#endregion
 //#region src/core/nodes/timer.d.ts
 /**
 * The canonical serializable game clock — never `setTimeout` in game logic.
@@ -267,6 +336,33 @@ declare const PARTICLE_PRESET_NAMES: readonly string[];
 */
 declare function applyParticlePreset(target: Record<string, unknown>, presetName: string, schema: PropSchema): void;
 //#endregion
+//#region src/core/pathfinding.d.ts
+/**
+* Grid A* — the pathfinding every top-down/RPG/tower-defense asks for and
+* agents keep re-inventing badly. Pure and dimension-free: cells in, cells
+* out; the caller maps cells to world units (px, meters, tiles).
+*/
+interface PathGrid {
+  width: number;
+  height: number;
+  /** True = impassable. Out-of-bounds is always solid. */
+  solid(x: number, y: number): boolean;
+}
+interface FindPathOptions {
+  /** Allow diagonal steps (blocked from cutting corners). Default true. */
+  diagonal?: boolean;
+  /** Abort guard for huge/impossible searches. Default 20000 nodes. */
+  maxExpansions?: number;
+}
+/**
+* A* from `from` to `to` (inclusive cell coords). Returns the cell path
+* INCLUDING both endpoints, or null when unreachable. Straight steps cost
+* 1, diagonals √2; the heuristic is octile (admissible for both modes).
+*/
+declare function findPath(grid: PathGrid, from: [number, number], to: [number, number], opts?: FindPathOptions): [number, number][] | null;
+/** Build a PathGrid from row-strings ('#' = solid) — tests and tile games. */
+declare function gridFromRows(rows: readonly string[]): PathGrid;
+//#endregion
 //#region src/core/preload.d.ts
 interface PreloadResult {
   /** Urls whose fetch failed — show an error UI instead of pretending success. */
@@ -310,6 +406,52 @@ declare function resolveRendering(environment: JsonObject | undefined, fallback:
   pixelRatio?: number;
 }): ResolvedRendering;
 //#endregion
+//#region src/core/replay.d.ts
+/**
+* Deterministic input replay — the engine already runs on a seeded RNG and
+* an injectable clock, so a recording of (tick timestamps + input events)
+* replays BIT-IDENTICALLY into a fresh engine with the same seed and scene.
+* That turns "does my game still work?" into an assertion an agent can run
+* headlessly: record once while playing, replay forever as a regression.
+*
+*   const rec = startRecording(engine);            // play the game...
+*   const replayJson = rec.stop();                 // ...save this JSON
+*
+*   const fresh = new Engine({ seed: SAME_SEED }); // same seed + scene JSON
+*   fresh.setScene(loadScene(sceneJson));
+*   replay(fresh, replayJson);                     // now assert game state
+*
+* Caveats (documented, by design): game code must use `engine.rng` (not
+* Math.random) and dt/engine.time (not Date.now) — the engine's own rules.
+* Gamepad polling is not recorded (bind pads to actions; actions replay).
+*/
+/** [tickIndex, methodName, ...primitive args] */
+type ReplayEvent = [number, string, ...(string | number | boolean)[]];
+interface ReplayJson {
+  /** File-format marker for forward compatibility. */
+  replay: 1;
+  /** Tick timestamps (ms) exactly as the loop delivered them. */
+  ticks: number[];
+  events: ReplayEvent[];
+}
+interface Recorder {
+  /** Detach the taps and return the recording. */
+  stop(): ReplayJson;
+}
+/**
+* Tap the engine's input entry points and tick clock. Recording starts at
+* the CURRENT moment — start it before the first tick for full-run replays.
+*/
+declare function startRecording(engine: Engine): Recorder;
+/**
+* Drive a fresh engine through a recording: for each recorded tick, feed
+* that tick's input events first, then tick with the recorded timestamp.
+* `onTick(index)` lets tests assert mid-run state.
+*/
+declare function replay(engine: Engine, recording: ReplayJson, opts?: {
+  onTick?: (index: number) => void;
+}): void;
+//#endregion
 //#region src/core/save.d.ts
 /**
 * Namespaced game persistence — high scores, unlocks, settings. localStorage
@@ -453,4 +595,4 @@ declare function computeViewport(canvasW: number, canvasH: number, viewport: {
 /** Engine version. Kept in sync with package.json by the release pipeline. */
 declare const VERSION: string;
 //#endregion
-export { AudioBuses, type AudioElementLike, AudioPlayer, Behavior, type BehaviorCtor, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, Engine, type EngineOptions, type EngineStats, type GameStats, type HudAnchor, HudLayer, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LoadSceneOptions, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, ORDER_GROUP_BASE, type OrderGroup, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, ROLLOFF_MODELS, type RendererStats, type ResolvedRendering, type ResolvedViewport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiText, VERSION, type Vec3, type ViewportFit, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, getBehavior, getNodeSchema, getNodeSignals, getNodeType, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, synthSfx };
+export { AudioBuses, type AudioElementLike, AudioPlayer, Behavior, type BehaviorCtor, type BusName, CONST_REF_KEY, type ComputedViewport, type ConnectionJson, type CrossfadeGains, type DebugLineSource, Engine, type EngineOptions, type EngineStats, type FindPathOptions, type GameStats, type HudAnchor, HudLayer, IncantoError, type IncantoErrorCode, type IncantoErrorDetails, InputMap, type JsonKind, type JsonObject, type JsonValue, type Listener, type LoadSceneOptions, type LogEntry, type LogLevel, LogManager, type MusicBackend, MusicManager, type MusicTrack, Node, type NodeCtor, type NodeJson, type NodeLifecycle, ORDER_GROUP_BASE, type OrderGroup, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, type ParsedNodePath, type ParticlePresetValues, ParticleSim, type ParticleSimConfig, type ParticleView, type PathGrid, type PlayMusicOptions, type PreloadResult, type PropDef, type PropSchema, ROLLOFF_MODELS, type Recorder, type RendererStats, type ReplayEvent, type ReplayJson, type ResolvedRendering, type ResolvedViewport, Rng, type RolloffModel, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, type SaveStore, Scene, type SceneJson, SceneTree, type Scheduler, SfxEngine, type SfxParams, type SfxPlayOptions, type SfxWave, Signal, type SignalListener, type SpatialParams, type SynthOptions, Timer, TouchControls, type TouchControlsOptions, UiBanner, UiBar, UiButton, UiDialogue, UiText, VERSION, type Vec3, type ViewportFit, type Voice, type VoicePreset, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, auditScene, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, createSaveStore, crossfadeGains, duplicateNode, effectiveOrder, fadeGain, findPath, getBehavior, getNodeSchema, getNodeSignals, getNodeType, gridFromRows, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, replay, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, startRecording, synthSfx };