incanto 0.1.0

package/dist/behavior-BAQq7HGM.d.ts

@@ -0,0 +1,851 @@
+import { a as Rng, c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
+
+//#region src/core/signal.d.ts
+/**
+* Minimal typed observer used for every engine event (Godot signal semantics).
+*
+* Emission is snapshot-based: listeners added during an emit do not fire in that
+* emit, and listeners removed during an emit are skipped.
+*/
+type SignalListener<Args extends unknown[]> = (...args: Args) => void;
+declare class Signal<Args extends unknown[] = unknown[]> {
+  private connections;
+  /** Connect a listener. Returns a disposer. Connecting the same fn twice is a no-op. */
+  connect(fn: SignalListener<Args>, opts?: {
+    once?: boolean;
+  }): () => void;
+  disconnect(fn: SignalListener<Args>): void;
+  disconnectAll(): void;
+  emit(...args: Args): void;
+  get connectionCount(): number;
+}
+//#endregion
+//#region src/core/audio/buses.d.ts
+/** The two volume buses every sound routes through (plus the global `master`). */
+type BusName = "sfx" | "music";
+/**
+* Global volume state — `master` × `sfx`/`music` gain (0..1) plus a `muted`
+* flag. PURE state (no WebAudio): games and AI set it to control overall
+* loudness/mute; the renderer reads `effectiveVolume()` when it actually plays
+* a sound. Lives on the engine as `engine.audio` (instance-scoped, no
+* singletons). The WebAudio wiring is in the adapter; this just holds the
+* numbers so they're fully testable in `node`.
+*
+* ```ts
+* engine.audio.master = 0.8;   // dim everything
+* engine.audio.music = 0.4;    // quieter background music
+* engine.audio.muted = true;   // mute toggle
+* ```
+*/
+declare class AudioBuses {
+  /** Fires whenever any value changes (drives live re-gain of playing sounds). */
+  readonly changed: Signal<[]>;
+  private _master;
+  private _sfx;
+  private _music;
+  private _muted;
+  get master(): number;
+  set master(v: number);
+  get sfx(): number;
+  set sfx(v: number);
+  get music(): number;
+  set music(v: number);
+  get muted(): boolean;
+  set muted(v: 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. */
+  private assign;
+}
+//#endregion
+//#region src/core/audio/music-manager.d.ts
+/**
+* One streamed music track the manager controls — a thin handle the adapter
+* implements over an HTMLAudio element routed through a WebAudio GainNode (so
+* its gain can ramp). Pure-JS fakes implement the same shape for tests.
+*/
+interface MusicTrack {
+  readonly src: string;
+  /** Set the track's output gain (0..1, already bus-multiplied). */
+  setGain(gain: number): void;
+  setLoop(loop: boolean): void;
+  /** Begin (or resume) playback. May be gesture-blocked; that's not an error. */
+  play(): void;
+  /** Stop and release the underlying element/source. */
+  stop(): void;
+}
+/** Backend that mints {@link MusicTrack}s — WebAudio-backed in the browser. */
+interface MusicBackend {
+  /** False headless (no AudioContext) — the manager stays a pure no-op. */
+  readonly available?: boolean;
+  createTrack(src: string): MusicTrack;
+  /** Resume a gesture-suspended context (wired to the first user gesture). */
+  unlock(): void;
+}
+interface PlayMusicOptions {
+  /** Loop the track (default true — music usually loops). */
+  loop?: boolean;
+  /** Fade in over N seconds (default 0 — start at full gain). */
+  fadeIn?: number;
+  /** Which volume bus to route through (default 'music'). */
+  bus?: BusName;
+}
+/**
+* Single-track background-music manager: plays ONE music track, crossfading to
+* a new one (equal-power) or fading in/out. Lives on the engine as
+* `engine.music`; routes through `engine.audio` (the music bus by default) so
+* the global volume/mute sliders dim it for free.
+*
+* The state machine (current/outgoing track, fade phase + timer) is fully
+* testable headlessly via an injected backend; the real backend is WebAudio +
+* HTMLAudio and a no-op when there's no AudioContext. Drive `tick(dt)` once per
+* frame to advance fades (the engine wires this to `updated`).
+*
+* ```ts
+* engine.music.play('incanto/assets/audio/theme.mp3');     // loop, full
+* engine.music.crossfadeTo('boss.mp3', 3);                  // 3s equal-power swap
+* engine.music.stop(2);                                     // fade out over 2s
+* engine.music.setVolume(0.5);                              // per-manager volume
+* ```
+*/
+declare class MusicManager {
+  private readonly buses;
+  private backend;
+  private resolved;
+  /** The current (incoming) track; an outgoing one lives during a fade. */
+  private active;
+  private outgoing;
+  private _bus;
+  private _volume;
+  constructor(buses: AudioBuses);
+  /** Source of the logically-current track, or null when nothing is playing. */
+  get current(): string | null;
+  /** Per-manager volume (0..1), on top of the bus gain. */
+  get volume(): number;
+  private ensure;
+  /** Resume a gesture-suspended context + (re)start any pending track. */
+  unlock(): void;
+  /** Play a single track (replacing any current one immediately, no fade). */
+  play(src: string, opts?: PlayMusicOptions): void;
+  /**
+  * Equal-power crossfade to a new track over `seconds`. With no current track
+  * it's a fade-in. Crossfading to the already-current src is a no-op.
+  */
+  crossfadeTo(src: string, seconds?: number): void;
+  /** Stop the current track, optionally fading out over `fadeOut` seconds. */
+  stop(fadeOut?: number): void;
+  /** Set the per-manager volume (re-applied to live tracks on the next tick). */
+  setVolume(v: number): void;
+  /** Advance fades by `dt` seconds and (re)apply bus×fade gains. Frame-driven. */
+  tick(dt: number): void;
+  /** Effective bus gain for THIS manager (master × bus × manager volume). */
+  private busGain;
+  /** Push the current fade-derived gains onto both tracks. */
+  private applyGains;
+  private killOutgoing;
+}
+//#endregion
+//#region src/core/audio/sfx-presets.d.ts
+/**
+* jsfxr/sfxr-style procedural sound parameters — the AUDIO analog of the
+* particle presets: zero asset bytes, instant, deterministic. A small, pure
+* float-DSP synth (`synthSfx`) turns a param set into a PCM `Float32Array`
+* entirely in core (no WebAudio, no DOM), so the params and the waveform are
+* fully unit-testable in `node`. The browser path (webaudio-sfx.ts) just wraps
+* the PCM in an AudioBuffer and plays it.
+*
+* This is intentionally a *small* sfxr — enough for crisp arcade SFX, not a
+* full DAW. Each preset is one oscillator + an ADSR envelope + optional
+* frequency ramp/vibrato/noise, mirroring the classic "Bfxr" knobs.
+*/
+type SfxWave = "square" | "sawtooth" | "sine" | "triangle" | "noise";
+interface SfxParams {
+  /** Oscillator shape. `noise` is white noise (explosions, hits, steps). */
+  wave: SfxWave;
+  /** Starting pitch in Hz. */
+  baseFreq: number;
+  /** Linear pitch slide over the sound, in Hz/second (+ rises, − falls). */
+  freqRamp: number;
+  /** Attack time (s) — fade in from silence. */
+  attack: number;
+  /** Sustain time (s) — the body of the sound at full level. */
+  sustain: number;
+  /** Decay time (s) — fade out to silence. */
+  decay: number;
+  /** Square-wave duty cycle 0..1 (ignored by other waves). */
+  duty?: number;
+  /** Vibrato depth as a fraction of baseFreq (0 = none). */
+  vibratoDepth?: number;
+  /** Vibrato rate in Hz. */
+  vibratoRate?: number;
+  /** Peak amplitude 0..1. */
+  volume: number;
+}
+/**
+* A tasteful, distinct set of common game sounds. Pick one via
+* `AudioPlayer.preset`. Tuned by ear for crisp arcade feel; `seed`/`pitch`
+* props add free variation so repeated sounds don't feel robotic.
+*/
+declare const SFX_PRESETS: Record<string, SfxParams>;
+declare const SFX_PRESET_NAMES: readonly string[];
+interface SynthOptions {
+  /** Output sample rate (Hz) — match the AudioContext's. Default 44100. */
+  sampleRate?: number;
+  /** Pitch multiplier for variation (1 = preset's pitch). Default 1. */
+  pitch?: number;
+  /** Seed for the noise generator + tiny envelope jitter. Default 0. */
+  seed?: number;
+}
+/**
+* Render a preset to mono PCM in [-1, 1]. PURE: identical inputs → identical
+* output (the only randomness is the seeded noise generator), so determinism is
+* unit-testable headlessly. Length = ceil((attack+sustain+decay) * sampleRate).
+*/
+declare function synthSfx(params: SfxParams, opts?: SynthOptions): Float32Array;
+//#endregion
+//#region src/core/audio/spatial.d.ts
+/**
+* PURE spatial-audio math — the testable heart of 3D positional sound. No
+* WebAudio, no three: just the distance-attenuation curve and listener-relative
+* panning that the adapter feeds into a real `PannerNode`. Mirrors the WebAudio
+* `PannerNode` distance models so the headless math and the browser graph agree,
+* and so the gain we apply on the (non-spatial) HTMLAudio path matches what a
+* panner would produce. Fully unit-testable in `node`.
+*/
+type Vec3 = readonly [number, number, number];
+/** The three WebAudio distance models (PannerNode.distanceModel). */
+type RolloffModel = "inverse" | "linear" | "exponential";
+declare const ROLLOFF_MODELS: readonly RolloffModel[];
+interface SpatialParams {
+  /** Distance at which gain is 1; closer never gets louder. */
+  refDistance: number;
+  /** Distance past which gain stops falling (clamped). */
+  maxDistance: number;
+  /** Attenuation curve shape (matches PannerNode.distanceModel). */
+  rolloff: RolloffModel;
+  /**
+  * Rolloff factor (PannerNode.rolloffFactor) — how quickly gain drops.
+  * Defaults to 1. Higher = steeper falloff.
+  */
+  rolloffFactor?: number;
+}
+/** A listener pose in world space (the active Camera3D drives this). */
+interface Listener {
+  position: Vec3;
+  /** Unit-ish forward (camera looks down -Z by default). */
+  forward: Vec3;
+  /** Unit-ish up. */
+  up: Vec3;
+}
+/**
+* Gain (0..1) for a source `distance` units from the listener, per the chosen
+* model. Identical to the WebAudio PannerNode formulas so the headless number
+* matches the browser panner:
+*
+* - inverse:     ref / (ref + factor·(clamp(d) − ref))
+* - linear:      1 − factor·(clamp(d) − ref) / (max − ref)
+* - exponential: (clamp(d) / ref)^(−factor)
+*
+* where `clamp(d)` is `d` clamped to `[ref, max]`. Always full inside
+* `refDistance`; monotonic non-increasing out to `maxDistance`. Non-finite or
+* degenerate inputs return a safe finite gain.
+*/
+declare function spatialGain(distance: number, params: SpatialParams): number;
+/**
+* Stereo pan (−1 left … 0 center … +1 right) for a source at `sourcePos`,
+* relative to the listener's orientation. Projects the listener→source vector
+* onto the listener's RIGHT axis (forward × up) and normalizes by its length —
+* sign tells left/right, magnitude tells how far off-axis. A source at the
+* listener position (or dead ahead) is centered. Result clamped to [−1, 1].
+*
+* This is the CPU twin of what HRTF/equalpower panning does to the azimuth; the
+* real PannerNode does the full spatialization, but exposing the sign here makes
+* the geometry unit-testable and lets the 2D fallback pan by the same rule.
+*/
+declare function spatialPan(sourcePos: Vec3, listener: Listener): number;
+//#endregion
+//#region src/core/audio/webaudio-sfx.d.ts
+/** A spatial emitter: where the sound is + where the listener is. */
+interface SpatialPlay {
+  /** Emitter world position. */
+  position: Vec3;
+  /** The listener pose (active Camera3D). */
+  listener: Listener;
+  refDistance: number;
+  maxDistance: number;
+  rolloff: RolloffModel;
+  rolloffFactor?: number;
+}
+/** True when a real (or injected) AudioContext backend exists. */
+declare function isAudioContextAvailable(): boolean;
+interface SfxPlayOptions {
+  pitch?: number;
+  seed?: number;
+  /** When set, the sound is spatialized through a PannerNode at this emitter. */
+  spatial?: SpatialPlay;
+}
+/**
+* One AudioContext + a PCM cache. Instance-scoped (held by the renderer's game
+* instance, not a singleton). `play()` synthesizes (cached) and fires a
+* one-shot source at the given gain.
+*/
+declare class SfxEngine {
+  private ctx;
+  private resolved;
+  private readonly pcmCache;
+  /** True once a backend is present (lazily created on first use). */
+  get available(): boolean;
+  private ensure;
+  /** Resume a gesture-suspended context (wired to the first user gesture). */
+  unlock(): 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.
+  * Headless → no-op.
+  */
+  play(params: SfxParams, gain: number, opts?: SfxPlayOptions): void;
+}
+//#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 detach;
+  /** Load (or extend with) scene-JSON action declarations. Hard-validates shape. */
+  declare(decls: Record<string, unknown>): void;
+  /** Feed a key state change (code = KeyboardEvent.code, e.g. 'Space', 'KeyW'). */
+  handleKey(code: string, isDown: boolean): void;
+  private readonly injectedDown;
+  private readonly injectedPressed;
+  private readonly injectedReleased;
+  private readonly injectedVectors;
+  /**
+  * Press a button ACTION directly — no key codes involved. This is how
+  * scripted gameplay tests and touch buttons drive the game by intent
+  * (`press('jump')`) instead of reverse-engineering keybinds.
+  */
+  pressAction(action: string): void;
+  /** Release an injected button action (yields one justReleased frame). */
+  releaseAction(action: string): void;
+  /**
+  * Feed an analog direction for a vector2 ACTION — virtual joysticks and
+  * scripted runs. Persists until replaced; (0, 0) clears the injection.
+  * Combines with key state in getVector (clamped to unit length).
+  */
+  setActionVector(action: string, x: number, y: number): void;
+  /**
+  * Actions the scene wants on-screen touch controls for, in declaration
+  * order (`"touch": "joystick"` on vector2, `"touch": "button"` on buttons).
+  * The touch overlay (core/touch.ts) renders these.
+  */
+  touchControls(): Array<{
+    action: string;
+    kind: "joystick" | "button";
+  }>;
+  /** Drop all injected action state (held buttons, vectors, pending edges). */
+  clearInjected(): void;
+  private dx;
+  private dy;
+  private wheel;
+  /** Mouse buttons feed the same code space as keys: Mouse0/Mouse1/Mouse2. */
+  handleMouseButton(button: number, isDown: boolean): void;
+  /** Accumulate look deltas (movementX/Y under pointer lock, else move deltas). */
+  handlePointerMove(dx: number, dy: number): void;
+  handleWheel(deltaY: number): void;
+  /** Drain the accumulated pointer delta (read once per frame). */
+  pointerDelta(): {
+    x: number;
+    y: number;
+  };
+  /** Drain the accumulated wheel delta. */
+  wheelDelta(): number;
+  /**
+  * Wire browser pointer events on a canvas: buttons → Mouse0/1/2 codes,
+  * movement → pointerDelta (movementX/Y so pointer lock just works),
+  * wheel → wheelDelta. `lockOnClick` requests pointer lock on mousedown
+  * (the FPS pattern).
+  */
+  attachPointer(target: HTMLElement, opts?: {
+    lockOnClick?: boolean;
+  }): () => void;
+  /**
+  * Wire browser keyboard events. Returns (and chains into dispose()) a detach
+  * function.
+  *
+  * By default the browser default is prevented for keys BOUND to a declared
+  * action — an embedded game must not scroll its host page on Space/arrows.
+  * Keys typed into editable elements (inputs, textareas, contenteditable)
+  * are ignored entirely so DOM UI overlays keep working.
+  */
+  attachKeyboard(target: {
+    addEventListener: (t: string, cb: (e: KeyboardEvent) => void) => void;
+    removeEventListener: (t: string, cb: (e: KeyboardEvent) => void) => void;
+  }, opts?: {
+    preventDefault?: "bound" | "none";
+  }): () => void;
+  /** Whether any declared action binds this key code. */
+  private codeIsBound;
+  dispose(): void;
+  isPressed(action: string): boolean;
+  justPressed(action: string): boolean;
+  justReleased(action: string): boolean;
+  /** Normalized direction for a vector2 action (y-down: up = -y). */
+  getVector(action: string): {
+    x: number;
+    y: number;
+  };
+  /** Consume one-frame edges. The Engine calls this at the end of every tick. */
+  endFrame(): void;
+  /**
+  * Drop all action declarations and injected action state (physical key
+  * state is kept). The Engine calls this on setScene so keybinds never
+  * bleed between scenes.
+  */
+  clear(): void;
+  private get;
+  private button;
+}
+//#endregion
+//#region src/core/log.d.ts
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface LogEntry {
+  /** Monotonic per-manager sequence number (1-based). */
+  readonly seq: number;
+  /** Wall-clock-ish timestamp (performance.now when available) — diagnostics only. */
+  readonly timeMs: number;
+  readonly level: LogLevel;
+  /** The raw logged values, untouched — consumers format. */
+  readonly parts: readonly unknown[];
+}
+/**
+* The engine's log channel (`engine.log`, `this.log` in a Behavior): a ring
+* buffer plus a live `added` signal, so debug overlays and headless test
+* harnesses can tail game logs without scraping the browser console.
+*/
+declare class LogManager {
+  /** Fires once per entry, after it is buffered. */
+  readonly added: Signal<[LogEntry]>;
+  private readonly buffer;
+  private readonly capacity;
+  private seq;
+  constructor(capacity?: number);
+  debug(...parts: unknown[]): void;
+  info(...parts: unknown[]): void;
+  warn(...parts: unknown[]): void;
+  error(...parts: unknown[]): void;
+  /** Buffered entries, oldest first (capped at capacity). */
+  entries(): readonly LogEntry[];
+  /** Empty the buffer. The sequence keeps counting (entries stay unique). */
+  clear(): void;
+  private push;
+}
+//#endregion
+//#region src/core/scene-tree.d.ts
+/**
+* Owns a node tree and drives its lifecycle:
+*
+* - `setRoot` → onEnterTree parent-first, then onReady children-first (once per instance)
+* - `update`/`fixedUpdate` → parent-first traversal, then flush of queued frees
+* - group queries across attached nodes
+*
+* Headless by design — tests step it manually; the render loop (M2) calls it.
+*/
+declare class SceneTree {
+  private _root;
+  private _engine;
+  private readonly freeQueue;
+  private _frameId;
+  /**
+  * Monotonic update-frame counter — bumped once per `update()`. Per-frame
+  * caches (e.g. the 3d grass-bender body gather) key off this so they rebuild
+  * at most once a frame regardless of node visitation order.
+  */
+  get frameId(): number;
+  /**
+  * @internal Opaque per-frame scratch the 3d layer parks its shared moving-body
+  * snapshot on (kept here so it is per-tree-instance, never a module global —
+  * core stays three-free, the 3d resolver owns the shape).
+  */
+  _frameScratch: unknown;
+  get root(): Node | null;
+  /** The engine driving this tree (set by Engine.setScene), or null. */
+  get engine(): Engine | null;
+  /** @internal */
+  _setEngine(engine: Engine | null): void;
+  setRoot(node: Node): void;
+  update(dt: number): void;
+  fixedUpdate(dt: number): void;
+  getNodesInGroup(group: string): Node[];
+  /** Call `method(...args)` on every group member that implements it. */
+  callGroup(group: string, method: string, ...args: unknown[]): void;
+  /** @internal */
+  _queueFree(node: Node): void;
+  /** @internal Called by Node.free(): a freed root must not be re-drivable. */
+  _detachRoot(node: Node): void;
+  private flushFreeQueue;
+}
+//#endregion
+//#region src/core/node.d.ts
+/** Lifecycle hooks a SceneTree drives. Wired in scene-tree.ts. */
+interface NodeLifecycle {
+  onEnterTree(): void;
+  onReady(): void;
+  onExitTree(): void;
+  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;
+  /**
+  * Signals this node type can emit, declared statically (merged up the class
+  * hierarchy). A behavior's `static signals` are declared onto its node at
+  * load. Emitting or subscribing an UNDECLARED signal is a hard error —
+  * a typo'd signal name must fail loudly, never silently never-fire.
+  */
+  static readonly signals?: readonly string[];
+  private _name;
+  private _parent;
+  private readonly _children;
+  private readonly _groups;
+  private readonly _signals;
+  private _declared;
+  private _tree;
+  private _ready;
+  /**
+  * Optional STABLE identifier (scene JSON `uid`) — unlike names (unique only
+  * 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;
+  /** 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). */
+  script: JsonObject | null;
+  /** The resolved behavior instance (set by the loader from `script`). */
+  behavior: Behavior | null;
+  /** Replication config blob from scene JSON (interpreted in M6; preserved until then). */
+  network: JsonObject | null;
+  constructor(name?: string);
+  get name(): string;
+  set name(value: string);
+  get parent(): Node | null;
+  get children(): readonly Node[];
+  get groups(): ReadonlySet<string>;
+  /** The SceneTree this node is attached to, or null while detached. */
+  get tree(): SceneTree | null;
+  /** Whether onReady has run (it runs at most once per instance). */
+  get isReady(): boolean;
+  addChild<T extends Node>(child: T): T;
+  removeChild(child: Node): void;
+  reparent(newParent: Node): void;
+  findChild(name: string, recursive?: boolean): Node | null;
+  /** Topmost ancestor (the node itself when detached). */
+  getRoot(): Node;
+  /** Depth-first search of THIS subtree for the node carrying `uid`. */
+  getNodeByUid(uid: string): Node | null;
+  /** Every node in THIS subtree named `name` — names repeat, so a list. */
+  getNodesByName(name: string): Node[];
+  getPath(): string;
+  getNode(path: string): Node;
+  getNodeOrNull(path: string): Node | null;
+  private resolve;
+  addToGroup(group: string): void;
+  removeFromGroup(group: string): void;
+  isInGroup(group: string): boolean;
+  private declaredSignals;
+  /** Declare an ad-hoc signal on THIS instance (static `signals` covers types). */
+  declareSignal(name: string): void;
+  /** Every signal this instance may emit (static + behavior + ad-hoc). */
+  declaredSignalNames(): string[];
+  private assertDeclared;
+  /** Get the named DECLARED signal (creating its Signal object on demand). */
+  signal(name: string): Signal<unknown[]>;
+  on(signal: string, fn: SignalListener<unknown[]>, opts?: {
+    once?: boolean;
+  }): () => void;
+  off(signal: string, fn: SignalListener<unknown[]>): void;
+  emit(signal: string, ...args: unknown[]): void;
+  /**
+  * Defer destruction to the end of the current update pass (flushed by the
+  * SceneTree). Frees immediately when detached from any tree.
+  */
+  queueFree(): void;
+  /** Immediately detach and tear down this node and its children. */
+  free(): void;
+  /** @internal */
+  _propagateEnterTree(tree: SceneTree): void;
+  /** @internal */
+  _propagateReady(): void;
+  /** @internal */
+  _propagateExitTree(): void;
+  /** @internal */
+  _propagateUpdate(dt: number): void;
+  /** @internal */
+  _propagateFixedUpdate(dt: number): void;
+  onEnterTree(): void;
+  onReady(): void;
+  onExitTree(): void;
+  update(_dt: number): void;
+  fixedUpdate(_dt: number): void;
+}
+//#endregion
+//#region src/core/scene/scene.d.ts
+/**
+* A loaded, live scene: the node tree plus everything needed to round-trip
+* back to scene JSON (declared connections, asset/input/multiplayer blobs).
+*
+* JSON is the source of truth for STRUCTURE; imperative listeners added via
+* `node.on(...)` are code, not data, and intentionally do not serialize.
+*/
+declare class Scene {
+  readonly name: string;
+  readonly dimension: "2d" | "3d" | undefined;
+  readonly root: Node;
+  readonly tree: SceneTree;
+  /** Scene-level rendering environment (read by renderer adapters). */
+  readonly environment: JsonObject | undefined;
+  /** Asset declarations (consumed by renderer/asset layers, `$key` references). */
+  readonly assets: Record<string, JsonObject> | undefined;
+  /** Named constant values (`{"@const": "NAME"}` prop references resolve to these). */
+  readonly constants: Record<string, JsonValue> | undefined;
+  /** Input action declarations (loaded into `Engine.input` on setScene). */
+  readonly input: JsonObject | undefined;
+  /** Physics config (gravity etc. — interpreted by the physics modules). */
+  readonly physics: JsonObject | undefined;
+  /** Multiplayer config (room etc. — interpreted by incanto/net). */
+  readonly multiplayer: JsonObject | undefined;
+  /** Design-resolution viewport (consumed by renderers via resolveViewport). */
+  readonly viewport: JsonObject | undefined;
+  private readonly connections;
+  constructor(source: SceneJson, root: Node, tree: SceneTree);
+  /** Lossless export. Note: expanded sub-scene instances serialize as full trees in M1. */
+  toJSON(): SceneJson;
+}
+//#endregion
+//#region src/core/stats.d.ts
+/**
+* Performance-stats shapes — pure data, importable everywhere (core stays
+* three-free; the renderer adapters fill RendererStats from three's
+* `renderer.info`).
+*/
+/** Loop-side counters from `engine.stats()` — queryable at any time. */
+interface EngineStats {
+  /** Frames per second over the last ~60 REAL ticks (headless runs: 0). */
+  fps: number;
+  /** Mean frame delta in ms over the same window (headless runs: 0). */
+  frameMs: number;
+  /** Current node count of the active scene tree (no scene: 0). */
+  nodes: number;
+  /** Whether the loop is scheduled (start() without stop()/dispose()). */
+  running: boolean;
+}
+/** GPU-side counters from `renderer.stats()` — the LAST rendered frame. */
+interface RendererStats {
+  triangles: number;
+  drawCalls: number;
+  geometries: number;
+  textures: number;
+}
+/** The merged `game.stats()` surface returned by createGame2D/3D. */
+type GameStats = EngineStats & RendererStats;
+//#endregion
+//#region src/core/engine.d.ts
+/** Schedules a per-frame callback; returns a disposer. */
+type Scheduler = (cb: (nowMs: number) => void) => () => void;
+interface EngineOptions {
+  /** Fixed-update frequency in Hz (default 60). */
+  fixedHz?: number;
+  /** Spiral-of-death clamp: max fixedUpdate steps per tick (default 5). */
+  maxFixedStepsPerTick?: number;
+  /** Frame source (default: requestAnimationFrame loop). Inject for headless tests. */
+  scheduler?: Scheduler;
+  /** Seed for `engine.rng` — set it to make a run reproducible (default: random). */
+  seed?: number;
+}
+/**
+* The game loop: drives a Scene's tree with fixed-timestep `fixedUpdate`
+* (physics/network window) and variable `update` (everything else).
+*
+* Instance-scoped by design — multiple engines can coexist. Headless-testable
+* via the injectable scheduler and the public `tick(nowMs)`.
+*/
+declare class Engine {
+  /** Emitted after the tree's variable update each frame, with dt seconds. */
+  readonly updated: Signal<[number]>;
+  /** Emitted after each fixed step, with the fixed dt seconds. */
+  readonly fixedUpdated: Signal<[number]>;
+  /**
+  * Emitted after a scene swap completes (input map redeclared) with the new
+  * scene, and with null on dispose — overlays (touch controls, debug panels)
+  * rebuild themselves here.
+  */
+  readonly sceneChanged: Signal<[Scene | null]>;
+  /** Declarative input — scene `input{}` declarations load on setScene. */
+  readonly input: InputMap;
+  /** Seeded randomness for game logic (deterministic when `seed` is set). */
+  readonly rng: Rng;
+  /** The engine log channel (debug overlay + headless harness tail this). */
+  readonly log: LogManager;
+  /** Global volume buses — `master` × `sfx`/`music` gain + `muted`. AudioPlayer
+  *  routes its volume through this; games set it for global volume/mute. */
+  readonly audio: AudioBuses;
+  /** Low-latency procedural-SFX player (WebAudio, headless-safe). AudioPlayer
+  *  presets play through it; games may call `engine.sfx.play(...)` directly. */
+  readonly sfx: SfxEngine;
+  /** Single-track background-music manager (crossfade/loop, headless-safe).
+  *  `engine.music.play(src)` / `crossfadeTo(src, secs)` / `stop(fadeOut)`;
+  *  routes through the music bus and is advanced each frame by the loop. */
+  readonly music: MusicManager;
+  private readonly fixedStep;
+  private readonly maxFixedSteps;
+  private readonly scheduler;
+  private _scene;
+  private lastMs;
+  private accumulator;
+  private disposeScheduler;
+  private readonly frameStats;
+  constructor(opts?: EngineOptions);
+  get scene(): Scene | null;
+  /** Replace the active scene. The previous scene's root is freed. */
+  setScene(scene: Scene): void;
+  start(): void;
+  stop(): void;
+  /**
+  * Live performance counters, queryable at ANY time. fps/frameMs come from a
+  * rolling window of REAL `tick` timestamps — headless `step()` runs report 0.
+  * Node count walks the active tree on demand. Renderer counters (triangles,
+  * draw calls) live on `renderer.stats()` / the merged `game.stats()`.
+  */
+  stats(): EngineStats;
+  /**
+  * Render interpolation factor in [0,1]: how far the wall clock has advanced
+  * INTO the next fixed step. Renderers lerp physics bodies between their last
+  * two fixed-step transforms by this much so motion looks smooth even when the
+  * display refresh doesn't divide evenly into the 60Hz fixed step (the classic
+  * fixed-timestep judder). Only meaningful in the real-time `tick()` loop;
+  * the headless `step()` path doesn't bank wall-clock time.
+  */
+  get interpolationAlpha(): number;
+  /**
+  * Full teardown in one call: stop the loop, free the scene tree, detach
+  * every input listener. The single-unmount story for SPA embedding —
+  * renderers own GPU resources and keep their own dispose().
+  */
+  dispose(): void;
+  /**
+  * Advance exactly ONE fixed step and one variable update (both dt = the
+  * fixed step), bypassing the wall-clock accumulator entirely. Drift-free
+  * by construction — the unit of time for headless harnesses (incanto/test
+  * runScript): every input edge is visible to BOTH fixedUpdate and update
+  * exactly once.
+  */
+  step(): void;
+  /** Advance the loop manually. First call after (re)start only primes the clock. */
+  tick(nowMs: number): void;
+}
+//#endregion
+//#region src/core/registry.d.ts
+/** A node prop definition. The default both documents and types the prop. */
+interface PropDef {
+  default: JsonValue;
+  /** For enum-like string props: the valid values. Drives editor/debug
+  * dropdowns and the generated JSON-Schema enum — keep it exhaustive. */
+  options?: readonly string[];
+}
+type PropSchema = Record<string, PropDef>;
+interface NodeCtor {
+  new (name?: string): Node;
+  readonly typeName: string;
+  readonly props?: PropSchema;
+  readonly signals?: readonly string[];
+}
+declare function registerNode(ctor: NodeCtor, opts?: {
+  replace?: boolean;
+}): void;
+declare function getNodeType(typeName: string): NodeCtor;
+declare function registeredTypes(): string[];
+/** Test isolation helper. */
+declare function clearRegistry(): void;
+/**
+* Effective prop schema for a type: own static `props` merged over every
+* ancestor's (subclass keys win).
+*/
+declare function getNodeSchema(typeName: string): PropSchema;
+/** Walk a constructor's prototype chain collecting static `signals` (deduped). */
+declare function mergeStaticSignals(ctor: {
+  signals?: readonly string[];
+} | null): string[];
+/** Every signal a registered type declares (its own + inherited). */
+declare function getNodeSignals(typeName: string): string[];
+/**
+* Instantiate a registered type, assign schema defaults (cloned), then the
+* given props — validating every key and its JSON kind against the default.
+*/
+declare function createNode(typeName: string, props?: Record<string, JsonValue>): Node;
+//#endregion
+//#region src/core/behavior.d.ts
+interface BehaviorCtor {
+  new (): Behavior;
+  props?: PropSchema;
+  signals?: readonly string[];
+}
+/**
+* Vibe-coded logic attached to a JSON-declared node — the ONE script a node
+* may carry (`"script": {"name": "PlayerController", "props": {...}}`).
+*
+* Lifecycle hooks run AFTER the node's own. Props follow the same
+* schema/defaults/delta model as node props.
+*/
+declare abstract class Behavior {
+  static props?: PropSchema;
+  /**
+  * Custom signals this behavior emits via `this.emit(...)` — declared onto
+  * its node at load. Undeclared emits are hard errors (typo safety).
+  */
+  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. */
+  get engine(): Engine;
+  /** Shortcut for `this.engine.input`. */
+  get input(): InputMap;
+  /** Seeded engine randomness — use this, not Math.random(), for replayability. */
+  get rng(): Rng;
+  /** The engine log channel (visible in the debug overlay and test harness). */
+  get log(): LogManager;
+  getNode(path: string): Node;
+  emit(signal: string, ...args: unknown[]): void;
+  on(signal: string, fn: SignalListener<unknown[]>, opts?: {
+    once?: boolean;
+  }): () => void;
+  onEnterTree?(): void;
+  onReady?(): void;
+  onExitTree?(): void;
+  update?(dt: number): void;
+  fixedUpdate?(dt: number): void;
+}
+/** Explicit registration — never an import side effect (tree-shaking safety). */
+declare function registerBehavior(name: string, ctor: BehaviorCtor, opts?: {
+  replace?: boolean;
+}): void;
+declare function getBehavior(name: string): BehaviorCtor;
+declare function registeredBehaviors(): string[];
+/** Test isolation helper. */
+declare function clearBehaviors(): void;
+//#endregion
+export { BusName as $, LogManager as A, spatialGain as B, RendererStats as C, SceneTree as D, NodeLifecycle as E, Listener as F, SfxWave as G, SFX_PRESETS as H, ROLLOFF_MODELS as I, MusicBackend as J, SynthOptions as K, RolloffModel as L, SfxEngine as M, SfxPlayOptions as N, LogEntry as O, isAudioContextAvailable as P, AudioBuses as Q, SpatialParams as R, GameStats as S, Node as T, SFX_PRESET_NAMES as U, spatialPan as V, SfxParams as W, MusicTrack as X, MusicManager as Y, PlayMusicOptions as Z, registeredTypes as _, registerBehavior as a, Scheduler as b, PropDef as c, createNode as d, Signal as et, getNodeSchema as f, registerNode as g, mergeStaticSignals as h, getBehavior as i, InputMap as j, LogLevel as k, PropSchema as l, getNodeType as m, BehaviorCtor as n, registeredBehaviors as o, getNodeSignals as p, synthSfx as q, clearBehaviors as r, NodeCtor as s, Behavior as t, SignalListener as tt, clearRegistry as u, Engine as v, Scene as w, EngineStats as x, EngineOptions as y, Vec3 as z };