@awesome-ecs/abstract 0.23.0 → 0.25.0

package/dist/components/index.d.cts

@@ -1,2 +1,2 @@
-import { m as IComponent, n as IdentityComponent, p as ComponentTypeUid, t as BasicComponentType } from "../identity-component-5neFUd2Q.cjs";
+import { f as ComponentTypeUid, n as IdentityComponent, p as IComponent, t as BasicComponentType } from "../identity-component-uU0yDR-y.cjs";
 export { BasicComponentType, ComponentTypeUid, IComponent, IdentityComponent };

package/dist/components/index.d.mts

@@ -1,2 +1,2 @@
-import { m as IComponent, n as IdentityComponent, p as ComponentTypeUid, t as BasicComponentType } from "../identity-component-BCmEilvk.mjs";
+import { f as ComponentTypeUid, n as IdentityComponent, p as IComponent, t as BasicComponentType } from "../identity-component-CgzvgBVh.mjs";
 export { BasicComponentType, ComponentTypeUid, IComponent, IdentityComponent };

package/dist/entities/index.d.cts

@@ -1,3 +1,3 @@
-import { a as IEntity, c as EntityProxy, d as RequiredProxies, f as TypedEntityProxy, i as EntityUid, l as IEntityProxy, o as IEntityModel, r as EntityTypeUid, s as IEntityModelWithRequiredProxies, u as IEntityProxyRepository } from "../identity-component-5neFUd2Q.cjs";
-import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEventsDispatcher, f as IEntityEventsManager, i as IEntityUpdate, l as EntityEventUid, n as IEntityRepository, o as IEntitySnapshot, p as IEventData, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as IEntityEvent } from "../index-6OSsa_UD.cjs";
-export { EntityEventSubscriptionFilter, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };
+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 IEntityUpdate, c as IEntitySnapshotProvider, d as EntityEventUid, f as IEntityEvent, h as IEventData, i as EntityUpdateType, l as EntityEventSubscriptionFilter, m as IEntityEventsManager, n as IEntityScheduler, o as IEntityUpdateQueue, p as IEntityEventsDispatcher, r as IEntityRepository, s as IEntitySnapshot, t as EntitySchedule, u as EntityEventSubscriptionOptions } from "../index-CY3I0Xdn.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, TypedEntityProxy };

package/dist/entities/index.d.mts

