@yagejs/core 0.3.0 → 0.4.0

package/dist/index.js

@@ -231,14 +231,6 @@ var MathUtils = {
     const wrapped = MathUtils.wrap(t, 0, length * 2);
     return length - Math.abs(wrapped - length);
   },
-  /** Random float in [min, max). */
-  randomRange(min, max) {
-    return min + Math.random() * (max - min);
-  },
-  /** Random integer in [min, max] (inclusive). */
-  randomInt(min, max) {
-    return Math.floor(min + Math.random() * (max - min + 1));
-  },
   /** Convert degrees to radians. */
   degToRad(degrees) {
     return degrees * Math.PI / 180;
@@ -289,12 +281,138 @@ var MathUtils = {
   }
 };
 
+// src/EngineContext.ts
+var ServiceKey = class {
+  constructor(id, options) {
+    this.id = id;
+    this.scope = options?.scope ?? "engine";
+  }
+  id;
+  static {
+    __name(this, "ServiceKey");
+  }
+  /** Declared scope (engine or scene). Defaults to `"engine"`. */
+  scope;
+};
+var EngineContext = class {
+  static {
+    __name(this, "EngineContext");
+  }
+  services = /* @__PURE__ */ new Map();
+  /** Register a service. Throws if the key is already registered. */
+  register(key, service) {
+    if (this.services.has(key.id)) {
+      throw new Error(`Service "${key.id}" is already registered.`);
+    }
+    this.services.set(key.id, service);
+  }
+  /** Resolve a service. Throws if not registered. */
+  resolve(key) {
+    if (!this.services.has(key.id)) {
+      throw new Error(`Service "${key.id}" is not registered.`);
+    }
+    return this.services.get(key.id);
+  }
+  /** Resolve a service, returning undefined if not registered. */
+  tryResolve(key) {
+    return this.services.get(key.id);
+  }
+  /** Remove a registered service. No-op if not registered. */
+  unregister(key) {
+    this.services.delete(key.id);
+  }
+  /** Check if a service is registered. */
+  has(key) {
+    return this.services.has(key.id);
+  }
+};
+var EngineKey = new ServiceKey("engine");
+var EventBusKey = new ServiceKey("eventBus");
+var SceneManagerKey = new ServiceKey("sceneManager");
+var LoggerKey = new ServiceKey("logger");
+var InspectorKey = new ServiceKey("inspector");
+var QueryCacheKey = new ServiceKey("queryCache");
+var ErrorBoundaryKey = new ServiceKey("errorBoundary");
+var GameLoopKey = new ServiceKey("gameLoop");
+var SystemSchedulerKey = new ServiceKey(
+  "systemScheduler"
+);
+var ProcessSystemKey = new ServiceKey("processSystem");
+var AssetManagerKey = new ServiceKey("assetManager");
+
+// src/Random.ts
+var RandomKey = new ServiceKey("random", {
+  scope: "scene"
+});
+var UINT32_MAX = 4294967296;
+function normalizeSeed(seed) {
+  return seed >>> 0;
+}
+__name(normalizeSeed, "normalizeSeed");
+function createDefaultRandomSeed() {
+  return normalizeSeed(Date.now() ^ Math.floor(Math.random() * 1e9));
+}
+__name(createDefaultRandomSeed, "createDefaultRandomSeed");
+var Mulberry32Random = class {
+  static {
+    __name(this, "Mulberry32Random");
+  }
+  seed;
+  state;
+  constructor(seed) {
+    const normalized = normalizeSeed(seed);
+    this.seed = normalized;
+    this.state = normalized;
+  }
+  float() {
+    let t = this.state += 1831565813;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / UINT32_MAX;
+  }
+  range(min, max) {
+    return min + this.float() * (max - min);
+  }
+  int(min, max) {
+    return Math.floor(this.range(min, max + 1));
+  }
+  pick(arr) {
+    if (arr.length === 0) {
+      throw new Error("RandomService.pick() requires a non-empty array.");
+    }
+    return arr[this.int(0, arr.length - 1)];
+  }
+  shuffle(arr) {
+    for (let i = arr.length - 1; i > 0; i--) {
+      const j = this.int(0, i);
+      const tmp = arr[i];
+      arr[i] = arr[j];
+      arr[j] = tmp;
+    }
+    return arr;
+  }
+  setSeed(seed) {
+    const normalized = normalizeSeed(seed);
+    this.seed = normalized;
+    this.state = normalized;
+  }
+  getSeed() {
+    return this.seed;
+  }
+};
+function createRandomService(seed = createDefaultRandomSeed()) {
+  return new Mulberry32Random(seed);
+}
+__name(createRandomService, "createRandomService");
+var globalRandom = createRandomService();
+
 // src/EventBus.ts
 var EventBus = class {
   static {
     __name(this, "EventBus");
   }
   handlers = /* @__PURE__ */ new Map();
+  observers = /* @__PURE__ */ new Set();
   /** Subscribe to an event. Returns an unsubscribe function. */
   on(event, handler) {
     let list = this.handlers.get(event);
@@ -321,6 +439,12 @@ var EventBus = class {
   }
   /** Emit an event. Handlers are called synchronously in registration order. */
   emit(event, data) {
+    if (this.observers.size > 0) {
+      const observers = [...this.observers];
+      for (const observer of observers) {
+        observer(event, data);
+      }
+    }
     const list = this.handlers.get(event);
     if (!list) return;
     const snapshot = [...list];
@@ -328,6 +452,16 @@ var EventBus = class {
       handler(data);
     }
   }
+  /**
+   * Observe every emitted event without affecting handler order or control
+   * flow. Used by tooling such as the Inspector event log.
+   */
+  tap(observer) {
+    this.observers.add(observer);
+    return () => {
+      this.observers.delete(observer);
+    };
+  }
   /** Remove all handlers for an event, or all handlers if no event specified. */
   clear(event) {
     if (event !== void 0) {
@@ -437,63 +571,6 @@ var Logger = class {
   }
 };
 
-// src/EngineContext.ts
-var ServiceKey = class {
-  constructor(id, options) {
-    this.id = id;
-    this.scope = options?.scope ?? "engine";
-  }
-  id;
-  static {
-    __name(this, "ServiceKey");
-  }
-  /** Declared scope (engine or scene). Defaults to `"engine"`. */
-  scope;
-};
-var EngineContext = class {
-  static {
-    __name(this, "EngineContext");
-  }
-  services = /* @__PURE__ */ new Map();
-  /** Register a service. Throws if the key is already registered. */
-  register(key, service) {
-    if (this.services.has(key.id)) {
-      throw new Error(`Service "${key.id}" is already registered.`);
-    }
-    this.services.set(key.id, service);
-  }
-  /** Resolve a service. Throws if not registered. */
-  resolve(key) {
-    if (!this.services.has(key.id)) {
-      throw new Error(`Service "${key.id}" is not registered.`);
-    }
-    return this.services.get(key.id);
-  }
-  /** Resolve a service, returning undefined if not registered. */
-  tryResolve(key) {
-    return this.services.get(key.id);
-  }
-  /** Remove a registered service. No-op if not registered. */
-  unregister(key) {
-    this.services.delete(key.id);
-  }
-  /** Check if a service is registered. */
-  has(key) {
-    return this.services.has(key.id);
-  }
-};
-var EngineKey = new ServiceKey("engine");
-var EventBusKey = new ServiceKey("eventBus");
-var SceneManagerKey = new ServiceKey("sceneManager");
-var LoggerKey = new ServiceKey("logger");
-var InspectorKey = new ServiceKey("inspector");
-var QueryCacheKey = new ServiceKey("queryCache");
-var ErrorBoundaryKey = new ServiceKey("errorBoundary");
-var GameLoopKey = new ServiceKey("gameLoop");
-var SystemSchedulerKey = new ServiceKey("systemScheduler");
-var ProcessSystemKey = new ServiceKey("processSystem");
-var AssetManagerKey = new ServiceKey("assetManager");
-
 // src/SceneHooks.ts
 var SceneHookRegistry = class {
   static {
@@ -1230,6 +1307,7 @@ var Entity = class {
       }
     }
     this._scene?._onEntityEvent(token.name, data, this);
+    this._scene?._observeEntityEvent(token.name, data, this);
   }
   /** Get all components as an iterable. */
   getAll() {
@@ -1652,89 +1730,888 @@ var GameLoop = class {
   }
 };
 
-// src/Scene.ts
-var Scene = class {
+// src/Inspector.ts
+var InputManagerRuntimeKey = new ServiceKey("inputManager");
+var PhysicsWorldManagerRuntimeKey = new ServiceKey(
+  "physicsWorldManager"
+);
+var RendererRuntimeKey = new ServiceKey("renderer");
+var Inspector = class {
   static {
-    __name(this, "Scene");
+    __name(this, "Inspector");
   }
-  /** Whether scenes below this one in the stack should be paused. Default: true. */
-  pauseBelow = true;
-  /** Whether scenes below this one should still render. Default: false. */
-  transparentBelow = false;
-  /** Asset handles to load before onEnter(). Override in subclasses. */
-  preload;
-  /** Default transition used when this scene is the destination of a push/pop/replace. */
-  defaultTransition;
-  /** Manual pause flag. Set by game code to pause this scene regardless of stack position. */
-  paused = false;
-  /** Time scale multiplier for this scene. 1.0 = normal, 0.5 = half speed. Default: 1. */
-  timeScale = 1;
-  entities = /* @__PURE__ */ new Set();
-  destroyQueue = [];
-  _context;
-  entityCallbacks;
-  queryCache;
-  bus;
-  _entityEventHandlers;
-  _scopedServices;
-  /** Access the EngineContext. */
-  get context() {
-    return this._context;
+  engine;
+  extensions = /* @__PURE__ */ new Map();
+  sceneIds = /* @__PURE__ */ new WeakMap();
+  nextSceneId = 0;
+  defaultSceneSeed;
+  sceneSeedOverride;
+  timeController = null;
+  eventLogEnabled = false;
+  eventCapacity = 500;
+  /**
+   * Ring buffer of recent events. `eventLogHead` points at the oldest slot;
+   * a full ring contains exactly `eventCapacity` entries. We avoid `splice` to
+   * keep `appendEvent` O(1) — the previous shift-on-overflow approach was
+   * O(n) per event once the buffer was full.
+   */
+  eventLog = [];
+  eventLogHead = 0;
+  eventWaiters = /* @__PURE__ */ new Set();
+  detachBusTap = null;
+  busEventObserver = /* @__PURE__ */ __name((event, data) => {
+    this.recordBusEvent(String(event), data);
+  }, "busEventObserver");
+  sceneEventObserver = /* @__PURE__ */ __name((eventName, data, entity) => {
+    this.recordEntityEvent(eventName, data, entity);
+  }, "sceneEventObserver");
+  time = {
+    freeze: /* @__PURE__ */ __name(() => {
+      this.requireTimeController().freeze();
+    }, "freeze"),
+    thaw: /* @__PURE__ */ __name(() => {
+      this.requireTimeController().thaw();
+    }, "thaw"),
+    step: /* @__PURE__ */ __name((frames = 1) => {
+      this.assertNonNegativeInteger(frames, "Inspector.time.step(frames)");
+      if (frames === 0) return;
+      this.requireTimeController().stepFrames(frames);
+      this.expireDeadlineWaiters();
+    }, "step"),
+    setDelta: /* @__PURE__ */ __name((ms) => {
+      if (!Number.isFinite(ms) || ms <= 0) {
+        throw new Error("Inspector.time.setDelta(ms) requires a positive number.");
+      }
+      this.requireTimeController().setDelta(ms);
+    }, "setDelta"),
+    isFrozen: /* @__PURE__ */ __name(() => this.timeController?.isFrozen ?? false, "isFrozen"),
+    getFrame: /* @__PURE__ */ __name(() => this.timeController?.getFrame() ?? this.engine.loop.frameCount, "getFrame")
+  };
+  input = {
+    keyDown: /* @__PURE__ */ __name((code) => {
+      this.requireInputManager().fireKeyDown(code);
+    }, "keyDown"),
+    keyUp: /* @__PURE__ */ __name((code) => {
+      this.requireInputManager().fireKeyUp(code);
+    }, "keyUp"),
+    mouseMove: /* @__PURE__ */ __name((x, y) => {
+      this.requireInputManager().firePointerMove(x, y);
+    }, "mouseMove"),
+    mouseDown: /* @__PURE__ */ __name((button = 0) => {
+      this.requireInputManager().firePointerDown(button);
+    }, "mouseDown"),
+    mouseUp: /* @__PURE__ */ __name((button = 0) => {
+      this.requireInputManager().firePointerUp(button);
+    }, "mouseUp"),
+    gamepadButton: /* @__PURE__ */ __name((idx, pressed) => {
+      this.requireInputManager().fireGamepadButton(idx, pressed);
+    }, "gamepadButton"),
+    gamepadAxis: /* @__PURE__ */ __name((idx, value) => {
+      this.requireInputManager().fireGamepadAxis(idx, value);
+    }, "gamepadAxis"),
+    tap: /* @__PURE__ */ __name((code, frames = 1) => {
+      this.assertNonNegativeInteger(frames, "Inspector.input.tap(frames)");
+      const input = this.requireInputManager();
+      input.fireKeyDown(code);
+      try {
+        this.time.step(frames);
+      } finally {
+        input.fireKeyUp(code);
+      }
+    }, "tap"),
+    hold: /* @__PURE__ */ __name((code, frames) => {
+      this.assertNonNegativeInteger(frames, "Inspector.input.hold(frames)");
+      const input = this.requireInputManager();
+      input.fireKeyDown(code);
+      try {
+        this.time.step(frames);
+      } finally {
+        input.fireKeyUp(code);
+      }
+    }, "hold"),
+    fireAction: /* @__PURE__ */ __name((name, frames = 1) => {
+      this.assertNonNegativeInteger(
+        frames,
+        "Inspector.input.fireAction(frames)"
+      );
+      const input = this.requireInputManager();
+      for (let i = 0; i < frames; i++) {
+        input.fireAction(name);
+        this.time.step(1);
+      }
+    }, "fireAction"),
+    clearAll: /* @__PURE__ */ __name(() => {
+      this.requireInputManager().clearAll();
+    }, "clearAll")
+  };
+  events = {
+    getLog: /* @__PURE__ */ __name(() => this.iterateLog().map(({ entry }) => ({ ...entry })), "getLog"),
+    clearLog: /* @__PURE__ */ __name(() => {
+      this.eventLog.length = 0;
+      this.eventLogHead = 0;
+    }, "clearLog"),
+    setCapacity: /* @__PURE__ */ __name((n) => {
+      this.assertNonNegativeInteger(
+        n,
+        "Inspector.events.setCapacity(capacity)"
+      );
+      const ordered = n === 0 ? [] : this.iterateLog().slice(-n);
+      this.eventCapacity = n;
+      this.eventLog = ordered;
+      this.eventLogHead = 0;
+    }, "setCapacity"),
+    waitFor: /* @__PURE__ */ __name((pattern, options) => {
+      const existing = this.findMatchingEvent(pattern, options?.source);
+      if (existing) return Promise.resolve(existing);
+      const withinFrames = options?.withinFrames;
+      if (withinFrames !== void 0 && (!Number.isInteger(withinFrames) || withinFrames < 0)) {
+        throw new Error(
+          "Inspector.events.waitFor(withinFrames) requires a non-negative integer."
+        );
+      }
+      return new Promise((resolve, reject) => {
+        const waiter = {
+          pattern,
+          source: options?.source,
+          withinFrames,
+          deadlineFrame: withinFrames !== void 0 ? this.time.getFrame() + withinFrames : void 0,
+          resolve,
+          reject
+        };
+        this.eventWaiters.add(waiter);
+      });
+    }, "waitFor")
+  };
+  capture = {
+    png: /* @__PURE__ */ __name(async () => {
+      const base64 = await this.capture.pngBase64();
+      return decodeBase64(base64);
+    }, "png"),
+    dataURL: /* @__PURE__ */ __name(async () => {
+      const renderer = this.engine.context.tryResolve(RendererRuntimeKey);
+      if (!renderer) {
+        throw new Error(
+          "Inspector.capture requires RendererPlugin to be active."
+        );
+      }
+      const canvas = renderer.application.renderer.extract.canvas(
+        renderer.application.stage
+      );
+      return canvas.toDataURL("image/png");
+    }, "dataURL"),
+    pngBase64: /* @__PURE__ */ __name(async () => {
+      const dataUrl = await this.capture.dataURL();
+      const comma = dataUrl.indexOf(",");
+      return comma === -1 ? dataUrl : dataUrl.slice(comma + 1);
+    }, "pngBase64")
+  };
+  constructor(engine) {
+    this.engine = engine;
   }
-  /** Whether this scene is effectively paused (manual pause or paused by stack). */
-  get isPaused() {
-    if (this.paused) return true;
-    const sm = this._context?.tryResolve(SceneManagerKey);
-    if (!sm) return false;
-    const stack = sm.all;
-    const idx = stack.indexOf(this);
-    if (idx === -1) return false;
-    for (let i = idx + 1; i < stack.length; i++) {
-      if (stack[i].pauseBelow) return true;
+  /** Register a namespaced extension API for plugin-specific debug helpers. */
+  addExtension(namespace, api) {
+    this.assertNonEmptyString(
+      namespace,
+      "Inspector.addExtension(namespace)"
+    );
+    if (!api || typeof api !== "object") {
+      throw new Error("Inspector.addExtension(api) requires an object.");
     }
-    return false;
+    if (this.extensions.has(namespace)) {
+      throw new Error(
+        `Inspector.addExtension(): namespace "${namespace}" is already registered.`
+      );
+    }
+    this.extensions.set(namespace, api);
+    return api;
   }
-  /** Whether a scene transition is currently running. */
-  get isTransitioning() {
-    const sm = this._context?.tryResolve(SceneManagerKey);
-    return sm?.isTransitioning ?? false;
+  /** Look up a previously registered extension API by namespace. */
+  getExtension(namespace) {
+    this.assertNonEmptyString(
+      namespace,
+      "Inspector.getExtension(namespace)"
+    );
+    return this.extensions.get(namespace);
   }
-  /** Convenience accessor for the AssetManager. */
-  get assets() {
-    return this._context.resolve(AssetManagerKey);
+  /** Remove a previously registered extension namespace. */
+  removeExtension(namespace) {
+    this.assertNonEmptyString(
+      namespace,
+      "Inspector.removeExtension(namespace)"
+    );
+    this.extensions.delete(namespace);
   }
-  /**
-   * Lazy proxy-based service resolution. Can be used at field-declaration time:
-   * ```ts
-   * readonly layers = this.service(RenderLayerManagerKey);
-   * ```
-   * The actual resolution is deferred until first property access.
-   */
-  service(key) {
-    let resolved;
-    return new Proxy({}, {
-      get: /* @__PURE__ */ __name((_target, prop) => {
-        resolved ??= this._context.resolve(key);
-        const value = resolved[prop];
-        return typeof value === "function" ? value.bind(resolved) : value;
-      }, "get"),
-      set: /* @__PURE__ */ __name((_target, prop, value) => {
-        resolved ??= this._context.resolve(key);
-        resolved[prop] = value;
-        return true;
-      }, "set")
-    });
+  /** Full deterministic state snapshot (stable ordering, serializable). */
+  snapshot() {
+    const scenes = this.engine.scenes.all.map(
+      (scene) => this.sceneToWorldSnapshot(scene)
+    );
+    return {
+      version: 1,
+      frame: this.time.getFrame(),
+      sceneStack: this.getSceneStack(),
+      entityCount: this.countEntities(),
+      systemCount: this.getSystems().length,
+      errors: this.getErrors(),
+      scenes,
+      camera: this.buildCameraSnapshot(),
+      input: this.buildInputSnapshot()
+    };
   }
-  spawn(nameOrBlueprintOrClass, params) {
-    if (typeof nameOrBlueprintOrClass === "function") {
-      const entity2 = new nameOrBlueprintOrClass();
-      entity2._setScene(this, this.entityCallbacks);
-      this.entities.add(entity2);
-      this.bus?.emit("entity:created", { entity: entity2 });
-      entity2.setup?.(params);
-      return entity2;
+  /** Stable JSON form of {@link snapshot}. */
+  snapshotJSON() {
+    return stableStringify(this.snapshot());
+  }
+  /** Snapshot one scene by inspector scene id. */
+  snapshotScene(id) {
+    const scene = this.engine.scenes.all.find(
+      (candidate) => this.getSceneId(candidate) === id
+    );
+    if (!scene) {
+      throw new Error(`Inspector.snapshotScene(): unknown scene id "${id}".`);
     }
-    const isBlueprint = typeof nameOrBlueprintOrClass === "object" && nameOrBlueprintOrClass !== null && "build" in nameOrBlueprintOrClass;
+    return this.sceneToWorldSnapshot(scene);
+  }
+  /** Find entity by name in the active scene. */
+  getEntityByName(name) {
+    const entity = this.findActiveEntity(name);
+    if (!entity) return void 0;
+    return this.entityToQuerySnapshot(entity);
+  }
+  /** Get entity position (from Transform component). */
+  getEntityPosition(name) {
+    const entity = this.findActiveEntity(name);
+    if (!entity) return void 0;
+    const transform = this.getTransform(entity);
+    if (!transform) return void 0;
+    return { x: transform.position.x, y: transform.position.y };
+  }
+  /** Check if an entity has a component by class name string. */
+  hasComponent(entityName, componentClass) {
+    return this.findComponentByName(entityName, componentClass) !== void 0;
+  }
+  /** Get component data (serializable subset) by class name string. */
+  getComponentData(entityName, componentClass) {
+    const comp = this.findComponentByName(entityName, componentClass);
+    if (!comp) return void 0;
+    if (typeof comp.serialize === "function") {
+      const data = trySerialize(comp);
+      if (data !== void 0) return data;
+    }
+    return this.serializeComponentOwnProperties(comp);
+  }
+  /** Get all entities in the active scene as lightweight snapshots. */
+  getEntities() {
+    const scene = this.engine.scenes.active;
+    if (!scene) return [];
+    const result = [];
+    for (const entity of scene.getEntities()) {
+      if (!entity.isDestroyed) {
+        result.push(this.entityToQuerySnapshot(entity));
+      }
+    }
+    return result;
+  }
+  /** Get scene stack info. */
+  getSceneStack() {
+    return this.engine.scenes.all.map((scene) => ({
+      name: scene.name,
+      entityCount: scene.getEntities().size,
+      paused: scene.isPaused
+    }));
+  }
+  /** Get active system info. */
+  getSystems() {
+    const scheduler = this.engine.context.tryResolve(SystemSchedulerKey);
+    if (!scheduler) return [];
+    return scheduler.getAllSystems().map((sys) => ({
+      name: sys.constructor.name,
+      phase: sys.phase,
+      priority: sys.priority,
+      enabled: sys.enabled
+    }));
+  }
+  /** Get disabled components/systems from error boundary. */
+  getErrors() {
+    const boundary = this.engine.context.tryResolve(ErrorBoundaryKey);
+    if (!boundary) return { disabledSystems: [], disabledComponents: [] };
+    const disabled = boundary.getDisabled();
+    return {
+      disabledSystems: disabled.systems.map(
+        (s) => s.system.constructor.name
+      ),
+      disabledComponents: disabled.components.map((c) => ({
+        entity: c.component.entity?.name ?? "unknown",
+        component: c.component.constructor.name,
+        error: c.error
+      }))
+    };
+  }
+  /** Create a new scene-scoped RNG instance using the current inspector seed policy. */
+  createSceneRandom() {
+    const seed = this.sceneSeedOverride ?? this.defaultSceneSeed ?? createDefaultRandomSeed();
+    return createRandomService(seed);
+  }
+  /** Force every current and future scene RNG to the provided seed. */
+  setSeed(seed) {
+    const normalized = normalizeSeed(seed);
+    this.sceneSeedOverride = normalized;
+    for (const scene of this.engine.scenes.all) {
+      this.resolveInternalRandom(scene)?.setSeed(normalized);
+    }
+  }
+  /** @internal DebugPlugin installs a deterministic default seed through this hook. */
+  setDefaultSceneSeed(seed) {
+    this.defaultSceneSeed = seed === void 0 ? void 0 : normalizeSeed(seed);
+    if (this.sceneSeedOverride !== void 0 || this.defaultSceneSeed === void 0) {
+      return;
+    }
+    for (const scene of this.engine.scenes.all) {
+      this.resolveInternalRandom(scene)?.setSeed(this.defaultSceneSeed);
+    }
+  }
+  resolveInternalRandom(scene) {
+    return scene._resolveScoped(RandomKey);
+  }
+  /** @internal DebugPlugin attaches the frozen-time controller through this hook. */
+  attachTimeController(controller) {
+    this.timeController = controller;
+  }
+  /** @internal Clear a previously attached time controller. */
+  detachTimeController(controller) {
+    if (!controller || this.timeController === controller) {
+      this.timeController = null;
+    }
+  }
+  /** @internal Enable or disable event log recording. */
+  setEventLogEnabled(enabled) {
+    if (this.eventLogEnabled === enabled) return;
+    this.eventLogEnabled = enabled;
+    if (enabled) {
+      if (!this.detachBusTap && this.engine.events?.tap) {
+        this.detachBusTap = this.engine.events.tap(this.busEventObserver);
+      }
+    } else {
+      this.detachBusTap?.();
+      this.detachBusTap = null;
+    }
+    for (const scene of this.engine.scenes.all) {
+      if (enabled) {
+        this.attachSceneEventObserver(scene);
+      } else {
+        this.detachSceneEventObserver(scene);
+      }
+    }
+  }
+  /** @internal Install entity-event observation for one scene. No-op if disabled. */
+  attachSceneEventObserver(scene) {
+    if (!this.eventLogEnabled) return;
+    scene._setEntityEventObserver(this.sceneEventObserver);
+  }
+  /** @internal Clear entity-event observation for one scene. */
+  detachSceneEventObserver(scene) {
+    scene._setEntityEventObserver(void 0);
+  }
+  /** @internal Scene hooks forward entity events through this method. */
+  recordEntityEvent(eventName, data, entity) {
+    if (!this.eventLogEnabled) return;
+    const scene = entity.tryScene;
+    this.appendEvent(
+      {
+        frame: this.time.getFrame(),
+        source: "entity",
+        type: eventName,
+        targetId: String(entity.id),
+        payload: serializeEventPayload(data)
+      },
+      scene ? this.getSceneId(scene) : void 0
+    );
+  }
+  /** @internal Engine teardown releases the event-bus tap through this hook. */
+  dispose() {
+    this.detachBusTap?.();
+    this.detachBusTap = null;
+    for (const scene of this.engine.scenes.all) {
+      scene._setEntityEventObserver(void 0);
+    }
+    this.extensions.clear();
+  }
+  requireTimeController() {
+    if (!this.timeController) {
+      throw new Error(
+        "Inspector.time requires DebugPlugin to be active."
+      );
+    }
+    return this.timeController;
+  }
+  requireInputManager() {
+    const input = this.engine.context.tryResolve(InputManagerRuntimeKey);
+    if (!input) {
+      throw new Error(
+        "Inspector.input requires InputPlugin to be active."
+      );
+    }
+    return input;
+  }
+  recordBusEvent(type, data) {
+    if (!this.eventLogEnabled) return;
+    this.appendEvent(
+      {
+        frame: this.time.getFrame(),
+        source: "bus",
+        type,
+        payload: serializeEventPayload(data)
+      },
+      this.inferSceneIdFromPayload(data)
+    );
+  }
+  appendEvent(entry, sceneId) {
+    if (this.eventCapacity === 0) {
+      this.flushMatchingWaiter(entry);
+      return;
+    }
+    const logged = { entry, sceneId };
+    if (this.eventLog.length < this.eventCapacity) {
+      this.eventLog.push(logged);
+    } else {
+      this.eventLog[this.eventLogHead] = logged;
+      this.eventLogHead = (this.eventLogHead + 1) % this.eventCapacity;
+    }
+    this.flushMatchingWaiter(entry);
+  }
+  /** Resolve waiters whose deadline has passed without a match. */
+  expireDeadlineWaiters() {
+    if (this.eventWaiters.size === 0) return;
+    const frame = this.time.getFrame();
+    for (const waiter of [...this.eventWaiters]) {
+      if (waiter.deadlineFrame !== void 0 && frame > waiter.deadlineFrame) {
+        this.eventWaiters.delete(waiter);
+        waiter.reject(
+          new Error(
+            `Inspector.events.waitFor() timed out after ${waiter.withinFrames} frames.`
+          )
+        );
+      }
+    }
+  }
+  /** Resolve any waiter that matches the just-appended entry. */
+  flushMatchingWaiter(entry) {
+    if (this.eventWaiters.size === 0) return;
+    for (const waiter of [...this.eventWaiters]) {
+      if (this.eventMatches(entry, waiter.pattern, waiter.source)) {
+        this.eventWaiters.delete(waiter);
+        waiter.resolve(entry);
+      }
+    }
+  }
+  /**
+   * Walk the ring buffer in chronological order. We avoid materializing the
+   * ordered array on every event append; instead, every consumer that needs
+   * order calls this helper.
+   */
+  iterateLog() {
+    if (this.eventLog.length < this.eventCapacity || this.eventLogHead === 0) {
+      return this.eventLog;
+    }
+    return [
+      ...this.eventLog.slice(this.eventLogHead),
+      ...this.eventLog.slice(0, this.eventLogHead)
+    ];
+  }
+  findMatchingEvent(pattern, source) {
+    for (const { entry } of this.iterateLog()) {
+      if (this.eventMatches(entry, pattern, source)) {
+        return { ...entry };
+      }
+    }
+    return void 0;
+  }
+  eventMatches(entry, pattern, source) {
+    if (source && entry.source !== source) return false;
+    return typeof pattern === "string" ? entry.type === pattern : pattern.test(entry.type);
+  }
+  sceneToWorldSnapshot(scene) {
+    const random = scene._resolveScoped(RandomKey);
+    const physicsManager = this.engine.context.tryResolve(
+      PhysicsWorldManagerRuntimeKey
+    );
+    return {
+      id: this.getSceneId(scene),
+      name: scene.name,
+      paused: scene.isPaused,
+      timeScale: scene.timeScale,
+      seed: random?.getSeed() ?? 0,
+      entities: this.getSceneEntities(scene),
+      ui: this.buildUISnapshot(scene),
+      physics: physicsManager?.getContext(scene)?.world.snapshot() ?? {
+        bodies: [],
+        contacts: []
+      },
+      events: this.getSceneEvents(scene)
+    };
+  }
+  getSceneEntities(scene) {
+    return [...scene.getEntities()].filter((entity) => !entity.isDestroyed).sort((a, b) => a.id - b.id).map((entity) => this.entityToWorldSnapshot(entity));
+  }
+  entityToWorldSnapshot(entity) {
+    const transform = entity.has(Transform) ? entity.get(Transform) : void 0;
+    const worldPosition = transform?.worldPosition;
+    const worldScale = transform?.worldScale;
+    const components = [...entity.getAll()].map((component) => this.componentToSnapshot(component)).sort((a, b) => a.type < b.type ? -1 : a.type > b.type ? 1 : 0);
+    return {
+      id: String(entity.id),
+      type: entity.constructor.name,
+      parent: entity.parent ? String(entity.parent.id) : null,
+      transform: {
+        x: worldPosition?.x ?? 0,
+        y: worldPosition?.y ?? 0,
+        rotation: transform?.worldRotation ?? 0,
+        scaleX: worldScale?.x ?? 1,
+        scaleY: worldScale?.y ?? 1
+      },
+      components
+    };
+  }
+  componentToSnapshot(component) {
+    return {
+      type: component.constructor.name,
+      state: typeof component.serialize === "function" ? trySerialize(component) ?? null : null
+    };
+  }
+  buildUISnapshot(scene) {
+    const roots = [...scene.getEntities()].filter((entity) => !entity.isDestroyed).flatMap(
+      (entity) => [...entity.getAll()].filter(
+        (component) => component.constructor.name === "UIPanel" && "_node" in component
+      ).map(
+        (component, index) => this.buildUINodeSnapshot(
+          component._node,
+          `entity-${entity.id}:UIPanel:${index}`
+        )
+      )
+    );
+    if (roots.length === 0) return null;
+    if (roots.length === 1) {
+      return { root: roots[0] };
+    }
+    return {
+      root: {
+        id: `scene-${this.getSceneId(scene)}:ui`,
+        type: "UIRoot",
+        layout: { x: 0, y: 0, width: 0, height: 0 },
+        children: roots,
+        state: null
+      }
+    };
+  }
+  buildUINodeSnapshot(node, id) {
+    const layout = node.yogaNode?.getComputedLayout();
+    const children = (node.children ?? []).map(
+      (child, index) => this.buildUINodeSnapshot(child, `${id}/${index}`)
+    );
+    return {
+      id,
+      type: node.constructor.name,
+      layout: {
+        x: layout?.left ?? 0,
+        y: layout?.top ?? 0,
+        width: layout?.width ?? 0,
+        height: layout?.height ?? 0
+      },
+      children,
+      state: null
+    };
+  }
+  buildCameraSnapshot() {
+    const match = this.findTopmostCamera();
+    if (!match) return null;
+    const { scene, camera } = match;
+    return {
+      sceneId: this.getSceneId(scene),
+      sceneName: scene.name,
+      name: camera.cameraName ?? null,
+      priority: camera.priority ?? 0,
+      position: {
+        x: camera.position.x,
+        y: camera.position.y
+      },
+      zoom: camera.zoom,
+      rotation: camera.rotation
+    };
+  }
+  findTopmostCamera() {
+    const stack = this.engine.scenes.all;
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const scene = stack[i];
+      if (!scene) continue;
+      let highest;
+      for (const entity of scene.getEntities()) {
+        if (entity.isDestroyed) continue;
+        for (const component of entity.getAll()) {
+          if (component.constructor.name !== "CameraComponent") continue;
+          const camera = component;
+          if (camera.enabled && (!highest || (camera.priority ?? 0) > (highest.priority ?? 0))) {
+            highest = camera;
+          }
+        }
+      }
+      if (highest) {
+        return { scene, camera: highest };
+      }
+    }
+    return void 0;
+  }
+  buildInputSnapshot() {
+    const input = this.engine.context.tryResolve(InputManagerRuntimeKey);
+    return input?.snapshotState() ?? {
+      keys: [],
+      actions: [],
+      mouse: { x: 0, y: 0, buttons: [], down: false },
+      gamepad: { buttons: [], axes: [] }
+    };
+  }
+  getSceneEvents(scene) {
+    const sceneId = this.getSceneId(scene);
+    return this.iterateLog().filter((entry) => entry.sceneId === sceneId).map(({ entry }) => ({ ...entry }));
+  }
+  inferSceneIdFromPayload(data) {
+    if (!data || typeof data !== "object") return void 0;
+    const record = data;
+    const scene = this.extractScene(record["scene"]) ?? this.extractSceneFromEntity(record["entity"]) ?? this.extractSceneFromEntity(record["oldScene"]) ?? this.extractSceneFromEntity(record["newScene"]);
+    return scene ? this.getSceneId(scene) : void 0;
+  }
+  extractScene(value) {
+    if (!value || typeof value !== "object") return void 0;
+    return this.engine.scenes.all.find((scene) => scene === value);
+  }
+  extractSceneFromEntity(value) {
+    if (!value || typeof value !== "object") return void 0;
+    const maybeEntity = value;
+    return maybeEntity.tryScene ?? this.extractScene(value);
+  }
+  findActiveEntity(name) {
+    return this.engine.scenes.active?.findEntity(name);
+  }
+  findComponentByName(entityName, componentClass) {
+    const entity = this.findActiveEntity(entityName);
+    if (!entity) return void 0;
+    for (const comp of entity.getAll()) {
+      if (comp.constructor.name === componentClass) return comp;
+    }
+    return void 0;
+  }
+  entityToQuerySnapshot(entity) {
+    const transform = this.getTransform(entity);
+    const snapshot = {
+      id: entity.id,
+      name: entity.name,
+      tags: [...entity.tags].sort((a, b) => a < b ? -1 : a > b ? 1 : 0),
+      components: [...entity.getAll()].map((component) => component.constructor.name).sort((a, b) => a < b ? -1 : a > b ? 1 : 0)
+    };
+    if (transform) {
+      snapshot.position = {
+        x: transform.position.x,
+        y: transform.position.y
+      };
+    }
+    return snapshot;
+  }
+  getTransform(entity) {
+    return entity.has(Transform) ? entity.get(Transform) : void 0;
+  }
+  serializeComponentOwnProperties(comp) {
+    const result = {};
+    for (const key of Object.getOwnPropertyNames(comp)) {
+      if (key === "entity") continue;
+      if (key.startsWith("_")) continue;
+      const value = comp[key];
+      if (!isSerializableValue(value)) continue;
+      result[key] = value;
+    }
+    return result;
+  }
+  countEntities() {
+    let count = 0;
+    for (const scene of this.engine.scenes.all) {
+      for (const entity of scene.getEntities()) {
+        if (!entity.isDestroyed) count++;
+      }
+    }
+    return count;
+  }
+  getSceneId(scene) {
+    let id = this.sceneIds.get(scene);
+    if (!id) {
+      this.nextSceneId++;
+      id = `scene-${this.nextSceneId}`;
+      this.sceneIds.set(scene, id);
+    }
+    return id;
+  }
+  assertNonNegativeInteger(value, name) {
+    if (!Number.isInteger(value) || value < 0) {
+      throw new Error(`${name} requires a non-negative integer.`);
+    }
+  }
+  assertNonEmptyString(value, name) {
+    if (value.trim().length === 0) {
+      throw new Error(`${name} requires a non-empty string.`);
+    }
+  }
+};
+function isSerializableValue(value) {
+  if (value === null || value === void 0) return true;
+  const t = typeof value;
+  if (t === "function") return false;
+  if (t !== "object") return true;
+  if (Array.isArray(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+__name(isSerializableValue, "isSerializableValue");
+function safeClone(value) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return void 0;
+  }
+}
+__name(safeClone, "safeClone");
+function trySerialize(component) {
+  try {
+    return safeClone(component.serialize?.());
+  } catch {
+    return void 0;
+  }
+}
+__name(trySerialize, "trySerialize");
+function serializeEventPayload(payload) {
+  if (payload === void 0) return null;
+  const cloned = safeClone(payload);
+  return cloned === void 0 ? { _unserializable: true } : cloned;
+}
+__name(serializeEventPayload, "serializeEventPayload");
+function stableStringify(value) {
+  return JSON.stringify(sortJsonValue(value));
+}
+__name(stableStringify, "stableStringify");
+function sortJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJsonValue(item));
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).sort(
+      ([left], [right]) => left < right ? -1 : left > right ? 1 : 0
+    );
+    const result = {};
+    for (const [key, child] of entries) {
+      result[key] = sortJsonValue(child);
+    }
+    return result;
+  }
+  return value;
+}
+__name(sortJsonValue, "sortJsonValue");
+function decodeBase64(base64) {
+  if (typeof atob === "function") {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+  }
+  const bufferCtor = globalThis.Buffer;
+  if (bufferCtor) {
+    return bufferCtor.from(base64, "base64");
+  }
+  throw new Error("Inspector.capture.png() is not supported in this environment.");
+}
+__name(decodeBase64, "decodeBase64");
+
+// src/Scene.ts
+var Scene = class {
+  static {
+    __name(this, "Scene");
+  }
+  /** Whether scenes below this one in the stack should be paused. Default: true. */
+  pauseBelow = true;
+  /** Whether scenes below this one should still render. Default: false. */
+  transparentBelow = false;
+  /** Asset handles to load before onEnter(). Override in subclasses. */
+  preload;
+  /** Default transition used when this scene is the destination of a push/pop/replace. */
+  defaultTransition;
+  /** Manual pause flag. Set by game code to pause this scene regardless of stack position. */
+  paused = false;
+  /** Time scale multiplier for this scene. 1.0 = normal, 0.5 = half speed. Default: 1. */
+  timeScale = 1;
+  entities = /* @__PURE__ */ new Set();
+  destroyQueue = [];
+  _context;
+  entityCallbacks;
+  queryCache;
+  bus;
+  _entityEventHandlers;
+  _entityEventObserver;
+  _scopedServices;
+  /** Access the EngineContext. */
+  get context() {
+    return this._context;
+  }
+  /** Whether this scene is effectively paused (manual pause or paused by stack). */
+  get isPaused() {
+    if (this.paused) return true;
+    const sm = this._context?.tryResolve(SceneManagerKey);
+    if (!sm) return false;
+    const stack = sm.all;
+    const idx = stack.indexOf(this);
+    if (idx === -1) return false;
+    for (let i = idx + 1; i < stack.length; i++) {
+      if (stack[i].pauseBelow) return true;
+    }
+    return false;
+  }
+  /** Whether a scene transition is currently running. */
+  get isTransitioning() {
+    const sm = this._context?.tryResolve(SceneManagerKey);
+    return sm?.isTransitioning ?? false;
+  }
+  /** Convenience accessor for the AssetManager. */
+  get assets() {
+    return this._context.resolve(AssetManagerKey);
+  }
+  /**
+   * Lazy proxy-based service resolution. Can be used at field-declaration time:
+   * ```ts
+   * readonly layers = this.service(RenderLayerManagerKey);
+   * ```
+   * The actual resolution is deferred until first property access.
+   */
+  service(key) {
+    let resolved;
+    return new Proxy({}, {
+      get: /* @__PURE__ */ __name((_target, prop) => {
+        resolved ??= this._context.resolve(key);
+        const value = resolved[prop];
+        return typeof value === "function" ? value.bind(resolved) : value;
+      }, "get"),
+      set: /* @__PURE__ */ __name((_target, prop, value) => {
+        resolved ??= this._context.resolve(key);
+        resolved[prop] = value;
+        return true;
+      }, "set")
+    });
+  }
+  spawn(nameOrBlueprintOrClass, params) {
+    if (typeof nameOrBlueprintOrClass === "function") {
+      const entity2 = new nameOrBlueprintOrClass();
+      entity2._setScene(this, this.entityCallbacks);
+      this.entities.add(entity2);
+      this.bus?.emit("entity:created", { entity: entity2 });
+      entity2.setup?.(params);
+      return entity2;
+    }
+    const isBlueprint = typeof nameOrBlueprintOrClass === "object" && nameOrBlueprintOrClass !== null && "build" in nameOrBlueprintOrClass;
     const name = isBlueprint ? nameOrBlueprintOrClass.name : nameOrBlueprintOrClass;
     const entity = new Entity(name);
     entity._setScene(this, this.entityCallbacks);
@@ -1822,6 +2699,14 @@ var Scene = class {
       }
     }
   }
+  /**
+   * Observe entity-scoped event emissions after they dispatch locally and
+   * bubble to the scene. Tooling only; game code should keep using `on()`.
+   * @internal
+   */
+  _observeEntityEvent(eventName, data, entity) {
+    this._entityEventObserver?.(eventName, data, entity);
+  }
   // ---- Internal methods ----
   /**
    * Register a scene-scoped service. Called from a plugin's `beforeEnter`
@@ -1833,6 +2718,13 @@ var Scene = class {
     this._scopedServices ??= /* @__PURE__ */ new Map();
     this._scopedServices.set(key.id, value);
   }
+  /**
+   * Install or clear a tooling-only observer for bubbled entity events.
+   * @internal
+   */
+  _setEntityEventObserver(observer) {
+    this._entityEventObserver = observer;
+  }
   /**
    * Resolve a scene-scoped service, or `undefined` if none was registered.
    * @internal
@@ -1899,6 +2791,128 @@ var Scene = class {
   }
 };
 
+// src/Process.ts
+var Process = class _Process {
+  static {
+    __name(this, "Process");
+  }
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+  updateFn;
+  onCompleteFn;
+  duration;
+  loop;
+  /** Tags for filtering/grouping. */
+  tags;
+  elapsed = 0;
+  _completed = false;
+  _paused = false;
+  _cancelled = false;
+  resolvePromise;
+  /** Create a timer that fires `onComplete` after `duration` ms. */
+  static delay(duration, onComplete, tags) {
+    const opts = { duration };
+    if (onComplete !== void 0) opts.onComplete = onComplete;
+    if (tags !== void 0) opts.tags = tags;
+    return new _Process(opts);
+  }
+  constructor(options) {
+    this.updateFn = options.update ?? (() => {
+    });
+    this.onCompleteFn = options.onComplete;
+    this.duration = options.duration;
+    this.loop = options.loop ?? false;
+    this.tags = options.tags ?? [];
+  }
+  /** Whether the process has completed. */
+  get completed() {
+    return this._completed;
+  }
+  /** Whether the process is paused. */
+  get paused() {
+    return this._paused;
+  }
+  /** Pause the process. */
+  pause() {
+    this._paused = true;
+  }
+  /** Resume the process. */
+  resume() {
+    this._paused = false;
+  }
+  /** Cancel the process. */
+  cancel() {
+    this._cancelled = true;
+    this._completed = true;
+    this.resolvePromise?.();
+  }
+  /** Returns a promise that resolves when the process completes or is cancelled. */
+  toPromise() {
+    if (this._completed) return Promise.resolve();
+    return new Promise((resolve) => {
+      this.resolvePromise = resolve;
+    });
+  }
+  /**
+   * Advance the process by dt milliseconds.
+   * @internal
+   */
+  _update(dt) {
+    if (this._completed || this._paused || this._cancelled) return;
+    this.elapsed += dt;
+    if (this.duration !== void 0 && this.elapsed >= this.duration) {
+      const result2 = this.updateFn(dt, this.elapsed);
+      if (this.loop && result2 !== true) {
+        this.elapsed = this.elapsed % this.duration;
+        return;
+      }
+      this.complete();
+      return;
+    }
+    const result = this.updateFn(dt, this.elapsed);
+    if (result === true) {
+      if (this.loop) {
+        this.elapsed = 0;
+        return;
+      }
+      this.complete();
+    }
+  }
+  /**
+   * Reset the process to its initial state so it can be re-run.
+   * @internal Used by Sequence for loop/repeat with direct instances.
+   */
+  _reset() {
+    this.elapsed = 0;
+    this._completed = false;
+    this._paused = false;
+    this._cancelled = false;
+    delete this.resolvePromise;
+  }
+  complete() {
+    this._completed = true;
+    this.onCompleteFn?.();
+    this.resolvePromise?.();
+  }
+};
+var easeLinear = /* @__PURE__ */ __name((t) => t, "easeLinear");
+var easeInQuad = /* @__PURE__ */ __name((t) => t * t, "easeInQuad");
+var easeOutQuad = /* @__PURE__ */ __name((t) => t * (2 - t), "easeOutQuad");
+var easeInOutQuad = /* @__PURE__ */ __name((t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t, "easeInOutQuad");
+var easeOutBounce = /* @__PURE__ */ __name((t) => {
+  if (t < 1 / 2.75) {
+    return 7.5625 * t * t;
+  } else if (t < 2 / 2.75) {
+    const t2 = t - 1.5 / 2.75;
+    return 7.5625 * t2 * t2 + 0.75;
+  } else if (t < 2.5 / 2.75) {
+    const t2 = t - 2.25 / 2.75;
+    return 7.5625 * t2 * t2 + 0.9375;
+  } else {
+    const t2 = t - 2.625 / 2.75;
+    return 7.5625 * t2 * t2 + 0.984375;
+  }
+}, "easeOutBounce");
+
 // src/LoadingScene.ts
 var LoadingScene = class extends Scene {
   static {
@@ -1923,6 +2937,7 @@ var LoadingScene = class extends Scene {
   _active = true;
   _continueRequested = false;
   _continueGate;
+  _pendingWaits = /* @__PURE__ */ new Set();
   // Bumped on every `_run` attempt. `AssetManager.loadAll` uses `Promise.all`
   // under the hood, so individual loaders from a failed attempt can still
   // resolve and fire `onProgress` after the attempt rejects. Without this
@@ -1977,28 +2992,32 @@ var LoadingScene = class extends Scene {
   onExit() {
     this._active = false;
     this._continueGate?.();
+    for (const wait of this._pendingWaits) {
+      wait.cancel();
+    }
+    this._pendingWaits.clear();
   }
   async _run() {
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await Promise.resolve();
     if (!this._active) return;
     const attempt = ++this._attempt;
     const target = typeof this.target === "function" ? this.target() : this.target;
-    const startedAt = performance.now();
     const bus = this.context.resolve(EventBusKey);
+    const minDuration = this._createEngineTimeDelay(this.minDuration);
     try {
       await this.assets.loadAll(target.preload ?? [], (ratio) => {
         if (!this._active || attempt !== this._attempt) return;
         this._progress = ratio;
         bus.emit("scene:loading:progress", { scene: this, ratio });
       });
-      if (!this._active || attempt !== this._attempt) return;
-      const elapsed = performance.now() - startedAt;
-      const remaining = this.minDuration - elapsed;
-      if (remaining > 0) {
-        await new Promise((resolve) => setTimeout(resolve, remaining));
-        if (!this._active || attempt !== this._attempt) return;
+      if (!this._active || attempt !== this._attempt) {
+        minDuration.cancel();
+        return;
       }
+      await minDuration.promise;
+      if (!this._active || attempt !== this._attempt) return;
     } catch (err) {
+      minDuration.cancel();
       if (!this._active || attempt !== this._attempt) return;
       const error = err instanceof Error ? err : new Error(String(err));
       this._started = false;
@@ -2022,6 +3041,26 @@ var LoadingScene = class extends Scene {
       this.transition ? { transition: this.transition } : void 0
     );
   }
+  _createEngineTimeDelay(ms) {
+    if (ms <= 0) {
+      return {
+        promise: Promise.resolve(),
+        cancel: /* @__PURE__ */ __name(() => {
+        }, "cancel")
+      };
+    }
+    const wait = Process.delay(ms);
+    this._pendingWaits.add(wait);
+    this.context.resolve(ProcessSystemKey).add(wait);
+    return {
+      promise: wait.toPromise().finally(() => {
+        this._pendingWaits.delete(wait);
+      }),
+      cancel: /* @__PURE__ */ __name(() => {
+        wait.cancel();
+      }, "cancel")
+    };
+  }
 };
 
 // src/SceneTransition.ts
@@ -2427,177 +3466,55 @@ var SceneManager = class {
       kind: run.kind,
       engineContext: this._context,
       fromScene: run.fromScene,
-      toScene: run.toScene
-    };
-  }
-  _snapshotPauseStates() {
-    return new Map(
-      this.stack.map((scene) => [scene, scene.isPaused])
-    );
-  }
-  _assertNotMutating(method) {
-    if (this._mutationDepth === 0) return;
-    throw new Error(
-      `SceneManager.${method}() called reentrantly from a scene lifecycle hook (onEnter/onExit/onPause/onResume or a beforeEnter/afterExit hook). Defer the call outside the hook, e.g. via queueMicrotask() or from a component update().`
-    );
-  }
-  async _withMutation(work) {
-    this._mutationDepth++;
-    try {
-      return await work();
-    } finally {
-      this._mutationDepth--;
-    }
-  }
-  _withMutationSync(work) {
-    this._mutationDepth++;
-    try {
-      return work();
-    } finally {
-      this._mutationDepth--;
-    }
-  }
-  /** Fire onPause() for scenes that transitioned from not-paused to paused. */
-  _firePauseTransitions(wasPaused) {
-    for (const scene of this.stack) {
-      const was = wasPaused.get(scene) ?? false;
-      if (scene.isPaused && !was) {
-        scene.onPause?.();
-      }
-    }
-  }
-  /** Fire onResume() for scenes that transitioned from paused to not-paused. */
-  _fireResumeTransitions(wasPaused) {
-    for (const scene of this.stack) {
-      const was = wasPaused.get(scene) ?? false;
-      if (!scene.isPaused && was) {
-        scene.onResume?.();
-      }
-    }
-  }
-};
-
-// src/Process.ts
-var Process = class _Process {
-  static {
-    __name(this, "Process");
-  }
-  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
-  updateFn;
-  onCompleteFn;
-  duration;
-  loop;
-  /** Tags for filtering/grouping. */
-  tags;
-  elapsed = 0;
-  _completed = false;
-  _paused = false;
-  _cancelled = false;
-  resolvePromise;
-  /** Create a timer that fires `onComplete` after `duration` ms. */
-  static delay(duration, onComplete, tags) {
-    const opts = { duration };
-    if (onComplete !== void 0) opts.onComplete = onComplete;
-    if (tags !== void 0) opts.tags = tags;
-    return new _Process(opts);
-  }
-  constructor(options) {
-    this.updateFn = options.update ?? (() => {
-    });
-    this.onCompleteFn = options.onComplete;
-    this.duration = options.duration;
-    this.loop = options.loop ?? false;
-    this.tags = options.tags ?? [];
-  }
-  /** Whether the process has completed. */
-  get completed() {
-    return this._completed;
-  }
-  /** Whether the process is paused. */
-  get paused() {
-    return this._paused;
+      toScene: run.toScene
+    };
   }
-  /** Pause the process. */
-  pause() {
-    this._paused = true;
+  _snapshotPauseStates() {
+    return new Map(
+      this.stack.map((scene) => [scene, scene.isPaused])
+    );
   }
-  /** Resume the process. */
-  resume() {
-    this._paused = false;
+  _assertNotMutating(method) {
+    if (this._mutationDepth === 0) return;
+    throw new Error(
+      `SceneManager.${method}() called reentrantly from a scene lifecycle hook (onEnter/onExit/onPause/onResume or a beforeEnter/afterExit hook). Defer the call outside the hook, e.g. via queueMicrotask() or from a component update().`
+    );
   }
-  /** Cancel the process. */
-  cancel() {
-    this._cancelled = true;
-    this._completed = true;
-    this.resolvePromise?.();
+  async _withMutation(work) {
+    this._mutationDepth++;
+    try {
+      return await work();
+    } finally {
+      this._mutationDepth--;
+    }
   }
-  /** Returns a promise that resolves when the process completes or is cancelled. */
-  toPromise() {
-    if (this._completed) return Promise.resolve();
-    return new Promise((resolve) => {
-      this.resolvePromise = resolve;
-    });
+  _withMutationSync(work) {
+    this._mutationDepth++;
+    try {
+      return work();
+    } finally {
+      this._mutationDepth--;
+    }
   }
-  /**
-   * Advance the process by dt milliseconds.
-   * @internal
-   */
-  _update(dt) {
-    if (this._completed || this._paused || this._cancelled) return;
-    this.elapsed += dt;
-    if (this.duration !== void 0 && this.elapsed >= this.duration) {
-      const result2 = this.updateFn(dt, this.elapsed);
-      if (this.loop && result2 !== true) {
-        this.elapsed = this.elapsed % this.duration;
-        return;
+  /** Fire onPause() for scenes that transitioned from not-paused to paused. */
+  _firePauseTransitions(wasPaused) {
+    for (const scene of this.stack) {
+      const was = wasPaused.get(scene) ?? false;
+      if (scene.isPaused && !was) {
+        scene.onPause?.();
       }
-      this.complete();
-      return;
     }
-    const result = this.updateFn(dt, this.elapsed);
-    if (result === true) {
-      if (this.loop) {
-        this.elapsed = 0;
-        return;
+  }
+  /** Fire onResume() for scenes that transitioned from paused to not-paused. */
+  _fireResumeTransitions(wasPaused) {
+    for (const scene of this.stack) {
+      const was = wasPaused.get(scene) ?? false;
+      if (!scene.isPaused && was) {
+        scene.onResume?.();
       }
-      this.complete();
     }
   }
-  /**
-   * Reset the process to its initial state so it can be re-run.
-   * @internal Used by Sequence for loop/repeat with direct instances.
-   */
-  _reset() {
-    this.elapsed = 0;
-    this._completed = false;
-    this._paused = false;
-    this._cancelled = false;
-    delete this.resolvePromise;
-  }
-  complete() {
-    this._completed = true;
-    this.onCompleteFn?.();
-    this.resolvePromise?.();
-  }
 };
-var easeLinear = /* @__PURE__ */ __name((t) => t, "easeLinear");
-var easeInQuad = /* @__PURE__ */ __name((t) => t * t, "easeInQuad");
-var easeOutQuad = /* @__PURE__ */ __name((t) => t * (2 - t), "easeOutQuad");
-var easeInOutQuad = /* @__PURE__ */ __name((t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t, "easeInOutQuad");
-var easeOutBounce = /* @__PURE__ */ __name((t) => {
-  if (t < 1 / 2.75) {
-    return 7.5625 * t * t;
-  } else if (t < 2 / 2.75) {
-    const t2 = t - 1.5 / 2.75;
-    return 7.5625 * t2 * t2 + 0.75;
-  } else if (t < 2.5 / 2.75) {
-    const t2 = t - 2.25 / 2.75;
-    return 7.5625 * t2 * t2 + 0.9375;
-  } else {
-    const t2 = t - 2.625 / 2.75;
-    return 7.5625 * t2 * t2 + 0.984375;
-  }
-}, "easeOutBounce");
 
 // src/Tween.ts
 var Tween = {
@@ -2824,7 +3741,9 @@ var ProcessSlot = class {
 };
 
 // src/ProcessComponent.ts
-var ProcessComponent = class extends Component {
+var _ProcessComponent_decorators, _init2, _a2;
+_ProcessComponent_decorators = [serializable];
+var ProcessComponent = class extends (_a2 = Component) {
   static {
     __name(this, "ProcessComponent");
   }
@@ -2894,10 +3813,18 @@ var ProcessComponent = class extends Component {
   onDestroy() {
     this.cancel();
   }
+  serialize() {
+    return null;
+  }
 };
+_init2 = __decoratorStart(_a2);
+ProcessComponent = __decorateElement(_init2, 0, "ProcessComponent", _ProcessComponent_decorators, ProcessComponent);
+__runInitializers(_init2, 1, ProcessComponent);
 
 // src/KeyframeAnimator.ts
-var KeyframeAnimator = class extends Component {
+var _KeyframeAnimator_decorators, _init3, _a3;
+_KeyframeAnimator_decorators = [serializable];
+var KeyframeAnimator = class extends (_a3 = Component) {
   static {
     __name(this, "KeyframeAnimator");
   }
@@ -2949,6 +3876,9 @@ var KeyframeAnimator = class extends Component {
   onDestroy() {
     this.stopAll();
   }
+  serialize() {
+    return null;
+  }
   stopInternal(name, complete) {
     const process = this.active.get(name);
     if (!process) return;
@@ -2957,6 +3887,9 @@ var KeyframeAnimator = class extends Component {
     this.defs[name]?.onExit?.(complete);
   }
 };
+_init3 = __decoratorStart(_a3);
+KeyframeAnimator = __decorateElement(_init3, 0, "KeyframeAnimator", _KeyframeAnimator_decorators, KeyframeAnimator);
+__runInitializers(_init3, 1, KeyframeAnimator);
 
 // src/Sequence.ts
 var Sequence = class {
@@ -3108,36 +4041,94 @@ var ProcessSystem = class extends System {
   /** Global time scale multiplier. Stacks multiplicatively with per-scene timeScale. */
   timeScale = 1;
   sceneManager;
-  sceneProcesses = /* @__PURE__ */ new Set();
+  globalProcesses = /* @__PURE__ */ new Set();
+  scenePools = /* @__PURE__ */ new Map();
+  _unregisterSceneHook = null;
   onRegister(context) {
     this.sceneManager = context.resolve(SceneManagerKey);
+    const hooks = context.tryResolve(SceneHookRegistryKey);
+    this._unregisterSceneHook = hooks?.register({
+      afterExit: /* @__PURE__ */ __name((scene) => this.cancelForScene(scene), "afterExit")
+    }) ?? null;
+  }
+  onUnregister() {
+    this._unregisterSceneHook?.();
+    this._unregisterSceneHook = null;
+    for (const p of this.globalProcesses) {
+      if (!p.completed) p.cancel();
+    }
+    this.globalProcesses.clear();
+    for (const pool of this.scenePools.values()) {
+      for (const p of pool) {
+        if (!p.completed) p.cancel();
+      }
+    }
+    this.scenePools.clear();
   }
-  /** Add a scene-level process (not tied to any entity). */
+  /**
+   * Add an engine-global process. Ticked under the global timeScale only;
+   * NOT gated by per-scene pause or scaled by per-scene timeScale. Use this
+   * for cross-scene effects (e.g. screen-scope filter fades on `app.stage`)
+   * or processes that have no owning scene.
+   */
   add(process) {
-    this.sceneProcesses.add(process);
+    this.globalProcesses.add(process);
+    return process;
+  }
+  /**
+   * Add a process bound to a specific scene's lifecycle. Ticked only while
+   * the scene is active (not paused) and scaled by the scene's `timeScale`,
+   * exactly like an entity-owned `ProcessComponent`. Use this for layer or
+   * scene-scope effect fades that should pause with the scene.
+   */
+  addForScene(scene, process) {
+    let pool = this.scenePools.get(scene);
+    if (!pool) {
+      pool = /* @__PURE__ */ new Set();
+      this.scenePools.set(scene, pool);
+    }
+    pool.add(process);
     return process;
   }
-  /** Cancel scene-level processes, optionally by tag. */
+  /** Cancel engine-global processes, optionally by tag. */
   cancel(tag) {
-    for (const p of this.sceneProcesses) {
+    for (const p of this.globalProcesses) {
       if (tag === void 0 || p.tags.includes(tag)) {
         p.cancel();
+        this.globalProcesses.delete(p);
       }
     }
-    if (tag === void 0) {
-      this.sceneProcesses.clear();
+  }
+  /** Cancel every scene-bound process for `scene`, optionally by tag. */
+  cancelForScene(scene, tag) {
+    const pool = this.scenePools.get(scene);
+    if (!pool) return;
+    for (const p of pool) {
+      if (tag === void 0 || p.tags.includes(tag)) {
+        p.cancel();
+        pool.delete(p);
+      }
     }
+    if (pool.size === 0) this.scenePools.delete(scene);
   }
   update(dt) {
     const globalScaledDt = dt * this.timeScale;
-    for (const p of this.sceneProcesses) {
+    for (const p of this.globalProcesses) {
       p._update(globalScaledDt);
       if (p.completed) {
-        this.sceneProcesses.delete(p);
+        this.globalProcesses.delete(p);
       }
     }
     for (const scene of this.sceneManager.activeScenes) {
       const effectiveDt = globalScaledDt * scene.timeScale;
+      const pool = this.scenePools.get(scene);
+      if (pool) {
+        for (const p of pool) {
+          p._update(effectiveDt);
+          if (p.completed) pool.delete(p);
+        }
+        if (pool.size === 0) this.scenePools.delete(scene);
+      }
       for (const entity of scene.getEntities()) {
         if (entity.isDestroyed) continue;
         const pc = entity.tryGet(ProcessComponent);
@@ -3148,145 +4139,45 @@ var ProcessSystem = class extends System {
   }
 };
 
-// src/Inspector.ts
-var Inspector = class {
-  static {
-    __name(this, "Inspector");
-  }
-  engine;
-  constructor(engine) {
-    this.engine = engine;
-  }
-  /** Full state snapshot (serializable). */
-  snapshot() {
-    return {
-      frameCount: this.engine.loop.frameCount,
-      sceneStack: this.getSceneStack(),
-      entityCount: this.countEntities(),
-      systemCount: this.getSystems().length,
-      errors: this.getErrors()
-    };
-  }
-  /** Find entity by name in the active scene. */
-  getEntityByName(name) {
-    const entity = this.findActiveEntity(name);
-    if (!entity) return void 0;
-    return this.entityToSnapshot(entity);
-  }
-  /** Get entity position (from Transform component). */
-  getEntityPosition(name) {
-    const entity = this.findActiveEntity(name);
-    if (!entity) return void 0;
-    const transform = this.getTransform(entity);
-    if (!transform) return void 0;
-    return { x: transform.position.x, y: transform.position.y };
-  }
-  /** Check if an entity has a component by class name string. */
-  hasComponent(entityName, componentClass) {
-    return this.findComponentByName(entityName, componentClass) !== void 0;
-  }
-  /** Get component data (serializable subset) by class name string. */
-  getComponentData(entityName, componentClass) {
-    const comp = this.findComponentByName(entityName, componentClass);
-    if (!comp) return void 0;
-    return this.serializeComponent(comp);
-  }
-  /** Get all entities in the active scene as snapshots. */
-  getEntities() {
-    const scene = this.engine.scenes.active;
-    if (!scene) return [];
-    const result = [];
-    for (const entity of scene.getEntities()) {
-      if (!entity.isDestroyed) {
-        result.push(this.entityToSnapshot(entity));
+// src/ProcessQueue.ts
+function makeQueue(route) {
+  const ours = /* @__PURE__ */ new Set();
+  return {
+    run(p) {
+      for (const old of ours) {
+        if (old.completed) ours.delete(old);
       }
-    }
-    return result;
-  }
-  /** Get scene stack info. */
-  getSceneStack() {
-    return this.engine.scenes.all.map((scene) => ({
-      name: scene.name,
-      entityCount: scene.getEntities().size,
-      paused: scene.isPaused
-    }));
-  }
-  /** Get active system info. */
-  getSystems() {
-    const scheduler = this.engine.context.tryResolve(SystemSchedulerKey);
-    if (!scheduler) return [];
-    return scheduler.getAllSystems().map((sys) => ({
-      name: sys.constructor.name,
-      phase: sys.phase,
-      priority: sys.priority,
-      enabled: sys.enabled
-    }));
-  }
-  /** Get disabled components/systems from error boundary. */
-  getErrors() {
-    const boundary = this.engine.context.tryResolve(ErrorBoundaryKey);
-    if (!boundary) return { disabledSystems: [], disabledComponents: [] };
-    const disabled = boundary.getDisabled();
-    return {
-      disabledSystems: disabled.systems.map(
-        (s) => s.system.constructor.name
-      ),
-      disabledComponents: disabled.components.map((c) => ({
-        entity: c.component.entity?.name ?? "unknown",
-        component: c.component.constructor.name,
-        error: c.error
-      }))
-    };
-  }
-  findActiveEntity(name) {
-    return this.engine.scenes.active?.findEntity(name);
-  }
-  findComponentByName(entityName, componentClass) {
-    const entity = this.findActiveEntity(entityName);
-    if (!entity) return void 0;
-    for (const comp of entity.getAll()) {
-      if (comp.constructor.name === componentClass) return comp;
-    }
-    return void 0;
-  }
-  entityToSnapshot(entity) {
-    const transform = this.getTransform(entity);
-    const snapshot = {
-      id: entity.id,
-      name: entity.name,
-      tags: [...entity.tags],
-      components: [...entity.getAll()].map((c) => c.constructor.name)
-    };
-    if (transform) {
-      snapshot.position = {
-        x: transform.position.x,
-        y: transform.position.y
-      };
-    }
-    return snapshot;
-  }
-  getTransform(entity) {
-    return entity.has(Transform) ? entity.get(Transform) : void 0;
-  }
-  serializeComponent(comp) {
-    const result = {};
-    for (const key of Object.getOwnPropertyNames(comp)) {
-      if (key === "entity") continue;
-      const value = comp[key];
-      if (typeof value !== "function") {
-        result[key] = value;
+      route(p);
+      ours.add(p);
+      return p;
+    },
+    cancelAll() {
+      for (const p of ours) {
+        if (!p.completed) p.cancel();
       }
+      ours.clear();
     }
-    return result;
-  }
-  countEntities() {
-    let count = 0;
-    for (const scene of this.engine.scenes.all) {
-      count += scene.getEntities().size;
-    }
-    return count;
-  }
-};
+  };
+}
+__name(makeQueue, "makeQueue");
+function makeEntityScopedQueue(entity) {
+  return makeQueue((p) => {
+    let pc = entity.tryGet(ProcessComponent);
+    if (!pc) {
+      pc = entity.add(new ProcessComponent());
+    }
+    pc.run(p);
+  });
+}
+__name(makeEntityScopedQueue, "makeEntityScopedQueue");
+function makeSceneScopedQueue(processSystem, scene) {
+  return makeQueue((p) => processSystem.addForScene(scene, p));
+}
+__name(makeSceneScopedQueue, "makeSceneScopedQueue");
+function makeGlobalScopedQueue(processSystem) {
+  return makeQueue((p) => processSystem.add(p));
+}
+__name(makeGlobalScopedQueue, "makeGlobalScopedQueue");
 
 // src/Engine.ts
 var Engine = class {
@@ -3340,6 +4231,15 @@ var Engine = class {
     this.context.register(SystemSchedulerKey, this.scheduler);
     this.context.register(AssetManagerKey, this.assets);
     this.context.register(SceneHookRegistryKey, this.sceneHooks);
+    this.sceneHooks.register({
+      beforeEnter: /* @__PURE__ */ __name((scene) => {
+        scene._registerScoped(RandomKey, this.inspector.createSceneRandom());
+        this.inspector.attachSceneEventObserver(scene);
+      }, "beforeEnter"),
+      afterExit: /* @__PURE__ */ __name((scene) => {
+        this.inspector.detachSceneEventObserver(scene);
+      }, "afterExit")
+    });
     this.scenes._setContext(this.context);
     this.registerBuiltInSystems();
     this.loop.setCallbacks({
@@ -3421,6 +4321,7 @@ var Engine = class {
     if (this.debug && typeof globalThis !== "undefined" && "__yage__" in globalThis) {
       delete globalThis["__yage__"];
     }
+    this.inspector.dispose();
     this.events.clear();
     this.started = false;
   }
@@ -3518,6 +4419,7 @@ function createMockScene(name = "mock-scene") {
   ctx.register(ErrorBoundaryKey, boundary);
   const scene = new _TestScene(name);
   scene._setContext(ctx);
+  scene._registerScoped(RandomKey, createRandomService(1234));
   return { scene, context: ctx };
 }
 __name(createMockScene, "createMockScene");
@@ -3571,6 +4473,7 @@ export {
   QueryCache,
   QueryCacheKey,
   QueryResult,
+  RandomKey,
   RendererAdapterKey,
   SERIALIZABLE_KEY,
   Scene,
@@ -3592,9 +4495,11 @@ export {
   Vec2,
   _resetEntityIdCounter,
   advanceFrames,
+  createDefaultRandomSeed,
   createKeyframeTrack,
   createMockEntity,
   createMockScene,
+  createRandomService,
   createTestEngine,
   defineBlueprint,
   defineEvent,
@@ -3606,8 +4511,13 @@ export {
   easeOutQuad,
   filterEntities,
   getSerializableType,
+  globalRandom,
   interpolate,
   isSerializable,
+  makeEntityScopedQueue,
+  makeGlobalScopedQueue,
+  makeSceneScopedQueue,
+  normalizeSeed,
   resolveTransition,
   serializable,
   trait