ecspresso 0.4.2 → 0.5.0

package/dist/asset-types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Asset management types for ECSpresso ECS framework
+ */
+/**
+ * Status of an asset in the loading lifecycle
+ */
+export type AssetStatus = 'pending' | 'loading' | 'loaded' | 'failed';
+/**
+ * Definition for an asset including its loader and configuration
+ */
+export interface AssetDefinition<T> {
+    readonly loader: () => Promise<T>;
+    readonly eager?: boolean;
+    readonly group?: string;
+}
+/**
+ * Handle to an asset that provides status information and access methods
+ */
+export interface AssetHandle<T> {
+    readonly status: AssetStatus;
+    readonly isLoaded: boolean;
+    /**
+     * Get the asset value. Throws if asset is not loaded.
+     */
+    get(): T;
+    /**
+     * Get the asset value if loaded, undefined otherwise.
+     */
+    getOrUndefined(): T | undefined;
+}
+/**
+ * Resource interface for accessing assets in systems
+ * Exposed as $assets resource
+ */
+export interface AssetsResource<A extends Record<string, unknown>> {
+    /**
+     * Get the loading status of an asset
+     */
+    getStatus<K extends keyof A>(key: K): AssetStatus;
+    /**
+     * Check if an asset is loaded
+     */
+    isLoaded<K extends keyof A>(key: K): boolean;
+    /**
+     * Check if all assets in a group are loaded
+     */
+    isGroupLoaded(groupName: string): boolean;
+    /**
+     * Get the loading progress of a group (0-1)
+     */
+    getGroupProgress(groupName: string): number;
+    /**
+     * Get a loaded asset. Throws if not loaded.
+     */
+    get<K extends keyof A>(key: K): A[K];
+    /**
+     * Get a loaded asset or undefined if not loaded
+     */
+    getOrUndefined<K extends keyof A>(key: K): A[K] | undefined;
+    /**
+     * Get a handle to an asset with status information
+     */
+    getHandle<K extends keyof A>(key: K): AssetHandle<A[K]>;
+}
+/**
+ * Events emitted by the asset system
+ */
+export interface AssetEvents {
+    assetLoaded: {
+        key: string;
+    };
+    assetFailed: {
+        key: string;
+        error: Error;
+    };
+    assetGroupLoaded: {
+        group: string;
+    };
+    assetGroupProgress: {
+        group: string;
+        progress: number;
+        loaded: number;
+        total: number;
+    };
+}
+/**
+ * Configuration for asset definitions during builder setup
+ */
+export interface AssetConfigurator<A extends Record<string, unknown>> {
+    /**
+     * Add a single eager asset
+     */
+    add<K extends string, T>(key: K, loader: () => Promise<T>): AssetConfigurator<A & Record<K, T>>;
+    /**
+     * Add a single asset with full configuration
+     */
+    addWithConfig<K extends string, T>(key: K, definition: AssetDefinition<T>): AssetConfigurator<A & Record<K, T>>;
+    /**
+     * Add a group of assets that can be loaded together
+     */
+    addGroup<G extends string, T extends Record<string, () => Promise<unknown>>>(groupName: G, assets: T): AssetConfigurator<A & {
+        [K in keyof T]: Awaited<ReturnType<T[K]>>;
+    }>;
+}

package/dist/bundle.d.ts

@@ -1,12 +1,17 @@
 import { SystemBuilderWithBundle } from './system-builder';
 import type ECSpresso from './ecspresso';
+import type { AssetDefinition } from './asset-types';
+import type { ScreenDefinition } from './screen-types';
 /**
  * Bundle class that encapsulates a set of components, resources, events, and systems
  * that can be merged into a ECSpresso instance
  */