@@ -1,3 +1,3 @@
-import { a as IEntity, c as EntityProxy, d as RequiredProxies, f as TypedEntityProxy, i as EntityUid, l as IEntityProxy, o as IEntityModel, r as EntityTypeUid, s as IEntityModelWithRequiredProxies, u as IEntityProxyRepository } from "../identity-component-BCmEilvk.mjs";
-import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEventsDispatcher, f as IEntityEventsManager, i as IEntityUpdate, l as EntityEventUid, n as IEntityRepository, o as IEntitySnapshot, p as IEventData, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as IEntityEvent } from "../index-CQpE-5sx.mjs";
-export { EntityEventSubscriptionFilter, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };
+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 IEntityUpdate, c as IEntitySnapshotProvider, d as EntityEventUid, f as IEntityEvent, h as IEventData, i as EntityUpdateType, l as EntityEventSubscriptionFilter, m as IEntityEventsManager, n as IEntityScheduler, o as IEntityUpdateQueue, p as IEntityEventsDispatcher, r as IEntityRepository, s as IEntitySnapshot, t as EntitySchedule, u as EntityEventSubscriptionOptions } from "../index-CT8ci9Cn.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, TypedEntityProxy };

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';\nimport { IPipeline } from '../pipelines/pipeline';\n\n/**\n * Category identifier for grouping performance metrics.\n * Typed as string to allow extension beyond the built-in {@link PipelineCategory} values.\n */\nexport type PipelineCategoryName = string;\n\n/**\n * Built-in metric categories for classifying pipeline and middleware performance entries.\n *\n * - `module` — System module pipelines (initialize, update, render, sync phases).\n * - `runtime` — Runtime orchestration pipeline and its middleware.\n * - `system` — Individual system middleware within a module pipeline.\n */\nexport enum PipelineCategory {\n  module = 'module',\n  runtime = 'runtime',\n  system = 'system'\n}\n\n/**\n * Options for identifying and categorizing performance metrics on pipelines.\n */\nexport type PipelineMetricOptions = {\n  /** Display name for the pipeline in performance metrics. */\n  pipelineName: string;\n  /** Category assigned to pipeline-level metric entries. */\n  pipelineCategory: PipelineCategoryName;\n  /** Category assigned to per-middleware metric entries within this pipeline. */\n  middlewareCategory: PipelineCategoryName;\n};\n\n/**\n * Creates pipeline instances for various contexts.\n * Abstracts pipeline creation to support different implementations.\n * Used by the system to instantiate pipelines without coupling to specific implementations.\n */\nexport interface IPipelineFactory {\n  /**\n   * Creates a new pipeline for the specified context type.\n   * @template TContext - The context type for the pipeline. Must extend IPipelineContext.\n   * @param options - Optional performance metric options (name, category) for the pipeline.\n   * @returns A new pipeline instance ready for middleware registration.\n   */\n  createPipeline<TContext extends IPipelineContext>(\n    options?: PipelineMetricOptions\n  ): IPipeline<TContext>;\n}\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-5neFUd2Q.cjs";
-import { l as IPipelineContext, o as IPipeline } from "../index-BUadwkVZ.cjs";
-import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-BtPTY71-.cjs";
+import { a as IEntity } from "../identity-component-uU0yDR-y.cjs";
+import { l as IPipelineContext, o as IPipeline } from "../index-cF9FviwN.cjs";
+import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-CR3yK5HE.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-BCmEilvk.mjs";
-import { l as IPipelineContext, o as IPipeline } from "../index-DcirKLCP.mjs";
-import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-CW6-OhB4.mjs";
+import { a as IEntity } from "../identity-component-CgzvgBVh.mjs";
+import { l as IPipelineContext, o as IPipeline } from "../index-CyoGuBNw.mjs";
+import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-ei6_lV4I.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';\nimport { IPipeline } from '../pipelines/pipeline';\n\n/**\n * Category identifier for grouping performance metrics.\n * Typed as string to allow extension beyond the built-in {@link PipelineCategory} values.\n */\nexport type PipelineCategoryName = string;\n\n/**\n * Built-in metric categories for classifying pipeline and middleware performance entries.\n *\n * - `module` — System module pipelines (initialize, update, render, sync phases).\n * - `runtime` — Runtime orchestration pipeline and its middleware.\n * - `system` — Individual system middleware within a module pipeline.\n */\nexport enum PipelineCategory {\n  module = 'module',\n  runtime = 'runtime',\n  system = 'system'\n}\n\n/**\n * Options for identifying and categorizing performance metrics on pipelines.\n */\nexport type PipelineMetricOptions = {\n  /** Display name for the pipeline in performance metrics. */\n  pipelineName: string;\n  /** Category assigned to pipeline-level metric entries. */\n  pipelineCategory: PipelineCategoryName;\n  /** Category assigned to per-middleware metric entries within this pipeline. */\n  middlewareCategory: PipelineCategoryName;\n};\n\n/**\n * Creates pipeline instances for various contexts.\n * Abstracts pipeline creation to support different implementations.\n * Used by the system to instantiate pipelines without coupling to specific implementations.\n */\nexport interface IPipelineFactory {\n  /**\n   * Creates a new pipeline for the specified context type.\n   * @template TContext - The context type for the pipeline. Must extend IPipelineContext.\n   * @param options - Optional performance metric options (name, category) for the pipeline.\n   * @returns A new pipeline instance ready for middleware registration.\n   */\n  createPipeline<TContext extends IPipelineContext>(\n    options?: PipelineMetricOptions\n  ): IPipeline<TContext>;\n}\n"],"mappings":";;;;;;;;AAgBA,IAAY,8DAAL;AACL;AACA;AACA"}

package/dist/{identity-component-BCmEilvk.d.mts → identity-component-CgzvgBVh.d.mts}

