@awesome-ecs/abstract 0.24.0 → 0.26.0

package/README.md

@@ -71,8 +71,8 @@ Pipelines execute **middleware chains** with two phases:
 ```typescript
 export interface IPipeline<TContext extends IPipelineContext> {
   use(middleware: IMiddleware<TContext>): this;
-  dispatch(context: Partial<TContext>): PipelineResult;
-  cleanup(context: Partial<TContext>): PipelineResult;
+  dispatch(context: Partial<TContext>): void | Promise<void>;
+  cleanup(context: Partial<TContext>): void | Promise<void>;
 }
 ```
 
@@ -82,7 +82,6 @@ export interface IPipeline<TContext extends IPipelineContext> {
 - `middleware-runner.ts`: Middleware execution engine
 - `pipeline-context.ts`: Context passed to middleware
 - `pipeline-runner.ts`: Pipeline execution orchestration
-- `pipeline-result.ts`: Result type for success/failure
 
 ### Systems (`src/systems/`)
 
@@ -94,7 +93,7 @@ Systems are **modular logic units** that operate on entities. They implement the
 
 **Module-based organization:**
 - `systems-module.ts`: `ISystemsModule<TEntity>` - groups related systems targeting an entity type
-- `systems-module-definition.ts`: Module definition and pipeline registration
+- `systems-module-builder.ts`: `ISystemsModuleBuilder<TEntity>` - fluent builder for pipeline registration
 - `systems-module-repository.ts`: Module lifecycle and registration
 
 **Runtime execution:**

package/dist/entities/index.cjs

@@ -16,6 +16,22 @@ let EntityUpdateType = /* @__PURE__ */ function(EntityUpdateType) {
 	return EntityUpdateType;
 }({});
 
+//#endregion
+//#region src/entities/entity-scheduler.ts
+/**
+* Controls which scheduling modes are paused.
+*/
+let SchedulerPauseType = /* @__PURE__ */ function(SchedulerPauseType) {
+	/** Pause both interval timers and frame subscriptions. */
+	SchedulerPauseType["full"] = "full";
+	/** Pause only frame subscriptions. Interval timers continue firing. */
+	SchedulerPauseType["perFrame"] = "perFrame";
+	/** Pause only interval timers. Frame subscriptions continue. */
+	SchedulerPauseType["intervals"] = "intervals";
+	return SchedulerPauseType;
+}({});
+
 //#endregion
 exports.EntityUpdateType = EntityUpdateType;
+exports.SchedulerPauseType = SchedulerPauseType;
 //# sourceMappingURL=index.cjs.map

package/dist/entities/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../src/entities/entity-queue.ts"],"sourcesContent":["import { IEntityModel } from './entity';\r\nimport { IEntityProxy } from './entity-proxies';\r\nimport { IEntitySnapshot } from './entity-snapshot';\r\n\r\n/**\r\n * Specifies the action to be performed on an entity.\r\n * Updates are categorized to enable different processing paths in the runtime.\r\n */\r\nexport enum EntityUpdateType {\r\n  /**\r\n   * Indicates the entity should be updated with new data.\r\n   */\r\n  update = 'update',\r\n  /**\r\n   * Indicates the entity should be removed from the system.\r\n   */\r\n  remove = 'remove'\r\n}\r\n\r\n/**\r\n * Represents a queued entity state change or removal.\r\n * Updates flow through the system to be processed by entity update handlers.\r\n */\r\nexport interface IEntityUpdate {\r\n  /**\r\n   * The type of operation: update or remove.\r\n   */\r\n  readonly type: EntityUpdateType;\r\n\r\n  /**\r\n   * The entity being affected by this update.\r\n   */\r\n  readonly entity: IEntityProxy;\r\n\r\n  /**\r\n   * Optional model data for initialization or reconfiguration.\r\n   */\r\n  readonly model?: IEntityModel;\r\n\r\n  /**\r\n   * Optional serialized state to apply to the entity.\r\n   */\r\n  readonly snapshot?: IEntitySnapshot;\r\n}\r\n\r\n/**\r\n * Queue interface for managing pending entity updates.\r\n * Different implementations may use different prioritization strategies (e.g., priority queues, FIFO, ordered by entity type).\r\n * Updates are consumed by the runtime and dispatched to appropriate entity systems.\r\n */\r\nexport interface IEntityUpdateQueue {\r\n  /**\r\n   * The current number of updates in the queue.\r\n   */\r\n  readonly size: number;\r\n\r\n  /**\r\n   * Adds an update to the queue for processing.\r\n   * @param change - The update to queue.\r\n   */\r\n  enqueue(change: IEntityUpdate): void;\r\n\r\n  /**\r\n   * Removes and returns the next update from the queue.\r\n   * The specific update returned depends on the queue's prioritization strategy.\r\n   * @returns The next queued update.\r\n   */\r\n  dequeue(): IEntityUpdate;\r\n\r\n  /**\r\n   * Views the next update without removing it.\r\n   * Useful for inspection before dequeuing.\r\n   * @returns The next update in the queue.\r\n   */\r\n  peek(): IEntityUpdate;\r\n\r\n  /**\r\n   * Removes all updates from the queue.\r\n   */\r\n  clear(): void;\r\n}\r\n"],"mappings":";;;;;;AAQA,IAAY,8DAAL;;;;AAIL;;;;AAIA"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/entities/entity-queue.ts","../../src/entities/entity-scheduler.ts"],"sourcesContent":["import { IEntityModel } from './entity';\r\nimport { IEntityProxy } from './entity-proxies';\r\nimport { IEntitySnapshot } from './entity-snapshot';\r\n\r\n/**\r\n * Specifies the action to be performed on an entity.\r\n * Updates are categorized to enable different processing paths in the runtime.\r\n */\r\nexport enum EntityUpdateType {\r\n  /**\r\n   * Indicates the entity should be updated with new data.\r\n   */\r\n  update = 'update',\r\n  /**\r\n   * Indicates the entity should be removed from the system.\r\n   */\r\n  remove = 'remove'\r\n}\r\n\r\n/**\r\n * Represents a queued entity state change or removal.\r\n * Updates flow through the system to be processed by entity update handlers.\r\n */\r\nexport interface IEntityUpdate {\r\n  /**\r\n   * The type of operation: update or remove.\r\n   */\r\n  readonly type: EntityUpdateType;\r\n\r\n  /**\r\n   * The entity being affected by this update.\r\n   */\r\n  readonly entity: IEntityProxy;\r\n\r\n  /**\r\n   * Optional model data for initialization or reconfiguration.\r\n   */\r\n  readonly model?: IEntityModel;\r\n\r\n  /**\r\n   * Optional serialized state to apply to the entity.\r\n   */\r\n  readonly snapshot?: IEntitySnapshot;\r\n}\r\n\r\n/**\r\n * Queue interface for managing pending entity updates.\r\n * Different implementations may use different prioritization strategies (e.g., priority queues, FIFO, ordered by entity type).\r\n * Updates are consumed by the runtime and dispatched to appropriate entity systems.\r\n */\r\nexport interface IEntityUpdateQueue {\r\n  /**\r\n   * The current number of updates in the queue.\r\n   */\r\n  readonly size: number;\r\n\r\n  /**\r\n   * Adds an update to the queue for processing.\r\n   * @param change - The update to queue.\r\n   */\r\n  enqueue(change: IEntityUpdate): void;\r\n\r\n  /**\r\n   * Removes and returns the next update from the queue.\r\n   * The specific update returned depends on the queue's prioritization strategy.\r\n   * @returns The next queued update.\r\n   */\r\n  dequeue(): IEntityUpdate;\r\n\r\n  /**\r\n   * Views the next update without removing it.\r\n   * Useful for inspection before dequeuing.\r\n   * @returns The next update in the queue.\r\n   */\r\n  peek(): IEntityUpdate;\r\n\r\n  /**\r\n   * Removes all updates from the queue.\r\n   */\r\n  clear(): void;\r\n}\r\n","import { EntityTypeUid } from './entity';\nimport { IEntityProxy } from './entity-proxies';\n\n/**\n * Describes a scheduled entity update, including the target entity and optional interval.\n */\nexport type EntitySchedule = {\n  readonly proxy: IEntityProxy;\n  readonly intervalMs?: number;\n};\n\n/**\n * Controls which scheduling modes are paused.\n */\nexport enum SchedulerPauseType {\n  /** Pause both interval timers and frame subscriptions. */\n  full = 'full',\n  /** Pause only frame subscriptions. Interval timers continue firing. */\n  perFrame = 'perFrame',\n  /** Pause only interval timers. Frame subscriptions continue. */\n  intervals = 'intervals'\n}\n\n/**\n * Manages time-based scheduling of entity updates.\n *\n * Entities can be scheduled with an interval (timer-driven) or without one (per-frame).\n * The runtime pulls pending entities each tick via the {@link pending} iterator,\n * which yields both per-frame subscriptions and interval entities whose timer has fired.\n */\nexport interface IEntityScheduler {\n  /**\n   * Returns all currently scheduled entities with their configuration.\n   * Useful for inspection and debugging.\n   */\n  readonly schedules: ReadonlyArray<EntitySchedule>;\n\n  /**\n   * Yields entities pending processing this tick: per-frame subscriptions\n   * followed by interval entities whose timer has fired since the last drain.\n   * Iterating drains the due interval buckets; a second iteration without\n   * timer advancement yields only per-frame subscriptions.\n   */\n  readonly pending: IterableIterator<IEntityProxy>;\n\n  /**\n   * The set of entities scheduled for per-frame updates (no interval).\n   */\n  readonly frameSubscriptions: ReadonlySet<IEntityProxy>;\n\n  /**\n   * The number of entities currently awaiting processing:\n   * per-frame subscriptions (if not paused) plus interval entities whose timer has fired.\n   */\n  readonly pendingCount: number;\n\n  /**\n   * Whether the scheduler is currently paused in any mode.\n   */\n  readonly isPaused: boolean;\n\n  /**\n   * Registers an entity for updates.\n   * @param entityProxy - The entity to schedule.\n   * @param intervalMs - Update frequency in milliseconds. If omitted, the entity is scheduled per-frame.\n   */\n  schedule(entityProxy: IEntityProxy, intervalMs?: number): void;\n\n  /**\n   * Unregisters an entity from the scheduler.\n   * @param entityProxy - The entity to unschedule.\n   */\n  remove(entityProxy: IEntityProxy): void;\n\n  /**\n   * Checks if an entity is currently scheduled for updates.\n   * @param entityProxy - The entity to check.\n   * @returns True if the entity is scheduled, false otherwise.\n   */\n  has(entityProxy: IEntityProxy): boolean;\n\n  /**\n   * Removes all schedules and clears all timers.\n   */\n  clear(): void;\n\n  /**\n   * Entity types currently excluded from {@link pending} iteration.\n   */\n  readonly skippedEntityTypes: ReadonlySet<EntityTypeUid>;\n\n  /**\n   * Excludes an entity type from {@link pending} iteration.\n   * Entities remain registered; only yielding is suppressed.\n   */\n  skipEntityType(entityType: EntityTypeUid): void;\n\n  /**\n   * Re-includes a previously skipped entity type in {@link pending} iteration.\n   */\n  unskipEntityType(entityType: EntityTypeUid): void;\n\n  /**\n   * Pauses the scheduler.\n   * @param type - Which scheduling modes to pause. Defaults to {@link SchedulerPauseType.full}.\n   */\n  pause(type?: SchedulerPauseType): void;\n\n  /**\n   * Resumes the scheduler from any paused state.\n   */\n  resume(): void;\n}\n"],"mappings":";;;;;;AAQA,IAAY,8DAAL;;;;AAIL;;;;AAIA;;;;;;;;;ACFF,IAAY,kEAAL;;AAEL;;AAEA;;AAEA"}

