@codehz/ecs 0.9.0 → 0.10.0

package/src/world/world.ts

@@ -1,26 +1,19 @@
-import { Archetype } from "../archetype/archetype";
+import type { Archetype } from "../archetype/archetype";
 import { SparseStoreImpl } from "../archetype/store";
-import { CommandBuffer, type Command } from "../commands/buffer";
-import { ComponentChangeset } from "../commands/changeset";
+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,
-  isEntityRelation,
-  isExclusiveComponent,
   isSparseRelation,
-  isSparseWildcard,
   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";
@@ -34,30 +27,25 @@ import type {
   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,
-  debugHookExecutionCounter,
   triggerLifecycleHooks,
   triggerRemoveHooksForEntityDeletion,
   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
@@ -66,52 +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>>();
   /** 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();
 
-  // Debug observability collectors (armed only when non-empty)
-  private readonly _debugCollectors = new Set<(stats: SyncDebugStats) => void>();
-
-  // Transient counters for the current armed sync (reset each time)
-  private _debugMigrations = 0;
-  private _debugArchetypesCreated = 0;
-  private _debugArchetypesRemoved = 0;
-
-  // 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 = {
-    sparseStore: this.sparseStore,
-    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(
         {
@@ -119,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),
+    );
   }
 
   /**
@@ -255,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()`.
@@ -331,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);
   }
 
@@ -381,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);
   }
@@ -403,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.
    *
@@ -612,7 +584,7 @@ export class World {
     entityId: EntityId,
     relationComp: ComponentId<T>,
   ): [target: EntityId<unknown>, data: T | undefined][] {
-    this.assertEntityExists(entityId, "Entity");
+    assertEntityExists(entityId, "Entity", (id) => this.exists(id));
 
     const wildcard = relation(relationComp, "*") as WildcardRelationId<T>;
 
@@ -659,7 +631,7 @@ export class World {
    * given base component.
    */
   hasRelation(entityId: EntityId, relationComp: ComponentId<any>, targetId?: EntityId): boolean {
-    this.assertEntityExists(entityId, "Entity");
+    assertEntityExists(entityId, "Entity", (id) => this.exists(id));
 
     if (targetId !== undefined) {
       const specific = relation(relationComp, targetId);
@@ -675,7 +647,7 @@ export class World {
    * Returns the number of relations of the given base component held by the entity.
    */
   countRelations(entityId: EntityId, relationComp: ComponentId<any>): number {
-    this.assertEntityExists(entityId, "Entity");
+    assertEntityExists(entityId, "Entity", (id) => this.exists(id));
     const targets = this.getRelationTargets(entityId, relationComp);
     return targets.length;
   }
@@ -922,88 +894,7 @@ export class World {
    * This is intended for development/debugging and leak detection.
    */
   createDebugStatsCollector(callback: (stats: SyncDebugStats) => void): DebugStatsCollector {
-    this._debugCollectors.add(callback);
-
-    return {
-      [Symbol.dispose]: () => {
-        this._debugCollectors.delete(callback);
-      },
-    };
-  }
-
-  private _resetDebugActivityCounters(): void {
-    this._debugMigrations = 0;
-    this._debugArchetypesCreated = 0;
-    this._debugArchetypesRemoved = 0;
-    debugHookExecutionCounter.value = 0;
-  }
-
-  private _deliverDebugStats(timings: {
-    syncStart: number;
-    syncEnd: number;
-    commandBufferStart: number;
-    commandBufferEnd: number;
-    commandIterations: number;
-  }): void {
-    // Build structural counts (post-sync)
-    // Note: singletons (component-as-entity) are not included in the main archetype map.
-    // For debug purposes the dominant number is regular entities; we keep it simple here.
-    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;
-    }
-
-    const stats: SyncDebugStats = {
-      timestamps: {
-        syncStart: timings.syncStart,
-        syncEnd: timings.syncEnd,
-        commandBufferStart: timings.commandBufferStart,
-        commandBufferEnd: timings.commandBufferEnd,
-      },
-      commandIterations: timings.commandIterations,
-
-      entities: {
-        total: entityCount,
-        freelistSize: this.entityIdManager.getFreelistSize(),
-        nextId: this.entityIdManager.getNextId(),
-      },
-      archetypes: {
-        total: this.archetypes.length,
-        empty: emptyArchetypes,
-      },
-      queries: {
-        cached: (this.queryRegistry as any).cache?.size ?? 0,
-        registered: (this.queryRegistry as any).queries?.size ?? 0,
-      },
-      hooks: {
-        total: this.hooks.size,
-      },
-      indices: {
-        entityReferences: this.entityReferences.size,
-        entityToReferencingArchetypes: this.entityToReferencingArchetypes.size,
-        archetypesByComponent: archetypesByComponentSize,
-      },
-      activity: {
-        migrations: this._debugMigrations,
-        hooksExecuted: debugHookExecutionCounter.value,
-        archetypesCreated: this._debugArchetypesCreated,
-        archetypesRemoved: this._debugArchetypesRemoved,
-      },
-    };
-
-    for (const cb of this._debugCollectors) {
-      try {
-        cb(stats);
-      } catch {
-        // Intentionally ignore user callback errors
-      }
-    }
+    return this.debugStats.createCollector(callback);
   }
 
   /**
@@ -1017,29 +908,56 @@ export class World {
    * world.sync(); // Apply all buffered changes
    */
   sync(): void {
-    const hasCollectors = this._debugCollectors.size > 0;
-
-    const syncStart = hasCollectors ? performance.now() : 0;
-
-    if (hasCollectors) {
-      this._resetDebugActivityCounters();
+    if (!this.debugStats.hasActiveCollectors()) {
+      // Fast path: no debug collectors, skip all timing and stats work
+      this.commandBuffer.execute();
+      return;
     }
 
-    const commandBufferStart = hasCollectors ? performance.now() : 0;
+    // 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 = hasCollectors ? performance.now() : 0;
+    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++;
+    }
 
-    const syncEnd = hasCollectors ? performance.now() : 0;
+    let archetypesByComponentSize = 0;
+    for (const set of this.archetypesByComponent.values()) {
+      archetypesByComponentSize += set.size;
+    }
 
-    if (hasCollectors) {
-      this._deliverDebugStats({
+    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,
+      },
+    );
   }
 
   /**
@@ -1076,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);
   }
 
@@ -1146,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);
   }
 
   /**
@@ -1268,287 +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
-      const newArchetype = applyChangeset(
-        this._commandCtx,
-        entityId,
-        currentArchetype,
-        changeset,
-        this.entityToArchetype,
-        null,
-      );
-      if (hasStructuralChange) {
-        this.updateEntityReferences(entityId, changeset);
-      }
-      if (this._debugCollectors.size > 0 && newArchetype !== currentArchetype) {
-        this._debugMigrations++;
-      }
-      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);
-    }
-
-    if (this._debugCollectors.size > 0 && newArchetype !== currentArchetype) {
-      this._debugMigrations++;
-    }
-
-    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.sparseStore);
-    this.archetypes.push(newArchetype);
-
-    if (this._debugCollectors.size > 0) {
-      this._debugArchetypesCreated++;
-    }
-
-    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 (isSparseWildcard(c)) return true;
-          const componentId = getComponentIdFromRelationId(c);
-          return componentId !== undefined && archetype.hasRelationWithComponentId(componentId);
-        }
-        return archetype.componentTypeSet.has(c) || isSparseRelation(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();
-    }
-
-    if (this._debugCollectors.size > 0) {
-      this._debugArchetypesRemoved++;
-    }
-
-    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);
   }
 
   /**
@@ -1572,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,
+    );
   }
 }