@zylem/game-lib 0.8.0 → 0.8.3

package/dist/api/game-lib.d.ts

@@ -1,4 +1,5 @@
 import { abs } from 'three/tsl';
+import { announceBridgeReady } from '@zylem/bridge';
 import { asin } from 'three/tsl';
 import { atan } from 'three/tsl';
 import { BehaviorDescriptor } from '@zylem/behaviors';
@@ -20,6 +21,14 @@ import { BoundaryRicochet3DEntity } from '@zylem/behaviors';
 import { BoundaryRicochetCoordinator } from '@zylem/behaviors';
 import { BoundaryRicochetEntity } from '@zylem/behaviors';
 import { BoundaryRicochetUpdate } from '@zylem/behaviors';
+import { BRIDGE_READY_EVENT } from '@zylem/bridge';
+import { BridgeChannel } from '@zylem/bridge';
+import { BridgeDebugTool } from '@zylem/bridge';
+import { BridgeHandler } from '@zylem/bridge';
+import { GameLoadingPayload as BridgeLoadingPayload } from '@zylem/bridge';
+import { BridgeMessages } from '@zylem/bridge';
+import { BridgeMessageType } from '@zylem/bridge';
+import { BridgeVec3 } from '@zylem/bridge';
 import { BufferGeometry } from 'three';
 import { BurstParticlePresetOptions } from '@zylem/behaviors';
 import { Camera } from 'three';
@@ -71,11 +80,14 @@ import { Destructible3DHandle } from '@zylem/behaviors';
 import { DestructibleMesh } from '@zylem/behaviors';
 import { DestructiblePrebakeWorkerAPI } from '@zylem/behaviors';
 import { dot } from 'three/tsl';
+import { EditorToGameMessages } from '@zylem/bridge';
 import { emitRuntimeGoal } from '@zylem/behaviors/runtime-2d';
 import { emitRuntimeRicochet } from '@zylem/behaviors/runtime-2d';
 import { emitRuntimeTriggerRegionEnter } from '@zylem/behaviors/runtime-2d';
 import { EntityDefinition } from '@zylem/behaviors/core';
 import { EntityHandle } from '@zylem/behaviors/core';
+import { EntitySummaryPayload } from '@zylem/bridge';
+import { EntityThumbnailPayload } from '@zylem/bridge';
 import { exp } from 'three/tsl';
 import { FacingAngle2DEntity } from '@zylem/behaviors';
 import { fireCooldown } from '@zylem/behaviors';
@@ -102,11 +114,16 @@ import { FogExp2 } from 'three';
 import { fract } from 'three/tsl';
 import { FractureOptions } from '@zylem/behaviors';
 import { FractureOptionsInput } from '@zylem/behaviors';
+import { GameConfigPayload } from '@zylem/bridge';
+import { GameNoticePayload } from '@zylem/bridge';
+import { GameToEditorMessages } from '@zylem/bridge';
+import { GameVariablePayload } from '@zylem/bridge';
 import { getCooldown } from '@zylem/behaviors';
 import { getCooldownStore } from '@zylem/behaviors';
 import { getEntityFacingAngle2D } from '@zylem/behaviors';
 import { getPosition } from '@zylem/behaviors/core';
 import { getVelocity } from '@zylem/behaviors/core';
+import { getZylemBridge } from '@zylem/bridge';
 import { Group } from 'three';
 import { hasAnyWorldBoundary2DHit } from '@zylem/behaviors';
 import { hasAnyWorldBoundary3DHit } from '@zylem/behaviors';
@@ -302,6 +319,7 @@ import { StageBodyKindValue } from '@zylem/behaviors/core';
 import { StageBoundaryDim } from '@zylem/behaviors/core';
 import { StageColliderConfig } from '@zylem/behaviors/core';
 import { StageColliderShape } from '@zylem/behaviors/core';
+import { StageConfigPayload } from '@zylem/bridge';
 import { StageDebugRender } from '@zylem/behaviors/core';
 import { StageEvent } from '@zylem/behaviors/core';
 import { StageEventType } from '@zylem/behaviors/core';
@@ -310,6 +328,7 @@ import { StageRaycastHit } from '@zylem/behaviors/core';
 import { StageRenderSlot } from '@zylem/behaviors/core';
 import { StageRicochetDim } from '@zylem/behaviors/core';
 import { StageRicochetReflection } from '@zylem/behaviors/core';
+import { StageSnapshotPayload } from '@zylem/bridge';
 import { StageTopDownPlane } from '@zylem/behaviors/core';
 import { Static } from '@sinclair/typebox';
 import { step } from 'three/tsl';
@@ -374,6 +393,7 @@ import { WorldBoundary3DPosition } from '@zylem/behaviors';
 import { WorldBoundary3DState } from '@zylem/behaviors';
 import { wrapAround3D } from '@zylem/behaviors/core';
 import { wrapAroundXY } from '@zylem/behaviors/core';
