@awesome-ecs/abstract 0.29.0 → 0.30.0

package/dist/index-8XDo0pla.d.mts

@@ -0,0 +1,1065 @@
+import { _ as IEntityProxy, f as EntityTypeUid, g as EntityProxy, h as IEntityModel, i as Immutable, m as IEntity, p as EntityUid, v as IEntityProxyRepository } from "./identity-component-CuWHf7jX.mjs";
+import { c as IEntitySnapshot, d as EntityEventSubscriptionOptions, f as EntityEventUid, g as IEventData, o as IEntityUpdate, p as IEntityEvent } from "./index-kNcUiDBd.mjs";
+
+//#region src/utils/dispatch-sequential.d.ts
+/**
+ * Executes a function for each item in an iterable, sequentially.
+ *
+ * Uses a sync fast-path: iterates synchronously until the first Promise is
+ * encountered, then switches to async for the remainder. If no item produces
+ * a Promise, the entire call stays synchronous with zero async overhead.
+ *
+ * @param items - The iterable to iterate over.
+ * @param fn - The function to call for each item. May return void or a Promise.
+ * @returns void if all calls were synchronous, or a Promise if any were async.
+ */
+declare function dispatchSequential<T>(items: Iterable<T>, fn: (item: T) => void | Promise<void>): void | Promise<void>;
+//#endregion
+//#region src/utils/json-serializer.d.ts
+/**
+ * Custom JSON serialization and deserialization interface.
+ * Allows different serialization strategies for handling complex types.
+ * Used for entity snapshots, events, and any data needing JSON conversion.
+ */
+interface IJsonSerializer {
+  /**
+   * Converts an object to a serializable JSON representation.
+   * Handles types that don't serialize naturally (dates, maps, custom objects, etc.).
+   * @param value - The object to serialize.
+   * @returns A JSON-serializable representation.
+   */
+  serializeCustom(value: object): string;
+  /**
+   * Converts a JSON string back to its original object type.
+   * Reconstructs complex types from their serialized form.
+   * @template TObject - The target object type.
+   * @param text - The JSON string to deserialize.
+   * @returns The deserialized object of the specified type.
+   */
+  parseCustom<TObject>(text: string): TObject;
+}
+//#endregion
+//#region src/utils/logger.d.ts
+/**
+ * Logger interface for debug and diagnostic output.
+ * Supports multiple log levels for controlling verbosity.
+ * Implementations can target different outputs (console, file, remote, etc.).
+ */
+interface ILogger {
+  /**
+   * Logs a message with a specified severity level.
+   * @param level - The severity level of the message.
+   * @param message - The primary message content.
+   * @param args - Additional arguments to include in the log output.
+   */
+  log(level: LogLevel, message: any, ...args: any[]): void;
+  /**
+   * Logs detailed diagnostic information.
+   * Typically the lowest level, most verbose output.
+   * @param message - The message to log.
+   * @param args - Additional data.
+   */
+  trace(message: any, ...args: any[]): void;
+  /**
+   * Logs debug-level information.
+   * Useful during development and troubleshooting.
+   * @param message - The message to log.
+   * @param args - Additional data.
+   */
+  debug(message: any, ...args: any[]): void;
+  /**
+   * Logs warning-level messages.
+   * Indicates potentially problematic conditions.
+   * @param message - The message to log.
+   * @param args - Additional data.
+   */
+  warn(message: any, ...args: any[]): void;
+  /**
+   * Logs error-level messages.
+   * Indicates error conditions that may require attention.
+   * @param message - The message to log.
+   * @param args - Additional data.
+   */
+  error(message: any, ...args: any[]): void;
+}
+/**
+ * Logging severity levels in increasing order.
+ */
+declare enum LogLevel {
+  /**
+   * Most detailed, diagnostic-level logging.
+   */
+  trace = 0,
+  /**
+   * Development and debugging information.
+   */
+  debug = 1,
+  /**
+   * Warning-level conditions.
+   */
+  warn = 2,
+  /**
+   * Error-level conditions.
+   */
+  error = 3
+}
+/**
+ * Configuration options for logger instances.
+ */
+interface ILoggerOptions {
+  /**
+   * Enables/disables each log level.
+   * If a level is disabled, log calls at that level are ignored.
+   */
+  enabled: Map<LogLevel, boolean>;
+}
+//#endregion
+//#region src/utils/performance.d.ts
+type TickMetricEntry = {
+  name: string;
+  category: string;
+  totalMs: number;
+  count: number;
+};
+type TickSnapshot = {
+  tickIndex: number;
+  tickDurationMs: number;
+  fps: number;
+  queueSize: number;
+  timestamp: number;
+  metrics: TickMetricEntry[];
+  render?: RenderSnapshot;
+};
+type RenderSnapshot = {
+  frameTimeMs: number;
+  renderTimeMs: number;
+  gpuFrameTimeMs: number;
+  drawCalls: number;
+  activeMeshesEvalMs: number;
+  cameraRenderMs: number;
+  totalVertices: number;
+  activeIndices: number;
+};
+type MiddlewareMetricsSummary = {
+  name: string;
+  category: PipelineCategoryName;
+  count: number;
+  totalMs: number;
+  avgMs: number;
+  minMs: number;
+  maxMs: number;
+  lastMs: number;
+};
+//#endregion
+//#region src/utils/performance-timer.d.ts
+/**
+ * Unique identifier for a timer instance.
+ */
+type PerformanceTimerUid = number;
+/**
+ * Options for identifying and categorizing performance metrics.
+ * Used by pipeline factories and performance decorators.
+ */
+type PerformanceMetricOptions = {
+  name?: string;
+  category?: string;
+};
+/**
+ * Record of a completed timer measurement.
+ * Captures timing information for performance analysis and profiling.
+ */
+interface PerformanceTimeEntry {
+  /**
+   * The name identifying this timer.
+   */
+  name: string;
+  /**
+   * The category of this metric (e.g. 'module', 'runtime', 'system').
+   */
+  category?: string;
+  /**
+   * Timestamp in milliseconds when the timer started.
+   */
+  startedAt: number;
+  /**
+   * Timestamp in milliseconds when the timer ended.
+   */
+  endedAt?: number;
+  /**
+   * Duration in milliseconds that elapsed.
+   */
+  msPassed?: number;
+}
+/**
+ * Interface for measuring operation duration.
+ * Provides start/stop functionality for performance profiling.
+ * Used throughout the system to collect timing metrics.
+ */
+interface IPerformanceTimer {
+  /**
+   * Starts a new timer.
+   * @param name - Label for this timer (used in results).
+   * @param category - Optional category for grouping metrics.
+   * @returns A unique identifier for this timer instance.
+   */
+  startTimer(name: string, category?: string): PerformanceTimerUid;
+  /**
+   * Stops a timer and returns the recorded metrics.
+   * @param timerUid - The timer identifier returned by startTimer.
+   * @returns Complete timing entry with start, end, and duration.
+   */
+  endTimer(timerUid: PerformanceTimerUid): PerformanceTimeEntry;
+}
+//#endregion
+//#region src/pipelines/pipeline-context.d.ts
+/**
+ * Base interface for all pipeline context objects.
+ * Provides hooks for runtime state and control flow during pipeline execution.
+ */
+interface IPipelineContext {
+  /**
+   * The runtime state and control interface for the pipeline.
+   * Allows middleware to query and influence pipeline behavior.
+   */
+  readonly runtime?: PipelineRuntime;
+}
+/**
+ * Runtime state and control interface for pipeline execution.
+ * Allows middleware to query status and influence pipeline flow.
+ */
+type PipelineRuntime = {
+  /**
+   * Flag to request pipeline halt.
+   * Set to true to stop executing remaining middleware (cleanup still runs).
+   */
+  shouldStop?: boolean;
+  /**
+   * Optional error state if an exception occurred during execution.
+   */
+  error?: any;
+  /**
+   * Results collected from middleware execution.
+   * Typically includes performance metrics and operational results.
+   */
+  readonly metrics?: PerformanceTimeEntry[];
+};
+//#endregion
+//#region src/pipelines/middleware.d.ts
+/**
+ * The basic unit of work in a pipeline.
+ * Middleware are chained together to form processing pipelines.
+ * Each middleware can inspect/modify context during dispatch and perform cleanup on their changes.
+ *
+ * @template TContext The context type passed through the middleware chain.
+ */
+interface IMiddleware<TContext extends IPipelineContext> {
+  /**
+   * Optional name for debugging and logging purposes.
+   */
+  readonly name?: string;
+  /**
+   * Optional guard condition before running the action.
+   * Allows middleware to skip execution based on context state.
+   * @param context The current pipeline context.
+   * @returns True to execute action, false to skip.
+   */
+  shouldRun?(context: TContext): boolean;
+  /**
+   * The main unit of work executed as part of the pipeline.
+   * Middlewares execute in registration order during dispatch phase.
+   * Can read and modify the context to influence downstream middleware and results.
+   * @param context The pipeline context containing all relevant state.
+   */
+  action(context: TContext): void | Promise<void>;
+  /**
+   * Optional cleanup function executed during pipeline teardown.
+   * Middlewares execute in reverse registration order during cleanup phase.
+   * Used to release resources, clear temporary state, and perform final operations.
+   * @param context The pipeline context (may be in modified state from action phases).
+   */
+  cleanup?(context: TContext): void | Promise<void>;
+}
+//#endregion
+//#region src/pipelines/middleware-runner.d.ts
+/**
+ * Customizes how middleware is executed within a pipeline.
+ * Allows decorators to wrap, intercept, or modify middleware execution behavior.
+ * Useful for implementing middleware decorators (logging, timing, error handling, etc.).
+ *
+ * @template TContext The type of context passed to middleware.
+ */
+interface IMiddlewareRunner<TContext extends IPipelineContext> {
+  /**
+   * Decides how to execute a middleware's action.
+   * Can add pre/post processing, error handling, or performance tracking around the middleware.
+   * @param context The current pipeline context.
+   * @param middleware The middleware whose action should be executed.
+   */
+  dispatch(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
+  /**
+   * Decides how to execute a middleware's cleanup.
+   * Can add pre/post processing or error handling around cleanup operations.
+   * @param context The current pipeline context.
+   * @param middleware The middleware whose cleanup should be executed.
+   */
+  cleanup(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
+}
+//#endregion
+//#region src/pipelines/pipeline.d.ts
+/**
+ * A composable middleware chain for ordered execution of operations.
+ * Pipelines provide a framework for registering and executing middleware with dispatch and cleanup phases.
+ * Used throughout the ECS system for entity initialization, updates, rendering, and synchronization.
+ *
+ * @template TContext - The context type passed to all registered middleware.
+ */
+interface IPipeline<TContext extends IPipelineContext> {
+  /**
+   * The pipeline's name, useful for debugging and logging.
+   */
+  readonly name?: string;
+  /**
+   * The number of middleware currently registered in this pipeline.
+   */
+  readonly length?: number;
+  /**
+   * Direct access to the ordered list of registered middleware.
+   * Allows inspection of the execution chain.
+   */
+  readonly middleware?: Immutable<IMiddleware<TContext>[]>;
+  /**
+   * Registers middleware to be executed as part of this pipeline.
+   * Middleware is added to the end of the chain and executed in registration order during dispatch.
+   * @param middleware - The middleware to register.
+   * @returns This instance for method chaining.
+   */
+  use(middleware: Immutable<IMiddleware<TContext>>): this;
+  /**
+   * Executes the dispatch phase with all registered middleware in order.
+   * Each middleware's action is called, allowing modifications to context state.
+   * Execution continues until all middleware complete or a middleware requests early termination.
+   * @param context - The context object passed to all middleware.
+   */
+  dispatch(context: Partial<TContext>): void | Promise<void>;
+  /**
+   * Executes the cleanup phase with all registered middleware in reverse order.
+   * Allows middleware to perform resource cleanup and final operations.
+   * Typically called after dispatch to ensure proper teardown.
+   *
+   * @param context - The context object that will be passed to each middleware function.
+   */
+  cleanup(context: Partial<TContext>): void | Promise<void>;
+}
+//#endregion
+//#region src/pipelines/pipeline-nested.d.ts
+/**
+ * Context for a parent pipeline containing nested pipelines.
+ * Allows coordination between outer and inner pipeline execution.
+ *
+ * @template N - The context type for the nested pipelines.
+ */
+interface IParentContext<N extends IPipelineContext> extends IPipelineContext {
+  /**
+   * The nested pipeline to execute for each context in nestedContexts.
+   */
+  readonly nestedPipeline: IPipeline<INestedContext<this>>;
+  /**
+   * Contexts to pass to the nested pipeline.
+   * The parent pipeline iterates these and executes the nested pipeline for each.
+   */
+  readonly nestedContexts: Partial<N>[];
+}
+/**
+ * Context for a nested pipeline.
+ * Provides access to both current and previous nested context data plus the parent context.
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+interface INestedContext<P extends IParentContext<any>> extends IPipelineContext {
+  /**
+   * The current context item being processed in the nested pipeline.
+   */
+  readonly current: P extends IParentContext<infer N> ? N : never;
+  /**
+   * The previous context item (if this is not the first iteration).
+   */
+  readonly previous?: P extends IParentContext<infer N> ? N : never;
+  /**
+   * Reference back to the parent pipeline context.
+   */
+  readonly parent: P;
+}
+/**
+ * Middleware executing within a nested pipeline.
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+type INestedMiddleware<P extends IParentContext<any>> = IMiddleware<INestedContext<P>>;
+/**
+ * Middleware executing within a parent pipeline (containing nested pipelines).
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+type IParentMiddleware<P extends IParentContext<any>> = IMiddleware<P>;
+//#endregion
+//#region src/pipelines/pipeline-runner.d.ts
+/**
+ * Executes an array of middleware in a controlled sequence.
+ * Supports custom execution strategies through implementation flexibility.
+ * Used by pipelines to manage complex middleware chains with features like early termination and nested pipelines.
+ *
+ * @template TContext - The context type passed to all middleware.
+ */
+interface IPipelineRunner<TContext extends IPipelineContext> {
+  /**
+   * Executes the action phase of all middleware in sequence.
+   * Middleware at startIndex and onward are executed in order.
+   * Execution may terminate early if middleware requests it via context.runtime.shouldStop.
+   * @param context - The context passed to each middleware action.
+   * @param middleware - The ordered middleware array to execute.
+   * @param startIndex - Optional starting position in the middleware array (default: 0).
+   */
+  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void | Promise<void>;
+  /**
+   * Executes the cleanup phase of all middleware in reverse order.
+   * All middleware cleanup functions are called (if defined), regardless of errors.
+   * Allows proper resource release and final state management.
+   * @param context - The context passed to each middleware cleanup.
+   * @param middleware - The ordered middleware array for cleanup (reversed during execution).
+   */
+  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void | Promise<void>;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-events.d.ts
+/**
+ * System context API for event-driven entity communication.
+ * Allows middleware to dispatch events, manage subscriptions, and query event state.
+ * Events enable decoupled communication between distant or unrelated entities.
+ */
+interface ISystemContextEvents {
+  /**
+   * Publishes an event to one or more explicit targets.
+   * The event is sent only to the specified target(s) — it does NOT fall back to subscriptions.
+   * @param data - The event payload.
+   * @param target - The entity or entities to send the event to.
+   */
+  dispatchEvent<TEventData extends IEventData>(data: TEventData, target: IEntityProxy | IEntityProxy[]): void;
+  /**
+   * Publishes multiple events to one or more explicit targets.
+   * Each target receives all events in a single update.
+   * @param data - Array of event payloads to dispatch.
+   * @param target - The entity or entities to send the events to.
+   */
+  dispatchEvents<TEventData extends IEventData>(data: TEventData[], target: IEntityProxy | IEntityProxy[]): void;
+  /**
+   * Broadcasts an event to all subscribers registered for that event type.
+   * Uses the subscription registry to resolve targets.
+   * @param data - The event payload.
+   */
+  broadcastEvent<TEventData extends IEventData>(data: TEventData): void;
+  /**
+   * Broadcasts multiple events to all subscribers.
+   * Events are grouped per subscriber so each receives a single update.
+   * @param data - Array of event payloads to broadcast.
+   */
+  broadcastEvents<TEventData extends IEventData>(data: TEventData[]): void;
+  /**
+   * Retrieves an event from the current context by its identifier.
+   * Useful for checking if an event was received this frame.
+   * @param uid - The event type identifier.
+   * @returns The event if present, undefined otherwise.
+   */
+  getEvent<TEventData extends IEventData>(uid: EntityEventUid): IEntityEvent<TEventData> | undefined;
+  /**
+   * Retrieves all events currently set on this context.
+   * Events are cleared between frames.
+   * @returns Array of all active events for this context.
+   */
+  listEvents<TEventData extends IEventData>(): IEntityEvent<TEventData>[];
+  /**
+   * Checks if a specific event is present in the current context.
+   * If no uid is provided, checks if any events exist.
+   * @param uid - Optional event type to check for. If omitted, checks for any event.
+   * @returns True if matching event(s) found, false otherwise.
+   */
+  hasEvent(uid?: EntityEventUid): boolean;
+  /**
+   * Subscribes to events of a specific type.
+   * The entity will be notified of matching events through the update system.
+   * @param uid - The event type to listen for.
+   * @param options - Optional subscription options (filter, scopeId).
+   */
+  subscribeTo(uid: EntityEventUid, options?: EntityEventSubscriptionOptions): void;
+  /**
+   * Stops listening for events of a specific type.
+   * @param uid - The event type to stop listening for.
+   */
+  unsubscribeFrom(uid: EntityEventUid): void;
+  /**
+   * Adds events to the current context for processing by this and downstream middleware.
+   * @param events - Event array to add to context.
+   */
+  setContextEvents(events: IEntityEvent<IEventData>[]): void;
+  /**
+   * Adds a single event to the current context.
+   * @param event - Event to add to context.
+   */
+  setContextEvent(event: IEntityEvent<IEventData>): void;
+  /**
+   * Removes all events from the current context.
+   */
+  clearContextEvents(): void;
+  /**
+   * Clears all event subscriptions for the current entity.
+   */
+  clearSubscriptions(): void;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-proxies.d.ts
+/**
+ * System context API for managing entity relationships (proxies).
+ * Provides context-bound operations for establishing and managing entity links.
+ * All operations apply to the current entity in the context.
+ */
+interface ISystemContextProxies {
+  /**
+   * Establishes a reference to another entity from the current entity.
+   * Creates a bidirectional link between the entities.
+   * @param proxy - The entity to establish a reference to.
+   * @param cleanup - If true, removes existing proxies of the same type before adding.
+   */
+  register(proxy: IEntityProxy, cleanup?: boolean): void;
+  /**
+   * Establishes multiple references from the current entity.
+   * Batch version of register for efficiency.
+   * @param proxies - The entities to establish references to.
+   * @param cleanup - If true, removes existing proxies of matching types before adding.
+   */
+  registerMany(proxies: readonly IEntityProxy[], cleanup?: boolean): void;
+  /**
+   * Removes a reference from the current entity to another entity.
+   * Breaks the bidirectional link.
+   * @param proxy - The entity reference to remove.
+   */
+  remove(proxy: IEntityProxy): void;
+  /**
+   * Removes all entity references from the current entity.
+   * Optionally filter by target entity type.
+   * @param targetType - If provided, only removes references to entities of this type.
+   */
+  removeAll(targetType?: EntityTypeUid): void;
+  /**
+   * Retrieves a single reference of a specific entity type from the current entity.
+   * @param targetType - The entity type to find.
+   * @returns The first matching proxy, or null if not found.
+   */
+  get(targetType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Retrieves all references to entities of a specific type from the current entity.
+   * @param targetType - The entity type to find.
+   * @returns Array of matching proxies.
+   */
+  getMany(targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
+  /**
+   * Retrieves all entity references from the current entity.
+   * Organized by target entity type.
+   * @returns Map of entity type to their proxies.
+   */
+  getAll(): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-repository.d.ts
+/**
+ * System context API for entity repository operations.
+ * Provides controlled access to entity storage for creating, updating, and removing entities.
+ * All changes go through the repository to maintain system consistency.
+ */
+interface ISystemContextRepository {
+  /**
+   * Queues a new entity for creation.
+   * The entity is created with the provided model and optional initial snapshot.
+   * @param entityType - The type of entity to create.
+   * @param model - The entity initialization data.
+   * @param snapshot - Optional initial state for the entity.
+   */
+  addEntity(entityType: EntityTypeUid, model: IEntityModel, snapshot?: IEntitySnapshot): void;
+  /**
+   * Retrieves an entity from storage.
+   * @template TEntity - The expected entity type.
+   * @param proxy - Reference to the entity.
+   * @returns The immutable entity instance.
+   */
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityTypeUid): Immutable<TEntity>;
+  /**
+   * Queues an entity for update.
+   * Triggers the update pipeline for the entity.
+   * @param target - Optional specific entity to update. Defaults to current entity in context.
+   */
+  updateEntity(target?: IEntityProxy): void;
+  /**
+   * Removes an entity from storage.
+   * Triggers entity cleanup and removal from all systems.
+   * @param target - The entity to remove.
+   */
+  removeEntity(target: IEntityProxy): void;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-scheduler.d.ts
+/**
+ * System context API for scheduling and managing entity updates.
+ * Allows middleware to request that an entity (or another) be updated again on the next or subsequent frame.
+ * Supports both immediate (next frame) and interval-based scheduling.
+ */
+interface ISystemContextScheduler {
+  /**
+   * Schedules an entity for update.
+   * If no target is specified, schedules the current entity.
+   * If no interval is specified, schedules on a default interval.
+   * @param target - Optional entity to schedule. Defaults to current entity in context.
+   * @param intervalMs - Optional update interval in milliseconds. Undefined uses default interval.
+   */
+  scheduleUpdate(target?: IEntityProxy, intervalMs?: number): void;
+  /**
+   * Cancels scheduled updates for an entity.
+   * If no target is specified, removes schedule for the current entity.
+   * @param target - Optional entity to unschedule. Defaults to current entity in context.
+   */
+  removeSchedule(target?: IEntityProxy): void;
+  /**
+   * Checks whether an entity has a scheduled update.
+   * If no target is specified, checks the current entity.
+   * @param target - Optional entity to check. Defaults to current entity in context.
+   */
+  hasSchedule(target?: IEntityProxy): boolean;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-snapshot.d.ts
+/**
+ * System context API for entity serialization and state transfer.
+ * Handles conversion between entities and their serializable snapshots.
+ * Used for state persistence, synchronization, and applying external updates.
+ */
+interface ISystemContextSnapshot {
+  /**
+   * The JSON serializer instance used by this context.
+   * Handles serialization of complex types within snapshots.
+   */
+  readonly serializer: Immutable<IJsonSerializer>;
+  /**
+   * Applies serialized state to the current entity.
+   * Updates the entity's components based on the snapshot.
+   * @param snapshot - The state to apply.
+   */
+  applyToEntity(snapshot: IEntitySnapshot): void;
+  /**
+   * Creates a serialized snapshot of an entity.
+   * Captures the current state for transmission or storage.
+   * @param entity - The entity to snapshot. If omitted, snapshots current entity in context.
+   * @returns The serialized entity state.
+   */
+  createFromEntity(entity?: IEntity): IEntitySnapshot;
+  /**
+   * Queues a snapshot-based update for an entity.
+   * Applies the snapshot through the entity update system.
+   * @param snapshot - The state to apply.
+   * @param proxy - The entity to update.
+   */
+  dispatchToUpdate(snapshot: IEntitySnapshot, proxy: IEntityProxy): void;
+}
+//#endregion
+//#region src/systems/pipeline/system-context.d.ts
+/**
+ * The execution context passed to system middleware.
+ * Provides comprehensive access to entity state, scheduling, events, and repository operations.
+ * Serves as the primary interface between middleware and the ECS framework.
+ *
+ * @template TEntity - The specific entity type this context operates on.
+ */
+interface ISystemContext<TEntity extends IEntity> extends IPipelineContext {
+  /**
+   * Time elapsed since the last system update for this entity, in milliseconds.
+   * Useful for time-based calculations and animations.
+   */
+  readonly deltaTimeMs: Immutable<number>;
+  /**
+   * The entity currently being processed by this middleware.
+   */
+  readonly entity: Immutable<TEntity>;
+  /**
+   * Information about the update triggering this system execution.
+   * Contains type (update/remove) and optional model/snapshot data.
+   */
+  readonly update: Immutable<IEntityUpdate>;
+  /**
+   * Event system API for publishing and subscribing to entity events.
+   */
+  readonly events: Immutable<ISystemContextEvents>;
+  /**
+   * Proxy management API for establishing and managing entity relationships.
+   */
+  readonly proxies: Immutable<ISystemContextProxies>;
+  /**
+   * Repository access API for querying and modifying entity storage.
+   */
+  readonly repository: Immutable<ISystemContextRepository>;
+  /**
+   * Scheduling API for requesting follow-up entity updates.
+   */
+  readonly scheduler: Immutable<ISystemContextScheduler>;
+  /**
+   * Snapshot management API for serialization and state transfer.
+   */
+  readonly snapshot: Immutable<ISystemContextSnapshot>;
+  /**
+   * Logging interface for debug and diagnostic output.
+   */
+  readonly logger: Immutable<ILogger>;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-mutable.d.ts
+/**
+ * Mutable extension of ISystemContext for infrastructure use.
+ * Provides setters for update, delta time, and runtime state that should not be
+ * exposed to system middleware. Used by the dispatcher and runtime middleware.
+ *
+ * @template TEntity - The specific entity type this context operates on.
+ */
+interface IMutableSystemContext<TEntity extends IEntity> extends ISystemContext<TEntity> {
+  setUpdate(update: IEntityUpdate): void;
+  setDeltaTime(deltaTimeMs: number): void;
+  setRuntime(runtime: PipelineRuntime): void;
+}
+//#endregion
+//#region src/factories/context-factory.d.ts
+/**
+ * Creates and caches per-entity system contexts.
+ *
+ * On the first call for a given entity, creates a new SystemContext with all sub-contexts
+ * (events, proxies, repository, scheduler, snapshot) bound to that entity.
+ * Subsequent calls return the cached context. Disposal removes all cache entries for an entity.
+ */
+interface IContextFactory {
+  /**
+   * Creates or retrieves the cached system context for the given entity.
+   * On first call, creates sub-contexts bound to the entity.
+   * On subsequent calls, returns the cached context.
+   * @template TEntity - The entity type for which the system context is being created.
+   * @param entity - The entity to create or retrieve the context for.
+   * @returns The mutable system context for the entity.
+   */
+  getOrCreateContext<TEntity extends IEntity>(entity: Immutable<TEntity>): IMutableSystemContext<TEntity>;
+  /**
+   * Retrieves a previously cached system context by entity UID.
+   * @template TEntity - The entity type.
+   * @param entityUid - The entity's unique identifier.
+   * @returns The cached context, or undefined if not found.
+   */
+  getContext<TEntity extends IEntity>(entityUid: EntityUid): IMutableSystemContext<TEntity> | undefined;
+  /**
+   * Disposes all cached contexts for the given entity.
+   * Removes the entity from the repository and clears all cache entries.
+   * @param entityUid - The entity's unique identifier.
+   */
+  disposeEntity(entityUid: EntityUid): void;
+}
+//#endregion
+//#region src/factories/pipeline-factory.d.ts
+/**
+ * Category identifier for grouping performance metrics.
+ * Typed as string to allow extension beyond the built-in {@link PipelineCategory} values.
+ */
+type PipelineCategoryName = string;
+/**
+ * Built-in metric categories for classifying pipeline and middleware performance entries.
+ *
+ * - `module` — System module pipelines (initialize, update, render, sync phases).
+ * - `runtime` — Runtime orchestration pipeline and its middleware.
+ * - `system` — Individual system middleware within a module pipeline.
+ */
+declare enum PipelineCategory {
+  module = "module",
+  runtime = "runtime",
+  system = "system"
+}
+/**
+ * Options for identifying and categorizing performance metrics on pipelines.
+ */
+type PipelineMetricOptions = {
+  /** Display name for the pipeline in performance metrics. */pipelineName: string; /** Category assigned to pipeline-level metric entries. */
+  pipelineCategory: PipelineCategoryName; /** Category assigned to per-middleware metric entries within this pipeline. */
+  middlewareCategory: PipelineCategoryName;
+};
+/**
+ * Creates pipeline instances for various contexts.
+ * Abstracts pipeline creation to support different implementations.
+ * Used by the system to instantiate pipelines without coupling to specific implementations.
+ */
+interface IPipelineFactory {
+  /**
+   * Creates a new pipeline for the specified context type.
+   * @template TContext - The context type for the pipeline. Must extend IPipelineContext.
+   * @param options - Optional performance metric options (name, category) for the pipeline.
+   * @returns A new pipeline instance ready for middleware registration.
+   */
+  createPipeline<TContext extends IPipelineContext>(options?: PipelineMetricOptions): IPipeline<TContext>;
+}
+//#endregion
+//#region src/systems/system-type.d.ts
+/**
+ * The four phases of entity system execution in each frame.
+ * Each phase serves a specific purpose in the entity lifecycle and can be extended by custom system types.
+ * The runtime handles each phase in order, allowing systems to perform stage-specific operations.
+ */
+declare enum SystemType {
+  /**
+   * Initial setup and resource allocation for the entity.
+   * Runs once when the entity is first created or initialized.
+   */
+  initialize = 0,
+  /**
+   * Main logic and state updates for the entity.
+   * Runs on every update to change entity behavior and properties.
+   */
+  update = 1,
+  /**
+   * Output and visualization operations.
+   * Runs after updates to render or display the entity state.
+   */
+  render = 2,
+  /**
+   * Synchronization and persistence.
+   * Runs last to synchronize state with external systems or storage.
+   */
+  sync = 3
+}
+//#endregion
+//#region src/systems/module/systems-module.d.ts
+/**
+ * Collection of pipelines for a specific entity type.
+ * Defines the complete system processing flow for one entity category.
+ *
+ * @template TEntity - The entity type this module processes.
+ */
+interface ISystemsModule<TEntity extends IEntity> {
+  /**
+   * The pipelines for this entity type.
+   * Each pipeline contains middleware that operates on the entity.
+   */
+  readonly pipelines: ReadonlyMap<SystemType, Immutable<IPipeline<ISystemContext<TEntity>>>>;
+  /**
+   * Optional factory function to initialize new entity instances.
+   * If provided, is called when a new entity of this type is created.
+   * @param model - The initialization model.
+   * @returns The initialized entity.
+   */
+  readonly initEntity?: (model: IEntityModel) => TEntity;
+  /**
+   * If true, this entity type creates a new scope boundary when initialized.
+   * A new scope ID is auto-generated. All child entities inherit this scope.
+   * Typically used for root entities like Engine.
+   */
+  readonly scopeRoot?: boolean;
+  /**
+   * If true, this entity type registers itself as a scoped proxy when initialized.
+   * It joins the inherited scope and becomes resolvable via `context.proxies.get()`
+   * by any entity in the same scope. Throws if no scope exists.
+   * Typically used for scope-wide entities like Scene, Input, AssetsManager.
+   */
+  readonly scopedProxy?: boolean;
+}
+//#endregion
+//#region src/systems/pipeline/system-middleware.d.ts
+/**
+ * A middleware unit that operates within the system pipeline.
+ * System middleware receive comprehensive context about the entity being processed
+ * and can influence entity state and behavior through various APIs.
+ *
+ * @template TEntity - The entity type this middleware handles.
+ */
+type ISystemMiddleware<TEntity extends IEntity> = IMiddleware<ISystemContext<TEntity>>;
+//#endregion
+//#region src/systems/module/systems-module-builder.d.ts
+/**
+ * Builder pattern interface for constructing system modules.
+ * Allows incremental registration of systems and modules for an entity type.
+ * Supports adding individual systems or entire pre-configured modules.
+ *
+ * @template TEntity - The entity type for which systems are being added.
+ */
+interface ISystemsModuleBuilder<TEntity extends IEntity> {
+  /**
+   * The Module Builder's name.
+   */
+  readonly name: string;
+  /**
+   * The pipelines being built.
+   * Accessible during and after construction.
+   */
+  readonly pipelines: ReadonlyMap<SystemType, IPipeline<ISystemContext<TEntity>>>;
+  /**
+   * Whether this entity type is a scope root.
+   */
+  readonly scopeRoot: boolean;
+  /**
+   * Whether this entity type is a scoped proxy.
+   */
+  readonly scopedProxy: boolean;
+  /**
+   * Registers middleware systems for a specific pipeline stage.
+   * The middleware are added to the pipeline in the order provided.
+   * @param type - The pipeline stage (initialize, update, render, sync).
+   * @param systems - Array of middleware to add.
+   * @returns This builder for method chaining.
+   */
+  addSystems(type: SystemType, systems: Immutable<ISystemMiddleware<TEntity>[]>): this;
+  /**
+   * Integrates an entire module's pipelines into this builder.
+   * Allows composition of multiple modules into one.
+   * @template TModuleEntity - The module's entity type (must extend current type).
+   * @param module - The module to integrate.
+   * @param systemType - Optional specific pipeline to integrate from module. If omitted, integrates all.
+   * @returns This builder for method chaining.
+   */
+  addModule<TModuleEntity extends TEntity>(module: ISystemsModule<TModuleEntity>, systemType?: SystemType): this;
+  /**
+   * Marks this entity type as a scope root.
+   * When initialized, a new scope is auto-generated and all child entities inherit it.
+   * @returns This builder for method chaining.
+   */
+  setScopeRoot(): this;
+  /**
+   * Marks this entity type as a scoped proxy.
+   * When initialized, the entity registers itself in the inherited scope,
+   * making it resolvable via `context.proxies.get()` by any entity in the same scope.
+   * @returns This builder for method chaining.
+   */
+  setScopedProxy(): this;
+}
+//#endregion
+//#region src/systems/module/systems-module-repository.d.ts
+/**
+ * Central registry for all systems modules in the ECS.
+ * Maintains a module for each entity type, providing access to all system pipelines.
+ * This is the authoritative source for system module data.
+ *
+ * @template TEntity - The entity types managed by modules in this repository.
+ */
+interface ISystemsModuleRepository {
+  /**
+   * The total number of modules in the repository.
+   */
+  readonly size: number;
+  /**
+   * Retrieves the module for a specific entity type.
+   * @template TEntity - The entity type to retrieve module for.
+   * @param type - The entity type identifier.
+   * @returns The systems module for that entity type.
+   */
+  get<TEntity extends IEntity>(type: EntityTypeUid): ISystemsModule<TEntity>;
+  /**
+   * Registers or updates a module for an entity type.
+   * @param type - The entity type identifier.
+   * @param module - The systems module to register.
+   */
+  set(type: EntityTypeUid, module: ISystemsModule<IEntity>): void;
+  /**
+   * Retrieves all registered modules.
+   * @returns A read-only map of entity type to module.
+   */
+  list(): ReadonlyMap<EntityTypeUid, Immutable<ISystemsModule<IEntity>>>;
+}
+//#endregion
+//#region src/systems/runtime/systems-runtime.d.ts
+/**
+ * Executes system middleware for entities.
+ * Processes entity updates by dispatching them through appropriate system modules.
+ * Different implementations may use different execution strategies or optimizations.
+ */
+interface ISystemsRuntime {
+  /**
+   * Processes a single entity update through its system pipeline.
+   * If no update is provided, may dequeue one from an internal queue.
+   * @param update - Optional specific update to process. If omitted, dequeues the next update.
+   * @returns Array of pipeline results containing execution metrics and data.
+   */
+  runTick(update?: IEntityUpdate): PerformanceTimeEntry[] | void;
+}
+//#endregion
+//#region src/systems/runtime/systems-runtime-context.d.ts
+/**
+ * Runtime context for system pipeline execution.
+ * Coordinates the execution of system pipelines across all entities.
+ * Maintains state about the current entity being processed and enabled pipeline stages.
+ *
+ * @template TEntity - The entity type being processed.
+ */
+interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineContext {
+  /**
+   * Indicates if the system pipeline should perform initialization for the current entity.
+   */
+  readonly shouldInitialize?: boolean;
+  /**
+   * The systems module for the current entity type.
+   */
+  readonly systemsModule: ISystemsModule<TEntity>;
+  /**
+   * The mutable system context for the current entity execution.
+   * Provides infrastructure setters for update, delta time, and runtime state.
+   */
+  readonly systemContext: IMutableSystemContext<TEntity>;
+  /**
+   * The proxy repository for managing entity proxy relationships and scopes.
+   */
+  readonly proxyRepository: IEntityProxyRepository;
+}
+//#endregion
+//#region src/systems/runtime/systems-runtime-middleware.d.ts
+/**
+ * Middleware for orchestrating system execution across entities.
+ * Operates at the runtime level to coordinate system module pipelines.
+ * Can influence which pipelines execute and in what order.
+ *
+ * @template TEntity - The entity type being processed.
+ */
+type ISystemsRuntimeMiddleware<TEntity extends IEntity> = IMiddleware<ISystemsRuntimeContext<TEntity>>;
+//#endregion
+//#region src/factories/runtime-factory.d.ts
+/**
+ * Creates runtime contexts and pipelines for system execution.
+ * Provides factory methods for constructing runtime infrastructure.
+ * Allows different runtime strategies through multiple implementations.
+ */
+interface IRuntimeFactory {
+  /**
+   * Creates a new runtime context for system execution.
+   * @template TEntity - The entity type for the runtime context.
+   * @returns A new systems runtime context instance.
+   */
+  createRuntimeContext<TEntity extends IEntity>(): ISystemsRuntimeContext<TEntity>;
+  /**
+   * Creates a pipeline for systems runtime orchestration.
+   * @template TEntity - The entity type for this runtime pipeline.
+   * @param name - Optional name for debugging.
+   * @returns A new runtime pipeline for system execution.
+   */
+  createRuntimePipeline<TEntity extends IEntity>(name?: string): IPipeline<ISystemsRuntimeContext<TEntity>>;
+}
+//#endregion
+//#region src/factories/systems-factory.d.ts
+/**
+ * Creates systems module builders for constructing entity system pipelines.
+ * Provides factory access to module builder instances.
+ * Enables composition of systems for different entity types.
+ */
+interface ISystemsFactory {
+  /**
+   * Creates a new builder for constructing a systems module.
+   * @template TEntity - The entity type for which systems are being built.
+   * @param name - The System Builder's name.
+   * @returns A new systems module builder instance.
+   */
+  createSystemsModuleBuilder<TEntity extends IEntity>(name: string): ISystemsModuleBuilder<TEntity>;
+}
+//#endregion
+export { IMiddleware as A, TickSnapshot as B, IPipelineRunner as C, IParentMiddleware as D, IParentContext as E, PerformanceTimeEntry as F, dispatchSequential as G, ILoggerOptions as H, PerformanceTimerUid as I, MiddlewareMetricsSummary as L, PipelineRuntime as M, IPerformanceTimer as N, IPipeline as O, PerformanceMetricOptions as P, RenderSnapshot as R, ISystemContextEvents as S, INestedMiddleware as T, LogLevel as U, ILogger as V, IJsonSerializer as W, ISystemContext as _, ISystemsRuntime as a, ISystemContextRepository as b, ISystemMiddleware as c, IPipelineFactory as d, PipelineCategory as f, IMutableSystemContext as g, IContextFactory as h, ISystemsRuntimeContext as i, IPipelineContext as j, IMiddlewareRunner as k, ISystemsModule as l, PipelineMetricOptions as m, IRuntimeFactory as n, ISystemsModuleRepository as o, PipelineCategoryName as p, ISystemsRuntimeMiddleware as r, ISystemsModuleBuilder as s, ISystemsFactory as t, SystemType as u, ISystemContextSnapshot as v, INestedContext as w, ISystemContextProxies as x, ISystemContextScheduler as y, TickMetricEntry as z };
+//# sourceMappingURL=index-8XDo0pla.d.mts.map