@yagejs/core 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -47,152 +47,6 @@ declare class AssetManager {
     private key;
 }
 
-/** Options for creating a Process. */
-interface ProcessOptions {
-    /** Called each frame with dt (ms) and elapsed (ms). Return true to complete early. */
-    update?: (dt: number, elapsed: number) => boolean | void;
-    /** Called when the process completes. */
-    onComplete?: () => void;
-    /** Auto-complete after this duration in ms. */
-    duration?: number;
-    /** Loop the process. */
-    loop?: boolean;
-    /** Tags for process filtering. */
-    tags?: string[];
-}
-/**
- * A Process represents an ongoing action updated each frame.
- * Used internally by Tween and Sequence, and directly for custom coroutines.
- */
-declare class Process {
-    private readonly updateFn;
-    private readonly onCompleteFn;
-    private readonly duration;
-    private readonly loop;
-    /** Tags for filtering/grouping. */
-    readonly tags: readonly string[];
-    private elapsed;
-    private _completed;
-    private _paused;
-    private _cancelled;
-    private resolvePromise?;
-    /** Create a timer that fires `onComplete` after `duration` ms. */
-    static delay(duration: number, onComplete?: () => void, tags?: string[]): Process;
-    constructor(options: ProcessOptions);
-    /** Whether the process has completed. */
-    get completed(): boolean;
-    /** Whether the process is paused. */
-    get paused(): boolean;
-    /** Pause the process. */
-    pause(): void;
-    /** Resume the process. */
-    resume(): void;
-    /** Cancel the process. */
-    cancel(): void;
-    /** Returns a promise that resolves when the process completes or is cancelled. */
-    toPromise(): Promise<void>;
-    /**
-     * Advance the process by dt milliseconds.
-     * @internal
-     */
-    _update(dt: number): void;
-    /**
-     * Reset the process to its initial state so it can be re-run.
-     * @internal Used by Sequence for loop/repeat with direct instances.
-     */
-    _reset(): void;
-    private complete;
-}
-/** Linear easing (no easing). */
-declare const easeLinear: EasingFunction;
-/** Ease in quadratic. */
-declare const easeInQuad: EasingFunction;
-/** Ease out quadratic. */
-declare const easeOutQuad: EasingFunction;
-/** Ease in-out quadratic. */
-declare const easeInOutQuad: EasingFunction;
-/** Ease out bounce. */
-declare const easeOutBounce: EasingFunction;
-
-/**
- * Built-in system that ticks all ProcessComponents on entities in non-paused
- * scenes, plus a scene-level set of global processes.
- *
- * Runs at Phase.Update with priority 500, ensuring tweened values are fresh
- * before ComponentUpdateSystem (priority 1000) reads them.
- */
-declare class ProcessSystem extends System {
-    readonly phase = Phase.Update;
-    readonly priority = 500;
-    /** Global time scale multiplier. Stacks multiplicatively with per-scene timeScale. */
-    timeScale: number;
-    private sceneManager;
-    private sceneProcesses;
-    onRegister(context: EngineContext): void;
-    /** Add a scene-level process (not tied to any entity). */
-    add(process: Process): Process;
-    /** Cancel scene-level processes, optionally by tag. */
-    cancel(tag?: string): void;
-    update(dt: number): void;
-}
-
-/** Callbacks invoked by the game loop each frame. */
-interface GameLoopCallbacks {
-    earlyUpdate(dt: number): void;
-    fixedUpdate(fixedDt: number): void;
-    update(dt: number): void;
-    lateUpdate(dt: number): void;
-    render(dt: number): void;
-    endOfFrame(dt: number): void;
-}
-/** Configuration for the game loop. */
-interface GameLoopConfig {
-    /** Fixed timestep in ms. Default: 1000/60. */
-    fixedTimestep?: number;
-    /** Max fixed steps per frame to prevent spiral of death. Default: 5. */
-    maxFixedStepsPerFrame?: number;
-}
-/**
- * Game loop with fixed timestep accumulator.
- *
- * Driven by an external ticker (e.g., PixiJS Ticker) or manual `tick()` calls
- * for testing. Implements deterministic fixed updates with variable rendering.
- */
-declare class GameLoop {
-    /** Fixed timestep in ms. */
-    readonly fixedTimestep: number;
-    /** Max fixed steps per frame. */
-    readonly maxFixedStepsPerFrame: number;
-    private accumulator;
-    private running;
-    private callbacks;
-    private tickerUnsubscribe;
-    private rafId;
-    private lastTime;
-    private _frameCount;
-    constructor(config?: GameLoopConfig);
-    /** Current frame count. */
-    get frameCount(): number;
-    /** Whether the loop is running. */
-    get isRunning(): boolean;
-    /** Ratio of accumulated time to fixed timestep, for physics interpolation. */
-    get interpolationAlpha(): number;
-    /** Provide the callbacks that the loop invokes each frame. */
-    setCallbacks(callbacks: GameLoopCallbacks): void;
-    /**
-     * Attach an external ticker (e.g., PixiJS Ticker).
-     * The ticker calls `tick(dt)` every frame.
-     * If no ticker is attached, the loop uses requestAnimationFrame.
-     */
-    attachTicker(subscribe: (callback: (dt: number) => void) => () => void): void;
-    /** Start the loop. */
-    start(): void;
-    /** Stop the loop. */
-    stop(): void;
-    /** Process one frame with the given dt in milliseconds. */
-    tick(dtMs: number): void;
-}
-
 /**
  * A phantom-typed token for entity events.
  * Similar to ServiceKey, but used for entity-level event pub/sub.
@@ -443,46 +297,6 @@ 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 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 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;
-}
-/** 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 {
     /** Match entities whose class implements this trait. */
