@awesome-ecs/abstract 0.32.1 → 0.34.0

package/dist/{index-BD7sDB60.d.mts → index-BivyWazf.d.cts}

@@ -1,8 +1,46 @@
-import { _ as ConfigRecord, a as IEntity, c as IEntityProxy, f as ComponentTypeUid, i as EntityUid, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy } from "./index-BlP67nCr.mjs";
-import { r as Immutable } from "./types-C1ojaDL4.mjs";
-import { c as IEntitySnapshot, d as EntityEventSubscriptionOptions, f as EntityEventUid, g as IEventData, o as IEntityUpdate, p as IEntityEvent, v as IEntityConfigSnapshot } from "./index-vpjRaGIC.mjs";
-import { c as IMiddleware, l as IPipelineContext, o as IPipeline, u as PipelineRuntime } from "./index-CeqaKmWR.mjs";
+import { T as ConfigRecord, a as IEntityProxy, b as ComponentTypeUid, f as IEntity, h as IEntitySpec, i as EntityProxyManyLookup, n as EntityProxy, p as IEntityModel, r as EntityProxyLookup, u as EntityTypeUid } from "./index-DMZSrHoB.cjs";
+import { r as Immutable } from "./types-BaCGIrym.cjs";
+import { b as IEntityConfigSnapshot, c as IEntityUpdate, g as IEntityEvent, h as EntityEventUid, m as EntityEventSubscriptionOptions, u as IEntitySnapshot, y as IEventData } from "./index-CSaKdQe-.cjs";
+import { c as IMiddleware, l as IPipelineContext, o as IPipeline, u as PipelineDispatch } from "./index-aVjnG975.cjs";
 
+//#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.
@@ -78,6 +116,103 @@ interface ILoggerOptions {
   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/systems/pipeline/system-context-config.d.ts
 /**
  * Config-specific API for the current system execution.
@@ -142,14 +277,25 @@ type MiddlewareRegistryReadonly = ReadonlyMap<SystemMiddlewareName, SystemModule
  * @template TEntity - The entity type this middleware handles.
  */
 type ISystemMiddleware<TEntity extends IEntity> = IMiddleware<ISystemContext<TEntity>>;
+/**
+ * Event-routed middleware. Unlike normal system middleware, event middleware is
+ * invoked once per matching event instance and receives that event explicitly.
+ */
+interface ISystemEventMiddleware<TEntity extends IEntity, TEventData extends IEventData = IEventData> {
+  readonly name?: string;
+  shouldRun?(context: ISystemContext<TEntity>, event: IEntityEvent<TEventData>): boolean;
+  action(context: ISystemContext<TEntity>, event: IEntityEvent<TEventData>): void | Promise<void>;
+  cleanup?(context: ISystemContext<TEntity>): void | Promise<void>;
+}
 //#endregion
 //#region src/systems/pipeline/system-context-control.d.ts
+interface SystemContextControlTarget {
+  readonly name?: string;
+}
 declare enum SystemContextControlState {
   none = "none",
   enableCurrentSystem = "enableCurrentSystem",
-  disableCurrentSystem = "disableCurrentSystem",
-  enableCurrentModule = "enableCurrentModule",
-  disableCurrentModule = "disableCurrentModule"
+  disableCurrentSystem = "disableCurrentSystem"
 }
 /**
  * Interface for controlling the execution of systems and modules within a system context.
@@ -165,13 +311,13 @@ interface ISystemContextControl {
    */
   enableCurrentSystem(): void;
   /**
-   * Disables the current module for the current entity.
+   * Disables a module for the current entity.
    */
-  disableCurrentModule(): void;
+  disableModule(name: SystemModuleName): void;
   /**
-   * Re-enables the current module for the current entity.
+   * Re-enables a module for the current entity.
    */
-  enableCurrentModule(): void;
+  enableModule(name: SystemModuleName): void;
 }
 /**
  * Extended system context interface that includes control state for middleware to manage system and module execution.
@@ -187,33 +333,32 @@ interface ISystemContextControlState extends ISystemContextControl {
    * @param middleware - The middleware to check for disabled state.
    * @returns True if the specified middleware is currently disabled, false otherwise.
    */
-  isMiddlewareDisabled(middleware: ISystemMiddleware<IEntity>): boolean;
+  isMiddlewareDisabled(middleware: SystemContextControlTarget): boolean;
   /**
    * Disables a specific middleware in the context.
    * @param middleware - The middleware to disable.
    */
-  disableMiddleware(middleware: ISystemMiddleware<IEntity>): void;
+  disableMiddleware(middleware: SystemContextControlTarget): void;
   /**
    * Enables a specific middleware in the context.
    * @param middleware - The middleware to enable.
    */
