ecspresso 0.10.2 → 0.12.0

package/dist/ecspresso.d.ts

@@ -1,29 +1,33 @@
 import EntityManager from "./entity-manager";
 import EventBus from "./event-bus";
+import { type ResourceFactoryWithDeps, type ResourceDirectValue } from "./resource-manager";
 import AssetManager from "./asset-manager";
 import ScreenManager from "./screen-manager";
 import { type ReactiveQueryDefinition } from "./reactive-query-manager";
 import CommandBuffer from "./command-buffer";
 import type { System, SystemPhase, FilteredEntity, Entity, RemoveEntityOptions, HierarchyEntry, HierarchyIteratorOptions } from "./types";
-import type Bundle from "./bundle";
-import type { BundlesAreCompatible } from "./type-utils";
-import type { AssetHandle, AssetConfigurator } from "./asset-types";
-import type { ScreenDefinition, ScreenConfigurator } from "./screen-types";
+import { type Plugin } from "./plugin";
+import { SystemBuilder } from "./system-builder";
+import type { AssetDefinition, AssetHandle } from "./asset-types";
+import type { ScreenDefinition } from "./screen-types";
+import { ECSpressoBuilder } from "./ecspresso-builder";
+import type { WorldConfig, EmptyConfig } from "./type-utils";
 /**
     * Interface declaration for ECSpresso constructor to ensure type augmentation works properly.
     * This merges with the class declaration below.
 */