package/dist/entities/index.d.cts

@@ -1,3 +1,3 @@
 import { a as IEntity, c as IEntityProxy, d as TypedEntityProxy, i as EntityUid, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy, u as RequiredProxies } from "../identity-component-uU0yDR-y.cjs";
-import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEvent, f as IEntityEventsDispatcher, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, n as IEntityRepository, o as IEntitySnapshot, p as IEntityEventsManager, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as EntityEventUid } from "../index-qSeVF9hf.cjs";
-export { EntityEventSubscriptionFilter, EntityEventSubscriptionOptions, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };
+import { a as EntityUpdateType, c as IEntitySnapshot, d as EntityEventSubscriptionOptions, f as EntityEventUid, g as IEventData, h as IEntityEventsManager, i as IEntityRepository, l as IEntitySnapshotProvider, m as IEntityEventsDispatcher, n as IEntityScheduler, o as IEntityUpdate, p as IEntityEvent, r as SchedulerPauseType, s as IEntityUpdateQueue, t as EntitySchedule, u as EntityEventSubscriptionFilter } from "../index-D_z9RbVT.cjs";
+export { EntityEventSubscriptionFilter, EntityEventSubscriptionOptions, EntityEventUid, EntityProxy, EntitySchedule, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, SchedulerPauseType, TypedEntityProxy };

package/dist/entities/index.d.mts

@@ -1,3 +1,3 @@
 import { a as IEntity, c as IEntityProxy, d as TypedEntityProxy, i as EntityUid, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy, u as RequiredProxies } from "../identity-component-CgzvgBVh.mjs";
-import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEvent, f as IEntityEventsDispatcher, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, n as IEntityRepository, o as IEntitySnapshot, p as IEntityEventsManager, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as EntityEventUid } from "../index-CfEs8NEA.mjs";
-export { EntityEventSubscriptionFilter, EntityEventSubscriptionOptions, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };
+import { a as EntityUpdateType, c as IEntitySnapshot, d as EntityEventSubscriptionOptions, f as EntityEventUid, g as IEventData, h as IEntityEventsManager, i as IEntityRepository, l as IEntitySnapshotProvider, m as IEntityEventsDispatcher, n as IEntityScheduler, o as IEntityUpdate, p as IEntityEvent, r as SchedulerPauseType, s as IEntityUpdateQueue, t as EntitySchedule, u as EntityEventSubscriptionFilter } from "../index-ke1H7wmC.mjs";
+export { EntityEventSubscriptionFilter, EntityEventSubscriptionOptions, EntityEventUid, EntityProxy, EntitySchedule, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, SchedulerPauseType, TypedEntityProxy };

package/dist/entities/index.mjs

@@ -16,5 +16,20 @@ let EntityUpdateType = /* @__PURE__ */ function(EntityUpdateType) {
 }({});
 
 //#endregion
-export { EntityUpdateType };
+//#region src/entities/entity-scheduler.ts
+/**
+* Controls which scheduling modes are paused.
+*/
+let SchedulerPauseType = /* @__PURE__ */ function(SchedulerPauseType) {
+	/** Pause both interval timers and frame subscriptions. */
+	SchedulerPauseType["full"] = "full";
+	/** Pause only frame subscriptions. Interval timers continue firing. */
+	SchedulerPauseType["perFrame"] = "perFrame";
+	/** Pause only interval timers. Frame subscriptions continue. */
+	SchedulerPauseType["intervals"] = "intervals";
+	return SchedulerPauseType;
+}({});
+
+//#endregion
+export { EntityUpdateType, SchedulerPauseType };
 //# sourceMappingURL=index.mjs.map