@@ -132,6 +132,27 @@ interface IEntityProxyRepository {
    * @returns A readonly map of entity type UIDs to an array of their proxies.
    */
   getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+  /**
+   * Registers an entity as a scoped proxy, making it resolvable by any entity in the same scope.
+   * Only entity types marked as scopeRoot or scopedProxy should be registered.
+   * @param entity - The entity to register as a scoped proxy.
+   * @param scopeId - The scope in which to register.
+   */
+  setScopedProxy(entity: IEntityProxy, scopeId: string): void;
+  /**
+   * Retrieves a scoped proxy by scope ID and entity type.
+   * @param scopeId - The scope to look up.
+   * @param entityType - The entity type to resolve.
+   * @returns The scoped proxy, or null if none exists.
+   */
+  getScopedProxy(scopeId: string, entityType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Removes an entity from the scoped proxy index.
+   * Called during entity cleanup to unregister from scope resolution.
+   * @param entity - The entity to remove.
+   * @param scopeId - The scope to remove from.
+   */
+  removeScopedProxy(entity: IEntityProxy, scopeId: string): void;
 }
 //#endregion
 //#region src/entities/entity.d.ts
@@ -147,32 +168,24 @@ type EntityTypeUid = string | number;
 type EntityUid = string | number;
 /**
  * Represents the core identification and initialization data for an entity.
- * Every entity must have a model containing the minimal information needed for instantiation.
- * Models are immutable and define the entity's initial structure.
+ * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies when creating an entity.
  */
-interface IEntityModel {
+interface IEntityModel<TProxyTypes extends readonly EntityTypeUid[] = undefined> {
   /**
    * The unique identifier for this entity instance.
    */
   readonly uid: EntityUid;
   /**
-   * Optional array of proxies (references) to other entities.
-   * Used to establish relationships at entity creation time.
+   * The scope this entity belongs to.
+   * Automatically set by the framework — scopeRoot entities generate a UUID,
+   * child entities inherit from their parent via addEntity().
    */
-  readonly proxies?: readonly IEntityProxy[];
-}
-/**
- * Entity model with enforced required proxy relationships.
- * Used when an entity requires specific relationships to be present from creation.
- *
- * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies.
- */
-interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends IEntityModel {
+  readonly scopeId?: string;
   /**
-   * Required proxies for this entity.
-   * The array structure matches the TProxyTypes template to ensure type-safe proxy definitions.
+   * Optional array of proxies (references) to other entities.
+   * Used to establish relationships at entity creation time.
    */
-  readonly proxies: RequiredProxies<TProxyTypes>;
+  readonly proxies?: RequiredProxies<TProxyTypes>;
 }
 /**
  * The core entity interface representing a composition of components and relationships.
@@ -237,5 +250,5 @@ interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
   readonly lastUpdated?: Date;
 }
 //#endregion
-export { IEntity as a, EntityProxy as c, RequiredProxies as d, TypedEntityProxy as f, EntityUid as i, IEntityProxy as l, IComponent as m, IdentityComponent as n, IEntityModel as o, ComponentTypeUid as p, EntityTypeUid as r, IEntityModelWithRequiredProxies as s, BasicComponentType as t, IEntityProxyRepository as u };
-//# sourceMappingURL=identity-component-BCmEilvk.d.mts.map
+export { IEntity as a, IEntityProxy as c, TypedEntityProxy as d, ComponentTypeUid as f, EntityUid as i, IEntityProxyRepository as l, IdentityComponent as n, IEntityModel as o, IComponent as p, EntityTypeUid as r, EntityProxy as s, BasicComponentType as t, RequiredProxies as u };
+//# sourceMappingURL=identity-component-CgzvgBVh.d.mts.map

package/dist/{identity-component-5neFUd2Q.d.cts → identity-component-uU0yDR-y.d.cts}

@@ -132,6 +132,27 @@ interface IEntityProxyRepository {
    * @returns A readonly map of entity type UIDs to an array of their proxies.
    */
   getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+  /**
+   * Registers an entity as a scoped proxy, making it resolvable by any entity in the same scope.
+   * Only entity types marked as scopeRoot or scopedProxy should be registered.
+   * @param entity - The entity to register as a scoped proxy.
+   * @param scopeId - The scope in which to register.
+   */
+  setScopedProxy(entity: IEntityProxy, scopeId: string): void;
+  /**
+   * Retrieves a scoped proxy by scope ID and entity type.
+   * @param scopeId - The scope to look up.
+   * @param entityType - The entity type to resolve.
+   * @returns The scoped proxy, or null if none exists.
+   */
+  getScopedProxy(scopeId: string, entityType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Removes an entity from the scoped proxy index.
+   * Called during entity cleanup to unregister from scope resolution.
+   * @param entity - The entity to remove.
+   * @param scopeId - The scope to remove from.
+   */
+  removeScopedProxy(entity: IEntityProxy, scopeId: string): void;
 }
 //#endregion
 //#region src/entities/entity.d.ts
@@ -147,32 +168,24 @@ type EntityTypeUid = string | number;
 type EntityUid = string | number;
 /**
  * Represents the core identification and initialization data for an entity.
- * Every entity must have a model containing the minimal information needed for instantiation.
- * Models are immutable and define the entity's initial structure.
+ * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies when creating an entity.
  */
-interface IEntityModel {
+interface IEntityModel<TProxyTypes extends readonly EntityTypeUid[] = undefined> {
   /**
    * The unique identifier for this entity instance.
    */
   readonly uid: EntityUid;
   /**
-   * Optional array of proxies (references) to other entities.
-   * Used to establish relationships at entity creation time.
+   * The scope this entity belongs to.
+   * Automatically set by the framework — scopeRoot entities generate a UUID,
+   * child entities inherit from their parent via addEntity().
    */
-  readonly proxies?: readonly IEntityProxy[];
-}
-/**
- * Entity model with enforced required proxy relationships.
- * Used when an entity requires specific relationships to be present from creation.
- *
- * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies.
- */
-interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends IEntityModel {
+  readonly scopeId?: string;
   /**
-   * Required proxies for this entity.
-   * The array structure matches the TProxyTypes template to ensure type-safe proxy definitions.
+   * Optional array of proxies (references) to other entities.
+   * Used to establish relationships at entity creation time.
    */
-  readonly proxies: RequiredProxies<TProxyTypes>;
+  readonly proxies?: RequiredProxies<TProxyTypes>;
 }
 /**
  * The core entity interface representing a composition of components and relationships.
@@ -237,5 +250,5 @@ interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
   readonly lastUpdated?: Date;
 }
 //#endregion
-export { IEntity as a, EntityProxy as c, RequiredProxies as d, TypedEntityProxy as f, EntityUid as i, IEntityProxy as l, IComponent as m, IdentityComponent as n, IEntityModel as o, ComponentTypeUid as p, EntityTypeUid as r, IEntityModelWithRequiredProxies as s, BasicComponentType as t, IEntityProxyRepository as u };
-//# sourceMappingURL=identity-component-5neFUd2Q.d.cts.map
+export { IEntity as a, IEntityProxy as c, TypedEntityProxy as d, ComponentTypeUid as f, EntityUid as i, IEntityProxyRepository as l, IdentityComponent as n, IEntityModel as o, IComponent as p, EntityTypeUid as r, EntityProxy as s, BasicComponentType as t, RequiredProxies as u };
+//# sourceMappingURL=identity-component-uU0yDR-y.d.cts.map

package/dist/{index-BtPTY71-.d.cts → index-CR3yK5HE.d.cts}

@@ -1,8 +1,8 @@
-import { a as IEntity, c as EntityProxy, l as IEntityProxy, o as IEntityModel, r as EntityTypeUid } from "./identity-component-5neFUd2Q.cjs";
+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 { i as IEntityUpdate, l as EntityEventUid, o as IEntitySnapshot, p as IEventData, u as IEntityEvent } from "./index-6OSsa_UD.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-BUadwkVZ.cjs";
+import { a as IEntityUpdate, d as EntityEventUid, f as IEntityEvent, h as IEventData, s as IEntitySnapshot, u as EntityEventSubscriptionOptions } from "./index-CY3I0Xdn.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
 /**
@@ -50,9 +50,9 @@ interface ISystemContextEvents {
    * 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 filter - Optional predicate to further filter which events are processed.
+   * @param options - Optional subscription options (filter, scopeId).
    */
-  subscribeTo<TEventData extends IEventData>(uid: EntityEventUid, filter?: (event: IEntityEvent<TEventData>) => boolean): void;
+  subscribeTo(uid: EntityEventUid, options?: EntityEventSubscriptionOptions): void;
   /**
    * Stops listening for events of a specific type.
    * @param uid - The event type to stop listening for.
@@ -152,7 +152,7 @@ interface ISystemContextRepository {
    * @param proxy - Reference to the entity.
    * @returns The immutable entity instance.
    */
-  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity>): Immutable<TEntity>;
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityTypeUid): Immutable<TEntity>;
   /**
    * Queues an entity for update.
    * Triggers the update pipeline for the entity.
@@ -322,6 +322,19 @@ interface ISystemsModule<TEntity extends IEntity> {
    * @returns The initialized entity.
    */
   readonly initEntity?: (model: IEntityModel) => TEntity;
+  /**
+   * If true, this entity type creates a new scope boundary when initialized.
+   * A new scope ID is auto-generated. All child entities inherit this scope.
+   * Typically used for root entities like Engine.
+   */
+  readonly scopeRoot?: boolean;
+  /**
+   * If true, this entity type registers itself as a scoped proxy when initialized.
+   * It joins the inherited scope and becomes resolvable via `context.proxies.get()`
+   * by any entity in the same scope. Throws if no scope exists.
+   * Typically used for scope-wide entities like Scene, Input, AssetsManager.
+   */
+  readonly scopedProxy?: boolean;
 }
 //#endregion
 //#region src/systems/pipeline/system-middleware.d.ts