-export default class Bundle<ComponentTypes extends Record<string, any> = {}, EventTypes extends Record<string, any> = {}, ResourceTypes extends Record<string, any> = {}> {
+export default class Bundle<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>> = {}> {
     private _systems;
     private _resources;
+    private _assets;
+    private _assetGroups;
+    private _screens;
     private _id;
     constructor(id?: string);
     /**
@@ -29,6 +34,53 @@ export default class Bundle<ComponentTypes extends Record<string, any> = {}, Eve
      * @param resource The resource value or a factory function that returns the resource
      */
     addResource<K extends keyof ResourceTypes>(label: K, resource: ResourceTypes[K] | ((ecs: ECSpresso<ComponentTypes, EventTypes, ResourceTypes>) => ResourceTypes[K] | Promise<ResourceTypes[K]>)): this;
+    /**
+     * Add an asset to this bundle
+     * @param key The asset key
+     * @param loader Function that loads and returns the asset
+     * @param options Optional asset configuration
+     */
+    addAsset<K extends string, T>(key: K, loader: () => Promise<T>, options?: {
+        eager?: boolean;
+        group?: string;
+    }): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes & Record<K, T>, ScreenStates>;
+    /**
+     * Add a group of assets to this bundle
+     * @param groupName The group name
+     * @param assets Object mapping asset keys to loader functions
+     */
+    addAssetGroup<G extends string, T extends Record<string, () => Promise<unknown>>>(groupName: G, assets: T): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes & {
+        [K in keyof T]: Awaited<ReturnType<T[K]>>;
+    }, ScreenStates>;
+    /**
+     * Add a screen to this bundle
+     * @param name The screen name
+     * @param definition The screen definition
+     */
+    addScreen<K extends string, Config extends Record<string, unknown>, State extends Record<string, unknown>>(name: K, definition: ScreenDefinition<Config, State>): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates & Record<K, ScreenDefinition<Config, State>>>;
+    /**
+     * Get all asset definitions in this bundle
+     */
+    getAssets(): Map<string, AssetDefinition<unknown>>;
+    /**
+     * Get all screen definitions in this bundle
+     */
+    getScreens(): Map<string, ScreenDefinition<any, any>>;
+    /**
+     * Internal method to set a resource
+     * @internal Used by mergeBundles
+     */
+    _setResource(key: string, value: unknown): void;
+    /**
+     * Internal method to set an asset definition
+     * @internal Used by mergeBundles
+     */
+    _setAsset(key: string, definition: AssetDefinition<unknown>): void;
+    /**
+     * Internal method to set a screen definition
+     * @internal Used by mergeBundles
+     */
+    _setScreen(name: string, definition: ScreenDefinition<any, any>): void;
     /**
      * Get all systems defined in this bundle
      * Returns built System objects instead of SystemBuilders
@@ -68,16 +120,20 @@ type Exactly<T, U> = T extends U ? U extends T ? true : false : false;
  * Simplified type constraint for bundle compatibility
  * Ensures that overlapping keys have exactly the same types
  */
-type CompatibleBundles<C1 extends Record<string, any>, C2 extends Record<string, any>, E1 extends Record<string, any>, E2 extends Record<string, any>, R1 extends Record<string, any>, R2 extends Record<string, any>> = {
+type CompatibleBundles<C1 extends Record<string, any>, C2 extends Record<string, any>, E1 extends Record<string, any>, E2 extends Record<string, any>, R1 extends Record<string, any>, R2 extends Record<string, any>, A1 extends Record<string, unknown> = {}, A2 extends Record<string, unknown> = {}, S1 extends Record<string, ScreenDefinition<any, any>> = {}, S2 extends Record<string, ScreenDefinition<any, any>> = {}> = {
     [K in keyof C1 & keyof C2]: Exactly<C1[K], C2[K]> extends true ? C1[K] : never;
 } & {
     [K in keyof E1 & keyof E2]: Exactly<E1[K], E2[K]> extends true ? E1[K] : never;
 } & {
     [K in keyof R1 & keyof R2]: Exactly<R1[K], R2[K]> extends true ? R1[K] : never;
+} & {
+    [K in keyof A1 & keyof A2]: Exactly<A1[K], A2[K]> extends true ? A1[K] : never;
+} & {
+    [K in keyof S1 & keyof S2]: Exactly<S1[K], S2[K]> extends true ? S1[K] : never;
 };
 /**
  * Function that merges multiple bundles into a single bundle
  */
-export declare function mergeBundles<C1 extends Record<string, any>, E1 extends Record<string, any>, R1 extends Record<string, any>, C2 extends Record<string, any>, E2 extends Record<string, any>, R2 extends Record<string, any>>(id: string, bundle1: Bundle<C1, E1, R1>, bundle2: Bundle<C2, E2, R2> & CompatibleBundles<C1, C2, E1, E2, R1, R2>): Bundle<C1 & C2, E1 & E2, R1 & R2>;
-export declare function mergeBundles<ComponentTypes extends Record<string, any>, EventTypes extends Record<string, any>, ResourceTypes extends Record<string, any>>(id: string, ...bundles: Array<Bundle<ComponentTypes, EventTypes, ResourceTypes>>): Bundle<ComponentTypes, EventTypes, ResourceTypes>;
+export declare function mergeBundles<C1 extends Record<string, any>, E1 extends Record<string, any>, R1 extends Record<string, any>, A1 extends Record<string, unknown>, S1 extends Record<string, ScreenDefinition<any, any>>, C2 extends Record<string, any>, E2 extends Record<string, any>, R2 extends Record<string, any>, A2 extends Record<string, unknown>, S2 extends Record<string, ScreenDefinition<any, any>>>(id: string, bundle1: Bundle<C1, E1, R1, A1, S1>, bundle2: Bundle<C2, E2, R2, A2, S2> & CompatibleBundles<C1, C2, E1, E2, R1, R2, A1, A2, S1, S2>): Bundle<C1 & C2, E1 & E2, R1 & R2, A1 & A2, S1 & S2>;
+export declare function mergeBundles<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>>>(id: string, ...bundles: Array<Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>>): Bundle<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
 export {};

package/dist/ecspresso.d.ts

@@ -1,23 +1,27 @@
 import EntityManager from "./entity-manager";
 import EventBus from "./event-bus";
-import type { System, FilteredEntity, Entity } from "./types";
+import AssetManager from "./asset-manager";
+import ScreenManager from "./screen-manager";
+import type { System, FilteredEntity, Entity, RemoveEntityOptions } 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";
 /**
     * 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> = {}> {
+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>> = {}> {
     /**
         * Default constructor
     */
-    new (): ECSpresso<ComponentTypes, EventTypes, ResourceTypes>;
+    new (): ECSpresso<ComponentTypes, EventTypes, ResourceTypes, AssetTypes, ScreenStates>;
 }
 /**
     * 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> = {}> {
+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>> = {}> {
     /** Library version*/
     static readonly VERSION: string;
     /** Access/modify stored components and entities*/
@@ -32,6 +36,12 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
     private _sortedSystems;
     /** Track installed bundles to prevent duplicates*/
     private _installedBundles;
+    /** Asset manager for loading and accessing assets */
+    private _assetManager;
+    /** Screen manager for state/screen transitions */
+    private _screenManager;
+    /** Post-update hooks to be called after all systems in update() */
+    private _postUpdateHooks;
     /**
         * Creates a new ECSpresso instance.
     */
@@ -50,7 +60,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      *	 .build();
         * ```
     */
-    static create<C extends Record<string, any> = {}, E extends Record<string, any> = {}, R extends Record<string, any> = {}>(): ECSpressoBuilder<C, E, R>;
+    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>;
     /**
         * Adds a system directly to this ECSpresso instance
         * @param label Unique name to identify the system
@@ -66,7 +76,9 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
      * Initialize all resources and systems
      * This method:
      * 1. Initializes all resources that were added as factory functions
-     * 2. Calls the onInitialize lifecycle hook on all systems
+     * 2. Sets up asset manager and loads eager assets
+     * 3. Sets up screen manager
+     * 4. Calls the onInitialize lifecycle hook on all systems
      *
      * This is useful for game startup to ensure all resources are ready
      * and systems are properly initialized before the game loop begins.
@@ -106,7 +118,7 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         * 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>): void;
+    _registerSystem(system: System<ComponentTypes, any, any, EventTypes, ResourceTypes, AssetTypes, ScreenStates>): void;
     /**
         * Check if a resource exists
     */
@@ -155,44 +167,300 @@ export default class ECSpresso<ComponentTypes extends Record<string, any> = {},
         */
     spawn<T extends {
         [K in keyof ComponentTypes]?: ComponentTypes[K];
-    }>(components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): Entity<ComponentTypes>;
+    }>(components: T & Record<Exclude<keyof T, keyof ComponentTypes>, never>): FilteredEntity<ComponentTypes, keyof T & keyof ComponentTypes, never>;
     /**
         * Get all entities with specific components
     */
     getEntitiesWithQuery<WithComponents extends keyof ComponentTypes, WithoutComponents extends keyof ComponentTypes = never>(withComponents: ReadonlyArray<WithComponents>, withoutComponents?: ReadonlyArray<WithoutComponents>): Array<FilteredEntity<ComponentTypes, WithComponents, WithoutComponents>>;
+    /**
+     * Remove an entity (and optionally its descendants)
+     * @param entityOrId Entity or 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;
+    /**
+     * Create an entity as a child of another entity with initial components
+     * @param parentId The parent entity ID
+     * @param components Initial components to add
+     * @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>;
+    /**
+     * Set the parent of an entity
+     * @param childId The entity to set as a child
+     * @param parentId The entity 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
+     * @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
+     * @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
+     * @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 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
+     * @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
+     * @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
+     * @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
+     * @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
+     * @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
+     * @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
+     * @returns true if entityId is an ancestor of descendantId
+     */
+    isAncestorOf(entityId: number, descendantId: number): boolean;
+    /**
+     * Get all root entities (entities that have children but no parent)
+     * @returns Readonly array of root entity IDs
+     */
+    getRootEntities(): readonly number[];
+    /**
+     * Emit a hierarchy changed event
+     * @internal
+     */
+    private _emitHierarchyChanged;
     /**
         * Get all installed bundle IDs
     */
     get installedBundles(): string[];
     get entityManager(): EntityManager<ComponentTypes>;
     get eventBus(): EventBus<EventTypes>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Get a loaded asset by key. Throws if not loaded.
+     */
+    getAsset<K extends keyof AssetTypes>(key: K): AssetTypes[K];
+    /**
+     * Get a loaded asset or undefined if not loaded
+     */
+    getAssetOrUndefined<K extends keyof AssetTypes>(key: K): AssetTypes[K] | undefined;
+    /**
+     * Get a handle to an asset with status information
+     */
+    getAssetHandle<K extends keyof AssetTypes>(key: K): AssetHandle<AssetTypes[K]>;
+    /**
+     * Check if an asset is loaded
+     */
+    isAssetLoaded<K extends keyof AssetTypes>(key: K): boolean;
+    /**
+     * Load a single asset
+     */
+    loadAsset<K extends keyof AssetTypes>(key: K): Promise<AssetTypes[K]>;
+    /**
+     * Load all assets in a group
+     */
+    loadAssetGroup(groupName: string): Promise<void>;
+    /**
+     * Check if all assets in a group are loaded
+     */
+    isAssetGroupLoaded(groupName: string): boolean;
+    /**
+     * Get the loading progress of a group (0-1)
+     */
+    getAssetGroupProgress(groupName: string): number;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Pop the current screen and return to the previous one
+     */
+    popScreen(): Promise<void>;
+    /**
+     * Get the current screen name
+     */
+    getCurrentScreen(): keyof ScreenStates | null;
+    /**
+     * Get the current screen config (immutable)
+     */
+    getScreenConfig<K extends keyof ScreenStates>(): ScreenStates[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never;
+    /**
+     * Get the current screen config or null
+     */
+    getScreenConfigOrNull<K extends keyof ScreenStates>(): (ScreenStates[K] extends ScreenDefinition<infer C, any> ? Readonly<C> : never) | null;
+    /**
+     * Get the current screen state (mutable)
+     */
+    getScreenState<K extends keyof ScreenStates>(): ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never;
+    /**
+     * Get the current screen state or null
+     */
+    getScreenStateOrNull<K extends keyof ScreenStates>(): (ScreenStates[K] extends ScreenDefinition<any, infer S> ? S : never) | null;
+    /**
+     * Update the current screen state
+     */
+    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;
+    /**
+     * Check if a screen is the current screen
+     */
+    isCurrentScreen(screenName: keyof ScreenStates): boolean;
+    /**
+     * Check if a screen is active (current or in stack)
+     */
+    isScreenActive(screenName: keyof ScreenStates): boolean;
+    /**
+     * Get the screen stack depth
+     */
+    getScreenStackDepth(): number;
+    /**
+     * Internal method to set the asset manager
+     * @internal Used by ECSpressoBuilder
+     */
+    _setAssetManager(manager: AssetManager<AssetTypes>): void;
+    /**
+     * Internal method to set the screen manager
+     * @internal Used by ECSpressoBuilder
+     */
+    _setScreenManager(manager: ScreenManager<ScreenStates>): 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>>(bundle: Bundle<C, E, R>): this;
+    _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;
 }
 /**
     * 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> = {}> {
+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;
     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<{}, {}, {}>, bundle: Bundle<BC, BE, BR>): ECSpressoBuilder<BC, BE, BR>;
+    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>;
     /**
         * 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>;
+    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>;
+    /**
+     * 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();
+     * ```
+     */
+    withAssets<NewA extends Record<string, unknown>>(configurator: (assets: AssetConfigurator<{}>) => AssetConfigurator<NewA>): ECSpressoBuilder<C, E, R, A & NewA, S>;
+    /**
+     * 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
+     *
+     * @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();
+     * ```
+     */
+    withScreens<NewS extends Record<string, ScreenDefinition<any, any>>>(configurator: (screens: ScreenConfigurator<{}>) => ScreenConfigurator<NewS>): ECSpressoBuilder<C, E, R, A, S & NewS>;
     /**
         * Complete the build process and return the built ECSpresso instance
     */
-    build(): ECSpresso<C, E, R>;
+    build(): ECSpresso<C, E, R, A, S>;
 }