+import { ZylemBridge } from '@zylem/bridge';
 
 export { abs }
 
@@ -439,6 +459,8 @@ declare type AnimationOptions = {
     fadeDuration?: number;
 };
 
+export { announceBridgeReady }
+
 declare type AnyNode = NodeLike | Promise<NodeLike>;
 
 /**
@@ -518,6 +540,12 @@ declare interface BaseCollisionOptions {
     collisionType?: string;
     /** Allowed collision types for filtering */
     collisionFilter?: string[];
+    /** Gravity scale applied at body spawn (no live setter FFI; default 1). */
+    gravityScale?: number;
+    /** Lock rotation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockRotations?: LockAxesInput;
+    /** Lock translation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockTranslations?: LockAxesInput;
 }
 
 /**
@@ -674,6 +702,22 @@ declare interface BoxMeshOptions extends BaseMeshOptions {
 
 declare type BoxOptions = BaseNode | Partial<ZylemBoxOptions>;
 
+export { BRIDGE_READY_EVENT }
+
+export { BridgeChannel }
+
+export { BridgeDebugTool }
+
+export { BridgeHandler }
+
+export { BridgeLoadingPayload }
+
+export { BridgeMessages }
+
+export { BridgeMessageType }
+
+export { BridgeVec3 }
+
 /** Cuboid collider sized as `size.xyz` (full extents — half-extents are computed). */
 export declare function buildBoxCollider(size: Vec3Input, options?: RuntimeColliderOptions): StageColliderConfig;
 