@@ -343,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.
@@ -365,6 +382,19 @@ interface ISystemsModuleBuilder<TEntity extends IEntity> {
    * @returns This builder for method chaining.
    */
   addModule<TModuleEntity extends TEntity>(module: ISystemsModule<TModuleEntity>, systemType?: SystemType): this;
+  /**
+   * Marks this entity type as a scope root.
+   * When initialized, a new scope is auto-generated and all child entities inherit it.
+   * @returns This builder for method chaining.
+   */
+  setScopeRoot(): this;
+  /**
+   * Marks this entity type as a scoped proxy.
+   * When initialized, the entity registers itself in the inherited scope,
+   * making it resolvable via `context.proxies.get()` by any entity in the same scope.
+   * @returns This builder for method chaining.
+   */
+  setScopedProxy(): this;
 }
 //#endregion
 //#region src/systems/module/systems-module-repository.d.ts
@@ -469,6 +499,10 @@ interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineConte
    * The system context for the current entity execution.
    */
   readonly systemContext: ISystemContext<TEntity>;
+  /**
+   * The proxy repository for managing entity proxy relationships and scopes.
+   */
+  readonly proxyRepository: IEntityProxyRepository;
 }
 //#endregion
 //#region src/systems/runtime/systems-runtime-middleware.d.ts
