@yagejs/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1512 @@
+/**
+ * A phantom-typed handle referencing an asset by type and path.
+ * Created by plugin-specific factory functions (e.g. `texture()`, `sound()`).
+ * Core knows nothing about concrete asset types.
+ */
+declare class AssetHandle<T> {
+    /** Loader type key (e.g. "texture", "sound"). */
+    readonly type: string;
+    /** Asset path or URL. */
+    readonly path: string;
+    constructor(
+    /** Loader type key (e.g. "texture", "sound"). */
+    type: string, 
+    /** Asset path or URL. */
+    path: string);
+    /** Phantom field to preserve the generic type at compile time. */
+    readonly _type: T;
+}
+/** Interface that plugins implement to load/unload a specific asset type. */
+interface AssetLoader<T = unknown> {
+    load(path: string): Promise<T>;
+    unload?(path: string, asset: T): void;
+}
+
+/**
+ * Orchestrates asset loading across plugin-provided loaders.
+ * Core owns the "when" and "what"; plugins own the "how".
+ */
+declare class AssetManager {
+    private loaders;
+    private cache;
+    /** Register a loader for a given asset type. Called by plugins during install(). */
+    registerLoader(type: string, loader: AssetLoader): void;
+    /** Retrieve a loaded asset. Throws if not loaded. */
+    get<T>(handle: AssetHandle<T>): T;
+    /** Check if an asset is loaded. */
+    has(handle: AssetHandle<unknown>): boolean;
+    /**
+     * Load all assets, skipping already-cached ones.
+     * Reports progress via optional callback (0→1).
+     */
+    loadAll(handles: readonly AssetHandle<unknown>[], onProgress?: (ratio: number) => void): Promise<void>;
+    /** Unload a single asset and remove from cache. */
+    unload(handle: AssetHandle<unknown>): void;
+    /** Unload all cached assets. */
+    clear(): void;
+    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.
+ */
+declare class EventToken<T = void> {
+    /** Unique string identifier for this event. */
+    readonly name: string;
+    constructor(
+    /** Unique string identifier for this event. */
+    name: string);
+    /** Phantom field to preserve the generic type. */
+    readonly _type: T;
+}
+/** Create a typed event token. */
+declare function defineEvent<T = void>(name: string): EventToken<T>;
+
+/**
+ * Passed to `afterRestore` hooks so user code can resolve entity references
+ * that were captured as IDs at save time.
+ */
+interface SnapshotResolver {
+    /** Resolve a save-time entity ID to the restored entity instance. Returns null if not found. */
+    entity(savedId: number): Entity | null;
+}
+/** Symbol stored on classes decorated with @serializable. Holds the type string. */
+declare const SERIALIZABLE_KEY: unique symbol;
+/** Read-only access to the serializable type registry. */
+declare const SerializableRegistry: {
+    /** Look up a class by its type string. */
+    get(type: string): (new (...args: any[]) => any) | undefined;
+    /** Check if a type string is registered. */
+    has(type: string): boolean;
+    /** Iterate all registered [type, class] entries. */
+    entries(): IterableIterator<[string, new (...args: any[]) => any]>;
+    /** Remove a type from the registry. */
+    delete(type: string): boolean;
+};
+/** Check if an instance belongs to a @serializable-decorated class. */
+declare function isSerializable(instance: object): boolean;
+/** Get the type string from a @serializable-decorated class or instance. */
+declare function getSerializableType(target: object | (new (...args: any[]) => any)): string | undefined;
+/**
+ * Decorator that registers a class in the global SerializableRegistry.
+ *
+ * Works on Component, Entity, and Scene subclasses.
+ *
+ * ```ts
+ * // Zero-arg — uses class.name as type string
+ * @serializable
+ * class Transform extends Component { ... }
+ *
+ * // With override — for name collisions or minified builds
+ * @serializable({ type: "MyTransform" })
+ * class Transform extends Component { ... }
+ * ```
+ */
+declare function serializable<T extends new (...args: any[]) => any>(target: T): T;
+declare function serializable(config: {
+    type: string;
+}): <T extends new (...args: any[]) => any>(target: T) => T;
+
+/**
+ * Trait system — discoverable, type-safe entity capabilities.
+ *
+ * Traits let entity subclasses declare capabilities (`Interactable`, `Damageable`)
+ * that are enforced at compile time (via decorator constraint) and queryable at
+ * runtime via `hasTrait()`.
+ */
+/** Symbol key for storing the set of trait symbols on a class. */
+declare const TRAITS_KEY: unique symbol;
+/**
+ * A phantom-typed token representing a trait.
+ * Follows the same pattern as EventToken / ServiceKey.
+ */
+declare class TraitToken<T> {
+    /** Human-readable name for debugging. */
+    readonly name: string;
+    readonly symbol: symbol;
+    constructor(
+    /** Human-readable name for debugging. */
+    name: string);
+    /** Phantom field to preserve the generic type. */
+    readonly _type: T;
+}
+/**
+ * Create a typed trait token.
+ *
+ * ```ts
+ * const Interactable = defineTrait<{ interact(): void; priority: number }>("Interactable");
+ * ```
+ */
+declare function defineTrait<T>(name: string): TraitToken<T>;
+/**
+ * Class decorator that registers a trait on an entity subclass.
+ * The type constraint enforces that the class implements all trait members.
+ *
+ * ```ts
+ * @trait(Interactable)
+ * class LightEntity extends Entity {
+ *   priority = 4;
+ *   interact() { ... } // TS error if missing
+ * }
+ * ```
+ */
+declare function trait<Trait>(token: TraitToken<Trait>): <T extends typeof Entity & {
+    prototype: Trait;
+}>(target: T) => T;
+
+/** Reset the entity ID counter. Exposed for testing only. */
+declare function _resetEntityIdCounter(): void;
+/**
+ * Callback interface for notifying external systems (QueryCache, EventBus)
+ * about entity component changes. Injected by Scene.
+ */
+interface EntityCallbacks {
+    onComponentAdded(entity: Entity, componentClass: ComponentClass): void;
+    onComponentRemoved(entity: Entity, componentClass: ComponentClass): void;
+}
+/**
+ * An entity is a named container of components with O(1) lookups by type.
+ */
+declare class Entity {
+    static [TRAITS_KEY]: Set<symbol>;
+    /** Unique auto-incrementing ID. */
+    readonly id: number;
+    /** Display name for debugging. */
+    readonly name: string;
+    /** Tags for group queries. */
+    readonly tags: Set<string>;
+    private components;
+    private _destroyed;
+    private _scene;
+    private callbacks;
+    private _eventHandlers?;
+    private _parent;
+    private _children;
+    constructor(name?: string, tags?: Iterable<string>);
+    /** The scene this entity belongs to, or null. */
+    get scene(): Scene | null;
+    /** True if destroy() has been called. */
+    get isDestroyed(): boolean;
+    /** The parent entity, or null if this is a root entity. */
+    get parent(): Entity | null;
+    /** Named children as a read-only map. Empty map if no children. */
+    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;
+    /** Remove a named child. Returns the detached entity. */
+    removeChild(name: string): Entity;
+    /** Get a child by name. Throws if not found. */
+    getChild(name: string): Entity;
+    /** Get a child by name, or undefined if not found. */
+    tryGetChild(name: string): Entity | undefined;
+    /** Add a component instance. Returns the component for chaining. */
+    add<C extends Component>(component: C): C;
+    /** Get a component by class. Throws if not found. */
+    get<C extends Component>(cls: ComponentClass<C>): C;
+    /** Get a component by class, or undefined if not found. */
+    tryGet<C extends Component>(cls: ComponentClass<C>): C | undefined;
+    /** Check if entity has a component of the given class. */
+    has(cls: ComponentClass): boolean;
+    /** Remove a component by class. */
+    remove(cls: ComponentClass): void;
+    /** Subscribe to a typed event on this entity. Returns an unsubscribe function. */
+    on<T>(token: EventToken<T>, handler: (data: T) => void): () => void;
+    /** Emit a typed event on this entity. Bubbles to the scene. */
+    emit(token: EventToken<void>): void;
+    emit<T>(token: EventToken<T>, data: T): void;
+    /** Get all components as an iterable. */
+    getAll(): Iterable<Component>;
+    /** Mark for deferred destruction. Actual cleanup happens at end of frame. */
+    destroy(): void;
+    /**
+     * Internal: perform actual destruction — remove all components and clear state.
+     * Called by Scene during endOfFrame flush.
+     * @internal
+     */
+    _performDestroy(): void;
+    /**
+     * Optional setup method. Called by `scene.spawn(Class, params)` after the
+     * entity is wired to its scene, so components can access services.
+     * Override in subclasses — do NOT use the constructor for component setup.
+     */
+    setup?(params: unknown): void;
+    /** Return a JSON-serializable snapshot of this entity's custom state. Used by the save system. */
+    serialize?(): unknown;
+    /** Called after components are restored during save/load. Rebuild non-serializable state here. */
+    afterRestore?(data: unknown, resolve: SnapshotResolver): void;
+    /** Check if this entity's class implements a given trait. Acts as a type guard. */
+    hasTrait<T>(token: TraitToken<T>): this is this & T;
+    /**
+     * Internal: set the scene and callbacks. Called by Scene.spawn().
+     * @internal
+     */
+    _setScene(scene: Scene | null, callbacks: EntityCallbacks | null): void;
+}
+
+/**
+ * A reusable entity template. Blueprints define how to assemble
+ * an entity from components, given optional parameters.
+ */
+interface Blueprint<P = void> {
+    readonly name: string;
+    build(entity: Entity, params: P): 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>;
+
+/** Filter criteria for entity queries. All fields are AND'd together. */
+interface EntityFilter {
+    /** Match entities whose class implements this trait. */
+    trait?: TraitToken<any>;
+    /** Match entities that have ALL of these tags. */
+    tags?: string[];
+    /** Match entities with this exact name. */
+    name?: string;
+    /** Custom predicate — called after other checks pass. */
+    filter?: (entity: Entity) => boolean;
+}
+/** Apply a filter to an iterable of entities. Skips destroyed entities. */
+declare function filterEntities(entities: Iterable<Entity>, filter: EntityFilter): Entity[];
+
+/**
+ * Scenes own entities and define lifecycle hooks.
+ * Each scene is a self-contained world with its own entity pool.
+ */
+declare abstract class Scene {
+    /** Name for debugging/inspection. */
+    abstract readonly name: string;
+    /** Whether scenes below this one in the stack should be paused. Default: true. */
+    readonly pauseBelow: boolean;
+    /** Whether scenes below this one should still render. Default: false. */
+    readonly transparentBelow: boolean;
+    /** Asset handles to load before onEnter(). Override in subclasses. */
+    readonly preload?: readonly AssetHandle<unknown>[];
+    /** 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. */
+    timeScale: number;
+    private entities;
+    private destroyQueue;
+    private _context;
+    private entityCallbacks;
+    private queryCache;
+    private bus;
+    private _entityEventHandlers?;
+    /** Access the EngineContext. */
+    get context(): EngineContext;
+    /** Whether this scene is effectively paused (manual pause or paused by stack). */
+    get isPaused(): boolean;
+    /** Convenience accessor for the AssetManager. */
+    get assets(): AssetManager;
+    /**
+     * Lazy proxy-based service resolution. Can be used at field-declaration time:
+     * ```ts
+     * readonly layers = this.service(RenderLayerManagerKey);
+     * ```
+     * The actual resolution is deferred until first property access.
+     */
+    protected service<T extends object>(key: ServiceKey<T>): T;
+    /** Spawn a new entity in this scene. */
+    spawn(name?: string): Entity;
+    spawn<P>(blueprint: Blueprint<P>, params: P): Entity;
+    spawn(blueprint: Blueprint<void>): Entity;
+    /** Spawn an entity subclass with setup params. */
+    spawn<E extends Entity, P>(Class: new () => E & {
+        setup(params: P): void;
+    }, params: P): E;
+    /** Spawn an entity subclass without setup params. */
+    spawn<E extends Entity>(Class: new () => E): E;
+    /**
+     * Add an existing entity to this scene (used by Entity.addChild for auto-scene-membership).
+     * @internal
+     */
+    _addExistingEntity(entity: Entity): void;
+    /** Mark an entity for destruction. Deferred to endOfFrame flush. */
+    destroyEntity(entity: Entity): void;
+    /**
+     * Add an entity to the destroy queue. Called by Entity.destroy().
+     * @internal
+     */
+    _queueDestroy(entity: Entity): void;
+    /** Get all active entities. */
+    getEntities(): ReadonlySet<Entity>;
+    /** Find entity by name (first match). */
+    findEntity(name: string): Entity | undefined;
+    /** Find entities by tag. */
+    findEntitiesByTag(tag: string): Entity[];
+    /** Find entities matching a filter. Trait filter narrows the return type. */
+    findEntities<T>(filter: EntityFilter & {
+        trait: TraitToken<T>;
+    }): (Entity & T)[];
+    findEntities(filter?: EntityFilter): Entity[];
+    /** Subscribe to bubbled entity events at the scene level. Handler receives (data, emittingEntity). */
+    on<T>(token: EventToken<T>, handler: (data: T, entity: Entity) => void): () => void;
+    /**
+     * Called by Entity.emit() for bubbling entity events to the scene.
+     * @internal
+     */
+    _onEntityEvent(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). */
+    onEnter?(): void;
+    /** Called when the scene is exited (popped or replaced). */
+    onExit?(): void;
+    /** Called when a scene is pushed on top of this one. */
+    onPause?(): void;
+    /** Called when the scene above is popped, restoring this scene. */
+    onResume?(): void;
+    /** Return a JSON-serializable snapshot of this scene's custom state. Used by the save system. */
+    serialize?(): unknown;
+    /** Called after entities are restored during save/load. Rebuild non-serializable state here. */
+    afterRestore?(data: unknown, resolve: SnapshotResolver): void;
+    /**
+     * Set the engine context. Called by SceneManager when the scene is pushed.
+     * @internal
+     */
+    _setContext(context: EngineContext): void;
+    /**
+     * Flush the destroy queue — destroy pending entities.
+     * Called by the engine during the endOfFrame phase.
+     * @internal
+     */
+    _flushDestroyQueue(): void;
+    /**
+     * Destroy all entities — used during scene exit.
+     * @internal
+     */
+    _destroyAllEntities(): void;
+}
+
+/**
+ * Base class for all components.
+ *
+ * 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 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 `this.entity.scene!` in component methods.
+     */
+    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. */
+    protected use<T>(key: ServiceKey<T>): T;
+    /**
+     * Lazy proxy-based service resolution. Can be used at field-declaration time:
+     * ```ts
+     * readonly camera = this.service(CameraKey);
+     * ```
+     * 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;
+}
+
+/** Log severity levels. */
+declare enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Warn = 2,
+    Error = 3,
+    None = 4
+}
+/** Configuration for the Logger. */
+interface LoggerConfig {
+    /** Minimum log level. Default: Info. */
+    level?: LogLevel;
+    /** Category whitelist. Empty = all categories allowed. */
+    categories?: string[];
+    /** Ring buffer size. Default: 500. */
+    bufferSize?: number;
+    /** Custom output handler. */
+    output?: (entry: LogEntry) => void;
+}
+/** A single log entry. */
+interface LogEntry {
+    /** Log severity level. */
+    level: LogLevel;
+    /** Category string (e.g., "physics", "core"). */
+    category: string;
+    /** Log message. */
+    message: string;
+    /** Optional structured data. */
+    data?: unknown;
+    /** Timestamp in milliseconds since epoch. */
+    timestamp: number;
+    /** Game frame number at time of log. */
+    frame: number;
+}
+/** Structured logger with ring buffer, levels, and category filtering. */
+declare class Logger {
+    private readonly level;
+    private readonly categories;
+    private readonly bufferSize;
+    private readonly output;
+    private readonly buffer;
+    private writeIndex;
+    private count;
+    private currentFrame;
+    constructor(config?: LoggerConfig);
+    /** Set the current frame number (incremented externally by the game loop). */
+    setFrame(frame: number): void;
+    /** Log a debug message. */
+    debug(category: string, message: string, data?: unknown): void;
+    /** Log an info message. */
+    info(category: string, message: string, data?: unknown): void;
+    /** Log a warning message. */
+    warn(category: string, message: string, data?: unknown): void;
+    /** Log an error message. */
+    error(category: string, message: string, data?: unknown): void;
+    /** Get recent log entries from the ring buffer. */
+    getRecent(count?: number): LogEntry[];
+    /** Format recent logs as structured text for agent consumption. */
+    formatRecentLogs(count?: number): string;
+    /** Clear the ring buffer. */
+    clear(): void;
+    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;
+        }>;
+    };
+}
+
+/** 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;
+}
+
+/** Stack-based scene manager with push/pop/replace semantics. */
+declare class SceneManager {
+    private stack;
+    private _context;
+    private bus;
+    private assetManager;
+    /**
+     * Set the engine context.
+     * @internal
+     */
+    _setContext(context: EngineContext): void;
+    /** 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[];
+    /**
+     * 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>;
+    /** Pop the top scene. Scenes below may receive onResume(). */
+    pop(): Scene | undefined;
+    /**
+     * Replace the top scene. Old scene receives onExit().
+     * New scene receives onEnter() (after preload, if declared).
+     */
+    replace(scene: Scene): Promise<void>;
+    /** Clear all scenes. Each receives onExit() from top to bottom. */
+    clear(): void;
+    /**
+     * Flush destroy queues for all active scenes.
+     * Called by the engine during endOfFrame.
+     * @internal
+     */
+    _flushDestroyQueues(): void;
+    /** Fire onPause() for scenes that transitioned from not-paused to paused. */
+    private _firePauseTransitions;
+    /** Fire onResume() for scenes that transitioned from paused to not-paused. */
+    private _fireResumeTransitions;
+}
+
+/** Full engine state snapshot. */
+interface EngineSnapshot {
+    frameCount: number;
+    sceneStack: SceneSnapshot[];
+    entityCount: number;
+    systemCount: number;
+    errors: ErrorSnapshot;
+}
+/** Snapshot of a single entity. */
+interface EntitySnapshot {
+    id: number;
+    name: string;
+    tags: string[];
+    components: string[];
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+/** Snapshot of a scene in the stack. */
+interface SceneSnapshot {
+    name: string;
+    entityCount: number;
+    paused: boolean;
+}
+/** Snapshot of a registered system. */
+interface SystemSnapshot {
+    name: string;
+    phase: string;
+    priority: number;
+    enabled: boolean;
+}
+/** Snapshot of error boundary state. */
+interface ErrorSnapshot {
+    disabledSystems: string[];
+    disabledComponents: Array<{
+        entity: string;
+        component: string;
+        error: string;
+    }>;
+}
+/** Internal engine reference to avoid circular dependency with Engine class. */
+interface EngineRef {
+    readonly context: EngineContext;
+    readonly scenes: SceneManager;
+    readonly loop: GameLoop;
+}
+/**
+ * Programmatic state queries for testing and debugging.
+ * Exposed on `window.__yage__` in debug mode.
+ */
+declare class Inspector {
+    private engine;
+    constructor(engine: EngineRef);
+    /** Full state snapshot (serializable). */
+    snapshot(): EngineSnapshot;
+    /** Find entity by name in the active scene. */
+    getEntityByName(name: string): EntitySnapshot | undefined;
+    /** Get entity position (from Transform component). */
+    getEntityPosition(name: string): {
+        x: number;
+        y: number;
+    } | undefined;
+    /** Check if an entity has a component by class name string. */
+    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. */
+    getEntities(): EntitySnapshot[];
+    /** Get scene stack info. */
+    getSceneStack(): SceneSnapshot[];
+    /** Get active system info. */
+    getSystems(): SystemSnapshot[];
+    /** Get disabled components/systems from error boundary. */
+    getErrors(): ErrorSnapshot;
+    private findActiveEntity;
+    private findComponentByName;
+    private entityToSnapshot;
+    private getTransform;
+    private serializeComponent;
+    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;
+    };
+    "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;
+}
+
+/** Engine configuration. */
+interface EngineConfig {
+    /** Enable debug mode (Inspector API, debug logging). */
+    debug?: boolean;
+    /** Fixed timestep in ms (default: 1000/60). */
+    fixedTimestep?: number;
+    /** Max fixed steps per frame to prevent spiral of death (default: 5). */
+    maxFixedStepsPerFrame?: number;
+    /** Logger configuration. */
+    logger?: LoggerConfig;
+}
+/**
+ * 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;
+    /** The asset manager. */
+    readonly assets: AssetManager;
+    private readonly plugins;
+    private sortedPlugins;
+    private started;
+    private readonly debug;
+    constructor(config?: EngineConfig);
+    /** 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;
+}
+
+/** A typed key for service registration and resolution. */
+declare class ServiceKey<T> {
+    /** Unique string identifier for this service. */
+    readonly id: string;
+    constructor(
+    /** Unique string identifier for this service. */
+    id: string);
+    /** Phantom field to preserve the generic type. */
+    readonly _type: T;
+}
+/** Dependency injection container for engine services. */
+declare class EngineContext {
+    private services;
+    /** Register a service. Throws if the key is already registered. */
+    register<T>(key: ServiceKey<T>, service: T): void;
+    /** Resolve a service. Throws if not registered. */
+    resolve<T>(key: ServiceKey<T>): T;
+    /** Resolve a service, returning undefined if not registered. */
+    tryResolve<T>(key: ServiceKey<T>): T | undefined;
+    /** Remove a registered service. No-op if not registered. */
+    unregister<T>(key: ServiceKey<T>): void;
+    /** Check if a service is registered. */
+    has<T>(key: ServiceKey<T>): boolean;
+}
+/** Key for the Engine instance. */
+declare const EngineKey: ServiceKey<Engine>;
+/** Key for the EventBus instance. */
+declare const EventBusKey: ServiceKey<EventBus<EngineEvents>>;
+/** Key for the SceneManager instance. */
+declare const SceneManagerKey: ServiceKey<SceneManager>;
+/** Key for the Logger instance. */
+declare const LoggerKey: ServiceKey<Logger>;
+/** Key for the Inspector instance. */
+declare const InspectorKey: ServiceKey<Inspector>;
+/** Key for the QueryCache instance. */
+declare const QueryCacheKey: ServiceKey<QueryCache>;
+/** Key for the ErrorBoundary instance. */
+declare const ErrorBoundaryKey: ServiceKey<ErrorBoundary>;
+/** Key for the GameLoop instance. */
+declare const GameLoopKey: ServiceKey<GameLoop>;
+/** Key for the SystemScheduler instance. */
+declare const SystemSchedulerKey: ServiceKey<SystemScheduler>;
+/** Key for the ProcessSystem instance. */
+declare const ProcessSystemKey: ServiceKey<ProcessSystem>;
+/** Key for the AssetManager instance. */
+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.
+ *
+ * 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;
+}
+
+/** 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[];
+}
+
+/** Constructor type for components. */
+type ComponentClass<C extends Component = Component> = new (...args: never[]) => C;
+/** Game loop phase identifiers. Systems run in one specific phase. */
+declare enum Phase {
+    EarlyUpdate = "earlyUpdate",
+    FixedUpdate = "fixedUpdate",
+    Update = "update",
+    LateUpdate = "lateUpdate",
+    Render = "render",
+    EndOfFrame = "endOfFrame"
+}
+/** Plugin interface for extending the engine. */
+interface Plugin {
+    /** Unique plugin name. */
+    readonly name: string;
+    /** Semantic version string. */
+    readonly version: string;
+    /** Names of plugins this plugin depends on. */
+    readonly dependencies?: readonly string[];
+    /** Install services into the engine context. Called in topological order. */
+    install?(context: EngineContext): void | Promise<void>;
+    /** 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;
+    /** Called when the engine is destroyed. */
+    onDestroy?(): void;
+}
+/** An easing function mapping t in [0,1] to a value in [0,1]. */
+type EasingFunction = (t: number) => number;
+
+/** Any object with x and y numeric properties. */
+interface Vec2Like {
+    readonly x: number;
+    readonly y: number;
+}
+/** Immutable 2D vector. All operations return new instances. */
+declare class Vec2 implements Vec2Like {
+    /** The x component. */
+    readonly x: number;
+    /** The y component. */
+    readonly y: number;
+    /** The zero vector (0, 0). */
+    static readonly ZERO: Vec2;
+    /** The one vector (1, 1). */
+    static readonly ONE: Vec2;
+    /** Up direction (0, -1) — screen coordinates. */
+    static readonly UP: Vec2;
+    /** Down direction (0, 1) — screen coordinates. */
+    static readonly DOWN: Vec2;
+    /** Left direction (-1, 0). */
+    static readonly LEFT: Vec2;
+    /** Right direction (1, 0). */
+    static readonly RIGHT: Vec2;
+    constructor(
+    /** The x component. */
+    x: number, 
+    /** The y component. */
+    y: number);
+    /** Add another vector. */
+    add(other: Vec2Like): Vec2;
+    /** Subtract another vector. */
+    sub(other: Vec2Like): Vec2;
+    /** Scale by a scalar. */
+    scale(scalar: number): Vec2;
+    /** Component-wise multiply with another vector. */
+    multiply(other: Vec2Like): Vec2;
+    /** Dot product with another vector. */
+    dot(other: Vec2Like): number;
+    /** Cross product (z-component of the 3D cross product). */
+    cross(other: Vec2Like): number;
+    /** Magnitude of this vector. */
+    length(): number;
+    /** Squared magnitude (avoids sqrt). */
+    lengthSq(): number;
+    /** Return a unit vector in the same direction. Returns ZERO for zero-length vectors. */
+    normalize(): Vec2;
+    /** Euclidean distance to another vector. */
+    distance(other: Vec2Like): number;
+    /** Squared distance to another vector (avoids sqrt). */
+    distanceSq(other: Vec2Like): number;
+    /** Linear interpolation toward another vector. */
+    lerp(other: Vec2Like, t: number): Vec2;
+    /** Angle of this vector in radians (atan2). */
+    angle(): number;
+    /** Rotate this vector by radians. */
+    rotate(radians: number): Vec2;
+    /** Check equality with optional epsilon tolerance. */
+    equals(other: Vec2Like, epsilon?: number): boolean;
+    /** String representation. */
+    toString(): string;
+    /** Create a unit vector from an angle in radians, optionally scaled. */
+    static fromAngle(radians: number, length?: number): Vec2;
+    /** Euclidean distance between two vectors. */
+    static distance(a: Vec2Like, b: Vec2Like): number;
+    /** Linear interpolation between two vectors. */
+    static lerp(a: Vec2Like, b: Vec2Like, t: number): Vec2;
+}
+
+/** Common math utility functions. */
+declare const MathUtils: {
+    /** Linear interpolation between a and b. */
+    readonly lerp: (a: number, b: number, t: 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;
+    /** 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. */
+    readonly radToDeg: (radians: number) => number;
+    /** Move current toward target by at most step. */
+    readonly approach: (current: number, target: number, step: number) => number;
+    /** Wrap value into the range [min, max). */
+    readonly wrap: (value: number, min: number, max: number) => number;
+};
+
+/** Serialized transform state. */
+interface TransformData {
+    position: {
+        x: number;
+        y: number;
+    };
+    rotation: number;
+    scale: {
+        x: number;
+        y: number;
+    };
+}
+/** Mutable transform component for entity positioning. */
+declare class Transform extends Component {
+    private _position;
+    private _rotation;
+    private _scale;
+    private _worldPosition;
+    private _worldRotation;
+    private _worldScale;
+    private _dirty;
+    constructor(options?: {
+        position?: Vec2Like;
+        rotation?: number;
+        scale?: Vec2Like;
+    });
+    /** Local position (relative to parent, or world if no parent). */
+    get position(): Vec2;
+    set position(v: Vec2);
+    /** Local rotation in radians. */
+    get rotation(): number;
+    set rotation(v: number);
+    /** Local scale factor. */
+    get scale(): Vec2;
+    set scale(v: Vec2);
+    /** Computed world position. Recomputed lazily when dirty. */
+    get worldPosition(): Vec2;
+    /** Set position in world space. Back-computes the local position from the parent chain. */
+    set worldPosition(v: Vec2);
+    /** Computed world rotation. Recomputed lazily when dirty. */
+    get worldRotation(): number;
+    /** Set rotation in world space. Back-computes the local rotation from the parent chain. */
+    set worldRotation(v: number);
+    /** Computed world scale. Recomputed lazily when dirty. */
+    get worldScale(): Vec2;
+    /** Set position directly. */
+    setPosition(x: number, y: number): void;
+    /** Translate by an offset. */
+    translate(dx: number, dy: number): void;
+    /** Set rotation in radians. */
+    setRotation(radians: number): void;
+    /** Rotate by a delta in radians. */
+    rotate(deltaRadians: number): void;
+    /** Set scale. */
+    setScale(x: number, y: number): void;
+    /**
+     * Mark this transform and all descendant transforms as dirty.
+     * @internal
+     */
+    _markDirty(): void;
+    private _recompute;
+    serialize(): TransformData;
+    static fromSnapshot(data: TransformData): Transform;
+}
+
+/**
+ * Built-in system that bridges the OOP and ECS worlds.
+ *
+ * Iterates all entities in non-paused scenes and calls component
+ * `update(dt)` or `fixedUpdate(dt)` methods on enabled components.
+ *
+ * This system runs at two phases:
+ * - Phase.FixedUpdate for fixedUpdate(dt)
+ * - Phase.Update for update(dt)
+ *
+ * We actually register two separate instances — one per phase — since
+ * a System can only belong to one phase.
+ */
+declare abstract class BaseComponentUpdateSystem extends System {
+    /** High priority so game logic runs after engine systems like physics. */
+    readonly priority = 1000;
+    protected sceneManager: SceneManager;
+    protected errorBoundary: ErrorBoundary;
+    onRegister(context: EngineContext): void;
+}
+/** Calls `fixedUpdate(dt)` on all enabled components in non-paused scenes. */
+declare class ComponentFixedUpdateSystem extends BaseComponentUpdateSystem {
+    readonly phase = Phase.FixedUpdate;
+    update(dt: number): void;
+}
+/** Calls `update(dt)` on all enabled components in non-paused scenes. */
+declare class ComponentUpdateSystem extends BaseComponentUpdateSystem {
+    readonly phase = Phase.Update;
+    update(dt: number): void;
+}
+
+/** Static factory for creating tween Processes. */
+declare const Tween: {
+    /** Tween a numeric property on a target object. */
+    to(target: Record<string, number>, property: string, to: number, duration: number, easing?: EasingFunction): Process;
+    /** Tween using a custom setter. */
+    custom(setter: (value: number) => void, from: number, to: number, duration: number, easing?: EasingFunction): Process;
+    /** Tween a Vec2 value. */
+    vec2(setter: (value: Vec2) => void, from: Vec2Like, to: Vec2Like, duration: number, easing?: EasingFunction): Process;
+};
+
+/** Types that can be interpolated by keyframe tracks. */
+type Interpolatable = number | Vec2Like;
+/**
+ * Interpolate between two values of the same type.
+ * - `number` → linear interpolation
+ * - `Vec2Like` → component-wise lerp, returns `Vec2`
+ */
+declare function interpolate<T extends Interpolatable>(from: T, to: T, t: number, easing?: EasingFunction): T;
+
+/** A single keyframe in an animation track. */
+interface Keyframe<T extends Interpolatable> {
+    /** Time in ms from the start of the track. */
+    time: number;
+    /** Value at this keyframe. */
+    data: T;
+    /** Easing from this keyframe to the next (overrides track default). */
+    easing?: EasingFunction;
+    /** Fired once when playback passes this keyframe's time. */
+    event?: () => void;
+}
+/** Options for creating a keyframe track. */
+interface KeyframeTrackOptions<T extends Interpolatable> {
+    /** At least 2 keyframes, sorted by time. */
+    keyframes: Keyframe<T>[];
+    /** Called each frame with the interpolated value. */
+    setter: (value: T) => void;
+    /** Total duration in ms. Defaults to the last keyframe's time. */
+    duration?: number;
+    /** Whether to loop the track. */
+    loop?: boolean;
+    /** Playback speed multiplier (default 1). */
+    speed?: number;
+    /** Default easing between keyframes (default easeLinear). */
+    easing?: EasingFunction;
+    /** Called when the track completes (non-looping only). */
+    onComplete?: () => void;
+}
+/**
+ * Create a Process that animates through keyframes.
+ * Returns a standard Process — composable with Sequence, ProcessComponent.run(), etc.
+ */
+declare function createKeyframeTrack<T extends Interpolatable>(options: KeyframeTrackOptions<T>): Process;
+
+/** Definition for a named keyframe animation. */
+interface KeyframeAnimationDef<T extends Interpolatable = Interpolatable> {
+    keyframes: Keyframe<T>[];
+    setter: (value: T) => void;
+    loop?: boolean;
+    speed?: number;
+    duration?: number;
+    easing?: EasingFunction;
+    onEnter?: () => void;
+    onExit?: (complete: boolean) => void;
+}
+/**
+ * Component that manages named keyframe animations.
+ *
+ * Multiple animations can play concurrently (bob + pulse).
+ * Each animation runs as a Process on the sibling ProcessComponent.
+ * Requires a sibling ProcessComponent on the same entity.
+ */
+declare class KeyframeAnimator<T extends string = string> extends Component {
+    private readonly defs;
+    private readonly active;
+    private readonly pc;
+    constructor(animations: Record<T, KeyframeAnimationDef>);
+    /** Start (or restart) a named animation. */
+    play(name: T): void;
+    /** Stop a named animation. */
+    stop(name: T): void;
+    /** Stop all playing animations. */
+    stopAll(): void;
+    /** Whether a named animation is currently playing. */
+    isPlaying(name: T): boolean;
+    onDestroy(): void;
+    private stopInternal;
+}
+
+type StepFactory = () => Process;
+/**
+ * Builds a chain of Processes that run in order.
+ * Supports sequential steps, waits, callbacks, and parallel groups.
+ */
+declare class Sequence {
+    private steps;
+    private _loop;
+    private _repeatCount;
+    /** Add a step (Process or factory function). */
+    then(step: Process | StepFactory): this;
+    /** Add a delay in ms. */
+    wait(ms: number): this;
+    /** Add an instant callback. */
+    call(fn: () => void): this;
+    /** Run steps in parallel (all must complete before sequence continues). */
+    parallel(...steps: Array<Process | StepFactory>): this;
+    /** Loop the sequence indefinitely. */
+    loop(): this;
+    /** Repeat the sequence a fixed number of times (1 = play once, 2 = play twice, etc.). */
+    repeat(times: number): this;
+    /**
+     * Build the sequence into a Process without registering with a scene.
+     * Exposed for unit testing.
+     * @internal
+     */
+    _build(): Process;
+    /** Build and start the sequence. Returns the wrapping Process. */
+    start(): Process;
+}
+
+/** Configuration for a ProcessSlot. */
+interface ProcessSlotConfig {
+    /** Auto-complete after this duration in ms. */
+    duration?: number;
+    /** Called each frame with dt (ms) and elapsed (ms). Return true to complete early. */
+    update?: (dt: number, elapsed: number) => boolean | void;
+    /** Called on natural completion only. */
+    onComplete?: () => void;
+    /** Called on complete, cancel, OR restart — like `finally`. */
+    cleanup?: () => void;
+    /** Tags for filtering. */
+    tags?: string[];
+    /** Loop the slot's process. */
+    loop?: boolean;
+}
+/**
+ * A reusable, restartable process handle owned by a ProcessComponent.
+ *
+ * Starts in `completed` state (ready to use). Call `start()` to activate.
+ * Use for cooldowns, invincibility windows, flash effects, shakes, etc.
+ */
+declare class ProcessSlot {
+    private config;
+    private _elapsed;
+    private _completed;
+    private _paused;
+    /** Tags for filtering/grouping. */
+    readonly tags: readonly string[];
+    constructor(config?: ProcessSlotConfig);
+    /** Whether the slot has completed (starts true). */
+    get completed(): boolean;
+    /** Whether the slot is actively running (not completed and not paused). */
+    get running(): boolean;
+    /** Milliseconds elapsed since start. */
+    get elapsed(): number;
+    /** Progress ratio 0..1 (elapsed / duration). 0 if no duration set. */
+    get ratio(): number;
+    /** Start the slot. No-op if already running (use restart() to force). */
+    start(overrides?: Partial<ProcessSlotConfig>): this;
+    /** Cancel if running, then start fresh. Always restarts. */
+    restart(overrides?: Partial<ProcessSlotConfig>): this;
+    /** Cancel the slot. Calls cleanup if running. */
+    cancel(): void;
+    /** Pause the slot. */
+    pause(): void;
+    /** Resume the slot. */
+    resume(): void;
+    /** Set/override the onComplete callback. Chainable. */
+    onComplete(fn: () => void): this;
+    /**
+     * Advance the slot by dt milliseconds.
+     * @internal — called by ProcessComponent
+     */
+    _tick(dt: number): void;
+    private _complete;
+}
+
+/**
+ * A component that holds a set of processes on an entity.
+ * Processes are ticked automatically by ProcessSystem each frame.
+ * All processes are cancelled when the entity is destroyed.
+ */
+declare class ProcessComponent extends Component {
+    private processes;
+    private slots;
+    /**
+     * Run a one-off process (tween, sequence, delay).
+     * Optionally apply tags for cancel-by-tag.
+     */
+    run(process: Process, options?: {
+        tags?: string[];
+    }): Process;
+    /** Create a reusable, restartable process slot. */
+    slot(config?: ProcessSlotConfig): ProcessSlot;
+    /** Cancel all processes and slots, or only those matching a tag. */
+    cancel(tag?: string): void;
+    /** Number of active (non-completed) processes and slots. */
+    get count(): number;
+    /**
+     * Advance all processes and slots by dt milliseconds and remove completed one-offs.
+     * @internal — called by ProcessSystem
+     */
+    _tick(dt: number): void;
+    /** Cancel all processes and slots on entity destroy. */
+    onDestroy(): void;
+}
+
+/**
+ * A pre-built entity that exposes the ProcessComponent API directly.
+ * Useful for scene-level timing without manual component wiring.
+ *
+ * ```ts
+ * const timers = this.spawn(TimerEntity);
+ * timers.run(Process.delay(500, () => { ... }));
+ * const cd = timers.slot({ duration: 300 });
+ * ```
+ */
+declare class TimerEntity extends Entity {
+    private pc;
+    setup(): void;
+    run(process: Process, options?: {
+        tags?: string[];
+    }): Process;
+    slot(config?: ProcessSlotConfig): ProcessSlot;
+    cancel(tag?: string): void;
+}
+
+/** 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. */
+declare function createMockScene(name?: string): {
+    scene: Scene;
+    context: EngineContext;
+};
+/** Create a mock entity spawned in a mock scene with full EngineContext access. */
+declare function createMockEntity(name?: string): {
+    entity: Entity;
+    scene: Scene;
+    context: EngineContext;
+};
+/** Advance the game loop by N frames (manual tick). */
+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 };