package/dist/entities/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/entities/entity-queue.ts"],"sourcesContent":["import { IEntityModel } from './entity';\r\nimport { IEntityProxy } from './entity-proxies';\r\nimport { IEntitySnapshot } from './entity-snapshot';\r\n\r\n/**\r\n * Specifies the action to be performed on an entity.\r\n * Updates are categorized to enable different processing paths in the runtime.\r\n */\r\nexport enum EntityUpdateType {\r\n  /**\r\n   * Indicates the entity should be updated with new data.\r\n   */\r\n  update = 'update',\r\n  /**\r\n   * Indicates the entity should be removed from the system.\r\n   */\r\n  remove = 'remove'\r\n}\r\n\r\n/**\r\n * Represents a queued entity state change or removal.\r\n * Updates flow through the system to be processed by entity update handlers.\r\n */\r\nexport interface IEntityUpdate {\r\n  /**\r\n   * The type of operation: update or remove.\r\n   */\r\n  readonly type: EntityUpdateType;\r\n\r\n  /**\r\n   * The entity being affected by this update.\r\n   */\r\n  readonly entity: IEntityProxy;\r\n\r\n  /**\r\n   * Optional model data for initialization or reconfiguration.\r\n   */\r\n  readonly model?: IEntityModel;\r\n\r\n  /**\r\n   * Optional serialized state to apply to the entity.\r\n   */\r\n  readonly snapshot?: IEntitySnapshot;\r\n}\r\n\r\n/**\r\n * Queue interface for managing pending entity updates.\r\n * Different implementations may use different prioritization strategies (e.g., priority queues, FIFO, ordered by entity type).\r\n * Updates are consumed by the runtime and dispatched to appropriate entity systems.\r\n */\r\nexport interface IEntityUpdateQueue {\r\n  /**\r\n   * The current number of updates in the queue.\r\n   */\r\n  readonly size: number;\r\n\r\n  /**\r\n   * Adds an update to the queue for processing.\r\n   * @param change - The update to queue.\r\n   */\r\n  enqueue(change: IEntityUpdate): void;\r\n\r\n  /**\r\n   * Removes and returns the next update from the queue.\r\n   * The specific update returned depends on the queue's prioritization strategy.\r\n   * @returns The next queued update.\r\n   */\r\n  dequeue(): IEntityUpdate;\r\n\r\n  /**\r\n   * Views the next update without removing it.\r\n   * Useful for inspection before dequeuing.\r\n   * @returns The next update in the queue.\r\n   */\r\n  peek(): IEntityUpdate;\r\n\r\n  /**\r\n   * Removes all updates from the queue.\r\n   */\r\n  clear(): void;\r\n}\r\n"],"mappings":";;;;;AAQA,IAAY,8DAAL;;;;AAIL;;;;AAIA"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/entities/entity-queue.ts","../../src/entities/entity-scheduler.ts"],"sourcesContent":["import { IEntityModel } from './entity';\r\nimport { IEntityProxy } from './entity-proxies';\r\nimport { IEntitySnapshot } from './entity-snapshot';\r\n\r\n/**\r\n * Specifies the action to be performed on an entity.\r\n * Updates are categorized to enable different processing paths in the runtime.\r\n */\r\nexport enum EntityUpdateType {\r\n  /**\r\n   * Indicates the entity should be updated with new data.\r\n   */\r\n  update = 'update',\r\n  /**\r\n   * Indicates the entity should be removed from the system.\r\n   */\r\n  remove = 'remove'\r\n}\r\n\r\n/**\r\n * Represents a queued entity state change or removal.\r\n * Updates flow through the system to be processed by entity update handlers.\r\n */\r\nexport interface IEntityUpdate {\r\n  /**\r\n   * The type of operation: update or remove.\r\n   */\r\n  readonly type: EntityUpdateType;\r\n\r\n  /**\r\n   * The entity being affected by this update.\r\n   */\r\n  readonly entity: IEntityProxy;\r\n\r\n  /**\r\n   * Optional model data for initialization or reconfiguration.\r\n   */\r\n  readonly model?: IEntityModel;\r\n\r\n  /**\r\n   * Optional serialized state to apply to the entity.\r\n   */\r\n  readonly snapshot?: IEntitySnapshot;\r\n}\r\n\r\n/**\r\n * Queue interface for managing pending entity updates.\r\n * Different implementations may use different prioritization strategies (e.g., priority queues, FIFO, ordered by entity type).\r\n * Updates are consumed by the runtime and dispatched to appropriate entity systems.\r\n */\r\nexport interface IEntityUpdateQueue {\r\n  /**\r\n   * The current number of updates in the queue.\r\n   */\r\n  readonly size: number;\r\n\r\n  /**\r\n   * Adds an update to the queue for processing.\r\n   * @param change - The update to queue.\r\n   */\r\n  enqueue(change: IEntityUpdate): void;\r\n\r\n  /**\r\n   * Removes and returns the next update from the queue.\r\n   * The specific update returned depends on the queue's prioritization strategy.\r\n   * @returns The next queued update.\r\n   */\r\n  dequeue(): IEntityUpdate;\r\n\r\n  /**\r\n   * Views the next update without removing it.\r\n   * Useful for inspection before dequeuing.\r\n   * @returns The next update in the queue.\r\n   */\r\n  peek(): IEntityUpdate;\r\n\r\n  /**\r\n   * Removes all updates from the queue.\r\n   */\r\n  clear(): void;\r\n}\r\n","import { EntityTypeUid } from './entity';\nimport { IEntityProxy } from './entity-proxies';\n\n/**\n * Describes a scheduled entity update, including the target entity and optional interval.\n */\nexport type EntitySchedule = {\n  readonly proxy: IEntityProxy;\n  readonly intervalMs?: number;\n};\n\n/**\n * Controls which scheduling modes are paused.\n */\nexport enum SchedulerPauseType {\n  /** Pause both interval timers and frame subscriptions. */\n  full = 'full',\n  /** Pause only frame subscriptions. Interval timers continue firing. */\n  perFrame = 'perFrame',\n  /** Pause only interval timers. Frame subscriptions continue. */\n  intervals = 'intervals'\n}\n\n/**\n * Manages time-based scheduling of entity updates.\n *\n * Entities can be scheduled with an interval (timer-driven) or without one (per-frame).\n * The runtime pulls pending entities each tick via the {@link pending} iterator,\n * which yields both per-frame subscriptions and interval entities whose timer has fired.\n */\nexport interface IEntityScheduler {\n  /**\n   * Returns all currently scheduled entities with their configuration.\n   * Useful for inspection and debugging.\n   */\n  readonly schedules: ReadonlyArray<EntitySchedule>;\n\n  /**\n   * Yields entities pending processing this tick: per-frame subscriptions\n   * followed by interval entities whose timer has fired since the last drain.\n   * Iterating drains the due interval buckets; a second iteration without\n   * timer advancement yields only per-frame subscriptions.\n   */\n  readonly pending: IterableIterator<IEntityProxy>;\n\n  /**\n   * The set of entities scheduled for per-frame updates (no interval).\n   */\n  readonly frameSubscriptions: ReadonlySet<IEntityProxy>;\n\n  /**\n   * The number of entities currently awaiting processing:\n   * per-frame subscriptions (if not paused) plus interval entities whose timer has fired.\n   */\n  readonly pendingCount: number;\n\n  /**\n   * Whether the scheduler is currently paused in any mode.\n   */\n  readonly isPaused: boolean;\n\n  /**\n   * Registers an entity for updates.\n   * @param entityProxy - The entity to schedule.\n   * @param intervalMs - Update frequency in milliseconds. If omitted, the entity is scheduled per-frame.\n   */\n  schedule(entityProxy: IEntityProxy, intervalMs?: number): void;\n\n  /**\n   * Unregisters an entity from the scheduler.\n   * @param entityProxy - The entity to unschedule.\n   */\n  remove(entityProxy: IEntityProxy): void;\n\n  /**\n   * Checks if an entity is currently scheduled for updates.\n   * @param entityProxy - The entity to check.\n   * @returns True if the entity is scheduled, false otherwise.\n   */\n  has(entityProxy: IEntityProxy): boolean;\n\n  /**\n   * Removes all schedules and clears all timers.\n   */\n  clear(): void;\n\n  /**\n   * Entity types currently excluded from {@link pending} iteration.\n   */\n  readonly skippedEntityTypes: ReadonlySet<EntityTypeUid>;\n\n  /**\n   * Excludes an entity type from {@link pending} iteration.\n   * Entities remain registered; only yielding is suppressed.\n   */\n  skipEntityType(entityType: EntityTypeUid): void;\n\n  /**\n   * Re-includes a previously skipped entity type in {@link pending} iteration.\n   */\n  unskipEntityType(entityType: EntityTypeUid): void;\n\n  /**\n   * Pauses the scheduler.\n   * @param type - Which scheduling modes to pause. Defaults to {@link SchedulerPauseType.full}.\n   */\n  pause(type?: SchedulerPauseType): void;\n\n  /**\n   * Resumes the scheduler from any paused state.\n   */\n  resume(): void;\n}\n"],"mappings":";;;;;AAQA,IAAY,8DAAL;;;;AAIL;;;;AAIA;;;;;;;;;ACFF,IAAY,kEAAL;;AAEL;;AAEA;;AAEA"}

