@codehz/ecs 0.8.2 → 0.10.0

package/src/world/world.ts

@@ -1,40 +1,36 @@
-import { Archetype } from "../archetype/archetype";
-import { DontFragmentStoreImpl } from "../archetype/store";
-import { CommandBuffer, type Command } from "../commands/buffer";
-import { ComponentChangeset } from "../commands/changeset";
+import type { Archetype } from "../archetype/archetype";
+import { SparseStoreImpl } from "../archetype/store";
+import { CommandBuffer } from "../commands/buffer";
 import { ComponentEntityStore } from "../component/entity-store";
 import { normalizeComponentTypes } from "../component/type-utils";
 import type { ComponentId, EntityId, WildcardRelationId } from "../entity";
 import {
-  ENTITY_ID_START,
   EntityIdManager,
   RELATION_SHIFT,
   getComponentIdFromRelationId,
-  getDetailedIdType,
-  getTargetIdFromRelationId,
   isCascadeDeleteRelation,
-  isDontFragmentRelation,
-  isDontFragmentWildcard,
-  isEntityRelation,
-  isExclusiveComponent,
+  isSparseRelation,
   isWildcardRelationId,
+  relation,
 } from "../entity";
-import { matchesFilter, serializeQueryFilter, type QueryFilter } from "../query/filter";
+import { serializeQueryFilter, type QueryFilter } from "../query/filter";
 import type { Query } from "../query/query";
 import { QueryRegistry } from "../query/registry";
 import type { SerializedWorld } from "../storage/serialization";
-import type { ComponentTuple, ComponentType, LifecycleCallback, LifecycleHook, LifecycleHookEntry } from "../types";
+import type {
+  ComponentTuple,
+  ComponentType,
+  DebugStatsCollector,
+  LifecycleCallback,
+  LifecycleHook,
+  LifecycleHookEntry,
+  SyncDebugStats,
+} from "../types";
 import { isOptionalEntityId } from "../types";
-import { getOrCompute } from "../utils/utils";
+import { ArchetypeManager } from "./archetype-manager";
 import { EntityBuilder } from "./builder";
-import {
-  applyChangeset,
-  filterRegularComponentTypes,
-  maybeRemoveWildcardMarker,
-  processCommands,
-  removeMatchingRelations,
-  type CommandProcessorContext,
-} from "./commands";
+import { CommandExecutor, type CommandExecutorContext } from "./command-executor";
+import { DebugStatsManager } from "./debug-stats";
 import {
   collectMultiHookComponents,
   triggerLifecycleHooks,
@@ -42,12 +38,14 @@ import {
   type HooksContext,
 } from "./hooks";
 import {
-  getEntityReferences,
-  trackEntityReference,
-  untrackEntityReference,
-  type EntityReferencesMap,
-} from "./references";
+  assertEntityExists,
+  assertSetComponentTypeValid,
+  resolveRemoveOperation,
+  resolveSetOperation,
+} from "./operations";
+import { getEntityReferences, type EntityReferencesMap } from "./references";
 import { deserializeWorld, serializeWorld } from "./serialization";
+import { SingletonHandle } from "./singleton";
 
 /**
  * World class for ECS architecture
@@ -56,44 +54,59 @@ import { deserializeWorld, serializeWorld } from "./serialization";
 export class World {
   // Core data structures for entity and archetype management
   private entityIdManager = new EntityIdManager();
-  private archetypes: Archetype[] = [];
-  private archetypeBySignature = new Map<string, Archetype>();
-  private entityToArchetype = new Map<EntityId, Archetype>();
-  private archetypesByComponent = new Map<EntityId<any>, Set<Archetype>>();
   private entityReferences: EntityReferencesMap = new Map();
-  /** Reverse index: entity ID → set of archetypes whose componentTypes include that entity ID */
-  private entityToReferencingArchetypes = new Map<EntityId, Set<Archetype>>();
-  /** DontFragment relation storage, shared with all Archetype instances */
-  private readonly dontFragmentStore = new DontFragmentStoreImpl();
+  /** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
+  private readonly sparseStore = new SparseStoreImpl();
   /** Component entity (singleton) storage */
   private readonly componentEntities = new ComponentEntityStore();
 
+  // Archetype storage, indexes, creation/removal, and referencing are now encapsulated
+  // in ArchetypeManager (extracted to reduce World line count and improve cohesion).
+  private archetypeManager!: ArchetypeManager;
+
+  // Temporary forwarding accessors so the rest of World (and its internal collaborators)
+  // can continue using the familiar names with almost zero call-site changes.
+  // These can be removed in a follow-up cleanup pass if desired.
+  private get archetypes() {
+    return this.archetypeManager.archetypes;
+  }
+  private get entityToArchetype() {
+    return this.archetypeManager.entityToArchetype;
+  }
+  private get archetypesByComponent() {
+    return this.archetypeManager.archetypesByComponent;
+  }
+  private get entityToReferencingArchetypes() {
+    return this.archetypeManager.entityToReferencingArchetypes;
+  }
+
   // Query registry – manages caching, ref counts, and archetype notifications
   private readonly queryRegistry = new QueryRegistry();
 
   // Lifecycle hooks (declared before cached contexts that reference them)
   private hooks: Set<LifecycleHookEntry> = new Set();
 
