@zylem/game-lib 0.6.4 → 0.7.0

package/dist/{camera-4XO5gbQH.d.ts → zylem-stage-runtime-Cs-UDEVU.d.ts}

@@ -1,7 +1,9 @@
-import { Object3D, WebGLRenderer, Vector2, Scene, Camera, Vector3, Quaternion, WebGLRenderTarget, Texture } from 'three';
-import { S as StageEntity } from './entity-Bq_eNEDI.js';
-import { WebGPURenderer } from 'three/webgpu';
-import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { h as SetupFunction, a as Inputs } from './base-node-life-cycle-CnJ-7zX-.js';
+import { G as GameEntity } from './entity-DNkYKfdp.js';
+import { Object3D, Vector2, Scene, Camera, Vector3, Quaternion, RenderTarget, Texture, Color } from 'three';
+import { S as StageEntity, E as Entity, L as LifecycleFunction, Z as ZylemWorld } from './world-C9zdyl5d.js';
+import { WebGPURenderer, RenderPipeline } from 'three/webgpu';
+import { o as ZylemShader } from './material-Wz83vTTp.js';
 
 declare const Perspectives: {
     readonly FirstPerson: "first-person";
@@ -23,16 +25,19 @@ interface CameraDebugDelegate {
 }
 
 /**
- * Renderer type option for choosing rendering backend
- * - 'auto': Try WebGPU first, fall back to WebGL
- * - 'webgpu': Force WebGPU (error if not supported)
- * - 'webgl': Force WebGL
+ * Renderer type option.
+ *
+ * @deprecated game-lib now always renders with WebGPU (Three.js
+ * {@link WebGPURenderer}, which keeps its own internal WebGL2 fallback for
+ * devices without WebGPU). This type is retained only so existing public
+ * APIs (e.g. `CameraOptions.rendererType`) keep type-checking; the value is
+ * ignored by the renderer.
  */
 type RendererType = 'auto' | 'webgpu' | 'webgl';
 /**
- * Union type for renderer instances
+ * The renderer instance type. game-lib standardizes on {@link WebGPURenderer}.
  */
-type ZylemRenderer = WebGLRenderer | WebGPURenderer;
+type ZylemRenderer = WebGPURenderer;
 /**
  * Viewport definition in normalized coordinates (0-1).
  * Represents a rectangular region of the canvas for camera rendering.
@@ -44,36 +49,63 @@ interface Viewport {
     height: number;
 }
 /**
- * Check if WebGPU is supported in the current browser
+ * Check if WebGPU is supported in the current browser.
+ *
+ * Informational only — game-lib always constructs a {@link WebGPURenderer},
+ * which transparently falls back to a WebGL2 backend when the WebGPU adapter
+ * is unavailable. Callers can use this to surface device capabilities.
  */
 declare function isWebGPUSupported(): Promise<boolean>;
 /**
- * RendererManager owns the shared WebGL/WebGPU renderer, canvas element,
- * effect composer, and render loop. There is one RendererManager per game.
+ * RendererManager owns the shared WebGPU renderer, canvas element, the
+ * optional post-processing pipeline, and the render loop. There is one
+ * RendererManager per game.
  *
  * It iterates active cameras and renders each with its configured viewport.
  */
 declare class RendererManager {
     renderer: ZylemRenderer;
-    composer: EffectComposer;
+    /**
+     * Optional TSL post-processing pipeline. Bound to a single fullscreen
+     * scene+camera via {@link setupPostProcessing}. When present and the
+     * frame is a single fullscreen viewport, the pipeline drives the final
+     * draw instead of `renderer.render(...)`.
+     */
+    postProcessing: RenderPipeline | null;
+    /**
+     * Supersampling (SSAA) multiplier for the scene pass. `1` renders at native
+     * resolution (default). Values > 1 render the scene pass larger and let the
+     * post pipeline downsample it, trading GPU cost for smoother shading/edges
+     * (this is what the legacy WebGL pipeline did implicitly). Applied on the
+     * next {@link setupPostProcessing}.
+     */
+    renderScale: number;
     screenResolution: Vector2;
+    /**
+     * @deprecated Always `'webgpu'`. Retained for backward compatibility.
+     */
     rendererType: RendererType;
-    private _isWebGPU;
     private _initialized;
     private _sceneRef;
     private _lastAnimationTimestamp;
-    constructor(screenResolution?: Vector2, rendererType?: RendererType);
+    constructor(screenResolution?: Vector2, _rendererType?: RendererType);
     /**
      * Check if the renderer has been initialized
      */
     get initialized(): boolean;
     /**
-     * Check if using WebGPU renderer
+     * Whether the active renderer is WebGPU. Always true; retained for
+     * backward compatibility with callers that branched on backend.
+     *
+     * @deprecated game-lib is WebGPU-only.
      */
     get isWebGPU(): boolean;
     /**
      * Initialize the renderer (must be called before rendering).
      * Async because WebGPU requires async initialization.
+     *
+     * The renderer keeps Three.js's built-in WebGL2 fallback backend, so it
+     * still initializes on devices without native WebGPU.
      */
     initRenderer(): Promise<void>;
     /**
@@ -81,9 +113,24 @@ declare class RendererManager {
      */
     setScene(scene: Scene): void;
     /**
-     * Setup post-processing render pass for a camera (WebGL only).
+     * Set up the post-processing pipeline for a scene + camera.
+     *
+     * Builds a TSL `pass(scene, camera)` (HalfFloat + MSAA) and composes the
+     * final output ourselves so a display-space dither can be added: the dither
+     * breaks up 8-bit gradient banding (e.g. on terrain/sky) that the legacy
+     * WebGL pipeline hid via implicit supersampling. This is the WebGPU
+     * replacement for the old `EffectComposer` + `RenderPass`.
+     */
+    setupPostProcessing(scene: Scene, camera: Camera): void;
+    /**
+     * Set the supersampling (SSAA) multiplier. Takes effect on the next
+     * {@link setupPostProcessing}. `1` = native resolution (default).
+     */
+    setRenderScale(scale: number): void;
+    /**
+     * Dispose the current post-processing pipeline, if any.
      */
-    setupRenderPass(scene: Scene, camera: Camera): void;
+    private disposePostProcessing;
     /**
      * Start the render loop. Calls the provided callback each frame.
      */
@@ -94,13 +141,17 @@ declare class RendererManager {
     stopRenderLoop(): void;
     /**
      * Render a scene from a single camera's perspective.
-     * Sets the viewport based on the camera's viewport config.
+     * Sets the viewport/scissor based on the camera's viewport config so
+     * split-screen / picture-in-picture layouts render to their region.
+     *
+     * @param usePostProcessing When true and a pipeline is configured, the
+     * post-processing pipeline drives the draw (fullscreen only).
      */
-    renderCamera(scene: Scene, camera: ZylemCamera): void;
+    renderCamera(scene: Scene, camera: ZylemCamera, usePostProcessing?: boolean): void;
     /**
-     * Render a camera to its offscreen render target (WebGL only).
-     * Bypasses the EffectComposer since post-processing is not needed
-     * for render-to-texture output.
+     * Render a camera to its offscreen render target.
+     * Bypasses post-processing since render-to-texture output is consumed by
+     * an in-scene material (jumbotron / security-camera / portal effects).
      *
      * The camera must have a non-null renderTarget.
      */
@@ -108,11 +159,15 @@ declare class RendererManager {
     /**
      * Render a scene from multiple cameras, each with their own viewport.
      * Cameras are rendered in order (first = bottom layer, last = top layer).
+     *
+     * Post-processing is applied only when there is a single fullscreen
+     * camera; split-screen layouts render directly per-viewport (a single
+     * fullscreen post pass cannot honor per-camera scissor regions).
      */
     renderCameras(scene: Scene, cameras: ZylemCamera[]): void;
     /**
      * Simple single-camera render (backwards compatible).
-     * Uses the full viewport for a single camera.
+     * Uses post-processing when configured.
      */
     render(scene: Scene, camera: Camera): void;
     /**
@@ -128,7 +183,7 @@ declare class RendererManager {
      */
     getDomElement(): HTMLCanvasElement;
     /**
-     * Dispose renderer, composer, and related resources.
+     * Dispose renderer, post-processing, and related resources.
      */
     dispose(): void;
 }
@@ -331,8 +386,11 @@ declare class ZylemCamera {
      * Offscreen render target for render-to-texture (RTT) cameras.
      * When set, the camera renders to this target instead of the screen viewport.
      * Created via createRenderTarget() or automatically by setCameraFeed().
+     *
+     * Uses the backend-agnostic {@link RenderTarget} so it works with the
+     * WebGPU renderer (and Three's internal WebGL2 fallback).
      */
-    renderTarget: WebGLRenderTarget | null;
+    renderTarget: RenderTarget | null;
     /**
      * @deprecated Use `targets` array instead. Kept for backward compatibility.
      */
@@ -369,6 +427,15 @@ declare class ZylemCamera {
      * Check if debug mode is active (orbit controls taking over camera).
      */
     isDebugModeActive(): boolean;
+    /**
+     * True when debug orbit or user orbital controls are enabled (orbit controller is driving the camera).
+     */
+    get isOrbitActive(): boolean;
+    /**
+     * Advance OrbitControls (damping, pointer release) and follow the debug-selection orbit target.
+     * Intended to run once per render frame — see `CameraManager.render` and legacy `setupLegacy` render loop.
+     */
+    updateOrbitControls(): void;
     /**
      * Enable user-configured orbital controls (not debug mode).
      */
@@ -409,7 +476,7 @@ declare class ZylemCamera {
      * @param width  Texture width in pixels (default 512)
      * @param height Texture height in pixels (default 512)
      */
-    createRenderTarget(width?: number, height?: number): WebGLRenderTarget;
+    createRenderTarget(width?: number, height?: number): RenderTarget;
     /**
      * Get the texture from the render target (for applying to a mesh material).
      * Returns null if no render target has been created.
@@ -447,7 +514,7 @@ declare class ZylemCamera {
     setRendererManager(manager: RendererManager): void;
     /** @deprecated Renderer is now owned by RendererManager */
     get renderer(): any;
-    /** @deprecated Composer is now owned by RendererManager */
+    /** @deprecated Post-processing is now owned by RendererManager */
     get composer(): any;
     /** @deprecated Use RendererManager.setPixelRatio() instead */
     setPixelRatio(dpr: number): void;
@@ -555,6 +622,7 @@ declare class CameraManager {
      * 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.
      */
@@ -573,333 +641,137 @@ declare class CameraManager {
     private resolveCamera;
 }
 
-/**
- * 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?: Vector3;
-    /** Fallback lookAt point when no targets exist. */
-    initialLookAt?: Vector3;
-}
-/**
- * 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";
-    readonly defaults: {
-        damping: number;
-    };
-    private opts;
-    private initialPosition?;
-    private initialLookAt?;
-    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 = target + offset, lookAt = target.
-     */
-    private singleTargetPose;
+interface SceneState {
+    backgroundColor: Color | string;
+    backgroundImage: string | null;
+    backgroundShader?: ZylemShader | null;
     /**
-     * Multi-target: compute centroid and adjust distance to frame all targets.
+     * 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.
      */
-    private multiTargetPose;
-}
-
-/**
- * Configuration for the fixed 2D perspective.
- */
-interface Fixed2DOptions {
-    /** Fixed camera position. Default (0, 0, 10). */
-    position?: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** 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?: Vector3;
-    /** Fallback look-at point used to derive initial yaw/pitch when no target. */
-    initialLookAt?: Vector3;
-}
-/**
- * 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;
-    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;
-    private computeRotation;
-    private lerpFov;
-    private deriveYawPitchFromLookAt;
-    private deriveYawPitchFromQuaternion;
+    defaultLighting?: boolean;
 }
-
-/**
- * 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?: Vector3 | {
-        x: number;
-        y: number;
-        z: number;
-    };
-    target?: Vector3 | {
-        x: number;
-        y: number;
-        z: number;
-    } | any;
-    zoom?: number;
-    screenResolution?: Vector2;
-    /**
-     * Renderer type: 'auto' | 'webgpu' | 'webgl'
-     * Use 'webgpu' for TSL shaders
-     * @default 'webgl'
-     */
-    rendererType?: RendererType;
-    /**
-     * 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.).
+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;
+    private skyboxMaterial;
+    private skyboxMesh;
+    constructor(id: string, camera: ZylemCamera, state: SceneState);
+    /**
+     * Create a large inverted box with the shader for a skybox effect.
      *
-     * @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
+     * 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).
      */
-    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;
+    private setupBackgroundShader;
+    setup(): void;
+    destroy(): void;
     /**
-     * Remove a target entity from the camera.
+     * Setup camera with the scene.
+     * Supports both legacy single camera and CameraManager modes.
      */
-    removeTarget(entity: StageEntity): void;
+    setupCamera(scene: Scene, camera: ZylemCamera, rendererManager?: RendererManager): Promise<void>;
     /**
-     * Clear all targets. Camera will look at world origin.
+     * Setup with a CameraManager (multi-camera support).
      */
-    clearTargets(): void;
+    setupCameraManager(scene: Scene, cameraManager: CameraManager, rendererManager: RendererManager): Promise<void>;
     /**
-     * Enable orbital controls for this camera.
-     * Allows the user to orbit, pan, and zoom the camera.
+     * Add a camera (rig or direct) to the scene graph.
      */
-    enableOrbitalControls(): void;
+    private addCameraToScene;
     /**
-     * Disable orbital controls for this camera.
+     * Setup scene lighting
      */
-    disableOrbitalControls(): void;
+    setupLighting(scene: Scene): 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
+     * Update renderer size - delegates to camera manager or camera
      */
-    setViewport(x: number, y: number, width: number, height: number): void;
+    updateRenderer(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.
+     * Add object to scene
      */
-    addBehavior(key: string, behavior: CameraBehavior): void;
+    add(object: Object3D, position?: Vector3): void;
     /**
-     * Remove a behavior by key.
+     * Add game entity to scene
      */
-    removeBehavior(key: string): boolean;
+    addEntity(entity: GameEntity<any>): void;
     /**
-     * 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).
+     * Add an entity's group or mesh to the scene (for late-loaded models).
+     * Uses entity's current body position if physics is active.
      *
-     * @param type     Perspective type string (e.g. Perspectives.ThirdPerson).
-     * @param options  Perspective-specific options (distance, height, zoom, etc.).
+     * 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.
      */
-    setPerspective(type: PerspectiveType, options?: PerspectiveOptions): void;
+    addEntityGroup(entity: GameEntity<any>): void;
+    private isAttachedOutsideScene;
     /**
-     * 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);
+     * Add debug helpers to scene
      */
-    getPerspective<T extends CameraPerspective = CameraPerspective>(): T;
+    debugScene(): void;
     /**
-     * Return a debug snapshot of the camera pipeline state.
-     * Includes: active perspective, desired/final pose, behavior keys, action count.
+     * Per-frame skybox hook. Ensures the skybox cube follows the active camera
+     * position so it always appears infinitely far away regardless of camera
+     * movement. TSL background shaders animate via the `time` node, which the
+     * renderer advances automatically.
      */
-    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;
+    updateSkybox(_delta: number): void;
 }
+
 /**
- * Create a camera with the given options.
- * Returns a CameraWrapper for convenient access to camera features.
+ * Host-provided debug signals for wasm runtime adapters (no direct `debugState` import in adapters).
  */
-declare function createCamera(options: CameraOptions): CameraWrapper;
+interface RuntimeDebugBinding {
+    /** When true, show wasm-side diagnostics (e.g. instanced collision heat tint). */
+    runtimeDiagnostics(): boolean;
+}
+interface StageRuntimeContext {
+    scene: ZylemScene;
+    world: ZylemWorld;
+    camera: ZylemCamera;
+    /** Optional; when set, adapters may enable extra runtime visualization. */
+    debug?: RuntimeDebugBinding;
+}
+interface StageRuntimeStepContext extends StageRuntimeContext {
+    delta: number;
+    inputs: Inputs;
+}
+interface StageRuntimeAdapter {
+    init(context: StageRuntimeContext): Promise<void> | void;
+    step(context: StageRuntimeStepContext): void;
+    destroy(context: StageRuntimeContext | null): void;
+    ownsEntity(entity: GameEntity<any>): boolean;
+    rendersEntity(entity: GameEntity<any>): boolean;
+    registerEntity(entity: GameEntity<any>): void;
+    unregisterEntity(entity: GameEntity<any>): void;
+    /**
+     * Optional: when implemented, the stage debug delegate will draw the
+     * returned line segments alongside the TS Rapier debug overlay so wasm
+     * runtime adapters can visualize their own colliders. Returning `null`
+     * (or omitting the method entirely) disables the second pass.
+     */
+    getDebugRender?(): {
+        vertices: Float32Array;
+        colors: Float32Array;
+    } | null;
+}
+interface ZylemRuntimeStageAdapterSource {
+    source: RequestInfo | URL | ArrayBuffer;
+}
+declare function createZylemRuntimeStageAdapter(options: ZylemRuntimeStageAdapterSource): StageRuntimeAdapter;
 
-export { CameraManager as C, FirstPersonPerspective as F, type PerspectiveType as P, RendererManager as R, type TransformLike as T, type Viewport as V, ZylemCamera as Z, CameraWrapper as a, type CameraBehavior as b, createCamera as c, type CameraOptions as d, Perspectives as e, type RendererType as f, type ZylemRenderer as g, type CameraPose as h, isWebGPUSupported as i, type PoseDelta as j, type CameraContext as k, type CameraPerspective as l, type CameraAction as m, type CameraPipelineState as n, CameraPipeline as o, ThirdPersonPerspective as p, Fixed2DPerspective as q, createPerspective as r, type ThirdPersonOptions as s, type Fixed2DOptions as t, type FirstPersonOptions as u, type PerspectiveOptions as v };
+export { type CameraBehavior as C, type PerspectiveType as P, type RuntimeDebugBinding as R, type StageRuntimeAdapter as S, type TransformLike as T, type Viewport as V, type ZylemRenderer as Z, type StageRuntimeContext as a, type StageRuntimeStepContext as b, createZylemRuntimeStageAdapter as c, Perspectives as d, type RendererType as e, CameraManager as f, type CameraPose as g, type PoseDelta as h, isWebGPUSupported as i, type CameraContext as j, type CameraPerspective as k, type CameraAction as l, type CameraPipelineState as m, CameraPipeline as n, ZylemCamera as o, ZylemScene as p, RendererManager as q };