package/dist/factories/index.cjs

@@ -0,0 +1,19 @@
+
+//#region src/factories/pipeline-factory.ts
+/**
+* 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.
+*/
+let PipelineCategory = /* @__PURE__ */ function(PipelineCategory) {
+	PipelineCategory["module"] = "module";
+	PipelineCategory["runtime"] = "runtime";
+	PipelineCategory["system"] = "system";
+	return PipelineCategory;
+}({});
+
+//#endregion
+exports.PipelineCategory = PipelineCategory;
+//# sourceMappingURL=index.cjs.map

package/dist/factories/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/factories/pipeline-factory.ts"],"sourcesContent":["import { IPipelineContext } from '../pipelines';\r\nimport { IPipeline } from '../pipelines/pipeline';\r\n\r\n/**\r\n * Category identifier for grouping performance metrics.\r\n * Typed as string to allow extension beyond the built-in {@link PipelineCategory} values.\r\n */\r\nexport type PipelineCategoryName = string;\r\n\r\n/**\r\n * Built-in metric categories for classifying pipeline and middleware performance entries.\r\n *\r\n * - `module` — System module pipelines (initialize, update, render, sync phases).\r\n * - `runtime` — Runtime orchestration pipeline and its middleware.\r\n * - `system` — Individual system middleware within a module pipeline.\r\n */\r\nexport enum PipelineCategory {\r\n  module = 'module',\r\n  runtime = 'runtime',\r\n  system = 'system'\r\n}\r\n\r\n/**\r\n * Options for identifying and categorizing performance metrics on pipelines.\r\n */\r\nexport type PipelineMetricOptions = {\r\n  /** Display name for the pipeline in performance metrics. */\r\n  pipelineName: string;\r\n  /** Category assigned to pipeline-level metric entries. */\r\n  pipelineCategory: PipelineCategoryName;\r\n  /** Category assigned to per-middleware metric entries within this pipeline. */\r\n  middlewareCategory: PipelineCategoryName;\r\n};\r\n\r\n/**\r\n * Creates pipeline instances for various contexts.\r\n * Abstracts pipeline creation to support different implementations.\r\n * Used by the system to instantiate pipelines without coupling to specific implementations.\r\n */\r\nexport interface IPipelineFactory {\r\n  /**\r\n   * Creates a new pipeline for the specified context type.\r\n   * @template TContext - The context type for the pipeline. Must extend IPipelineContext.\r\n   * @param options - Optional performance metric options (name, category) for the pipeline.\r\n   * @returns A new pipeline instance ready for middleware registration.\r\n   */\r\n  createPipeline<TContext extends IPipelineContext>(\r\n    options?: PipelineMetricOptions\r\n  ): IPipeline<TContext>;\r\n}\r\n"],"mappings":";;;;;;;;;AAgBA,IAAY,8DAAL;AACL;AACA;AACA"}

package/dist/factories/index.d.cts

@@ -1,6 +1,6 @@
 import { a as IEntity } from "../identity-component-uU0yDR-y.cjs";
-import { l as IPipelineContext, o as IPipeline } from "../index-DZvjMjYZ.cjs";
-import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-J5AU4JAU.cjs";
+import { l as IPipelineContext, o as IPipeline } from "../index-cF9FviwN.cjs";
+import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-BoBx4MQT.cjs";
 
 //#region src/factories/context-factory.d.ts
 interface IContextFactory {
@@ -13,6 +13,31 @@ interface IContextFactory {
 }
 //#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.
@@ -22,10 +47,10 @@ interface IPipelineFactory {
   /**
    * Creates a new pipeline for the specified context type.
    * @template TContext - The context type for the pipeline. Must extend IPipelineContext.
-   * @param name - Optional name for the pipeline (useful for debugging).
+   * @param options - Optional performance metric options (name, category) for the pipeline.
    * @returns A new pipeline instance ready for middleware registration.
    */
-  createPipeline<TContext extends IPipelineContext>(name?: string): IPipeline<TContext>;
+  createPipeline<TContext extends IPipelineContext>(options?: PipelineMetricOptions): IPipeline<TContext>;
 }
 //#endregion
 //#region src/factories/runtime-factory.d.ts
@@ -60,10 +85,11 @@ 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>(): ISystemsModuleBuilder<TEntity>;
+  createSystemsModuleBuilder<TEntity extends IEntity>(name: string): ISystemsModuleBuilder<TEntity>;
 }
 //#endregion
-export { IContextFactory, IPipelineFactory, IRuntimeFactory, ISystemsFactory };
+export { IContextFactory, IPipelineFactory, IRuntimeFactory, ISystemsFactory, PipelineCategory, PipelineCategoryName, PipelineMetricOptions };
 //# sourceMappingURL=index.d.cts.map

package/dist/factories/index.d.mts

@@ -1,6 +1,6 @@
 import { a as IEntity } from "../identity-component-CgzvgBVh.mjs";