-  // Command execution
-  private commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
-
-  // Reusable instances to reduce per-frame allocations
-  private readonly _changeset = new ComponentChangeset();
-  private readonly _removeChangeset = new ComponentChangeset();
-  /** Cached command processor context to avoid per-entity object allocation */
-  private readonly _commandCtx: CommandProcessorContext = {
-    dontFragmentStore: this.dontFragmentStore,
-    ensureArchetype: (ct) => this.ensureArchetype(ct),
-  };
-  /** Cached hooks context to avoid per-entity object allocation */
-  private readonly _hooksCtx: HooksContext = {
-    multiHooks: this.hooks,
-    has: (eid, ct) => this.has(eid, ct),
-    get: (eid, ct) => this.get(eid, ct),
-    getOptional: (eid, ct) => this.getOptional(eid, ct),
-  };
+  // Debug observability (extracted to DebugStatsManager to reduce World line count)
+  private readonly debugStats = new DebugStatsManager();
+
+  // Command execution (orchestration extracted to CommandExecutor)
+  private commandBuffer!: CommandBuffer;
+  private commandExecutor!: CommandExecutor;
 
   constructor(snapshot?: SerializedWorld) {
+    // Must create the manager before any code that may invoke ensureArchetype
+    // (including the snapshot deserialization path below, and the closures
+    // captured in the field-initialized _commandCtx).
+    this.archetypeManager = new ArchetypeManager(
+      {
+        queryRegistry: this.queryRegistry,
+        hooks: this.hooks,
+        recordArchetypeCreated: () => this.debugStats.recordArchetypeCreated(),
+        recordArchetypeRemoved: () => this.debugStats.recordArchetypeRemoved(),
+      },
+      this.sparseStore,
+    );
+
     if (snapshot && typeof snapshot === "object") {
       deserializeWorld(
         {
@@ -101,15 +114,34 @@ export class World {
           componentEntities: this.componentEntities,
           entityReferences: this.entityReferences,
           ensureArchetype: (ct) => this.ensureArchetype(ct),
-          setEntityToArchetype: (eid, arch) => this.entityToArchetype.set(eid, arch),
+          setEntityToArchetype: (eid, arch) => this.archetypeManager.entityToArchetype.set(eid, arch),
         },
         snapshot,
       );
     }
-  }
 
-  private createArchetypeSignature(componentTypes: EntityId<any>[]): string {
-    return componentTypes.join(",");
+    // CommandExecutor must be created after archetypeManager (and debugStats) because its context
+    // closes over several pieces and the destroy fast path.
+    const execCtx: CommandExecutorContext = {
+      componentEntities: this.componentEntities,
+      entityReferences: this.entityReferences,
+      hooks: this.hooks,
+      entityToArchetype: this.entityToArchetype,
+      ensureArchetype: (ct) => this.ensureArchetype(ct),
+      sparseStore: this.sparseStore,
+      has: (eid, ct) => this.has(eid, ct),
+      get: (eid, ct) => this.get(eid, ct),
+      getOptional: (eid, ct) => this.getOptional(eid, ct),
+      destroyEntityImmediate: (eid) => this.destroyEntityImmediate(eid),
+      incrementMigrations: () => this.debugStats.incrementMigrations(),
+      triggerLifecycleHooks,
+      triggerRemoveHooksForEntityDeletion,
+    };
+    this.commandExecutor = new CommandExecutor(execCtx);
+
+    this.commandBuffer = new CommandBuffer((entityId, commands) =>
+      this.commandExecutor.executeEntityCommands(entityId, commands),
+    );
   }
 
   /**
@@ -198,7 +230,7 @@ export class World {
         }
       }
 
-      // Remove entity from archetype - this also cleans up dontFragment relations
+      // Remove entity from archetype - this also cleans up sparse relations
       // and returns all removed component data
       this.entityReferences.delete(cur);
       const removedComponents = archetype.removeEntity(cur)!;
@@ -237,71 +269,6 @@ export class World {
     return this.entityToArchetype.has(entityId);
   }
 
-  private assertEntityExists(entityId: EntityId, label: "Entity" | "Component entity"): void {
-    if (!this.exists(entityId)) {
-      throw new Error(`${label} ${entityId} does not exist`);
-    }
-  }
-
-  private assertComponentTypeValid(componentType: EntityId): void {
-    const detailedType = getDetailedIdType(componentType);
-    if (detailedType.type === "invalid") {
-      throw new Error(`Invalid component type: ${componentType}`);
-    }
-  }
-
-  private assertSetComponentTypeValid(componentType: EntityId): void {
-    const detailedType = getDetailedIdType(componentType);
-    if (detailedType.type === "invalid") {
-      throw new Error(`Invalid component type: ${componentType}`);
-    }
-    if (detailedType.type === "wildcard-relation") {
-      throw new Error(`Cannot directly add wildcard relation components: ${componentType}`);
-    }
-  }
-
-  private resolveSetOperation(
-    entityId: EntityId | ComponentId,
-    componentTypeOrComponent?: EntityId | any,
-    maybeComponent?: any,
-  ): { entityId: EntityId; componentType: EntityId; component: any } {
-    // Handle singleton component overload: set(componentId, data)
-    if (maybeComponent === undefined && componentTypeOrComponent !== undefined) {
-      const detailedType = getDetailedIdType(entityId);
-      if (detailedType.type === "component" || detailedType.type === "component-relation") {
-        const componentId = entityId as ComponentId;
-        this.assertEntityExists(componentId, "Component entity");
-        this.assertSetComponentTypeValid(componentId);
-        return { entityId: componentId, componentType: componentId, component: componentTypeOrComponent };
-      }
-    }
-
-    const targetEntityId = entityId as EntityId;
-    const componentType = componentTypeOrComponent as EntityId;
-    this.assertEntityExists(targetEntityId, "Entity");
-    this.assertSetComponentTypeValid(componentType);
-
-    return { entityId: targetEntityId, componentType, component: maybeComponent };
-  }
-
-  private resolveRemoveOperation<T>(
-    entityId: EntityId | ComponentId,
-    componentType?: EntityId<T>,
-  ): { entityId: EntityId; componentType: EntityId } {
-    // Handle singleton component overload: remove(componentId)
-    if (componentType === undefined) {
-      const componentId = entityId as ComponentId<T>;
-      this.assertEntityExists(componentId, "Component entity");
-      return { entityId: componentId, componentType: componentId };
-    }
-
-    const targetEntityId = entityId as EntityId;
-    this.assertEntityExists(targetEntityId, "Entity");
-    this.assertComponentTypeValid(componentType);
-
-    return { entityId: targetEntityId, componentType };
-  }
-
   /**
    * Adds or updates a component on an entity (or marks void component as present).
    * The change is buffered and takes effect after calling `world.sync()`.
@@ -313,27 +280,23 @@ export class World {
    * @overload set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void
    * Adds or updates a component with data on the entity
    *
-   * @overload set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void
-   * Adds or updates a singleton component (shorthand for set(componentId, componentId, component))
-   *
    * @throws {Error} If the entity does not exist
    * @throws {Error} If the component type is invalid or is a wildcard relation
    *
    * @example
    * world.set(entity, Position, { x: 10, y: 20 });
    * world.set(entity, Marker); // void component
-   * world.set(GlobalConfig, { debug: true }); // singleton component
+   * world.singleton(GlobalConfig).set({ debug: true }); // singleton component
    * world.sync(); // Apply changes
    */
   set(entityId: EntityId, componentType: EntityId<void>): void;
   set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
-  set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void;
   set(entityId: EntityId | ComponentId, componentTypeOrComponent?: EntityId | any, maybeComponent?: any): void {
     const {
       entityId: targetEntityId,
       componentType,
       component,
-    } = this.resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent);
+    } = resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, (id) => this.exists(id));
     this.commandBuffer.set(targetEntityId, componentType, component);
   }
 