-export default interface ECSpresso<ComponentTypes extends Record<string, any> = {}, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, ScreenDefinition<any, any>> = {}> {
+export default interface ECSpresso<Cfg extends WorldConfig = EmptyConfig, Labels extends string = string, Groups extends string = string, AssetGroupNames extends string = string, ReactiveQueryNames extends string = string> {
     /**
         * Default constructor
     */
-    new (): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
+    new (): ECSpresso<Cfg, Labels, Groups, AssetGroupNames, ReactiveQueryNames>;
 }
 /**
     * ECSpresso is the central ECS framework class that connects all features.
     * It handles creation and management of entities, components, and systems, and provides lifecycle hooks.
 */
-export default class ECSpresso<ComponentTypes extends Record<string, any> = {}, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}, AssetTypes extends Record<string, unknown> = {}, ScreenStates extends Record<string, ScreenDefinition<any, any>> = {}> {
+export default class ECSpresso<Cfg extends WorldConfig = EmptyConfig, Labels extends string = string, Groups extends string = string, AssetGroupNames extends string = string, ReactiveQueryNames extends string = string> {
+    readonly _cfg: Cfg;
     /** Library version*/
     static readonly VERSION: string;
     /** Access/modify stored components and entities*/
@@ -38,8 +42,8 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     private _systems;
     /** Systems grouped by execution phase, each sorted by priority */
     private _phaseSystems;
-    /** Track installed bundles to prevent duplicates*/
-    private _installedBundles;
+    /** Track installed plugins to prevent duplicates*/
+    private _installedPlugins;
     /** Disabled system groups */
     private _disabledGroups;
     /** Asset manager for loading and accessing assets */
@@ -64,36 +68,71 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     private _interpolationAlpha;
     /** Maximum fixed update steps per frame (spiral-of-death protection) */
     private _maxFixedSteps;
+    /** Registry of required component relationships: trigger -> [{component, factory}] */
+    private _requiredComponents;
+    /** Pending plugin assets awaiting manager creation at build time */
+    private _pendingPluginAssets;
+    /** Pending plugin screens awaiting manager creation at build time */
+    private _pendingPluginScreens;
+    /** Whether diagnostics timing collection is enabled */
+    private _diagnosticsEnabled;
+    /** Per-system timing in ms, populated when diagnostics enabled */
+    private _systemTimings;
+    /** Per-phase timing in ms, populated when diagnostics enabled */
+    private _phaseTimings;
+    /** Per-system per-query seen entity IDs for onEntityEnter tracking */
+    private _entityEnterTracking;
+    /** Shared reusable set for per-tick entity enter comparison (avoids allocation) */
+    private _entityEnterFrameSet;
+    /** Pre-allocated process context per system (avoids per-frame allocation) */
+    private _systemContexts;
+    /** Pending system builder finalizers to run before next update/initialize */
+    private _pendingFinalizers;
+    private _batchingRegistrations;
     /**
         * Creates a new ECSpresso instance.
     */
     constructor();
     /**
-     * Sets up component lifecycle hooks for reactive query tracking
+     * Subscribes to EntityManager lifecycle hooks for change detection,
+     * required component auto-addition, and reactive query tracking.
      * @private
      */
-    private _setupReactiveQueryHooks;
+    private _subscribeLifecycleHooks;
     /**
-        * Creates a new ECSpresso builder for type-safe bundle installation.
-        * This is the preferred way to create an ECSpresso instance with bundles.
+        * Creates a new ECSpresso builder for type-safe plugin installation.
+        * Types are inferred from the builder chain — use `.withPlugin()`,
+        * `.withComponentTypes<T>()`, `.withEventTypes<T>()`, and `.withResource()`
+        * to accumulate types without manual aggregate interfaces.
      *
         * @returns A builder instance for fluent method chaining
      *
         * @example
         * ```typescript
-        * const ecs = ECSpresso.create<BaseComponents, BaseEvents, BaseResources>()
-     *	 .withBundle(bundle1)
-     *	 .withBundle(bundle2)
+        * const ecs = ECSpresso.create()
+     *	 .withPlugin(createRenderer2DPlugin({ ... }))
+     *	 .withPlugin(createPhysics2DPlugin())
+     *	 .withComponentTypes<{ player: true; enemy: { type: string } }>()
+     *	 .withEventTypes<{ gameStart: true }>()
+     *	 .withResource('score', { value: 0 })
      *	 .build();
+     *
+     * type ECS = typeof ecs;
         * ```
     */
-    static create<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}>(): ECSpressoBuilder<C, E, R, A, S>;
+    static create<Cfg2 extends WorldConfig = EmptyConfig>(): ECSpressoBuilder<Cfg2, never, never, never, never>;
     /**
-        * Adds a system directly to this ECSpresso instance
+        * Adds a system directly to this ECSpresso instance.
+        * The system is registered when initialize() or update() is next called.
         * @param label Unique name to identify the system
         * @returns A SystemBuilder instance for method chaining
     */
-    addSystem(label: string): import("./system-builder").SystemBuilderWithEcspresso<ComponentTypes, EventTypes, ResourceTypes, {}>;
+    addSystem(label: string): SystemBuilder<Cfg>;
+    /**
+     * Finalize and register all pending system builders.
+     * @private
+     */
+    private _finalizePendingBuilders;
     /**
      * Update all systems across execution phases.
      * Phases run in order: preUpdate -> fixedUpdate -> update -> postUpdate -> render.
@@ -106,6 +145,11 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @private
      */
     private _executePhase;
+    /**
+     * Execute a non-fixed phase with optional timing, then play back the command buffer.
+     * @private
+     */
+    private _runPhase;
     /**
      * Initialize all resources and systems
      * This method:
@@ -127,7 +171,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @param keys Optional array of resource keys to initialize. If not provided, all pending resources will be initialized.
      * @returns Promise that resolves when the specified resources are initialized
      */
-    initializeResources<K extends keyof ResourceTypes>(...keys: K[]): Promise<void>;
+    initializeResources<K extends keyof Cfg['resources']>(...keys: K[]): Promise<void>;
     /**
      * Rebuild per-phase system arrays from the flat _systems list.
      * Each phase array is sorted by priority (higher first), with
@@ -141,14 +185,14 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         * @param priority The new priority value (higher values execute first)
         * @returns true if the system was found and updated, false otherwise
     */
-    updateSystemPriority(label: string, priority: number): boolean;
+    updateSystemPriority(label: Labels, priority: number): boolean;
     /**
      * Move a system to a different execution phase at runtime.
      * @param label The unique label of the system to move
      * @param phase The target phase
      * @returns true if the system was found and updated, false otherwise
      */
-    updateSystemPhase(label: string, phase: SystemPhase): boolean;
+    updateSystemPhase(label: Labels, phase: SystemPhase): boolean;
     /**
      * The interpolation alpha between fixed update steps.
      * Ranges from 0 to <1, representing how far into the next
@@ -164,64 +208,88 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * Disable a system group. Systems in this group will be skipped during update().
      * @param groupName The name of the group to disable
      */
-    disableSystemGroup(groupName: string): void;
+    disableSystemGroup(groupName: Groups): void;
     /**
      * Enable a system group. Systems in this group will run during update().
      * @param groupName The name of the group to enable
      */
-    enableSystemGroup(groupName: string): void;
+    enableSystemGroup(groupName: Groups): void;
     /**
      * Check if a system group is enabled.
      * @param groupName The name of the group to check
      * @returns true if the group is enabled (or doesn't exist), false if disabled
      */
-    isSystemGroupEnabled(groupName: string): boolean;
+    isSystemGroupEnabled(groupName: Groups): boolean;
     /**
      * Get all system labels that belong to a specific group.
      * @param groupName The name of the group
      * @returns Array of system labels in the group
      */
-    getSystemsInGroup(groupName: string): string[];
+    getSystemsInGroup(groupName: Groups): string[];
     /**
         * Remove a system by its label
         * Calls the system's onDetach method with this ECSpresso instance if defined
         * @param label The unique label of the system to remove
         * @returns true if the system was found and removed, false otherwise
     */
-    removeSystem(label: string): boolean;
+    removeSystem(label: Labels): boolean;
     /**
         * Internal method to register a system with this ECSpresso instance
         * @internal Used by SystemBuilder - replaces direct private property access
     */
-    _registerSystem(system: System<ComponentTypes, any, any, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
+    _registerSystem(system: System<Cfg, any, any>): void;
     /**
         * Check if a resource exists
     */
-    hasResource<K extends keyof ResourceTypes>(key: K): boolean;
+    hasResource<K extends keyof Cfg['resources']>(key: K): boolean;
     /**
-        * Get a resource if it exists, or undefined if not
-    */
-    getResource<K extends keyof ResourceTypes>(key: K): ResourceTypes[K];
+     * Get a resource by key. Throws if the resource is not found.
+     * @param key The resource key
+     * @returns The resource value
+     * @throws Error if resource not found
+     * @see tryGetResource — the non-throwing alternative that returns undefined
+     */
+    getResource<K extends keyof Cfg['resources']>(key: K): Cfg['resources'][K];
     /**
-        * Add a resource to the ECS instance
+     * Try to get a resource by key. Returns undefined if the resource is not found.
+     * Inspired by Bevy's `World::get_resource::<T>()` which returns `Option<&T>`.
+     *
+     * Two overloads:
+     * 1. Known key — full type safety from `ResourceTypes`
+     * 2. String key with explicit type param — for cross-plugin optional dependencies
+     *
+     * @example
+     * ```typescript
+     * // Known key (type inferred from ResourceTypes)
+     * const score = ecs.tryGetResource('score'); // ScoreResource | undefined
+     *
+     * // Cross-plugin optional dependency (caller specifies expected type)
+     * const si = ecs.tryGetResource<SpatialIndex>('spatialIndex') ?? null;
+     * ```
+     */
+    tryGetResource<K extends keyof Cfg['resources']>(key: K): Cfg['resources'][K] | undefined;
+    tryGetResource<T>(key: unknown extends T ? never : string): T | undefined;
+    /**
+        * Add a resource to the ECS instance.
+        *
+        * - Plain value → stored directly
+        * - Function → treated as a factory, called with this ECSpresso instance on first access
+        * - `{ factory, dependsOn?, onDispose? }` → factory with dependencies/disposal
+        * - `directValue(val)` → stores the value as-is (use to store functions/classes without invoking them)
     */
-    addResource<K extends keyof ResourceTypes>(key: K, resource: ResourceTypes[K] | ((ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]>) | {
-        dependsOn?: readonly string[];
-        factory: (ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]>;
-        onDispose?: (resource: ResourceTypes[K], ecs?: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => void | Promise<void>;
-    }): this;
+    addResource<K extends keyof Cfg['resources']>(key: K, resource: Cfg['resources'][K] | ((ecs: ECSpresso<Cfg>) => Cfg['resources'][K] | Promise<Cfg['resources'][K]>) | ResourceFactoryWithDeps<Cfg['resources'][K], ECSpresso<Cfg>, keyof Cfg['resources'] & string> | ResourceDirectValue<Cfg['resources'][K]>): this;
     /**
         * Remove a resource from the ECS instance (without calling onDispose)
         * @param key The resource key to remove
         * @returns True if the resource was removed, false if it didn't exist
     */
-    removeResource<K extends keyof ResourceTypes>(key: K): boolean;
+    removeResource<K extends keyof Cfg['resources']>(key: K): boolean;
     /**
      * Dispose a single resource, calling its onDispose callback if defined
      * @param key The resource key to dispose
      * @returns True if the resource existed and was disposed, false if it didn't exist
      */
-    disposeResource<K extends keyof ResourceTypes>(key: K): Promise<boolean>;
+    disposeResource<K extends keyof Cfg['resources']>(key: K): Promise<boolean>;
     /**
      * Dispose all initialized resources in reverse dependency order.
      * Resources that depend on others are disposed first.
@@ -235,34 +303,64 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         * @returns This ECSpresso instance for chaining
         * @throws Error if the resource doesn't exist
     */
-    updateResource<K extends keyof ResourceTypes>(key: K, updater: (current: ResourceTypes[K]) => ResourceTypes[K]): this;
+    updateResource<K extends keyof Cfg['resources']>(key: K, updater: (current: Cfg['resources'][K]) => Cfg['resources'][K]): this;
     /**
         * Get all resource keys that are currently registered
         * @returns Array of resource keys
     */
-    getResourceKeys(): Array<keyof ResourceTypes>;
+    getResourceKeys(): Array<keyof Cfg['resources']>;
     /**
         * Check if a resource needs initialization (was added as a factory function)
         * @param key The resource key to check
         * @returns True if the resource needs initialization
     */
-    resourceNeedsInitialization<K extends keyof ResourceTypes>(key: K): boolean;
+    resourceNeedsInitialization<K extends keyof Cfg['resources']>(key: K): boolean;
+    /**
+        * Get a component value from an entity.
+        * @param entityId The entity ID
+        * @param componentName The component to retrieve
+        * @returns The component value, or undefined if the entity doesn't have it
+    */
+    getComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K): Cfg['components'][K] | undefined;
+    /**
+        * Add or replace a component on an entity.
+        * Triggers component-added callbacks and marks the component as changed.
+        * @param entityId The entity ID
+        * @param componentName The component to add
+        * @param value The component value
+    */
+    addComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K, value: Cfg['components'][K]): void;
+    /**
+        * Add multiple components to an entity at once.
+        * @param entityId The entity ID
+        * @param components Object with component names as keys and component data as values
+    */
+    addComponents<T extends {
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(entityId: number, components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): void;
+    /**
+        * Remove a component from an entity.
+        * Triggers component-removed and dispose callbacks.
+        * @param entityId The entity ID
+        * @param componentName The component to remove
+    */
+    removeComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K): void;
     /**
         * Check if an entity has a component
     */
-    hasComponent<K extends keyof ComponentTypes>(entityId: number, componentName: K): boolean;
+    hasComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K): boolean;
     /**
         * Create an entity and add components to it in one call
         * @param components Object with component names as keys and component data as values
         * @returns The created entity with all components added
         */
     spawn<T extends {
-        [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes, never>;
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): FilteredEntity<Cfg['components'], keyof T & keyof Cfg['components']>;
     /**
         * Get all entities with specific components
     */
-    getEntitiesWithQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>, changedComponents?: ReadonlyArray<keyof ComponentTypes>, parentHas?: ReadonlyArray<keyof ComponentTypes>): Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>;
+    getEntitiesWithQuery<WithComponents extends keyof Cfg['components'], WithoutComponents extends keyof Cfg['components'] = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>, changedComponents?: ReadonlyArray<keyof Cfg['components']>, parentHas?: ReadonlyArray<keyof Cfg['components']>): Array<FilteredEntity<Cfg['components'], WithComponents, WithoutComponents>>;
     /**
      * Get the single entity matching a query. Throws if zero or more than one match.
      * @param withComponents Components the entity must have
@@ -270,7 +368,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @returns The single matching entity
      * @throws If zero or more than one entity matches
      */