-import { l as IPipelineContext, o as IPipeline } from "../index-D4jK3qG1.mjs";
-import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-DULE7rVz.mjs";
+import { l as IPipelineContext, o as IPipeline } from "../index-CyoGuBNw.mjs";
+import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-CBIhhk81.mjs";
 
 //#region src/factories/context-factory.d.ts
 interface IContextFactory {
@@ -13,6 +13,31 @@ interface IContextFactory {
 }
 //#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.
@@ -22,10 +47,10 @@ interface IPipelineFactory {
   /**
    * Creates a new pipeline for the specified context type.
    * @template TContext - The context type for the pipeline. Must extend IPipelineContext.
-   * @param name - Optional name for the pipeline (useful for debugging).
+   * @param options - Optional performance metric options (name, category) for the pipeline.
    * @returns A new pipeline instance ready for middleware registration.
    */
-  createPipeline<TContext extends IPipelineContext>(name?: string): IPipeline<TContext>;
+  createPipeline<TContext extends IPipelineContext>(options?: PipelineMetricOptions): IPipeline<TContext>;
 }
 //#endregion
 //#region src/factories/runtime-factory.d.ts
@@ -60,10 +85,11 @@ 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>(): ISystemsModuleBuilder<TEntity>;
+  createSystemsModuleBuilder<TEntity extends IEntity>(name: string): ISystemsModuleBuilder<TEntity>;
 }
 //#endregion
-export { IContextFactory, IPipelineFactory, IRuntimeFactory, ISystemsFactory };
+export { IContextFactory, IPipelineFactory, IRuntimeFactory, ISystemsFactory, PipelineCategory, PipelineCategoryName, PipelineMetricOptions };
 //# sourceMappingURL=index.d.mts.map

package/dist/factories/index.mjs

@@ -1 +1,18 @@
-export {  };
+//#region src/factories/pipeline-factory.ts
+/**
+* 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.
+*/
+let PipelineCategory = /* @__PURE__ */ function(PipelineCategory) {
+	PipelineCategory["module"] = "module";
+	PipelineCategory["runtime"] = "runtime";
+	PipelineCategory["system"] = "system";
+	return PipelineCategory;
+}({});
+
+//#endregion
+export { PipelineCategory };
+//# sourceMappingURL=index.mjs.map

package/dist/factories/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/factories/pipeline-factory.ts"],"sourcesContent":["import { IPipelineContext } from '../pipelines';\r\nimport { IPipeline } from '../pipelines/pipeline';\r\n\r\n/**\r\n * Category identifier for grouping performance metrics.\r\n * Typed as string to allow extension beyond the built-in {@link PipelineCategory} values.\r\n */\r\nexport type PipelineCategoryName = string;\r\n\r\n/**\r\n * Built-in metric categories for classifying pipeline and middleware performance entries.\r\n *\r\n * - `module` — System module pipelines (initialize, update, render, sync phases).\r\n * - `runtime` — Runtime orchestration pipeline and its middleware.\r\n * - `system` — Individual system middleware within a module pipeline.\r\n */\r\nexport enum PipelineCategory {\r\n  module = 'module',\r\n  runtime = 'runtime',\r\n  system = 'system'\r\n}\r\n\r\n/**\r\n * Options for identifying and categorizing performance metrics on pipelines.\r\n */\r\nexport type PipelineMetricOptions = {\r\n  /** Display name for the pipeline in performance metrics. */\r\n  pipelineName: string;\r\n  /** Category assigned to pipeline-level metric entries. */\r\n  pipelineCategory: PipelineCategoryName;\r\n  /** Category assigned to per-middleware metric entries within this pipeline. */\r\n  middlewareCategory: PipelineCategoryName;\r\n};\r\n\r\n/**\r\n * Creates pipeline instances for various contexts.\r\n * Abstracts pipeline creation to support different implementations.\r\n * Used by the system to instantiate pipelines without coupling to specific implementations.\r\n */\r\nexport interface IPipelineFactory {\r\n  /**\r\n   * Creates a new pipeline for the specified context type.\r\n   * @template TContext - The context type for the pipeline. Must extend IPipelineContext.\r\n   * @param options - Optional performance metric options (name, category) for the pipeline.\r\n   * @returns A new pipeline instance ready for middleware registration.\r\n   */\r\n  createPipeline<TContext extends IPipelineContext>(\r\n    options?: PipelineMetricOptions\r\n  ): IPipeline<TContext>;\r\n}\r\n"],"mappings":";;;;;;;;AAgBA,IAAY,8DAAL;AACL;AACA;AACA"}

package/dist/{index-J5AU4JAU.d.cts → index-BoBx4MQT.d.cts}

@@ -1,8 +1,8 @@
 import { a as IEntity, c as IEntityProxy, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy } from "./identity-component-uU0yDR-y.cjs";
 import { n as Immutable } from "./types-DLOd2zXO.cjs";
-import { d as IEntityEvent, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, o as IEntitySnapshot, u as EntityEventUid } from "./index-qSeVF9hf.cjs";
-import { i as ILogger, n as PerformanceTimeEntry, s as IJsonSerializer } from "./index-eECJUE_O.cjs";
-import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-DZvjMjYZ.cjs";
+import { c as IEntitySnapshot, d as EntityEventSubscriptionOptions, f as EntityEventUid, g as IEventData, o as IEntityUpdate, p as IEntityEvent } from "./index-D_z9RbVT.cjs";
+import { a as ILogger, c as IJsonSerializer, r as PerformanceTimeEntry } from "./index-CmTRwW4W.cjs";
+import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-cF9FviwN.cjs";
 
 //#region src/systems/pipeline/system-context-events.d.ts
 /**
@@ -356,6 +356,10 @@ type ISystemMiddleware<TEntity extends IEntity> = IMiddleware<ISystemContext<TEn
  * @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.
@@ -512,4 +516,4 @@ interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineConte
 type ISystemsRuntimeMiddleware<TEntity extends IEntity> = IMiddleware<ISystemsRuntimeContext<TEntity>>;
 //#endregion
 export { ISystemsModuleRepository as a, ISystemsModule as c, ISystemContextSnapshot as d, ISystemContextScheduler as f, ISystemContextEvents as h, ISystemContextEntity as i, SystemType as l, ISystemContextProxies as m, ISystemsRuntimeContext as n, ISystemsModuleBuilder as o, ISystemContextRepository as p, ISystemsRuntime as r, ISystemMiddleware as s, ISystemsRuntimeMiddleware as t, ISystemContext as u };
-//# sourceMappingURL=index-J5AU4JAU.d.cts.map
+//# sourceMappingURL=index-BoBx4MQT.d.cts.map

package/dist/{index-DULE7rVz.d.mts → index-CBIhhk81.d.mts}

@@ -1,8 +1,8 @@
 import { a as IEntity, c as IEntityProxy, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy } from "./identity-component-CgzvgBVh.mjs";
 import { n as Immutable } from "./types-CnDtpKsY.mjs";
-import { d as IEntityEvent, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, o as IEntitySnapshot, u as EntityEventUid } from "./index-CfEs8NEA.mjs";
-import { i as ILogger, n as PerformanceTimeEntry, s as IJsonSerializer } from "./index-BWmhFdFg.mjs";
-import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-D4jK3qG1.mjs";
+import { c as IEntitySnapshot, d as EntityEventSubscriptionOptions, f as EntityEventUid, g as IEventData, o as IEntityUpdate, p as IEntityEvent } from "./index-ke1H7wmC.mjs";
+import { a as ILogger, c as IJsonSerializer, r as PerformanceTimeEntry } from "./index-Iqc9jR5E.mjs";
+import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-CyoGuBNw.mjs";
 
 //#region src/systems/pipeline/system-context-events.d.ts
 /**
@@ -356,6 +356,10 @@ type ISystemMiddleware<TEntity extends IEntity> = IMiddleware<ISystemContext<TEn
  * @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.
@@ -512,4 +516,4 @@ interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineConte
 type ISystemsRuntimeMiddleware<TEntity extends IEntity> = IMiddleware<ISystemsRuntimeContext<TEntity>>;
 //#endregion
 export { ISystemsModuleRepository as a, ISystemsModule as c, ISystemContextSnapshot as d, ISystemContextScheduler as f, ISystemContextEvents as h, ISystemContextEntity as i, SystemType as l, ISystemContextProxies as m, ISystemsRuntimeContext as n, ISystemsModuleBuilder as o, ISystemContextRepository as p, ISystemsRuntime as r, ISystemMiddleware as s, ISystemsRuntimeMiddleware as t, ISystemContext as u };
-//# sourceMappingURL=index-DULE7rVz.d.mts.map
+//# sourceMappingURL=index-CBIhhk81.d.mts.map

package/dist/{index-BWmhFdFg.d.mts → index-CmTRwW4W.d.cts}

@@ -102,6 +102,14 @@ interface ILoggerOptions {
  * 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.
@@ -111,6 +119,10 @@ 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.
    */
