@yagejs/core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -209,6 +209,25 @@ declare class EventToken<T = void> {
 /** Create a typed event token. */
 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.
+ *
+ * @deprecated Prefer Entity subclasses with `setup()` for entity types.
+ */
+declare function defineBlueprint<P = void>(name: string, build: (entity: Entity, params: P) => void): Blueprint<P>;
+
 /**
  * Passed to `afterRestore` hooks so user code can resolve entity references
  * that were captured as IDs at save time.
@@ -330,8 +349,20 @@ declare class Entity {
     private _parent;
     private _children;
     constructor(name?: string, tags?: Iterable<string>);
-    /** The scene this entity belongs to, or null. */
-    get scene(): Scene | 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(): Scene;
+    /** The scene this entity belongs to, or `null` if detached. */
+    get tryScene(): Scene | null;
     /** True if destroy() has been called. */
     get isDestroyed(): boolean;
     /** The parent entity, or null if this is a root entity. */
@@ -340,6 +371,28 @@ declare class Entity {
     get children(): ReadonlyMap<string, Entity>;
     /** Add a named child entity. Auto-adds to parent's scene if not already in one. */
     addChild(name: string, child: Entity): void;
+    /**
+     * Spawn a new entity in this entity's scene and add it as a named child.
+     * Combines `scene.spawn(...)` + `this.addChild(name, ...)` in one call —
+     * the idiomatic way to compose entity trees (logical root + visual body
+     * + UI sibling + ...).
+     *
+     * Mirrors the overload shape of `Scene.spawn`: pass an Entity subclass
+     * (with optional setup params), a `Blueprint`, or omit for an anonymous
+     * base Entity.
+     *
+     * ```ts
+     * this.spawnChild("body", EnemyBody, { color: 0xff6b6b });
+     * this.spawnChild("hp", EnemyHealthBar);
+     * ```
+     */
+    spawnChild(name: string): Entity;
+    spawnChild<E extends Entity>(name: string, Class: new () => E): E;
+    spawnChild<E extends Entity, P>(name: string, Class: new () => E & {
+        setup(params: P): void;
+    }, params: P): E;
+    spawnChild<P>(name: string, blueprint: Blueprint<P>, params: P): Entity;
+    spawnChild(name: string, blueprint: Blueprint<void>): Entity;
     /** Remove a named child. Returns the detached entity. */
     removeChild(name: string): Entity;
     /** Get a child by name. Throws if not found. */
@@ -390,16 +443,45 @@ declare class Entity {
     _setScene(scene: Scene | null, callbacks: EntityCallbacks | null): void;
 }
 
+/** Which scene op triggered this transition. */
+type SceneTransitionKind = "push" | "pop" | "replace";
+/** Context passed to a transition each frame. */
+interface SceneTransitionContext {
+    /** Wall-clock ms elapsed since begin(). */
+    readonly elapsed: number;
+    readonly kind: SceneTransitionKind;
+    readonly engineContext: EngineContext;
+    /** The scene being left or removed (undefined on first push). */
+    readonly fromScene: Scene | undefined;
+    /** The scene being entered or revealed (undefined on last pop). */
+    readonly toScene: Scene | undefined;
+}
 /**
- * A reusable entity template. Blueprints define how to assemble
- * an entity from components, given optional parameters.
+ * A scene transition animates the handoff between scene stack states.
+ *
+ * `SceneManager` keeps both the outgoing and incoming scenes on the stack
+ * for the transition's duration, then removes the outgoing scene afterward.
+ * Transitions use raw wall-clock dt and ignore engine + scene `timeScale`.
  */
-interface Blueprint<P = void> {
-    readonly name: string;
-    build(entity: Entity, params: P): void;
+interface SceneTransition {
+    /** Total duration in wall-clock ms. */
+    readonly duration: number;
+    /** Called once when the transition starts. Set up resources here. */
+    begin?(ctx: SceneTransitionContext): void;
+    /** Called each frame with frame dt in ms. `ctx.elapsed` is clamped to `duration`. */
+    tick(dt: number, ctx: SceneTransitionContext): void;
+    /** Called when the transition ends. Tear down resources here. */
+    end?(ctx: SceneTransitionContext): void;
 }
-/** Create a blueprint from a name and a build function. */
-declare function defineBlueprint<P = void>(name: string, build: (entity: Entity, params: P) => void): Blueprint<P>;
+/** Options accepted by `SceneManager.push/pop/replace`. */
+interface SceneTransitionOptions {
+    transition?: SceneTransition;
+}
+/**
+ * Resolve the effective transition for a scene op.
+ * Precedence: call-site option → destination's `defaultTransition` → undefined.
+ */
+declare function resolveTransition(callSite: SceneTransition | undefined, destination: Scene | undefined): SceneTransition | undefined;
 
 /** Filter criteria for entity queries. All fields are AND'd together. */
 interface EntityFilter {
@@ -428,6 +510,8 @@ declare abstract class Scene {
     readonly transparentBelow: boolean;
     /** Asset handles to load before onEnter(). Override in subclasses. */
     readonly preload?: readonly AssetHandle<unknown>[];
+    /** Default transition used when this scene is the destination of a push/pop/replace. */
+    readonly defaultTransition?: SceneTransition;
     /** Manual pause flag. Set by game code to pause this scene regardless of stack position. */
     paused: boolean;
     /** Time scale multiplier for this scene. 1.0 = normal, 0.5 = half speed. Default: 1. */
@@ -439,10 +523,13 @@ declare abstract class Scene {
     private queryCache;
     private bus;
     private _entityEventHandlers?;
+    private _scopedServices?;
     /** Access the EngineContext. */
     get context(): EngineContext;
     /** Whether this scene is effectively paused (manual pause or paused by stack). */
     get isPaused(): boolean;
+    /** Whether a scene transition is currently running. */
+    get isTransitioning(): boolean;
     /** Convenience accessor for the AssetManager. */
     get assets(): AssetManager;
     /**
@@ -507,6 +594,24 @@ declare abstract class Scene {
     serialize?(): unknown;
     /** Called after entities are restored during save/load. Rebuild non-serializable state here. */
     afterRestore?(data: unknown, resolve: SnapshotResolver): void;
+    /**
+     * 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<T>(key: ServiceKey<T>, value: T): void;
+    /**
+     * Resolve a scene-scoped service, or `undefined` if none was registered.
+     * @internal
+     */
+    _resolveScoped<T>(key: ServiceKey<T>): T | undefined;
+    /**
+     * Clear all scene-scoped services. Called by the SceneManager after
+     * `afterExit` hooks run, so plugin cleanup code still sees scoped state.
+     * @internal
+     */
+    _clearScopedServices(): void;
     /**
      * Set the engine context. Called by SceneManager when the scene is pushed.
      * @internal
@@ -544,7 +649,8 @@ declare abstract class Component {
     private _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(): Scene;
     /**
@@ -552,12 +658,19 @@ declare abstract class Component {
      * Throws if the entity is not in a scene.
      */
     get context(): EngineContext;
-    /** 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.
+     */
     protected use<T>(key: ServiceKey<T>): T;
+    private _warnScopedFallback;
     /**
      * 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.
      */
@@ -727,38 +840,114 @@ declare class SceneManager {
     private _context;
     private bus;
     private assetManager;
+    private hookRegistry;
+    private logger;
+    private _currentRun;
+    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. */
     get all(): readonly Scene[];
     /** All non-paused scenes in the stack, bottom to top. */
     get activeScenes(): readonly Scene[];
+    /** Whether a scene transition is currently running. */
+    get isTransitioning(): boolean;
     /**
      * 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: Scene): Promise<void>;
+    push(scene: Scene, opts?: SceneTransitionOptions): Promise<void>;
     /** Pop the top scene. Scenes below may receive onResume(). */
-    pop(): Scene | undefined;
+    pop(opts?: SceneTransitionOptions): Promise<Scene | undefined>;
     /**
-     * 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: Scene): Promise<void>;
-    /** Clear all scenes. Each receives onExit() from top to bottom. */
-    clear(): void;
+    replace(scene: Scene, opts?: SceneTransitionOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    popAll(): Promise<void>;
+    /**
+     * 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
+     */
+    _mountDetached(scene: Scene): Promise<void>;
+    /**
+     * Run the scene-exit lifecycle (onExit, entity destruction, afterExit
+     * hooks, scoped-service clear) for a detached scene.
+     * @internal
+     */
+    _unmountDetached(scene: Scene): void;
+    /**
+     * 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(): void;
     /**
      * Flush destroy queues for all active scenes.
      * Called by the engine during endOfFrame.
      * @internal
      */
     _flushDestroyQueues(): void;
+    /**
+     * Advance the active transition by `dt` ms. Called by Engine's earlyUpdate
+     * callback with raw (unscaled) wall-clock dt.
+     * @internal
+     */
+    _tickTransition(dt: number): void;
+    private _enqueue;
+    private _pushScene;
+    private _popScene;
+    private _replaceScene;
+    private _removeScene;
+    private _preloadScene;
+    private _teardownScene;
+    private _runTransition;
+    private _cleanupRun;
+    private _safeTick;
+    private _safeCall;
+    private _makeContext;
+    private _snapshotPauseStates;
+    private _assertNotMutating;
+    private _withMutation;
+    private _withMutationSync;
     /** Fire onPause() for scenes that transitioned from not-paused to paused. */
     private _firePauseTransitions;
     /** Fire onResume() for scenes that transitioned from paused to not-paused. */
@@ -883,6 +1072,23 @@ interface EngineEvents {
         oldScene: SceneRef;
         newScene: SceneRef;
     };
+    "scene:transition:started": {
+        kind: SceneTransitionKind;
+        fromScene: SceneRef | undefined;
+        toScene: SceneRef | undefined;
+    };
+    "scene:transition:ended": {
+        kind: SceneTransitionKind;
+        fromScene: SceneRef | undefined;
+        toScene: SceneRef | undefined;
+    };
+    "scene:loading:progress": {
+        scene: Scene;
+        ratio: number;
+    };
+    "scene:loading:done": {
+        scene: Scene;
+    };
     "engine:started": undefined;
     "engine:stopped": undefined;
 }
@@ -899,6 +1105,39 @@ declare class EventBus<E = EventMap> {
     clear(event?: keyof E): void;
 }
 
+/**
+ * Plugin hooks invoked by the SceneManager at scene lifecycle points.
+ * Plugins register hooks via `engine.registerSceneHooks(hooks)` to set up or
+ * tear down per-scene state (e.g. render containers, physics worlds).
+ */
+interface SceneHooks {
+    /**
+     * Runs after the scene's context is bound but before preload / `onEnter`.
+     * Awaited serially so scoped services registered here are ready when the
+     * scene's own code runs. Fires on `push`, `replace`, and `_mountDetached`.
+     */
+    beforeEnter?(scene: Scene): void | Promise<void>;
+    /**
+     * Runs after `onExit` + `_destroyAllEntities` and before the scene's
+     * scoped-service map is cleared. Fires on `pop`, `replace`, `clear`, and
+     * `_unmountDetached`.
+     */
+    afterExit?(scene: Scene): void;
+}
+/**
+ * Registry of scene hooks. Held by the engine, consumed by the SceneManager.
+ * @internal
+ */
+declare class SceneHookRegistry {
+    private readonly hooks;
+    register(hooks: SceneHooks): () => void;
+    /** Run all `beforeEnter` hooks serially. */
+    runBeforeEnter(scene: Scene): Promise<void>;
+    runAfterExit(scene: Scene): void;
+}
+/** DI key for the scene-hook registry. @internal */
+declare const SceneHookRegistryKey: ServiceKey<SceneHookRegistry>;
+
 /** Engine configuration. */
 interface EngineConfig {
     /** Enable debug mode (Inspector API, debug logging). */
@@ -930,6 +1169,7 @@ declare class Engine {
     private readonly scheduler;
     private readonly errorBoundary;
     private readonly queryCache;
+    private readonly sceneHooks;
     /** The asset manager. */
     readonly assets: AssetManager;
     private readonly plugins;
@@ -937,6 +1177,12 @@ declare class Engine {
     private started;
     private readonly debug;
     constructor(config?: EngineConfig);
+    /**
+     * 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: SceneHooks): () => void;
     /** Register a plugin. Must be called before start(). */
     use(plugin: Plugin): this;
     /** Start the engine. Installs plugins in topological order, starts the game loop. */
@@ -951,13 +1197,27 @@ declare class Engine {
     private topologicalSort;
 }
 
+/** The resolution scope for a service. */
+type ServiceScope = "engine" | "scene";
+/** Options passed to `new ServiceKey(id, options)`. */
+interface ServiceKeyOptions {
+    /**
+     * Declared scope. `"scene"` keys are expected to be registered per-scene
+     * via a `beforeEnter` hook; `Component.use` will check scene scope first
+     * and warn if it falls back to engine scope.
+     * Default: `"engine"`.
+     */
+    scope?: ServiceScope;
+}
 /** A typed key for service registration and resolution. */
 declare class ServiceKey<T> {
     /** Unique string identifier for this service. */
     readonly id: string;
+    /** Declared scope (engine or scene). Defaults to `"engine"`. */
+    readonly scope: ServiceScope;
     constructor(
     /** Unique string identifier for this service. */
-    id: string);
+    id: string, options?: ServiceKeyOptions);
     /** Phantom field to preserve the generic type. */
     readonly _type: T;
 }
@@ -1072,7 +1332,7 @@ interface Plugin {
     /** Register systems with the scheduler. Called after install. */
     registerSystems?(scheduler: SystemScheduler): void;
     /** Called after all plugins are installed and the engine has started. */
-    onStart?(): void;
+    onStart?(): void | Promise<void>;
     /** Called when the engine is destroyed. */
     onDestroy?(): void;
 }
@@ -1145,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). */
@@ -1165,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;
 };
@@ -1265,6 +1546,112 @@ declare class ComponentUpdateSystem extends BaseComponentUpdateSystem {
     update(dt: number): void;
 }
 
+/**
+ * Base class for a progress-bar style loading screen.
+ *
+ * Preloads the target scene's assets through the `AssetManager`, exposes
+ * `progress` and emits `scene:loading:progress` / `scene:loading:done` on
+ * the engine event bus, enforces `minDuration` to prevent flicker on cached
+ * loads, then replaces itself with `target` — optionally through a
+ * transition.
+ *
+ * LoadingScene owns orchestration only. It does not render anything. To show
+ * a progress UI, spawn an entity that subscribes to the loading events (the
+ * canonical default is `LoadingSceneProgressBar` in `@yagejs/ui`, or any
+ * custom component). The loading scene is a normal Scene, so you can use
+ * `onEnter` to spawn whatever you want.
+ *
+ * ```ts
+ * class Boot extends LoadingScene {
+ *   readonly target = new GameScene();
+ *   readonly minDuration = 500;
+ *   readonly transition = fade({ duration: 300 });
+ *   override onEnter() {
+ *     this.spawn(LoadingSceneProgressBar);
+ *     this.startLoading();
+ *   }
+ * }
+ *
+ * await engine.scenes.replace(new Boot());
+ * ```
+ *
+ * Set `autoContinue = false` to gate the handoff behind a `continue()` call
+ * — useful for "press any key to continue" flows. `scene:loading:done`
+ * still fires so UI can react (show a prompt), and whoever eventually
+ * calls `this.continue()` triggers the transition.
+ */
+declare abstract class LoadingScene extends Scene {
+    readonly name: string;
+    /**
+     * Scene to load and transition to. Accepts an instance or a factory —
+     * use a factory when target construction should be deferred until
+     * loading starts (heavy constructors, side effects). The factory runs
+     * before `assets.loadAll` so `target.preload` can be inspected.
+     */
+    abstract readonly target: Scene | (() => Scene);
+    /**
+     * Minimum wall-clock ms the scene stays visible before handing off.
+     * Prevents flicker on cached loads. Default 0.
+     */
+    readonly minDuration: number;
+    /** Transition used for the loading → target handoff. */
+    readonly transition?: SceneTransition;
+    /**
+     * 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.
+     */
+    readonly autoContinue: boolean;
+    /**
+     * Optional hook; fires if asset loading rejects. The scene stays mounted
+     * whether or not this is set. When set, the hook is the recovery channel:
+     * draw a retry UI, push an error scene, or call `this.startLoading()`
+     * again to retry the load. When unset, the error is logged via the engine
+     * logger and the scene remains mounted in a failed state with no
+     * automatic recovery.
+     *
+     * The hook may still be running when the scene is replaced externally —
+     * don't assume the scene is live (check `this.context.tryResolve` rather
+     * than `this.service` before touching engine services, and avoid spawning
+     * new entities after an `await`).
+     */
+    onLoadError?(error: Error): void | Promise<void>;
+    private _progress;
+    private _started;
+    private _active;
+    private _continueRequested;
+    private _continueGate?;
+    private _attempt;
+    /** Current load progress, 0 → 1. Updated as the AssetManager reports progress. */
+    get progress(): number;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    onExit(): void;
+    private _run;
+}
+
 /** Static factory for creating tween Processes. */
 declare const Tween: {
     /** Tween a numeric property on a target object. */
@@ -1491,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. */
@@ -1509,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, 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, SceneManager, SceneManagerKey, type SceneSnapshot, Sequence, SerializableRegistry, ServiceKey, 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, 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 };