@@ -523,6 +337,7 @@ declare abstract class Scene {
     private queryCache;
     private bus;
     private _entityEventHandlers?;
+    private _entityEventObserver?;
     private _scopedServices?;
     /** Access the EngineContext. */
     get context(): EngineContext;
@@ -580,6 +395,12 @@ declare abstract class Scene {
      * @internal
      */
     _onEntityEvent(eventName: string, data: unknown, entity: Entity): void;
+    /**
+     * Observe entity-scoped event emissions after they dispatch locally and
+     * bubble to the scene. Tooling only; game code should keep using `on()`.
+     * @internal
+     */
+    _observeEntityEvent(eventName: string, data: unknown, entity: Entity): void;
     /** Called during asset preloading with progress ratio (0→1). */
     onProgress?(ratio: number): void;
     /** Called when the scene is entered (after preload completes). */
@@ -601,6 +422,11 @@ declare abstract class Scene {
      * @internal
      */
     _registerScoped<T>(key: ServiceKey<T>, value: T): void;
+    /**
+     * Install or clear a tooling-only observer for bubbled entity events.
+     * @internal
+     */
+    _setEntityEventObserver(observer?: (eventName: string, data: unknown, entity: Entity) => void): void;
     /**
      * Resolve a scene-scoped service, or `undefined` if none was registered.
      * @internal
@@ -630,85 +456,124 @@ declare abstract class Scene {
     _destroyAllEntities(): 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;
+}
 /**
- * Base class for all components.
+ * A scene transition animates the handoff between scene stack states.
  *
- * Components are the primary authoring model. Game developers write behavior
- * in components using optional `update(dt)` and `fixedUpdate(dt)` methods.
- * The built-in ComponentUpdateSystem calls these methods automatically.
+ * `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`.
  */
-declare abstract class Component {
-    /**
-     * Back-reference to the owning entity. Set by the engine when the component
-     * is added to an entity. Do not set manually.
-     */
-    entity: Entity;
-    /** Whether this component is active. Disabled components are skipped by ComponentUpdateSystem. */
-    enabled: boolean;
-    private _serviceCache;
-    private _cleanups?;
-    /**
-     * Access the entity's scene. Throws if the entity is not in a scene.
-     * Prefer this over threading through `this.entity.scene` in component
-     * code.
-     */
-    get scene(): Scene;
-    /**
-     * Access the EngineContext from the entity's scene.
-     * Throws if the entity is not in a scene.
-     */
-    get context(): EngineContext;
-    /**
-     * 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 input = this.service(InputManagerKey);
-     * ```
-     * The actual resolution is deferred until first property access.
-     */
-    protected service<T extends object>(key: ServiceKey<T>): T;
-    /**
-     * Lazy proxy-based sibling component resolution. Can be used at field-declaration time:
-     * ```ts
-     * readonly anim = this.sibling(AnimatedSpriteComponent);
-     * ```
-     * The actual resolution is deferred until first property access.
-     */
-    protected sibling<C extends Component>(cls: ComponentClass<C>): C;
-    /** Subscribe to events on any entity, auto-unsubscribe on removal. */
-    protected listen<T>(entity: Entity, token: EventToken<T>, handler: (data: T) => void): void;
-    /** Subscribe to scene-level bubbled events, auto-unsubscribe on removal. */
-    protected listenScene<T>(token: EventToken<T>, handler: (data: T, entity: Entity) => void): void;
-    /** Register a cleanup function to run when this component is removed or destroyed. */
-    protected addCleanup(fn: () => void): 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;
+}
+/** 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;
+
+type EntityRef = {
+    readonly id: number;
+    readonly name: string;
+};
+type SceneRef = {
+    readonly name: string;
+};
+/** Base type for event map definitions. */
+type EventMap = Record<string, unknown>;
+/** Well-known engine events. */
+interface EngineEvents {
+    "entity:created": {
+        entity: EntityRef;
+    };
+    "entity:destroyed": {
+        entity: EntityRef;
+    };
+    "component:added": {
+        entity: EntityRef;
+        component: Component;
+    };
+    "component:removed": {
+        entity: EntityRef;
+        componentClass: ComponentClass;
+    };
+    "scene:pushed": {
+        scene: SceneRef;
+    };
+    "scene:popped": {
+        scene: SceneRef;
+    };
+    "scene:replaced": {
+        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;
+    "screen:fullscreen": {
+        active: boolean;
+    };
+    "screen:orientation": {
+        type: OrientationType;
+    };
+}
+/** Typed publish/subscribe event bus. */
+declare class EventBus<E = EventMap> {
+    private handlers;
+    private observers;
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<K extends keyof E>(event: K, handler: (data: E[K]) => void): () => void;
+    /** Subscribe to an event, auto-unsubscribe after first emission. */
+    once<K extends keyof E>(event: K, handler: (data: E[K]) => void): () => void;
+    /** Emit an event. Handlers are called synchronously in registration order. */
+    emit<K extends keyof E>(event: K, data: E[K]): void;
     /**
-     * Run and clear all registered cleanups.
-     * Called by Entity.remove() and Entity._performDestroy() before onRemove/onDestroy.
-     * @internal
+     * Observe every emitted event without affecting handler order or control
+     * flow. Used by tooling such as the Inspector event log.
      */
-    _runCleanups(): void;
-    /** Called when the component is added to an entity. */
-    onAdd?(): void;
-    /** Called when the component is removed from an entity. */
-    onRemove?(): void;
-    /** Called when the component is destroyed (entity destroyed or component removed). */
-    onDestroy?(): void;
-    /** Called every frame by the built-in ComponentUpdateSystem. */
-    update?(dt: number): void;
-    /** Called every fixed timestep by the built-in ComponentUpdateSystem. */
-    fixedUpdate?(dt: number): void;
-    /** Return a JSON-serializable snapshot of this component's state. Used by the save system. */
-    serialize?(): unknown;
-    /** Called after onAdd() during save/load restoration. Apply state that depends on onAdd() having run. */
-    afterRestore?(data: unknown, resolve: SnapshotResolver): void;
+    tap(observer: (event: keyof E, data: E[keyof E]) => void): () => void;
+    /** Remove all handlers for an event, or all handlers if no event specified. */
+    clear(event?: keyof E): void;
 }
 
 /** Log severity levels. */
@@ -775,63 +640,61 @@ declare class Logger {
     private log;
 }
 
-/**
- * Wraps system and component execution. On error, disables the offending
- * system/component and logs the error. The game loop never crashes.
- */
-declare class ErrorBoundary {
-    private logger;
-    private disabledSystems;
-    private disabledComponents;
-    constructor(logger: Logger);
-    /** Wrap a system update call. On throw, disables the system. */
-    wrapSystem(system: System, fn: () => void): void;
-    /** Wrap a component lifecycle or update call. On throw, disables the component. */
-    wrapComponent(component: Component, fn: () => void): void;
-    /** Get all disabled systems and components for inspection. */
-    getDisabled(): {
-        systems: ReadonlyArray<{
-            system: System;
-            error: string;
-        }>;
-        components: ReadonlyArray<{
-            component: Component;
-            error: string;
-        }>;
-    };
+/** Callbacks invoked by the game loop each frame. */
+interface GameLoopCallbacks {
+    earlyUpdate(dt: number): void;
+    fixedUpdate(fixedDt: number): void;
+    update(dt: number): void;
+    lateUpdate(dt: number): void;
+    render(dt: number): void;
+    endOfFrame(dt: number): void;
 }
-
-/** A filter used to register a query — an array of required component classes. */
-type QueryFilter = readonly ComponentClass[];
-/** A live, iterable set of entities matching a query filter. */
-declare class QueryResult {
-    /** @internal */
-    readonly _entities: Set<Entity>;
-    /** @internal */
-    readonly _filter: QueryFilter;
-    /** @internal */
-    constructor(filter: QueryFilter);
-    /** Iterate matching entities. */
-    [Symbol.iterator](): Iterator<Entity>;
-    /** Number of matching entities. */
-    get size(): number;
-    /** Get the first match (useful for singleton queries). */
-    get first(): Entity | undefined;
-    /** Convert to array (allocates). */
-    toArray(): Entity[];
+/** Configuration for the game loop. */
+interface GameLoopConfig {
+    /** Fixed timestep in ms. Default: 1000/60. */
+    fixedTimestep?: number;
+    /** Max fixed steps per frame to prevent spiral of death. Default: 5. */
+    maxFixedStepsPerFrame?: number;
 }
-/** Incrementally maintained entity sets based on component signatures. */
-declare class QueryCache {
-    private queries;
-    /** Register a query. Returns a stable reference to a live result set. */
-    register(filter: QueryFilter): QueryResult;
-    /** Called by Entity when a component is added. */
-    onComponentAdded(entity: Entity): void;
-    /** Called by Entity when a component is removed. */
-    onComponentRemoved(entity: Entity): void;
-    /** Called when an entity is destroyed. */
-    onEntityDestroyed(entity: Entity): void;
-    private matches;
+/**
+ * Game loop with fixed timestep accumulator.
+ *
+ * Driven by an external ticker (e.g., PixiJS Ticker) or manual `tick()` calls
+ * for testing. Implements deterministic fixed updates with variable rendering.
+ */
+declare class GameLoop {
+    /** Fixed timestep in ms. */
+    readonly fixedTimestep: number;
+    /** Max fixed steps per frame. */
+    readonly maxFixedStepsPerFrame: number;
+    private accumulator;
+    private running;
+    private callbacks;
+    private tickerUnsubscribe;
+    private rafId;
+    private lastTime;
+    private _frameCount;
+    constructor(config?: GameLoopConfig);
+    /** Current frame count. */
+    get frameCount(): number;
+    /** Whether the loop is running. */
+    get isRunning(): boolean;
+    /** Ratio of accumulated time to fixed timestep, for physics interpolation. */
+    get interpolationAlpha(): number;
+    /** Provide the callbacks that the loop invokes each frame. */
+    setCallbacks(callbacks: GameLoopCallbacks): void;
+    /**
+     * Attach an external ticker (e.g., PixiJS Ticker).
+     * The ticker calls `tick(dt)` every frame.
+     * If no ticker is attached, the loop uses requestAnimationFrame.
+     */
+    attachTicker(subscribe: (callback: (dt: number) => void) => () => void): void;
+    /** Start the loop. */
+    start(): void;
+    /** Stop the loop. */
+    stop(): void;
+    /** Process one frame with the given dt in milliseconds. */
+    tick(dtMs: number): void;
 }
 
 /** Stack-based scene manager with push/pop/replace semantics. */
@@ -954,15 +817,52 @@ declare class SceneManager {
     private _fireResumeTransitions;
 }
 
-/** Full engine state snapshot. */
-interface EngineSnapshot {
-    frameCount: number;
-    sceneStack: SceneSnapshot[];
-    entityCount: number;
-    systemCount: number;
-    errors: ErrorSnapshot;
+/** Seeded random service used by runtime systems that must be deterministic. */
+interface RandomService {
+    /** Random float in the range [0, 1). */
+    float(): number;
+    /** Random float in the range [min, max). */
+    range(min: number, max: number): number;
+    /** Random integer in the range [min, max] (inclusive). */
+    int(min: number, max: number): number;
+    /** Pick a random element from a non-empty array. */
+    pick<T>(arr: readonly T[]): T;
+    /** Shuffle an array in place and return the same array. */
+    shuffle<T>(arr: T[]): T[];
+    /** Return the seed this generator was constructed (or last reseeded) with. */
+    getSeed(): number;
+}
+/** Scene-scoped key for the active scene's deterministic RNG. */
+declare const RandomKey: ServiceKey<RandomService>;
+/** Normalize arbitrary numbers into the uint32 seed space. */
+declare function normalizeSeed(seed: number): number;
+/** Default seed for explicitly non-deterministic paths. */
+declare function createDefaultRandomSeed(): number;
+/** Create a deterministic random service. */
+declare function createRandomService(seed?: number): RandomService;
+/**
+ * Explicitly non-deterministic global RNG for boot-time or cross-scene code.
+ * Inspector seed control never touches this instance.
+ */
+declare const globalRandom: RandomService;
+
+/**
+ * Mirrors `GamepadAxisKey` from `@yagejs/input` as a local union so the
+ * Inspector contract gets compile-time literal checking without taking a
+ * runtime dependency on the input package.
+ */
+type InspectorGamepadAxisKey = "leftX" | "leftY" | "rightX" | "rightY" | "leftTrigger" | "rightTrigger";
+/**
+ * Options for synthetic pointer injection. Pass `id` / `type` / `isPrimary`
+ * to drive a non-primary, touch, or pen pointer in deterministic tests. All
+ * fields are optional and default to a primary mouse pointer with `id: 1`.
+ */
+interface InspectorPointerOpts {
+    id?: number;
+    type?: "mouse" | "pen" | "touch";
+    isPrimary?: boolean;
 }
-/** Snapshot of a single entity. */
+/** Backward-compatible summary snapshot returned by query helpers. */
 interface EntitySnapshot {
     id: number;
     name: string;
@@ -973,7 +873,7 @@ interface EntitySnapshot {
         y: number;
     };
 }
-/** Snapshot of a scene in the stack. */
+/** Backward-compatible scene stack summary. */
 interface SceneSnapshot {
     name: string;
     entityCount: number;
@@ -995,21 +895,250 @@ interface ErrorSnapshot {
         error: string;
     }>;
 }
+interface ComponentStateSnapshot {
+    type: string;
+    state: unknown | null;
+}
+interface WorldEntitySnapshot {
+    id: string;
+    type: string;
+    parent: string | null;
+    transform: {
+        x: number;
+        y: number;
+        rotation: number;
+        scaleX: number;
+        scaleY: number;
+    };
+    components: ComponentStateSnapshot[];
+}
+interface UINodeSnapshot {
+    id: string;
+    type: string;
+    layout: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    children: UINodeSnapshot[];
+    state: unknown | null;
+}
+interface UITreeSnapshot {
+    root: UINodeSnapshot;
+}
+interface PhysicsSnapshot {
+    bodies: Array<{
+        entityId: string;
+        type: "dynamic" | "kinematic" | "static";
+        position: {
+            x: number;
+            y: number;
+        };
+        rotation: number;
+        linvel: {
+            x: number;
+            y: number;
+        };
+        angvel: number;
+    }>;
+    contacts: Array<{
+        a: string;
+        b: string;
+    }>;
+}
+interface EventLogEntry {
+    frame: number;
+    source: "bus" | "entity";
+    type: string;
+    targetId?: string;
+    payload: unknown | null;
+}
+interface WorldSceneSnapshot {
+    id: string;
+    name: string;
+    paused: boolean;
+    timeScale: number;
+    seed: number;
+    entities: WorldEntitySnapshot[];
+    ui: UITreeSnapshot | null;
+    physics: PhysicsSnapshot;
+    events: EventLogEntry[];
+}
+interface CameraSnapshot {
+    sceneId: string;
+    sceneName: string;
+    name: string | null;
+    priority: number;
+    position: {
+        x: number;
+        y: number;
+    };
+    zoom: number;
+    rotation: number;
+}
+/**
+ * Per-pointer entry in {@link InputStateSnapshot.pointers}. Mirrors the runtime
+ * `PointerInfo` shape from `@yagejs/input`. Touch pointers vanish from the
+ * array once their last button releases; mouse pointers persist.
+ */
+interface PointerSnapshot {
+    /** `PointerEvent.pointerId`, or the synthetic id passed via `firePointer*`. */
+    id: number;
+    x: number;
+    y: number;
+    type: "mouse" | "pen" | "touch";
+    isPrimary: boolean;
+    buttons: number[];
+    down: boolean;
+}
+interface InputStateSnapshot {
+    keys: string[];
+    actions: string[];
+    /**
+     * Aggregate / primary-pointer view, retained for back-compat. `x` / `y` track
+     * the primary pointer's screen position; `buttons` / `down` reflect the
+     * any-pointer aggregate that drives the `MouseLeft`/`Middle`/`Right` action codes.
+     *
+     * For multi-touch state, read {@link InputStateSnapshot.pointers}.
+     */
+    mouse: {
+        x: number;
+        y: number;
+        buttons: number[];
+        down: boolean;
+    };
+    /** All currently-tracked pointers (one per active mouse, pen, or finger). */
+    pointers: PointerSnapshot[];
+    gamepad: {
+        /** Currently-held gamepad codes (e.g. `"GamepadA"`, `"GamepadLT"`). */
+        buttons: string[];
+        /**
+         * Axis state keyed by `${padIndex}:${axisName}` (axisName is a
+         * `GamepadAxisKey` from `@yagejs/input`).
+         */
+        axes: Array<{
+            key: string;
+            value: number;
+        }>;
+    };
+}
+/** Full deterministic inspector snapshot. */
+interface EngineSnapshot {
+    version: 1;
+    frame: number;
+    sceneStack: SceneSnapshot[];
+    entityCount: number;
+    systemCount: number;
+    errors: ErrorSnapshot;
+    scenes: WorldSceneSnapshot[];
+    camera: CameraSnapshot | null;
+    input: InputStateSnapshot;
+}
+interface InspectorTimeController {
+    readonly isFrozen: boolean;
+    freeze(): void;
+    thaw(): void;
+    stepFrames(count: number): void;
+    setDelta(ms: number): void;
+    getFrame(): number;
+}
 /** Internal engine reference to avoid circular dependency with Engine class. */
 interface EngineRef {
     readonly context: EngineContext;
     readonly scenes: SceneManager;
     readonly loop: GameLoop;
+    readonly events?: EventBus<EngineEvents>;
 }
 /**
- * Programmatic state queries for testing and debugging.
+ * Programmatic runtime control and state queries for testing and debugging.
  * Exposed on `window.__yage__` in debug mode.
  */
 declare class Inspector {
-    private engine;
+    private readonly engine;
+    private readonly extensions;
+    private readonly sceneIds;
+    private nextSceneId;
+    private defaultSceneSeed;
+    private sceneSeedOverride;
+    private timeController;
+    private eventLogEnabled;
+    private eventCapacity;
+    /**
+     * Ring buffer of recent events. `eventLogHead` points at the oldest slot;
+     * a full ring contains exactly `eventCapacity` entries. We avoid `splice` to
+     * keep `appendEvent` O(1) — the previous shift-on-overflow approach was
+     * O(n) per event once the buffer was full.
+     */
+    private eventLog;
+    private eventLogHead;
+    private eventWaiters;
+    private detachBusTap;
+    private readonly busEventObserver;
+    private readonly sceneEventObserver;
+    readonly time: {
+        freeze: () => void;
+        thaw: () => void;
+        step: (frames?: number) => void;
+        setDelta: (ms: number) => void;
+        isFrozen: () => boolean;
+        getFrame: () => number;
+    };
+    readonly input: {
+        keyDown: (code: string) => void;
+        keyUp: (code: string) => void;
+        mouseMove: (x: number, y: number) => void;
+        mouseDown: (button?: 0 | 1 | 2) => void;
+        mouseUp: (button?: 0 | 1 | 2) => void;
+        /**
+         * Inject a synthetic pointer-move with full pointer addressing. Pass `opts`
+         * with `id` / `type: "touch"` to drive a specific finger; defaults match
+         * the primary mouse pointer (same as `mouseMove`).
+         */
+        pointerMove: (x: number, y: number, opts?: InspectorPointerOpts) => void;
+        /**
+         * Inject a synthetic pointer-down. With `opts.id` and `opts.type: "touch"`
+         * this drives a multi-touch contact, exercising `getPointers()`,
+         * per-pointer event hooks, and the any-pointer aggregate for `MouseLeft`.
+         */
+        pointerDown: (button?: 0 | 1 | 2, opts?: InspectorPointerOpts) => void;
+        pointerUp: (button?: 0 | 1 | 2, opts?: {
+            id?: number;
+        }) => void;
+        gamepadButton: (code: string, pressed: boolean) => void;
+        gamepadAxis: (side: InspectorGamepadAxisKey, value: number) => void;
+        tap: (code: string, frames?: number) => void;
+        hold: (code: string, frames: number) => void;
+        fireAction: (name: string, frames?: number) => void;
+        clearAll: () => void;
+    };
+    readonly events: {
+        getLog: () => EventLogEntry[];
+        clearLog: () => void;
+        setCapacity: (n: number) => void;
+        waitFor: (pattern: string | RegExp, options?: {
+            withinFrames?: number;
+            source?: "bus" | "entity";
+        }) => Promise<EventLogEntry>;
+    };
+    readonly capture: {
+        png: () => Promise<Uint8Array>;
+        dataURL: () => Promise<string>;
+        pngBase64: () => Promise<string>;
+    };
     constructor(engine: EngineRef);
-    /** Full state snapshot (serializable). */
+    /** Register a namespaced extension API for plugin-specific debug helpers. */
+    addExtension<T extends object>(namespace: string, api: T): T;
+    /** Look up a previously registered extension API by namespace. */
+    getExtension<T extends object>(namespace: string): T | undefined;
+    /** Remove a previously registered extension namespace. */
+    removeExtension(namespace: string): void;
+    /** Full deterministic state snapshot (stable ordering, serializable). */
     snapshot(): EngineSnapshot;
+    /** Stable JSON form of {@link snapshot}. */
+    snapshotJSON(): string;
+    /** Snapshot one scene by inspector scene id. */
+    snapshotScene(id: string): WorldSceneSnapshot;
     /** Find entity by name in the active scene. */
     getEntityByName(name: string): EntitySnapshot | undefined;
     /** Get entity position (from Transform component). */
@@ -1021,7 +1150,7 @@ declare class Inspector {
     hasComponent(entityName: string, componentClass: string): boolean;
     /** Get component data (serializable subset) by class name string. */
     getComponentData(entityName: string, componentClass: string): unknown;
-    /** Get all entities in the active scene as snapshots. */
+    /** Get all entities in the active scene as lightweight snapshots. */
     getEntities(): EntitySnapshot[];
     /** Get scene stack info. */
     getSceneStack(): SceneSnapshot[];
@@ -1029,80 +1158,65 @@ declare class Inspector {
     getSystems(): SystemSnapshot[];
     /** Get disabled components/systems from error boundary. */
     getErrors(): ErrorSnapshot;
+    /** Create a new scene-scoped RNG instance using the current inspector seed policy. */
+    createSceneRandom(): RandomService;
+    /** Force every current and future scene RNG to the provided seed. */
+    setSeed(seed: number): void;
+    /** @internal DebugPlugin installs a deterministic default seed through this hook. */
+    setDefaultSceneSeed(seed: number | undefined): void;
+    private resolveInternalRandom;
+    /** @internal DebugPlugin attaches the frozen-time controller through this hook. */
+    attachTimeController(controller: InspectorTimeController): void;
+    /** @internal Clear a previously attached time controller. */
+    detachTimeController(controller?: InspectorTimeController): void;
+    /** @internal Enable or disable event log recording. */
+    setEventLogEnabled(enabled: boolean): void;
+    /** @internal Install entity-event observation for one scene. No-op if disabled. */
+    attachSceneEventObserver(scene: Scene): void;
+    /** @internal Clear entity-event observation for one scene. */
+    detachSceneEventObserver(scene: Scene): void;
+    /** @internal Scene hooks forward entity events through this method. */
+    recordEntityEvent(eventName: string, data: unknown, entity: Entity): void;
+    /** @internal Engine teardown releases the event-bus tap through this hook. */
+    dispose(): void;
+    private requireTimeController;
+    private requireInputManager;
+    private recordBusEvent;
+    private appendEvent;
+    /** Resolve waiters whose deadline has passed without a match. */
+    private expireDeadlineWaiters;
+    /** Resolve any waiter that matches the just-appended entry. */
+    private flushMatchingWaiter;
+    /**
+     * Walk the ring buffer in chronological order. We avoid materializing the
+     * ordered array on every event append; instead, every consumer that needs
+     * order calls this helper.
+     */
+    private iterateLog;
+    private findMatchingEvent;
+    private eventMatches;
+    private sceneToWorldSnapshot;
+    private getSceneEntities;
+    private entityToWorldSnapshot;
+    private componentToSnapshot;
+    private buildUISnapshot;
+    private buildUINodeSnapshot;
+    private buildCameraSnapshot;
+    private findTopmostCamera;
+    private buildInputSnapshot;
+    private getSceneEvents;
+    private inferSceneIdFromPayload;
+    private extractScene;
+    private extractSceneFromEntity;
     private findActiveEntity;
     private findComponentByName;
-    private entityToSnapshot;
+    private entityToQuerySnapshot;
     private getTransform;
-    private serializeComponent;
+    private serializeComponentOwnProperties;
     private countEntities;
-}
-
-type EntityRef = {
-    readonly id: number;
-    readonly name: string;
-};
-type SceneRef = {
-    readonly name: string;
-};
-/** Base type for event map definitions. */
-type EventMap = Record<string, unknown>;
-/** Well-known engine events. */
-interface EngineEvents {
-    "entity:created": {
-        entity: EntityRef;
-    };
-    "entity:destroyed": {
-        entity: EntityRef;
-    };
-    "component:added": {
-        entity: EntityRef;
-        component: Component;
-    };
-    "component:removed": {
-        entity: EntityRef;
-        componentClass: ComponentClass;
-    };
-    "scene:pushed": {
-        scene: SceneRef;
-    };
-    "scene:popped": {
-        scene: SceneRef;
-    };
-    "scene:replaced": {
-        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;
-}
-/** Typed publish/subscribe event bus. */
-declare class EventBus<E = EventMap> {
-    private handlers;
-    /** Subscribe to an event. Returns an unsubscribe function. */
-    on<K extends keyof E>(event: K, handler: (data: E[K]) => void): () => void;
-    /** Subscribe to an event, auto-unsubscribe after first emission. */
-    once<K extends keyof E>(event: K, handler: (data: E[K]) => void): () => void;
-    /** Emit an event. Handlers are called synchronously in registration order. */
-    emit<K extends keyof E>(event: K, data: E[K]): void;
-    /** Remove all handlers for an event, or all handlers if no event specified. */
-    clear(event?: keyof E): void;
+    private getSceneId;
+    private assertNonNegativeInteger;
+    private assertNonEmptyString;
 }
 
 /**
@@ -1150,51 +1264,266 @@ interface EngineConfig {
     logger?: LoggerConfig;
 }
 /**
- * The top-level entry point. Owns the plugin registry, game loop,
- * scene manager, and DI container.
+ * The top-level entry point. Owns the plugin registry, game loop,
+ * scene manager, and DI container.
+ */
+declare class Engine {
+    /** The dependency injection container. */
+    readonly context: EngineContext;
+    /** The scene manager. */
+    readonly scenes: SceneManager;
+    /** The event bus. */
+    readonly events: EventBus<EngineEvents>;
+    /** The game loop. */
+    readonly loop: GameLoop;
+    /** The logger. */
+    readonly logger: Logger;
+    /** The inspector (debug queries). */
+    readonly inspector: Inspector;
+    private readonly scheduler;
+    private readonly errorBoundary;
+    private readonly queryCache;
+    private readonly sceneHooks;
+    /** The asset manager. */
+    readonly assets: AssetManager;
+    private readonly plugins;
+    private sortedPlugins;
+    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. */
+    start(): Promise<void>;
+    /** Stop the engine. Destroys all scenes, plugins, and the game loop. */
+    destroy(): void;
+    private registerBuiltInSystems;
+    /**
+     * Topological sort of plugins using Kahn's algorithm.
+     * Errors on missing dependencies, circular dependencies, and duplicates.
+     */
+    private topologicalSort;
+}
+
+/**
+ * Base class for systems. Systems run in a specific game loop phase,
+ * query for entities matching a component signature, and operate on them.
+ *
+ * Systems are primarily for engine plugins (physics, rendering, audio).
+ * Game developers typically write Components instead.
+ */
+declare abstract class System {
+    /** The phase this system runs in. */
+    abstract readonly phase: Phase;
+    /** Execution priority within the phase. Lower = earlier. Default: 0. */
+    readonly priority: number;
+    /** Whether this system is active. */
+    enabled: boolean;
+    /** Reference to the engine context, set on registration. */
+    protected context: EngineContext;
+    private _serviceCache;
+    /**
+     * Set the engine context. Called by Engine during startup.
+     * @internal
+     */
+    _setContext(context: EngineContext): void;
+    /** Resolve a service by key, cached after first lookup. */
+    protected use<T>(key: ServiceKey<T>): T;
+    /** Called once when the system is registered with the engine. */
+    onRegister?(context: EngineContext): void;
+    /** Called every frame (or every fixed step for FixedUpdate). */
+    abstract update(dt: number): void;
+    /** Called when the system is removed. */
+    onUnregister?(): void;
+}
+
+/**
+ * Wraps system and component execution. On error, disables the offending
+ * system/component and logs the error. The game loop never crashes.
+ */
+declare class ErrorBoundary {
+    private logger;
+    private disabledSystems;
+    private disabledComponents;
+    constructor(logger: Logger);
+    /** Wrap a system update call. On throw, disables the system. */
+    wrapSystem(system: System, fn: () => void): void;
+    /** Wrap a component lifecycle or update call. On throw, disables the component. */
+    wrapComponent(component: Component, fn: () => void): void;
+    /** Get all disabled systems and components for inspection. */
+    getDisabled(): {
+        systems: ReadonlyArray<{
+            system: System;
+            error: string;
+        }>;
+        components: ReadonlyArray<{
+            component: Component;
+            error: string;
+        }>;
+    };
+}
+
+/** Options for creating a Process. */
+interface ProcessOptions {
+    /** Called each frame with dt (ms) and elapsed (ms). Return true to complete early. */
+    update?: (dt: number, elapsed: number) => boolean | void;
+    /** Called when the process completes. */
+    onComplete?: () => void;
+    /** Auto-complete after this duration in ms. */
+    duration?: number;
+    /** Loop the process. */
+    loop?: boolean;
+    /** Tags for process filtering. */
+    tags?: string[];
+}
+/**
+ * A Process represents an ongoing action updated each frame.
+ * Used internally by Tween and Sequence, and directly for custom coroutines.
+ */
+declare class Process {
+    private readonly updateFn;
+    private readonly onCompleteFn;
+    private readonly duration;
+    private readonly loop;
+    /** Tags for filtering/grouping. */
+    readonly tags: readonly string[];
+    private elapsed;
+    private _completed;
+    private _paused;
+    private _cancelled;
+    private resolvePromise?;
+    /** Create a timer that fires `onComplete` after `duration` ms. */
+    static delay(duration: number, onComplete?: () => void, tags?: string[]): Process;
+    constructor(options: ProcessOptions);
+    /** Whether the process has completed. */
+    get completed(): boolean;
+    /** Whether the process is paused. */
+    get paused(): boolean;
+    /** Pause the process. */
+    pause(): void;
+    /** Resume the process. */
+    resume(): void;
+    /** Cancel the process. */
+    cancel(): void;
+    /** Returns a promise that resolves when the process completes or is cancelled. */
+    toPromise(): Promise<void>;
+    /**
+     * Advance the process by dt milliseconds.
+     * @internal
+     */
+    _update(dt: number): void;
+    /**
+     * Reset the process to its initial state so it can be re-run.
+     * @internal Used by Sequence for loop/repeat with direct instances.
+     */
+    _reset(): void;
+    private complete;
+}
+/** Linear easing (no easing). */
+declare const easeLinear: EasingFunction;
+/** Ease in quadratic. */
+declare const easeInQuad: EasingFunction;
+/** Ease out quadratic. */
+declare const easeOutQuad: EasingFunction;
+/** Ease in-out quadratic. */
+declare const easeInOutQuad: EasingFunction;
+/** Ease out bounce. */
+declare const easeOutBounce: EasingFunction;
+
+/**
+ * Built-in system that ticks all ProcessComponents on entities in non-paused
+ * scenes, plus a scene-level set of global processes.
+ *
+ * Runs at Phase.Update with priority 500, ensuring tweened values are fresh
+ * before ComponentUpdateSystem (priority 1000) reads them.
  */
-declare class Engine {
-    /** The dependency injection container. */
-    readonly context: EngineContext;
-    /** The scene manager. */
-    readonly scenes: SceneManager;
-    /** The event bus. */
-    readonly events: EventBus<EngineEvents>;
-    /** The game loop. */
-    readonly loop: GameLoop;
-    /** The logger. */
-    readonly logger: Logger;
-    /** The inspector (debug queries). */
-    readonly inspector: Inspector;
-    private readonly scheduler;
-    private readonly errorBoundary;
-    private readonly queryCache;
-    private readonly sceneHooks;
-    /** The asset manager. */
-    readonly assets: AssetManager;
-    private readonly plugins;
-    private sortedPlugins;
-    private started;
-    private readonly debug;
-    constructor(config?: EngineConfig);
+declare class ProcessSystem extends System {
+    readonly phase = Phase.Update;
+    readonly priority = 500;
+    /** Global time scale multiplier. Stacks multiplicatively with per-scene timeScale. */
+    timeScale: number;
+    private sceneManager;
+    private globalProcesses;
+    private scenePools;
+    private _unregisterSceneHook;
+    onRegister(context: EngineContext): void;
+    onUnregister(): void;
     /**
-     * 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.
+     * Add an engine-global process. Ticked under the global timeScale only;
+     * NOT gated by per-scene pause or scaled by per-scene timeScale. Use this
+     * for cross-scene effects (e.g. screen-scope filter fades on `app.stage`)
+     * or processes that have no owning scene.
      */
-    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. */
-    start(): Promise<void>;
-    /** Stop the engine. Destroys all scenes, plugins, and the game loop. */
-    destroy(): void;
-    private registerBuiltInSystems;
+    add(process: Process): Process;
     /**
-     * Topological sort of plugins using Kahn's algorithm.
-     * Errors on missing dependencies, circular dependencies, and duplicates.
+     * Add a process bound to a specific scene's lifecycle. Ticked only while
+     * the scene is active (not paused) and scaled by the scene's `timeScale`,
+     * exactly like an entity-owned `ProcessComponent`. Use this for layer or
+     * scene-scope effect fades that should pause with the scene.
      */
-    private topologicalSort;
+    addForScene(scene: Scene, process: Process): Process;
+    /** Cancel engine-global processes, optionally by tag. */
+    cancel(tag?: string): void;
+    /** Cancel every scene-bound process for `scene`, optionally by tag. */
+    cancelForScene(scene: Scene, tag?: string): void;
+    update(dt: number): void;
+}
+
+/** A filter used to register a query — an array of required component classes. */
+type QueryFilter = readonly ComponentClass[];
+/** A live, iterable set of entities matching a query filter. */
+declare class QueryResult {
+    /** @internal */
+    readonly _entities: Set<Entity>;
+    /** @internal */
+    readonly _filter: QueryFilter;
+    /** @internal */
+    constructor(filter: QueryFilter);
+    /** Iterate matching entities. */
+    [Symbol.iterator](): Iterator<Entity>;
+    /** Number of matching entities. */
+    get size(): number;
+    /** Get the first match (useful for singleton queries). */
+    get first(): Entity | undefined;
+    /** Convert to array (allocates). */
+    toArray(): Entity[];
+}
+/** Incrementally maintained entity sets based on component signatures. */
+declare class QueryCache {
+    private queries;
+    /** Register a query. Returns a stable reference to a live result set. */
+    register(filter: QueryFilter): QueryResult;
+    /** Called by Entity when a component is added. */
+    onComponentAdded(entity: Entity): void;
+    /** Called by Entity when a component is removed. */
+    onComponentRemoved(entity: Entity): void;
+    /** Called when an entity is destroyed. */
+    onEntityDestroyed(entity: Entity): void;
+    private matches;
+}
+
+/** Manages ordered execution of systems within each phase. */
+declare class SystemScheduler {
+    private phases;
+    private errorBoundary;
+    /** Set the error boundary for wrapping system execution. */
+    setErrorBoundary(boundary: ErrorBoundary): void;
+    /** Register a system. Sorted by priority within its phase. */
+    add(system: System): void;
+    /** Remove a system. */
+    remove(system: System): void;
+    /** Run all enabled systems in a given phase. Wraps each in ErrorBoundary if available. */
+    run(phase: Phase, dt: number): void;
+    /** Get all systems registered for a phase. */
+    getSystems(phase: Phase): readonly System[];
+    /** Get all systems across all phases. */
+    getAllSystems(): System[];
 }
 
 /** The resolution scope for a service. */
@@ -1259,53 +1588,84 @@ declare const ProcessSystemKey: ServiceKey<ProcessSystem>;
 declare const AssetManagerKey: ServiceKey<AssetManager>;
 
 /**
- * Base class for systems. Systems run in a specific game loop phase,
- * query for entities matching a component signature, and operate on them.
+ * Base class for all components.
  *
- * Systems are primarily for engine plugins (physics, rendering, audio).
- * Game developers typically write Components instead.
+ * Components are the primary authoring model. Game developers write behavior
+ * in components using optional `update(dt)` and `fixedUpdate(dt)` methods.
+ * The built-in ComponentUpdateSystem calls these methods automatically.
  */
-declare abstract class System {
-    /** The phase this system runs in. */
-    abstract readonly phase: Phase;
-    /** Execution priority within the phase. Lower = earlier. Default: 0. */
-    readonly priority: number;
-    /** Whether this system is active. */
+declare abstract class Component {
+    /**
+     * Back-reference to the owning entity. Set by the engine when the component
+     * is added to an entity. Do not set manually.
+     */
+    entity: Entity;
+    /** Whether this component is active. Disabled components are skipped by ComponentUpdateSystem. */
     enabled: boolean;
-    /** Reference to the engine context, set on registration. */
-    protected context: EngineContext;
     private _serviceCache;
+    private _cleanups?;
     /**
-     * Set the engine context. Called by Engine during startup.
-     * @internal
+     * Access the entity's scene. Throws if the entity is not in a scene.
+     * Prefer this over threading through `this.entity.scene` in component
+     * code.
+     */
+    get scene(): Scene;
+    /**
+     * Access the EngineContext from the entity's scene.
+     * Throws if the entity is not in a scene.
+     */
+    get context(): EngineContext;
+    /**
+     * 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.
      */
-    _setContext(context: EngineContext): void;
-    /** Resolve a service by key, cached after first lookup. */
     protected use<T>(key: ServiceKey<T>): T;
-    /** Called once when the system is registered with the engine. */
-    onRegister?(context: EngineContext): void;
-    /** Called every frame (or every fixed step for FixedUpdate). */
-    abstract update(dt: number): void;
-    /** Called when the system is removed. */
-    onUnregister?(): void;
-}
-
-/** Manages ordered execution of systems within each phase. */
-declare class SystemScheduler {
-    private phases;
-    private errorBoundary;
-    /** Set the error boundary for wrapping system execution. */
-    setErrorBoundary(boundary: ErrorBoundary): void;
-    /** Register a system. Sorted by priority within its phase. */
-    add(system: System): void;
-    /** Remove a system. */
-    remove(system: System): void;
-    /** Run all enabled systems in a given phase. Wraps each in ErrorBoundary if available. */
-    run(phase: Phase, dt: number): void;
-    /** Get all systems registered for a phase. */
-    getSystems(phase: Phase): readonly System[];
-    /** Get all systems across all phases. */
-    getAllSystems(): System[];
+    private _warnScopedFallback;
+    /**
+     * Lazy proxy-based service resolution. Can be used at field-declaration time:
+     * ```ts
+     * readonly input = this.service(InputManagerKey);
+     * ```
+     * The actual resolution is deferred until first property access.
+     */
+    protected service<T extends object>(key: ServiceKey<T>): T;
+    /**
+     * Lazy proxy-based sibling component resolution. Can be used at field-declaration time:
+     * ```ts
+     * readonly anim = this.sibling(AnimatedSpriteComponent);
+     * ```
+     * The actual resolution is deferred until first property access.
+     */
+    protected sibling<C extends Component>(cls: ComponentClass<C>): C;
+    /** Subscribe to events on any entity, auto-unsubscribe on removal. */
+    protected listen<T>(entity: Entity, token: EventToken<T>, handler: (data: T) => void): void;
+    /** Subscribe to scene-level bubbled events, auto-unsubscribe on removal. */
+    protected listenScene<T>(token: EventToken<T>, handler: (data: T, entity: Entity) => void): void;
+    /** Register a cleanup function to run when this component is removed or destroyed. */
+    protected addCleanup(fn: () => void): void;
+    /**
+     * Run and clear all registered cleanups.
+     * Called by Entity.remove() and Entity._performDestroy() before onRemove/onDestroy.
+     * @internal
+     */
+    _runCleanups(): void;
+    /** Called when the component is added to an entity. */
+    onAdd?(): void;
+    /** Called when the component is removed from an entity. */
+    onRemove?(): void;
+    /** Called when the component is destroyed (entity destroyed or component removed). */
+    onDestroy?(): void;
+    /** Called every frame by the built-in ComponentUpdateSystem. */
+    update?(dt: number): void;
+    /** Called every fixed timestep by the built-in ComponentUpdateSystem. */
+    fixedUpdate?(dt: number): void;
+    /** Return a JSON-serializable snapshot of this component's state. Used by the save system. */
+    serialize?(): unknown;
+    /** Called after onAdd() during save/load restoration. Apply state that depends on onAdd() having run. */
+    afterRestore?(data: unknown, resolve: SnapshotResolver): void;
 }
 
 /** Constructor type for components. */
@@ -1431,10 +1791,6 @@ declare const MathUtils: {
     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). */
-    readonly randomInt: (min: number, max: number) => number;
     /** Convert degrees to radians. */
     readonly degToRad: (degrees: number) => number;
     /** Convert radians to degrees. */
@@ -1621,6 +1977,7 @@ declare abstract class LoadingScene extends Scene {
     private _active;
     private _continueRequested;
     private _continueGate?;
+    private _pendingWaits;
     private _attempt;
     /** Current load progress, 0 → 1. Updated as the AssetManager reports progress. */
     get progress(): number;
@@ -1650,6 +2007,7 @@ declare abstract class LoadingScene extends Scene {
     continue(): void;
     onExit(): void;
     private _run;
+    private _createEngineTimeDelay;
 }
 
 /** Static factory for creating tween Processes. */
@@ -1737,6 +2095,7 @@ declare class KeyframeAnimator<T extends string = string> extends Component {
     /** Whether a named animation is currently playing. */
     isPlaying(name: T): boolean;
     onDestroy(): void;
+    serialize(): null;
     private stopInternal;
 }
 
@@ -1856,6 +2215,7 @@ declare class ProcessComponent extends Component {
     _tick(dt: number): void;
     /** Cancel all processes and slots on entity destroy. */
     onDestroy(): void;
+    serialize(): null;
 }
 
 /**
@@ -1878,6 +2238,43 @@ declare class TimerEntity extends Entity {
     cancel(tag?: string): void;
 }
 
+/**
+ * A scoped queue for `Process` instances. Tracks the processes it enqueued so
+ * `cancelAll()` can tear them down without touching unrelated processes that
+ * happen to share the same underlying pool (entity `ProcessComponent` or
+ * engine-level `ProcessSystem`).
+ *
+ * Use one of the `make*ScopedQueue` factories to construct one — each picks
+ * the right routing strategy and lifetime semantics for its scope.
+ */
+interface ScopedProcessQueue {
+    /** Enqueue a process. Returned for chaining. */
+    run(p: Process): Process;
+    /** Cancel every process this queue enqueued. Idempotent. */
+    cancelAll(): void;
+}
+/**
+ * Scoped queue that routes through the entity's `ProcessComponent`. Auto-adds
+ * one if the entity doesn't already have it. `cancelAll()` only cancels the
+ * processes this queue enqueued, so sharing the underlying ProcessComponent
+ * with user code stays safe.
+ */
+declare function makeEntityScopedQueue(entity: Entity): ScopedProcessQueue;
+/**
+ * Scoped queue bound to a specific scene's lifecycle. Routes through
+ * `ProcessSystem.addForScene`, so processes pause with the scene and are
+ * scaled by its `timeScale` — matching the behaviour of entity-owned
+ * `ProcessComponent` processes.
+ */
+declare function makeSceneScopedQueue(processSystem: ProcessSystem, scene: Scene): ScopedProcessQueue;
+/**
+ * Engine-global scoped queue. Routes through `ProcessSystem.add` — ticked
+ * under the global timeScale only, NOT gated by per-scene pause or scaled
+ * by per-scene timeScale. Right for cross-scene work that should keep
+ * playing during scene transitions and across paused scenes.
+ */
+declare function makeGlobalScopedQueue(processSystem: ProcessSystem): ScopedProcessQueue;
+
 /**
  * Cross-package contract for "something that owns a canvas and can map
  * canvas-relative CSS pixels into virtual-space pixels".
@@ -1899,6 +2296,19 @@ interface RendererAdapter {
         x: number;
         y: number;
     };
+    /**
+     * Hit-test at virtual-space coordinates and return `true` when the topmost
+     * interactive container under `(x, y)` is parented (directly or through any
+     * ancestor) to a container marked via {@link markPointerConsumeContainer}.
+     * Optional — when absent, the input plugin's UI auto-consume fallback is a
+     * no-op.
+     *
+     * Implemented by `@yagejs/renderer` over Pixi's `EventBoundary`. The input
+     * plugin calls this on `pointerdown` drains to auto-claim presses that land
+     * on UI surfaces (UIPanel backgrounds, decorative UIText, etc.) without
+     * requiring per-component handler boilerplate.
+     */
+    hitTestUI?(x: number, y: number): boolean;
 }
 /**
  * Well-known service key for the current renderer's pointer-input adapter.
@@ -1908,6 +2318,36 @@ interface RendererAdapter {
  */
 declare const RendererAdapterKey: ServiceKey<RendererAdapter>;
 
+/**
+ * Cross-package WeakSet for marking display containers (Pixi `Container`s in
+ * the canonical setup) as "swallow pointer input." The `@yagejs/input`
+ * package's drain step consults this set via the renderer's optional
+ * `hitTestUI(x, y)` — when the topmost interactive container under a
+ * `pointerdown` is parented to a marked container, the pointer is auto-claimed
+ * (`consumePointer`-equivalent), so the press never propagates to gameplay
+ * action-map edges like `MouseLeft`.
+ *
+ * Lives in `@yagejs/core` so the renderer (read side) and the UI / sprite
+ * components (write side) can both reach it without circular imports.
+ *
+ * Untyped on `Container` to keep `@yagejs/core` free of any Pixi dependency.
+ * Callers pass their `Pixi.Container` instances directly; `WeakSet` accepts
+ * any object reference.
+ */
+/**
+ * Mark a display container as a UI-input surface. Idempotent. Call from a
+ * component's `onAdd` (or equivalent) after the underlying Pixi container is
+ * created.
+ */
+declare function markPointerConsumeContainer(container: object): void;
+/**
+ * Remove the mark. Call from a component's `onDestroy` for symmetry, or to
+ * implement an opt-out (`consumeInput: false`) escape hatch on UI primitives.
+ */
+declare function unmarkPointerConsumeContainer(container: object): void;
+/** Whether a container has been marked as a UI-input surface. */
+declare function isPointerConsumeContainer(container: object): boolean;
+
 /** 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. */
@@ -1926,4 +2366,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, 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 };
+export { AssetHandle, type AssetLoader, AssetManager, AssetManagerKey, type Blueprint, type CameraSnapshot, Component, type ComponentClass, ComponentFixedUpdateSystem, type ComponentStateSnapshot, 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 EventLogEntry, type EventMap, EventToken, GameLoop, type GameLoopCallbacks, type GameLoopConfig, GameLoopKey, type InputStateSnapshot, Inspector, InspectorKey, type InspectorTimeController, type Interpolatable, type Keyframe, type KeyframeAnimationDef, KeyframeAnimator, type KeyframeTrackOptions, LoadingScene, type LogEntry, LogLevel, Logger, type LoggerConfig, LoggerKey, MathUtils, Phase, type PhysicsSnapshot, type Plugin, type PointerSnapshot, Process, ProcessComponent, type ProcessOptions, ProcessSlot, type ProcessSlotConfig, ProcessSystem, ProcessSystemKey, QueryCache, QueryCacheKey, QueryResult, RandomKey, type RandomService, type RendererAdapter, RendererAdapterKey, SERIALIZABLE_KEY, Scene, SceneHookRegistry, SceneHookRegistryKey, type SceneHooks, SceneManager, SceneManagerKey, type SceneSnapshot, type SceneTransition, type SceneTransitionContext, type SceneTransitionKind, type SceneTransitionOptions, type ScopedProcessQueue, Sequence, SerializableRegistry, ServiceKey, type ServiceKeyOptions, type ServiceScope, type SmoothDampResult, type SnapshotResolver, System, SystemScheduler, SystemSchedulerKey, type SystemSnapshot, TimerEntity, TraitToken, Transform, type TransformData, Tween, type UINodeSnapshot, type UITreeSnapshot, VERSION, Vec2, type Vec2Like, type WorldEntitySnapshot, type WorldSceneSnapshot, _resetEntityIdCounter, advanceFrames, createDefaultRandomSeed, createKeyframeTrack, createMockEntity, createMockScene, createRandomService, createTestEngine, defineBlueprint, defineEvent, defineTrait, easeInOutQuad, easeInQuad, easeLinear, easeOutBounce, easeOutQuad, filterEntities, getSerializableType, globalRandom, interpolate, isPointerConsumeContainer, isSerializable, makeEntityScopedQueue, makeGlobalScopedQueue, makeSceneScopedQueue, markPointerConsumeContainer, normalizeSeed, resolveTransition, serializable, trait, unmarkPointerConsumeContainer };