@@ -133,9 +145,10 @@ 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): PerformanceTimerUid;
+  startTimer(name: string, category?: string): PerformanceTimerUid;
   /**
    * Stops a timer and returns the recorded metrics.
    * @param timerUid - The timer identifier returned by startTimer.
@@ -144,5 +157,5 @@ interface IPerformanceTimer {
   endTimer(timerUid: PerformanceTimerUid): PerformanceTimeEntry;
 }
 //#endregion
-export { ILoggerOptions as a, ILogger as i, PerformanceTimeEntry as n, LogLevel as o, PerformanceTimerUid as r, IJsonSerializer as s, IPerformanceTimer as t };
-//# sourceMappingURL=index-BWmhFdFg.d.mts.map
+export { ILogger as a, IJsonSerializer as c, PerformanceTimerUid as i, PerformanceMetricOptions as n, ILoggerOptions as o, PerformanceTimeEntry as r, LogLevel as s, IPerformanceTimer as t };
+//# sourceMappingURL=index-CmTRwW4W.d.cts.map

package/dist/{index-D4jK3qG1.d.mts → index-CyoGuBNw.d.mts}

@@ -1,5 +1,5 @@
 import { n as Immutable } from "./types-CnDtpKsY.mjs";
-import { n as PerformanceTimeEntry } from "./index-BWmhFdFg.mjs";
+import { r as PerformanceTimeEntry } from "./index-Iqc9jR5E.mjs";
 
 //#region src/pipelines/pipeline-context.d.ts
 /**
@@ -221,4 +221,4 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
 }
 //#endregion
 export { IParentMiddleware as a, IMiddleware as c, IParentContext as i, IPipelineContext as l, INestedContext as n, IPipeline as o, INestedMiddleware as r, IMiddlewareRunner as s, IPipelineRunner as t, PipelineRuntime as u };
-//# sourceMappingURL=index-D4jK3qG1.d.mts.map
+//# sourceMappingURL=index-CyoGuBNw.d.mts.map

package/dist/{index-qSeVF9hf.d.cts → index-D_z9RbVT.d.cts}

@@ -299,20 +299,65 @@ interface IEntityRepository {
 }
 //#endregion
 //#region src/entities/entity-scheduler.d.ts
+/**
+ * Describes a scheduled entity update, including the target entity and optional interval.
+ */
+type EntitySchedule = {
+  readonly proxy: IEntityProxy;
+  readonly intervalMs?: number;
+};
+/**
+ * Controls which scheduling modes are paused.
+ */
+declare enum SchedulerPauseType {
+  /** Pause both interval timers and frame subscriptions. */
+  full = "full",
+  /** Pause only frame subscriptions. Interval timers continue firing. */
+  perFrame = "perFrame",
+  /** Pause only interval timers. Frame subscriptions continue. */
+  intervals = "intervals"
+}
 /**
  * Manages time-based scheduling of entity updates.
- * Entities are registered with intervals and receive updates at the specified cadence, or on the next frame (engine-dependent).
+ *
+ * Entities can be scheduled with an interval (timer-driven) or without one (per-frame).
+ * The runtime pulls pending entities each tick via the {@link pending} iterator,
+ * which yields both per-frame subscriptions and interval entities whose timer has fired.
  */
 interface IEntityScheduler {
   /**
-   * Registers an entity for periodic updates.
+   * Returns all currently scheduled entities with their configuration.
+   * Useful for inspection and debugging.
+   */
+  readonly schedules: ReadonlyArray<EntitySchedule>;
+  /**
+   * Yields entities pending processing this tick: per-frame subscriptions
+   * followed by interval entities whose timer has fired since the last drain.
+   * Iterating drains the due interval buckets; a second iteration without
+   * timer advancement yields only per-frame subscriptions.
+   */
+  readonly pending: IterableIterator<IEntityProxy>;
+  /**
+   * The set of entities scheduled for per-frame updates (no interval).
+   */
+  readonly frameSubscriptions: ReadonlySet<IEntityProxy>;
+  /**
+   * The number of entities currently awaiting processing:
+   * per-frame subscriptions (if not paused) plus interval entities whose timer has fired.
+   */
+  readonly pendingCount: number;
+  /**
+   * Whether the scheduler is currently paused in any mode.
+   */
+  readonly isPaused: boolean;
+  /**
+   * Registers an entity for updates.
    * @param entityProxy - The entity to schedule.
-   * @param intervalMs - Update frequency in milliseconds. If omitted, a default interval is used.
+   * @param intervalMs - Update frequency in milliseconds. If omitted, the entity is scheduled per-frame.
    */
   schedule(entityProxy: IEntityProxy, intervalMs?: number): void;
   /**
    * Unregisters an entity from the scheduler.
-   * The entity will no longer receive periodic updates.
    * @param entityProxy - The entity to unschedule.
    */
   remove(entityProxy: IEntityProxy): void;
@@ -322,7 +367,33 @@ interface IEntityScheduler {
    * @returns True if the entity is scheduled, false otherwise.
    */
   has(entityProxy: IEntityProxy): boolean;
+  /**
+   * Removes all schedules and clears all timers.
+   */
+  clear(): void;
+  /**
+   * Entity types currently excluded from {@link pending} iteration.
+   */
+  readonly skippedEntityTypes: ReadonlySet<EntityTypeUid>;
+  /**
+   * Excludes an entity type from {@link pending} iteration.
+   * Entities remain registered; only yielding is suppressed.
+   */
+  skipEntityType(entityType: EntityTypeUid): void;
+  /**
+   * Re-includes a previously skipped entity type in {@link pending} iteration.
+   */
+  unskipEntityType(entityType: EntityTypeUid): void;
+  /**
+   * Pauses the scheduler.
+   * @param type - Which scheduling modes to pause. Defaults to {@link SchedulerPauseType.full}.
+   */
+  pause(type?: SchedulerPauseType): void;
+  /**
+   * Resumes the scheduler from any paused state.
+   */
+  resume(): void;
 }
 //#endregion
-export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEvent as d, IEntityEventsDispatcher as f, IEntityUpdate as i, EntityEventSubscriptionOptions as l, IEventData as m, IEntityRepository as n, IEntitySnapshot as o, IEntityEventsManager as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, EntityEventUid as u };
-//# sourceMappingURL=index-qSeVF9hf.d.cts.map
+export { EntityUpdateType as a, IEntitySnapshot as c, EntityEventSubscriptionOptions as d, EntityEventUid as f, IEventData as g, IEntityEventsManager as h, IEntityRepository as i, IEntitySnapshotProvider as l, IEntityEventsDispatcher as m, IEntityScheduler as n, IEntityUpdate as o, IEntityEvent as p, SchedulerPauseType as r, IEntityUpdateQueue as s, EntitySchedule as t, EntityEventSubscriptionFilter as u };
+//# sourceMappingURL=index-D_z9RbVT.d.cts.map

