@zylem/game-lib 0.7.0 → 0.8.2

package/dist/{game-Cuj5gy7U.d.ts → game-DbqBQiFC.d.ts}

@@ -1,15 +1,16 @@
-import { d as InputPlayerNumber, e as InputProvider, a as Inputs, U as UpdateFunction, h as SetupFunction, j as DestroyFunction, S as SetupContext, f as UpdateContext, D as DestroyContext, g as LoadingEvent, l as IGame } from './base-node-life-cycle-CnJ-7zX-.js';
-import { G as GameInputConfig, B as BaseGlobals, Z as ZylemGameConfig } from './game-interfaces-tfpM5NBk.js';
-import { G as GameEntity, I as GameEntityOptions, W as WasmStageRuntimeOptions, M as BaseNode, p as WasmStageRuntime, _ as GameEntityLifeCycle } from './entity-DNkYKfdp.js';
-import { Object3D, BufferGeometry, Material, Group, Vector3, Texture, Color } from 'three';
-import { S as StageEntity, Z as ZylemWorld } from './world-C9zdyl5d.js';
-import { k as CameraPerspective, j as CameraContext, g as CameraPose, P as PerspectiveType, o as ZylemCamera, C as CameraBehavior, l as CameraAction, m as CameraPipelineState, e as RendererType, V as Viewport, S as StageRuntimeAdapter, R as RuntimeDebugBinding, p as ZylemScene, f as CameraManager, q as RendererManager } from './zylem-stage-runtime-Cs-UDEVU.js';
-import { RigidBody, Collider } from '@dimforge/rapier3d-compat';
-import { a as Vec3Input, b as Vec2Input, o as ZylemShader, V as Vec3Components } from './material-Wz83vTTp.js';
-import { BehaviorSystem, BehaviorEntityLink, BehaviorSystemFactory } from '@zylem/behaviors/core';
-import { ac as EntityTypeMap } from './entity-type-map-C94h2TDW.js';
+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-BK9xebT9.js';
+import { G as GameInputConfig, B as BaseGlobals, Z as ZylemGameConfig } from './game-interfaces-vF5sRi1n.js';
+import { G as GameEntity, a as GameEntityOptions, B as BaseNode, y as GameEntityLifeCycle } from './entity-BGEq1yfC.js';
+import { Scene, Color, Object3D, Vector3, BufferGeometry, Material, Group, Texture } from 'three';
+import { ak as ZylemWorld, ai as EntityTypeMap } from './entity-type-map-CW6RHQkx.js';
+import { E as Entity, L as LifecycleFunction, S as StageEntity } from './entity-B9yZeBm4.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-Du2UPW9O.js';
+import { d as ZylemShader } from './material-DbSuZBbP.js';
+import { l as SimulationBody, e as Vec3Input, b as Vec2Input, d as Vec3Components } from './vector-DN6zlPoE.js';
+import { BehaviorSystem, BehaviorEntityLink, BehaviorRuntime, BehaviorSystemFactory, Simulation } from '@zylem/behaviors/core';
 import { StageEvents, GameEvents } from './events.js';
