@zylem/game-lib 0.6.4 → 0.8.0

package/dist/game-C1FHVqXl.d.ts

@@ -0,0 +1,1886 @@
+import { e as InputPlayerNumber, f as InputProvider, I as Inputs, h as SetupFunction, g as UpdateFunction, j as DestroyFunction, a as SetupContext, U as UpdateContext, D as DestroyContext, L as LoadingEvent, m as IGame, S as StageNavigationOptions } from './base-node-life-cycle-D2NuN1VB.js';
+import { G as GameInputConfig, B as BaseGlobals, Z as ZylemGameConfig } from './game-interfaces-mchNYSZE.js';
+import { G as GameEntity, a as GameEntityOptions, B as BaseNode, y as GameEntityLifeCycle } from './entity-BdSI8CL3.js';
+import { Scene, Color, Object3D, Vector3, BufferGeometry, Material, Group, Texture } from 'three';
+import { ak as ZylemWorld, ai as EntityTypeMap } from './entity-type-map-Bd69SpAS.js';
+import { E as Entity, L as LifecycleFunction, S as StageEntity } from './entity-DZbFQ1Wg.js';
+import { k as ZylemCamera, R as RendererManager, e as CameraPerspective, d as CameraContext, C as CameraPose, P as PerspectiveType, f as CameraBehavior, g as CameraAction, h as CameraPipelineState, V as Viewport, Z as ZylemPostEffect } from './zylem-camera-C3bn6BTI.js';
+import { d as ZylemShader } from './material-9vJ6SZaI.js';
+import { l as SimulationBody, e as Vec3Input, b as Vec2Input, d as Vec3Components } from './vector-CiSHbivc.js';
+import { BehaviorSystem, BehaviorEntityLink, BehaviorRuntime, BehaviorSystemFactory, Simulation } from '@zylem/behaviors/core';
+import { StageEvents, GameEvents } from './events.js';
+import { D as DefaultTouchControlsOptions } from './default-controls-0-vCnli7.js';
+import { S as StageTransitionConfig } from './stage-transition-CmGpV4tc.js';
+
+declare class InputManager {
+    private inputMap;
+    private currentInputs;
+    private previousInputs;
+    private readonly targetElement?;
+    private readonly mouseTargetElement?;
+    constructor(config?: GameInputConfig, options?: {
+        targetElement?: HTMLElement;
+        mouseTargetElement?: HTMLElement;
+    });
+    /**
+     * Reconfigure keyboard and mouse providers at runtime without affecting gamepad providers.
+     * Disposes existing keyboard/mouse providers and creates new ones from the given config.
+     */
+    configure(config: GameInputConfig): void;
+    addInputProvider(playerNumber: InputPlayerNumber, provider: InputProvider): void;
+    dispose(): void;
+    getInputs(delta: number): Inputs;
+    private buildPlayerEntries;
+    private addConfigurableProviders;
+    private createConfigurableProviders;
+    private mergeInputs;
+}
+
+/**
+ * This class is an alternative to {@link Clock} with a different API design and behavior.
+ * The goal is to avoid the conceptual flaws that became apparent in `Clock` over time.
+ *
+ * - `Timer` has an `update()` method that updates its internal state. That makes it possible to
+ * call `getDelta()` and `getElapsed()` multiple times per simulation step without getting different values.
+ * - The class can make use of the Page Visibility API to avoid large time delta values when the app
+ * is inactive (e.g. tab switched or browser hidden).
+ *
+ * ```js
+ * const timer = new Timer();
+ * timer.connect( document ); // use Page Visibility API
+ * ```
+ *
+ * @three_import import { Timer } from 'three/addons/misc/Timer.js';
+ */
+declare class Timer {
+    protected _previousTime: number;
+    protected _currentTime: number;
+    protected _startTime: number;
+    protected _delta: number;
+    protected _elapsed: number;
+    protected _timescale: number;
+    protected _document: Document | null;
+    protected _pageVisibilityHandler: (() => void) | null;
+    /**
+     * Constructs a new timer.
+     */
+    constructor();
+    /**
+     * Connect the timer to the given document.Calling this method is not mandatory to
+     * use the timer but enables the usage of the Page Visibility API to avoid large time
+     * delta values.
+     *
+     * @param {Document} document - The document.
+     */
+    connect(document: Document): void;
+    /**
+     * Disconnects the timer from the DOM and also disables the usage of the Page Visibility API.
+     */
+    disconnect(): void;
+    /**
+     * Returns the time delta in seconds.
+     *
+     * @return {number} The time delta in second.
+     */
+    getDelta(): number;
+    /**
+     * Returns the elapsed time in seconds.
+     *
+     * @return {number} The elapsed time in second.
+     */
+    getElapsed(): number;
+    /**
+     * Returns the timescale.
+     *
+     * @return {number} The timescale.
+     */
+    getTimescale(): number;
+    /**
+     * Sets the given timescale which scale the time delta computation
+     * in `update()`.
+     *
+     * @param {number} timescale - The timescale to set.
+     * @return {Timer} A reference to this timer.
+     */
+    setTimescale(timescale: number): Timer;
+    /**
+     * Resets the time computation for the current simulation step.
+     *
+     * @return {Timer} A reference to this timer.
+     */
+    reset(): Timer;
+    /**
+     * Can be used to free all internal resources. Usually called when
+     * the timer instance isn't required anymore.
+     */
+    dispose(): void;
+    /**
+     * Updates the internal state of the timer. This method should be called
+     * once per simulation step and before you perform queries against the timer
+     * (e.g. via `getDelta()`).
+     *
+     * @param {number} timestamp - The current time in milliseconds. Can be obtained
+     * from the `requestAnimationFrame` callback argument. If not provided, the current
+     * time will be determined with `performance.now`.
+     * @return {Timer} A reference to this timer.
+     */
+    update(timestamp?: number): Timer;
+}
+
+/**
+ * CameraManager orchestrates multiple cameras per stage.
+ *
+ * Responsibilities:
+ * - Named camera registry (add/remove/get by name or reference)
+ * - Active camera list management (determines which cameras render)
+ * - Always-available debug camera with orbit controls
+ * - Per-frame update of all active cameras' perspective controllers
+ * - Coordinating rendering via RendererManager for all active viewports
+ */
+declare class CameraManager {
+    /** Named camera registry */
+    private cameras;
+    /** Currently active cameras, ordered by render layer (first = bottom) */
+    private _activeCameras;
+    /** Auto-created debug camera with orbit controls */
+    private _debugCamera;
+    /** Reference to the shared renderer manager */
+    private _rendererManager;
+    /** Scene reference */
+    private _sceneRef;
+    /** Counter for auto-generated camera names */
+    private _autoNameCounter;
+    constructor();
+    /**
+     * Get the list of currently active cameras.
+     */
+    get activeCameras(): ReadonlyArray<ZylemCamera>;
+    /**
+     * Get the primary active camera (first in the active list).
+     */
+    get primaryCamera(): ZylemCamera | null;
+    /**
+     * Get the debug camera.
+     */
+    get debugCamera(): ZylemCamera | null;
+    /**
+     * Get all registered cameras.
+     */
+    get allCameras(): ReadonlyArray<ZylemCamera>;
+    /**
+     * Add a camera to the manager.
+     * If no name is provided, one is auto-generated.
+     * The first camera added becomes the active camera.
+     *
+     * @param camera The ZylemCamera instance to add
+     * @param name Optional name for lookup
+     * @returns The assigned name
+     */
+    addCamera(camera: ZylemCamera, name?: string): string;
+    /**
+     * Remove a camera by name or reference.
+     * Cannot remove the debug camera via this method.
+     */
+    removeCamera(nameOrRef: string | ZylemCamera): boolean;
+    /**
+     * Set a camera as the primary active camera (replaces all active cameras
+     * except additional viewport cameras).
+     *
+     * @param nameOrRef Camera name or reference to activate
+     */
+    setActiveCamera(nameOrRef: string | ZylemCamera): boolean;
+    /**
+     * Add a camera as an additional active camera (for split-screen or PiP).
+     */
+    addActiveCamera(nameOrRef: string | ZylemCamera): boolean;
+    /**
+     * Remove a camera from the active render list (does not remove from registry).
+     */
+    deactivateCamera(nameOrRef: string | ZylemCamera): boolean;
+    /**
+     * Get a camera by name.
+     */
+    getCamera(name: string): ZylemCamera | null;
+    /**
+     * Setup all cameras with the given scene and renderer manager.
+     * Also creates the debug camera.
+     */
+    setup(scene: Scene, rendererManager: RendererManager): Promise<void>;
+    /**
+     * Update all active cameras' controllers.
+     */
+    update(delta: number): void;
+    /**
+     * Render all active cameras through the renderer manager.
+     * RTT cameras (those with a renderTarget) are rendered first to their
+     * offscreen textures, then viewport cameras are rendered to the screen.
+     */
+    render(scene: Scene): void;
+    private updateOrbitingCamerasForRender;
+    /**
+     * Create a default third-person camera if no cameras have been added.
+     */
+    ensureDefaultCamera(): ZylemCamera;
+    /**
+     * Dispose all cameras and cleanup.
+     */
+    dispose(): void;
+    /**
+     * Create the always-available debug camera with orbit controls.
+     */
+    private createDebugCamera;
+    /**
+     * Resolve a camera from a name or reference.
+     */
+    private resolveCamera;
+}
+
+interface SceneState {
+    backgroundColor: Color | string;
+    backgroundImage: string | null;
+    backgroundShader?: ZylemShader | null;
+    /**
+     * When `false`, skip the engine's built-in ambient + directional lights so
+     * the caller can configure the scene's lighting entirely via
+     * `createLight(...)` entities. Defaults to `true` for backward
+     * compatibility with existing demos.
+     */
+    defaultLighting?: boolean;
+}
+declare class ZylemScene implements Entity<ZylemScene> {
+    type: string;
+    _setup?: SetupFunction<ZylemScene>;
+    scene: Scene;
+    /** @deprecated Use cameraManager instead */
+    zylemCamera: ZylemCamera;
+    cameraManager: CameraManager | null;
+    containerElement: HTMLElement | null;
+    update: LifecycleFunction<ZylemScene>;
+    _collision?: ((entity: any, other: any, globals?: any) => void) | undefined;
+    _destroy?: ((globals?: any) => void) | undefined;
+    name?: string | undefined;
+    tag?: Set<string> | undefined;
+    constructor(id: string, camera: ZylemCamera, state: SceneState);
+    /**
+     * Render the shader as a true skybox via the WebGPU renderer's
+     * `scene.backgroundNode`. The node is evaluated per background pixel at
+     * infinite depth — inside it, `normalWorld` (from `three/tsl`) is the
+     * per-pixel view direction, so the sky is stable under camera movement
+     * with no skybox mesh, far-plane sizing, or camera-follow logic.
+     *
+     * WebGPU-only: background shaders must be authored in TSL
+     * ({@link ZylemTSLShader}). A GLSL shader logs a warning and is ignored
+     * (the solid background color is kept).
+     */
+    private setupBackgroundShader;
+    setup(): void;
+    destroy(): void;
+    /**
+     * Setup camera with the scene.
+     * Supports both legacy single camera and CameraManager modes.
+     */
+    setupCamera(scene: Scene, camera: ZylemCamera, rendererManager?: RendererManager): Promise<void>;
+    /**
+     * Setup with a CameraManager (multi-camera support).
+     */
+    setupCameraManager(scene: Scene, cameraManager: CameraManager, rendererManager: RendererManager): Promise<void>;
+    /**
+     * Add a camera (rig or direct) to the scene graph.
+     */
+    private addCameraToScene;
+    /**
+     * Setup scene lighting
+     */
+    setupLighting(scene: Scene): void;
+    /**
+     * Update renderer size - delegates to camera manager or camera
+     */
+    updateRenderer(width: number, height: number): void;
+    /**
+     * Add object to scene
+     */
+    add(object: Object3D, position?: Vector3): void;
+    /**
+     * Add game entity to scene
+     */
+    addEntity(entity: GameEntity<any>): void;
+    /**
+     * Add an entity's group or mesh to the scene (for late-loaded models).
+     * Uses entity's current body position if physics is active.
+     *
+     * Fog entities ({@link ZylemFog}) are routed through the normal add
+     * pipeline so their empty placeholder group is parented for cleanup,
+     * but they also get an `attachToScene` call that wires `scene.fog`
+     * and starts the optional material patcher.
+     */
+    addEntityGroup(entity: GameEntity<any>): void;
+    private isAttachedOutsideScene;
+    /**
+     * Add debug helpers to scene
+     */
+    debugScene(): void;
+}
+
+/** Configuration for pack key generation */
+interface PackKeyConfig {
+    geometryType: string;
+    dimensions: Record<string, number>;
+    materialPath?: string | null;
+    shaderType?: 'standard' | 'custom';
+    colorHex?: number;
+}
+/** Manages instanced mesh packs for `category: 'pack'` entities */
+declare class InstanceManager {
+    private packs;
+    private entityToPack;
+    private scene;
+    /** Default initial capacity for new packs */
+    static DEFAULT_CAPACITY: number;
+    /** Factor to grow a pack when full */
+    static GROWTH_FACTOR: number;
+    setScene(scene: Object3D): void;
+    static generatePackKey(config: PackKeyConfig): string;
+    static generateEntityPackKey(entity: Pick<GameEntity<GameEntityOptions>, 'options' | 'materials'> & {
+        constructor: any;
+    }): string;
+    /**
+     * Register an entity with the instance manager.
+     * @returns The instance index, or -1 if registration failed
+     */
+    register(entity: GameEntity<any>, geometry: BufferGeometry, material: Material, packKey: string): number;
+    unregister(entity: GameEntity<any>): void;
+    markDirty(entity: GameEntity<any>): void;
+    /**
+     * Update all active instance transforms.
+     * Call once per frame after the simulation step and render-buffer sync.
+     */
+    update(interpolationAlpha?: number): void;
+    private updateInstanceMatrix;
+    getPackInfo(entity: GameEntity<any>): {
+        packKey: string;
+        instanceId: number;
+    } | null;
+    getStats(): {
+        packCount: number;
+        totalInstances: number;
+        packs: {
+            key: string;
+            count: number;
+            capacity: number;
+        }[];
+    };
+    dispose(): void;
+    private createPack;
+    private growPack;
+}
+
+/**
+ * Groups static environment meshes into WebGPU `BundleGroup`s for record-once
+ * replay. Dynamic entities must use `pack` (instancing) or `none` (scene-direct).
+ */
+declare class RenderBundleManager {
+    private readonly bundles;
+    private readonly entityToBundle;
+    private scene;
+    setScene(scene: Object3D): void;
+    /**
+     * Parent the entity's renderable into a static bundle group.
+     * @returns `true` when registration succeeded.
+     */
+    register(entity: GameEntity<any>, _geometry: BufferGeometry, _material: Material, bundleKey: string): boolean;
+    unregister(entity: GameEntity<any>): void;
+    getStats(): {
+        bundleCount: number;
+        entityCount: number;
+    };
+    dispose(): void;
+    private getOrCreateBundle;
+}
+
+/**
+ * Routes entities to scene-direct (`none`), WebGPU bundles (`environment`), or
+ * instanced meshes (`pack`) based on `options.category`.
+ */
+declare class RenderStrategyManager {
+    readonly bundles: RenderBundleManager;
+    readonly instances: InstanceManager;
+    setScene(scene: Object3D): void;
+    /**
+     * Register an entity with the appropriate managed render path.
+     * @returns `true` when the entity was placed into bundle or instanced rendering.
+     */
+    register(entity: GameEntity<any>): boolean;
+    unregister(entity: GameEntity<any>): void;
+    update(interpolationAlpha?: number): void;
+    dispose(): void;
+}
+
+/**
+ * Base entity interface - shared across modules to prevent circular dependencies
+ */
+interface BaseEntityInterface {
+    uuid: string;
+    name: string;
+    group: Group | null | undefined;
+    body: SimulationBody | null | undefined;
+}
+/**
+ * Game entity interface - minimal interface to break circular dependencies
+ */
+interface GameEntityInterface extends BaseEntityInterface {
+    type: string;
+    isStatic: boolean;
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+}
+
+/**
+ * Provides BaseNode-like lifecycle without ECS/children. Consumers implement
+ * the protected hooks and may assign public setup/update/destroy callbacks.
+ */
+declare abstract class LifeCycleBase<TSelf> {
+    update: UpdateFunction<TSelf>;
+    setup: SetupFunction<TSelf>;
+    destroy: DestroyFunction<TSelf>;
+    protected abstract _setup(context: SetupContext<TSelf>): void;
+    protected abstract _update(context: UpdateContext<TSelf>): void;
+    protected abstract _destroy(context: DestroyContext<TSelf>): void;
+    nodeSetup(context: SetupContext<TSelf>): void;
+    nodeUpdate(context: UpdateContext<TSelf>): void;
+    nodeDestroy(context: DestroyContext<TSelf>): void;
+}
+
+/**
+ * Configuration for the third-person perspective.
+ */
+interface ThirdPersonOptions {
+    /** Distance behind the target. Default 8. */
+    distance?: number;
+    /** Height above the target. Default 5. */
+    height?: number;
+    /** Lateral offset from the target (shoulder cam). Default 0. */
+    shoulderOffset?: number;
+    /** Key in CameraContext.targets to follow. Default 'primary'. */
+    targetKey?: string;
+    /** Perspective field of view. Default 75. */
+    fov?: number;
+    /** Padding multiplier when framing multiple targets. Default 1.5. */
+    paddingFactor?: number;
+    /** Minimum camera distance when multi-framing. Default 5. */
+    minDistance?: number;
+    /** Fallback camera position when no targets exist (e.g. the user-specified initial position). */
+    initialPosition?: Vec3Input;
+    /** Fallback lookAt point when no targets exist. */
+    initialLookAt?: Vec3Input;
+    /**
+     * Seconds the camera lags behind the target's actual position. The camera
+     * samples target moves from `now - trailDelay` so brief, fast Y motion
+     * (jump apex / fall start) doesn't get tracked 1:1 — eliminates the
+     * shimmer-on-fall effect at high refresh rates. 0 disables the trail and
+     * restores instantaneous tracking. Default 0.1 (100 ms).
+     */
+    trailDelay?: number;
+    /**
+     * Maximum number of samples to keep in the trailing ring buffer.
+     * Sized to cover ~1 s at 120 Hz; larger only matters if `trailDelay` is
+     * raised significantly. Default 120.
+     */
+    trailBufferSize?: number;
+}
+/**
+ * Third-person 3D perspective.
+ *
+ * - 0 targets: returns a static pose behind the origin.
+ * - 1 target: camera positioned behind and above the target, looking at it.
+ * - 2+ targets: weighted-centroid framing with dynamic distance.
+ */
+declare class ThirdPersonPerspective implements CameraPerspective {
+    readonly id = "third-person";
+    /**
+     * Slightly looser than the previous 0.15 to compose better with the
+     * trailing-delay follow: the trail absorbs short, fast moves and the
+     * damping smooths the rest.
+     */
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    private initialPosition?;
+    private initialLookAt?;
+    /** Per-target ring buffers for trailing-delay sampling, keyed by target key. */
+    private _trailBuffers;
+    constructor(options?: ThirdPersonOptions);
+    getBasePose(ctx: CameraContext): CameraPose;
+    /**
+     * No targets: use the user-specified initial position if available,
+     * otherwise fall back to a default pose behind the origin.
+     */
+    private staticPose;
+    /**
+     * Single target: position = trailedTarget + offset, lookAt = trailedTarget.
+     *
+     * The trailed position lags `targetPos` by `trailDelay` seconds (default
+     * 100 ms), so transient spikes in target Y (the start of a fall, jump apex)
+     * don't propagate into the camera every frame. Both `position` and
+     * `lookAt` are derived from the same trailed point so the relative offset
+     * is preserved exactly.
+     */
+    private singleTargetPose;
+    /**
+     * Multi-target: compute centroid (using trailed positions) and adjust
+     * distance to frame all targets.
+     */
+    private multiTargetPose;
+    /**
+     * Push the current target position into the per-target ring buffer and
+     * return a position interpolated at `now - trailDelay`.
+     *
+     * - When `trailDelay` is 0 the call short-circuits and returns `targetPos`
+     *   unchanged (no allocation, no buffer growth).
+     * - During the warmup window (the first `trailDelay` seconds of life)
+     *   the oldest sample is returned so the camera starts from rest rather
+     *   than snapping to the live target.
+     */
+    private getTrailedPosition;
+}
+
+/**
+ * Configuration for the fixed 2D perspective.
+ */
+interface Fixed2DOptions {
+    /** Fixed camera position. Default (0, 0, 10). */
+    position?: Vec3Input;
+    /** Orthographic zoom (frustum size). Default 10. */
+    zoom?: number;
+}
+/**
+ * Fixed 2D perspective.
+ *
+ * Returns a static orthographic pose looking down the Z-axis.
+ * No target following -- the camera stays at the configured position.
+ */
+declare class Fixed2DPerspective implements CameraPerspective {
+    readonly id = "fixed-2d";
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    constructor(options?: Fixed2DOptions);
+    getBasePose(_ctx: CameraContext): CameraPose;
+}
+
+/**
+ * Configuration for the first-person perspective.
+ */
+interface FirstPersonOptions {
+    /** Vertical offset above the target entity's position (eye height). @default 1.7 */
+    eyeHeight?: number;
+    /** Default field of view in degrees. @default 75 */
+    defaultFov?: number;
+    /** Maximum pitch angle in radians. @default Math.PI/2 - 0.01 */
+    pitchLimit?: number;
+    /** Lerp speed for smooth look-at transitions. @default 5 */
+    lookAtLerpSpeed?: number;
+    /** Lerp speed for FOV zoom transitions. @default 8 */
+    fovLerpSpeed?: number;
+    /** Key in CameraContext.targets to follow. @default 'primary' */
+    targetKey?: string;
+    /** Fallback position when no target entity is attached. */
+    initialPosition?: Vec3Input;
+    /** Fallback look-at point used to derive initial yaw/pitch when no target. */
+    initialLookAt?: Vec3Input;
+    /**
+     * Vertical (eye-height) smoothing factor in 0..1, applied per 60Hz frame.
+     * 1 = instant snap (no smoothing), lower = smoother. Hides physics
+     * micro-jitter and Rapier sub-step Y corrections without adding perceptible
+     * input lag. Smooths only Y; X/Z still snap to the target every frame so
+     * horizontal aim is never laggy.
+     * @default 1 (disabled)
+     */
+    verticalSmoothing?: number;
+}
+/**
+ * First-person camera perspective.
+ *
+ * Position is derived from the attached target entity (+ eye height).
+ * Rotation is driven via `look()` / `setLook()` methods called by game code
+ * or a future FPS behavior. Supports smooth FOV zoom and lerp'd look-at.
+ */
+declare class FirstPersonPerspective implements CameraPerspective {
+    readonly id = "first-person";
+    readonly defaults: {
+        damping: number;
+    };
+    private opts;
+    /** Fallback position when no target entity is attached. Mutate directly for manual movement. */
+    initialPosition?: Vector3;
+    private initialLookAt?;
+    private _yaw;
+    private _pitch;
+    private _currentFov;
+    private _targetFov;
+    private _lookAtTarget;
+    private _lookAtLerpSpeed;
+    private _currentRotation;
+    private _rotationInitialized;
+    private _smoothedY;
+    constructor(options?: FirstPersonOptions);
+    /** Accumulate yaw and pitch deltas. Pitch is clamped to the configured limit. */
+    look(deltaYaw: number, deltaPitch: number): void;
+    /** Set absolute yaw and pitch. Pitch is clamped to the configured limit. */
+    setLook(yaw: number, pitch: number): void;
+    /** Current yaw in radians. */
+    get yaw(): number;
+    /** Current pitch in radians. */
+    get pitch(): number;
+    /** Set the target FOV for a smooth zoom transition (e.g. sniper scope). */
+    zoom(fov: number): void;
+    /** Return to the default FOV. */
+    resetZoom(): void;
+    /** Current field of view. */
+    get currentFov(): number;
+    /**
+     * Enable smooth look-at toward a world position.
+     * The camera will slerp from the current rotation toward the look-at direction.
+     */
+    lookAt(target: Vector3, lerpSpeed?: number): void;
+    /** Disable look-at and return to manual yaw/pitch control. */
+    clearLookAt(): void;
+    getBasePose(ctx: CameraContext): CameraPose;
+    private computePosition;
+    /**
+     * Low-pass filter the eye Y so Rapier sub-step corrections and probe-driven
+     * micro-bobs don't show up as visible head jitter. X/Z are left un-smoothed
+     * so horizontal aim remains 1:1 with input.
+     */
+    private smoothVertical;
+    private computeRotation;
+    private lerpFov;
+    private deriveYawPitchFromLookAt;
+    private deriveYawPitchFromQuaternion;
+}
+
+/**
+ * Perspective-specific options union.
+ * Extend as new perspective types are added.
+ */
+type PerspectiveOptions = ThirdPersonOptions | Fixed2DOptions | FirstPersonOptions;
+/**
+ * Factory: create a CameraPerspective from a PerspectiveType string.
+ * Unrecognized types default to ThirdPersonPerspective.
+ */
+declare function createPerspective(type: PerspectiveType, options?: PerspectiveOptions): CameraPerspective;
+
+interface CameraOptions {
+    perspective?: PerspectiveType;
+    position?: Vec3Input;
+    target?: Vec3Input;
+    zoom?: number;
+    screenResolution?: Vec2Input;
+    /**
+     * Enable orbital controls for this camera.
+     * Can be toggled at runtime via enableOrbitalControls() / disableOrbitalControls().
+     * @default false
+     */
+    useOrbitalControls?: boolean;
+    /**
+     * Viewport in normalized coordinates (0-1).
+     * Defines where this camera renders on the canvas.
+     * @default { x: 0, y: 0, width: 1, height: 1 } (fullscreen)
+     */
+    viewport?: Viewport;
+    /**
+     * Optional name for camera manager lookup.
+     */
+    name?: string;
+    /**
+     * Initial behaviors to attach to the camera pipeline.
+     * Keys are used for idempotent add/remove.
+     */
+    behaviors?: Record<string, CameraBehavior>;
+    /**
+     * Pipeline smoothing factor (0-1).
+     * 1 = instant snap, 0 = no movement.
+     * @default 0.15
+     */
+    damping?: number;
+    /**
+     * When set, the camera renders to an offscreen texture instead of a
+     * screen viewport. Use with setCameraFeed() to display the feed on
+     * an in-scene mesh (jumbotron, security monitor, portal, etc.).
+     *
+     * @default undefined (renders to screen)
+     */
+    renderToTexture?: {
+        /** Texture width in pixels. @default 512 */
+        width?: number;
+        /** Texture height in pixels. @default 512 */
+        height?: number;
+    };
+    /**
+     * When true, this camera will not activate orbital controls in debug mode.
+     * The pipeline (and its behaviors) will always run for this camera.
+     * Use for cameras with custom behaviors (e.g. FPS mouse-look) that must
+     * control the camera through the pipeline rather than debug orbit controls.
+     * @default false
+     */
+    skipDebugOrbit?: boolean;
+}
+/**
+ * CameraWrapper is the user-facing camera handle returned by createCamera().
+ * It provides convenience methods for target management, orbital controls,
+ * viewport configuration, and the camera pose pipeline.
+ */
+declare class CameraWrapper {
+    cameraRef: ZylemCamera;
+    constructor(camera: ZylemCamera);
+    /**
+     * Add a target entity for the camera to follow/frame.
+     * With multiple targets, the camera auto-frames to include all of them.
+     */
+    addTarget(entity: StageEntity): void;
+    /**
+     * Remove a target entity from the camera.
+     */
+    removeTarget(entity: StageEntity): void;
+    /**
+     * Clear all targets. Camera will look at world origin.
+     */
+    clearTargets(): void;
+    /**
+     * Enable orbital controls for this camera.
+     * Allows the user to orbit, pan, and zoom the camera.
+     */
+    enableOrbitalControls(): void;
+    /**
+     * Disable orbital controls for this camera.
+     */
+    disableOrbitalControls(): void;
+    /**
+     * Set the viewport for this camera (normalized 0-1 coordinates).
+     * @param x Left edge (0 = left of canvas)
+     * @param y Bottom edge (0 = bottom of canvas)
+     * @param width Width as fraction of canvas
+     * @param height Height as fraction of canvas
+     */
+    setViewport(x: number, y: number, width: number, height: number): void;
+    /**
+     * Add or replace a behavior by key (idempotent).
+     * Behaviors modify the desired camera pose each frame.
+     *
+     * @param key   Unique key for this behavior (used for replacement/removal).
+     * @param behavior  The CameraBehavior implementation.
+     */
+    addBehavior(key: string, behavior: CameraBehavior): void;
+    /**
+     * Remove a behavior by key.
+     */
+    removeBehavior(key: string): boolean;
+    /**
+     * Add a transient action (screenshake, recoil, etc.).
+     * Actions apply additive deltas and self-expire when isDone() returns true.
+     */
+    addAction(action: CameraAction): void;
+    /**
+     * Switch the camera's active perspective at runtime.
+     * The first frame after switching snaps to the new pose (no lerp).
+     *
+     * @param type     Perspective type string (e.g. Perspectives.ThirdPerson).
+     * @param options  Perspective-specific options (distance, height, zoom, etc.).
+     */
+    setPerspective(type: PerspectiveType, options?: PerspectiveOptions): void;
+    /**
+     * Retrieve the active perspective instance, cast to the desired type.
+     * Useful for calling perspective-specific methods (e.g. FirstPersonPerspective.look()).
+     *
+     * @example
+     * const fps = camera.getPerspective<FirstPersonPerspective>();
+     * fps.look(dx, dy);
+     */
+    getPerspective<T extends CameraPerspective = CameraPerspective>(): T;
+    /**
+     * Return a debug snapshot of the camera pipeline state.
+     * Includes: active perspective, desired/final pose, behavior keys, action count.
+     */
+    getState(): CameraPipelineState;
+    /**
+     * Get the offscreen render texture for this camera.
+     * Returns null if the camera was not created with renderToTexture.
+     * Use with setCameraFeed() or apply directly to a mesh material.
+     */
+    getRenderTexture(): Texture | null;
+}
+/**
+ * Create a camera with the given options.
+ * Returns a CameraWrapper for convenient access to camera features.
+ */
+declare function createCamera(options: CameraOptions): CameraWrapper;
+
+/**
+ * Owns the stage's in-world debug/editor interaction layer.
+ *
+ * Self-manages around the global `debugState`: when debug is enabled it draws
+ * the wasm simulation's collider wireframes, attaches mouse listeners,
+ * raycasts into the physics world to hover/select/delete/spawn entities, and
+ * drives the `DebugEntityCursor` highlight. When disabled it tears down
+ * visuals but stays alive to re-activate. Centralizes all debug-tool plumbing
+ * so `ZylemStage` doesn't have to know about raycasting, DOM input, or debug
+ * rendering.
+ */
+
+type AddEntityFactory = (params: {
+    position: Vector3;
+    normal?: Vector3;
+}) => Promise<any> | any;
+interface StageDebugDelegateOptions {
+    maxRayDistance?: number;
+    addEntityFactory?: AddEntityFactory | null;
+}
+/**
+ * Self-managing debug delegate that subscribes to `debugState` internally.
+ *
+ * When debug is enabled it lazily initializes visuals and DOM listeners.
+ * When debug is disabled it tears down visuals but stays alive so it can
+ * re-activate without being recreated. Call `dispose()` to fully tear down.
+ */
+declare class StageDebugDelegate {
+    private stage;
+    private options;
+    private mouseNdc;
+    private raycaster;
+    private isMouseDown;
+    private domDisposeFns;
+    private domListenersAttached;
+    private debugCursor;
+    private debugLines;
+    private cameraDebugDelegate;
+    private debugStateUnsubscribe;
+    private focusContextUnregister;
+    constructor(stage: ZylemStage, options?: StageDebugDelegateOptions);
+    private resolveEntity;
+    /** Copy all stage children into debugMap so raycast/select tools work after enabling debug mid-session. */
+    private populateDebugMap;
+    private ensureCameraDebugDelegate;
+    private syncWithDebugState;
+    /** Initialize DOM listeners and camera debug delegate when debug is turned on. */
+    private activate;
+    /** Tear down visuals and camera debug delegate when debug is turned off. */
+    private deactivate;
+    private initDebugVisuals;
+    private disposeDebugVisuals;
+    update(): void;
+    /** Full teardown — unsubscribes from debugState and cleans up all resources. */
+    dispose(): void;
+    private handleActionOnHit;
+    private attachDomListeners;
+}
+
+/**
+ * Stage configuration: types, defaults, and option parsing.
+ *
+ * Defines the user-facing stage config shape (`StageConfigLike`), the internal
+ * `StageConfig` class, and the engine defaults applied to every stage. Its core
+ * job is `parseStageOptions`, which untangles the heterogeneous `createStage(...)`
+ * argument list (config objects, camera wrappers, sync/async entities) into a
+ * normalized `ParsedStageOptions` that `ZylemStage` can consume directly.
+ */
+
+type StageGLTFAssetLoaderConfig = {
+    meshopt?: boolean;
+    ktx2TranscoderPath?: URL | string;
+};
+type StageAssetLoaderConfig = {
+    gltf?: StageGLTFAssetLoaderConfig;
+};
+/**
+ * Stage configuration type for user-facing options.
+ */
+type StageConfigLike = Partial<{
+    inputs: Record<string, string[]>;
+    backgroundColor: Color | string;
+    backgroundImage: string | null;
+    backgroundShader: ZylemShader;
+    gravity: Vector3 | Vec3Components;
+    variables: Record<string, any>;
+    /** Physics update rate in Hz (default 60). */
+    physicsRate: number;
+    assetLoaders: StageAssetLoaderConfig;
+    /**
+     * When `false`, the engine's built-in ambient + directional lights are
+     * suppressed so the stage can be lit entirely via `createLight(...)`
+     * entities. Defaults to `true`.
+     */
+    defaultLighting: boolean;
+    /**
+     * Postprocessing effects applied in order between the scene pass and the
+     * display output (e.g. effects from `@zylem/shaders`). Only active for
+     * single fullscreen-camera rendering.
+     */
+    postProcessingEffects: ZylemPostEffect[];
+}>;
+/**
+ * Factory for authoring stage configuration objects in user code.
+ * Returns a plain object that can be passed to `createStage(...)`.
+ */
+declare function stageConfig(config: StageConfigLike): StageConfigLike;
+
+/**
+ * Fan-out hub for a stage's loading lifecycle events.
+ *
+ * Collects start/progress/complete loading events and broadcasts them both to
+ * direct per-stage subscribers and to the global `gameEventBus` (tagged with
+ * stage name/index) for game-level loading UIs. Exists so the entity-load
+ * generator and stage code can emit progress through one place without knowing
+ * who is listening.
+ */
+
+/**
+ * Delegate for managing loading events and progress within a stage.
+ * Handles subscription to loading events and broadcasting progress.
+ * Emits to game event bus for game-level observation.
+ */
+declare class StageLoadingDelegate {
+    private loadingHandlers;
+    private stageName?;
+    private stageIndex?;
+    /**
+     * Set stage context for event bus emissions.
+     */
+    setStageContext(stageName: string, stageIndex: number): void;
+    /**
+     * Subscribe to loading events.
+     *
+     * @param callback Invoked for each loading event (start, progress, complete)
+     * @returns Unsubscribe function
+     */
+    onLoading(callback: (event: LoadingEvent) => void): () => void;
+    /**
+     * Emit a loading event to all subscribers and to the game event bus.
+     *
+     * @param event The loading event to broadcast
+     */
+    emit(event: LoadingEvent): void;
+    /**
+     * Emit a start loading event.
+     */
+    emitStart(message?: string): void;
+    /**
+     * Emit a progress loading event.
+     */
+    emitProgress(message: string, current: number, total: number): void;
+    /**
+     * Emit a complete loading event.
+     */
+    emitComplete(message?: string): void;
+    /**
+     * Clear all loading handlers.
+     */
+    dispose(): void;
+}
+
+/**
+ * Delegate for handling deferred model loading in entities.
+ * Subscribes to model:loaded events and adds entity groups to the scene
+ * when they become available after async loading completes.
+ */
+declare class StageEntityModelDelegate {
+    private scene;
+    private onEntityReady;
+    private pendingEntities;
+    private modelLoadedHandler;
+    /**
+     * Initialize the delegate with the scene reference and start listening.
+     */
+    attach(scene: ZylemScene, onEntityReady?: (entity: GameEntity<any>) => void): void;
+    /**
+     * Register an entity for observation.
+     * When its model loads, the group will be added to the scene.
+     */
+    observe(entity: GameEntity<any>): void;
+    /**
+     * Unregister an entity (e.g., when removed before model loads).
+     */
+    unobserve(entityId: string): void;
+    /**
+     * Handle model loaded event - add group to scene if entity is pending.
+     */
+    private handleModelLoaded;
+    /**
+     * Cleanup all subscriptions and pending entities.
+     */
+    dispose(): void;
+}
+
+/**
+ * The stage's entity lifecycle engine.
+ *
+ * Owns everything about entities within a stage: queuing (sync, async, and
+ * factory inputs), progressive load via a yielding generator, spawning into
+ * scene/world/runtime, instanced-mesh batching, deferred-model handling,
+ * removal, name/UUID lookup, and ECS behavior-system registration/indexing.
+ * Extracted from `ZylemStage` so entity bookkeeping lives in one cohesive place
+ * and can be shared with the debug delegate and transform system.
+ */
+
+type NodeLike$1 = {
+    create: Function;
+};
+type StageEntityInput = NodeLike$1 | Promise<any> | (() => NodeLike$1 | Promise<any>);
+/**
+ * Runtime context provided by ZylemStage after scene and world are initialized.
+ */
+interface EntityDelegateContext {
+    scene: ZylemScene;
+    world: ZylemWorld;
+    renderStrategy: RenderStrategyManager | null;
+    /** Resolved camera for entity setup contexts. */
+    camera: ZylemCamera;
+}
+/**
+ * Delegate responsible for entity spawning, tracking, queuing, removal, and lookup.
+ *
+ * Owns all entity-related state and exposes it to ZylemStage for orchestration
+ * and to external consumers (debug delegate, transform system) via public getters.
+ */
+declare class StageEntityDelegate {
+    private static readonly EMPTY_BEHAVIOR_LINKS;
+    /** Entities queued before load completes. */
+    children: BaseNode[];
+    /** UUID → BaseNode map of all live entities. */
+    readonly childrenMap: Map<string, BaseNode>;
+    /** UUID → BaseNode map populated when debug mode is active. */
+    readonly debugMap: Map<string, BaseNode>;
+    private pendingEntities;
+    private pendingPromises;
+    private _isLoaded;
+    private entityAddedHandlers;
+    /** ECS behavior systems auto-registered from entity refs or manually added. */
+    readonly behaviorSystems: BehaviorSystem[];
+    readonly behaviorSystemByKey: Map<symbol, BehaviorSystem>;
+    readonly registeredSystemKeys: Set<symbol>;
+    readonly behaviorEntityIndex: Map<symbol, Set<BehaviorEntityLink>>;
+    private readonly behaviorLinksByUuid;
+    private scene;
+    private world;
+    private renderStrategy;
+    private camera;
+    /**
+     * The behaviors runtime adapter backing the world's Simulation; shared with
+     * descriptor `systemFactory` calls as `ctx.wasmStage`.
+     */
+    wasmStage: BehaviorRuntime | null;
+    private loadingDelegate;
+    private entityModelDelegate;
+    constructor(loadingDelegate: StageLoadingDelegate, entityModelDelegate: StageEntityModelDelegate);
+    get isLoaded(): boolean;
+    set isLoaded(value: boolean);
+    /**
+     * Bind runtime context after scene and world are initialized.
+     * Must be called before any spawn/enqueue operations.
+     */
+    attach(context: EntityDelegateContext): void;
+    /**
+     * Create, register, and add an entity to the scene/world.
+     * Safe to call only after `attach` when scene/world exist.
+     */
+    spawnEntity(child: BaseNode): Promise<void>;
+    handleLateModelReady(entity: GameEntity<any>): void;
+    /**
+     * Register an entity for bundle or instanced rendering when opted in via
+     * `category: 'environment'` or `category: 'pack'`.
+     */
+    private tryRegisterRenderStrategy;
+    /**
+     * Environment bundles require static bodies. Force static collision and
+     * patch any already-built body description.
+     */
+    private ensureEnvironmentStatic;
+    private maybeAttachEntityPhysics;
+    /** Add the entity to internal maps and notify listeners. */
+    addEntityToStage(entity: BaseNode): void;
+    /**
+     * Remove an entity and its resources by its UUID.
+     * @returns true if removed, false if not found or stage not ready
+     */
+    removeEntityByUuid(uuid: string): boolean;
+    /** Get an entity by its name; returns null if not found. */
+    getEntityByName(name: string): BaseNode | null;
+    /** Build a serializable state snapshot for an entity. */
+    buildEntityState(child: BaseNode): Partial<BaseEntityInterface>;
+    /**
+     * Subscribe to entity-added events.
+     * @param callback Invoked for each entity when added
+     * @param options.replayExisting If true and stage already loaded, replays existing entities
+     * @returns Unsubscribe function
+     */
+    onEntityAdded(callback: (entity: BaseNode) => void, options?: {
+        replayExisting?: boolean;
+    }): () => void;
+    /**
+     * Enqueue items to be spawned. Items can be:
+     * - BaseNode instances (immediate or deferred until load)
+     * - Factory functions returning BaseNode or Promise<BaseNode>
+     * - Promises resolving to BaseNode
+     */
+    enqueue(...items: StageEntityInput[]): void;
+    private handleEntityImmediatelyOrQueue;
+    private handlePromiseWithSpawnOnResolve;
+    /** Yields to the event loop via MessageChannel (~0.1ms vs ~4ms for setTimeout). */
+    private yieldToEventLoop;
+    /**
+     * Spawns all queued entities, awaiting each attach before the stage is
+     * marked loaded so the game loop never steps wasm while bodies are still
+     * being added. Yields to the event loop in batches for loading UI updates.
+     */
+    runEntityLoadGenerator(): Promise<void>;
+    /**
+     * Register an ECS behavior system to run each frame.
+     * @param systemOrFactory A BehaviorSystem instance or factory function
+     */
+    registerSystem(systemOrFactory: BehaviorSystem | BehaviorSystemFactory): void;
+    /**
+     * Destroy all entities and clear internal state.
+     * Called by ZylemStage._destroy().
+     */
+    destroyAll(): void;
+    private registerBehaviorLinks;
+    private unregisterBehaviorLinks;
+}
+
+/**
+ * The runtime heart of a loaded stage.
+ *
+ * `ZylemStage` is the disposable per-load object that actually owns and drives
+ * the scene, physics world, cameras, optional wasm runtime, and the suite of
+ * delegates (entity, camera, loading, model, debug). It parses options into
+ * config, builds scene/world during `load()`, runs the per-frame update loop
+ * (physics step, behavior systems, entity updates, transform sync, camera
+ * updates, render), and tears everything down on destroy. The author-facing
+ * `Stage` wraps and recreates one of these on each load.
+ */
+
+interface ZylemStageConfig {
+    inputs: Record<string, string[]>;
+    backgroundColor: Color | string;
+    backgroundImage: string | null;
+    backgroundShader: any | null;
+    gravity: Vector3 | Vec3Components;
+    variables: Record<string, any>;
+    /** Physics update rate in Hz (default 60). */
+    physicsRate: number;
+    /** Optional runtime loader configuration for stage-managed assets. */
+    assetLoaders?: StageAssetLoaderConfig;
+    /**
+     * When `false`, suppress the engine's built-in ambient + directional
+     * lights so the stage owns its lighting rig entirely (usually via
+     * `createLight(...)` entities). Defaults to `true`.
+     */
+    defaultLighting: boolean;
+    /**
+     * Postprocessing effects applied in order between the scene pass and the
+     * display output (e.g. effects from `@zylem/shaders`). Only active for
+     * single fullscreen-camera rendering.
+     */
+    postProcessingEffects?: ZylemPostEffect[];
+    stageRef?: Stage;
+}
+type StageOptionItem = Partial<ZylemStageConfig> | CameraWrapper | StageEntityInput;
+type StageOptions = [] | [Partial<ZylemStageConfig>, ...StageOptionItem[]];
+type StageState = ZylemStageConfig & {
+    entities: GameEntityInterface[];
+};
+/**
+ * ZylemStage orchestrates scene, physics world, entities, and lifecycle.
+ *
+ * Responsibilities:
+ * - Manage stage configuration (background, inputs, gravity, variables)
+ * - Initialize and own `ZylemScene` and `ZylemWorld`
+ * - Coordinate delegates for entities, camera, loading, debug, and models
+ * - Drive per-frame updates and transform system
+ */
+declare class ZylemStage extends LifeCycleBase<ZylemStage> {
+    type: string;
+    state: StageState;
+    gravity: Vector3 | Vec3Components;
+    world: ZylemWorld | null;
+    scene: ZylemScene | null;
+    renderStrategy: RenderStrategyManager | null;
+    debugDelegate: StageDebugDelegate | null;
+    uuid: string;
+    wrapperRef: Stage | null;
+    camera?: CameraWrapper;
+    cameras: CameraWrapper[];
+    cameraRef?: ZylemCamera | null;
+    /** Camera manager for multi-camera support */
+    cameraManagerRef: CameraManager | null;
+    /** Shared renderer manager (injected by the game) */
+    rendererManager: RendererManager | null;
+    private cameraDelegate;
+    private loadingDelegate;
+    private entityModelDelegate;
+    private readonly childUpdateParams;
+    /** Entity management delegate — public for external consumers (debug, transform system). */
+    readonly entityDelegate: StageEntityDelegate;
+    /**
+     * Create a new stage.
+     * @param options Stage options: partial config, camera, and initial entities or factories
+     */
+    constructor(options?: StageOptions);
+    private setState;
+    /**
+     * Resolve the active renderer, preferring the shared renderer manager and
+     * falling back to the camera's own renderer.
+     */
+    private resolveRenderer;
+    /**
+     * Load and initialize the stage's scene and world.
+     * Uses generator pattern to yield control to event loop for real-time progress.
+     * @param id DOM element id for the renderer container
+     * @param camera Optional camera override
+     */
+    load(id: string, camera?: ZylemCamera | null, rendererManager?: RendererManager | null): Promise<void>;
+    /**
+     * Idempotency guard for `_setup`. The initial stage is currently set up
+     * twice — once when `ZylemGame.loadStage` runs for non-initial stages
+     * (so every stage gets a `StageDebugDelegate`, stage.onSetup callbacks,
+     * etc.), and once from `ZylemGame.start()` for the very first stage.
+     * Keeping a flag here lets both call sites invoke `stage.start(...)`
+     * safely; the second call is a no-op.
+     */
+    hasSetup: boolean;
+    protected _setup(params: SetupContext<ZylemStage>): void;
+    protected _update(params: UpdateContext<ZylemStage>): void;
+    outOfLoop(): void;
+    /** Update debug overlays and helpers if enabled. */
+    debugUpdate(): void;
+    /** Cleanup owned resources when the stage is destroyed. */
+    protected _destroy(params: DestroyContext<ZylemStage>): void;
+    /** Forward to entity delegate. */
+    spawnEntity(child: BaseNode): Promise<void>;
+    /** Forward to entity delegate. */
+    buildEntityState(child: BaseNode): Partial<BaseEntityInterface>;
+    /** Forward to entity delegate. */
+    onEntityAdded(callback: (entity: BaseNode) => void, options?: {
+        replayExisting?: boolean;
+    }): () => void;
+    onLoading(callback: (event: LoadingEvent) => void): () => void;
+    /**
+     * Register an ECS behavior system to run each frame.
+     * @param systemOrFactory A BehaviorSystem instance or factory function
+     * @returns this for chaining
+     */
+    registerSystem(systemOrFactory: BehaviorSystem | BehaviorSystemFactory): this;
+    /** Forward to entity delegate. */
+    removeEntityByUuid(uuid: string): boolean;
+    /** Forward to entity delegate. */
+    getEntityByName(name: string): BaseNode<any, any> | null;
+    /** Forward to entity delegate. */
+    enqueue(...items: StageEntityInput[]): void;
+    logMissingEntities(): void;
+    /** Add a camera to this stage's camera manager. */
+    addCamera(camera: ZylemCamera, name?: string): string | null;
+    /** Remove a camera from this stage's camera manager. */
+    removeCamera(nameOrRef: string | ZylemCamera): boolean;
+    /** Set the active camera by name or reference. */
+    setActiveCamera(nameOrRef: string | ZylemCamera): boolean;
+    /** Get a camera by name from the camera manager. */
+    getCamera(name: string): ZylemCamera | null;
+    /** Resize renderer viewport. */
+    resize(width: number, height: number): void;
+}
+
+/**
+ * The user-facing stage handle and its fluent authoring API.
+ *
+ * `Stage` is the durable, author-time wrapper game code holds onto: it stores
+ * options, pending entities, and lifecycle/loading callbacks, then constructs
+ * and drives a fresh internal `ZylemStage` on each `load()`. Exists to give a
+ * stable, ergonomic surface (`add`, `onSetup/onUpdate/onDestroy`, camera, input,
+ * and event helpers) that survives stage reloads, while `ZylemStage` owns the
+ * disposable per-load runtime. `createStage(...)` is the entry point.
+ */
+
+type NodeLike = {
+    create: Function;
+};
+type AnyNode = NodeLike | Promise<NodeLike>;
+type EntityInput = AnyNode | (() => AnyNode) | (() => Promise<any>);
+declare class Stage {
+    wrappedStage: ZylemStage | null;
+    options: StageOptionItem[];
+    private _pendingEntities;
+    private setupCallbacks;
+    private updateCallbacks;
+    private destroyCallbacks;
+    private pendingLoadingCallbacks;
+    private eventDelegate;
+    /** Per-stage input configuration overrides. Merged with game-level defaults on stage load. */
+    inputConfig: GameInputConfig | null;
+    /**
+     * Callback set by the game to trigger input reconfiguration
+     * when this stage's input config changes at runtime.
+     * @internal
+     */
+    onInputConfigChanged: (() => void) | null;
+    constructor(options: StageOptions);
+    /**
+     * Set composable input configuration for this stage.
+     * Multiple configs are deep-merged (later configs win on key conflicts).
+     * If this stage is currently active, the change takes effect immediately.
+     * @example stage.setInputConfiguration(useArrowsForAxes('p1'), useWASDForDirections('p2'));
+     */
+    setInputConfiguration(...configs: GameInputConfig[]): this;
+    load(id: string, camera?: ZylemCamera | CameraWrapper | null, rendererManager?: RendererManager | null): Promise<void>;
+    private applyLifecycleCallbacks;
+    addEntities(entities: BaseNode[]): Promise<void>;
+    add(...inputs: Array<EntityInput>): void;
+    private addToBlueprints;
+    private addToStage;
+    start(params: SetupContext<ZylemStage>): void;
+    onUpdate(...callbacks: UpdateFunction<ZylemStage>[]): this;
+    onSetup(...callbacks: SetupFunction<ZylemStage>[]): this;
+    onDestroy(...callbacks: DestroyFunction<ZylemStage>[]): this;
+    onLoading(callback: (event: LoadingEvent) => void): () => void;
+    /**
+     * Find an entity by name on the current stage.
+     * @param name The name of the entity to find
+     * @param type Optional type symbol for type inference (e.g., TEXT_TYPE, SPRITE_TYPE)
+     * @returns The entity if found, or undefined
+     * @example stage.getEntityByName('scoreText', TEXT_TYPE)
+     */
+    getEntityByName<T extends symbol | void = void>(name: string, type?: T): T extends keyof EntityTypeMap ? EntityTypeMap[T] | undefined : BaseNode | undefined;
+    /**
+     * Add a camera to this stage.
+     * @param camera The ZylemCamera or CameraWrapper to add
+     * @param name Optional name for lookup
+     */
+    addCamera(camera: ZylemCamera | CameraWrapper, name?: string): string | null;
+    /**
+     * Remove a camera from this stage by name or reference.
+     */
+    removeCamera(nameOrRef: string | ZylemCamera | CameraWrapper): boolean;
+    /**
+     * Set the active camera by name or reference.
+     */
+    setActiveCamera(nameOrRef: string | ZylemCamera | CameraWrapper): boolean;
+    /**
+     * Get a camera by name from the camera manager.
+     */
+    getCamera(name: string): ZylemCamera | null;
+    /**
+     * Dispatch an event from the stage.
+     * Events are emitted both locally and to the global event bus.
+     */
+    dispatch<K extends keyof StageEvents>(event: K, payload: StageEvents[K]): void;
+    /**
+     * Listen for events on this stage instance.
+     * @returns Unsubscribe function
+     */
+    listen<K extends keyof StageEvents>(event: K, handler: (payload: StageEvents[K]) => void): () => void;
+    /**
+     * Clean up stage resources including event subscriptions.
+     */
+    dispose(): void;
+}
+/**
+ * Create a stage with optional camera
+ */
+declare function createStage(...options: StageOptions): Stage;
+
+/**
+ * Stage state interface - minimal to prevent circular dependencies
+ */
+interface StageStateInterface {
+    backgroundColor: Color;
+    backgroundImage: string | null;
+    inputs: {
+        p1: string[];
+        p2: string[];
+    };
+    variables: Record<string, any>;
+    gravity: Vector3 | Vec3Components;
+    entities: Partial<BaseEntityInterface>[];
+    stageRef?: any;
+}
+/**
+ * Minimal stage interface to break circular dependencies
+ */
+interface StageInterface {
+    uuid: string;
+    children: any[];
+    state: StageStateInterface;
+}
+
+declare const AspectRatio: {
+    readonly FourByThree: number;
+    readonly SixteenByNine: number;
+    readonly NineBySixteen: number;
+    readonly TwentyOneByNine: number;
+    readonly OneByOne: number;
+};
+type AspectRatioValue = (typeof AspectRatio)[keyof typeof AspectRatio] | number;
+/**
+ * AspectRatioDelegate manages sizing a canvas to fit within a container
+ * while preserving a target aspect ratio. It notifies a consumer via
+ * onResize when the final width/height are applied so renderers/cameras
+ * can update their viewports.
+ */
+declare class AspectRatioDelegate {
+    container: HTMLElement;
+    canvas: HTMLCanvasElement;
+    aspectRatio: number;
+    onResize?: (width: number, height: number) => void;
+    private handleResizeBound;
+    private resizeObserver;
+    constructor(params: {
+        container: HTMLElement;
+        canvas: HTMLCanvasElement;
+        aspectRatio: AspectRatioValue;
+        onResize?: (width: number, height: number) => void;
+    });
+    /** Attach window resize listener and apply once. */
+    attach(): void;
+    /** Detach window resize listener. */
+    detach(): void;
+    /** Compute the largest size that fits container while preserving aspect. */
+    measure(): {
+        width: number;
+        height: number;
+    };
+    /** Apply measured size to canvas and notify. */
+    apply(): void;
+}
+
+interface ViewportSize {
+    width: number;
+    height: number;
+}
+
+type RetroResolution = {
+    key: string;
+    width: number;
+    height: number;
+    notes?: string;
+};
+type RetroPreset = {
+    displayAspect: number;
+    resolutions: RetroResolution[];
+};
+/**
+ * Retro, console, and device display presets.
+ * displayAspect represents the intended display aspect (letterboxing target),
+ * not necessarily the raw pixel aspect of internal buffers.
+ */
+declare const RetroPresets: Record<string, RetroPreset>;
+type RetroPresetKey = keyof typeof RetroPresets;
+declare function getDisplayAspect(preset: RetroPresetKey): number;
+declare function getPresetResolution(preset: RetroPresetKey, key?: string): RetroResolution | undefined;
+declare function parseResolution(text: string): {
+    width: number;
+    height: number;
+} | null;
+
+/**
+ * Resolution descriptor for the game's internal render buffer.
+ *  - `string` : a "WxH" literal or a known retro preset (e.g. `'NES'`).
+ *  - `{ width, height }` : explicit pixel dimensions.
+ *  - `'native'` : skip internal-resolution scaling — render at the
+ *    canvas' CSS size × DPR (i.e. 1:1 with the device viewport).
+ */
+type ResolutionInput = string | {
+    width: number;
+    height: number;
+} | 'native';
+type DeviceProfile = 'auto' | 'desktop' | 'mobile';
+interface ResolveGameConfigRuntime {
+    deviceProfile?: DeviceProfile;
+    viewportSize?: ViewportSize;
+}
+type GameDeviceConfig = Partial<{
+    /** numeric value or key in AspectRatio */
+    aspectRatio: AspectRatioValue | keyof typeof AspectRatio;
+    /** console/display preset to derive aspect ratio */
+    preset: RetroPresetKey;
+    /** lock internal render buffer for this device profile */
+    resolution: ResolutionInput;
+    /**
+     * Auto-merge built-in virtual touch controls into the resolved input
+     * config. The provider auto-enables on mobile devices via
+     * `enabled: 'auto'`, so on desktop runtimes the UI stays dormant.
+     *  - `true`         : default joystick + A/B layout, default theme.
+     *  - options object : forwarded to `defaultTouchControls('p1', ...)`.
+     *  - `false` / unset: no auto-injection (caller wires controls manually).
+     */
+    controls: boolean | DefaultTouchControlsOptions;
+}>;
+type GameConfigLike = Partial<{
+    id: string;
+    globals: Record<string, any>;
+    stages: StageInterface[];
+    debug: boolean;
+    time: number;
+    input: GameInputConfig;
+    /** numeric value or key in AspectRatio */
+    aspectRatio: AspectRatioValue | keyof typeof AspectRatio;
+    /** console/display preset to derive aspect ratio */
+    preset: RetroPresetKey;
+    /** lock internal render buffer to this desktop/default resolution */
+    resolution: ResolutionInput;
+    /** mobile-specific aspect/preset/resolution overrides */
+    mobile: GameDeviceConfig;
+    fullscreen: boolean;
+    /** CSS background value for document body */
+    bodyBackground: string;
+    /** existing container by reference */
+    container: HTMLElement;
+    /** create/find container by id */
+    containerId: string;
+    /** optional canvas if caller wants to manage it */
+    canvas: HTMLCanvasElement;
+}>;
+declare class GameConfig {
+    id: string;
+    globals: Record<string, any>;
+    stages: StageInterface[];
+    debug: boolean;
+    time: number;
+    input: GameInputConfig | undefined;
+    aspectRatio: number;
+    internalResolution: {
+        width: number;
+        height: number;
+    } | undefined;
+    fullscreen: boolean;
+    bodyBackground: string | undefined;
+    container: HTMLElement;
+    containerId?: string | undefined;
+    canvas?: HTMLCanvasElement | undefined;
+    constructor(id: string, globals: Record<string, any>, stages: StageInterface[], debug: boolean, time: number, input: GameInputConfig | undefined, aspectRatio: number, internalResolution: {
+        width: number;
+        height: number;
+    } | undefined, fullscreen: boolean, bodyBackground: string | undefined, container: HTMLElement, containerId?: string | undefined, canvas?: HTMLCanvasElement | undefined);
+}
+/**
+ * Factory for authoring configuration objects in user code.
+ * Returns a plain object that can be passed to `game(...)`.
+ */
+declare function gameConfig(config: GameConfigLike): GameConfigLike;
+
+interface GameCanvasOptions {
+    id: string;
+    container?: HTMLElement;
+    containerId?: string;
+    canvas?: HTMLCanvasElement;
+    bodyBackground?: string;
+    fullscreen?: boolean;
+    aspectRatio: AspectRatioValue | number;
+}
+/**
+ * GameCanvas is a DOM delegate that owns:
+ * - container lookup/creation and styling (including fullscreen centering)
+ * - body background application
+ * - canvas mounting into container
+ * - aspect ratio sizing via AspectRatioDelegate
+ */
+declare class GameCanvas {
+    id: string;
+    container: HTMLElement;
+    canvas: HTMLCanvasElement;
+    bodyBackground?: string;
+    fullscreen: boolean;
+    aspectRatio: number;
+    private ratioDelegate;
+    private overlayContainer;
+    constructor(options: GameCanvasOptions);
+    applyBodyBackground(): void;
+    mountCanvas(): void;
+    mountRenderer(rendererDom: HTMLCanvasElement, onResize: (width: number, height: number) => void): void;
+    getOverlayContainer(): HTMLElement;
+    centerIfFullscreen(): void;
+    attachAspectRatio(onResize: (width: number, height: number) => void): void;
+    setAspectRatio(aspectRatio: number): void;
+    reapplyLayout(): void;
+    destroy(): void;
+    private mountChildren;
+    private ensureOverlayContainer;
+    private ensureContainer;
+}
+
+/**
+ * Game-level loading event that includes stage context.
+ */
+interface GameLoadingEvent {
+    type: 'start' | 'progress' | 'complete';
+    stageName?: string;
+    stageIndex?: number;
+    message: string;
+    progress: number;
+    current?: number;
+    total?: number;
+}
+
+type ZylemGameOptions<TGlobals extends BaseGlobals> = ZylemGameConfig<Stage, ZylemGame<TGlobals>, TGlobals> & Partial<GameConfig>;
+declare class ZylemGame<TGlobals extends BaseGlobals> {
+    id: string;
+    initialGlobals: TGlobals;
+    customSetup: ((params: SetupContext<ZylemGame<TGlobals>, TGlobals>) => void) | null;
+    customUpdate: ((params: UpdateContext<ZylemGame<TGlobals>, TGlobals>) => void) | null;
+    customDestroy: ((params: DestroyContext<ZylemGame<TGlobals>, TGlobals>) => void) | null;
+    stages: Stage[];
+    stageMap: Map<string, Stage>;
+    currentStageId: string;
+    previousTimeStamp: number;
+    totalTime: number;
+    timer: Timer;
+    inputManager: InputManager;
+    wrapperRef: Game<TGlobals>;
+    globalInputConfig: GameInputConfig | undefined;
+    defaultCamera: ZylemCamera | null;
+    /** Shared renderer manager for all stages */
+    rendererManager: RendererManager | null;
+    container: HTMLElement | null;
+    canvas: HTMLCanvasElement | null;
+    aspectRatioDelegate: AspectRatioDelegate | null;
+    resolvedConfig: GameConfig | null;
+    gameCanvas: GameCanvas | null;
+    private animationFrameId;
+    private isDisposed;
+    /**
+     * True while a `loadStage` is in progress. Used to reject re-entrant stage
+     * navigation (e.g. a button press during a transition), which would race
+     * two loads on `stageMap`/the render loop and, because `currentStageId` is
+     * transiently `''`, misresolve the target stage.
+     */
+    private loadInFlight;
+    /**
+     * True once `start()` has been invoked for this game's initial stage.
+     * Used by `loadStage` to decide whether to drive the stage's `_setup`
+     * lifecycle directly (for subsequent stages loaded via `nextStage`
+     * / `loadStage`) or defer to `start()` (for the very first stage).
+     */
+    private hasStarted;
+    private debugDelegate;
+    private loadingDelegate;
+    private rendererObserver;
+    private eventBusUnsubscribes;
+    private thumbnailUnsubscribes;
+    /**
+     * Trailing-debounce timer for entity-driven state dispatches. Building a
+     * `state:dispatch` payload is O(entities) (and downstream editor stores
+     * re-proxy/reconcile every entity), so bursts of thumbnail/destroy events
+     * must coalesce into a single dispatch instead of one per entity.
+     */
+    private entityDispatchTimer;
+    private pendingEntityDispatchPath;
+    /** Debounce window (ms) for coalescing entity-driven state dispatches. */
+    private static readonly ENTITY_DISPATCH_DEBOUNCE_MS;
+    private readonly gameUpdateParams;
+    private readonly stageSetupParams;
+    private readonly stageUpdateParams;
+    private readonly frameCallback;
+    private readonly sourceOptions;
+    private displayRuntime;
+    static FRAME_LIMIT: number;
+    static FRAME_DURATION: number;
+    static MAX_DELTA_SECONDS: number;
+    constructor(options: ZylemGameOptions<TGlobals>, wrapperRef: Game<TGlobals>, displayRuntime?: ResolveGameConfigRuntime);
+    setDisplayRuntime(runtime: ResolveGameConfigRuntime): void;
+    loadGameCanvas(config: GameConfig): void;
+    loadDebugOptions(options: ZylemGameOptions<TGlobals>): void;
+    /** Whether a stage load is currently in progress. */
+    isLoading(): boolean;
+    loadStage(stage: Stage, stageIndex?: number, transition?: StageTransitionConfig): Promise<void>;
+    private performLoadStage;
+    /**
+     * Merges game-level global input config with the stage's per-stage overrides
+     * and reconfigures the InputManager.
+     */
+    applyInputConfig(stage: Stage): void;
+    /**
+     * Update the game-level global input config and re-apply to the current stage.
+     */
+    setGlobalInputConfig(config: GameInputConfig): void;
+    unloadCurrentStage(): void;
+    setGlobals(options: ZylemGameConfig<Stage, ZylemGame<TGlobals>, TGlobals>): void;
+    params(): UpdateContext<ZylemGame<TGlobals>, TGlobals>;
+    start(): void;
+    /**
+     * Execute a single frame update.
+     * This method can be called directly for testing or from the game loop.
+     * @param deltaTime Optional delta time in seconds. If not provided, uses timer delta.
+     */
+    step(deltaTime?: number): void;
+    loop(timestamp: number): void;
+    dispose(): void;
+    outOfLoop(): void;
+    getStage(id: string): Stage | undefined;
+    currentStage(): Stage | undefined;
+    /**
+     * Subscribe to loading events from the game.
+     * Events include stage context (stageName, stageIndex).
+     * @param callback Invoked for each loading event
+     * @returns Unsubscribe function
+     */
+    onLoading(callback: (event: GameLoadingEvent) => void): () => void;
+    /**
+     * Build the stage config payload for the current stage.
+     */
+    private buildStageConfigPayload;
+    /**
+     * Build the entities payload for the current stage.
+     */
+    private buildEntitiesPayload;
+    /**
+     * Generate entity thumbnails as entities become available, then refresh editor state.
+     */
+    private wireEntityThumbnails;
+    private clearEntityThumbnailWiring;
+    /**
+     * Coalesce entity-driven state dispatches (thumbnail resolutions, entity
+     * destruction) into one trailing `emitStateDispatch` per burst.
+     */
+    private queueEntityStateDispatch;
+    /**
+     * Emit a state:dispatch event to the zylemEventBus.
+     * Called after stage load and on global state changes.
+     */
+    private emitStateDispatch;
+    /**
+     * Subscribe to the game event bus for stage loading and state events.
+     * Emits events to zylemEventBus for cross-package communication.
+     */
+    private subscribeToEventBus;
+}
+
+type GameOptions<TGlobals extends BaseGlobals> = Array<ZylemGameConfig<Stage, any, TGlobals> | GameConfigLike | Stage | GameEntityLifeCycle | BaseNode>;
+
+declare class Game<TGlobals extends BaseGlobals> implements IGame<TGlobals> {
+    private wrappedGame;
+    options: GameOptions<TGlobals>;
+    private setupCallbacks;
+    private updateCallbacks;
+    private destroyCallbacks;
+    private pendingLoadingCallbacks;
+    private globalChangeCallbacks;
+    private globalChangesCallbacks;
+    private activeGlobalSubscriptions;
+    private eventDelegate;
+    /** Pending global input config set before the game starts. */
+    private pendingInputConfig;
+    private displayRuntime;
+    refErrorMessage: string;
+    constructor(options: GameOptions<TGlobals>);
+    onSetup(...callbacks: Array<SetupFunction<ZylemGame<TGlobals>, TGlobals>>): this;
+    onUpdate(...callbacks: Array<UpdateFunction<ZylemGame<TGlobals>, TGlobals>>): this;
+    onDestroy(...callbacks: Array<DestroyFunction<ZylemGame<TGlobals>, TGlobals>>): this;
+    /**
+     * Set composable input configuration as global defaults for the entire game.
+     * Multiple configs are deep-merged (later configs win on key conflicts).
+     * Per-stage overrides (via stage.setInputConfiguration) are merged on top.
+     * Can be called before or after start().
+     * @example game.setInputConfiguration(useArrowsForAxes('p1'), useWASDForDirections('p2'));
+     */
+    setInputConfiguration(...configs: GameInputConfig[]): this;
+    start(): Promise<this>;
+    setDisplayRuntime(runtime: Partial<ResolveGameConfigRuntime>): this;
+    setDeviceProfile(profile: DeviceProfile): this;
+    setViewportSize(width: number, height: number): this;
+    private load;
+    private setOverrides;
+    /**
+     * Subscribe to changes on a global value. Subscriptions are registered
+     * when the game starts and cleaned up when disposed.
+     * The callback receives the value and the current stage.
+     * @example game.onGlobalChange('score', (val, stage) => console.log(val));
+     */
+    onGlobalChange<T = unknown>(path: string, callback: (value: T, stage: Stage | null) => void): this;
+    /**
+     * Subscribe to changes on multiple global paths. Subscriptions are registered
+     * when the game starts and cleaned up when disposed.
+     * The callback receives the values and the current stage.
+     * @example game.onGlobalChanges(['score', 'lives'], ([score, lives], stage) => console.log(score, lives));
+     */
+    onGlobalChanges<T extends unknown[] = unknown[]>(paths: string[], callback: (values: T, stage: Stage | null) => void): this;
+    /**
+     * Register all stored global change callbacks.
+     * Called internally during start().
+     */
+    private registerGlobalSubscriptions;
+    /**
+     * Get the current stage wrapper.
+     */
+    getCurrentStage(): Stage | null;
+    /**
+     * Experimental escape hatches. APIs here are unstable and may change or be
+     * removed without a major version bump.
+     */
+    readonly experimental: {
+        /**
+         * The `@zylem/behaviors` {@link Simulation} backing the current stage's
+         * physics world, or `null` before a stage is loaded. Intended for debug
+         * tooling and the editor; games should not need it.
+         */
+        getRuntime: () => Simulation | null;
+    };
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    /**
+     * Execute a single frame update.
+     * Useful for testing or manual frame stepping.
+     * @param deltaTime Optional delta time in seconds (defaults to 1/60)
+     */
+    step(deltaTime?: number): void;
+    /**
+     * Reload the first stage. Pass `{ transition }` to blend from the current
+     * stage instead of cutting.
+     * @example game.reset({ transition: { duration: 1 } });
+     */
+    reset(options?: StageNavigationOptions): Promise<void>;
+    /**
+     * Go to the previous stage in the stage array. Pass `{ transition }` to
+     * blend from the current stage instead of cutting.
+     */
+    previousStage(options?: StageNavigationOptions): void;
+    loadStageFromId(stageId: string): Promise<void>;
+    /**
+     * Go to the next stage. Pass `{ transition }` to blend from the current
+     * stage instead of cutting.
+     * @example
+     * game.nextStage({
+     *   transition: { duration: 1.2, shader: createStageTransition({ pattern: 'noise' }) },
+     * });
+     */
+    nextStage(options?: StageNavigationOptions): void;
+    goToStage(): Promise<void>;
+    end(): Promise<void>;
+    dispose(): void;
+    /**
+     * Dispatch an event from the game.
+     * Events are emitted both locally and to the global event bus.
+     */
+    dispatch<K extends keyof GameEvents>(event: K, payload: GameEvents[K]): void;
+    /**
+     * Listen for events on this game instance.
+     * @returns Unsubscribe function
+     */
+    listen<K extends keyof GameEvents>(event: K, handler: (payload: GameEvents[K]) => void): () => void;
+    /**
+     * Subscribe to loading events from the game.
+     * Events include stage context (stageName, stageIndex).
+     * @param callback Invoked for each loading event
+     * @returns Unsubscribe function
+     */
+    onLoading(callback: (event: GameLoadingEvent) => void): () => void;
+}
+/**
+ * create a new game
+ * @param options GameOptions - Array of IGameOptions, Stage, GameEntity, or BaseNode objects
+ * @param options.id Game name string (when using IGameOptions)
+ * @param options.globals Game globals object (when using IGameOptions)
+ * @param options.stages Array of stage objects (when using IGameOptions)
+ * @returns Game
+ */
+declare function createGame<TGlobals extends BaseGlobals>(...options: GameOptions<TGlobals>): Game<TGlobals>;
+
+export { AspectRatio as A, Stage as B, CameraWrapper as C, type DeviceProfile as D, type StageStateInterface as E, Fixed2DPerspective as F, Game as G, type PerspectiveOptions as P, type ResolutionInput as R, type StageConfigLike as S, ThirdPersonPerspective as T, type GameLoadingEvent as a, type GameConfigLike as b, createGame as c, type GameDeviceConfig as d, type ResolveGameConfigRuntime as e, createStage as f, gameConfig as g, type StageOptions as h, createCamera as i, type CameraOptions as j, CameraManager as k, FirstPersonPerspective as l, createPerspective as m, type ThirdPersonOptions as n, type Fixed2DOptions as o, type FirstPersonOptions as p, type AspectRatioValue as q, getDisplayAspect as r, stageConfig as s, getPresetResolution as t, parseResolution as u, type RetroPreset as v, type RetroPresetKey as w, type RetroResolution as x, RenderBundleManager as y, RenderStrategyManager as z };