package/dist/{index-eECJUE_O.d.cts → index-Iqc9jR5E.d.mts}

@@ -102,6 +102,14 @@ interface ILoggerOptions {
  * 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.
@@ -111,6 +119,10 @@ 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.
    */
@@ -133,9 +145,10 @@ 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): PerformanceTimerUid;
+  startTimer(name: string, category?: string): PerformanceTimerUid;
   /**
    * Stops a timer and returns the recorded metrics.
    * @param timerUid - The timer identifier returned by startTimer.
@@ -144,5 +157,5 @@ interface IPerformanceTimer {
   endTimer(timerUid: PerformanceTimerUid): PerformanceTimeEntry;
 }
 //#endregion
-export { ILoggerOptions as a, ILogger as i, PerformanceTimeEntry as n, LogLevel as o, PerformanceTimerUid as r, IJsonSerializer as s, IPerformanceTimer as t };
-//# sourceMappingURL=index-eECJUE_O.d.cts.map
+export { ILogger as a, IJsonSerializer as c, PerformanceTimerUid as i, PerformanceMetricOptions as n, ILoggerOptions as o, PerformanceTimeEntry as r, LogLevel as s, IPerformanceTimer as t };
+//# sourceMappingURL=index-Iqc9jR5E.d.mts.map

package/dist/{index-DZvjMjYZ.d.cts → index-cF9FviwN.d.cts}

@@ -1,5 +1,5 @@
 import { n as Immutable } from "./types-DLOd2zXO.cjs";
-import { n as PerformanceTimeEntry } from "./index-eECJUE_O.cjs";
+import { r as PerformanceTimeEntry } from "./index-CmTRwW4W.cjs";
 
 //#region src/pipelines/pipeline-context.d.ts
 /**
@@ -221,4 +221,4 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
 }
 //#endregion
 export { IParentMiddleware as a, IMiddleware as c, IParentContext as i, IPipelineContext as l, INestedContext as n, IPipeline as o, INestedMiddleware as r, IMiddlewareRunner as s, IPipelineRunner as t, PipelineRuntime as u };
-//# sourceMappingURL=index-DZvjMjYZ.d.cts.map
+//# sourceMappingURL=index-cF9FviwN.d.cts.map

package/dist/{index-CfEs8NEA.d.mts → index-ke1H7wmC.d.mts}

@@ -299,20 +299,65 @@ interface IEntityRepository {
 }
 //#endregion
 //#region src/entities/entity-scheduler.d.ts
+/**
+ * Describes a scheduled entity update, including the target entity and optional interval.
+ */
+type EntitySchedule = {
+  readonly proxy: IEntityProxy;
+  readonly intervalMs?: number;
+};
+/**
+ * Controls which scheduling modes are paused.
+ */
+declare enum SchedulerPauseType {
+  /** Pause both interval timers and frame subscriptions. */
+  full = "full",
+  /** Pause only frame subscriptions. Interval timers continue firing. */
+  perFrame = "perFrame",
+  /** Pause only interval timers. Frame subscriptions continue. */
+  intervals = "intervals"
+}
 /**
  * Manages time-based scheduling of entity updates.
- * Entities are registered with intervals and receive updates at the specified cadence, or on the next frame (engine-dependent).
+ *
+ * Entities can be scheduled with an interval (timer-driven) or without one (per-frame).
+ * The runtime pulls pending entities each tick via the {@link pending} iterator,
+ * which yields both per-frame subscriptions and interval entities whose timer has fired.
  */
 interface IEntityScheduler {
   /**
-   * Registers an entity for periodic updates.
+   * Returns all currently scheduled entities with their configuration.
+   * Useful for inspection and debugging.
+   */
+  readonly schedules: ReadonlyArray<EntitySchedule>;
+  /**
+   * Yields entities pending processing this tick: per-frame subscriptions
+   * followed by interval entities whose timer has fired since the last drain.
+   * Iterating drains the due interval buckets; a second iteration without
+   * timer advancement yields only per-frame subscriptions.
+   */
+  readonly pending: IterableIterator<IEntityProxy>;
+  /**
+   * The set of entities scheduled for per-frame updates (no interval).
+   */
+  readonly frameSubscriptions: ReadonlySet<IEntityProxy>;
+  /**
+   * The number of entities currently awaiting processing:
+   * per-frame subscriptions (if not paused) plus interval entities whose timer has fired.
+   */
+  readonly pendingCount: number;
+  /**
+   * Whether the scheduler is currently paused in any mode.
+   */
+  readonly isPaused: boolean;
+  /**
+   * Registers an entity for updates.
    * @param entityProxy - The entity to schedule.
-   * @param intervalMs - Update frequency in milliseconds. If omitted, a default interval is used.
+   * @param intervalMs - Update frequency in milliseconds. If omitted, the entity is scheduled per-frame.
    */
   schedule(entityProxy: IEntityProxy, intervalMs?: number): void;
   /**
    * Unregisters an entity from the scheduler.
-   * The entity will no longer receive periodic updates.
    * @param entityProxy - The entity to unschedule.
    */
   remove(entityProxy: IEntityProxy): void;
@@ -322,7 +367,33 @@ interface IEntityScheduler {
    * @returns True if the entity is scheduled, false otherwise.
    */
   has(entityProxy: IEntityProxy): boolean;
+  /**
+   * Removes all schedules and clears all timers.
+   */
+  clear(): void;
+  /**
+   * Entity types currently excluded from {@link pending} iteration.
+   */
+  readonly skippedEntityTypes: ReadonlySet<EntityTypeUid>;
+  /**
+   * Excludes an entity type from {@link pending} iteration.
+   * Entities remain registered; only yielding is suppressed.
+   */
+  skipEntityType(entityType: EntityTypeUid): void;
+  /**
+   * Re-includes a previously skipped entity type in {@link pending} iteration.
+   */
+  unskipEntityType(entityType: EntityTypeUid): void;
+  /**
+   * Pauses the scheduler.
+   * @param type - Which scheduling modes to pause. Defaults to {@link SchedulerPauseType.full}.
+   */
+  pause(type?: SchedulerPauseType): void;
+  /**
+   * Resumes the scheduler from any paused state.
+   */
+  resume(): void;
 }
 //#endregion
-export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEvent as d, IEntityEventsDispatcher as f, IEntityUpdate as i, EntityEventSubscriptionOptions as l, IEventData as m, IEntityRepository as n, IEntitySnapshot as o, IEntityEventsManager as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, EntityEventUid as u };
-//# sourceMappingURL=index-CfEs8NEA.d.mts.map
+export { EntityUpdateType as a, IEntitySnapshot as c, EntityEventSubscriptionOptions as d, EntityEventUid as f, IEventData as g, IEntityEventsManager as h, IEntityRepository as i, IEntitySnapshotProvider as l, IEntityEventsDispatcher as m, IEntityScheduler as n, IEntityUpdate as o, IEntityEvent as p, SchedulerPauseType as r, IEntityUpdateQueue as s, EntitySchedule as t, EntityEventSubscriptionFilter as u };
+//# sourceMappingURL=index-ke1H7wmC.d.mts.map

package/dist/pipelines/index.d.cts