@@ -482,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-BtPTY71-.d.cts.map
+//# sourceMappingURL=index-CR3yK5HE.d.cts.map

package/dist/{index-CQpE-5sx.d.mts → index-CT8ci9Cn.d.mts}

@@ -1,4 +1,4 @@
-import { a as IEntity, l as IEntityProxy, m as IComponent, n as IdentityComponent, o as IEntityModel, r as EntityTypeUid } from "./identity-component-BCmEilvk.mjs";
+import { a as IEntity, c as IEntityProxy, n as IdentityComponent, o as IEntityModel, p as IComponent, r as EntityTypeUid } from "./identity-component-CgzvgBVh.mjs";
 
 //#region src/entities/entity-events.d.ts
 /**
@@ -39,6 +39,25 @@ interface IEntityEvent<TEventData extends IEventData> {
    * The event payload containing type-specific data.
    */
   data: TEventData;
+  /**
+   * The scope of the dispatching entity.
+   * When set, the event is only delivered to subscribers in the same scope.
+   */
+  scopeId?: string;
+}
+/**
+ * Options for subscribing to an entity event.
+ */
+interface EntityEventSubscriptionOptions {
+  /**
+   * Optional function to determine which specific events are processed.
+   */
+  filter?: EntityEventSubscriptionFilter;
+  /**
+   * The scope of the subscribing entity.
+   * When set, the subscriber only receives events from the same scope.
+   */
+  scopeId?: string;
 }
 /**
  * Manages subscriptions and dispatching for entity events.
@@ -51,9 +70,9 @@ interface IEntityEventsManager {
    * The entity will be notified when events of that type are dispatched.
    * @param uid - The event type to subscribe to.
    * @param entity - The entity registering for this event type.
-   * @param filter - Optional function to determine which specific events are processed.
+   * @param options - Optional subscription options (filter, scopeId).
    */