-import { D as DefaultTouchControlsOptions } from './default-controls-BGc61yYl.js';
+import { D as DefaultTouchControlsOptions } from './default-controls-CAKJ5zlo.js';
+import { S as StageTransitionConfig } from './stage-transition-CmGpV4tc.js';
 
 declare class InputManager {
     private inputMap;
@@ -127,91 +128,315 @@ declare class Timer {
 }
 
 /**
- * Configuration for batch key generation
+ * 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
  */
-interface BatchKeyConfig {
+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;
+    /** Gameplay primary camera saved while the debug camera is active. */
+    private _preDebugPrimary;
+    /** Scene anchor at world origin for debug orbit when nothing is selected. */
+    private _debugOrbitTargetAnchor;
+    /** 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;
+    /**
+     * Gameplay primary camera that was active before debug mode was enabled.
+     */
+    get preDebugPrimary(): 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>;
+    /**
+     * Switch the primary viewport to the debug orbit camera, remembering the
+     * previous primary so gameplay cameras (e.g. first-person) can be restored.
+     */
+    activateDebugCamera(): boolean;
+    /**
+     * Restore the gameplay primary camera that was active before
+     * {@link activateDebugCamera}.
+     */
+    deactivateDebugCamera(): boolean;
+    /**
+     * 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.
+     * Registered for lookup/activation, but not added to the active list.
+     */
+    private createDebugCamera;
+    /**
+     * Seed the debug camera orbit pose on first activation, framing the origin
+     * or offsetting from the saved gameplay primary.
+     */
+    private seedDebugCameraPose;
+    /**
+     * 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 batching for entities
- */
+/** Manages instanced mesh packs for `category: 'pack'` entities */
 declare class InstanceManager {
-    private batches;
-    private entityToBatch;
+    private packs;
+    private entityToPack;
     private scene;
-    /** Default initial capacity for new batches */
+    /** Default initial capacity for new packs */
     static DEFAULT_CAPACITY: number;
-    /** Factor to grow batch when full */
+    /** Factor to grow a pack when full */
     static GROWTH_FACTOR: number;
-    /**
-     * Set the scene to add instanced meshes to
-     */
     setScene(scene: Object3D): void;
-    /**
-     * Generate a batch key from configuration
-     */
-    static generateBatchKey(config: BatchKeyConfig): string;
-    static generateEntityBatchKey(entity: Pick<GameEntity<GameEntityOptions>, 'options' | 'materials'> & {
+    static generatePackKey(config: PackKeyConfig): string;
+    static generateEntityPackKey(entity: Pick<GameEntity<GameEntityOptions>, 'options' | 'materials'> & {
         constructor: any;
     }): string;
     /**
-     * Register an entity with the instance manager
+     * Register an entity with the instance manager.
      * @returns The instance index, or -1 if registration failed
      */
-    register(entity: GameEntity<any>, geometry: BufferGeometry, material: Material, batchKey: string): number;
-    /**
-     * Unregister an entity from the instance manager
-     */
+    register(entity: GameEntity<any>, geometry: BufferGeometry, material: Material, packKey: string): number;
     unregister(entity: GameEntity<any>): void;
-    /**
-     * Mark an entity's transform as dirty (needs syncing)
-     */
     markDirty(entity: GameEntity<any>): void;
     /**
-     * Update all dirty instance transforms
-     * Call this once per frame
+     * Update all active instance transforms.
+     * Call once per frame after the simulation step and render-buffer sync.
      */
-    /**
-     * Update all active instance transforms
-     * Call this once per frame
-     */
-    update(): void;
+    update(interpolationAlpha?: number): void;
     private updateInstanceMatrix;
-    /**
-     * Get batch info for an entity
-     */
-    getBatchInfo(entity: GameEntity<any>): {
-        batchKey: string;
+    getPackInfo(entity: GameEntity<any>): {
+        packKey: string;
         instanceId: number;
     } | null;
-    /**
-     * Get statistics about current batching
-     */
     getStats(): {
-        batchCount: number;
+        packCount: number;
         totalInstances: number;
-        batches: {
+        packs: {
             key: string;
             count: number;
             capacity: number;
         }[];
     };
-    /**
-     * Dispose all batches and release resources
-     */
     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;
     /**
-     * Create a new batch group
+     * Parent the entity's renderable into a static bundle group.
+     * @returns `true` when registration succeeded.
      */
-    private createBatch;
+    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;
     /**
-     * Grow a batch's capacity
+     * Register an entity with the appropriate managed render path.
+     * @returns `true` when the entity was placed into bundle or instanced rendering.
      */
-    private growBatch;
+    register(entity: GameEntity<any>): boolean;
+    unregister(entity: GameEntity<any>): void;
+    update(interpolationAlpha?: number): void;
+    dispose(): void;
 }
 
 /**
@@ -221,8 +446,7 @@ interface BaseEntityInterface {
     uuid: string;
     name: string;
     group: Group | null | undefined;
-    body: RigidBody | null | undefined;
-    collider: Collider | null | undefined;
+    body: SimulationBody | null | undefined;
 }
 /**
  * Game entity interface - minimal interface to break circular dependencies
@@ -430,6 +654,8 @@ declare class FirstPersonPerspective implements CameraPerspective {
     look(deltaYaw: number, deltaPitch: number): void;
     /** Set absolute yaw and pitch. Pitch is clamped to the configured limit. */
     setLook(yaw: number, pitch: number): void;
+    /** Set eye height above the followed target (used when syncing from FirstPersonBehavior). */
+    setEyeHeight(height: number): void;
     /** Current yaw in radians. */
     get yaw(): number;
     /** Current pitch in radians. */
@@ -478,15 +704,6 @@ interface CameraOptions {
     target?: Vec3Input;
     zoom?: number;
     screenResolution?: Vec2Input;
-    /**
-     * Renderer type.
-     *
-     * @deprecated game-lib always renders with WebGPU (Three.js keeps its own
-     * internal WebGL2 fallback for devices without WebGPU). This option is
-     * ignored and retained only for backward compatibility.
-     * @default 'webgpu'
-     */
-    rendererType?: RendererType;
     /**
      * Enable orbital controls for this camera.
      * Can be toggled at runtime via enableOrbitalControls() / disableOrbitalControls().
@@ -626,6 +843,18 @@ declare class CameraWrapper {
  */
 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;
@@ -651,15 +880,22 @@ declare class StageDebugDelegate {
     private domListenersAttached;
     private debugCursor;
     private debugLines;
-    private runtimeDebugLines;
     private cameraDebugDelegate;
     private debugStateUnsubscribe;
+    private focusContextUnregister;
     constructor(stage: ZylemStage, options?: StageDebugDelegateOptions);
+    /** Camera used for debug orbit / raycasts (active primary, usually `__debug__`). */
+    private getDebugViewCamera;
+    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. */
+    /** Initialize DOM listeners and switch rendering to the debug orbit camera. */
     private activate;
-    /** Tear down visuals and camera debug delegate when debug is turned off. */
+    /** Tear down visuals and restore the gameplay primary camera. */
     private deactivate;
+    private rebindPostProcessing;
     private initDebugVisuals;
     private disposeDebugVisuals;
     update(): void;
@@ -669,15 +905,16 @@ declare class StageDebugDelegate {
     private attachDomListeners;
 }
 
-/** Source for the unified-Stage wasm runtime: bytes, fetch URL, or a builder. */
-type StageWasmSource = ArrayBuffer | RequestInfo | URL | (() => Promise<ArrayBuffer | RequestInfo | URL>);
-/** Authoring-side configuration for the unified-Stage wasm runtime. */
-interface StageWasmRuntimeConfig {
-    /** wasm bytes (ArrayBuffer) or a URL/`fetch` input that resolves to bytes. */
-    source: StageWasmSource;
-    /** Forwarded to {@link WasmStageRuntime} construction. */
-    options?: Omit<WasmStageRuntimeOptions, 'imports'>;
-}
+/**
+ * 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;
@@ -698,21 +935,18 @@ type StageConfigLike = Partial<{
     /** Physics update rate in Hz (default 60). */
     physicsRate: number;
     assetLoaders: StageAssetLoaderConfig;
-    runtimeAdapter: StageRuntimeAdapter;
-    /** Binds stage debug policy into wasm runtime adapters (see {@link RuntimeDebugBinding}). */
-    runtimeDebugBinding?: RuntimeDebugBinding;
-    /**
-     * When set, the stage instantiates a {@link WasmStageRuntime} from the given
-     * source during `load()`. Behavior descriptors that have been ported to the
-     * unified-Stage Rust runtime read this via `BehaviorSystemContext.wasmStage`.
-     */
-    wasmRuntime?: StageWasmRuntimeConfig;
     /**
      * 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.
@@ -720,6 +954,16 @@ type StageConfigLike = Partial<{
  */
 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.
@@ -797,6 +1041,17 @@ declare class StageEntityModelDelegate {
     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;
 };
@@ -807,12 +1062,9 @@ type StageEntityInput = NodeLike$1 | Promise<any> | (() => NodeLike$1 | Promise<
 interface EntityDelegateContext {
     scene: ZylemScene;
     world: ZylemWorld;
-    instanceManager: InstanceManager | null;
+    renderStrategy: RenderStrategyManager | null;
     /** Resolved camera for entity setup contexts. */
     camera: ZylemCamera;
-    runtimeAdapter?: StageRuntimeAdapter | null;
-    /** Optional unified-Stage wasm runtime (Phase 2+ of the runtime-only migration). */
-    wasmStage?: WasmStageRuntime | null;
 }
 /**
  * Delegate responsible for entity spawning, tracking, queuing, removal, and lookup.
@@ -840,11 +1092,13 @@ declare class StageEntityDelegate {
     private readonly behaviorLinksByUuid;
     private scene;
     private world;
-    private instanceManager;
+    private renderStrategy;
     private camera;
-    private runtimeAdapter;
-    /** Unified-Stage wasm runtime; shared with descriptor `systemFactory` calls. */
-    wasmStage: WasmStageRuntime | null;
+    /**
+     * 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);
@@ -862,9 +1116,15 @@ declare class StageEntityDelegate {
     spawnEntity(child: BaseNode): Promise<void>;
     handleLateModelReady(entity: GameEntity<any>): void;
     /**
-     * Register an entity for instanced rendering if opted in with `batched: true`.
+     * Register an entity for bundle or instanced rendering when opted in via
+     * `category: 'environment'` or `category: 'pack'`.
      */
-    private tryRegisterInstance;
+    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;
@@ -895,15 +1155,12 @@ declare class StageEntityDelegate {
     enqueue(...items: StageEntityInput[]): void;
     private handleEntityImmediatelyOrQueue;
     private handlePromiseWithSpawnOnResolve;
-    /**
-     * Generator that yields between entity loads for real-time progress updates.
-     */
-    private entityLoadGenerator;
     /** Yields to the event loop via MessageChannel (~0.1ms vs ~4ms for setTimeout). */
     private yieldToEventLoop;
     /**
-     * Runs the entity load generator, yielding to the event loop in batches.
-     * Emits progress events through the loading delegate.
+     * 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>;
     /**
@@ -920,6 +1177,18 @@ declare class StageEntityDelegate {
     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;
@@ -931,22 +1200,18 @@ interface ZylemStageConfig {
     physicsRate: number;
     /** Optional runtime loader configuration for stage-managed assets. */
     assetLoaders?: StageAssetLoaderConfig;
-    /** Optional runtime adapter for wasm-driven simulation/rendering. */
-    runtimeAdapter?: StageRuntimeAdapter;
-    /** Optional debug binding for wasm runtime adapters (heat tint, etc.). */
-    runtimeDebugBinding?: RuntimeDebugBinding;
-    /**
-     * Optional unified-Stage wasm runtime configuration. When set, the stage
-     * instantiates a {@link WasmStageRuntime} during `load()` and exposes it
-     * to behavior systems via `BehaviorSystemContext.wasmStage`.
-     */
-    wasmRuntime?: StageWasmRuntimeConfig;
     /**
      * 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;
@@ -969,9 +1234,7 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     gravity: Vector3 | Vec3Components;
     world: ZylemWorld | null;
     scene: ZylemScene | null;
-    instanceManager: InstanceManager | null;
-    /** Unified-Stage wasm runtime; non-null only when `wasmRuntime` was configured. */
-    wasmStage: WasmStageRuntime | null;
+    renderStrategy: RenderStrategyManager | null;
     debugDelegate: StageDebugDelegate | null;
     uuid: string;
     wrapperRef: Stage | null;
@@ -982,7 +1245,6 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     cameraManagerRef: CameraManager | null;
     /** Shared renderer manager (injected by the game) */
     rendererManager: RendererManager | null;
-    runtimeAdapter: StageRuntimeAdapter | null;
     private cameraDelegate;
     private loadingDelegate;
     private entityModelDelegate;
@@ -1045,14 +1307,6 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     /** Forward to entity delegate. */
     enqueue(...items: StageEntityInput[]): void;
     logMissingEntities(): void;
-    private runtimeContext;
-    /**
-     * Resolve a {@link StageWasmRuntimeConfig} into a live {@link WasmStageRuntime}.
-     * Accepts wasm bytes (`ArrayBuffer`), a fetch URL, or a deferred async
-     * builder so demos can `?url`-import a Vite asset without forcing the engine
-     * to bundle the wasm itself.
-     */
-    private loadWasmStage;
     /** 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. */
@@ -1065,6 +1319,17 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     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;
 };
@@ -1410,6 +1675,13 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
     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`
@@ -1421,6 +1693,17 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
     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;
@@ -1434,7 +1717,10 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
     setDisplayRuntime(runtime: ResolveGameConfigRuntime): void;
     loadGameCanvas(config: GameConfig): void;
     loadDebugOptions(options: ZylemGameOptions<TGlobals>): void;
-    loadStage(stage: Stage, stageIndex?: number): Promise<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.
@@ -1474,6 +1760,16 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
      * 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.
@@ -1544,6 +1840,18 @@ declare class Game<TGlobals extends BaseGlobals> implements IGame<TGlobals> {
      * 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>;
     /**
@@ -1552,10 +1860,27 @@ declare class Game<TGlobals extends BaseGlobals> implements IGame<TGlobals> {
      * @param deltaTime Optional delta time in seconds (defaults to 1/60)
      */
     step(deltaTime?: number): void;
-    reset(): Promise<void>;
-    previousStage(): 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>;
-    nextStage(): 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;
@@ -1587,4 +1912,4 @@ declare class Game<TGlobals extends BaseGlobals> implements IGame<TGlobals> {
  */
 declare function createGame<TGlobals extends BaseGlobals>(...options: GameOptions<TGlobals>): Game<TGlobals>;
 
-export { AspectRatio as A, CameraWrapper as C, type DeviceProfile as D, Fixed2DPerspective as F, Game as G, type PerspectiveOptions as P, type ResolutionInput as R, Stage as S, ThirdPersonPerspective as T, type StageStateInterface as a, type GameLoadingEvent as b, createGame as c, type GameConfigLike as d, type GameDeviceConfig as e, type ResolveGameConfigRuntime as f, gameConfig as g, createStage as h, type StageConfigLike as i, type StageOptions as j, createCamera as k, type CameraOptions as l, FirstPersonPerspective as m, createPerspective as n, type ThirdPersonOptions as o, type Fixed2DOptions as p, type FirstPersonOptions as q, type AspectRatioValue as r, stageConfig as s, getDisplayAspect as t, getPresetResolution as u, parseResolution as v, type RetroPreset as w, type RetroPresetKey as x, type RetroResolution as y };
+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 };