@yagejs/core 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -85,6 +85,7 @@ __export(index_exports, {
   Inspector: () => Inspector,
   InspectorKey: () => InspectorKey,
   KeyframeAnimator: () => KeyframeAnimator,
+  LoadingScene: () => LoadingScene,
   LogLevel: () => LogLevel,
   Logger: () => Logger,
   LoggerKey: () => LoggerKey,
@@ -98,8 +99,11 @@ __export(index_exports, {
   QueryCache: () => QueryCache,
   QueryCacheKey: () => QueryCacheKey,
   QueryResult: () => QueryResult,
+  RendererAdapterKey: () => RendererAdapterKey,
   SERIALIZABLE_KEY: () => SERIALIZABLE_KEY,
   Scene: () => Scene,
+  SceneHookRegistry: () => SceneHookRegistry,
+  SceneHookRegistryKey: () => SceneHookRegistryKey,
   SceneManager: () => SceneManager,
   SceneManagerKey: () => SceneManagerKey,
   Sequence: () => Sequence,
@@ -132,6 +136,7 @@ __export(index_exports, {
   getSerializableType: () => getSerializableType,
   interpolate: () => interpolate,
   isSerializable: () => isSerializable,
+  resolveTransition: () => resolveTransition,
   serializable: () => serializable,
   trait: () => trait
 });
@@ -261,14 +266,52 @@ var Vec2 = class _Vec2 {
   static lerp(a, b, t) {
     return new _Vec2(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t);
   }
+  /** Move current toward target by at most maxDelta without overshooting. */
+  static moveTowards(current, target, maxDelta) {
+    const dx = target.x - current.x;
+    const dy = target.y - current.y;
+    const distanceSq = dx * dx + dy * dy;
+    if (distanceSq < EPSILON * EPSILON) {
+      return new _Vec2(target.x, target.y);
+    }
+    if (maxDelta <= 0) {
+      return new _Vec2(current.x, current.y);
+    }
+    const distance = Math.sqrt(distanceSq);
+    if (distance <= maxDelta) {
+      return new _Vec2(target.x, target.y);
+    }
+    const scale = maxDelta / distance;
+    return new _Vec2(current.x + dx * scale, current.y + dy * scale);
+  }
 };
 
 // src/MathUtils.ts
+var TAU = Math.PI * 2;
+var MIN_SMOOTH_TIME = 1e-4;
+function normalizeAngle(radians) {
+  const wrapped = ((radians + Math.PI) % TAU + TAU) % TAU - Math.PI;
+  return wrapped === -Math.PI && radians > 0 ? Math.PI : wrapped;
+}
+__name(normalizeAngle, "normalizeAngle");
 var MathUtils = {
   /** Linear interpolation between a and b. */
   lerp(a, b, t) {
     return a + (b - a) * t;
   },
+  /** Return the clamped interpolation factor that produces v between a and b. */
+  inverseLerp(a, b, v) {
+    if (a === b) return 0;
+    return MathUtils.clamp((v - a) / (b - a), 0, 1);
+  },
+  /** Interpolate between angles in radians along the shortest path. */
+  lerpAngle(a, b, t) {
+    return normalizeAngle(a + MathUtils.shortestAngleBetween(a, b) * t);
+  },
+  /** Signed shortest angular delta from a to b, in radians. */
+  shortestAngleBetween(a, b) {
+    return normalizeAngle(b - a);
+  },
   /** Clamp a value between min and max. */
   clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
@@ -278,6 +321,12 @@ var MathUtils = {
     const t = (value - inMin) / (inMax - inMin);
     return outMin + (outMax - outMin) * t;
   },
+  /** Bounce t between 0 and length. */
+  pingPong(t, length) {
+    if (length <= 0) return 0;
+    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);
@@ -301,6 +350,34 @@ var MathUtils = {
     }
     return Math.max(current - step, target);
   },
+  /**
+   * Smoothly damp current toward target without overshooting.
+   * Pass the returned velocity back into the next call.
+   */
+  smoothDamp(current, target, velocity, smoothTime, deltaTime, maxSpeed = Infinity) {
+    if (deltaTime <= 0) {
+      return { value: current, velocity };
+    }
+    const safeSmoothTime = Math.max(MIN_SMOOTH_TIME, smoothTime);
+    const omega = 2 / safeSmoothTime;
+    const x = omega * deltaTime;
+    const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x);
+    const originalTarget = target;
+    const maxChange = maxSpeed * safeSmoothTime;
+    const change = MathUtils.clamp(current - target, -maxChange, maxChange);
+    const adjustedTarget = current - change;
+    const temp = (velocity + omega * change) * deltaTime;
+    const nextVelocity = (velocity - omega * temp) * exp;
+    let value = adjustedTarget + (change + temp) * exp;
+    let resultVelocity = nextVelocity;
+    const targetIsAboveCurrent = originalTarget - current > 0;
+    const valuePassedTarget = targetIsAboveCurrent ? value > originalTarget : value < originalTarget;
+    if (valuePassedTarget) {
+      value = originalTarget;
+      resultVelocity = 0;
+    }
+    return { value, velocity: resultVelocity };
+  },
   /** Wrap value into the range [min, max). */
   wrap(value, min, max) {
     const range = max - min;
@@ -458,13 +535,16 @@ var Logger = class {
 
 // src/EngineContext.ts
 var ServiceKey = class {
-  constructor(id) {
+  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 {
@@ -510,6 +590,50 @@ var SystemSchedulerKey = new ServiceKey("systemScheduler");
 var ProcessSystemKey = new ServiceKey("processSystem");
 var AssetManagerKey = new ServiceKey("assetManager");
 
+// src/SceneHooks.ts
+var SceneHookRegistry = class {
+  static {
+    __name(this, "SceneHookRegistry");
+  }
+  hooks = [];
+  register(hooks) {
+    this.hooks.push(hooks);
+    return () => {
+      const idx = this.hooks.indexOf(hooks);
+      if (idx !== -1) this.hooks.splice(idx, 1);
+    };
+  }
+  /** Run all `beforeEnter` hooks serially. */
+  async runBeforeEnter(scene) {
+    for (const h of this.hooks) {
+      await h.beforeEnter?.(scene);
+    }
+  }
+  runAfterExit(scene) {
+    for (const h of this.hooks) {
+      try {
+        h.afterExit?.(scene);
+      } catch (err) {
+        const logger = scene.context.tryResolve(LoggerKey);
+        if (logger) {
+          logger.error("core", "Scene afterExit hook threw", {
+            scene: scene.name,
+            error: err
+          });
+        } else {
+          console.error(
+            `[yage] Scene afterExit hook threw for scene "${scene.name}":`,
+            err
+          );
+        }
+      }
+    }
+  }
+};
+var SceneHookRegistryKey = new ServiceKey(
+  "sceneHookRegistry"
+);
+
 // src/EventToken.ts
 var EventToken = class {
   constructor(name) {
@@ -731,10 +855,11 @@ var Component = class {
   _cleanups;
   /**
    * Access the entity's scene. Throws if the entity is not in a scene.
-   * Prefer this over `this.entity.scene!` in component methods.
+   * Prefer this over threading through `this.entity.scene` in component
+   * code.
    */
   get scene() {
-    const scene = this.entity.scene;
+    const scene = this.entity.tryScene;
     if (!scene) {
       throw new Error(
         "Cannot access scene: entity is not attached to a scene."
@@ -749,20 +874,43 @@ var Component = class {
   get context() {
     return this.scene.context;
   }
-  /** Resolve a service by key, cached after first lookup. */
+  /**
+   * Resolve a service by key, cached after first lookup. Scene-scoped values
+   * (registered via `scene._registerScoped`) take precedence over engine
+   * scope. A key declared with `scope: "scene"` that falls back to engine
+   * scope emits a one-shot dev warning — almost always signals a missed
+   * `beforeEnter` hook.
+   */
   use(key) {
     this._serviceCache ??= /* @__PURE__ */ new Map();
-    let value = this._serviceCache.get(key.id);
-    if (value === void 0) {
-      value = this.context.resolve(key);
-      this._serviceCache.set(key.id, value);
-    }
+    const cached = this._serviceCache.get(key.id);
+    if (cached !== void 0) return cached;
+    const scene = this.entity.tryScene;
+    const scoped = scene?._resolveScoped(key);
+    if (scoped !== void 0) {
+      this._serviceCache.set(key.id, scoped);
+      return scoped;
+    }
+    const value = this.context.resolve(key);
+    if (key.scope === "scene") {
+      this._warnScopedFallback(key);
+      return value;
+    }
+    this._serviceCache.set(key.id, value);
     return value;
   }
+  _warnScopedFallback(key) {
+    const logger = this.context.tryResolve(LoggerKey);
+    logger?.warn(
+      "core",
+      `Scoped key "${key.id}" fell back to engine scope \u2014 did a plugin forget to register a beforeEnter hook?`,
+      { component: this.constructor.name }
+    );
+  }
   /**
    * Lazy proxy-based service resolution. Can be used at field-declaration time:
    * ```ts
-   * readonly camera = this.service(CameraKey);
+   * readonly input = this.service(InputManagerKey);
    * ```
    * The actual resolution is deferred until first property access.
    */
@@ -1019,8 +1167,27 @@ var Entity = class {
     this.name = name ?? new.target.name ?? "Entity";
     this.tags = new Set(tags);
   }
-  /** The scene this entity belongs to, or null. */
+  /**
+   * The scene this entity belongs to. Throws if the entity is not attached
+   * to a scene — which in practice only happens before `scene.spawn` /
+   * `addChild` wires it up, or after `destroy()` tears it down. Inside
+   * lifecycle methods (`setup`, component `onAdd`, `update`, etc.) this is
+   * always safe to access.
+   *
+   * For the rare case where you genuinely need to inspect whether an
+   * entity has a scene (e.g. defensive code in systems iterating a query
+   * result), use `tryScene` instead.
+   */
   get scene() {
+    if (!this._scene) {
+      throw new Error(
+        `Entity "${this.name}" is not attached to a scene. Use \`tryScene\` if you need to check.`
+      );
+    }
+    return this._scene;
+  }
+  /** The scene this entity belongs to, or `null` if detached. */
+  get tryScene() {
     return this._scene;
   }
   /** True if destroy() has been called. */
@@ -1058,6 +1225,20 @@ var Entity = class {
       this._scene._addExistingEntity(child);
     }
   }
+  spawnChild(name, classOrBlueprint, params) {
+    const scene = this.scene;
+    if (this._children?.has(name)) {
+      throw new Error(
+        `Entity "${this.name}" already has a child named "${name}".`
+      );
+    }
+    const child = classOrBlueprint === void 0 ? scene.spawn(name) : scene.spawn(
+      classOrBlueprint,
+      params
+    );
+    this.addChild(name, child);
+    return child;
+  }
   /** Remove a named child. Returns the detached entity. */
   removeChild(name) {
     const child = this._children?.get(name);
@@ -1550,7 +1731,7 @@ var GameLoop = class {
   }
   /** Process one frame with the given dt in milliseconds. */
   tick(dtMs) {
-    if (!this.callbacks) return;
+    if (!this.running || !this.callbacks) return;
     this._frameCount++;
     this.callbacks.earlyUpdate(dtMs);
     this.accumulator += dtMs;
@@ -1578,6 +1759,8 @@ var Scene = class {
   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. */
@@ -1589,6 +1772,7 @@ var Scene = class {
   queryCache;
   bus;
   _entityEventHandlers;
+  _scopedServices;
   /** Access the EngineContext. */
   get context() {
     return this._context;
@@ -1606,6 +1790,11 @@ var Scene = class {
     }
     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);
@@ -1730,6 +1919,31 @@ var Scene = class {
     }
   }
   // ---- Internal methods ----
+  /**
+   * Register a scene-scoped service. Called from a plugin's `beforeEnter`
+   * hook to make per-scene state (render tree, physics world) resolvable via
+   * `Component.use(key)`.
+   * @internal
+   */
+  _registerScoped(key, value) {
+    this._scopedServices ??= /* @__PURE__ */ new Map();
+    this._scopedServices.set(key.id, value);
+  }
+  /**
+   * Resolve a scene-scoped service, or `undefined` if none was registered.
+   * @internal
+   */
+  _resolveScoped(key) {
+    return this._scopedServices?.get(key.id);
+  }
+  /**
+   * Clear all scene-scoped services. Called by the SceneManager after
+   * `afterExit` hooks run, so plugin cleanup code still sees scoped state.
+   * @internal
+   */
+  _clearScopedServices() {
+    this._scopedServices?.clear();
+  }
   /**
    * Set the engine context. Called by SceneManager when the scene is pushed.
    * @internal
@@ -1781,6 +1995,138 @@ var Scene = class {
   }
 };
 
+// src/LoadingScene.ts
+var LoadingScene = class extends Scene {
+  static {
+    __name(this, "LoadingScene");
+  }
+  name = "loading";
+  /**
+   * Minimum wall-clock ms the scene stays visible before handing off.
+   * Prevents flicker on cached loads. Default 0.
+   */
+  minDuration = 0;
+  /** Transition used for the loading → target handoff. */
+  transition;
+  /**
+   * When true (default), the handoff fires automatically after loading and
+   * `minDuration`. Set false to gate it behind `continue()` — useful when
+   * the loading scene also asks the player to press a key or click.
+   */
+  autoContinue = true;
+  _progress = 0;
+  _started = false;
+  _active = true;
+  _continueRequested = false;
+  _continueGate;
+  // 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
+  // guard, a retry kicked off from `onLoadError` would see stale progress
+  // callbacks mutate `_progress` and emit `scene:loading:progress` events
+  // attributed to the current attempt.
+  _attempt = 0;
+  /** Current load progress, 0 → 1. Updated as the AssetManager reports progress. */
+  get progress() {
+    return this._progress;
+  }
+  /**
+   * Kick off asset loading. While a load is in flight, subsequent calls
+   * are no-ops. After a load failure the guard is released, so calling
+   * `startLoading()` from `onLoadError` (or from a retry button) kicks off
+   * a fresh load against the same target.
+   *
+   * Usually called once from `onEnter` after spawning the loading UI:
+   * ```ts
+   * override onEnter() {
+   *   this.spawn(LoadingSceneProgressBar);
+   *   this.startLoading();
+   * }
+   * ```
+   *
+   * Deferring the call lets you gate the start of the load behind a
+   * title screen, "press any key" prompt, intro animation, etc.
+   */
+  startLoading() {
+    if (this._started) return;
+    this._started = true;
+    this._run().catch((err) => {
+      if (!this._active) return;
+      const logger = this.context.tryResolve(LoggerKey);
+      if (logger) {
+        logger.error("LoadingScene", "loading failed", { error: err });
+      } else {
+        console.error("[LoadingScene] loading failed:", err);
+      }
+    });
+  }
+  /**
+   * Trigger the handoff to `target`. No-op if already called or if
+   * `autoContinue` already fired it. If called before loading finishes,
+   * the handoff runs as soon as loading + `minDuration` complete.
+   */
+  continue() {
+    if (this._continueRequested) return;
+    this._continueRequested = true;
+    this._continueGate?.();
+  }
+  onExit() {
+    this._active = false;
+    this._continueGate?.();
+  }
+  async _run() {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    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);
+    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;
+      }
+    } catch (err) {
+      if (!this._active || attempt !== this._attempt) return;
+      const error = err instanceof Error ? err : new Error(String(err));
+      this._started = false;
+      this._attempt++;
+      if (this.onLoadError) {
+        await this.onLoadError(error);
+        return;
+      }
+      throw error;
+    }
+    bus.emit("scene:loading:done", { scene: this });
+    if (!this.autoContinue && !this._continueRequested) {
+      await new Promise((resolve) => {
+        this._continueGate = resolve;
+      });
+      if (!this._active || attempt !== this._attempt) return;
+    }
+    const scenes = this.context.resolve(SceneManagerKey);
+    await scenes.replace(
+      target,
+      this.transition ? { transition: this.transition } : void 0
+    );
+  }
+};
+
+// src/SceneTransition.ts
+function resolveTransition(callSite, destination) {
+  if (callSite) return callSite;
+  return destination?.defaultTransition;
+}
+__name(resolveTransition, "resolveTransition");
+
 // src/SceneManager.ts
 var SceneManager = class {
   static {
@@ -1790,6 +2136,35 @@ var SceneManager = class {
   _context;
   bus;
   assetManager;
+  hookRegistry;
+  logger;
+  _currentRun;
+  _pendingChain = Promise.resolve();
+  _mutationDepth = 0;
+  _destroyed = false;
+  _autoPauseOnBlur = false;
+  _isBlurred = false;
+  _visibilityPausedScenes = /* @__PURE__ */ new Set();
+  _visibilityListenerCleanup;
+  /**
+   * Pause all non-paused scenes when `document.hidden` becomes `true`; restore
+   * them on focus. Default: `false`. Only scenes paused by this mechanism are
+   * restored — user-paused scenes (manual `scene.paused = true` or `pauseBelow`
+   * cascade) are never touched.
+   */
+  get autoPauseOnBlur() {
+    return this._autoPauseOnBlur;
+  }
+  set autoPauseOnBlur(value) {
+    if (this._autoPauseOnBlur === value) return;
+    this._autoPauseOnBlur = value;
+    if (!this._isBlurred) return;
+    if (value) {
+      this._applyBlurPause();
+    } else if (this._visibilityPausedScenes.size > 0) {
+      this._restoreBlurPause();
+    }
+  }
   /**
    * Set the engine context.
    * @internal
@@ -1798,6 +2173,42 @@ var SceneManager = class {
     this._context = context;
     this.bus = context.tryResolve(EventBusKey);
     this.assetManager = context.tryResolve(AssetManagerKey);
+    this.hookRegistry = context.tryResolve(SceneHookRegistryKey);
+    this.logger = context.tryResolve(LoggerKey);
+    if (this._visibilityListenerCleanup || typeof document === "undefined") {
+      return;
+    }
+    const onVisibilityChange = /* @__PURE__ */ __name(() => {
+      this._handleVisibilityChange(document.hidden);
+    }, "onVisibilityChange");
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    this._visibilityListenerCleanup = () => document.removeEventListener("visibilitychange", onVisibilityChange);
+  }
+  /**
+   * React to a visibility change. Parameterised on `hidden` so unit tests can
+   * drive it without a real `document`.
+   * @internal
+   */
+  _handleVisibilityChange(hidden) {
+    if (hidden && !this._isBlurred) {
+      this._isBlurred = true;
+      if (this._autoPauseOnBlur) this._applyBlurPause();
+    } else if (!hidden && this._isBlurred) {
+      this._isBlurred = false;
+      if (this._visibilityPausedScenes.size > 0) this._restoreBlurPause();
+    }
+  }
+  _applyBlurPause() {
+    for (const scene of this.activeScenes) {
+      scene.paused = true;
+      this._visibilityPausedScenes.add(scene);
+    }
+  }
+  _restoreBlurPause() {
+    for (const scene of this._visibilityPausedScenes) {
+      scene.paused = false;
+    }
+    this._visibilityPausedScenes.clear();
   }
   /** The topmost (active) scene. */
   get active() {
@@ -1809,84 +2220,132 @@ var SceneManager = class {
   }
   /** All non-paused scenes in the stack, bottom to top. */
   get activeScenes() {
-    return this.stack.filter((s) => !s.isPaused);
+    return this.stack.filter((scene) => !scene.isPaused);
+  }
+  /** Whether a scene transition is currently running. */
+  get isTransitioning() {
+    return this._currentRun !== void 0;
   }
   /**
    * Push a scene onto the stack. Scenes below may receive onPause().
    * If the scene declares a `preload` array, assets are loaded before onEnter().
-   * Await the returned promise when using preloaded scenes.
    */
-  push(scene) {
-    const wasPaused = new Map(this.stack.map((s) => [s, s.isPaused]));
-    scene._setContext(this._context);
-    this.stack.push(scene);
-    this._firePauseTransitions(wasPaused);
-    if (scene.preload?.length && this.assetManager) {
-      return this.assetManager.loadAll(scene.preload, scene.onProgress?.bind(scene)).then(() => {
-        scene.onEnter?.();
-        this.bus?.emit("scene:pushed", { scene });
-      });
-    }
-    scene.onEnter?.();
-    this.bus?.emit("scene:pushed", { scene });
-    return Promise.resolve();
+  async push(scene, opts) {
+    this._assertNotMutating("push");
+    await this._enqueue(async () => {
+      const fromScene = this.active;
+      await this._pushScene(scene);
+      const transition = resolveTransition(opts?.transition, scene);
+      if (!transition) return;
+      await this._runTransition("push", transition, fromScene, scene);
+    });
   }
   /** Pop the top scene. Scenes below may receive onResume(). */
-  pop() {
-    const wasPaused = new Map(this.stack.map((s) => [s, s.isPaused]));
-    const removed = this.stack.pop();
-    if (!removed) return void 0;
-    removed.onExit?.();
-    removed._destroyAllEntities();
-    this._fireResumeTransitions(wasPaused);
-    this.bus?.emit("scene:popped", { scene: removed });
-    return removed;
+  async pop(opts) {
+    this._assertNotMutating("pop");
+    return this._enqueue(async () => {
+      if (this.stack.length === 0) return void 0;
+      const fromScene = this.active;
+      const destination = this.stack.length > 1 ? this.stack[this.stack.length - 2] : void 0;
+      const transition = resolveTransition(opts?.transition, destination);
+      if (transition) {
+        await this._runTransition("pop", transition, fromScene, destination);
+      }
+      return this._popScene();
+    });
   }
   /**
-   * Replace the top scene. Old scene receives onExit().
-   * New scene receives onEnter() (after preload, if declared).
+   * Replace the top scene. Without a transition the old scene exits first,
+   * then the new scene enters. With a transition the new scene is pushed
+   * first, both scenes coexist for the transition duration, then the old
+   * scene is removed at the end.
    */
-  replace(scene) {
-    const wasPaused = new Map(this.stack.map((s) => [s, s.isPaused]));
-    const old = this.stack.pop();
-    if (old) {
-      old.onExit?.();
-      old._destroyAllEntities();
-    }
-    scene._setContext(this._context);
-    this.stack.push(scene);
-    this._firePauseTransitions(wasPaused);
-    this._fireResumeTransitions(wasPaused);
-    if (scene.preload?.length && this.assetManager) {
-      return this.assetManager.loadAll(scene.preload, scene.onProgress?.bind(scene)).then(() => {
-        scene.onEnter?.();
-        if (old) {
-          this.bus?.emit("scene:replaced", {
-            oldScene: old,
-            newScene: scene
-          });
-        } else {
-          this.bus?.emit("scene:pushed", { scene });
+  async replace(scene, opts) {
+    this._assertNotMutating("replace");
+    await this._enqueue(async () => {
+      const transition = resolveTransition(opts?.transition, scene);
+      if (!transition) {
+        await this._replaceScene(scene);
+        return;
+      }
+      const old = this.active;
+      await this._pushScene(scene, true);
+      await this._runTransition("replace", transition, old, scene);
+      if (old) {
+        this._removeScene(old, true);
+      }
+      this.bus?.emit("scene:replaced", {
+        oldScene: old ?? scene,
+        newScene: scene
+      });
+    });
+  }
+  /**
+   * Pop every scene on the stack, top to bottom. Each receives onExit().
+   * Queued like push/pop/replace — runs after any in-flight transition.
+   * Use for "restart from menu"-style flows. Does not run transitions.
+   */
+  async popAll() {
+    this._assertNotMutating("popAll");
+    await this._enqueue(async () => {
+      this._withMutationSync(() => {
+        while (this.stack.length > 0) {
+          const scene = this.stack.pop();
+          if (!scene) break;
+          this._teardownScene(scene);
+          this.bus?.emit("scene:popped", { scene });
         }
       });
-    }
-    scene.onEnter?.();
-    if (old) {
-      this.bus?.emit("scene:replaced", { oldScene: old, newScene: scene });
-    } else {
-      this.bus?.emit("scene:pushed", { scene });
-    }
-    return Promise.resolve();
+    });
   }
-  /** Clear all scenes. Each receives onExit() from top to bottom. */
-  clear() {
-    while (this.stack.length > 0) {
-      const scene = this.stack.pop();
-      if (!scene) break;
-      scene.onExit?.();
-      scene._destroyAllEntities();
-      this.bus?.emit("scene:popped", { scene });
-    }
+  /**
+   * Run the full scene-enter lifecycle (beforeEnter hooks, preload, onEnter)
+   * for a scene that is NOT placed on the stack. Used by infrastructure
+   * plugins like DebugPlugin that render a scene off-stack.
+   * @internal
+   */
+  async _mountDetached(scene) {
+    await this._withMutation(async () => {
+      scene._setContext(this._context);
+      await this.hookRegistry?.runBeforeEnter(scene);
+      await this._preloadScene(scene);
+      scene.onEnter?.();
+    });
+  }
+  /**
+   * Run the scene-exit lifecycle (onExit, entity destruction, afterExit
+   * hooks, scoped-service clear) for a detached scene.
+   * @internal
+   */
+  _unmountDetached(scene) {
+    this._withMutationSync(() => {
+      this._teardownScene(scene);
+    });
+  }
+  /**
+   * Mark the manager destroyed and synchronously tear down every scene.
+   * Called by Engine.destroy(). Any queued async work short-circuits on
+   * resume; in-flight transitions' pending promises are resolved via
+   * _cleanupRun so they don't leak.
+   * @internal
+   */
+  _destroy() {
+    this._destroyed = true;
+    if (this._currentRun) {
+      this._cleanupRun(this._currentRun);
+    }
+    this._pendingChain = Promise.resolve();
+    this._visibilityListenerCleanup?.();
+    this._visibilityListenerCleanup = void 0;
+    this._visibilityPausedScenes.clear();
+    this._withMutationSync(() => {
+      while (this.stack.length > 0) {
+        const scene = this.stack.pop();
+        if (!scene) break;
+        this._teardownScene(scene);
+        this.bus?.emit("scene:popped", { scene });
+      }
+    });
   }
   /**
    * Flush destroy queues for all active scenes.
@@ -1898,21 +2357,217 @@ var SceneManager = class {
       scene._flushDestroyQueue();
     }
   }
+  /**
+   * Advance the active transition by `dt` ms. Called by Engine's earlyUpdate
+   * callback with raw (unscaled) wall-clock dt.
+   * @internal
+   */
+  _tickTransition(dt) {
+    const run = this._currentRun;
+    if (!run) return;
+    const remaining = run.transition.duration - run.elapsed;
+    const consume = Math.min(dt, remaining);
+    run.elapsed += consume;
+    this._safeTick(run, consume);
+    if (run.elapsed >= run.transition.duration) {
+      this._cleanupRun(run);
+    }
+  }
+  // ---- Private helpers ----
+  _enqueue(work) {
+    if (this._destroyed) return Promise.resolve(void 0);
+    const next = this._pendingChain.then(async () => {
+      if (this._destroyed) return void 0;
+      return work();
+    });
+    this._pendingChain = next.then(
+      () => void 0,
+      () => void 0
+    );
+    return next;
+  }
+  async _pushScene(scene, suppressEvent = false) {
+    const wasPaused = this._snapshotPauseStates();
+    await this._withMutation(async () => {
+      scene._setContext(this._context);
+      await this.hookRegistry?.runBeforeEnter(scene);
+      await this._preloadScene(scene);
+      this.stack.push(scene);
+      scene.onEnter?.();
+      this._firePauseTransitions(wasPaused);
+      if (!suppressEvent) {
+        this.bus?.emit("scene:pushed", { scene });
+      }
+    });
+  }
+  _popScene(suppressEvent = false) {
+    const wasPaused = this._snapshotPauseStates();
+    return this._withMutationSync(() => {
+      const removed = this.stack.pop();
+      if (!removed) return void 0;
+      this._teardownScene(removed);
+      this._fireResumeTransitions(wasPaused);
+      if (!suppressEvent) {
+        this.bus?.emit("scene:popped", { scene: removed });
+      }
+      return removed;
+    });
+  }
+  async _replaceScene(scene) {
+    const wasPaused = this._snapshotPauseStates();
+    await this._withMutation(async () => {
+      scene._setContext(this._context);
+      await this.hookRegistry?.runBeforeEnter(scene);
+      await this._preloadScene(scene);
+      const old = this.stack.pop();
+      if (old) this._teardownScene(old);
+      this.stack.push(scene);
+      scene.onEnter?.();
+      this._firePauseTransitions(wasPaused);
+      this._fireResumeTransitions(wasPaused);
+      this.bus?.emit("scene:replaced", {
+        oldScene: old ?? scene,
+        newScene: scene
+      });
+    });
+  }
+  _removeScene(scene, suppressEvent = false) {
+    this._withMutationSync(() => {
+      const idx = this.stack.indexOf(scene);
+      if (idx === -1) return;
+      const wasPaused = this._snapshotPauseStates();
+      this.stack.splice(idx, 1);
+      this._teardownScene(scene);
+      this._firePauseTransitions(wasPaused);
+      this._fireResumeTransitions(wasPaused);
+      if (!suppressEvent) {
+        this.bus?.emit("scene:popped", { scene });
+      }
+    });
+  }
+  async _preloadScene(scene) {
+    if (!scene.preload?.length || !this.assetManager) return;
+    await this.assetManager.loadAll(
+      scene.preload,
+      scene.onProgress?.bind(scene)
+    );
+  }
+  _teardownScene(scene) {
+    scene.onExit?.();
+    scene._destroyAllEntities();
+    this.hookRegistry?.runAfterExit(scene);
+    scene._clearScopedServices();
+    this._visibilityPausedScenes.delete(scene);
+  }
+  async _runTransition(kind, transition, fromScene, toScene) {
+    if (this._destroyed) return;
+    let resolveRun;
+    const promise = new Promise((resolve) => {
+      resolveRun = resolve;
+    });
+    const run = {
+      kind,
+      transition,
+      elapsed: 0,
+      fromScene,
+      toScene,
+      resolve: resolveRun
+    };
+    this._currentRun = run;
+    this.bus?.emit("scene:transition:started", {
+      kind,
+      fromScene,
+      toScene
+    });
+    this._safeCall(run, "begin");
+    if (!Number.isFinite(transition.duration) || transition.duration <= 0) {
+      this._cleanupRun(run);
+      return;
+    }
+    await promise;
+  }
+  _cleanupRun(run) {
+    if (this._currentRun !== run) return;
+    this._safeCall(run, "end");
+    this._currentRun = void 0;
+    this.bus?.emit("scene:transition:ended", {
+      kind: run.kind,
+      fromScene: run.fromScene,
+      toScene: run.toScene
+    });
+    run.resolve();
+  }
+  _safeTick(run, dt) {
+    try {
+      run.transition.tick(dt, this._makeContext(run));
+    } catch (err) {
+      this.logger?.warn(
+        "SceneManager",
+        `Transition tick error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  _safeCall(run, method) {
+    try {
+      run.transition[method]?.(this._makeContext(run));
+    } catch (err) {
+      this.logger?.warn(
+        "SceneManager",
+        `Transition ${method} error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  _makeContext(run) {
+    return {
+      elapsed: run.elapsed,
+      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 s of this.stack) {
-      const was = wasPaused.get(s) ?? false;
-      if (s.isPaused && !was) {
-        s.onPause?.();
+    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 s of this.stack) {
-      const was = wasPaused.get(s) ?? false;
-      if (!s.isPaused && was) {
-        s.onResume?.();
+    for (const scene of this.stack) {
+      const was = wasPaused.get(scene) ?? false;
+      if (!scene.isPaused && was) {
+        scene.onResume?.();
       }
     }
   }
@@ -2749,6 +3404,7 @@ var Engine = class {
   scheduler;
   errorBoundary;
   queryCache;
+  sceneHooks;
   /** The asset manager. */
   assets;
   plugins = /* @__PURE__ */ new Map();
@@ -2767,6 +3423,7 @@ var Engine = class {
     this.scheduler = new SystemScheduler();
     this.inspector = new Inspector(this);
     this.assets = new AssetManager();
+    this.sceneHooks = new SceneHookRegistry();
     this.scheduler.setErrorBoundary(this.errorBoundary);
     this.context.register(EngineKey, this);
     this.context.register(EventBusKey, this.events);
@@ -2778,11 +3435,13 @@ var Engine = class {
     this.context.register(InspectorKey, this.inspector);
     this.context.register(SystemSchedulerKey, this.scheduler);
     this.context.register(AssetManagerKey, this.assets);
+    this.context.register(SceneHookRegistryKey, this.sceneHooks);
     this.scenes._setContext(this.context);
     this.registerBuiltInSystems();
     this.loop.setCallbacks({
       earlyUpdate: /* @__PURE__ */ __name((dt) => {
         this.logger.setFrame(this.loop.frameCount);
+        this.scenes._tickTransition(dt);
         this.scheduler.run("earlyUpdate" /* EarlyUpdate */, dt);
       }, "earlyUpdate"),
       fixedUpdate: /* @__PURE__ */ __name((dt) => this.scheduler.run("fixedUpdate" /* FixedUpdate */, dt), "fixedUpdate"),
@@ -2795,6 +3454,14 @@ var Engine = class {
       }, "endOfFrame")
     });
   }
+  /**
+   * Register scene lifecycle hooks. The returned function unregisters the
+   * hooks. Infrastructure plugins (renderer, physics, debug) register hooks
+   * in their `install` or `onStart` to set up and tear down per-scene state.
+   */
+  registerSceneHooks(hooks) {
+    return this.sceneHooks.register(hooks);
+  }
   /** Register a plugin. Must be called before start(). */
   use(plugin) {
     if (this.started) {
@@ -2830,7 +3497,7 @@ var Engine = class {
       };
     }
     for (const plugin of sorted) {
-      plugin.onStart?.();
+      await plugin.onStart?.();
     }
     this.events.emit("engine:started", void 0);
   }
@@ -2838,7 +3505,7 @@ var Engine = class {
   destroy() {
     this.events.emit("engine:stopped", void 0);
     this.loop.stop();
-    this.scenes.clear();
+    this.scenes._destroy();
     const allSystems = this.scheduler.getAllSystems();
     for (let i = allSystems.length - 1; i >= 0; i--) {
       allSystems[i].onUnregister?.();
@@ -2912,6 +3579,11 @@ var Engine = class {
   }
 };
 
+// src/RendererAdapter.ts
+var RendererAdapterKey = new ServiceKey(
+  "rendererAdapter"
+);
+
 // src/test-utils.ts
 var _TestScene = class extends Scene {
   static {
@@ -2982,6 +3654,7 @@ var VERSION = "0.0.0";
   Inspector,
   InspectorKey,
   KeyframeAnimator,
+  LoadingScene,
   LogLevel,
   Logger,
   LoggerKey,
@@ -2995,8 +3668,11 @@ var VERSION = "0.0.0";
   QueryCache,
   QueryCacheKey,
   QueryResult,
+  RendererAdapterKey,
   SERIALIZABLE_KEY,
   Scene,
+  SceneHookRegistry,
+  SceneHookRegistryKey,
   SceneManager,
   SceneManagerKey,
   Sequence,
@@ -3029,6 +3705,7 @@ var VERSION = "0.0.0";
   getSerializableType,
   interpolate,
   isSerializable,
+  resolveTransition,
   serializable,
   trait
 });