@yagejs/core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -212,12 +212,20 @@ declare function defineEvent<T = void>(name: string): EventToken<T>;
 /**
  * A reusable entity template. Blueprints define how to assemble
  * an entity from components, given optional parameters.
+ *
+ * @deprecated Prefer Entity subclasses with `setup()` for entity types.
+ *   Blueprints still work for parametric factories but are no longer the
+ *   recommended pattern for new code.
  */
 interface Blueprint<P = void> {
     readonly name: string;
     build(entity: Entity, params: P): void;
 }
-/** Create a blueprint from a name and a build function. */
+/**
+ * Create a blueprint from a name and a build function.
+ *
+ * @deprecated Prefer Entity subclasses with `setup()` for entity types.
+ */
 declare function defineBlueprint<P = void>(name: string, build: (entity: Entity, params: P) => void): Blueprint<P>;
 
 /**
@@ -838,11 +846,31 @@ declare class SceneManager {
     private _pendingChain;
     private _mutationDepth;
     private _destroyed;
+    private _autoPauseOnBlur;
+    private _isBlurred;
+    private readonly _visibilityPausedScenes;
+    private _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(): boolean;
+    set autoPauseOnBlur(value: boolean);
     /**
      * Set the engine context.
      * @internal
      */
     _setContext(context: EngineContext): void;
+    /**
+     * React to a visibility change. Parameterised on `hidden` so unit tests can
+     * drive it without a real `document`.
+     * @internal
+     */
+    _handleVisibilityChange(hidden: boolean): void;
+    private _applyBlurPause;
+    private _restoreBlurPause;
     /** The topmost (active) scene. */
     get active(): Scene | undefined;
     /** All scenes in the stack, bottom to top. */
@@ -1377,16 +1405,32 @@ declare class Vec2 implements Vec2Like {
     static distance(a: Vec2Like, b: Vec2Like): number;
     /** Linear interpolation between two vectors. */
     static lerp(a: Vec2Like, b: Vec2Like, t: number): Vec2;
+    /** Move current toward target by at most maxDelta without overshooting. */
+    static moveTowards(current: Vec2Like, target: Vec2Like, maxDelta: number): Vec2;
 }
 