-  enableMiddleware(middleware: ISystemMiddleware<IEntity>): void;
+  enableMiddleware(middleware: SystemContextControlTarget): void;
   /**
-   * Disables an entire module of middleware in the context.
-   * @param middleware - A middleware from the module to disable.
+   * Registers an event subscription owned by a module. This is runtime-only state:
+   * disabling the module should also detach its event subscriptions.
    */
-  disableModule(middleware: ISystemMiddleware<IEntity>): void;
+  registerModuleEvent(moduleName: SystemModuleName, eventUid: EntityEventUid, options?: EntityEventSubscriptionOptions): void;
   /**
-   * Enables an entire module of middleware in the context.
-   * @param middleware - A middleware from the module to enable.
+   * Clears all runtime-owned module event subscriptions for the current entity.
    */
-  enableModule(middleware: ISystemMiddleware<IEntity>): void;
+  clearModuleEvents(): 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.
+ * System middleware can dispatch events, while subscriptions are owned by the runtime.
  * Events enable decoupled communication between distant or unrelated entities.
  */
 interface ISystemContextEvents {
@@ -243,56 +388,10 @@ interface ISystemContextEvents {
    * @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).
-   */
+}
+interface IMutableSystemContextEvents extends ISystemContextEvents {
   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
@@ -322,30 +421,18 @@ interface ISystemContextProxies {
    * @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;
+  getProxy<TEntity extends IEntity = IEntity>(targetType: EntityProxyLookup<TEntity>): EntityProxy<TEntity> | 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[]>>;
+  getProxies<TEntity extends IEntity = IEntity>(targetType: EntityProxyManyLookup<TEntity>): Readonly<EntityProxy<TEntity>[]>;
 }
 //#endregion
 //#region src/systems/pipeline/system-context-repository.d.ts
@@ -369,7 +456,28 @@ interface ISystemContextRepository {
    * @param proxy - Reference to the entity.
    * @returns The immutable entity instance.
    */
-  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityTypeUid): Immutable<TEntity>;
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | null | undefined): TEntity | undefined;
+  /**
+   * Retrieves an entity from storage based on its type.
+   * @template TEntity - The expected entity type.
+   * @param targetType - Reference to the entity type.
+   * @returns The immutable entity instance.
+   */
+  getEntity<TEntity extends IEntity>(targetType: EntityProxyLookup<TEntity> | null | undefined): TEntity | undefined;
+  /**
+   * Retrieves an entity from storage based on its type or proxy.
+   * @template TEntity - The expected entity type.
+   * @param proxyOrTargetType - Reference to the entity proxy or type.
+   * @returns The immutable entity instance.
+   */
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityProxyLookup<TEntity> | null | undefined): TEntity | undefined;
+  /**
+   * Retrieves all entities from the current entity's proxy relationships.
+   * @template TEntity - The expected entity type.
+   * @param targetType - Reference to the entity type.
+   * @returns The immutable entity instances.
+   */
+  getEntities<TEntity extends IEntity>(targetType: EntityProxyManyLookup<TEntity> | null | undefined): Readonly<TEntity[]>;
   /**
    * Enqueues an entity for update.
    * Triggers the update pipeline for the entity.
@@ -413,30 +521,6 @@ interface ISystemContextScheduler {
   hasSchedule(target?: IEntityProxy): boolean;
 }
 //#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/systems/pipeline/system-context-snapshot.d.ts
 /**
  * System context API for entity serialization and state transfer.
@@ -484,7 +568,7 @@ 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>;
+  readonly deltaTimeMs: number;
   /**
    * The entity currently being processed by this middleware.
    */
@@ -492,44 +576,44 @@ interface ISystemContext<TEntity extends IEntity> extends IPipelineContext {
   /**
    * Config metadata and config-update API for the current update.
    */
-  readonly config: Immutable<ISystemContextConfigReadonly>;
+  readonly config: ISystemContextConfigReadonly;
   /**
    * Information about the update triggering this system execution.
    * Contains type (update/remove) and optional model/snapshot data.
    */
-  readonly update: Immutable<IEntityUpdate>;
+  readonly update: IEntityUpdate;
   /**
-   * Event system API for publishing and subscribing to entity events.
+   * Event system API for publishing entity events.
    */
-  readonly events: Immutable<ISystemContextEvents>;
+  readonly events: ISystemContextEvents;
   /**
    * Logging interface for debug and diagnostic output.
    */
-  readonly logger: Immutable<ILogger>;
+  readonly logger: ILogger;
   /**
    * Proxy management API for establishing and managing entity relationships.
    */
-  readonly proxies: Immutable<ISystemContextProxies>;
+  readonly proxies: ISystemContextProxies;
   /**
    * Repository access API for querying and modifying entity storage.
    */
-  readonly repository: Immutable<ISystemContextRepository>;
+  readonly repository: ISystemContextRepository;
   /**
    * Scheduling API for requesting follow-up entity updates.
    */
-  readonly scheduler: Immutable<ISystemContextScheduler>;
+  readonly scheduler: ISystemContextScheduler;
   /**
    * Snapshot management API for serialization and state transfer.
    */
-  readonly snapshot: Immutable<ISystemContextSnapshot>;
+  readonly snapshot: ISystemContextSnapshot;
   /**
    * Control API for enabling/disabling the current system or entire module during execution.
    */
-  readonly systems: Immutable<ISystemContextControl>;
+  readonly systems: ISystemContextControl;
   /**
-   * The per-entity runtime state and control interface for this system context.
+   * The per-entity dispatch state and control interface for this system context.
    */
-  readonly runtime: PipelineRuntime;
+  readonly dispatch: PipelineDispatch;
 }
 //#endregion
 //#region src/systems/pipeline/system-context-mutable.d.ts
