@zylem/game-lib 0.5.1 → 0.6.0

package/dist/stage.js

@@ -1,12 +1,56 @@
 // src/lib/stage/zylem-stage.ts
 import { addComponent, addEntity, createWorld as createECS, removeEntity } from "bitecs";
-import { Color as Color6, Vector3 as Vector310, Vector2 as Vector25 } from "three";
+import { Color as Color7, Vector3 as Vector311 } from "three";
 
 // src/lib/collision/world.ts
 import RAPIER from "@dimforge/rapier3d-compat";
 
 // src/lib/game/game-state.ts
 import { proxy, subscribe } from "valtio/vanilla";
+
+// src/lib/game/game-event-bus.ts
+var GameEventBus = class {
+  listeners = /* @__PURE__ */ new Map();
+  /**
+   * Subscribe to an event type.
+   */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return () => this.off(event, callback);
+  }
+  /**
+   * Unsubscribe from an event type.
+   */
+  off(event, callback) {
+    this.listeners.get(event)?.delete(callback);
+  }
+  /**
+   * Emit an event to all subscribers.
+   */
+  emit(event, payload) {
+    const callbacks = this.listeners.get(event);
+    if (!callbacks) return;
+    for (const cb of callbacks) {
+      try {
+        cb(payload);
+      } catch (e) {
+        console.error(`Error in event handler for ${event}`, e);
+      }
+    }
+  }
+  /**
+   * Clear all listeners.
+   */
+  dispose() {
+    this.listeners.clear();
+  }
+};
+var gameEventBus = new GameEventBus();
+
+// src/lib/game/game-state.ts
 var state = proxy({
   id: "",
   globals: {},
@@ -28,7 +72,8 @@ import {
   defineSystem,
   defineQuery,
   defineComponent,
-  Types
+  Types,
+  removeQuery
 } from "bitecs";
 import { Quaternion } from "three";
 var position = defineComponent({
@@ -47,52 +92,49 @@ var scale = defineComponent({
   y: Types.f32,
   z: Types.f32
 });
+var _tempQuaternion = new Quaternion();
 function createTransformSystem(stage) {
-  const transformQuery = defineQuery([position, rotation]);
+  const queryTerms = [position, rotation];
+  const transformQuery = defineQuery(queryTerms);
   const stageEntities = stage._childrenMap;
-  return defineSystem((world) => {
+  const system = defineSystem((world) => {
     const entities = transformQuery(world);
     if (stageEntities === void 0) {
       return world;
     }
-    ;
-    for (const [key, value] of stageEntities) {
-      const id = entities[key];
-      const stageEntity = value;
-      if (stageEntity === void 0 || !stageEntity?.body || stageEntity.markedForRemoval) {
+    for (const [key, stageEntity] of stageEntities) {
+      if (!stageEntity?.body || stageEntity.markedForRemoval) {
         continue;
       }
-      const { x, y, z } = stageEntity.body.translation();
-      position.x[id] = x;
-      position.y[id] = y;
-      position.z[id] = z;
-      if (stageEntity.group) {
-        stageEntity.group.position.set(position.x[id], position.y[id], position.z[id]);
-      } else if (stageEntity.mesh) {
-        stageEntity.mesh.position.set(position.x[id], position.y[id], position.z[id]);
+      const id = entities[key];
+      const body = stageEntity.body;
+      const target = stageEntity.group ?? stageEntity.mesh;
+      const translation = body.translation();
+      position.x[id] = translation.x;
+      position.y[id] = translation.y;
+      position.z[id] = translation.z;
+      if (target) {
+        target.position.set(translation.x, translation.y, translation.z);
       }
       if (stageEntity.controlledRotation) {
         continue;
       }
-      const { x: rx, y: ry, z: rz, w: rw } = stageEntity.body.rotation();
-      rotation.x[id] = rx;
-      rotation.y[id] = ry;
-      rotation.z[id] = rz;
-      rotation.w[id] = rw;
-      const newRotation = new Quaternion(
-        rotation.x[id],
-        rotation.y[id],
-        rotation.z[id],
-        rotation.w[id]
-      );
-      if (stageEntity.group) {
-        stageEntity.group.setRotationFromQuaternion(newRotation);
-      } else if (stageEntity.mesh) {
-        stageEntity.mesh.setRotationFromQuaternion(newRotation);
+      const rot = body.rotation();
+      rotation.x[id] = rot.x;
+      rotation.y[id] = rot.y;
+      rotation.z[id] = rot.z;
+      rotation.w[id] = rot.w;
+      if (target) {
+        _tempQuaternion.set(rot.x, rot.y, rot.z, rot.w);
+        target.setRotationFromQuaternion(_tempQuaternion);
       }
     }
     return world;
   });
+  const destroy = (world) => {
+    removeQuery(world, transformQuery);
+  };
+  return { system, destroy };
 }
 
 // src/lib/core/flags.ts
@@ -108,21 +150,76 @@ var BaseNode = class _BaseNode {
   uuid = "";
   name = "";
   markedForRemoval = false;
-  setup = () => {
-  };
-  loaded = () => {
-  };
-  update = () => {
-  };
-  destroy = () => {
-  };
-  cleanup = () => {
+  /**
+   * Lifecycle callback arrays - use onSetup(), onUpdate(), etc. to add callbacks
+   */
+  lifecycleCallbacks = {
+    setup: [],
+    loaded: [],
+    update: [],
+    destroy: [],
+    cleanup: []
   };
   constructor(args = []) {
     const options = args.filter((arg) => !(arg instanceof _BaseNode)).reduce((acc, opt) => ({ ...acc, ...opt }), {});
     this.options = options;
     this.uuid = nanoid();
   }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Fluent API for adding lifecycle callbacks
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Add setup callbacks to be executed in order during nodeSetup
+   */
+  onSetup(...callbacks) {
+    this.lifecycleCallbacks.setup.push(...callbacks);
+    return this;
+  }
+  /**
+   * Add loaded callbacks to be executed in order during nodeLoaded
+   */
+  onLoaded(...callbacks) {
+    this.lifecycleCallbacks.loaded.push(...callbacks);
+    return this;
+  }
+  /**
+   * Add update callbacks to be executed in order during nodeUpdate
+   */
+  onUpdate(...callbacks) {
+    this.lifecycleCallbacks.update.push(...callbacks);
+    return this;
+  }
+  /**
+   * Add destroy callbacks to be executed in order during nodeDestroy
+   */
+  onDestroy(...callbacks) {
+    this.lifecycleCallbacks.destroy.push(...callbacks);
+    return this;
+  }
+  /**
+   * Add cleanup callbacks to be executed in order during nodeCleanup
+   */
+  onCleanup(...callbacks) {
+    this.lifecycleCallbacks.cleanup.push(...callbacks);
+    return this;
+  }
+  /**
+   * Prepend setup callbacks (run before existing ones)
+   */
+  prependSetup(...callbacks) {
+    this.lifecycleCallbacks.setup.unshift(...callbacks);
+    return this;
+  }
+  /**
+   * Prepend update callbacks (run before existing ones)
+   */
+  prependUpdate(...callbacks) {
+    this.lifecycleCallbacks.update.unshift(...callbacks);
+    return this;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tree structure
+  // ─────────────────────────────────────────────────────────────────────────────
   setParent(parent) {
     this.parent = parent;
   }
@@ -146,6 +243,9 @@ var BaseNode = class _BaseNode {
   isComposite() {
     return this.children.length > 0;
   }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Node lifecycle execution - runs internal + callback arrays
+  // ─────────────────────────────────────────────────────────────────────────────
   nodeSetup(params) {
     if (DEBUG_FLAG) {
     }
@@ -153,8 +253,8 @@ var BaseNode = class _BaseNode {
     if (typeof this._setup === "function") {
       this._setup(params);
     }
-    if (this.setup) {
-      this.setup(params);
+    for (const callback of this.lifecycleCallbacks.setup) {
+      callback(params);
     }
     this.children.forEach((child) => child.nodeSetup(params));
   }
@@ -165,21 +265,40 @@ var BaseNode = class _BaseNode {
     if (typeof this._update === "function") {
       this._update(params);
     }
-    if (this.update) {
-      this.update(params);
+    for (const callback of this.lifecycleCallbacks.update) {
+      callback(params);
     }
     this.children.forEach((child) => child.nodeUpdate(params));
   }
   nodeDestroy(params) {
     this.children.forEach((child) => child.nodeDestroy(params));
-    if (this.destroy) {
-      this.destroy(params);
+    for (const callback of this.lifecycleCallbacks.destroy) {
+      callback(params);
     }
     if (typeof this._destroy === "function") {
       this._destroy(params);
     }
     this.markedForRemoval = true;
   }
+  async nodeLoaded(params) {
+    if (typeof this._loaded === "function") {
+      await this._loaded(params);
+    }
+    for (const callback of this.lifecycleCallbacks.loaded) {
+      callback(params);
+    }
+  }
+  async nodeCleanup(params) {
+    for (const callback of this.lifecycleCallbacks.cleanup) {
+      callback(params);
+    }
+    if (typeof this._cleanup === "function") {
+      await this._cleanup(params);
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Options
+  // ─────────────────────────────────────────────────────────────────────────────
   getOptions() {
     return this.options;
   }
@@ -201,11 +320,6 @@ var GameEntity = class extends BaseNode {
   custom = {};
   debugInfo = {};
   debugMaterial;
-  lifeCycleDelegate = {
-    setup: [],
-    update: [],
-    destroy: []
-  };
   collisionDelegate = {
     collision: []
   };
@@ -230,67 +344,40 @@ var GameEntity = class extends BaseNode {
     this.name = this.options.name || "";
     return this;
   }
-  onSetup(...callbacks) {
-    const combineCallbacks = [...this.lifeCycleDelegate.setup ?? [], ...callbacks];
-    this.lifeCycleDelegate = {
-      ...this.lifeCycleDelegate,
-      setup: combineCallbacks
-    };
-    return this;
-  }
-  onUpdate(...callbacks) {
-    const combineCallbacks = [...this.lifeCycleDelegate.update ?? [], ...callbacks];
-    this.lifeCycleDelegate = {
-      ...this.lifeCycleDelegate,
-      update: combineCallbacks
-    };
-    return this;
-  }
-  onDestroy(...callbacks) {
-    this.lifeCycleDelegate = {
-      ...this.lifeCycleDelegate,
-      destroy: callbacks.length > 0 ? callbacks : void 0
-    };
-    return this;
-  }
+  /**
+   * Add collision callbacks
+   */
   onCollision(...callbacks) {
-    this.collisionDelegate = {
-      collision: callbacks.length > 0 ? callbacks : void 0
-    };
+    const existing = this.collisionDelegate.collision ?? [];
+    this.collisionDelegate.collision = [...existing, ...callbacks];
     return this;
   }
+  /**
+   * Entity-specific setup - runs behavior callbacks
+   * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
+   */
   _setup(params) {
     this.behaviorCallbackMap.setup.forEach((callback) => {
       callback({ ...params, me: this });
     });
-    if (this.lifeCycleDelegate.setup?.length) {
-      const callbacks = this.lifeCycleDelegate.setup;
-      callbacks.forEach((callback) => {
-        callback({ ...params, me: this });
-      });
-    }
   }
   async _loaded(_params) {
   }
+  /**
+   * Entity-specific update - updates materials and runs behavior callbacks
+   * (User callbacks are handled by BaseNode's lifecycleCallbacks.update)
+   */
   _update(params) {
     this.updateMaterials(params);
-    if (this.lifeCycleDelegate.update?.length) {
-      const callbacks = this.lifeCycleDelegate.update;
-      callbacks.forEach((callback) => {
-        callback({ ...params, me: this });
-      });
-    }
     this.behaviorCallbackMap.update.forEach((callback) => {
       callback({ ...params, me: this });
     });
   }
+  /**
+   * Entity-specific destroy - runs behavior callbacks
+   * (User callbacks are handled by BaseNode's lifecycleCallbacks.destroy)
+   */
   _destroy(params) {
-    if (this.lifeCycleDelegate.destroy?.length) {
-      const callbacks = this.lifeCycleDelegate.destroy;
-      callbacks.forEach((callback) => {
-        callback({ ...params, me: this });
-      });
-    }
     this.behaviorCallbackMap.destroy.forEach((callback) => {
       callback({ ...params, me: this });
     });
@@ -481,6 +568,23 @@ var AnimationDelegate = class {
     this._currentAction = action;
     this._currentKey = key;
   }
+  /**
+   * Dispose of all animation resources
+   */
+  dispose() {
+    Object.values(this._actions).forEach((action) => {
+      action.stop();
+    });
+    if (this._mixer) {
+      this._mixer.stopAllAction();
+      this._mixer.uncacheRoot(this.target);
+      this._mixer = null;
+    }
+    this._actions = {};
+    this._animations = [];
+    this._currentAction = null;
+    this._currentKey = "";
+  }
   get currentAnimationKey() {
     return this._currentKey;
   }
@@ -506,7 +610,7 @@ var actorDefaults = {
   animations: [],
   models: []
 };
-var ACTOR_TYPE = Symbol("Actor");
+var ACTOR_TYPE = /* @__PURE__ */ Symbol("Actor");
 var ZylemActor = class extends GameEntity {
   static type = ACTOR_TYPE;
   _object = null;
@@ -517,9 +621,7 @@ var ZylemActor = class extends GameEntity {
   constructor(options) {
     super();
     this.options = { ...actorDefaults, ...options };
-    this.lifeCycleDelegate = {
-      update: [this.actorUpdate.bind(this)]
-    };
+    this.prependUpdate(this.actorUpdate.bind(this));
     this.controlledRotation = true;
   }
   async load() {
@@ -539,6 +641,34 @@ var ZylemActor = class extends GameEntity {
   async actorUpdate(params) {
     this._animationDelegate?.update(params.delta);
   }
+  /**
+   * Clean up actor resources including animations, models, and groups
+   */
+  actorDestroy() {
+    if (this._animationDelegate) {
+      this._animationDelegate.dispose();
+      this._animationDelegate = null;
+    }
+    if (this._object) {
+      this._object.traverse((child) => {
+        if (child.isMesh) {
+          const mesh = child;
+          mesh.geometry?.dispose();
+          if (Array.isArray(mesh.material)) {
+            mesh.material.forEach((m) => m.dispose());
+          } else if (mesh.material) {
+            mesh.material.dispose();
+          }
+        }
+      });
+      this._object = null;
+    }
+    if (this.group) {
+      this.group.clear();
+      this.group = null;
+    }
+    this._modelFileNames = [];
+  }
   async loadModels() {
     if (this._modelFileNames.length === 0) return;
     const promises = this._modelFileNames.map((file) => this._assetLoader.loadFile(file));
@@ -596,12 +726,10 @@ var ZylemActor = class extends GameEntity {
   }
 };
 
-// src/lib/collision/collision-delegate.ts
+// src/lib/collision/world.ts
 function isCollisionHandlerDelegate(obj) {
   return typeof obj?.handlePostCollision === "function" && typeof obj?.handleIntersectionEvent === "function";
 }
-
-// src/lib/collision/world.ts
 var ZylemWorld = class {
   type = "World";
   world;
@@ -827,7 +955,11 @@ var ZylemScene = class {
    * Setup camera with the scene
    */
   setupCamera(scene, camera) {
-    scene.add(camera.cameraRig);
+    if (camera.cameraRig) {
+      scene.add(camera.cameraRig);
+    } else {
+      scene.add(camera.camera);
+    }
     camera.setup(scene);
   }
   /**
@@ -922,6 +1054,9 @@ var ZylemBlueColor = new Color4("#0333EC");
 var Vec0 = new Vector34(0, 0, 0);
 var Vec1 = new Vector34(1, 1, 1);
 
+// src/lib/stage/zylem-stage.ts
+import { subscribe as subscribe4 } from "valtio/vanilla";
+
 // src/lib/core/lifecycle-base.ts
 var LifeCycleBase = class {
   update = () => {
@@ -959,67 +1094,334 @@ var LifeCycleBase = class {
 // src/lib/stage/zylem-stage.ts
 import { nanoid as nanoid2 } from "nanoid";
 
-// src/lib/camera/perspective.ts
-var Perspectives = {
-  FirstPerson: "first-person",
-  ThirdPerson: "third-person",
-  Isometric: "isometric",
-  Flat2D: "flat-2d",
-  Fixed2D: "fixed-2d"
-};
-
-// src/lib/camera/camera.ts
-import { Vector2 as Vector23, Vector3 as Vector37 } from "three";
-
-// src/lib/camera/zylem-camera.ts
-import { PerspectiveCamera, Vector3 as Vector36, Object3D as Object3D4, OrthographicCamera, WebGLRenderer as WebGLRenderer3 } from "three";
-import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+// src/lib/stage/stage-debug-delegate.ts
+import { Ray } from "@dimforge/rapier3d-compat";
+import { BufferAttribute, BufferGeometry as BufferGeometry2, LineBasicMaterial as LineBasicMaterial2, LineSegments as LineSegments2, Raycaster, Vector2 } from "three";
 
-// src/lib/camera/third-person.ts
-import { Vector3 as Vector35 } from "three";
-var ThirdPersonCamera = class {
-  distance;
-  screenResolution = null;
-  renderer = null;
-  scene = null;
-  cameraRef = null;
-  constructor() {
-    this.distance = new Vector35(0, 5, 8);
-  }
-  /**
-   * Setup the third person camera controller
-   */
-  setup(params) {
-    const { screenResolution, renderer, scene, camera } = params;
-    this.screenResolution = screenResolution;
-    this.renderer = renderer;
+// src/lib/stage/debug-entity-cursor.ts
+import {
+  Box3,
+  BoxGeometry,
+  Color as Color5,
+  EdgesGeometry,
+  Group as Group3,
+  LineBasicMaterial,
+  LineSegments,
+  Mesh as Mesh2,
+  MeshBasicMaterial,
+  Vector3 as Vector35
+} from "three";
+var DebugEntityCursor = class {
+  scene;
+  container;
+  fillMesh;
+  edgeLines;
+  currentColor = new Color5(65280);
+  bbox = new Box3();
+  size = new Vector35();
+  center = new Vector35();
+  constructor(scene) {
     this.scene = scene;
-    this.cameraRef = camera;
+    const initialGeometry = new BoxGeometry(1, 1, 1);
+    this.fillMesh = new Mesh2(
+      initialGeometry,
+      new MeshBasicMaterial({
+        color: this.currentColor,
+        transparent: true,
+        opacity: 0.12,
+        depthWrite: false
+      })
+    );
+    const edges = new EdgesGeometry(initialGeometry);
+    this.edgeLines = new LineSegments(
+      edges,
+      new LineBasicMaterial({ color: this.currentColor, linewidth: 1 })
+    );
+    this.container = new Group3();
+    this.container.name = "DebugEntityCursor";
+    this.container.add(this.fillMesh);
+    this.container.add(this.edgeLines);
+    this.container.visible = false;
+    this.scene.add(this.container);
+  }
+  setColor(color) {
+    this.currentColor.set(color);
+    this.fillMesh.material.color.set(this.currentColor);
+    this.edgeLines.material.color.set(this.currentColor);
   }
   /**
-   * Update the third person camera
+   * Update the cursor to enclose the provided Object3D using a world-space AABB.
    */
-  update(delta) {
-    if (!this.cameraRef.target) {
+  updateFromObject(object) {
+    if (!object) {
+      this.hide();
       return;
     }
-    const desiredCameraPosition = this.cameraRef.target.group.position.clone().add(this.distance);
-    this.cameraRef.camera.position.lerp(desiredCameraPosition, 0.1);
-    this.cameraRef.camera.lookAt(this.cameraRef.target.group.position);
-  }
-  /**
-   * Handle resize events
-   */
-  resize(width, height) {
-    if (this.screenResolution) {
-      this.screenResolution.set(width, height);
+    this.bbox.setFromObject(object);
+    if (!isFinite(this.bbox.min.x) || !isFinite(this.bbox.max.x)) {
+      this.hide();
+      return;
     }
+    this.bbox.getSize(this.size);
+    this.bbox.getCenter(this.center);
+    const newGeom = new BoxGeometry(
+      Math.max(this.size.x, 1e-6),
+      Math.max(this.size.y, 1e-6),
+      Math.max(this.size.z, 1e-6)
+    );
+    this.fillMesh.geometry.dispose();
+    this.fillMesh.geometry = newGeom;
+    const newEdges = new EdgesGeometry(newGeom);
+    this.edgeLines.geometry.dispose();
+    this.edgeLines.geometry = newEdges;
+    this.container.position.copy(this.center);
+    this.container.visible = true;
   }
-  /**
-   * Set the distance from the target
-   */
-  setDistance(distance) {
-    this.distance = distance;
+  hide() {
+    this.container.visible = false;
+  }
+  dispose() {
+    this.scene.remove(this.container);
+    this.fillMesh.geometry.dispose();
+    this.fillMesh.material.dispose();
+    this.edgeLines.geometry.dispose();
+    this.edgeLines.material.dispose();
+  }
+};
+
+// src/lib/stage/stage-debug-delegate.ts
+var SELECT_TOOL_COLOR = 2293538;
+var DELETE_TOOL_COLOR = 16724787;
+var StageDebugDelegate = class {
+  stage;
+  options;
+  mouseNdc = new Vector2(-2, -2);
+  raycaster = new Raycaster();
+  isMouseDown = false;
+  disposeFns = [];
+  debugCursor = null;
+  debugLines = null;
+  constructor(stage, options) {
+    this.stage = stage;
+    this.options = {
+      maxRayDistance: options?.maxRayDistance ?? 5e3,
+      addEntityFactory: options?.addEntityFactory ?? null
+    };
+    if (this.stage.scene) {
+      this.debugLines = new LineSegments2(
+        new BufferGeometry2(),
+        new LineBasicMaterial2({ vertexColors: true })
+      );
+      this.stage.scene.scene.add(this.debugLines);
+      this.debugLines.visible = true;
+      this.debugCursor = new DebugEntityCursor(this.stage.scene.scene);
+    }
+    this.attachDomListeners();
+  }
+  update() {
+    if (!debugState.enabled) return;
+    if (!this.stage.scene || !this.stage.world || !this.stage.cameraRef) return;
+    const { world, cameraRef } = this.stage;
+    if (this.debugLines) {
+      const { vertices, colors } = world.world.debugRender();
+      this.debugLines.geometry.setAttribute("position", new BufferAttribute(vertices, 3));
+      this.debugLines.geometry.setAttribute("color", new BufferAttribute(colors, 4));
+    }
+    const tool = getDebugTool();
+    const isCursorTool = tool === "select" || tool === "delete";
+    this.raycaster.setFromCamera(this.mouseNdc, cameraRef.camera);
+    const origin = this.raycaster.ray.origin.clone();
+    const direction = this.raycaster.ray.direction.clone().normalize();
+    const rapierRay = new Ray(
+      { x: origin.x, y: origin.y, z: origin.z },
+      { x: direction.x, y: direction.y, z: direction.z }
+    );
+    const hit = world.world.castRay(rapierRay, this.options.maxRayDistance, true);
+    if (hit && isCursorTool) {
+      const rigidBody = hit.collider?._parent;
+      const hoveredUuid2 = rigidBody?.userData?.uuid;
+      if (hoveredUuid2) {
+        const entity = this.stage._debugMap.get(hoveredUuid2);
+        if (entity) setHoveredEntity(entity);
+      } else {
+        resetHoveredEntity();
+      }
+      if (this.isMouseDown) {
+        this.handleActionOnHit(hoveredUuid2 ?? null, origin, direction, hit.toi);
+      }
+    }
+    this.isMouseDown = false;
+    const hoveredUuid = getHoveredEntity();
+    if (!hoveredUuid) {
+      this.debugCursor?.hide();
+      return;
+    }
+    const hoveredEntity = this.stage._debugMap.get(`${hoveredUuid}`);
+    const targetObject = hoveredEntity?.group ?? hoveredEntity?.mesh ?? null;
+    if (!targetObject) {
+      this.debugCursor?.hide();
+      return;
+    }
+    switch (tool) {
+      case "select":
+        this.debugCursor?.setColor(SELECT_TOOL_COLOR);
+        break;
+      case "delete":
+        this.debugCursor?.setColor(DELETE_TOOL_COLOR);
+        break;
+      default:
+        this.debugCursor?.setColor(16777215);
+        break;
+    }
+    this.debugCursor?.updateFromObject(targetObject);
+  }
+  dispose() {
+    this.disposeFns.forEach((fn) => fn());
+    this.disposeFns = [];
+    this.debugCursor?.dispose();
+    if (this.debugLines && this.stage.scene) {
+      this.stage.scene.scene.remove(this.debugLines);
+      this.debugLines.geometry.dispose();
+      this.debugLines.material.dispose();
+      this.debugLines = null;
+    }
+  }
+  handleActionOnHit(hoveredUuid, origin, direction, toi) {
+    const tool = getDebugTool();
+    switch (tool) {
+      case "select": {
+        if (hoveredUuid) {
+          const entity = this.stage._debugMap.get(hoveredUuid);
+          if (entity) setSelectedEntity(entity);
+        }
+        break;
+      }
+      case "delete": {
+        if (hoveredUuid) {
+          this.stage.removeEntityByUuid(hoveredUuid);
+        }
+        break;
+      }
+      case "scale": {
+        if (!this.options.addEntityFactory) break;
+        const hitPosition = origin.clone().add(direction.clone().multiplyScalar(toi));
+        const newNode = this.options.addEntityFactory({ position: hitPosition });
+        if (newNode) {
+          Promise.resolve(newNode).then((node) => {
+            if (node) this.stage.spawnEntity(node);
+          }).catch(() => {
+          });
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  attachDomListeners() {
+    const canvas = this.stage.cameraRef?.renderer.domElement ?? this.stage.scene?.zylemCamera.renderer.domElement;
+    if (!canvas) return;
+    const onMouseMove = (e) => {
+      const rect = canvas.getBoundingClientRect();
+      const x = (e.clientX - rect.left) / rect.width * 2 - 1;
+      const y = -((e.clientY - rect.top) / rect.height * 2 - 1);
+      this.mouseNdc.set(x, y);
+    };
+    const onMouseDown = (e) => {
+      this.isMouseDown = true;
+    };
+    canvas.addEventListener("mousemove", onMouseMove);
+    canvas.addEventListener("mousedown", onMouseDown);
+    this.disposeFns.push(() => canvas.removeEventListener("mousemove", onMouseMove));
+    this.disposeFns.push(() => canvas.removeEventListener("mousedown", onMouseDown));
+  }
+};
+
+// src/lib/stage/stage-camera-debug-delegate.ts
+import { subscribe as subscribe3 } from "valtio/vanilla";
+var StageCameraDebugDelegate = class {
+  stage;
+  constructor(stage) {
+    this.stage = stage;
+  }
+  subscribe(listener) {
+    const notify = () => listener(this.snapshot());
+    notify();
+    return subscribe3(debugState, notify);
+  }
+  resolveTarget(uuid) {
+    const entity = this.stage._debugMap.get(uuid) || this.stage.world?.collisionMap.get(uuid) || null;
+    const target = entity?.group ?? entity?.mesh ?? null;
+    return target ?? null;
+  }
+  snapshot() {
+    return {
+      enabled: debugState.enabled,
+      selected: debugState.selectedEntity ? [debugState.selectedEntity.uuid] : []
+    };
+  }
+};
+
+// src/lib/stage/stage-camera-delegate.ts
+import { Vector2 as Vector24 } from "three";
+
+// src/lib/camera/zylem-camera.ts
+import { PerspectiveCamera, Vector3 as Vector39, Object3D as Object3D6, OrthographicCamera, WebGLRenderer as WebGLRenderer3 } from "three";
+
+// src/lib/camera/perspective.ts
+var Perspectives = {
+  FirstPerson: "first-person",
+  ThirdPerson: "third-person",
+  Isometric: "isometric",
+  Flat2D: "flat-2d",
+  Fixed2D: "fixed-2d"
+};
+
+// src/lib/camera/third-person.ts
+import { Vector3 as Vector37 } from "three";
+var ThirdPersonCamera = class {
+  distance;
+  screenResolution = null;
+  renderer = null;
+  scene = null;
+  cameraRef = null;
+  constructor() {
+    this.distance = new Vector37(0, 5, 8);
+  }
+  /**
+   * Setup the third person camera controller
+   */
+  setup(params) {
+    const { screenResolution, renderer, scene, camera } = params;
+    this.screenResolution = screenResolution;
+    this.renderer = renderer;
+    this.scene = scene;
+    this.cameraRef = camera;
+  }
+  /**
+   * Update the third person camera
+   */
+  update(delta) {
+    if (!this.cameraRef.target) {
+      return;
+    }
+    const desiredCameraPosition = this.cameraRef.target.group.position.clone().add(this.distance);
+    this.cameraRef.camera.position.lerp(desiredCameraPosition, 0.1);
+    this.cameraRef.camera.lookAt(this.cameraRef.target.group.position);
+  }
+  /**
+   * Handle resize events
+   */
+  resize(width, height) {
+    if (this.screenResolution) {
+      this.screenResolution.set(width, height);
+    }
+  }
+  /**
+   * Set the distance from the target
+   */
+  setDistance(distance) {
+    this.distance = distance;
   }
 };
 
@@ -1146,109 +1548,42 @@ var RenderPass = class extends Pass {
   }
 };
 
-// src/lib/camera/zylem-camera.ts
-var ZylemCamera = class {
-  cameraRig;
+// src/lib/camera/camera-debug-delegate.ts
+import { Vector3 as Vector38 } from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+var CameraOrbitController = class {
   camera;
-  screenResolution;
-  renderer;
-  composer;
-  _perspective;
+  domElement;
   orbitControls = null;
-  target = null;
-  sceneRef = null;
-  frustumSize = 10;
-  // Perspective controller delegation
-  perspectiveController = null;
+  orbitTarget = null;
+  orbitTargetWorldPos = new Vector38();
   debugDelegate = null;
   debugUnsubscribe = null;
   debugStateSnapshot = { enabled: false, selected: [] };
-  orbitTarget = null;
-  orbitTargetWorldPos = new Vector36();
-  constructor(perspective, screenResolution, frustumSize = 10) {
-    this._perspective = perspective;
-    this.screenResolution = screenResolution;
-    this.frustumSize = frustumSize;
-    this.renderer = new WebGLRenderer3({ antialias: false, alpha: true });
-    this.renderer.setSize(screenResolution.x, screenResolution.y);
-    this.renderer.shadowMap.enabled = true;
-    this.composer = new EffectComposer(this.renderer);
-    const aspectRatio = screenResolution.x / screenResolution.y;
-    this.camera = this.createCameraForPerspective(aspectRatio);
-    this.cameraRig = new Object3D4();
-    this.cameraRig.position.set(0, 3, 10);
-    this.cameraRig.add(this.camera);
-    this.camera.lookAt(new Vector36(0, 2, 0));
-    this.initializePerspectiveController();
+  // Saved camera state for restoration when exiting debug mode
+  savedCameraPosition = null;
+  savedCameraQuaternion = null;
+  savedCameraZoom = null;
+  constructor(camera, domElement) {
+    this.camera = camera;
+    this.domElement = domElement;
   }
   /**
-   * Setup the camera with a scene
+   * Check if debug mode is currently active (orbit controls enabled).
    */
-  async setup(scene) {
-    this.sceneRef = scene;
-    if (this.orbitControls === null) {
-      this.orbitControls = new OrbitControls(this.camera, this.renderer.domElement);
-      this.orbitControls.enableDamping = true;
-      this.orbitControls.dampingFactor = 0.05;
-      this.orbitControls.screenSpacePanning = false;
-      this.orbitControls.minDistance = 1;
-      this.orbitControls.maxDistance = 500;
-      this.orbitControls.maxPolarAngle = Math.PI / 2;
-    }
-    let renderResolution = this.screenResolution.clone().divideScalar(2);
-    renderResolution.x |= 0;
-    renderResolution.y |= 0;
-    const pass = new RenderPass(renderResolution, scene, this.camera);
-    this.composer.addPass(pass);
-    if (this.perspectiveController) {
-      this.perspectiveController.setup({
-        screenResolution: this.screenResolution,
-        renderer: this.renderer,
-        scene,
-        camera: this
-      });
-    }
-    this.renderer.setAnimationLoop((delta) => {
-      this.update(delta || 0);
-    });
+  get isActive() {
+    return this.debugStateSnapshot.enabled;
   }
   /**
-   * Update camera and render
+   * Update orbit controls each frame.
+   * Should be called from the camera's update loop.
    */
-  update(delta) {
+  update() {
     if (this.orbitControls && this.orbitTarget) {
       this.orbitTarget.getWorldPosition(this.orbitTargetWorldPos);
       this.orbitControls.target.copy(this.orbitTargetWorldPos);
     }
     this.orbitControls?.update();
-    if (this.perspectiveController) {
-      this.perspectiveController.update(delta);
-    }
-    this.composer.render(delta);
-  }
-  /**
-   * Dispose renderer, composer, controls, and detach from scene
-   */
-  destroy() {
-    try {
-      this.renderer.setAnimationLoop(null);
-    } catch {
-    }
-    try {
-      this.disableOrbitControls();
-    } catch {
-    }
-    try {
-      this.composer?.passes?.forEach((p) => p.dispose?.());
-      this.composer?.dispose?.();
-    } catch {
-    }
-    try {
-      this.renderer.dispose();
-    } catch {
-    }
-    this.detachDebugDelegate();
-    this.sceneRef = null;
   }
   /**
    * Attach a delegate to react to debug state changes.
@@ -1271,135 +1606,48 @@ var ZylemCamera = class {
     };
   }
   /**
-   * Resize camera and renderer
+   * Clean up resources.
    */
-  resize(width, height) {
-    this.screenResolution.set(width, height);
-    this.renderer.setSize(width, height, false);
-    this.composer.setSize(width, height);
-    if (this.camera instanceof PerspectiveCamera) {
-      this.camera.aspect = width / height;
-      this.camera.updateProjectionMatrix();
-    }
-    if (this.perspectiveController) {
-      this.perspectiveController.resize(width, height);
-    }
-  }
-  /**
-   * Update renderer pixel ratio (DPR)
-   */
-  setPixelRatio(dpr) {
-    const safe = Math.max(1, Number.isFinite(dpr) ? dpr : 1);
-    this.renderer.setPixelRatio(safe);
-  }
-  /**
-   * Create camera based on perspective type
-   */
-  createCameraForPerspective(aspectRatio) {
-    switch (this._perspective) {
-      case Perspectives.ThirdPerson:
-        return this.createThirdPersonCamera(aspectRatio);
-      case Perspectives.FirstPerson:
-        return this.createFirstPersonCamera(aspectRatio);
-      case Perspectives.Isometric:
-        return this.createIsometricCamera(aspectRatio);
-      case Perspectives.Flat2D:
-        return this.createFlat2DCamera(aspectRatio);
-      case Perspectives.Fixed2D:
-        return this.createFixed2DCamera(aspectRatio);
-      default:
-        return this.createThirdPersonCamera(aspectRatio);
-    }
-  }
-  /**
-   * Initialize perspective-specific controller
-   */
-  initializePerspectiveController() {
-    switch (this._perspective) {
-      case Perspectives.ThirdPerson:
-        this.perspectiveController = new ThirdPersonCamera();
-        break;
-      case Perspectives.Fixed2D:
-        this.perspectiveController = new Fixed2DCamera();
-        break;
-      default:
-        this.perspectiveController = new ThirdPersonCamera();
-    }
-  }
-  createThirdPersonCamera(aspectRatio) {
-    return new PerspectiveCamera(75, aspectRatio, 0.1, 1e3);
-  }
-  createFirstPersonCamera(aspectRatio) {
-    return new PerspectiveCamera(75, aspectRatio, 0.1, 1e3);
-  }
-  createIsometricCamera(aspectRatio) {
-    return new OrthographicCamera(
-      this.frustumSize * aspectRatio / -2,
-      this.frustumSize * aspectRatio / 2,
-      this.frustumSize / 2,
-      this.frustumSize / -2,
-      1,
-      1e3
-    );
-  }
-  createFlat2DCamera(aspectRatio) {
-    return new OrthographicCamera(
-      this.frustumSize * aspectRatio / -2,
-      this.frustumSize * aspectRatio / 2,
-      this.frustumSize / 2,
-      this.frustumSize / -2,
-      1,
-      1e3
-    );
-  }
-  createFixed2DCamera(aspectRatio) {
-    return this.createFlat2DCamera(aspectRatio);
-  }
-  // Movement methods
-  moveCamera(position2) {
-    if (this._perspective === Perspectives.Flat2D || this._perspective === Perspectives.Fixed2D) {
-      this.frustumSize = position2.z;
-    }
-    this.cameraRig.position.set(position2.x, position2.y, position2.z);
-  }
-  move(position2) {
-    this.moveCamera(position2);
-  }
-  rotate(pitch, yaw, roll) {
-    this.cameraRig.rotateX(pitch);
-    this.cameraRig.rotateY(yaw);
-    this.cameraRig.rotateZ(roll);
+  dispose() {
+    this.disableOrbitControls();
+    this.detachDebugDelegate();
   }
   /**
-   * Get the DOM element for the renderer
+   * Get the current debug state snapshot.
    */
-  getDomElement() {
-    return this.renderer.domElement;
+  get debugState() {
+    return this.debugStateSnapshot;
   }
   applyDebugState(state2) {
+    const wasEnabled = this.debugStateSnapshot.enabled;
     this.debugStateSnapshot = {
       enabled: state2.enabled,
       selected: [...state2.selected]
     };
-    if (state2.enabled) {
+    if (state2.enabled && !wasEnabled) {
+      this.saveCameraState();
       this.enableOrbitControls();
       this.updateOrbitTargetFromSelection(state2.selected);
-    } else {
+    } else if (!state2.enabled && wasEnabled) {
       this.orbitTarget = null;
       this.disableOrbitControls();
+      this.restoreCameraState();
+    } else if (state2.enabled) {
+      this.updateOrbitTargetFromSelection(state2.selected);
     }
   }
   enableOrbitControls() {
     if (this.orbitControls) {
       return;
     }
-    this.orbitControls = new OrbitControls(this.camera, this.renderer.domElement);
+    this.orbitControls = new OrbitControls(this.camera, this.domElement);
     this.orbitControls.enableDamping = true;
     this.orbitControls.dampingFactor = 0.05;
     this.orbitControls.screenSpacePanning = false;
     this.orbitControls.minDistance = 1;
     this.orbitControls.maxDistance = 500;
     this.orbitControls.maxPolarAngle = Math.PI / 2;
+    this.orbitControls.target.set(0, 0, 0);
   }
   disableOrbitControls() {
     if (!this.orbitControls) {
@@ -1411,6 +1659,9 @@ var ZylemCamera = class {
   updateOrbitTargetFromSelection(selected) {
     if (!this.debugDelegate || selected.length === 0) {
       this.orbitTarget = null;
+      if (this.orbitControls) {
+        this.orbitControls.target.set(0, 0, 0);
+      }
       return;
     }
     for (let i = selected.length - 1; i >= 0; i -= 1) {
@@ -1437,259 +1688,453 @@ var ZylemCamera = class {
     this.debugUnsubscribe = null;
     this.debugDelegate = null;
   }
-};
-
-// src/lib/camera/camera.ts
-var CameraWrapper = class {
-  cameraRef;
-  constructor(camera) {
-    this.cameraRef = camera;
+  /**
+   * Save camera position, rotation, and zoom before entering debug mode.
+   */
+  saveCameraState() {
+    this.savedCameraPosition = this.camera.position.clone();
+    this.savedCameraQuaternion = this.camera.quaternion.clone();
+    if ("zoom" in this.camera) {
+      this.savedCameraZoom = this.camera.zoom;
+    }
+  }
+  /**
+   * Restore camera position, rotation, and zoom when exiting debug mode.
+   */
+  restoreCameraState() {
+    if (this.savedCameraPosition) {
+      this.camera.position.copy(this.savedCameraPosition);
+      this.savedCameraPosition = null;
+    }
+    if (this.savedCameraQuaternion) {
+      this.camera.quaternion.copy(this.savedCameraQuaternion);
+      this.savedCameraQuaternion = null;
+    }
+    if (this.savedCameraZoom !== null && "zoom" in this.camera) {
+      this.camera.zoom = this.savedCameraZoom;
+      this.camera.updateProjectionMatrix?.();
+      this.savedCameraZoom = null;
+    }
   }
 };
 
-// src/lib/stage/stage-debug-delegate.ts
-import { Ray } from "@dimforge/rapier3d-compat";
-import { BufferAttribute, BufferGeometry as BufferGeometry2, LineBasicMaterial as LineBasicMaterial2, LineSegments as LineSegments2, Raycaster, Vector2 as Vector24 } from "three";
-
-// src/lib/stage/debug-entity-cursor.ts
-import {
-  Box3,
-  BoxGeometry,
-  Color as Color5,
-  EdgesGeometry,
-  Group as Group3,
-  LineBasicMaterial,
-  LineSegments,
-  Mesh as Mesh2,
-  MeshBasicMaterial,
-  Vector3 as Vector38
-} from "three";
-var DebugEntityCursor = class {
-  scene;
-  container;
-  fillMesh;
-  edgeLines;
-  currentColor = new Color5(65280);
-  bbox = new Box3();
-  size = new Vector38();
-  center = new Vector38();
-  constructor(scene) {
-    this.scene = scene;
-    const initialGeometry = new BoxGeometry(1, 1, 1);
-    this.fillMesh = new Mesh2(
-      initialGeometry,
-      new MeshBasicMaterial({
-        color: this.currentColor,
-        transparent: true,
-        opacity: 0.12,
-        depthWrite: false
-      })
-    );
-    const edges = new EdgesGeometry(initialGeometry);
-    this.edgeLines = new LineSegments(
-      edges,
-      new LineBasicMaterial({ color: this.currentColor, linewidth: 1 })
-    );
-    this.container = new Group3();
-    this.container.name = "DebugEntityCursor";
-    this.container.add(this.fillMesh);
-    this.container.add(this.edgeLines);
-    this.container.visible = false;
-    this.scene.add(this.container);
-  }
-  setColor(color) {
-    this.currentColor.set(color);
-    this.fillMesh.material.color.set(this.currentColor);
-    this.edgeLines.material.color.set(this.currentColor);
+// src/lib/camera/zylem-camera.ts
+var ZylemCamera = class {
+  cameraRig = null;
+  camera;
+  screenResolution;
+  renderer;
+  composer;
+  _perspective;
+  target = null;
+  sceneRef = null;
+  frustumSize = 10;
+  // Perspective controller delegation
+  perspectiveController = null;
+  // Debug/orbit controls delegation
+  orbitController = null;
+  constructor(perspective, screenResolution, frustumSize = 10) {
+    this._perspective = perspective;
+    this.screenResolution = screenResolution;
+    this.frustumSize = frustumSize;
+    this.renderer = new WebGLRenderer3({ antialias: false, alpha: true });
+    this.renderer.setSize(screenResolution.x, screenResolution.y);
+    this.renderer.shadowMap.enabled = true;
+    this.composer = new EffectComposer(this.renderer);
+    const aspectRatio = screenResolution.x / screenResolution.y;
+    this.camera = this.createCameraForPerspective(aspectRatio);
+    if (this.needsRig()) {
+      this.cameraRig = new Object3D6();
+      this.cameraRig.position.set(0, 3, 10);
+      this.cameraRig.add(this.camera);
+      this.camera.lookAt(new Vector39(0, 2, 0));
+    } else {
+      this.camera.position.set(0, 0, 10);
+      this.camera.lookAt(new Vector39(0, 0, 0));
+    }
+    this.initializePerspectiveController();
+    this.orbitController = new CameraOrbitController(this.camera, this.renderer.domElement);
   }
   /**
-   * Update the cursor to enclose the provided Object3D using a world-space AABB.
+   * Setup the camera with a scene
    */
-  updateFromObject(object) {
-    if (!object) {
-      this.hide();
-      return;
-    }
-    this.bbox.setFromObject(object);
-    if (!isFinite(this.bbox.min.x) || !isFinite(this.bbox.max.x)) {
-      this.hide();
-      return;
+  async setup(scene) {
+    this.sceneRef = scene;
+    let renderResolution = this.screenResolution.clone().divideScalar(2);
+    renderResolution.x |= 0;
+    renderResolution.y |= 0;
+    const pass = new RenderPass(renderResolution, scene, this.camera);
+    this.composer.addPass(pass);
+    if (this.perspectiveController) {
+      this.perspectiveController.setup({
+        screenResolution: this.screenResolution,
+        renderer: this.renderer,
+        scene,
+        camera: this
+      });
     }
-    this.bbox.getSize(this.size);
-    this.bbox.getCenter(this.center);
-    const newGeom = new BoxGeometry(
-      Math.max(this.size.x, 1e-6),
-      Math.max(this.size.y, 1e-6),
-      Math.max(this.size.z, 1e-6)
-    );
-    this.fillMesh.geometry.dispose();
-    this.fillMesh.geometry = newGeom;
-    const newEdges = new EdgesGeometry(newGeom);
-    this.edgeLines.geometry.dispose();
-    this.edgeLines.geometry = newEdges;
-    this.container.position.copy(this.center);
-    this.container.visible = true;
+    this.renderer.setAnimationLoop((delta) => {
+      this.update(delta || 0);
+    });
   }
-  hide() {
-    this.container.visible = false;
+  /**
+   * Update camera and render
+   */
+  update(delta) {
+    this.orbitController?.update();
+    if (this.perspectiveController && !this.isDebugModeActive()) {
+      this.perspectiveController.update(delta);
+    }
+    this.composer.render(delta);
   }
-  dispose() {
-    this.scene.remove(this.container);
-    this.fillMesh.geometry.dispose();
-    this.fillMesh.material.dispose();
-    this.edgeLines.geometry.dispose();
-    this.edgeLines.material.dispose();
+  /**
+   * Check if debug mode is active (orbit controls taking over camera)
+   */
+  isDebugModeActive() {
+    return this.orbitController?.isActive ?? false;
   }
-};
-
-// src/lib/stage/stage-debug-delegate.ts
-var SELECT_TOOL_COLOR = 2293538;
-var DELETE_TOOL_COLOR = 16724787;
-var StageDebugDelegate = class {
-  stage;
-  options;
-  mouseNdc = new Vector24(-2, -2);
-  raycaster = new Raycaster();
-  isMouseDown = false;
-  disposeFns = [];
-  debugCursor = null;
-  debugLines = null;
-  constructor(stage, options) {
-    this.stage = stage;
-    this.options = {
-      maxRayDistance: options?.maxRayDistance ?? 5e3,
-      addEntityFactory: options?.addEntityFactory ?? null
-    };
-    if (this.stage.scene) {
-      this.debugLines = new LineSegments2(
-        new BufferGeometry2(),
-        new LineBasicMaterial2({ vertexColors: true })
-      );
-      this.stage.scene.scene.add(this.debugLines);
-      this.debugLines.visible = true;
-      this.debugCursor = new DebugEntityCursor(this.stage.scene.scene);
+  /**
+   * Dispose renderer, composer, controls, and detach from scene
+   */
+  destroy() {
+    try {
+      this.renderer.setAnimationLoop(null);
+    } catch {
     }
-    this.attachDomListeners();
-  }
-  update() {
-    if (!debugState.enabled) return;
-    if (!this.stage.scene || !this.stage.world || !this.stage.cameraRef) return;
-    const { world, cameraRef } = this.stage;
-    if (this.debugLines) {
-      const { vertices, colors } = world.world.debugRender();
-      this.debugLines.geometry.setAttribute("position", new BufferAttribute(vertices, 3));
-      this.debugLines.geometry.setAttribute("color", new BufferAttribute(colors, 4));
+    try {
+      this.orbitController?.dispose();
+    } catch {
     }
-    const tool = getDebugTool();
-    const isCursorTool = tool === "select" || tool === "delete";
-    this.raycaster.setFromCamera(this.mouseNdc, cameraRef.camera);
-    const origin = this.raycaster.ray.origin.clone();
-    const direction = this.raycaster.ray.direction.clone().normalize();
-    const rapierRay = new Ray(
-      { x: origin.x, y: origin.y, z: origin.z },
-      { x: direction.x, y: direction.y, z: direction.z }
-    );
-    const hit = world.world.castRay(rapierRay, this.options.maxRayDistance, true);
-    if (hit && isCursorTool) {
-      const rigidBody = hit.collider?._parent;
-      const hoveredUuid2 = rigidBody?.userData?.uuid;
-      if (hoveredUuid2) {
-        const entity = this.stage._debugMap.get(hoveredUuid2);
-        if (entity) setHoveredEntity(entity);
-      } else {
-        resetHoveredEntity();
-      }
-      if (this.isMouseDown) {
-        this.handleActionOnHit(hoveredUuid2 ?? null, origin, direction, hit.toi);
-      }
+    try {
+      this.composer?.passes?.forEach((p) => p.dispose?.());
+      this.composer?.dispose?.();
+    } catch {
     }
-    this.isMouseDown = false;
-    const hoveredUuid = getHoveredEntity();
-    if (!hoveredUuid) {
-      this.debugCursor?.hide();
-      return;
+    try {
+      this.renderer.dispose();
+    } catch {
     }
-    const hoveredEntity = this.stage._debugMap.get(`${hoveredUuid}`);
-    const targetObject = hoveredEntity?.group ?? hoveredEntity?.mesh ?? null;
-    if (!targetObject) {
-      this.debugCursor?.hide();
-      return;
+    this.sceneRef = null;
+  }
+  /**
+   * Attach a delegate to react to debug state changes.
+   */
+  setDebugDelegate(delegate) {
+    this.orbitController?.setDebugDelegate(delegate);
+  }
+  /**
+   * Resize camera and renderer
+   */
+  resize(width, height) {
+    this.screenResolution.set(width, height);
+    this.renderer.setSize(width, height, false);
+    this.composer.setSize(width, height);
+    if (this.camera instanceof PerspectiveCamera) {
+      this.camera.aspect = width / height;
+      this.camera.updateProjectionMatrix();
     }
-    switch (tool) {
-      case "select":
-        this.debugCursor?.setColor(SELECT_TOOL_COLOR);
-        break;
-      case "delete":
-        this.debugCursor?.setColor(DELETE_TOOL_COLOR);
+    if (this.perspectiveController) {
+      this.perspectiveController.resize(width, height);
+    }
+  }
+  /**
+   * Update renderer pixel ratio (DPR)
+   */
+  setPixelRatio(dpr) {
+    const safe = Math.max(1, Number.isFinite(dpr) ? dpr : 1);
+    this.renderer.setPixelRatio(safe);
+  }
+  /**
+   * Create camera based on perspective type
+   */
+  createCameraForPerspective(aspectRatio) {
+    switch (this._perspective) {
+      case Perspectives.ThirdPerson:
+        return this.createThirdPersonCamera(aspectRatio);
+      case Perspectives.FirstPerson:
+        return this.createFirstPersonCamera(aspectRatio);
+      case Perspectives.Isometric:
+        return this.createIsometricCamera(aspectRatio);
+      case Perspectives.Flat2D:
+        return this.createFlat2DCamera(aspectRatio);
+      case Perspectives.Fixed2D:
+        return this.createFixed2DCamera(aspectRatio);
+      default:
+        return this.createThirdPersonCamera(aspectRatio);
+    }
+  }
+  /**
+   * Initialize perspective-specific controller
+   */
+  initializePerspectiveController() {
+    switch (this._perspective) {
+      case Perspectives.ThirdPerson:
+        this.perspectiveController = new ThirdPersonCamera();
         break;
-      default:
-        this.debugCursor?.setColor(16777215);
+      case Perspectives.Fixed2D:
+        this.perspectiveController = new Fixed2DCamera();
         break;
+      default:
+        this.perspectiveController = new ThirdPersonCamera();
     }
-    this.debugCursor?.updateFromObject(targetObject);
   }
-  dispose() {
-    this.disposeFns.forEach((fn) => fn());
-    this.disposeFns = [];
-    this.debugCursor?.dispose();
-    if (this.debugLines && this.stage.scene) {
-      this.stage.scene.scene.remove(this.debugLines);
-      this.debugLines.geometry.dispose();
-      this.debugLines.material.dispose();
-      this.debugLines = null;
+  createThirdPersonCamera(aspectRatio) {
+    return new PerspectiveCamera(75, aspectRatio, 0.1, 1e3);
+  }
+  createFirstPersonCamera(aspectRatio) {
+    return new PerspectiveCamera(75, aspectRatio, 0.1, 1e3);
+  }
+  createIsometricCamera(aspectRatio) {
+    return new OrthographicCamera(
+      this.frustumSize * aspectRatio / -2,
+      this.frustumSize * aspectRatio / 2,
+      this.frustumSize / 2,
+      this.frustumSize / -2,
+      1,
+      1e3
+    );
+  }
+  createFlat2DCamera(aspectRatio) {
+    return new OrthographicCamera(
+      this.frustumSize * aspectRatio / -2,
+      this.frustumSize * aspectRatio / 2,
+      this.frustumSize / 2,
+      this.frustumSize / -2,
+      1,
+      1e3
+    );
+  }
+  createFixed2DCamera(aspectRatio) {
+    return this.createFlat2DCamera(aspectRatio);
+  }
+  // Movement methods
+  moveCamera(position2) {
+    if (this._perspective === Perspectives.Flat2D || this._perspective === Perspectives.Fixed2D) {
+      this.frustumSize = position2.z;
+    }
+    if (this.cameraRig) {
+      this.cameraRig.position.set(position2.x, position2.y, position2.z);
+    } else {
+      this.camera.position.set(position2.x, position2.y, position2.z);
     }
   }
-  handleActionOnHit(hoveredUuid, origin, direction, toi) {
-    const tool = getDebugTool();
-    switch (tool) {
-      case "select": {
-        if (hoveredUuid) {
-          const entity = this.stage._debugMap.get(hoveredUuid);
-          if (entity) setSelectedEntity(entity);
-        }
-        break;
-      }
-      case "delete": {
-        if (hoveredUuid) {
-          this.stage.removeEntityByUuid(hoveredUuid);
-        }
-        break;
-      }
-      case "scale": {
-        if (!this.options.addEntityFactory) break;
-        const hitPosition = origin.clone().add(direction.clone().multiplyScalar(toi));
-        const newNode = this.options.addEntityFactory({ position: hitPosition });
-        if (newNode) {
-          Promise.resolve(newNode).then((node) => {
-            if (node) this.stage.spawnEntity(node);
-          }).catch(() => {
-          });
-        }
-        break;
-      }
-      default:
-        break;
+  move(position2) {
+    this.moveCamera(position2);
+  }
+  rotate(pitch, yaw, roll) {
+    if (this.cameraRig) {
+      this.cameraRig.rotateX(pitch);
+      this.cameraRig.rotateY(yaw);
+      this.cameraRig.rotateZ(roll);
+    } else {
+      this.camera.rotateX(pitch);
+      this.camera.rotateY(yaw);
+      this.camera.rotateZ(roll);
     }
   }
-  attachDomListeners() {
-    const canvas = this.stage.cameraRef?.renderer.domElement ?? this.stage.scene?.zylemCamera.renderer.domElement;
-    if (!canvas) return;
-    const onMouseMove = (e) => {
-      const rect = canvas.getBoundingClientRect();
-      const x = (e.clientX - rect.left) / rect.width * 2 - 1;
-      const y = -((e.clientY - rect.top) / rect.height * 2 - 1);
-      this.mouseNdc.set(x, y);
+  /**
+   * Check if this perspective type needs a camera rig
+   */
+  needsRig() {
+    return this._perspective === Perspectives.ThirdPerson;
+  }
+  /**
+   * Get the DOM element for the renderer
+   */
+  getDomElement() {
+    return this.renderer.domElement;
+  }
+};
+
+// src/lib/stage/stage-camera-delegate.ts
+var StageCameraDelegate = class {
+  stage;
+  constructor(stage) {
+    this.stage = stage;
+  }
+  /**
+   * Create a default third-person camera based on window size.
+   */
+  createDefaultCamera() {
+    const width = window.innerWidth;
+    const height = window.innerHeight;
+    const screenResolution = new Vector24(width, height);
+    return new ZylemCamera(Perspectives.ThirdPerson, screenResolution);
+  }
+  /**
+   * Resolve the camera to use for the stage.
+   * Uses the provided camera, stage camera wrapper, or creates a default.
+   * 
+   * @param cameraOverride Optional camera override
+   * @param cameraWrapper Optional camera wrapper from stage options
+   * @returns The resolved ZylemCamera instance
+   */
+  resolveCamera(cameraOverride, cameraWrapper) {
+    if (cameraOverride) {
+      return cameraOverride;
+    }
+    if (cameraWrapper) {
+      return cameraWrapper.cameraRef;
+    }
+    return this.createDefaultCamera();
+  }
+};
+
+// src/lib/stage/stage-loading-delegate.ts
+var StageLoadingDelegate = class {
+  loadingHandlers = [];
+  stageName;
+  stageIndex;
+  /**
+   * Set stage context for event bus emissions.
+   */
+  setStageContext(stageName, stageIndex) {
+    this.stageName = stageName;
+    this.stageIndex = stageIndex;
+  }
+  /**
+   * Subscribe to loading events.
+   * 
+   * @param callback Invoked for each loading event (start, progress, complete)
+   * @returns Unsubscribe function
+   */
+  onLoading(callback) {
+    this.loadingHandlers.push(callback);
+    return () => {
+      this.loadingHandlers = this.loadingHandlers.filter((h) => h !== callback);
     };
-    const onMouseDown = (e) => {
-      this.isMouseDown = true;
+  }
+  /**
+   * Emit a loading event to all subscribers and to the game event bus.
+   * 
+   * @param event The loading event to broadcast
+   */
+  emit(event) {
+    for (const handler of this.loadingHandlers) {
+      try {
+        handler(event);
+      } catch (e) {
+        console.error("Loading handler failed", e);
+      }
+    }
+    const payload = {
+      ...event,
+      stageName: this.stageName,
+      stageIndex: this.stageIndex
     };
-    canvas.addEventListener("mousemove", onMouseMove);
-    canvas.addEventListener("mousedown", onMouseDown);
-    this.disposeFns.push(() => canvas.removeEventListener("mousemove", onMouseMove));
-    this.disposeFns.push(() => canvas.removeEventListener("mousedown", onMouseDown));
+    if (event.type === "start") {
+      gameEventBus.emit("stage:loading:start", payload);
+    } else if (event.type === "progress") {
+      gameEventBus.emit("stage:loading:progress", payload);
+    } else if (event.type === "complete") {
+      gameEventBus.emit("stage:loading:complete", payload);
+    }
+  }
+  /**
+   * Emit a start loading event.
+   */
+  emitStart(message = "Loading stage...") {
+    this.emit({ type: "start", message, progress: 0 });
+  }
+  /**
+   * Emit a progress loading event.
+   */
+  emitProgress(message, current, total) {
+    const progress = total > 0 ? current / total : 0;
+    this.emit({ type: "progress", message, progress, current, total });
+  }
+  /**
+   * Emit a complete loading event.
+   */
+  emitComplete(message = "Stage loaded") {
+    this.emit({ type: "complete", message, progress: 1 });
+  }
+  /**
+   * Clear all loading handlers.
+   */
+  dispose() {
+    this.loadingHandlers = [];
   }
 };
 
+// src/lib/stage/stage-config.ts
+import { Vector3 as Vector310 } from "three";
+
+// src/lib/core/utility/options-parser.ts
+function isBaseNode(item) {
+  return !!item && typeof item === "object" && typeof item.create === "function";
+}
+function isThenable(item) {
+  return !!item && typeof item.then === "function";
+}
+function isCameraWrapper(item) {
+  return !!item && typeof item === "object" && item.constructor?.name === "CameraWrapper";
+}
+function isConfigObject(item) {
+  if (!item || typeof item !== "object") return false;
+  if (isBaseNode(item)) return false;
+  if (isCameraWrapper(item)) return false;
+  if (isThenable(item)) return false;
+  if (typeof item.then === "function") return false;
+  return item.constructor === Object || item.constructor?.name === "Object";
+}
+function isEntityInput(item) {
+  if (!item) return false;
+  if (isBaseNode(item)) return true;
+  if (typeof item === "function") return true;
+  if (isThenable(item)) return true;
+  return false;
+}
+
+// src/lib/stage/stage-config.ts
+var StageConfig = class {
+  constructor(inputs, backgroundColor, backgroundImage, gravity, variables) {
+    this.inputs = inputs;
+    this.backgroundColor = backgroundColor;
+    this.backgroundImage = backgroundImage;
+    this.gravity = gravity;
+    this.variables = variables;
+  }
+};
+function createDefaultStageConfig() {
+  return new StageConfig(
+    {
+      p1: ["gamepad-1", "keyboard-1"],
+      p2: ["gamepad-2", "keyboard-2"]
+    },
+    ZylemBlueColor,
+    null,
+    new Vector310(0, 0, 0),
+    {}
+  );
+}
+function parseStageOptions(options = []) {
+  const defaults = createDefaultStageConfig();
+  let config = {};
+  const entities = [];
+  const asyncEntities = [];
+  let camera;
+  for (const item of options) {
+    if (isCameraWrapper(item)) {
+      camera = item;
+    } else if (isBaseNode(item)) {
+      entities.push(item);
+    } else if (isEntityInput(item) && !isBaseNode(item)) {
+      asyncEntities.push(item);
+    } else if (isConfigObject(item)) {
+      config = { ...config, ...item };
+    }
+  }
+  const resolvedConfig = new StageConfig(
+    config.inputs ?? defaults.inputs,
+    config.backgroundColor ?? defaults.backgroundColor,
+    config.backgroundImage ?? defaults.backgroundImage,
+    config.gravity ?? defaults.gravity,
+    config.variables ?? defaults.variables
+  );
+  return { config: resolvedConfig, entities, asyncEntities, camera };
+}
+
 // src/lib/stage/zylem-stage.ts
 var STAGE_TYPE = "Stage";
 var ZylemStage = class extends LifeCycleBase {
@@ -1701,7 +2146,7 @@ var ZylemStage = class extends LifeCycleBase {
       p1: ["gamepad-1", "keyboard"],
       p2: ["gamepad-2", "keyboard"]
     },
-    gravity: new Vector310(0, 0, 0),
+    gravity: new Vector311(0, 0, 0),
     variables: {},
     entities: []
   };
@@ -1716,16 +2161,19 @@ var ZylemStage = class extends LifeCycleBase {
   isLoaded = false;
   _debugMap = /* @__PURE__ */ new Map();
   entityAddedHandlers = [];
-  loadingHandlers = [];
   ecs = createECS();
   testSystem = null;
   transformSystem = null;
   debugDelegate = null;
   cameraDebugDelegate = null;
+  debugStateUnsubscribe = null;
   uuid;
   wrapperRef = null;
   camera;
   cameraRef = null;
+  // Delegates
+  cameraDelegate;
+  loadingDelegate;
   /**
    * Create a new stage.
    * @param options Stage options: partial config, camera, and initial entities or factories
@@ -1735,49 +2183,22 @@ var ZylemStage = class extends LifeCycleBase {
     this.world = null;
     this.scene = null;
     this.uuid = nanoid2();
-    const { config, entities, asyncEntities, camera } = this.parseOptions(options);
-    this.camera = camera;
-    this.children = entities;
-    this.pendingEntities = asyncEntities;
-    this.saveState({ ...this.state, ...config, entities: [] });
-    this.gravity = config.gravity ?? new Vector310(0, 0, 0);
-  }
-  parseOptions(options) {
-    let config = {};
-    const entities = [];
-    const asyncEntities = [];
-    let camera;
-    for (const item of options) {
-      if (this.isCameraWrapper(item)) {
-        camera = item;
-      } else if (this.isBaseNode(item)) {
-        entities.push(item);
-      } else if (this.isEntityInput(item)) {
-        asyncEntities.push(item);
-      } else if (this.isZylemStageConfig(item)) {
-        config = { ...config, ...item };
-      }
-    }
-    return { config, entities, asyncEntities, camera };
-  }
-  isZylemStageConfig(item) {
-    return item && typeof item === "object" && !(item instanceof BaseNode) && !(item instanceof CameraWrapper);
-  }
-  isBaseNode(item) {
-    return item && typeof item === "object" && typeof item.create === "function";
-  }
-  isCameraWrapper(item) {
-    return item && typeof item === "object" && item.constructor.name === "CameraWrapper";
-  }
-  isEntityInput(item) {
-    if (!item) return false;
-    if (this.isBaseNode(item)) return true;
-    if (typeof item === "function") return true;
-    if (typeof item === "object" && typeof item.then === "function") return true;
-    return false;
-  }
-  isThenable(value) {
-    return !!value && typeof value.then === "function";
+    this.cameraDelegate = new StageCameraDelegate(this);
+    this.loadingDelegate = new StageLoadingDelegate();
+    const parsed = parseStageOptions(options);
+    this.camera = parsed.camera;
+    this.children = parsed.entities;
+    this.pendingEntities = parsed.asyncEntities;
+    this.saveState({
+      ...this.state,
+      inputs: parsed.config.inputs,
+      backgroundColor: parsed.config.backgroundColor,
+      backgroundImage: parsed.config.backgroundImage,
+      gravity: parsed.config.gravity,
+      variables: parsed.config.variables,
+      entities: []
+    });
+    this.gravity = parsed.config.gravity ?? new Vector311(0, 0, 0);
   }
   handleEntityImmediatelyOrQueue(entity) {
     if (this.isLoaded) {
@@ -1798,42 +2219,47 @@ var ZylemStage = class extends LifeCycleBase {
   }
   setState() {
     const { backgroundColor, backgroundImage } = this.state;
-    const color = backgroundColor instanceof Color6 ? backgroundColor : new Color6(backgroundColor);
+    const color = backgroundColor instanceof Color7 ? backgroundColor : new Color7(backgroundColor);
     setStageBackgroundColor(color);
     setStageBackgroundImage(backgroundImage);
     setStageVariables(this.state.variables ?? {});
   }
   /**
    * Load and initialize the stage's scene and world.
+   * Uses generator pattern to yield control to event loop for real-time progress.
    * @param id DOM element id for the renderer container
    * @param camera Optional camera override
    */
   async load(id, camera) {
     this.setState();
-    const zylemCamera = camera || (this.camera ? this.camera.cameraRef : this.createDefaultCamera());
+    const zylemCamera = this.cameraDelegate.resolveCamera(camera, this.camera);
     this.cameraRef = zylemCamera;
     this.scene = new ZylemScene(id, zylemCamera, this.state);
-    const physicsWorld = await ZylemWorld.loadPhysics(this.gravity ?? new Vector310(0, 0, 0));
+    const physicsWorld = await ZylemWorld.loadPhysics(this.gravity ?? new Vector311(0, 0, 0));
     this.world = new ZylemWorld(physicsWorld);
     this.scene.setup();
-    this.emitLoading({ type: "start", message: "Loading stage...", progress: 0 });
+    this.loadingDelegate.emitStart();
+    await this.runEntityLoadGenerator();
+    this.transformSystem = createTransformSystem(this);
+    this.isLoaded = true;
+    this.loadingDelegate.emitComplete();
+  }
+  /**
+   * Generator that yields between entity loads for real-time progress updates.
+   */
+  *entityLoadGenerator() {
     const total = this.children.length + this.pendingEntities.length + this.pendingPromises.length;
     let current = 0;
-    for (let child of this.children) {
+    for (const child of this.children) {
       this.spawnEntity(child);
       current++;
-      this.emitLoading({
-        type: "progress",
-        message: `Loaded entity ${child.name || "unknown"}`,
-        progress: current / total,
-        current,
-        total
-      });
+      yield { current, total, name: child.name || "unknown" };
     }
     if (this.pendingEntities.length) {
       this.enqueue(...this.pendingEntities);
       current += this.pendingEntities.length;
       this.pendingEntities = [];
+      yield { current, total, name: "pending entities" };
     }
     if (this.pendingPromises.length) {
       for (const promise of this.pendingPromises) {
@@ -1843,24 +2269,44 @@ var ZylemStage = class extends LifeCycleBase {
       }
       current += this.pendingPromises.length;
       this.pendingPromises = [];
+      yield { current, total, name: "async entities" };
     }
-    this.transformSystem = createTransformSystem(this);
-    this.isLoaded = true;
-    this.emitLoading({ type: "complete", message: "Stage loaded", progress: 1 });
   }
-  createDefaultCamera() {
-    const width = window.innerWidth;
-    const height = window.innerHeight;
-    const screenResolution = new Vector25(width, height);
-    return new ZylemCamera(Perspectives.ThirdPerson, screenResolution);
+  /**
+   * Runs the entity load generator, yielding to the event loop between loads.
+   * This allows the browser to process events and update the UI in real-time.
+   */
+  async runEntityLoadGenerator() {
+    const gen = this.entityLoadGenerator();
+    for (const progress of gen) {
+      this.loadingDelegate.emitProgress(`Loaded ${progress.name}`, progress.current, progress.total);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
   }
   _setup(params) {
     if (!this.scene || !this.world) {
       this.logMissingEntities();
       return;
     }
-    if (debugState.enabled) {
+    this.updateDebugDelegate();
+    this.debugStateUnsubscribe = subscribe4(debugState, () => {
+      this.updateDebugDelegate();
+    });
+  }
+  updateDebugDelegate() {
+    if (debugState.enabled && !this.debugDelegate && this.scene && this.world) {
       this.debugDelegate = new StageDebugDelegate(this);
+      if (this.cameraRef && !this.cameraDebugDelegate) {
+        this.cameraDebugDelegate = new StageCameraDebugDelegate(this);
+        this.cameraRef.setDebugDelegate(this.cameraDebugDelegate);
+      }
+    } else if (!debugState.enabled && this.debugDelegate) {
+      this.debugDelegate.dispose();
+      this.debugDelegate = null;
+      if (this.cameraRef) {
+        this.cameraRef.setDebugDelegate(null);
+      }
+      this.cameraDebugDelegate = null;
     }
   }
   _update(params) {
@@ -1870,7 +2316,7 @@ var ZylemStage = class extends LifeCycleBase {
       return;
     }
     this.world.update(params);
-    this.transformSystem(this.ecs);
+    this.transformSystem?.system(this.ecs);
     this._childrenMap.forEach((child, eid) => {
       child.nodeUpdate({
         ...params,
@@ -1904,13 +2350,20 @@ var ZylemStage = class extends LifeCycleBase {
     this._debugMap.clear();
     this.world?.destroy();
     this.scene?.destroy();
+    if (this.debugStateUnsubscribe) {
+      this.debugStateUnsubscribe();
+      this.debugStateUnsubscribe = null;
+    }
     this.debugDelegate?.dispose();
+    this.debugDelegate = null;
     this.cameraRef?.setDebugDelegate(null);
     this.cameraDebugDelegate = null;
     this.isLoaded = false;
     this.world = null;
     this.scene = null;
     this.cameraRef = null;
+    this.transformSystem?.destroy(this.ecs);
+    this.transformSystem = null;
     resetStageVariables();
     clearVariables(this);
   }
@@ -1991,13 +2444,7 @@ var ZylemStage = class extends LifeCycleBase {
     };
   }
   onLoading(callback) {
-    this.loadingHandlers.push(callback);
-    return () => {
-      this.loadingHandlers = this.loadingHandlers.filter((h) => h !== callback);
-    };
-  }
-  emitLoading(event) {
-    this.loadingHandlers.forEach((h) => h(event));
+    return this.loadingDelegate.onLoading(callback);
   }
   /**
    * Remove an entity and its resources by its UUID.
@@ -2054,16 +2501,16 @@ var ZylemStage = class extends LifeCycleBase {
   enqueue(...items) {
     for (const item of items) {
       if (!item) continue;
-      if (this.isBaseNode(item)) {
+      if (isBaseNode(item)) {
         this.handleEntityImmediatelyOrQueue(item);
         continue;
       }
       if (typeof item === "function") {
         try {
           const result = item();
-          if (this.isBaseNode(result)) {
+          if (isBaseNode(result)) {
             this.handleEntityImmediatelyOrQueue(result);
-          } else if (this.isThenable(result)) {
+          } else if (isThenable(result)) {
             this.handlePromiseWithSpawnOnResolve(result);
           }
         } catch (error) {
@@ -2071,16 +2518,25 @@ var ZylemStage = class extends LifeCycleBase {
         }
         continue;
       }
-      if (this.isThenable(item)) {
+      if (isThenable(item)) {
         this.handlePromiseWithSpawnOnResolve(item);
       }
     }
   }
 };
 
+// src/lib/camera/camera.ts
+import { Vector2 as Vector26, Vector3 as Vector312 } from "three";
+var CameraWrapper = class {
+  cameraRef;
+  constructor(camera) {
+    this.cameraRef = camera;
+  }
+};
+
 // src/lib/stage/stage-default.ts
 import { proxy as proxy4 } from "valtio/vanilla";
-import { Vector3 as Vector311 } from "three";
+import { Vector3 as Vector313 } from "three";
 var initialDefaults = {
   backgroundColor: ZylemBlueColor,
   backgroundImage: null,
@@ -2088,7 +2544,7 @@ var initialDefaults = {
     p1: ["gamepad-1", "keyboard"],
     p2: ["gamepad-2", "keyboard"]
   },
-  gravity: new Vector311(0, 0, 0),
+  gravity: new Vector313(0, 0, 0),
   variables: {}
 };
 var stageDefaultsState = proxy4({
@@ -2117,30 +2573,58 @@ function getStageDefaultConfig() {
 var Stage = class {
   wrappedStage;
   options = [];
-  // TODO: these shouldn't be here maybe more like nextFrame(stageInstance, () => {})
-  update = () => {
-  };
-  setup = () => {
-  };
-  destroy = () => {
-  };
+  // Entities added after construction, consumed on each load
+  _pendingEntities = [];
+  // Lifecycle callback arrays
+  setupCallbacks = [];
+  updateCallbacks = [];
+  destroyCallbacks = [];
+  pendingLoadingCallbacks = [];
   constructor(options) {
     this.options = options;
     this.wrappedStage = null;
   }
   async load(id, camera) {
     stageState.entities = [];
-    this.wrappedStage = new ZylemStage(this.options);
+    const loadOptions = [...this.options, ...this._pendingEntities];
+    this._pendingEntities = [];
+    this.wrappedStage = new ZylemStage(loadOptions);
     this.wrappedStage.wrapperRef = this;
+    this.pendingLoadingCallbacks.forEach((cb) => {
+      this.wrappedStage.onLoading(cb);
+    });
+    this.pendingLoadingCallbacks = [];
     const zylemCamera = camera instanceof CameraWrapper ? camera.cameraRef : camera;
     await this.wrappedStage.load(id, zylemCamera);
     this.wrappedStage.onEntityAdded((child) => {
       const next = this.wrappedStage.buildEntityState(child);
       stageState.entities = [...stageState.entities, next];
     }, { replayExisting: true });
+    this.applyLifecycleCallbacks();
+  }
+  applyLifecycleCallbacks() {
+    if (!this.wrappedStage) return;
+    if (this.setupCallbacks.length > 0) {
+      this.wrappedStage.setup = (params) => {
+        const extended = { ...params, stage: this };
+        this.setupCallbacks.forEach((cb) => cb(extended));
+      };
+    }
+    if (this.updateCallbacks.length > 0) {
+      this.wrappedStage.update = (params) => {
+        const extended = { ...params, stage: this };
+        this.updateCallbacks.forEach((cb) => cb(extended));
+      };
+    }
+    if (this.destroyCallbacks.length > 0) {
+      this.wrappedStage.destroy = (params) => {
+        const extended = { ...params, stage: this };
+        this.destroyCallbacks.forEach((cb) => cb(extended));
+      };
+    }
   }
   async addEntities(entities) {
-    this.options.push(...entities);
+    this._pendingEntities.push(...entities);
     if (!this.wrappedStage) {
       return;
     }
@@ -2165,28 +2649,57 @@ var Stage = class {
   start(params) {
     this.wrappedStage?.nodeSetup(params);
   }
+  // Fluent API for adding lifecycle callbacks
   onUpdate(...callbacks) {
-    if (!this.wrappedStage) {
-      return;
+    this.updateCallbacks.push(...callbacks);
+    if (this.wrappedStage) {
+      this.wrappedStage.update = (params) => {
+        const extended = { ...params, stage: this };
+        this.updateCallbacks.forEach((cb) => cb(extended));
+      };
     }
-    this.wrappedStage.update = (params) => {
-      const extended = { ...params, stage: this };
-      callbacks.forEach((cb) => cb(extended));
-    };
+    return this;
   }
-  onSetup(callback) {
-    this.wrappedStage.setup = callback;
+  onSetup(...callbacks) {
+    this.setupCallbacks.push(...callbacks);
+    if (this.wrappedStage) {
+      this.wrappedStage.setup = (params) => {
+        const extended = { ...params, stage: this };
+        this.setupCallbacks.forEach((cb) => cb(extended));
+      };
+    }
+    return this;
   }
-  onDestroy(callback) {
-    this.wrappedStage.destroy = callback;
+  onDestroy(...callbacks) {
+    this.destroyCallbacks.push(...callbacks);
+    if (this.wrappedStage) {
+      this.wrappedStage.destroy = (params) => {
+        const extended = { ...params, stage: this };
+        this.destroyCallbacks.forEach((cb) => cb(extended));
+      };
+    }
+    return this;
   }
   onLoading(callback) {
     if (!this.wrappedStage) {
+      this.pendingLoadingCallbacks.push(callback);
       return () => {
+        this.pendingLoadingCallbacks = this.pendingLoadingCallbacks.filter((c) => c !== callback);
       };
     }
     return this.wrappedStage.onLoading(callback);
   }
+  /**
+   * Find an entity by name on the current stage.
+   * @param name The name of the entity to find
+   * @param type Optional type symbol for type inference (e.g., TEXT_TYPE, SPRITE_TYPE)
+   * @returns The entity if found, or undefined
+   * @example stage.getEntityByName('scoreText', TEXT_TYPE)
+   */
+  getEntityByName(name, type) {
+    const entity = this.wrappedStage?.children.find((c) => c.name === name);
+    return entity;
+  }
 };
 function createStage(...options) {
   const _options = getStageOptions(options);
@@ -2194,7 +2707,7 @@ function createStage(...options) {
 }
 
 // src/lib/stage/entity-spawner.ts
-import { Euler, Quaternion as Quaternion2, Vector2 as Vector26 } from "three";
+import { Euler, Quaternion as Quaternion3, Vector2 as Vector27 } from "three";
 function entitySpawner(factory) {
   return {
     spawn: async (stage, x, y) => {
@@ -2202,7 +2715,7 @@ function entitySpawner(factory) {
       stage.add(instance);
       return instance;
     },
-    spawnRelative: async (source, stage, offset = new Vector26(0, 1)) => {
+    spawnRelative: async (source, stage, offset = new Vector27(0, 1)) => {
       if (!source.body) {
         console.warn("body missing for entity during spawnRelative");
         return void 0;
@@ -2211,7 +2724,7 @@ function entitySpawner(factory) {
       let rz = source._rotation2DAngle ?? 0;
       try {
         const r = source.body.rotation();
-        const q = new Quaternion2(r.x, r.y, r.z, r.w);
+        const q = new Quaternion3(r.x, r.y, r.z, r.w);
         const e = new Euler().setFromQuaternion(q, "XYZ");
         rz = e.z;
       } catch {
@@ -2224,8 +2737,31 @@ function entitySpawner(factory) {
     }
   };
 }
+
+// src/lib/stage/stage-events.ts
+import { subscribe as subscribe5 } from "valtio/vanilla";
+var STAGE_STATE_CHANGE = "STAGE_STATE_CHANGE";
+function initStageStateDispatcher() {
+  return subscribe5(stageState, () => {
+    const detail = {
+      entities: stageState.entities,
+      variables: stageState.variables
+    };
+    window.dispatchEvent(new CustomEvent(STAGE_STATE_CHANGE, { detail }));
+  });
+}
+function dispatchStageState() {
+  const detail = {
+    entities: stageState.entities,
+    variables: stageState.variables
+  };
+  window.dispatchEvent(new CustomEvent(STAGE_STATE_CHANGE, { detail }));
+}
 export {
+  STAGE_STATE_CHANGE,
   createStage,
-  entitySpawner
+  dispatchStageState,
+  entitySpawner,
+  initStageStateDispatcher
 };
 //# sourceMappingURL=stage.js.map