@@ -363,9 +326,10 @@ export class World {
   remove<T>(componentId: ComponentId<T>): void;
   remove<T>(entityId: EntityId, componentType: EntityId<T>): void;
   remove<T>(entityId: EntityId | ComponentId, componentType?: EntityId<T>): void {
-    const { entityId: targetEntityId, componentType: targetComponentType } = this.resolveRemoveOperation(
+    const { entityId: targetEntityId, componentType: targetComponentType } = resolveRemoveOperation(
       entityId,
       componentType,
+      (id) => this.exists(id),
     );
     this.commandBuffer.remove(targetEntityId, targetComponentType);
   }
@@ -385,6 +349,32 @@ export class World {
     this.commandBuffer.delete(entityId);
   }
 
+  /**
+   * Returns an explicit handle for a singleton component (component-as-entity).
+   *
+   * This is the preferred API for singleton components.
+   *
+   * @example
+   * const config = world.singleton(GlobalConfig);
+   * config.set({ debug: true });
+   * world.sync();
+   * console.log(config.get());
+   */
+  singleton<T>(componentId: ComponentId<T>): SingletonHandle<T> {
+    assertEntityExists(componentId, "Component entity", (id) => this.exists(id));
+    assertSetComponentTypeValid(componentId);
+
+    return new SingletonHandle(componentId, {
+      has: () => this.componentEntities.hasSingleton(componentId),
+      get: () => this.get(componentId),
+      getOptional: () => this.getOptional(componentId),
+      remove: () => this.commandBuffer.remove(componentId, componentId),
+      set: (value) => {
+        this.commandBuffer.set(componentId, componentId as EntityId<any>, value as any);
+      },
+    });
+  }
+
   /**
    * Checks if a specific **component** is present on an entity.
    *
@@ -443,11 +433,11 @@ export class World {
 
     if (archetype.componentTypeSet.has(componentType)) return true;
 
-    if (isDontFragmentRelation(componentType)) {
+    if (isSparseRelation(componentType)) {
       // Use getValue; presence check via getAllForEntity only if value can legitimately be undefined
-      const val = this.dontFragmentStore.getValue(entityId, componentType);
+      const val = this.sparseStore.getValue(entityId, componentType);
       if (val !== undefined) return true;
-      return this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType);
+      return this.sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType);
     }
 
     return false;
@@ -495,12 +485,12 @@ export class World {
 
     if (componentType >= 0 || componentType % RELATION_SHIFT !== 0) {
       const inArchetype = archetype.componentTypeSet.has(componentType);
-      const hasDontFragment = isDontFragmentRelation(componentType);
+      const hasSparse = isSparseRelation(componentType);
       const hasComponent =
         inArchetype ||
-        (hasDontFragment &&
-          (this.dontFragmentStore.getValue(entityId, componentType) !== undefined ||
-            this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType)));
+        (hasSparse &&
+          (this.sparseStore.getValue(entityId, componentType) !== undefined ||
+            this.sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)));
 
       if (!hasComponent) {
         throw new Error(
@@ -571,6 +561,213 @@ export class World {
     return archetype.getOptional(entityId, componentType);
   }
 
+  // ==========================================================================
+  // Relation & Hierarchy Companion Tools (public API)
+  // ==========================================================================
+
+  /**
+   * Retrieves all targets (and their associated data) for relations of a given
+   * base component on an entity.
+   *
+   * This is the ergonomic replacement for the common pattern:
+   *   world.get(entity, relation(Comp, "*"))
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const children = world.getRelationTargets(parent, ChildOf); // usually []
+   * const items = world.getRelationTargets(player, InInventory);
+   *
+   * // For common hierarchy use cases, prefer the higher-level helpers:
+   * // world.getChildren(parent, ChildOf), world.getParent(child, ChildOf)
+   */
+  getRelationTargets<T = void>(
+    entityId: EntityId,
+    relationComp: ComponentId<T>,
+  ): [target: EntityId<unknown>, data: T | undefined][] {
+    assertEntityExists(entityId, "Entity", (id) => this.exists(id));
+
+    const wildcard = relation(relationComp, "*") as WildcardRelationId<T>;
+
+    // For component entities (singletons) the path is different; they rarely host relations
+    if (this.componentEntities.exists(entityId)) {
+      return this.componentEntities.getWildcard(entityId, wildcard);
+    }
+
+    // Regular entity path — archetype.get for wildcard always materializes the array
+    // (even if empty for a sparse relation that only has the marker)
+    const data = this.get(entityId, wildcard);
+    return data as [EntityId<unknown>, T | undefined][];
+  }
+
+  /**
+   * Returns every entity that currently holds a relation of the given base
+   * component pointing at `targetId`.
+   *
+   * This is the efficient **reverse** lookup. For common hierarchy cases,
+   * prefer the higher-level `world.getChildren(parent, ChildOf)` instead.
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const directChildren = world.getRelationSources(ship, ChildOf);
+   */
+  getRelationSources(targetId: EntityId, relationComp: ComponentId<any>): EntityId[] {
+    const refs = getEntityReferences(this.entityReferences, targetId);
+    const result: EntityId[] = [];
+
+    for (const [source, relType] of refs) {
+      // Only consider still-living sources
+      if (!this.entityToArchetype.has(source) && !this.componentEntities.exists(source)) continue;
+
+      const decodedComp = getComponentIdFromRelationId(relType);
+      if (decodedComp === relationComp) {
+        result.push(source);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Returns true if the entity has any (or a specific-target) relation of the
+   * given base component.
+   */
+  hasRelation(entityId: EntityId, relationComp: ComponentId<any>, targetId?: EntityId): boolean {
+    assertEntityExists(entityId, "Entity", (id) => this.exists(id));
+
+    if (targetId !== undefined) {
+      const specific = relation(relationComp, targetId);
+      return this.has(entityId, specific);
+    }
+
+    // Any target of this relation kind?
+    const targets = this.getRelationTargets(entityId, relationComp);
+    return targets.length > 0;
+  }
+
+  /**
+   * Returns the number of relations of the given base component held by the entity.
+   */
+  countRelations(entityId: EntityId, relationComp: ComponentId<any>): number {
+    assertEntityExists(entityId, "Entity", (id) => this.exists(id));
+    const targets = this.getRelationTargets(entityId, relationComp);
+    return targets.length;
+  }
+
+  /**
+   * For an *exclusive* relation (e.g. ChildOf, Owner), returns the single
+   * target entity (or undefined if none).
+   *
+   * When the component was declared `exclusive: true`, this is the preferred
+   * accessor (clearer intent than array destructuring).
+   */
+  getSingleRelationTarget<T = void>(entityId: EntityId, relationComp: ComponentId<T>): EntityId | undefined {
+    const targets = this.getRelationTargets(entityId, relationComp);
+    return targets.length > 0 ? (targets[0]![0] as EntityId) : undefined;
+  }
+
+  // --------------------------------------------------------------------------
+  // High-level hierarchy helpers (convenience methods on World)
+  // --------------------------------------------------------------------------
+
+  /**
+   * Returns the direct children of `parent` for the given relationship component
+   * (typically a `ChildOf` or similar exclusive `sparse` relation).
+   *
+   * This is the recommended high-level API for hierarchy traversal.
+   * It uses the internal reverse reference index for efficiency.
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const kids = world.getChildren(ship, ChildOf);
+   */
+  getChildren(parent: EntityId, childOf: ComponentId<any>): EntityId[] {
+    return this.getRelationSources(parent, childOf);
+  }
+
+  /**
+   * Returns the parent of `child` for the given relationship component
+   * (typically an exclusive `ChildOf` relation).
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const parent = world.getParent(turret, ChildOf);
+   */
+  getParent(child: EntityId, childOf: ComponentId<any>): EntityId | undefined {
+    return this.getSingleRelationTarget(child, childOf);
+  }
+
+  /**
+   * Returns the ancestor chain from the immediate parent up to (but not
+   * including) the root for the given relationship component.
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const ancestors = world.getAncestors(muzzle, ChildOf); // [turret, ship]
+   */
+  getAncestors(entity: EntityId, childOf: ComponentId<any>): EntityId[] {
+    const ancestors: EntityId[] = [];
+    let cur = this.getParent(entity, childOf);
+    while (cur !== undefined) {
+      ancestors.push(cur);
+      cur = this.getParent(cur, childOf);
+    }
+    return ancestors;
+  }
+
+  /**
+   * Iteratively traverses all descendants of `root` in DFS pre-order.
+   * This is a generator and is safe for very deep hierarchies.
+   *
+   * @example
+   * for (const { entity, depth, parent } of world.iterateDescendants(root, ChildOf)) {
+   *   console.log(depth, entity);
+   * }
+   */
+  *iterateDescendants(
+    root: EntityId,
+    childOf: ComponentId<any>,
+    opts: { includeSelf?: boolean; maxDepth?: number } = {},
+  ): IterableIterator<{ entity: EntityId; depth: number; parent: EntityId | null }> {
+    const { includeSelf = false, maxDepth } = opts;
+    const stack: Array<{ entity: EntityId; depth: number; parent: EntityId | null }> = [];
+
+    if (includeSelf) {
+      stack.push({ entity: root, depth: 0, parent: null });
+    } else {
+      for (const child of this.getChildren(root, childOf)) {
+        stack.push({ entity: child, depth: 1, parent: root });
+      }
+    }
+
+    while (stack.length > 0) {
+      const current = stack.pop()!;
+      if (maxDepth !== undefined && current.depth > maxDepth) continue;
+
+      yield current;
+
+      const kids = this.getChildren(current.entity, childOf);
+      for (let i = kids.length - 1; i >= 0; i--) {
+        const k = kids[i]!;
+        stack.push({ entity: k, depth: current.depth + 1, parent: current.entity });
+      }
+    }
+  }
+
+  /**
+   * Callback-based descendant traversal (hot path friendly).
+   * Return `false` from the visitor to stop early.
+   */
+  traverseDescendants(
+    root: EntityId,
+    childOf: ComponentId<any>,
+    visitor: (entity: EntityId, depth: number, parent: EntityId | null) => void | boolean,
+    opts: { includeSelf?: boolean; maxDepth?: number } = {},
+  ): void {
+    for (const { entity, depth, parent } of this.iterateDescendants(root, childOf, opts)) {
+      const res = visitor(entity, depth, parent);
+      if (res === false) return;
+    }
+  }
+
   /**
    * Registers a lifecycle hook that responds to component changes.
    * The hook callback is invoked when components matching the specified types are added, updated, or removed.
@@ -684,6 +881,22 @@ export class World {
     };
   }
 
+  /**
+   * Creates a debug stats collector that will receive a `SyncDebugStats` payload
+   * after every subsequent `sync()`.
+   *
+   * The returned object is a pure lifecycle handle. It does not store data.
+   * Collection stops when you call `[Symbol.dispose]()` (or use a `using` declaration).
+   *
+   * All active collectors receive the exact same stats object for a given sync.
+   * Exceptions thrown by callbacks are ignored.
+   *
+   * This is intended for development/debugging and leak detection.
+   */
+  createDebugStatsCollector(callback: (stats: SyncDebugStats) => void): DebugStatsCollector {
+    return this.debugStats.createCollector(callback);
+  }
+
   /**
    * Synchronizes all buffered commands (set/remove/delete) to the world.
    * This method must be called after making changes via `set()`, `remove()`, or `delete()` for them to take effect.
@@ -695,7 +908,56 @@ export class World {
    * world.sync(); // Apply all buffered changes
    */
   sync(): void {
-    this.commandBuffer.execute();
+    if (!this.debugStats.hasActiveCollectors()) {
+      // Fast path: no debug collectors, skip all timing and stats work
+      this.commandBuffer.execute();
+      return;
+    }
+
+    // Slow path: full instrumentation for active debug stats collectors
+    const syncStart = performance.now();
+    this.debugStats.resetActivity();
+
+    const commandBufferStart = performance.now();
+    const commandIterations = this.commandBuffer.execute();
+    const commandBufferEnd = performance.now();
+
+    const syncEnd = performance.now();
+
+    // Build the data bag for the extracted manager (keeps it decoupled from internal maps)
+    const entityCount = this.entityToArchetype.size;
+    let emptyArchetypes = 0;
+    for (const arch of this.archetypes) {
+      if (arch.size === 0) emptyArchetypes++;
+    }
+
+    let archetypesByComponentSize = 0;
+    for (const set of this.archetypesByComponent.values()) {
+      archetypesByComponentSize += set.size;
+    }
+
+    this.debugStats.deliver(
+      {
+        syncStart,
+        syncEnd,
+        commandBufferStart,
+        commandBufferEnd,
+        commandIterations,
+      },
+      {
+        entityCount,
+        freelistSize: this.entityIdManager.getFreelistSize(),
+        nextId: this.entityIdManager.getNextId(),
+        archetypeCount: this.archetypes.length,
+        emptyArchetypes,
+        archetypesByComponentSize,
+        cachedQueryCount: (this.queryRegistry as any).cache?.size ?? 0,
+        registeredQueryCount: (this.queryRegistry as any).queries?.size ?? 0,
+        hookCount: this.hooks.size,
+        entityReferencesSize: this.entityReferences.size,
+        entityToReferencingArchetypesSize: this.entityToReferencingArchetypes.size,
+      },
+    );
   }
 
   /**
@@ -732,7 +994,7 @@ export class World {
   createQuery(componentTypes: EntityId<any>[], filter: QueryFilter = {}): Query {
     const sortedTypes = normalizeComponentTypes(componentTypes);
     const filterKey = serializeQueryFilter(filter);
-    const key = `${this.createArchetypeSignature(sortedTypes)}${filterKey ? `|${filterKey}` : ""}`;
+    const key = `${sortedTypes.join(",")}${filterKey ? `|${filterKey}` : ""}`;
     return this.queryRegistry.getOrCreate(this, sortedTypes, key, filter);
   }
 
@@ -802,71 +1064,7 @@ export class World {
    * @internal
    */
   getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[] {
-    if (componentTypes.length === 0) {
-      return [...this.archetypes];
-    }
-
-    const regularComponents: EntityId<any>[] = [];
-    const wildcardRelations: { componentId: ComponentId<any>; relationId: EntityId<any> }[] = [];
-
-    for (const componentType of componentTypes) {
-      if (isWildcardRelationId(componentType)) {
-        const componentId = getComponentIdFromRelationId(componentType);
-        if (componentId !== undefined) {
-          wildcardRelations.push({ componentId, relationId: componentType });
-        }
-      } else {
-        regularComponents.push(componentType);
-      }
-    }
-
-    let matchingArchetypes = this.getArchetypesWithComponents(regularComponents);
-
-    for (const { componentId, relationId } of wildcardRelations) {
-      const markerSet = this.archetypesByComponent.get(relationId);
-      const archetypesWithMarker = markerSet ? Array.from(markerSet) : [];
-      matchingArchetypes =
-        matchingArchetypes.length === 0
-          ? archetypesWithMarker
-          : matchingArchetypes.filter((a) => markerSet?.has(a) || a.hasRelationWithComponentId(componentId));
-    }
-
-    return matchingArchetypes;
-  }
-
-  private getArchetypesWithComponents(componentTypes: EntityId<any>[]): Archetype[] {
-    if (componentTypes.length === 0) return [...this.archetypes];
-    if (componentTypes.length === 1) {
-      const set = this.archetypesByComponent.get(componentTypes[0]!);
-      return set ? Array.from(set) : [];
-    }
-
-    // Sort by Set size, intersect starting from the smallest
-    const sets = componentTypes
-      .map((type) => this.archetypesByComponent.get(type))
-      .filter((s): s is Set<Archetype> => s !== undefined && s.size > 0)
-      .sort((a, b) => a.size - b.size);
-
-    if (sets.length === 0) return [];
-    if (sets.length < componentTypes.length) return []; // One component has no matching archetypes
-
-    const smallest = sets[0]!;
-
-    // 2-component fast path
-    if (sets.length === 2) {
-      const other = sets[1]!;
-      return Array.from(smallest).filter((a) => other.has(a));
-    }
-
-    // Multi-component intersection
-    let result = new Set(smallest);
-    for (let i = 1; i < sets.length; i++) {
-      for (const item of result) {
-        if (!sets[i]!.has(item)) result.delete(item);
-      }
-      if (result.size === 0) return [];
-    }
-    return Array.from(result);
+    return this.archetypeManager.getMatchingArchetypes(componentTypes);
   }
 
   /**
@@ -924,264 +1122,17 @@ export class World {
     }
   }
 
-  private executeEntityCommands(entityId: EntityId, commands: Command[]): void {
-    this._changeset.clear();
-
-    // 1. Route: component entities use flat-map storage
-    if (this.componentEntities.exists(entityId)) {
-      this.componentEntities.executeCommands(entityId, commands);
-      return;
-    }
-
-    // 2. Route: destroy uses fast path
-    if (commands.some((cmd) => cmd.type === "destroy")) {
-      this.destroyEntityImmediate(entityId);
-      return;
-    }
-
-    // 3. Apply structural changes
-    this.applyEntityCommands(entityId, commands);
-  }
-
-  private applyEntityCommands(entityId: EntityId, commands: Command[]): void {
-    const currentArchetype = this.entityToArchetype.get(entityId);
-    if (!currentArchetype) return;
-
-    const changeset = this._changeset;
-    processCommands(entityId, currentArchetype, commands, changeset, (eid, arch, compId) => {
-      if (isExclusiveComponent(compId)) {
-        removeMatchingRelations(eid, arch, compId, changeset);
-      }
-    });
-
-    const hasStructuralChange = changeset.removes.size > 0 || changeset.adds.size > 0;
-
-    if (this.hooks.size === 0) {
-      // Fast path: no hooks, skip removedComponents map allocation and hook triggering
-      applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype, null);
-      if (hasStructuralChange) {
-        this.updateEntityReferences(entityId, changeset);
-      }
-      return;
-    }
-
-    const removedComponents = new Map<EntityId<any>, any>();
-    const newArchetype = applyChangeset(
-      this._commandCtx,
-      entityId,
-      currentArchetype,
-      changeset,
-      this.entityToArchetype,
-      removedComponents,
-    );
-
-    if (hasStructuralChange) {
-      this.updateEntityReferences(entityId, changeset);
-    }
-    triggerLifecycleHooks(
-      this.createHooksContext(),
-      entityId,
-      changeset.adds,
-      removedComponents,
-      currentArchetype,
-      newArchetype,
-    );
-  }
-
-  private createHooksContext(): HooksContext {
-    return this._hooksCtx;
-  }
-
-  private removeComponentImmediate(entityId: EntityId, componentType: EntityId<any>, targetEntityId: EntityId): void {
-    const sourceArchetype = this.entityToArchetype.get(entityId);
-    if (!sourceArchetype) return;
-
-    const changeset = this._removeChangeset;
-    changeset.clear();
-    changeset.delete(componentType);
-    maybeRemoveWildcardMarker(
-      entityId,
-      sourceArchetype,
-      componentType,
-      getComponentIdFromRelationId(componentType),
-      changeset,
-    );
-
-    const removedComponent = sourceArchetype.get(entityId, componentType);
-    const newArchetype = applyChangeset(
-      this._commandCtx,
-      entityId,
-      sourceArchetype,
-      changeset,
-      this.entityToArchetype,
-      null,
-    );
-    untrackEntityReference(this.entityReferences, entityId, componentType, targetEntityId);
-    triggerLifecycleHooks(
-      this.createHooksContext(),
-      entityId,
-      new Map(),
-      new Map([[componentType, removedComponent]]),
-      sourceArchetype,
-      newArchetype,
-    );
-  }
-
-  private updateEntityReferences(entityId: EntityId, changeset: ComponentChangeset): void {
-    for (const componentType of changeset.removes) {
-      if (isEntityRelation(componentType)) {
-        const targetId = getTargetIdFromRelationId(componentType)!;
-        untrackEntityReference(this.entityReferences, entityId, componentType, targetId);
-      } else if (componentType >= ENTITY_ID_START) {
-        untrackEntityReference(this.entityReferences, entityId, componentType, componentType);
-      }
-    }
-
-    for (const [componentType] of changeset.adds) {
-      if (isEntityRelation(componentType)) {
-        const targetId = getTargetIdFromRelationId(componentType)!;
-        trackEntityReference(this.entityReferences, entityId, componentType, targetId);
-      } else if (componentType >= ENTITY_ID_START) {
-        trackEntityReference(this.entityReferences, entityId, componentType, componentType);
-      }
-    }
-  }
-
+  // Delegators to the extracted ArchetypeManager (keeps public + internal call sites unchanged).
   private ensureArchetype(componentTypes: Iterable<EntityId<any>>): Archetype {
-    const regularTypes = filterRegularComponentTypes(componentTypes);
-    const sortedTypes = normalizeComponentTypes(regularTypes);
-    const hashKey = this.createArchetypeSignature(sortedTypes);
-
-    return getOrCompute(this.archetypeBySignature, hashKey, () => this.createNewArchetype(sortedTypes));
-  }
-
-  /** Add componentType to the reverse index if it contains an entity ID */
-  private addToReferencingIndex(componentType: EntityId<any>, archetype: Archetype): void {
-    const detailedType = getDetailedIdType(componentType);
-    let entityId: EntityId | undefined;
-
-    if (detailedType.type === "entity") {
-      entityId = componentType as EntityId;
-    } else if (detailedType.type === "entity-relation") {
-      entityId = detailedType.targetId;
-    }
-
-    if (entityId !== undefined) {
-      let refs = this.entityToReferencingArchetypes.get(entityId);
-      if (!refs) {
-        refs = new Set();
-        this.entityToReferencingArchetypes.set(entityId, refs);
-      }
-      refs.add(archetype);
-    }
-  }
-
-  /** Remove componentType from the reverse index */
-  private removeFromReferencingIndex(componentType: EntityId<any>, archetype: Archetype): void {
-    const detailedType = getDetailedIdType(componentType);
-    let entityId: EntityId | undefined;
-
-    if (detailedType.type === "entity") {
-      entityId = componentType as EntityId;
-    } else if (detailedType.type === "entity-relation") {
-      entityId = detailedType.targetId;
-    }
-
-    if (entityId !== undefined) {
-      const refs = this.entityToReferencingArchetypes.get(entityId);
-      if (refs) {
-        refs.delete(archetype);
-        if (refs.size === 0) {
-          this.entityToReferencingArchetypes.delete(entityId);
-        }
-      }
-    }
-  }
-
-  private createNewArchetype(componentTypes: EntityId<any>[]): Archetype {
-    const newArchetype = new Archetype(componentTypes, this.dontFragmentStore);
-    this.archetypes.push(newArchetype);
-
-    for (const componentType of componentTypes) {
-      let archetypes = this.archetypesByComponent.get(componentType);
-      if (!archetypes) {
-        archetypes = new Set();
-        this.archetypesByComponent.set(componentType, archetypes);
-      }
-      archetypes.add(newArchetype);
-
-      // Update reverse index
-      this.addToReferencingIndex(componentType, newArchetype);
-    }
-
-    this.queryRegistry.onNewArchetype(newArchetype);
-    this.updateArchetypeHookMatches(newArchetype);
-
-    return newArchetype;
-  }
-
-  private updateArchetypeHookMatches(archetype: Archetype): void {
-    for (const entry of this.hooks) {
-      if (this.archetypeMatchesHook(archetype, entry)) {
-        archetype.matchingMultiHooks.add(entry);
-        if (entry.matchedArchetypes) {
-          entry.matchedArchetypes.add(archetype);
-        }
-      }
-    }
-  }
-
-  private archetypeMatchesHook(archetype: Archetype, entry: LifecycleHookEntry): boolean {
-    return (
-      entry.requiredComponents.every((c: EntityId<any>) => {
-        if (isWildcardRelationId(c)) {
-          if (isDontFragmentWildcard(c)) return true;
-          const componentId = getComponentIdFromRelationId(c);
-          return componentId !== undefined && archetype.hasRelationWithComponentId(componentId);
-        }
-        return archetype.componentTypeSet.has(c) || isDontFragmentRelation(c);
-      }) && matchesFilter(archetype, entry.filter)
-    );
+    return this.archetypeManager.ensureArchetype(componentTypes);
   }
 
   private cleanupArchetypesReferencingEntity(entityId: EntityId): void {
-    const refs = this.entityToReferencingArchetypes.get(entityId);
-    if (!refs) return;
-
-    for (const archetype of refs) {
-      if (archetype.getEntities().length === 0) {
-        this.removeArchetype(archetype);
-      }
-    }
-    // removeArchetype already cleans up the reverse index entries
-    this.entityToReferencingArchetypes.delete(entityId);
+    this.archetypeManager.cleanupArchetypesReferencingEntity(entityId);
   }
 
-  private removeArchetype(archetype: Archetype): void {
-    const index = this.archetypes.indexOf(archetype);
-    if (index !== -1) {
-      // swap-and-pop: O(1) removal
-      const last = this.archetypes[this.archetypes.length - 1]!;
-      this.archetypes[index] = last;
-      this.archetypes.pop();
-    }
-
-    this.archetypeBySignature.delete(this.createArchetypeSignature(archetype.componentTypes));
-
-    for (const componentType of archetype.componentTypes) {
-      const archetypes = this.archetypesByComponent.get(componentType);
-      if (archetypes) {
-        archetypes.delete(archetype);
-        if (archetypes.size === 0) {
-          this.archetypesByComponent.delete(componentType);
-        }
-      }
-
-      // Clean up reverse index
-      this.removeFromReferencingIndex(componentType, archetype);
-    }
-
-    this.queryRegistry.onArchetypeRemoved(archetype);
+  private archetypeMatchesHook(archetype: Archetype, entry: LifecycleHookEntry): boolean {
+    return this.archetypeManager.archetypeMatchesHook(archetype, entry);
   }
 
   /**
@@ -1205,7 +1156,28 @@ export class World {
    * const savedData = JSON.parse(localStorage.getItem('save'));
    * const newWorld = new World(savedData);
    */
+  // Thin delegator to the extracted CommandExecutor for cascade paths (destroy* methods).
+  private removeComponentImmediate(entityId: EntityId, componentType: EntityId<any>, targetEntityId: EntityId): void {
+    this.commandExecutor.removeComponentImmediate(entityId, componentType, targetEntityId);
+  }
+
+  private createHooksContext(): HooksContext {
+    // The executor owns the current HooksContext; expose for any remaining internal use.
+    return (
+      (this.commandExecutor as any).getHooksContext?.() ?? {
+        multiHooks: this.hooks,
+        has: (eid, ct) => this.has(eid, ct),
+        get: (eid, ct) => this.get(eid, ct),
+        getOptional: (eid, ct) => this.getOptional(eid, ct),
+      }
+    );
+  }
+
   serialize(): SerializedWorld {
-    return serializeWorld(this.archetypes, this.componentEntities, this.entityIdManager);
+    return serializeWorld(
+      this.archetypeManager.archetypes as Archetype[],
+      this.componentEntities,
+      this.entityIdManager,
+    );
   }
 }