@@ -541,154 +625,15 @@ interface ISystemContext<TEntity extends IEntity> extends IPipelineContext {
  * @template TEntity - The specific entity type this context operates on.
  */
 interface IMutableSystemContext<TEntity extends IEntity> extends ISystemContext<TEntity> {
+  readonly events: IMutableSystemContextEvents;
   setUpdate(update: IEntityUpdate): void;
   setDeltaTime(deltaTimeMs: number): void;
-  setRuntime(runtime: PipelineRuntime): void;
-}
-//#endregion
-//#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/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;
+  setDispatch(dispatch: PipelineDispatch): 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.
-   * @param registry - Optional middleware registry to associate with the context for pipeline execution.
-   * @returns The mutable system context for the entity.
-   */
-  getOrCreateContext<TEntity extends IEntity>(entity: Immutable<TEntity>, registry?: MiddlewareRegistryReadonly): 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;
+  createContext<TEntity extends IEntity>(entity: Immutable<TEntity>, registry?: MiddlewareRegistryReadonly): IMutableSystemContext<TEntity>;
 }
 //#endregion
 //#region src/factories/pipeline-factory.d.ts
@@ -749,21 +694,40 @@ declare enum SystemType {
    * Runs on entity creation and on updates that carry a config payload.
    */
   config = 1,
+  /**
+   * Event reactions routed by event uid.
+   * Runs after config and before update for updates carrying events.
+   */
+  event = 2,
   /**
    * Main logic and state updates for the entity.
    * Runs on every update to change entity behavior and properties.
    */
-  update = 2,
+  update = 3,
   /**
    * Output and visualization operations.
    * Runs after updates to render or display the entity state.
    */
-  render = 3,
+  render = 4,
   /**
    * Synchronization and persistence.
    * Runs last to synchronize state with external systems or storage.
    */
-  sync = 4
+  sync = 5
+}
+//#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 builder instance used to construct this module.
+   */
+  readonly builder: ISystemsModuleBuilderReadonly<TEntity>;
 }
 //#endregion
 //#region src/systems/module/systems-module-builder.d.ts
@@ -776,6 +740,10 @@ interface ISystemsModuleBuilderReadonly<TEntity extends IEntity> {
    * Read-only map of system pipelines keyed by SystemType.
    */
   readonly pipelines: ReadonlyMap<SystemType, IPipeline<ISystemContext<TEntity>>>;
+  /**
+   * Event middleware keyed by event uid.
+   */
+  readonly eventMiddlewares: ReadonlyMap<EntityEventUid, ReadonlyArray<ISystemEventMiddleware<TEntity>>>;
   /**
    * Read-only registry mapping middleware names to their originating module names.
    */
@@ -785,9 +753,10 @@ interface ISystemsModuleBuilderReadonly<TEntity extends IEntity> {
    */
   readonly scopeRoot: boolean;
   /**
-   * Whether this entity type is 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.
+   * Whether this entity type is a scoped proxy. When initialized, the entity registers itself in the inherited scope, making it resolvable via `context.proxies.getProxy()` by any entity in the same scope.
    */
   readonly scopedProxy: boolean;
+  readonly entitySpec?: IEntitySpec<TEntity>;
 }
 /**
  * Builder pattern interface for constructing system modules.
@@ -806,15 +775,30 @@ interface ISystemsModuleBuilder<TEntity extends IEntity> extends ISystemsModuleB
    * @returns This builder for method chaining.
    */
   addSystems(type: SystemType, systems: Immutable<ISystemMiddleware<TEntity>[]>): this;
+  /**
+   * Registers event-routed middleware for a specific event uid.
+   * Event middleware are invoked once per matching event instance.
+   */
+  addEventSystems(uid: EntityEventUid, systems: Immutable<ISystemEventMiddleware<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).
+   *
+   * Composition is gated by structural assignability: the host's `TEntity` must extend
+   * the inner module's `TInner`. In other words, the host entity contract must contain
+   * every field the inner module reads from `context.entity`.
+   *
+   * @template TInner - The inner module's entity type; must be assignable from `TEntity`.
    * @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;
+  addModule<TInner extends IEntity>(module: TEntity extends TInner ? ISystemsModule<TInner> : never, systemType?: SystemType): this;
+  /**
+   * Declares this module's entity creation spec. `type` carries the entity type UID;
+   * `init` constructs and returns the entity at first creation. The dispatcher validates
+   * at runtime that the returned entity's `identity.entityType` matches `type`.
+   */
+  setEntity(spec: IEntitySpec<TEntity>): this;
   /**
    * Marks this entity type as a scope root.
    * When initialized, a new scope is auto-generated and all child entities inherit it.
@@ -824,146 +808,12 @@ interface ISystemsModuleBuilder<TEntity extends IEntity> extends ISystemsModuleB
   /**
    * 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.
+   * making it resolvable via `context.proxies.getProxy()` by any entity in the same scope.
    * @returns This builder for method chaining.
    */
   setScopedProxy(): this;
 }
 //#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 builder instance used to construct this module.
