@zylem/game-lib 0.8.2 → 0.8.4

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>;
 
 /**
@@ -680,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;
 
@@ -1662,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
  */
@@ -1673,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
@@ -1804,6 +1853,8 @@ export declare function dispatchStageState(): void;
 
 export { dot }
 
+export { EditorToGameMessages }
+
 export { emitRuntimeGoal }
 
 export { emitRuntimeRicochet }
@@ -1841,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>;
 }
@@ -2029,24 +2050,47 @@ 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.
+ *
+ * A rendered URL leaves this cache the moment it is read, and the editor holds
+ * it for as long as the entity is listed. Dropping an entry here therefore
+ * must not revoke its blob URL — the consumer owns that lifetime and releases
+ * it when the thumbnail is replaced, the entity is removed, or the stage
+ * changes.
  */
 export declare class EntityThumbnailCache {
     private cache;
     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;
 }
 
@@ -2057,7 +2101,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'>;
 }
@@ -2458,6 +2508,103 @@ 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.
+     *
+     * An editor takes out both entity subscriptions as it mounts, and each is
+     * a first-subscriber transition. Backfilling on both would republish the
+     * config, the whole stage snapshot, and every thumbnail twice per mount,
+     * so a signal is ignored while the other entity type still has a
+     * listener — that is the same editor finishing its setup, not a new one.
+     *
+     * @returns An unsubscribe function.
+     */
+    onEditorAttached(callback: () => void): () => void;
+    publishConfig(config: GameConfigPayload): void;
+    publishLoading(payload: BridgeLoadingPayload): void;
+    publishStatus(status: {
+        paused?: boolean;
+        debug?: boolean;
+    }): void;
+    /**
+     * Publish a global's new value.
+     *
+     * Sent rather than queued: a queued payload is merged into the pending one
+     * for its type, and since each message names a single `path`, two globals
+     * changing in the same frame would collapse into one and the first
+     * variable's update would never reach the editor.
+     */
+    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)
@@ -2668,6 +2815,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;
@@ -2994,7 +3143,6 @@ export declare type GameEvents = {
     'debug': {
         enabled: boolean;
     };
-    'state:dispatch': StateDispatchPayload;
 };
 
 export declare interface GameInputConfig {
@@ -3212,6 +3360,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 }
@@ -3232,6 +3384,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;
@@ -3241,6 +3398,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
@@ -3250,6 +3412,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) => { ... }))
@@ -4322,6 +4486,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.
  */
@@ -4600,6 +4773,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;
@@ -5038,6 +5214,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 }
@@ -5088,7 +5266,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;
 
@@ -5174,8 +5358,16 @@ export declare class SimulationBody implements PhysicsRenderPoseProvider {
      */
     private interpolationValidAfterStep;
     constructor(simulation: Simulation, handle: EntityHandle, clock: SimulationStepClock);
-    /** Suppress interpolation until the render buffers catch up. */
-    private markPoseDiscontinuity;
+    /**
+     * Suppress interpolation until the render buffers catch up.
+     *
+     * Called automatically by the pose setters below. Wasm-side behaviors that
+     * teleport a body during a step (e.g. `screen_wrap`) bypass those setters,
+     * so their host systems must call this after the step and before render
+     * poses are synced — otherwise the render buffers straddle the teleport and
+     * the body is drawn sweeping between the two poses.
+     */
+    markPoseDiscontinuity(): void;
     private isInterpolationStale;
     translation(): PhysicsVector3;
     rotation(): PhysicsQuaternion;
@@ -5333,6 +5525,21 @@ export declare type SpriteImage = {
 
 declare type SpriteOptions = BaseNode | Partial<ZylemSpriteOptions>;
 
+/**
+ * A single texture divided into a uniform grid of frames, addressed by UV
+ * offset. Prefer this over {@link SpriteImage} lists for character sheets: one
+ * texture and one draw call instead of one per frame.
+ */
+export declare type SpriteSheet = {
+    file: string;
+    columns: number;
+    rows: number;
+    /** Frame names in row-major order. `null` marks an unused cell. */
+    frames: Array<string | null>;
+    /** Texture filtering. Defaults to `nearest`, which keeps pixel art crisp. */
+    filter?: 'nearest' | 'linear';
+};
+
 declare class Stage {
     wrappedStage: ZylemStage | null;
     options: StageOptionItem[];
@@ -5500,19 +5707,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.
@@ -5534,13 +5729,27 @@ 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 switch rendering to the debug orbit camera. */
     private activate;
@@ -5939,6 +6148,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[];
 };
@@ -6006,27 +6217,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 }
 
 /**
@@ -7085,6 +7275,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
@@ -7575,16 +7767,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;
@@ -7638,27 +7824,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;
 }
@@ -8092,15 +8298,34 @@ export declare class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
     protected spriteMap: Map<string, number>;
     protected currentSpriteIndex: number;
     protected animations: Map<string, any>;
-    protected currentAnimation: any;
+    protected currentAnimation: string | null;
     protected currentAnimationFrame: string;
     protected currentAnimationIndex: number;
     protected currentAnimationTime: number;
+    /** Set only in sheet mode; the shared texture whose UV window we shift. */
+    protected sheetTexture: Texture | null;
+    protected flippedX: boolean;
     constructor(options?: ZylemSpriteOptions);
     create(): this;
     protected createSpritesFromImages(images: SpriteImage[]): void;
+    protected createSpriteFromSheet(sheet: SpriteSheet): void;
     protected createAnimations(animations: SpriteAnimation[]): void;
     setSprite(key: string): void;
+    /**
+     * Mirror the sprite horizontally, for characters whose sheet only contains
+     * one facing direction.
+     *
+     * In sheet mode this flips the UV window rather than the sprite scale,
+     * because {@link syncSpriteMaterials} rewrites scale from `options.size`
+     * every frame and would immediately undo a negative scale.
+     */
+    setFlipX(flip: boolean): void;
+    isFlippedX(): boolean;
+    private applySheetFrame;
+    /**
+     * Advance a named clip. Call once per frame from an update loop; `delta` is
+     * seconds, so scaling it scales playback rate.
+     */
     setAnimation(name: string, delta: number): void;
     private getCurrentRotationQuaternion;
     private syncSpriteMaterials;
@@ -8112,6 +8337,7 @@ export declare class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
 
 declare type ZylemSpriteOptions = GameEntityOptions & {
     images?: SpriteImage[];
+    sheet?: SpriteSheet;
     animations?: SpriteAnimation[];
     size?: Vec3Input;
     collisionSize?: Vec3Input;