-  subscribe(uid: EntityEventUid, entity: IEntityProxy, filter?: EntityEventSubscriptionFilter): void;
+  subscribe(uid: EntityEventUid, entity: IEntityProxy, options?: EntityEventSubscriptionOptions): void;
   /**
    * Unsubscribes an entity from a specific event type.
    * The entity will no longer receive notifications for this event type.
@@ -280,11 +299,22 @@ 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;
+};
 /**
  * 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).
  */
 interface IEntityScheduler {
+  /**
+   * Returns all currently scheduled entities with their configuration.
+   */
+  readonly schedules: ReadonlyArray<EntitySchedule>;
   /**
    * Registers an entity for periodic updates.
    * @param entityProxy - The entity to schedule.
@@ -305,5 +335,5 @@ interface IEntityScheduler {
   has(entityProxy: IEntityProxy): boolean;
 }
 //#endregion
-export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEventsDispatcher as d, IEntityEventsManager as f, IEntityUpdate as i, EntityEventUid as l, IEntityRepository as n, IEntitySnapshot as o, IEventData as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, IEntityEvent as u };
-//# sourceMappingURL=index-CQpE-5sx.d.mts.map
+export { IEntityUpdate as a, IEntitySnapshotProvider as c, EntityEventUid as d, IEntityEvent as f, IEventData as h, EntityUpdateType as i, EntityEventSubscriptionFilter as l, IEntityEventsManager as m, IEntityScheduler as n, IEntityUpdateQueue as o, IEntityEventsDispatcher as p, IEntityRepository as r, IEntitySnapshot as s, EntitySchedule as t, EntityEventSubscriptionOptions as u };
+//# sourceMappingURL=index-CT8ci9Cn.d.mts.map

package/dist/{index-6OSsa_UD.d.cts → index-CY3I0Xdn.d.cts}

@@ -1,4 +1,4 @@
-import { a as IEntity, l as IEntityProxy, m as IComponent, n as IdentityComponent, o as IEntityModel, r as EntityTypeUid } from "./identity-component-5neFUd2Q.cjs";
+import { a as IEntity, c as IEntityProxy, n as IdentityComponent, o as IEntityModel, p as IComponent, r as EntityTypeUid } from "./identity-component-uU0yDR-y.cjs";
 
 //#region src/entities/entity-events.d.ts
 /**
@@ -39,6 +39,25 @@ interface IEntityEvent<TEventData extends IEventData> {
    * The event payload containing type-specific data.
    */
   data: TEventData;
+  /**
+   * The scope of the dispatching entity.
+   * When set, the event is only delivered to subscribers in the same scope.
+   */
+  scopeId?: string;
+}
+/**
+ * Options for subscribing to an entity event.
+ */
+interface EntityEventSubscriptionOptions {
+  /**
+   * Optional function to determine which specific events are processed.
+   */
+  filter?: EntityEventSubscriptionFilter;
+  /**
+   * The scope of the subscribing entity.
+   * When set, the subscriber only receives events from the same scope.
+   */
+  scopeId?: string;
 }
 /**
  * Manages subscriptions and dispatching for entity events.
@@ -51,9 +70,9 @@ interface IEntityEventsManager {
    * The entity will be notified when events of that type are dispatched.
    * @param uid - The event type to subscribe to.
    * @param entity - The entity registering for this event type.
-   * @param filter - Optional function to determine which specific events are processed.
+   * @param options - Optional subscription options (filter, scopeId).
    */