-    getSingleton<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>;
+    getSingleton<WithComponents extends keyof Cfg['components'], WithoutComponents extends keyof Cfg['components'] = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): FilteredEntity<Cfg['components'], WithComponents, WithoutComponents>;
     /**
      * Get the single entity matching a query, or undefined if none match.
      * Throws if more than one entity matches.
@@ -279,14 +377,14 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @returns The single matching entity, or undefined if none match
      * @throws If more than one entity matches
      */
-    tryGetSingleton<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): FilteredEntity<ComponentTypes, WithComponents, WithoutComponents> | undefined;
+    tryGetSingleton<WithComponents extends keyof Cfg['components'], WithoutComponents extends keyof Cfg['components'] = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): FilteredEntity<Cfg['components'], WithComponents, WithoutComponents> | undefined;
     /**
      * Remove an entity (and optionally its descendants)
-     * @param entityOrId Entity or entity ID to remove
+     * @param entityId Entity ID to remove
      * @param options Options for removal (cascade: true by default)
      * @returns true if entity was removed
      */
-    removeEntity(entityOrId: number | Entity<ComponentTypes>, options?: RemoveEntityOptions): boolean;
+    removeEntity(entityId: number, options?: RemoveEntityOptions): boolean;
     /**
      * Create an entity as a child of another entity with initial components
      * @param parentId The parent entity ID
@@ -294,81 +392,81 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @returns The created child entity
      */
     spawnChild<T extends {
-        [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes, never>;
+        [K in keyof Cfg['components']]?: Cfg['components'][K];
+    }>(parentId: number, components: T & Record<Exclude<keyof T, keyof Cfg['components']>, never>): FilteredEntity<Cfg['components'], keyof T & keyof Cfg['components']>;
     /**
      * Set the parent of an entity
-     * @param childId The entity to set as a child
-     * @param parentId The entity to set as the parent
+     * @param childId The entity ID to set as a child
+     * @param parentId The entity ID to set as the parent
      */
     setParent(childId: number, parentId: number): this;
     /**
      * Remove the parent relationship for an entity (orphan it)
-     * @param childId The entity to orphan
+     * @param childId The entity ID to orphan
      * @returns true if a parent was removed, false if entity had no parent
      */
     removeParent(childId: number): boolean;
     /**
      * Get the parent of an entity
-     * @param entityId The entity to get the parent of
+     * @param entityId The entity ID to get the parent of
      * @returns The parent entity ID, or null if no parent
      */
     getParent(entityId: number): number | null;
     /**
      * Get all children of an entity in insertion order
-     * @param parentId The parent entity
+     * @param parentId The parent entity ID
      * @returns Readonly array of child entity IDs
      */
     getChildren(parentId: number): readonly number[];
     /**
      * Get a child at a specific index
-     * @param parentId The parent entity
+     * @param parentId The parent entity ID
      * @param index The index of the child
      * @returns The child entity ID, or null if index is out of bounds
      */
     getChildAt(parentId: number, index: number): number | null;
     /**
      * Get the index of a child within its parent's children list
-     * @param parentId The parent entity
-     * @param childId The child entity to find
+     * @param parentId The parent entity ID
+     * @param childId The child entity ID to find
      * @returns The index of the child, or -1 if not found
      */
     getChildIndex(parentId: number, childId: number): number;
     /**
      * Get all ancestors of an entity in order [parent, grandparent, ...]
-     * @param entityId The entity to get ancestors of
+     * @param entityId The entity ID to get ancestors of
      * @returns Readonly array of ancestor entity IDs
      */
     getAncestors(entityId: number): readonly number[];
     /**
      * Get all descendants of an entity in depth-first order
-     * @param entityId The entity to get descendants of
+     * @param entityId The entity ID to get descendants of
      * @returns Readonly array of descendant entity IDs
      */
     getDescendants(entityId: number): readonly number[];
     /**
      * Get the root ancestor of an entity (topmost parent), or self if no parent
-     * @param entityId The entity to get the root of
+     * @param entityId The entity ID to get the root of
      * @returns The root entity ID
      */
     getRoot(entityId: number): number;
     /**
      * Get siblings of an entity (other children of the same parent)
-     * @param entityId The entity to get siblings of
+     * @param entityId The entity ID to get siblings of
      * @returns Readonly array of sibling entity IDs
      */
     getSiblings(entityId: number): readonly number[];
     /**
      * Check if an entity is a descendant of another entity
-     * @param entityId The potential descendant
-     * @param ancestorId The potential ancestor
+     * @param entityId The potential descendant ID
+     * @param ancestorId The potential ancestor ID
      * @returns true if entityId is a descendant of ancestorId
      */
     isDescendantOf(entityId: number, ancestorId: number): boolean;
     /**
      * Check if an entity is an ancestor of another entity
-     * @param entityId The potential ancestor
-     * @param descendantId The potential descendant
+     * @param entityId The potential ancestor ID
+     * @param descendantId The potential descendant ID
      * @returns true if entityId is an ancestor of descendantId
      */
     isAncestorOf(entityId: number, descendantId: number): boolean;
@@ -397,11 +495,11 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      */
     private _emitHierarchyChanged;
     /**
-        * Get all installed bundle IDs
+        * Get all installed plugin IDs
     */
-    get installedBundles(): string[];
-    get entityManager(): EntityManager<ComponentTypes>;
-    get eventBus(): EventBus<EventTypes>;
+    get installedPlugins(): string[];
+    get entityManager(): EntityManager<Cfg["components"]>;
+    get eventBus(): EventBus<Cfg["events"]>;
     /**
      * Command buffer for queuing deferred structural changes.
      * Commands are executed automatically at the end of each update() cycle.
@@ -413,7 +511,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * ecs.commands.spawn({ position: { x: 0, y: 0 } });
      * ```
      */
-    get commands(): CommandBuffer<ComponentTypes, EventTypes, ResourceTypes>;
+    get commands(): CommandBuffer<Cfg>;
     /**
      * The current tick number, incremented at the end of each update()
      */
@@ -425,6 +523,25 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * Manual change detection should compare: getChangeSeq(...) > changeThreshold
      */
     get changeThreshold(): number;
+    /**
+     * Toggle diagnostics timing collection. When enabled, system and phase
+     * timings are recorded each frame. When disabled, timing maps are cleared
+     * and no overhead is incurred.
+     */
+    enableDiagnostics(enabled: boolean): void;
+    get diagnosticsEnabled(): boolean;
+    get systemTimings(): ReadonlyMap<string, number>;
+    get phaseTimings(): Readonly<Record<SystemPhase, number>>;
+    get entityCount(): number;
+    /**
+     * Mutate a component in place and automatically mark it as changed.
+     * Throws if the entity does not exist or does not have the component.
+     * @param entityId The entity ID
+     * @param componentName The component to mutate
+     * @param mutator A function that receives the component value for in-place mutation
+     * @returns The mutated component value
+     */
+    mutateComponent<K extends keyof Cfg['components']>(entityId: number, componentName: K, mutator: (value: Cfg['components'][K]) => void): Cfg['components'][K];
     /**
      * Mark a component as changed on an entity.
      * Each call increments a global monotonic sequence; systems with changed
@@ -432,93 +549,130 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * @param entityId The entity ID
      * @param componentName The component that was changed
      */
-    markChanged<K extends keyof ComponentTypes>(entityId: number, componentName: K): void;
+    markChanged<K extends keyof Cfg['components']>(entityId: number, componentName: K): void;
+    /**
+     * Register a dispose callback for a component type.
+     * Called when a component is removed (explicit removal, entity destruction, or replacement).
+     * Later registrations replace earlier ones for the same component type.
+     * @param componentName The component type to register disposal for
+     * @param callback Function receiving the component value being disposed and the entity ID
+     */
+    registerDispose<K extends keyof Cfg['components']>(componentName: K, callback: (ctx: {
+        value: Cfg['components'][K];
+        entityId: number;
+    }) => void): void;
+    /**
+     * Register a required component relationship.
+     * When an entity gains `trigger`, the `required` component is auto-added
+     * (using `factory` for the default value) if not already present.
+     * Enforced at insertion time (spawn/addComponent) only — removal is unrestricted.
+     * @param trigger The component whose presence triggers auto-addition
+     * @param required The component to auto-add
+     * @param factory Function that creates the default value for the required component
+     */
+    registerRequired<Trigger extends keyof Cfg['components'], Required extends keyof Cfg['components']>(trigger: Trigger, required: Required, factory: (triggerValue: Cfg['components'][Trigger]) => Cfg['components'][Required]): void;
+    /**
+     * Check for circular dependencies in the required components graph.
+     * @throws Error if adding trigger→newRequired would create a cycle
+     */
+    private _checkRequiredCycle;
     /**
      * Register a callback when a specific component is added to any entity
      * @param componentName The component key
      * @param handler Function receiving the new component value and the entity
      * @returns Unsubscribe function to remove the callback
      */
-    onComponentAdded<K extends keyof ComponentTypes>(componentName: K, handler: (value: ComponentTypes[K], entity: Entity<ComponentTypes>) => void): () => void;
+    onComponentAdded<K extends keyof Cfg['components']>(componentName: K, handler: (ctx: {
+        value: Cfg['components'][K];
+        entity: Entity<Cfg['components']>;
+    }) => void): () => void;
     /**
      * Register a callback when a specific component is removed from any entity
      * @param componentName The component key
      * @param handler Function receiving the old component value and the entity
      * @returns Unsubscribe function to remove the callback
      */
-    onComponentRemoved<K extends keyof ComponentTypes>(componentName: K, handler: (oldValue: ComponentTypes[K], entity: Entity<ComponentTypes>) => void): () => void;
+    onComponentRemoved<K extends keyof Cfg['components']>(componentName: K, handler: (ctx: {
+        value: Cfg['components'][K];
+        entity: Entity<Cfg['components']>;
+    }) => void): () => void;
     /**
      * Add a reactive query that triggers callbacks when entities enter/exit the query match.
      * @param name Unique name for the query
      * @param definition Query definition with with/without arrays and onEnter/onExit callbacks
      */
-    addReactiveQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never, OptionalComponents extends keyof ComponentTypes = never>(name: string, definition: ReactiveQueryDefinition<ComponentTypes, WithComponents, WithoutComponents, OptionalComponents>): void;
+    addReactiveQuery<WithComponents extends keyof Cfg['components'], WithoutComponents extends keyof Cfg['components'] = never, OptionalComponents extends keyof Cfg['components'] = never>(name: ReactiveQueryNames, definition: ReactiveQueryDefinition<Cfg['components'], WithComponents, WithoutComponents, OptionalComponents>): void;
     /**
      * Remove a reactive query by name.
      * @param name Name of the query to remove
      * @returns true if the query existed and was removed, false otherwise
      */
-    removeReactiveQuery(name: string): boolean;
+    removeReactiveQuery(name: ReactiveQueryNames): boolean;
     /**
      * Subscribe to an event (convenience wrapper for eventBus.subscribe)
      * @param eventType The event type to subscribe to
      * @param callback The callback to invoke when the event is published
      * @returns An unsubscribe function
      */
-    on<E extends keyof EventTypes>(eventType: E, callback: (data: EventTypes[E]) => void): () => void;
+    on<E extends keyof Cfg['events']>(eventType: E, callback: (data: Cfg['events'][E]) => void): () => void;
     /**
      * Unsubscribe from an event by callback reference (convenience wrapper for eventBus.unsubscribe)
      * @param eventType The event type to unsubscribe from
      * @param callback The callback to remove
      * @returns true if the callback was found and removed, false otherwise
      */
-    off<E extends keyof EventTypes>(eventType: E, callback: (data: EventTypes[E]) => void): boolean;
+    off<E extends keyof Cfg['events']>(eventType: E, callback: (data: Cfg['events'][E]) => void): boolean;
     /**
      * Register a hook that runs after all systems in update()
      * @param callback The hook to call after all systems have processed
      * @returns An unsubscribe function to remove the hook
      */
-    onPostUpdate(callback: (ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>, deltaTime: number) => void): () => void;
+    onPostUpdate(callback: (ctx: {
+        ecs: ECSpresso<Cfg>;
+        dt: number;
+    }) => void): () => void;
+    private requireAssetManager;
     /**
      * Get a loaded asset by key. Throws if not loaded.
      */
-    getAsset<K extends keyof AssetTypes>(key: K): AssetTypes[K];
+    getAsset<K extends keyof Cfg['assets']>(key: K): Cfg['assets'][K];
     /**
      * Get a loaded asset or undefined if not loaded
      */
-    getAssetOrUndefined<K extends keyof AssetTypes>(key: K): AssetTypes[K] | undefined;
+    tryGetAsset<K extends keyof Cfg['assets']>(key: K): Cfg['assets'][K] | undefined;
     /**
      * Get a handle to an asset with status information
      */
-    getAssetHandle<K extends keyof AssetTypes>(key: K): AssetHandle<AssetTypes[K]>;
+    getAssetHandle<K extends keyof Cfg['assets']>(key: K): AssetHandle<Cfg['assets'][K]>;
     /**
      * Check if an asset is loaded
      */
-    isAssetLoaded<K extends keyof AssetTypes>(key: K): boolean;
+    isAssetLoaded<K extends keyof Cfg['assets']>(key: K): boolean;
     /**
      * Load a single asset
      */
-    loadAsset<K extends keyof AssetTypes>(key: K): Promise<AssetTypes[K]>;
+    loadAsset<K extends keyof Cfg['assets']>(key: K): Promise<Cfg['assets'][K]>;
     /**
      * Load all assets in a group
      */
-    loadAssetGroup(groupName: string): Promise<void>;
+    loadAssetGroup(groupName: AssetGroupNames): Promise<void>;
     /**
      * Check if all assets in a group are loaded
      */
-    isAssetGroupLoaded(groupName: string): boolean;
+    isAssetGroupLoaded(groupName: AssetGroupNames): boolean;
     /**
      * Get the loading progress of a group (0-1)
      */
-    getAssetGroupProgress(groupName: string): number;
+    getAssetGroupProgress(groupName: AssetGroupNames): number;
+    private requireScreenManager;
     /**
      * Transition to a new screen, clearing the stack
      */
-    setScreen<K extends keyof ScreenStates>(name: K, config: ScreenStates[K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
+    setScreen<K extends keyof Cfg['screens']>(name: K, config: Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
     /**
      * Push a screen onto the stack (overlay)
      */
-    pushScreen<K extends keyof ScreenStates>(name: K, config: ScreenStates[K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
+    pushScreen<K extends keyof Cfg['screens']>(name: K, config: Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? C : never): Promise<void>;
     /**
      * Pop the current screen and return to the previous one
      */
@@ -526,164 +680,124 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     /**
      * Get the current screen name
      */
-    getCurrentScreen(): keyof ScreenStates | null;
+    getCurrentScreen(): keyof Cfg['screens'] | null;
+    /**
+     * Get the current screen config (immutable), narrowed to a specific screen.
+     * Throws if the current screen doesn't match.
+     */
+    getScreenConfig<K extends keyof Cfg['screens'] & string>(screen: K): Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    /**
+     * Get the current screen config (immutable).
+     * Returns a union of all possible config types.
+     */
+    getScreenConfig(): {
+        [K in keyof Cfg['screens']]: Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    }[keyof Cfg['screens']];
+    /**
+     * Get the current screen config narrowed to a specific screen, or undefined if not on that screen.
+     */
+    tryGetScreenConfig<K extends keyof Cfg['screens'] & string>(screen: K): (Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never) | undefined;
+    /**
+     * Get the current screen config or undefined.
+     * Returns a union of all possible config types, or undefined.
+     */
+    tryGetScreenConfig(): {
+        [K in keyof Cfg['screens']]: Cfg['screens'][K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    }[keyof Cfg['screens']] | undefined;
     /**
-     * Get the current screen config (immutable)
+     * Get the current screen state (mutable), narrowed to a specific screen.
+     * Throws if the current screen doesn't match.
      */
-    getScreenConfig<K extends keyof ScreenStates>(): ScreenStates[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    getScreenState<K extends keyof Cfg['screens'] & string>(screen: K): Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never;
     /**
-     * Get the current screen config or null
+     * Get the current screen state (mutable).
+     * Returns a union of all possible state types.
      */
-    getScreenConfigOrNull<K extends keyof ScreenStates>(): (ScreenStates[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never) | null;
+    getScreenState(): {
+        [K in keyof Cfg['screens']]: Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never;
+    }[keyof Cfg['screens']];
     /**
-     * Get the current screen state (mutable)
+     * Get the current screen state narrowed to a specific screen, or undefined if not on that screen.
      */
-    getScreenState<K extends keyof ScreenStates>(): ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never;
+    tryGetScreenState<K extends keyof Cfg['screens'] & string>(screen: K): (Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never) | undefined;
     /**
-     * Get the current screen state or null
+     * Get the current screen state or undefined.
+     * Returns a union of all possible state types, or undefined.
      */
-    getScreenStateOrNull<K extends keyof ScreenStates>(): (ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never) | null;
+    tryGetScreenState(): {
+        [K in keyof Cfg['screens']]: Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never;
+    }[keyof Cfg['screens']] | undefined;
     /**
-     * Update the current screen state
+     * Update the current screen state, narrowed to a specific screen.
+     * Throws if the current screen doesn't match.
      */
-    updateScreenState<K extends keyof ScreenStates>(update: Partial<ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never> | ((current: ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never) => Partial<ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never>)): void;
+    updateScreenState<K extends keyof Cfg['screens'] & string>(screen: K, update: Partial<Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never> | ((current: Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never) => Partial<Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never>)): void;
+    /**
+     * Update the current screen state.
+     */
+    updateScreenState<K extends keyof Cfg['screens']>(update: Partial<Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never> | ((current: Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never) => Partial<Cfg['screens'][K] extends ScreenDefinition<any, infer S> ? S : never>)): void;
     /**
      * Check if a screen is the current screen
      */
-    isCurrentScreen(screenName: keyof ScreenStates): boolean;
+    isCurrentScreen(screenName: keyof Cfg['screens']): boolean;
     /**
      * Check if a screen is active (current or in stack)
      */
-    isScreenActive(screenName: keyof ScreenStates): boolean;
+    isScreenActive(screenName: keyof Cfg['screens']): boolean;
     /**
      * Get the screen stack depth
      */
     getScreenStackDepth(): number;
     /**
-     * Internal method to set the asset manager
+     * Internal method to set the asset manager and drain pending plugin assets
      * @internal Used by ECSpressoBuilder
      */
-    _setAssetManager(manager: AssetManager<AssetTypes>): void;
+    _setAssetManager(manager: AssetManager<Cfg['assets']>): void;
     /**
-     * Internal method to set the screen manager
+     * Internal method to set the screen manager and drain pending plugin screens
      * @internal Used by ECSpressoBuilder
      */
-    _setScreenManager(manager: ScreenManager<ScreenStates>): void;
+    _setScreenManager(manager: ScreenManager<Cfg['screens']>): void;
+    /** @internal */
+    _hasPendingPluginAssets(): boolean;
+    /** @internal */
+    _hasPendingPluginScreens(): boolean;
     /**
      * Internal method to set the fixed timestep interval
      * @internal Used by ECSpressoBuilder
      */
     _setFixedDt(dt: number): void;
     /**
-        * Internal method to install a bundle into this ECSpresso instance.
-        * Called by the ECSpressoBuilder during the build process.
-        * The type safety is guaranteed by the builder's type system.
-    */
-    _installBundle<C extends Record<string, any>, E extends Record<string, any>, R extends Record<string, any>, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}>(bundle: Bundle<C, E, R, A, S>): this;
-}
-/**
- * Resource factory with optional dependencies and disposal callback
- */
-type ResourceFactoryWithDeps<T> = {
-    dependsOn?: readonly string[];
-    factory: (context?: any) => T | Promise<T>;
-    onDispose?: (resource: T, context?: any) => void | Promise<void>;
-};
-/**
-    * Builder class for ECSpresso that provides fluent type-safe bundle installation.
-    * Handles type checking during build process to ensure type safety.
-*/
-export declare class ECSpressoBuilder<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}, A extends Record<string, unknown> = {}, S extends Record<string, ScreenDefinition<any, any>> = {}> {
-    /** The ECSpresso instance being built*/
-    private ecspresso;
-    /** Asset configurator for collecting asset definitions */
-    private assetConfigurator;
-    /** Screen configurator for collecting screen definitions */
-    private screenConfigurator;
-    /** Pending resources to add during build */
-    private pendingResources;
-    /** Fixed timestep interval (null means use default 1/60) */
-    private _fixedDt;
-    constructor();
-    /**
-        * Add the first bundle when starting with empty types.
-        * This overload allows any bundle to be added to an empty ECSpresso instance.
-    */
-    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>>(this: ECSpressoBuilder<{}, {}, {}, A, S>, bundle: Bundle<BC, BE, BR>): ECSpressoBuilder<BC, BE, BR, A, S>;
+     * Register an asset definition for deferred registration.
+     * @internal Used by plugins that need to register assets
+     */
+    _registerAsset(key: string, definition: AssetDefinition<unknown>): void;
     /**
-        * Add a subsequent bundle with type checking.
-        * This overload enforces bundle type compatibility.
-    */
-    withBundle<BC extends Record<string, any>, BE extends Record<string, any>, BR extends Record<string, any>>(bundle: BundlesAreCompatible<C, BC, E, BE, R, BR> extends true ? Bundle<BC, BE, BR> : never): ECSpressoBuilder<C & BC, E & BE, R & BR, A, S>;
+     * Register a screen definition for deferred registration.
+     * @internal Used by plugins that need to register screens
+     */
+    _registerScreen(name: string, definition: ScreenDefinition<any, any>): void;
     /**
-     * Add a resource during ECSpresso construction
-     * @param key The resource key
-     * @param resource The resource value, factory function, or factory with dependencies/disposal
-     * @returns This builder with updated resource types
-     *
-     * @example
-     * ```typescript
-     * ECSpresso.create<Components, Events, Resources>()
-     *   .withResource('config', { debug: true })
-     *   .withResource('counter', () => 42)
-     *   .withResource('derived', {
-     *     dependsOn: ['base'],
-     *     factory: (ecs) => ecs.getResource('base') * 2,
-     *     onDispose: (value) => console.log('Disposed:', value)
-     *   })
-     *   .build();
-     * ```
+     * Install a plugin into this ECSpresso instance.
+     * Deduplicates by plugin ID. Composite plugins call this in their install function.
      */
-    withResource<K extends string, V>(key: K, resource: V | ((context?: any) => V | Promise<V>) | ResourceFactoryWithDeps<V>): ECSpressoBuilder<C, E, R & Record<K, V>, A, S>;
+    installPlugin(plugin: Plugin<any, any, any, any, any, any>): this;
     /**
-     * Configure assets for this ECSpresso instance
-     * @param configurator Function that receives an AssetConfigurator and returns it after adding assets
-     * @returns This builder with updated asset types
-     *
-     * @example
-     * ```typescript
-     * ECSpresso.create<Components, Events, Resources>()
-     *   .withAssets(assets => assets
-     *     .add('playerSprite', () => loadTexture('player.png'))
-     *     .addGroup('level1', {
-     *       background: () => loadTexture('level1-bg.png'),
-     *       music: () => loadAudio('level1.mp3'),
-     *     })
-     *   )
-     *   .build();
-     * ```
+     * Create a plugin factory from the built world's types.
+     * Returns a definePlugin equivalent with no manual type parameters.
      */
-    withAssets<NewA extends Record<string, unknown>>(configurator: (assets: AssetConfigurator<{}>) => AssetConfigurator<NewA>): ECSpressoBuilder<C, E, R, A & NewA, S>;
+    pluginFactory(): <PL extends string = never, PG extends string = never, PAG extends string = never, PRQ extends string = never>(config: {
+        id: string;
+        install: (world: ECSpresso<Cfg>) => void;
+    }) => Plugin<Cfg, EmptyConfig, PL, PG, PAG, PRQ>;
     /**
-     * Configure screens for this ECSpresso instance
-     * @param configurator Function that receives a ScreenConfigurator and returns it after adding screens
-     * @returns This builder with updated screen types
+     * Call a helper factory with this world instance, inferring the full world type.
+     * Eliminates the need for a separate `type ECS = typeof ecs` ceremony.
      *
      * @example
      * ```typescript
-     * ECSpresso.create<Components, Events, Resources>()
-     *   .withScreens(screens => screens
-     *     .add('loading', {
-     *       initialState: () => ({ progress: 0 }),
-     *     })
-     *     .add('gameplay', {
-     *       initialState: ({ level }) => ({ score: 0, level }),
-     *       requiredAssetGroups: ['level1'],
-     *     })
-     *   )
-     *   .build();
+     * const helpers = ecs.getHelpers(createStateMachineHelpers);
      * ```
      */
-    withScreens<NewS extends Record<string, ScreenDefinition<any, any>>>(configurator: (screens: ScreenConfigurator<{}>) => ScreenConfigurator<NewS>): ECSpressoBuilder<C, E, R, A, S & NewS>;
-    /**
-     * Configure the fixed timestep interval for the fixedUpdate phase.
-     * @param dt The fixed timestep in seconds (e.g., 1/60 for 60Hz physics)
-     * @returns This builder for method chaining
-     */
-    withFixedTimestep(dt: number): this;
-    /**
-        * Complete the build process and return the built ECSpresso instance
-    */
-    build(): ECSpresso<C, E, R, A, S>;
+    getHelpers<H>(factory: (world: this) => H): H;
 }
-export {};