@@ -801,6 +845,10 @@ export declare class CameraManager {
     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 */
@@ -820,6 +868,10 @@ export declare class CameraManager {
      * 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.
      */
@@ -863,6 +915,16 @@ export declare class CameraManager {
      * 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.
      */
@@ -884,8 +946,14 @@ export declare class CameraManager {
     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.
      */
@@ -1157,6 +1225,9 @@ export declare function clearGlobalSubscriptions(): void;
 declare class CollisionBuilder {
     static: boolean;
     sensor: boolean;
+    gravityScale?: number;
+    lockRotations?: LockAxesInput;
+    lockTranslations?: LockAxesInput;
     build(options: Partial<CollisionOptions>): [SimulationBodyDefinition, SimulationColliderDefinition];
     withCollision(collisionOptions: Partial<CollisionOptions>): this;
     collider(options: CollisionOptions): SimulationColliderDefinition;
@@ -1214,6 +1285,12 @@ declare interface CollisionOptions {
     position?: Vec3Input;
     collisionType?: string;
     collisionFilter?: string[];
+    /** Gravity scale applied at body spawn (no live setter FFI; default 1). */
+    gravityScale?: number;
+    /** Lock rotation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockRotations?: LockAxesInput;
+    /** Lock translation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockTranslations?: LockAxesInput;
 }
 
 declare type CollisionPhase = 'enter' | 'stay';
@@ -1385,8 +1462,10 @@ export declare function createEntity<T extends GameEntity<any>, CreateOptions ex
  * const asteroidFactory = createEntityFactory(asteroidTemplate);
  * const asteroids = asteroidFactory.generate(10);
  *
- * asteroids.forEach((asteroid, i) => {
- *     asteroid.setPosition(Math.random() * 20 - 10, Math.random() * 15 - 7.5, 0);
+ * asteroids.forEach((asteroid) => {
+ *     asteroid.onSetup(({ me }) => {
+ *         me.setPosition(Math.random() * 20 - 10, Math.random() * 15 - 7.5, 0);
+ *     });
  *     stage.add(asteroid);
  * });
  * ```
@@ -1621,6 +1700,9 @@ declare interface CylinderMeshOptions extends BaseMeshOptions {
 
 declare type CylinderOptions = BaseNode | Partial<ZylemCylinderOptions>;
 
+/** Resolves a UUID to the live entity owned by the active stage. */
+export declare type DebugEntityResolver = (uuid: string) => GameEntity<any> | null;
+
 /**
  * Interface for entities that provide custom debug information
  */
@@ -1632,14 +1714,22 @@ declare interface DebugState {
     enabled: boolean;
     paused: boolean;
     tool: DebugTools;
-    selectedEntity: GameEntity<any> | null;
-    hoveredEntity: GameEntity<any> | null;
+    /**
+     * UUID of the selected entity, never the entity itself. Valtio deep-proxies
+     * any object assigned into a proxy, so storing a live `GameEntity` here
+     * would walk `group.parent` into the entire THREE scene graph and
+     * `physicsWorldRef` into the Rapier world, freezing the tab and handing
+     * Proxy wrappers to engine code that expects real instances.
+     */
+    selectedEntityId: string | null;
+    /** UUID of the hovered entity. Same constraint as `selectedEntityId`. */
+    hoveredEntityId: string | null;
     flags: Set<string>;
 }
 
 export declare const debugState: DebugState;
 
-export declare type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'none';
+export declare type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'add' | 'none';
 
 /**
  * Builds a ready-to-use {@link GameInputConfig} that wires up themed
@@ -1763,6 +1853,8 @@ export declare function dispatchStageState(): void;
 
 export { dot }
 
+export { EditorToGameMessages }
+
 export { emitRuntimeGoal }
 
 export { emitRuntimeRicochet }
@@ -1800,36 +1892,6 @@ declare abstract class EntityCollisionBuilder extends CollisionBuilder {
     abstract collider(options: GameEntityOptions): SimulationColliderDefinition;
 }
 
-/** Payload for entity configuration sent to editor. */
-export declare interface EntityConfigPayload {
-    uuid: string;
-    name: string;
-    type: string;
-    position: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    rotation: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    scale: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** PNG data URL of a framed entity preview, when available. */
-    thumbnail?: string | null;
-    /** World-space AABB size used for thumbnail rulers. */
-    bounds?: {
-        width: number;
-        height: number;
-        depth: number;
-    };
-}
-
 declare interface EntityDebugInfo {
     buildInfo: () => Record<string, string>;
 }
@@ -1988,6 +2050,8 @@ declare interface EntitySpawner {
 
 export declare function entitySpawner(factory: (x: number, y: number) => Promise<any> | GameEntity<any>): EntitySpawner;
 
+export { EntitySummaryPayload }
+
 /**
  * Generates and caches entity thumbnail previews for the editor entity list.
  * Renders a cloned Object3D into an offscreen RenderTarget on the shared WebGPU renderer.
@@ -1997,15 +2061,30 @@ export declare class EntityThumbnailCache {
     private inFlight;
     private renderer;
     private size;
-    constructor(size?: number);
+    private maxEntries;
+    private queue;
+    private activeRenders;
+    constructor(size?: number, maxEntries?: number);
     setRenderer(renderer: WebGPURenderer | null): void;
     get(uuid: string): EntityThumbnailCacheEntry | null;
     invalidate(uuid: string): void;
     clear(): void;
+    /** Number of thumbnails currently cached. */
+    get cacheSize(): number;
+    /** Entities waiting for a render slot. */
+    get pendingCount(): number;
     /**
-     * Return a cached thumbnail or generate one asynchronously.
+     * Return a cached thumbnail, or schedule one. Renders are throttled to
+     * {@link MAX_CONCURRENT_RENDERS} at a time behind a bounded queue, so a
+     * burst of spawns cannot flood the renderer with pixel readbacks.
      */
     ensure(uuid: string, object: Object3D | null | undefined): Promise<EntityThumbnailCacheEntry | null>;
+    /** Start queued renders until the concurrency budget is spent. */
+    private drainQueue;
+    /** Move an entry to the end of the Map so it is evicted last. */
+    private touch;
+    /** Evict least-recently-used entries down to the cap. */
+    private evictOverflow;
     private render;
 }
 
@@ -2016,7 +2095,13 @@ export declare interface EntityThumbnailCacheEntry extends EntityThumbnailResult
     uuid: string;
 }
 
+export { EntityThumbnailPayload }
+
 export declare interface EntityThumbnailResult {
+    /**
+     * Preview image URL. Blob URL when the payload worker is available
+     * (encoded off-thread), PNG data URL on the synchronous fallback path.
+     */
     dataUrl: string;
     bounds: Pick<ObjectBounds, 'width' | 'height' | 'depth'>;
 }
@@ -2188,6 +2273,8 @@ export 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. */
@@ -2415,6 +2502,89 @@ export declare class Game<TGlobals extends BaseGlobals> implements IGame<TGlobal
     onLoading(callback: (event: GameLoadingEvent) => void): () => void;
 }
 
+export declare class GameBridge {
+    private channel;
+    private unsubscribes;
+    private host;
+    /**
+     * Values the editor is already known to hold, either because it commanded
+     * them or because we published them. Anything matching here is skipped, so
+     * an editor command can never echo back as a game update.
+     */
+    private editorKnown;
+    constructor();
+    /**
+     * Subscribe to editor commands and announce the game side as ready.
+     * @param host Live-game context for entity/stage lookups
+     * @param announceTarget DOM node the `zylem:bridge:ready` event bubbles from
+     */
+    connect(host: GameBridgeHost, announceTarget?: EventTarget): void;
+    disconnect(): void;
+    /**
+     * Publish only the parts of `debugState` the editor does not already know.
+     * Values that arrived as editor commands are recorded on `editorKnown`
+     * first, so they are never echoed back.
+     */
+    private publishDebugStateChanges;
+    /**
+     * Whether anything is listening for entity list updates. Building entity
+     * summaries is pure editor overhead, so publishers skip it when no editor
+     * is attached.
+     */
+    wantsEntityUpdates(): boolean;
+    /**
+     * Whether anything is listening for thumbnails. Each thumbnail costs an
+     * offscreen render plus a pixel readback on the renderer the game draws
+     * with, so this gate matters far more than the others.
+     */
+    wantsThumbnails(): boolean;
+    /**
+     * Run a callback when an editor first subscribes to entity data, so the
+     * game can backfill state produced while nothing was listening.
+     *
+     * @returns An unsubscribe function.
+     */
+    onEditorAttached(callback: () => void): () => void;
+    publishConfig(config: GameConfigPayload): void;
+    publishLoading(payload: BridgeLoadingPayload): void;
+    publishStatus(status: {
+        paused?: boolean;
+        debug?: boolean;
+    }): void;
+    publishVariable(payload: GameVariablePayload): void;
+    /** Surface a diagnostic message in the editor console. */
+    publishNotice(level: GameNoticePayload['level'], message: string): void;
+    publishStageSnapshot(snapshot: StageSnapshotPayload): void;
+    /** RAF-coalesced entity add/update stream; merged by uuid per frame. */
+    queueEntityUpsert(entities: EntitySummaryPayload[]): void;
+    /** RAF-coalesced entity removal stream. */
+    queueEntityRemoved(uuids: string[]): void;
+    /** RAF-coalesced thumbnail stream; merged by uuid per frame. */
+    queueThumbnails(thumbnails: EntityThumbnailPayload[]): void;
+}
+
+/**
+ * Game-side adapter for the shared editor ↔ game bridge.
+ *
+ * Owns the editor→game command subscriptions (debug/tool/playback, entity
+ * select/focus/transform, stage variables) and exposes typed publish helpers
+ * the running game uses to stream config, stage snapshots, entity upserts,
+ * and thumbnails to the editor. High-frequency publishes go through the
+ * channel's `queue`, which coalesces to at most one message per animation
+ * frame.
+ */
+
+/**
+ * Host context supplied by the running game so bridge commands can act on
+ * live stage state without the bridge importing game internals.
+ */
+export declare interface GameBridgeHost {
+    /** Resolve a live entity by UUID from the current stage. */
+    resolveEntity(uuid: string): GameEntity<any> | null;
+    /** Write a stage variable (editor `stage:variable:set`). */
+    setStageVariable?(key: string, value: unknown): void;
+}
+
 /**
  * GameCanvas is a DOM delegate that owns:
  * - container lookup/creation and styling (including fullscreen centering)
@@ -2502,6 +2672,9 @@ export declare const GameConfigJsonSchema: _sinclair_typebox.TObject<{
             mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
             pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
             sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+            maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+            lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
         }>>;
         touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
             enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -2622,6 +2795,8 @@ export declare type GameConfigLike = Partial<{
     canvas: HTMLCanvasElement;
 }>;
 
+export { GameConfigPayload }
+
 export declare type GameDeviceConfig = Partial<{
     /** numeric value or key in AspectRatio */
     aspectRatio: AspectRatioValue | keyof typeof AspectRatio;
@@ -2709,6 +2884,14 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
     private trackAddedComponents;
     private trackedComponents;
     transformStore: TransformState;
+    /** Hide render target until spawn placement is confirmed. */
+    _spawnPlacementPending: boolean;
+    /** Author passed `position` in create options. */
+    _spawnPositionExplicit: boolean;
+    /** setPosition / setPose assigned a spawn placement during this spawn. */
+    _spawnPlacementReady: boolean;
+    /** True while {@link StageEntityDelegate.spawnEntity} is running for this entity. */
+    _spawnInProgress: boolean;
     moveX: (delta: number) => void;
     moveY: (delta: number) => void;
     moveZ: (delta: number) => void;
@@ -2741,6 +2924,9 @@ export declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O>
     setRotation: (x: number, y: number, z: number) => void;
     getRotation: () => any;
     constructor();
+    private wrapSpawnPlacementMutators;
+    /** Make the entity visible, clearing spawn placement pending state. */
+    reveal(): void;
     /**
      * Read the entity's pose from the wasm simulation. Returns `null` when
      * the entity has not been spawned into the runtime yet.
@@ -2896,6 +3082,17 @@ export declare type GameEntityOptions = {
     color?: Color;
     size?: Vec3Input;
     position?: Vec3Input;
+    /**
+     * Spawn visibility behavior:
+     * - `undefined` (default): hidden while `spawnEntity` runs, revealed once
+     *   the spawn finalizes — even if no position was assigned.
+     * - `true` (strict): stays hidden until the first `setPosition`/`setPose`,
+     *   for spawner patterns that place the entity frames after spawn.
+     * - `false`: never hidden during spawn.
+     */
+    hideUntilPositioned?: boolean;
+    /** Explicit render visibility. When false, entity stays hidden until {@link GameEntity.reveal}. */
+    visible?: boolean;
     /** Render path: `environment` (bundle), `pack` (instanced), or `none` (default). */
     category?: RenderCategory_2;
     runtime?: RuntimeEntityOptions;
@@ -2926,7 +3123,6 @@ export declare type GameEvents = {
     'debug': {
         enabled: boolean;
     };
-    'state:dispatch': StateDispatchPayload;
 };
 
 export declare interface GameInputConfig {
@@ -2953,6 +3149,9 @@ export declare const GameInputConfigSchema: _sinclair_typebox.TRecord<_sinclair_
         mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
         pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+        maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
     }>>;
     touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
         enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -3041,6 +3240,9 @@ export declare const GameInputPlayerConfigSchema: _sinclair_typebox.TObject<{
         mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
         pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
         sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+        maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+        lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
     }>>;
     touch: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{
         enabled: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TBoolean, _sinclair_typebox.TLiteral<"auto">]>>;
@@ -3138,6 +3340,10 @@ export declare interface GameLoadingPayload extends LoadingEvent {
 
 declare type GameOptions<TGlobals extends BaseGlobals> = Array<ZylemGameConfig<Stage, any, TGlobals> | GameConfigLike | Stage | GameEntityLifeCycle | BaseNode>;
 
+export { GameToEditorMessages }
+
+export { GameVariablePayload }
+
 export { getCooldown }
 
 export { getCooldownStore }
@@ -3158,6 +3364,11 @@ export declare function getGlobal<T = unknown>(path: string): T | undefined;
  */
 export declare function getGlobals<T = Record<string, unknown>>(): T;
 
+/** The live hovered entity, resolved on demand through the active stage. */
+export declare function getHoveredEntity(): GameEntity<any> | null;
+
+export declare function getHoveredEntityId(): string | null;
+
 export { getPosition }
 
 export declare function getPresetResolution(preset: RetroPresetKey, key?: string): RetroResolution | undefined;
@@ -3167,6 +3378,11 @@ export declare function getPresetResolution(preset: RetroPresetKey, key?: string
  */
 export declare function getRotation(entity: RotatableEntity): any;
 
+/** The live selected entity, resolved on demand through the active stage. */
+export declare function getSelectedEntity(): GameEntity<any> | null;
+
+export declare function getSelectedEntityId(): string | null;
+
 /**
  * Get a variable from an object by path.
  * @example getVariable(stage1, 'totalAngle') // 0.5
@@ -3176,6 +3392,8 @@ export declare function getVariable<T = unknown>(target: object, path: string):
 
 export { getVelocity }
 
+export { getZylemBridge }
+
 /**
  * Listen for a single global key change inside an onUpdate pipeline.
  * Usage: onUpdate(globalChange('p1Score', (value) => { ... }))
@@ -3297,8 +3515,14 @@ export declare interface InputGamepad {
     };
     /** Screen-space cursor position (normalized 0..1). Only populated by MouseProvider. */
     pointer?: {
+        /** Window-normalized X (0 = left, 1 = right). */
         x: number;
+        /** Window-normalized Y (0 = top, 1 = bottom). */
         y: number;
+        /** Canvas-center-relative X (−1 = left edge, +1 = right edge). */
+        centerX: number;
+        /** Canvas-center-relative Y (−1 = top edge, +1 = bottom edge). */
+        centerY: number;
     };
 }
 
@@ -3590,6 +3814,9 @@ export declare type LoadingEvent = {
     current?: number;
 };
 
+/** Per-axis lock input: `true` locks all axes, or pass an [x, y, z] tuple. */
+declare type LockAxesInput = boolean | readonly [boolean, boolean, boolean];
+
 declare class MaterialBuilder {
     static sharedMaterialMap: Map<MaterialCacheKey, SharedMaterialMapEntry>;
     /**
@@ -3688,6 +3915,12 @@ export declare interface MouseConfig {
     pointerLock?: boolean;
     /** Sensitivity multiplier for mouse movement (default 0.002). */
     sensitivity?: number;
+    /** How mouse position drives look: delta (movement) or screenCenter (cursor offset from viewport center). */
+    lookMode?: 'delta' | 'screenCenter';
+    /** Max yaw/pitch in degrees when `lookMode` is `screenCenter` (default 45). */
+    maxLookDegrees?: number;
+    /** Screen-center follow rate toward cursor-mapped target (lower = snappier; default 2). */
+    lookSensitivity?: number;
 }
 
 /** Mouse input configuration. */
@@ -3695,6 +3928,9 @@ export declare const MouseConfigSchema: _sinclair_typebox.TObject<{
     mapping: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TArray<_sinclair_typebox.TString>>>;
     pointerLock: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
     sensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    lookMode: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"delta">, _sinclair_typebox.TLiteral<"screenCenter">]>>;
+    maxLookDegrees: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
+    lookSensitivity: _sinclair_typebox.TOptional<_sinclair_typebox.TNumber>;
 }>;
 
 export declare type MouseMapping = Record<string, string[]>;
@@ -4230,6 +4466,15 @@ declare type RectOptions = BaseNode | Partial<ZylemRectOptions>;
 
 export { registerCooldown }
 
+/**
+ * Register the active stage's entity resolver so `getSelectedEntity` /
+ * `getHoveredEntity` can hand back live entities without the reactive store
+ * ever holding one.
+ *
+ * @returns An unregister function.
+ */
+export declare function registerDebugEntityResolver(resolver: DebugEntityResolver): () => void;
+
 /**
  * Register the active stage's focus context. Returns an unregister function.
  */
@@ -4508,6 +4753,9 @@ export declare function resolveButtonAccent(theme: TouchTheme, slot: VirtualTouc
 
 export { ResolvedAim2D }
 
+/** Resolve a UUID through the active stage, or null when unavailable. */
+export declare function resolveDebugEntity(uuid: string | null): GameEntity<any> | null;
+
 /** `StageTransitionConfig` with all defaults applied. */
 declare interface ResolvedStageTransition {
     duration: number;
@@ -4832,6 +5080,41 @@ declare interface SceneState {
  */
 export declare type ScreenAnchor = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 
+/**
+ * Computes WASM look deltas that drive current yaw/pitch toward screen-center targets.
+ *
+ * `lookSensitivity` controls follow rate toward the cursor-mapped target (lower = snappier).
+ * WASM applies its own `look_sensitivity` multiplier to these deltas.
+ */
+export declare function screenCenterLookDeltas(nx: number, ny: number, currentYaw: number, currentPitch: number, options?: ScreenCenterLookOptions): {
+    lookX: number;
+    lookY: number;
+};
+
+export declare interface ScreenCenterLookOptions {
+    maxLookDegrees?: number;
+    /** How fast cursor position pulls yaw/pitch toward target (lower = snappier). @default 2 */
+    lookSensitivity?: number;
+}
+
+/**
+ * Maps canvas-center-relative pointer offset to absolute yaw/pitch targets.
+ * Used with screen-center mouse look (free cursor, no pointer lock).
+ */
+export declare interface ScreenCenterLookTargets {
+    targetYaw: number;
+    targetPitch: number;
+}
+
+/**
+ * Converts normalized pointer offset from viewport center to look angles.
+ *
+ * @param nx Horizontal offset from center (−1 = left edge, +1 = right edge).
+ * @param ny Vertical offset from center (−1 = top edge, +1 = bottom edge).
+ * @param maxDegrees Maximum yaw/pitch at viewport edges (default 45).
+ */
+export declare function screenCenterLookTargets(nx: number, ny: number, maxDegrees?: number): ScreenCenterLookTargets;
+
 export { ScreenVisibilityBehavior }
 
 export { ScreenVisibilityChangeContext }
@@ -4911,6 +5194,8 @@ export declare function setDebugTool(tool: DebugTools): void;
  */
 export declare function setGlobal(path: string, value: unknown): void;
 
+export declare function setHoveredEntityId(uuid: string | null): void;
+
 export declare function setPaused(paused: boolean): void;
 
 export { setPosition }
@@ -4961,7 +5246,13 @@ export declare function setRotationY(entity: RotatableEntity, y: number): void;
  */
 export declare function setRotationZ(entity: RotatableEntity, z: number): void;
 
-export declare function setSelectedEntity(entity: GameEntity<any> | null): void;
+/**
+ * @deprecated Pass a UUID to {@link setSelectedEntityId} instead. Accepts a
+ * live entity only to keep the previous public API working.
+ */
+export declare function setSelectedEntity(entity: GameEntity<any> | string | null): void;
+
+export declare function setSelectedEntityId(uuid: string | null): void;
 
 export declare function setStageFrameProfilerEnabled(value: boolean): void;
 
@@ -5023,6 +5314,9 @@ export { Shooter2DStateComponent }
 
 export { Shooter2DTarget }
 
+/** Shortest signed angle from `from` to `to` in radians. */
+export declare function shortestAngleDelta(from: number, to: number): number;
+
 declare function shortHash(objString: string): string;
 
 export { Simulation }
@@ -5034,7 +5328,19 @@ export declare class SimulationBody implements PhysicsRenderPoseProvider {
     private readonly poseScratch;
     private readonly renderScratch;
     private readonly previousScratch;
+    /**
+     * First step at which the shared render buffers are coherent for this
+     * body. After a spawn or an explicit pose write (teleport), the current
+     * slot isn't written until the next fixed step and the previous-step
+     * copy lags one more; interpolating across that gap would sweep the
+     * mesh from a stale pose (often the origin). Until this step is
+     * reached, render reads collapse to the live body pose.
+     */
+    private interpolationValidAfterStep;
     constructor(simulation: Simulation, handle: EntityHandle, clock: SimulationStepClock);
+    /** Suppress interpolation until the render buffers catch up. */
+    private markPoseDiscontinuity;
+    private isInterpolationStale;
     translation(): PhysicsVector3;
     rotation(): PhysicsQuaternion;
     linvel(): PhysicsVector3;
@@ -5044,6 +5350,22 @@ export declare class SimulationBody implements PhysicsRenderPoseProvider {
     setLinvel(velocity: PhysicsVector3, _wakeUp?: boolean): void;
     setAngvel(velocity: PhysicsVector3, _wakeUp?: boolean): void;
     applyImpulse(impulse: PhysicsVector3, _wakeUp?: boolean): void;
+    /**
+     * Rotation locks are fixed at body-creation time in the wasm runtime
+     * (`SimulationBodyDefinition.lockRotation`); there is no live setter FFI
+     * yet. Accepted for Rapier compat — when locking, the angular velocity is
+     * zeroed to approximate the intent. Prefer lock flags on the body
+     * definition at spawn time.
+     */
+    lockRotations(locked: boolean, _wakeUp?: boolean): void;
+    /**
+     * Translation locks are fixed at body-creation time in the wasm runtime
+     * (`SimulationBodyDefinition.lockTranslation`); there is no live setter
+     * FFI yet. Accepted for Rapier compat — when locking, the linear velocity
+     * is zeroed to approximate the intent. Prefer lock flags on the body
+     * definition at spawn time.
+     */
+    lockTranslations(locked: boolean, _wakeUp?: boolean): void;
     /**
      * Damping is fixed at body-creation time in the wasm runtime; there is no
      * live setter FFI yet, so this is accepted (for `MoveableBodyLike`
@@ -5342,19 +5664,7 @@ export declare type StageConfigLike = Partial<{
     postProcessingEffects: ZylemPostEffect[];
 }>;
 
-/** Payload for stage configuration sent to editor. */
-export declare interface StageConfigPayload {
-    id: string;
-    backgroundColor: string;
-    backgroundImage: string | null;
-    gravity: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    inputs: Record<string, string[]>;
-    variables: Record<string, unknown>;
-}
+export { StageConfigPayload }
 
 /**
  * Self-managing debug delegate that subscribes to `debugState` internally.
@@ -5376,16 +5686,33 @@ declare class StageDebugDelegate {
     private cameraDebugDelegate;
     private debugStateUnsubscribe;
     private focusContextUnregister;
+    private entityResolverUnregister;
+    private lastDebugEnabled;
+    private warnedMissingAddFactory;
     constructor(stage: ZylemStage, options?: StageDebugDelegateOptions);
+    /**
+     * Supply the factory the `add` tool uses to spawn entities at the clicked
+     * point. Without one the tool warns instead of silently doing nothing.
+     */
+    setAddEntityFactory(factory: AddEntityFactory | null): void;
+    /** 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;
+    /**
+     * Activate/deactivate only when `debugState.enabled` actually flips.
+     * Hover and selection write to `debugState` every frame, and `activate()`
+     * rebuilds post-processing, so reacting to every notification would
+     * rebuild the render pipeline once per frame.
+     */
     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;
@@ -5410,6 +5737,12 @@ export declare interface StageEntity extends Entity {
     instanceId: number;
     isInstanced?: boolean;
     isBundled?: boolean;
+    /**
+     * When true, `syncRenderPoses` leaves the entity's Three.js transform alone.
+     * Used for camera-parented viewmodels so physics pose sync cannot overwrite
+     * the local offset.
+     */
+    skipRenderPoseSync?: boolean;
     controlledRotation: boolean;
     name: string;
     markedForRemoval: boolean;
@@ -5772,6 +6105,8 @@ export declare const StageSchema: _sinclair_typebox.TObject<{
     assets: _sinclair_typebox.TOptional<_sinclair_typebox.TArray<_sinclair_typebox.TString>>;
 }>;
 
+export { StageSnapshotPayload }
+
 declare type StageState = ZylemStageConfig & {
     entities: GameEntityInterface[];
 };
@@ -5839,27 +6174,6 @@ export declare const standardShader: {
     fragment: string;
 };
 
-/** Payload for state dispatch events from game to editor. */
-export declare interface StateDispatchPayload {
-    scope: 'game' | 'stage' | 'entity';
-    path: string;
-    value: unknown;
-    previousValue?: unknown;
-    config?: {
-        id: string;
-        aspectRatio: number;
-        fullscreen: boolean;
-        bodyBackground: string | undefined;
-        internalResolution: {
-            width: number;
-            height: number;
-        } | undefined;
-        debug: boolean;
-    } | null;
-    stageConfig?: StageConfigPayload | null;
-    entities?: EntityConfigPayload[] | null;
-}
-
 export { step }
 
 /**
@@ -6355,6 +6669,16 @@ export declare function useMouseLook(player: InputPlayer, options?: {
     sensitivity?: number;
 }): GameInputConfig;
 
+/**
+ * Enables screen-center mouse look (free cursor, no pointer lock).
+ * Cursor offset from the game canvas center maps to yaw/pitch up to `maxLookDegrees`.
+ * @example stage.setInputConfiguration(useScreenCenterLook('p1'));
+ */
+export declare function useScreenCenterLook(player: InputPlayer, options?: {
+    maxLookDegrees?: number;
+    lookSensitivity?: number;
+}): GameInputConfig;
+
 /** Whether the entity opts into a managed render path (bundle or instanced). */
 export declare function usesManagedRenderPath(options?: RenderCategoryOptions | null): boolean;
 
@@ -6908,6 +7232,8 @@ export declare class ZylemBox extends GameEntity<ZylemBoxOptions> {
 
 declare type ZylemBoxOptions = GameEntityOptions;
 
+export { ZylemBridge }
+
 /**
  * ZylemCamera is a lightweight camera wrapper that manages the Three.js camera,
  * the camera pose pipeline, and viewport configuration. Rendering is handled
@@ -6961,6 +7287,8 @@ declare class ZylemCamera {
     private _useOrbitalControls;
     /** When true, debug-mode orbital controls are not attached to this camera. */
     _skipDebugOrbit: boolean;
+    /** Dedicated debug-view camera (e.g. `__debug__`); uses simplified orbit path. */
+    isDebugViewCamera: boolean;
     /** Reference to the shared renderer manager (set during setup). */
     private _rendererManager;
     /** Elapsed time tracker for CameraContext. */
@@ -7047,6 +7375,16 @@ declare class ZylemCamera {
      * Dispose camera resources.
      */
     destroy(): void;
+    /**
+     * Set the default orbit target for debug mode (e.g. origin anchor).
+     */
+    setDefaultOrbitTarget(target: Object3D): void;
+    /**
+     * Seed the debug orbit camera to an initial pose.
+     */
+    seedDebugOrbitPose(position: Vector3, lookAt: Vector3): void;
+    /** Whether the debug orbit camera has received its initial pose. */
+    isDebugOrbitPoseSeeded(): boolean;
     /**
      * Attach a delegate to react to debug state changes.
      * Skipped when _skipDebugOrbit is true so the pipeline always runs.
@@ -7386,16 +7724,10 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
     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;
+    /** Serialized last-published game config, for dirty-checking resize churn. */
+    private lastPublishedGameConfig;
+    /** Editor ↔ game bridge adapter (RAF-coalesced publishes, command intake). */
+    private gameBridge;
     private readonly gameUpdateParams;
     private readonly stageSetupParams;
     private readonly stageUpdateParams;
@@ -7449,27 +7781,47 @@ declare class ZylemGame<TGlobals extends BaseGlobals> {
      */
     private buildStageConfigPayload;
     /**
-     * Build the entities payload for the current stage.
+     * Build a bridge entity summary for one entity, or null for entities on
+     * the managed render path (instanced packs/bundles), which can number in
+     * the thousands and are not useful in the editor panel.
+     */
+    private buildEntitySummary;
+    /**
+     * Build the full entities payload for the current stage.
      */
     private buildEntitiesPayload;
     /**
-     * Generate entity thumbnails as entities become available, then refresh editor state.
+     * Generate entity thumbnails as entities become available, streaming
+     * upserts/thumbnails/removals to the editor through the bridge
+     * (RAF-coalesced, merged by uuid).
+     *
+     * All of this work exists only to feed the editor, and thumbnails in
+     * particular cost an offscreen render plus a pixel readback on the shared
+     * renderer. Each publisher therefore checks the bridge for a live listener
+     * first, and a late-connecting editor is backfilled from
+     * {@link wireEditorBackfill}.
      */
     private wireEntityThumbnails;
-    private clearEntityThumbnailWiring;
     /**
-     * Coalesce entity-driven state dispatches (thumbnail resolutions, entity
-     * destruction) into one trailing `emitStateDispatch` per burst.
+     * Republish the current stage when an editor subscribes after the game
+     * started. Without this, entities added while nothing was listening would
+     * never appear, since the per-entity publishers were skipped.
      */
-    private queueEntityStateDispatch;
+    private wireEditorBackfill;
+    private clearEntityThumbnailWiring;
+    private buildGameConfigPayload;
+    /** Publish the resolved display config over the bridge. */
     /**
-     * Emit a state:dispatch event to the zylemEventBus.
-     * Called after stage load and on global state changes.
+     * Publish the display config, skipping unchanged payloads. The
+     * `ResizeObserver` on `<zylem-game>` funnels into `setDisplayRuntime`, which
+     * fires on every layout tick even when nothing about the config moved.
      */
-    private emitStateDispatch;
+    private publishGameConfig;
+    /** Publish a full stage snapshot (config + entity list) over the bridge. */
+    private publishStageSnapshot;
     /**
-     * Subscribe to the game event bus for stage loading and state events.
-     * Emits events to zylemEventBus for cross-package communication.
+     * Subscribe to the game event bus for stage loading and state events,
+     * mirroring global-variable updates to the editor over the bridge.
      */
     private subscribeToEventBus;
 }