+interface SmoothDampResult {
+    /** Smoothed value after this step. */
+    readonly value: number;
+    /** Velocity to pass into the next smoothDamp step. */
+    readonly velocity: number;
+}
 /** Common math utility functions. */
 declare const MathUtils: {
     /** Linear interpolation between a and b. */
     readonly lerp: (a: number, b: number, t: number) => number;
+    /** Return the clamped interpolation factor that produces v between a and b. */
+    readonly inverseLerp: (a: number, b: number, v: number) => number;
+    /** Interpolate between angles in radians along the shortest path. */
+    readonly lerpAngle: (a: number, b: number, t: number) => number;
+    /** Signed shortest angular delta from a to b, in radians. */
+    readonly shortestAngleBetween: (a: number, b: number) => number;
     /** Clamp a value between min and max. */
     readonly clamp: (value: number, min: number, max: number) => number;
     /** Remap a value from one range to another. */
     readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number;
+    /** Bounce t between 0 and length. */
+    readonly pingPong: (t: number, length: number) => number;
     /** Random float in [min, max). */
     readonly randomRange: (min: number, max: number) => number;
     /** Random integer in [min, max] (inclusive). */
@@ -1397,6 +1441,11 @@ declare const MathUtils: {
     readonly radToDeg: (radians: number) => number;
     /** Move current toward target by at most step. */
     readonly approach: (current: number, target: number, step: number) => number;
+    /**
+     * Smoothly damp current toward target without overshooting.
+     * Pass the returned velocity back into the next call.
+     */
+    readonly smoothDamp: (current: number, target: number, velocity: number, smoothTime: number, deltaTime: number, maxSpeed?: number) => SmoothDampResult;
     /** Wrap value into the range [min, max). */
     readonly wrap: (value: number, min: number, max: number) => number;
 };
@@ -1829,6 +1878,36 @@ declare class TimerEntity extends Entity {
     cancel(tag?: string): void;
 }
 
+/**
+ * Cross-package contract for "something that owns a canvas and can map
+ * canvas-relative CSS pixels into virtual-space pixels".
+ *
+ * Implemented by `@yagejs/renderer`'s `RendererPlugin` and consumed by
+ * `@yagejs/input` for pointer-event targeting and coordinate mapping under
+ * responsive fit. Foreign renderers can implement this interface and register
+ * under `RendererAdapterKey` to integrate with the input plugin without
+ * importing `@yagejs/renderer`.
+ */
+interface RendererAdapter {
+    readonly canvas: HTMLCanvasElement;
+    /**
+     * Convert CSS pixels relative to the canvas into virtual-space pixels.
+     * Optional — when absent, consumers fall back to raw CSS pixels (correct
+     * only when canvas CSS size equals virtual size).
+     */
+    canvasToVirtual?(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Well-known service key for the current renderer's pointer-input adapter.
+ * The canonical `@yagejs/renderer` plugin registers itself here; consumers
+ * (notably `@yagejs/input`) resolve this key to auto-wire canvas targeting
+ * and coordinate mapping.
+ */
+declare const RendererAdapterKey: ServiceKey<RendererAdapter>;
+
 /** Create a fully wired Engine for integration tests. */
 declare function createTestEngine(config?: EngineConfig): Promise<Engine>;
 /** Create a lightweight mock scene with EngineContext for unit tests. */
@@ -1847,4 +1926,4 @@ declare function advanceFrames(engine: Engine, n: number, dtMs?: number): void;
 
 declare const VERSION = "0.0.0";
 
-export { AssetHandle, type AssetLoader, AssetManager, AssetManagerKey, type Blueprint, Component, type ComponentClass, ComponentFixedUpdateSystem, ComponentUpdateSystem, type EasingFunction, Engine, type EngineConfig, EngineContext, type EngineEvents, EngineKey, type EngineSnapshot, Entity, type EntityCallbacks, type EntityFilter, type EntitySnapshot, ErrorBoundary, ErrorBoundaryKey, type ErrorSnapshot, EventBus, EventBusKey, type EventMap, EventToken, GameLoop, type GameLoopCallbacks, type GameLoopConfig, GameLoopKey, Inspector, InspectorKey, type Interpolatable, type Keyframe, type KeyframeAnimationDef, KeyframeAnimator, type KeyframeTrackOptions, LoadingScene, type LogEntry, LogLevel, Logger, type LoggerConfig, LoggerKey, MathUtils, Phase, type Plugin, Process, ProcessComponent, type ProcessOptions, ProcessSlot, type ProcessSlotConfig, ProcessSystem, ProcessSystemKey, QueryCache, QueryCacheKey, QueryResult, SERIALIZABLE_KEY, Scene, SceneHookRegistry, SceneHookRegistryKey, type SceneHooks, SceneManager, SceneManagerKey, type SceneSnapshot, type SceneTransition, type SceneTransitionContext, type SceneTransitionKind, type SceneTransitionOptions, Sequence, SerializableRegistry, ServiceKey, type ServiceKeyOptions, type ServiceScope, type SnapshotResolver, System, SystemScheduler, SystemSchedulerKey, type SystemSnapshot, TimerEntity, TraitToken, Transform, type TransformData, Tween, VERSION, Vec2, type Vec2Like, _resetEntityIdCounter, advanceFrames, createKeyframeTrack, createMockEntity, createMockScene, createTestEngine, defineBlueprint, defineEvent, defineTrait, easeInOutQuad, easeInQuad, easeLinear, easeOutBounce, easeOutQuad, filterEntities, getSerializableType, interpolate, isSerializable, resolveTransition, serializable, trait };
+export { AssetHandle, type AssetLoader, AssetManager, AssetManagerKey, type Blueprint, Component, type ComponentClass, ComponentFixedUpdateSystem, ComponentUpdateSystem, type EasingFunction, Engine, type EngineConfig, EngineContext, type EngineEvents, EngineKey, type EngineSnapshot, Entity, type EntityCallbacks, type EntityFilter, type EntitySnapshot, ErrorBoundary, ErrorBoundaryKey, type ErrorSnapshot, EventBus, EventBusKey, type EventMap, EventToken, GameLoop, type GameLoopCallbacks, type GameLoopConfig, GameLoopKey, Inspector, InspectorKey, type Interpolatable, type Keyframe, type KeyframeAnimationDef, KeyframeAnimator, type KeyframeTrackOptions, LoadingScene, type LogEntry, LogLevel, Logger, type LoggerConfig, LoggerKey, MathUtils, Phase, type Plugin, Process, ProcessComponent, type ProcessOptions, ProcessSlot, type ProcessSlotConfig, ProcessSystem, ProcessSystemKey, QueryCache, QueryCacheKey, QueryResult, type RendererAdapter, RendererAdapterKey, SERIALIZABLE_KEY, Scene, SceneHookRegistry, SceneHookRegistryKey, type SceneHooks, SceneManager, SceneManagerKey, type SceneSnapshot, type SceneTransition, type SceneTransitionContext, type SceneTransitionKind, type SceneTransitionOptions, Sequence, SerializableRegistry, ServiceKey, type ServiceKeyOptions, type ServiceScope, type SmoothDampResult, type SnapshotResolver, System, SystemScheduler, SystemSchedulerKey, type SystemSnapshot, TimerEntity, TraitToken, Transform, type TransformData, Tween, VERSION, Vec2, type Vec2Like, _resetEntityIdCounter, advanceFrames, createKeyframeTrack, createMockEntity, createMockScene, createTestEngine, defineBlueprint, defineEvent, defineTrait, easeInOutQuad, easeInQuad, easeLinear, easeOutBounce, easeOutQuad, filterEntities, getSerializableType, interpolate, isSerializable, resolveTransition, serializable, trait };

package/dist/index.d.ts

@@ -212,12 +212,20 @@ declare function defineEvent<T = void>(name: string): EventToken<T>;
 /**
  * A reusable entity template. Blueprints define how to assemble
  * an entity from components, given optional parameters.
+ *
+ * @deprecated Prefer Entity subclasses with `setup()` for entity types.
+ *   Blueprints still work for parametric factories but are no longer the
+ *   recommended pattern for new code.
  */
 interface Blueprint<P = void> {
     readonly name: string;
     build(entity: Entity, params: P): void;
 }
-/** Create a blueprint from a name and a build function. */
+/**
+ * Create a blueprint from a name and a build function.
+ *
+ * @deprecated Prefer Entity subclasses with `setup()` for entity types.
+ */
 declare function defineBlueprint<P = void>(name: string, build: (entity: Entity, params: P) => void): Blueprint<P>;
 
 /**
@@ -838,11 +846,31 @@ declare class SceneManager {
     private _pendingChain;
     private _mutationDepth;
     private _destroyed;
+    private _autoPauseOnBlur;
+    private _isBlurred;
+    private readonly _visibilityPausedScenes;
+    private _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(): boolean;
+    set autoPauseOnBlur(value: boolean);
     /**
      * Set the engine context.
      * @internal
      */
     _setContext(context: EngineContext): void;
+    /**
+     * React to a visibility change. Parameterised on `hidden` so unit tests can
+     * drive it without a real `document`.
+     * @internal
+     */
+    _handleVisibilityChange(hidden: boolean): void;
+    private _applyBlurPause;
+    private _restoreBlurPause;
     /** The topmost (active) scene. */
     get active(): Scene | undefined;
     /** All scenes in the stack, bottom to top. */
@@ -1377,16 +1405,32 @@ declare class Vec2 implements Vec2Like {
     static distance(a: Vec2Like, b: Vec2Like): number;
     /** Linear interpolation between two vectors. */
     static lerp(a: Vec2Like, b: Vec2Like, t: number): Vec2;
+    /** Move current toward target by at most maxDelta without overshooting. */
+    static moveTowards(current: Vec2Like, target: Vec2Like, maxDelta: number): Vec2;
 }
 
+interface SmoothDampResult {
+    /** Smoothed value after this step. */
+    readonly value: number;
+    /** Velocity to pass into the next smoothDamp step. */
+    readonly velocity: number;
+}
 /** Common math utility functions. */
 declare const MathUtils: {
     /** Linear interpolation between a and b. */
     readonly lerp: (a: number, b: number, t: number) => number;
+    /** Return the clamped interpolation factor that produces v between a and b. */
+    readonly inverseLerp: (a: number, b: number, v: number) => number;
+    /** Interpolate between angles in radians along the shortest path. */
+    readonly lerpAngle: (a: number, b: number, t: number) => number;
+    /** Signed shortest angular delta from a to b, in radians. */
+    readonly shortestAngleBetween: (a: number, b: number) => number;
     /** Clamp a value between min and max. */
     readonly clamp: (value: number, min: number, max: number) => number;
     /** Remap a value from one range to another. */
     readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number;
+    /** Bounce t between 0 and length. */
+    readonly pingPong: (t: number, length: number) => number;
     /** Random float in [min, max). */
     readonly randomRange: (min: number, max: number) => number;
     /** Random integer in [min, max] (inclusive). */
@@ -1397,6 +1441,11 @@ declare const MathUtils: {
     readonly radToDeg: (radians: number) => number;
     /** Move current toward target by at most step. */
     readonly approach: (current: number, target: number, step: number) => number;
+    /**
+     * Smoothly damp current toward target without overshooting.
+     * Pass the returned velocity back into the next call.
+     */
+    readonly smoothDamp: (current: number, target: number, velocity: number, smoothTime: number, deltaTime: number, maxSpeed?: number) => SmoothDampResult;
     /** Wrap value into the range [min, max). */
     readonly wrap: (value: number, min: number, max: number) => number;
 };
@@ -1829,6 +1878,36 @@ declare class TimerEntity extends Entity {
     cancel(tag?: string): void;
 }
 
+/**
+ * Cross-package contract for "something that owns a canvas and can map
+ * canvas-relative CSS pixels into virtual-space pixels".
+ *
+ * Implemented by `@yagejs/renderer`'s `RendererPlugin` and consumed by
+ * `@yagejs/input` for pointer-event targeting and coordinate mapping under
+ * responsive fit. Foreign renderers can implement this interface and register
+ * under `RendererAdapterKey` to integrate with the input plugin without
+ * importing `@yagejs/renderer`.
+ */
+interface RendererAdapter {
+    readonly canvas: HTMLCanvasElement;
+    /**
+     * Convert CSS pixels relative to the canvas into virtual-space pixels.
+     * Optional — when absent, consumers fall back to raw CSS pixels (correct
+     * only when canvas CSS size equals virtual size).
+     */
+    canvasToVirtual?(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Well-known service key for the current renderer's pointer-input adapter.
+ * The canonical `@yagejs/renderer` plugin registers itself here; consumers
+ * (notably `@yagejs/input`) resolve this key to auto-wire canvas targeting
+ * and coordinate mapping.
+ */
+declare const RendererAdapterKey: ServiceKey<RendererAdapter>;
+
 /** Create a fully wired Engine for integration tests. */
 declare function createTestEngine(config?: EngineConfig): Promise<Engine>;
 /** Create a lightweight mock scene with EngineContext for unit tests. */
@@ -1847,4 +1926,4 @@ declare function advanceFrames(engine: Engine, n: number, dtMs?: number): void;
 
 declare const VERSION = "0.0.0";
 
-export { AssetHandle, type AssetLoader, AssetManager, AssetManagerKey, type Blueprint, Component, type ComponentClass, ComponentFixedUpdateSystem, ComponentUpdateSystem, type EasingFunction, Engine, type EngineConfig, EngineContext, type EngineEvents, EngineKey, type EngineSnapshot, Entity, type EntityCallbacks, type EntityFilter, type EntitySnapshot, ErrorBoundary, ErrorBoundaryKey, type ErrorSnapshot, EventBus, EventBusKey, type EventMap, EventToken, GameLoop, type GameLoopCallbacks, type GameLoopConfig, GameLoopKey, Inspector, InspectorKey, type Interpolatable, type Keyframe, type KeyframeAnimationDef, KeyframeAnimator, type KeyframeTrackOptions, LoadingScene, type LogEntry, LogLevel, Logger, type LoggerConfig, LoggerKey, MathUtils, Phase, type Plugin, Process, ProcessComponent, type ProcessOptions, ProcessSlot, type ProcessSlotConfig, ProcessSystem, ProcessSystemKey, QueryCache, QueryCacheKey, QueryResult, SERIALIZABLE_KEY, Scene, SceneHookRegistry, SceneHookRegistryKey, type SceneHooks, SceneManager, SceneManagerKey, type SceneSnapshot, type SceneTransition, type SceneTransitionContext, type SceneTransitionKind, type SceneTransitionOptions, Sequence, SerializableRegistry, ServiceKey, type ServiceKeyOptions, type ServiceScope, type SnapshotResolver, System, SystemScheduler, SystemSchedulerKey, type SystemSnapshot, TimerEntity, TraitToken, Transform, type TransformData, Tween, VERSION, Vec2, type Vec2Like, _resetEntityIdCounter, advanceFrames, createKeyframeTrack, createMockEntity, createMockScene, createTestEngine, defineBlueprint, defineEvent, defineTrait, easeInOutQuad, easeInQuad, easeLinear, easeOutBounce, easeOutQuad, filterEntities, getSerializableType, interpolate, isSerializable, resolveTransition, serializable, trait };
+export { AssetHandle, type AssetLoader, AssetManager, AssetManagerKey, type Blueprint, Component, type ComponentClass, ComponentFixedUpdateSystem, ComponentUpdateSystem, type EasingFunction, Engine, type EngineConfig, EngineContext, type EngineEvents, EngineKey, type EngineSnapshot, Entity, type EntityCallbacks, type EntityFilter, type EntitySnapshot, ErrorBoundary, ErrorBoundaryKey, type ErrorSnapshot, EventBus, EventBusKey, type EventMap, EventToken, GameLoop, type GameLoopCallbacks, type GameLoopConfig, GameLoopKey, Inspector, InspectorKey, type Interpolatable, type Keyframe, type KeyframeAnimationDef, KeyframeAnimator, type KeyframeTrackOptions, LoadingScene, type LogEntry, LogLevel, Logger, type LoggerConfig, LoggerKey, MathUtils, Phase, type Plugin, Process, ProcessComponent, type ProcessOptions, ProcessSlot, type ProcessSlotConfig, ProcessSystem, ProcessSystemKey, QueryCache, QueryCacheKey, QueryResult, type RendererAdapter, RendererAdapterKey, SERIALIZABLE_KEY, Scene, SceneHookRegistry, SceneHookRegistryKey, type SceneHooks, SceneManager, SceneManagerKey, type SceneSnapshot, type SceneTransition, type SceneTransitionContext, type SceneTransitionKind, type SceneTransitionOptions, Sequence, SerializableRegistry, ServiceKey, type ServiceKeyOptions, type ServiceScope, type SmoothDampResult, type SnapshotResolver, System, SystemScheduler, SystemSchedulerKey, type SystemSnapshot, TimerEntity, TraitToken, Transform, type TransformData, Tween, VERSION, Vec2, type Vec2Like, _resetEntityIdCounter, advanceFrames, createKeyframeTrack, createMockEntity, createMockScene, createTestEngine, defineBlueprint, defineEvent, defineTrait, easeInOutQuad, easeInQuad, easeLinear, easeOutBounce, easeOutQuad, filterEntities, getSerializableType, interpolate, isSerializable, resolveTransition, serializable, trait };

package/dist/index.js

@@ -170,14 +170,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));
@@ -187,6 +225,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);
@@ -210,6 +254,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;
@@ -1974,6 +2046,29 @@ var SceneManager = class {
   _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
@@ -1984,6 +2079,40 @@ var SceneManager = class {
     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() {
@@ -2110,6 +2239,9 @@ var SceneManager = class {
       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();
@@ -2229,6 +2361,7 @@ var SceneManager = class {
     scene._destroyAllEntities();
     this.hookRegistry?.runAfterExit(scene);
     scene._clearScopedServices();
+    this._visibilityPausedScenes.delete(scene);
   }
   async _runTransition(kind, transition, fromScene, toScene) {
     if (this._destroyed) return;
@@ -3350,6 +3483,11 @@ var Engine = class {
   }
 };
 
+// src/RendererAdapter.ts
+var RendererAdapterKey = new ServiceKey(
+  "rendererAdapter"
+);
+
 // src/test-utils.ts
 var _TestScene = class extends Scene {
   static {
@@ -3433,6 +3571,7 @@ export {
   QueryCache,
   QueryCacheKey,
   QueryResult,
+  RendererAdapterKey,
   SERIALIZABLE_KEY,
   Scene,
   SceneHookRegistry,