-  subscribe(uid: EntityEventUid, entity: IEntityProxy, filter?: EntityEventSubscriptionFilter): void;
+  subscribe(uid: EntityEventUid, entity: IEntityProxy, options?: EntityEventSubscriptionOptions): void;
   /**
    * Unsubscribes an entity from a specific event type.
    * The entity will no longer receive notifications for this event type.
@@ -280,11 +299,22 @@ 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;
+};
 /**
  * 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).
  */
 interface IEntityScheduler {
+  /**
+   * Returns all currently scheduled entities with their configuration.
+   */
+  readonly schedules: ReadonlyArray<EntitySchedule>;
   /**
    * Registers an entity for periodic updates.
    * @param entityProxy - The entity to schedule.
@@ -305,5 +335,5 @@ interface IEntityScheduler {
   has(entityProxy: IEntityProxy): boolean;
 }
 //#endregion
-export { IEntityUpdateQueue as a, EntityEventSubscriptionFilter as c, IEntityEventsDispatcher as d, IEntityEventsManager as f, IEntityUpdate as i, EntityEventUid as l, IEntityRepository as n, IEntitySnapshot as o, IEventData as p, EntityUpdateType as r, IEntitySnapshotProvider as s, IEntityScheduler as t, IEntityEvent as u };
-//# sourceMappingURL=index-6OSsa_UD.d.cts.map
+export { IEntityUpdate as a, IEntitySnapshotProvider as c, EntityEventUid as d, IEntityEvent as f, IEventData as h, EntityUpdateType as i, EntityEventSubscriptionFilter as l, IEntityEventsManager as m, IEntityScheduler as n, IEntityUpdateQueue as o, IEntityEventsDispatcher as p, IEntityRepository as r, IEntitySnapshot as s, EntitySchedule as t, EntityEventSubscriptionOptions as u };
+//# sourceMappingURL=index-CY3I0Xdn.d.cts.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-DcirKLCP.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
 /**
@@ -60,14 +60,14 @@ interface IMiddleware<TContext extends IPipelineContext> {
    * Can read and modify the context to influence downstream middleware and results.
    * @param context The pipeline context containing all relevant state.
    */
-  action(context: TContext): void;
+  action(context: TContext): void | Promise<void>;
   /**
    * Optional cleanup function executed during pipeline teardown.
    * Middlewares execute in reverse registration order during cleanup phase.
    * Used to release resources, clear temporary state, and perform final operations.
    * @param context The pipeline context (may be in modified state from action phases).
    */
-  cleanup?(context: TContext): void;
+  cleanup?(context: TContext): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/middleware-runner.d.ts
@@ -85,14 +85,14 @@ interface IMiddlewareRunner<TContext extends IPipelineContext> {
    * @param context The current pipeline context.
    * @param middleware The middleware whose action should be executed.
    */
-  dispatch(context: TContext, middleware: IMiddleware<TContext>): void;
+  dispatch(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
   /**
    * Decides how to execute a middleware's cleanup.
    * Can add pre/post processing or error handling around cleanup operations.
    * @param context The current pipeline context.
    * @param middleware The middleware whose cleanup should be executed.
    */
-  cleanup(context: TContext, middleware: IMiddleware<TContext>): void;
+  cleanup(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/pipeline.d.ts
@@ -130,7 +130,7 @@ interface IPipeline<TContext extends IPipelineContext> {
    * Execution continues until all middleware complete or a middleware requests early termination.
    * @param context - The context object passed to all middleware.
    */
-  dispatch(context: Partial<TContext>): void;
+  dispatch(context: Partial<TContext>): void | Promise<void>;
   /**
    * Executes the cleanup phase with all registered middleware in reverse order.
    * Allows middleware to perform resource cleanup and final operations.
@@ -138,7 +138,7 @@ interface IPipeline<TContext extends IPipelineContext> {
    *
    * @param context - The context object that will be passed to each middleware function.
    */
-  cleanup(context: Partial<TContext>): void;
+  cleanup(context: Partial<TContext>): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/pipeline-nested.d.ts
@@ -209,7 +209,7 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
    * @param middleware - The ordered middleware array to execute.
    * @param startIndex - Optional starting position in the middleware array (default: 0).
    */
-  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void;
+  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void | Promise<void>;
   /**
    * Executes the cleanup phase of all middleware in reverse order.
    * All middleware cleanup functions are called (if defined), regardless of errors.
@@ -217,8 +217,8 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
    * @param context - The context passed to each middleware cleanup.
    * @param middleware - The ordered middleware array for cleanup (reversed during execution).
    */
-  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void;
+  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void | Promise<void>;
 }
 //#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-DcirKLCP.d.mts.map
+//# sourceMappingURL=index-CyoGuBNw.d.mts.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-BUadwkVZ.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
 /**
@@ -60,14 +60,14 @@ interface IMiddleware<TContext extends IPipelineContext> {
    * Can read and modify the context to influence downstream middleware and results.
    * @param context The pipeline context containing all relevant state.
    */
-  action(context: TContext): void;
+  action(context: TContext): void | Promise<void>;
   /**
    * Optional cleanup function executed during pipeline teardown.
    * Middlewares execute in reverse registration order during cleanup phase.
    * Used to release resources, clear temporary state, and perform final operations.
    * @param context The pipeline context (may be in modified state from action phases).
    */
-  cleanup?(context: TContext): void;
+  cleanup?(context: TContext): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/middleware-runner.d.ts
@@ -85,14 +85,14 @@ interface IMiddlewareRunner<TContext extends IPipelineContext> {
    * @param context The current pipeline context.
    * @param middleware The middleware whose action should be executed.
    */
-  dispatch(context: TContext, middleware: IMiddleware<TContext>): void;
+  dispatch(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
   /**
    * Decides how to execute a middleware's cleanup.
    * Can add pre/post processing or error handling around cleanup operations.
    * @param context The current pipeline context.
    * @param middleware The middleware whose cleanup should be executed.
    */
-  cleanup(context: TContext, middleware: IMiddleware<TContext>): void;
+  cleanup(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/pipeline.d.ts
@@ -130,7 +130,7 @@ interface IPipeline<TContext extends IPipelineContext> {
    * Execution continues until all middleware complete or a middleware requests early termination.
    * @param context - The context object passed to all middleware.
    */
-  dispatch(context: Partial<TContext>): void;
+  dispatch(context: Partial<TContext>): void | Promise<void>;
   /**
    * Executes the cleanup phase with all registered middleware in reverse order.
    * Allows middleware to perform resource cleanup and final operations.
@@ -138,7 +138,7 @@ interface IPipeline<TContext extends IPipelineContext> {
    *
    * @param context - The context object that will be passed to each middleware function.
    */
-  cleanup(context: Partial<TContext>): void;
+  cleanup(context: Partial<TContext>): void | Promise<void>;
 }
 //#endregion
 //#region src/pipelines/pipeline-nested.d.ts
@@ -209,7 +209,7 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
    * @param middleware - The ordered middleware array to execute.
    * @param startIndex - Optional starting position in the middleware array (default: 0).
    */
-  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void;
+  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void | Promise<void>;
   /**
    * Executes the cleanup phase of all middleware in reverse order.
    * All middleware cleanup functions are called (if defined), regardless of errors.
@@ -217,8 +217,8 @@ interface IPipelineRunner<TContext extends IPipelineContext> {
    * @param context - The context passed to each middleware cleanup.
    * @param middleware - The ordered middleware array for cleanup (reversed during execution).
    */
-  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void;
+  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void | Promise<void>;
 }
 //#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-BUadwkVZ.d.cts.map
+//# sourceMappingURL=index-cF9FviwN.d.cts.map

package/dist/{index-CW6-OhB4.d.mts → index-ei6_lV4I.d.mts}

@@ -1,8 +1,8 @@
-import { a as IEntity, c as EntityProxy, l as IEntityProxy, o as IEntityModel, r as EntityTypeUid } from "./identity-component-BCmEilvk.mjs";
+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 { i as IEntityUpdate, l as EntityEventUid, o as IEntitySnapshot, p as IEventData, u as IEntityEvent } from "./index-CQpE-5sx.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-DcirKLCP.mjs";
+import { a as IEntityUpdate, d as EntityEventUid, f as IEntityEvent, h as IEventData, s as IEntitySnapshot, u as EntityEventSubscriptionOptions } from "./index-CT8ci9Cn.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
 /**
@@ -50,9 +50,9 @@ interface ISystemContextEvents {
    * 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 filter - Optional predicate to further filter which events are processed.
+   * @param options - Optional subscription options (filter, scopeId).
    */
-  subscribeTo<TEventData extends IEventData>(uid: EntityEventUid, filter?: (event: IEntityEvent<TEventData>) => boolean): void;
+  subscribeTo(uid: EntityEventUid, options?: EntityEventSubscriptionOptions): void;
   /**
    * Stops listening for events of a specific type.
    * @param uid - The event type to stop listening for.
@@ -152,7 +152,7 @@ interface ISystemContextRepository {
    * @param proxy - Reference to the entity.
    * @returns The immutable entity instance.
    */
-  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity>): Immutable<TEntity>;
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityTypeUid): Immutable<TEntity>;
   /**
    * Queues an entity for update.
    * Triggers the update pipeline for the entity.
@@ -322,6 +322,19 @@ interface ISystemsModule<TEntity extends IEntity> {
    * @returns The initialized entity.
    */
   readonly initEntity?: (model: IEntityModel) => TEntity;
+  /**
+   * If true, this entity type creates a new scope boundary when initialized.
+   * A new scope ID is auto-generated. All child entities inherit this scope.
+   * Typically used for root entities like Engine.
+   */
+  readonly scopeRoot?: boolean;
+  /**
+   * If true, this entity type registers itself as a scoped proxy when initialized.
+   * It joins the inherited scope and becomes resolvable via `context.proxies.get()`
+   * by any entity in the same scope. Throws if no scope exists.
+   * Typically used for scope-wide entities like Scene, Input, AssetsManager.
+   */
+  readonly scopedProxy?: boolean;
 }
 //#endregion
 //#region src/systems/pipeline/system-middleware.d.ts
@@ -343,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.
@@ -365,6 +382,19 @@ interface ISystemsModuleBuilder<TEntity extends IEntity> {
    * @returns This builder for method chaining.
    */
   addModule<TModuleEntity extends TEntity>(module: ISystemsModule<TModuleEntity>, systemType?: SystemType): this;
+  /**
+   * Marks this entity type as a scope root.
+   * When initialized, a new scope is auto-generated and all child entities inherit it.
+   * @returns This builder for method chaining.
+   */
+  setScopeRoot(): this;
+  /**
+   * Marks this entity type as a scoped proxy.
+   * When initialized, the entity registers itself in the inherited scope,
+   * making it resolvable via `context.proxies.get()` by any entity in the same scope.
+   * @returns This builder for method chaining.
+   */
+  setScopedProxy(): this;
 }
 //#endregion
 //#region src/systems/module/systems-module-repository.d.ts
@@ -469,6 +499,10 @@ interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineConte
    * The system context for the current entity execution.
    */
   readonly systemContext: ISystemContext<TEntity>;
+  /**
+   * The proxy repository for managing entity proxy relationships and scopes.
+   */
+  readonly proxyRepository: IEntityProxyRepository;
 }
 //#endregion
 //#region src/systems/runtime/systems-runtime-middleware.d.ts
@@ -482,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-CW6-OhB4.d.mts.map
+//# sourceMappingURL=index-ei6_lV4I.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-BUadwkVZ.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-DcirKLCP.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-BtPTY71-.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-CR3yK5HE.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-CW6-OhB4.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-ei6_lV4I.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.23.0",
+  "version": "0.25.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": "8409c84b5ac82181b01ad384d5732e84f6f5e13a"
+  "gitHead": "07371a6f49d462052187b4e28a178a6970d18aff"
 }