@@ -1,2 +1,2 @@
-import { a as IParentMiddleware, c as IMiddleware, i as IParentContext, l as IPipelineContext, n as INestedContext, o as IPipeline, r as INestedMiddleware, s as IMiddlewareRunner, t as IPipelineRunner, u as PipelineRuntime } from "../index-DZvjMjYZ.cjs";
+import { a as IParentMiddleware, c as IMiddleware, i as IParentContext, l as IPipelineContext, n as INestedContext, o as IPipeline, r as INestedMiddleware, s as IMiddlewareRunner, t as IPipelineRunner, u as PipelineRuntime } from "../index-cF9FviwN.cjs";
 export { IMiddleware, IMiddlewareRunner, INestedContext, INestedMiddleware, IParentContext, IParentMiddleware, IPipeline, IPipelineContext, IPipelineRunner, PipelineRuntime };

package/dist/pipelines/index.d.mts

@@ -1,2 +1,2 @@
-import { a as IParentMiddleware, c as IMiddleware, i as IParentContext, l as IPipelineContext, n as INestedContext, o as IPipeline, r as INestedMiddleware, s as IMiddlewareRunner, t as IPipelineRunner, u as PipelineRuntime } from "../index-D4jK3qG1.mjs";
+import { a as IParentMiddleware, c as IMiddleware, i as IParentContext, l as IPipelineContext, n as INestedContext, o as IPipeline, r as INestedMiddleware, s as IMiddlewareRunner, t as IPipelineRunner, u as PipelineRuntime } from "../index-CyoGuBNw.mjs";
 export { IMiddleware, IMiddlewareRunner, INestedContext, INestedMiddleware, IParentContext, IParentMiddleware, IPipeline, IPipelineContext, IPipelineRunner, PipelineRuntime };

package/dist/systems/index.d.cts

@@ -1,2 +1,2 @@
-import { a as ISystemsModuleRepository, c as ISystemsModule, d as ISystemContextSnapshot, f as ISystemContextScheduler, h as ISystemContextEvents, i as ISystemContextEntity, l as SystemType, m as ISystemContextProxies, n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, p as ISystemContextRepository, r as ISystemsRuntime, s as ISystemMiddleware, t as ISystemsRuntimeMiddleware, u as ISystemContext } from "../index-J5AU4JAU.cjs";
+import { a as ISystemsModuleRepository, c as ISystemsModule, d as ISystemContextSnapshot, f as ISystemContextScheduler, h as ISystemContextEvents, i as ISystemContextEntity, l as SystemType, m as ISystemContextProxies, n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, p as ISystemContextRepository, r as ISystemsRuntime, s as ISystemMiddleware, t as ISystemsRuntimeMiddleware, u as ISystemContext } from "../index-BoBx4MQT.cjs";
 export { ISystemContext, ISystemContextEntity, ISystemContextEvents, ISystemContextProxies, ISystemContextRepository, ISystemContextScheduler, ISystemContextSnapshot, ISystemMiddleware, ISystemsModule, ISystemsModuleBuilder, ISystemsModuleRepository, ISystemsRuntime, ISystemsRuntimeContext, ISystemsRuntimeMiddleware, SystemType };

package/dist/systems/index.d.mts

@@ -1,2 +1,2 @@
-import { a as ISystemsModuleRepository, c as ISystemsModule, d as ISystemContextSnapshot, f as ISystemContextScheduler, h as ISystemContextEvents, i as ISystemContextEntity, l as SystemType, m as ISystemContextProxies, n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, p as ISystemContextRepository, r as ISystemsRuntime, s as ISystemMiddleware, t as ISystemsRuntimeMiddleware, u as ISystemContext } from "../index-DULE7rVz.mjs";
+import { a as ISystemsModuleRepository, c as ISystemsModule, d as ISystemContextSnapshot, f as ISystemContextScheduler, h as ISystemContextEvents, i as ISystemContextEntity, l as SystemType, m as ISystemContextProxies, n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, p as ISystemContextRepository, r as ISystemsRuntime, s as ISystemMiddleware, t as ISystemsRuntimeMiddleware, u as ISystemContext } from "../index-CBIhhk81.mjs";
 export { ISystemContext, ISystemContextEntity, ISystemContextEvents, ISystemContextProxies, ISystemContextRepository, ISystemContextScheduler, ISystemContextSnapshot, ISystemMiddleware, ISystemsModule, ISystemsModuleBuilder, ISystemsModuleRepository, ISystemsRuntime, ISystemsRuntimeContext, ISystemsRuntimeMiddleware, SystemType };

package/dist/utils/index.d.cts

@@ -1,3 +1,3 @@
 import { a as ImmutableObject, c as Mutable, i as ImmutableMap, l as MutableDeep, n as Immutable, o as ImmutableObjectDeep, r as ImmutableArray, s as ImmutableSet, t as BooleanProps } from "../types-DLOd2zXO.cjs";
-import { a as ILoggerOptions, i as ILogger, n as PerformanceTimeEntry, o as LogLevel, r as PerformanceTimerUid, s as IJsonSerializer, t as IPerformanceTimer } from "../index-eECJUE_O.cjs";
-export { BooleanProps, IJsonSerializer, ILogger, ILoggerOptions, IPerformanceTimer, Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableObjectDeep, ImmutableSet, LogLevel, Mutable, MutableDeep, PerformanceTimeEntry, PerformanceTimerUid };
+import { a as ILogger, c as IJsonSerializer, i as PerformanceTimerUid, n as PerformanceMetricOptions, o as ILoggerOptions, r as PerformanceTimeEntry, s as LogLevel, t as IPerformanceTimer } from "../index-CmTRwW4W.cjs";
+export { BooleanProps, IJsonSerializer, ILogger, ILoggerOptions, IPerformanceTimer, Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableObjectDeep, ImmutableSet, LogLevel, Mutable, MutableDeep, PerformanceMetricOptions, PerformanceTimeEntry, PerformanceTimerUid };

package/dist/utils/index.d.mts

@@ -1,3 +1,3 @@
 import { a as ImmutableObject, c as Mutable, i as ImmutableMap, l as MutableDeep, n as Immutable, o as ImmutableObjectDeep, r as ImmutableArray, s as ImmutableSet, t as BooleanProps } from "../types-CnDtpKsY.mjs";
-import { a as ILoggerOptions, i as ILogger, n as PerformanceTimeEntry, o as LogLevel, r as PerformanceTimerUid, s as IJsonSerializer, t as IPerformanceTimer } from "../index-BWmhFdFg.mjs";
-export { BooleanProps, IJsonSerializer, ILogger, ILoggerOptions, IPerformanceTimer, Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableObjectDeep, ImmutableSet, LogLevel, Mutable, MutableDeep, PerformanceTimeEntry, PerformanceTimerUid };
+import { a as ILogger, c as IJsonSerializer, i as PerformanceTimerUid, n as PerformanceMetricOptions, o as ILoggerOptions, r as PerformanceTimeEntry, s as LogLevel, t as IPerformanceTimer } from "../index-Iqc9jR5E.mjs";
+export { BooleanProps, IJsonSerializer, ILogger, ILoggerOptions, IPerformanceTimer, Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableObjectDeep, ImmutableSet, LogLevel, Mutable, MutableDeep, PerformanceMetricOptions, PerformanceTimeEntry, PerformanceTimerUid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesome-ecs/abstract",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "A comprehensive Entity-Component-System (ECS) Architecture implementation. Abstract components.",
   "type": "module",
   "scripts": {
@@ -97,5 +97,5 @@
     "url": "https://github.com/privatebytes/awesome-ecs/issues"
   },
   "homepage": "https://github.com/privatebytes/awesome-ecs#readme",
-  "gitHead": "1146c6993998eaf82e765a7822d6cde176857a89"
+  "gitHead": "455478d411536325b36f39780c59941b14e633c4"
 }