-   */
-  readonly builder: ISystemsModuleBuilderReadonly<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;
-}
-//#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 Pipeline results containing execution data and metrics.
-   */
-  runTick(update?: IEntityUpdate): PipelineRuntime | Promise<PipelineRuntime> | 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;
-  /**
-   * Indicates if the config system phase should run for the current entity.
-   */
-  readonly shouldConfigure?: 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.
@@ -980,5 +830,5 @@ interface ISystemsFactory {
   createSystemsModuleBuilder<TEntity extends IEntity>(name: string): ISystemsModuleBuilder<TEntity>;
 }
 //#endregion
-export { ISystemContextRepository as A, SystemModuleName as B, TickSnapshot as C, ISystemContextSnapshot as D, ISystemContext as E, SystemContextControlState as F, LogLevel as G, ISystemContextConfigReadonly as H, ISystemMiddleware as I, MiddlewareRegistry as L, ISystemContextEvents as M, ISystemContextControl as N, IJsonSerializer as O, ISystemContextControlState as P, MiddlewareRegistryReadonly as R, TickMetricEntry as S, IMutableSystemContext as T, ILogger as U, ISystemContextConfig as V, ILoggerOptions as W, PerformanceMetricOptions as _, ISystemsRuntime as a, MiddlewareMetricsSummary as b, ISystemsModuleBuilder as c, IPipelineFactory as d, PipelineCategory as f, IPerformanceTimer as g, IContextFactory as h, ISystemsRuntimeContext as i, ISystemContextProxies as j, ISystemContextScheduler as k, ISystemsModuleBuilderReadonly as l, PipelineOptions as m, IRuntimeFactory as n, ISystemsModuleRepository as o, PipelineCategoryName as p, ISystemsRuntimeMiddleware as r, ISystemsModule as s, ISystemsFactory as t, SystemType as u, PerformanceTimeEntry as v, dispatchSequential as w, RenderSnapshot as x, PerformanceTimerUid as y, SystemMiddlewareName as z };
-//# sourceMappingURL=index-BD7sDB60.d.mts.map
+export { ISystemContextConfigReadonly as A, ILoggerOptions as B, ISystemEventMiddleware as C, SystemMiddlewareName as D, MiddlewareRegistryReadonly as E, MiddlewareMetricsSummary as F, IJsonSerializer as H, RenderSnapshot as I, TickMetricEntry as L, PerformanceMetricOptions as M, PerformanceTimeEntry as N, SystemModuleName as O, PerformanceTimerUid as P, TickSnapshot as R, SystemContextControlTarget as S, MiddlewareRegistry as T, dispatchSequential as U, LogLevel as V, IMutableSystemContextEvents as _, SystemType as a, ISystemContextControlState as b, PipelineCategoryName as c, IMutableSystemContext as d, ISystemContext as f, ISystemContextProxies as g, ISystemContextRepository as h, ISystemsModule as i, IPerformanceTimer as j, ISystemContextConfig as k, PipelineOptions as l, ISystemContextScheduler as m, ISystemsModuleBuilder as n, IPipelineFactory as o, ISystemContextSnapshot as p, ISystemsModuleBuilderReadonly as r, PipelineCategory as s, ISystemsFactory as t, IContextFactory as u, ISystemContextEvents as v, ISystemMiddleware as w, SystemContextControlState as x, ISystemContextControl as y, ILogger as z };
+//# sourceMappingURL=index-BivyWazf.d.cts.map