@codehz/ecs 0.9.0 → 0.10.1

package/dist/world.mjs

@@ -622,124 +622,327 @@ var EntityBuilder = class {
 	}
 };
 //#endregion
-//#region src/component/type-utils.ts
-/**
-* Normalize component type collections into a stable ascending order.
-* This keeps cache keys and archetype signatures deterministic.
-*/
-function normalizeComponentTypes(componentTypes) {
-	return [...componentTypes].sort((a, b) => a - b);
-}
-//#endregion
-//#region src/types/index.ts
-function isOptionalEntityId(type) {
-	return typeof type === "object" && type !== null && "optional" in type;
-}
-//#endregion
-//#region src/utils/utils.ts
+//#region src/world/singleton.ts
 /**
-* Utility functions for ECS library
-*/
-/**
-* Get a value from cache or compute and cache it if not present
-* @param cache The cache map
-* @param key The cache key
-* @param compute Function to compute the value if not cached (may have side effects)
-* @returns The cached or computed value
+* Explicit handle for a singleton component (component-as-entity).
+*
+* This is the preferred API for singleton components.
+* `world.set(componentId, value)` remains available only as a deprecated
+* compatibility shorthand.
+*
+* @example
+* const config = world.singleton(Config);
+* config.set({ debug: true });
+* world.sync();
+* console.log(config.get());
 */
-function getOrCompute(cache, key, compute) {
-	let value = cache.get(key);
-	if (value === void 0) {
-		value = compute();
-		cache.set(key, value);
+var SingletonHandle = class {
+	componentId;
+	ops;
+	constructor(componentId, ops) {
+		this.componentId = componentId;
+		this.ops = ops;
 	}
-	return value;
-}
+	has() {
+		return this.ops.has();
+	}
+	get() {
+		return this.ops.get();
+	}
+	getOptional() {
+		return this.ops.getOptional();
+	}
+	remove() {
+		this.ops.remove();
+	}
+	set(...args) {
+		this.ops.set(args[0]);
+	}
+};
 //#endregion
-//#region src/archetype/helpers.ts
+//#region src/archetype/store.ts
 /**
-* Check if a components map has any wildcard relations matching a component ID
-* @param components - Component entity's components map
-* @param wildcardComponentId - The component ID to match
-* @returns True if at least one matching relation exists
+* Production implementation of SparseStore.
+*
+* Internal layout (optimized):
+* - byComponent: baseComponentId → (entityId → RelationEntry)
+*   RelationEntry uses a single-value form for the common exclusive case (1 target),
+*   avoiding Map allocation for the vast majority of usage.
+* - entityIndex: entityId → Set<baseComponentId>
+*   Lightweight reverse index.
 */
-function hasWildcardRelation(components, wildcardComponentId) {
-	for (const relId of components.keys()) if (isRelationId(relId)) {
-		if (getComponentIdFromRelationId(relId) === wildcardComponentId) return true;
+var SparseStoreImpl = class {
+	/**
+	* Primary storage, keyed by the base relation component ID.
+	*/
+	byComponent = /* @__PURE__ */ new Map();
+	/**
+	* Reverse index: which base component kinds an entity participates in.
+	* Only required to support getAllForEntity and deleteEntity efficiently.
+	* The primary storage (byComponent) is deliberately not optimized for these operations.
+	*/
+	entityIndex = /* @__PURE__ */ new Map();
+	getValue(entityId, relationType) {
+		const componentId = getComponentIdFromRelationId(relationType);
+		if (componentId === void 0) return void 0;
+		const entities = this.byComponent.get(componentId);
+		if (!entities) return void 0;
+		const entry = entities.get(entityId);
+		if (!entry) return void 0;
+		const targetId = getTargetIdFromRelationId(relationType);
+		if (entry.type === "single") return entry.target === targetId ? entry.data : void 0;
+		else {
+			const item = entry.targets.get(targetId);
+			return item ? item.data : void 0;
+		}
 	}
-	return false;
-}
-/**
-* Check if a detailed type represents a relation (entity or component)
-*/
-function isRelationType(detailedType) {
-	return detailedType.type === "entity-relation" || detailedType.type === "component-relation";
-}
-/**
-* Check if a component type matches a given component ID for relations
-*/
-function matchesRelationComponentId(componentType, componentId) {
-	const detailedType = getDetailedIdType(componentType);
-	return isRelationType(detailedType) && detailedType.componentId === componentId;
-}
-/**
-* Build cache key for component types
-*/
-function buildCacheKey(componentTypes) {
-	return componentTypes.map((id) => isOptionalEntityId(id) ? `opt(${id.optional})` : `${id}`).join(",");
-}
+	setValue(entityId, relationType, data) {
+		const componentId = getComponentIdFromRelationId(relationType);
+		if (componentId === void 0) throw new Error("setValue called with a non-relation type on SparseStore");
+		let entities = this.byComponent.get(componentId);
+		if (!entities) {
+			entities = /* @__PURE__ */ new Map();
+			this.byComponent.set(componentId, entities);
+		}
+		const targetId = getTargetIdFromRelationId(relationType);
+		let entry = entities.get(entityId);
+		if (!entry) {
+			entry = {
+				type: "single",
+				relationType,
+				target: targetId,
+				data
+			};
+			entities.set(entityId, entry);
+		} else if (entry.type === "single") if (entry.target === targetId) {
+			entry.data = data;
+			entry.relationType = relationType;
+		} else {
+			const targets = /* @__PURE__ */ new Map();
+			targets.set(entry.target, {
+				relationType: entry.relationType,
+				data: entry.data
+			});
+			targets.set(targetId, {
+				relationType,
+				data
+			});
+			entities.set(entityId, {
+				type: "multi",
+				targets
+			});
+		}
+		else entry.targets.set(targetId, {
+			relationType,
+			data
+		});
+		let components = this.entityIndex.get(entityId);
+		if (!components) {
+			components = /* @__PURE__ */ new Set();
+			this.entityIndex.set(entityId, components);
+		}
+		components.add(componentId);
+	}
+	deleteValue(entityId, relationType) {
+		const componentId = getComponentIdFromRelationId(relationType);
+		if (componentId === void 0) return false;
+		const entities = this.byComponent.get(componentId);
+		if (!entities) return false;
+		const entry = entities.get(entityId);
+		if (!entry) return false;
+		const targetId = getTargetIdFromRelationId(relationType);
+		let existed = false;
+		if (entry.type === "single") {
+			if (entry.target === targetId) {
+				existed = true;
+				entities.delete(entityId);
+			}
+		} else {
+			existed = entry.targets.delete(targetId);
+			if (entry.targets.size === 0) entities.delete(entityId);
+			else if (entry.targets.size === 1) {
+				const [first] = entry.targets.entries();
+				const [t, item] = first;
+				entities.set(entityId, {
+					type: "single",
+					relationType: item.relationType,
+					target: t,
+					data: item.data
+				});
+			}
+		}
+		if (!entities.has(entityId) && entities.size === 0) this.byComponent.delete(componentId);
+		const components = this.entityIndex.get(entityId);
+		if (components && !entities.has(entityId)) {
+			components.delete(componentId);
+			if (components.size === 0) this.entityIndex.delete(entityId);
+		}
+		return existed;
+	}
+	hasAnyForComponent(componentId) {
+		const entities = this.byComponent.get(componentId);
+		return entities !== void 0 && entities.size > 0;
+	}
+	getRelationsForComponent(entityId, componentId) {
+		const result = [];
+		const entities = this.byComponent.get(componentId);
+		if (!entities) return result;
+		const entry = entities.get(entityId);
+		if (!entry) return result;
+		if (entry.type === "single") result.push([entry.target, entry.data]);
+		else for (const [target, item] of entry.targets) result.push([target, item.data]);
+		return result;
+	}
+	getAllForEntity(entityId) {
+		const components = this.entityIndex.get(entityId);
+		if (!components || components.size === 0) return [];
+		const result = [];
+		for (const componentId of components) {
+			const entry = this.byComponent.get(componentId)?.get(entityId);
+			if (entry) if (entry.type === "single") result.push([entry.relationType, entry.data]);
+			else for (const item of entry.targets.values()) result.push([item.relationType, item.data]);
+		}
+		return result;
+	}
+	deleteEntity(entityId) {
+		const components = this.entityIndex.get(entityId);
+		if (!components) return;
+		for (const componentId of components) {
+			const entities = this.byComponent.get(componentId);
+			if (entities) {
+				entities.delete(entityId);
+				if (entities.size === 0) this.byComponent.delete(componentId);
+			}
+		}
+		this.entityIndex.delete(entityId);
+	}
+	getAllForEntities(entityIds) {
+		const result = /* @__PURE__ */ new Map();
+		for (const eid of entityIds) {
+			const data = this.getAllForEntity(eid);
+			if (data.length > 0) result.set(eid, data);
+		}
+		return result;
+	}
+};
+//#endregion
+//#region src/commands/buffer.ts
 /**
-* Get data source for wildcard relations from component types
+* Maximum number of command buffer execution iterations to prevent infinite loops
 */
-function getWildcardRelationDataSource(componentTypes, componentId, optional) {
-	const matchingRelations = componentTypes.filter((ct) => matchesRelationComponentId(ct, componentId));
-	return optional ? matchingRelations.length > 0 ? matchingRelations : void 0 : matchingRelations;
-}
+const MAX_COMMAND_ITERATIONS = 100;
 /**
-* Build wildcard relation value from matching relations.
-* Receives the SparseStore directly for efficient per-component lookups.
+* Command buffer for deferred structural changes
 */
-function buildWildcardRelationValue(wildcardRelationType, matchingRelations, getDataAtIndex, sparseStore, entityId, optional) {
-	const relations = [];
-	const targetComponentId = getComponentIdFromRelationId(wildcardRelationType);
-	for (const relType of matchingRelations || []) {
-		const data = getDataAtIndex(relType);
-		const targetId = getTargetIdFromRelationId(relType);
-		relations.push([targetId, data === MISSING_COMPONENT ? void 0 : data]);
+var CommandBuffer = class {
+	commands = [];
+	swapBuffer = [];
+	/** Reusable map to group commands by entity, avoids per-sync allocations */
+	entityCommands = /* @__PURE__ */ new Map();
+	executeEntityCommands;
+	/**
+	* Create a command buffer with an executor function
+	*/
+	constructor(executeEntityCommands) {
+		this.executeEntityCommands = executeEntityCommands;
 	}
-	if (targetComponentId !== void 0) {
-		const dfMatches = sparseStore.getRelationsForComponent(entityId, targetComponentId);
-		for (const m of dfMatches) relations.push(m);
+	set(entityId, componentType, component) {
+		this.commands.push({
+			type: "set",
+			entityId,
+			componentType,
+			component
+		});
 	}
-	if (relations.length === 0) {
-		if (!optional) {
-			const componentId = getComponentIdFromRelationId(wildcardRelationType);
-			throw new Error(`No matching relations found for mandatory wildcard relation component ${componentId} on entity ${entityId}`);
+	/**
+	* Remove a component from an entity (deferred)
+	*/
+	remove(entityId, componentType) {
+		this.commands.push({
+			type: "delete",
+			entityId,
+			componentType
+		});
+	}
+	/**
+	* Destroy an entity (deferred)
+	*/
+	delete(entityId) {
+		this.commands.push({
+			type: "destroy",
+			entityId
+		});
+	}
+	/**
+	* Execute all commands and clear the buffer.
+	* Returns the number of iterations performed (for debug stats).
+	*/
+	execute() {
+		let iterations = 0;
+		while (this.commands.length > 0) {
+			if (iterations >= MAX_COMMAND_ITERATIONS) throw new Error("Command execution exceeded maximum iterations, possible infinite loop");
+			iterations++;
+			const currentCommands = this.commands;
+			this.commands = this.swapBuffer;
+			const entityCommands = this.entityCommands;
+			for (const cmd of currentCommands) {
+				const existing = entityCommands.get(cmd.entityId);
+				if (existing !== void 0) existing.push(cmd);
+				else entityCommands.set(cmd.entityId, [cmd]);
+			}
+			currentCommands.length = 0;
+			this.swapBuffer = currentCommands;
+			for (const [entityId, commands] of entityCommands) this.executeEntityCommands(entityId, commands);
+			entityCommands.clear();
 		}
-		return;
+		return iterations;
 	}
-	return optional ? { value: relations } : relations;
+	/**
+	* Get current commands (for testing)
+	*/
+	getCommands() {
+		return [...this.commands];
+	}
+	/**
+	* Clear all commands
+	*/
+	clear() {
+		this.commands = [];
+	}
+};
+//#endregion
+//#region src/types/index.ts
+function isOptionalEntityId(type) {
+	return typeof type === "object" && type !== null && "optional" in type;
+}
+//#endregion
+//#region src/component/type-utils.ts
+/**
+* Normalize component type collections into a stable ascending order.
+* This keeps cache keys and archetype signatures deterministic.
+*/
+function normalizeComponentTypes(componentTypes) {
+	return [...componentTypes].sort((a, b) => a - b);
 }
+//#endregion
+//#region src/utils/utils.ts
 /**
-* Build regular component value from data source
+* Utility functions for ECS library
 */
-function buildRegularComponentValue(dataSource, entityIndex, optional) {
-	if (dataSource === void 0) {
-		if (optional) return void 0;
-		throw new Error(`Component data not found for mandatory component type`);
-	}
-	const data = dataSource[entityIndex];
-	const result = data === MISSING_COMPONENT ? void 0 : data;
-	return optional ? { value: result } : result;
-}
 /**
-* Build a single component value based on its type
+* Get a value from cache or compute and cache it if not present
+* @param cache The cache map
+* @param key The cache key
+* @param compute Function to compute the value if not cached (may have side effects)
+* @returns The cached or computed value
 */
-function buildSingleComponent(compType, dataSource, entityIndex, entityId, getComponentData, sparseRelations) {
-	const optional = isOptionalEntityId(compType);
-	const actualType = optional ? compType.optional : compType;
-	if (getIdType(actualType) === "wildcard-relation") return buildWildcardRelationValue(actualType, dataSource, (relType) => getComponentData(relType)[entityIndex], sparseRelations, entityId, optional);
-	else return buildRegularComponentValue(dataSource, entityIndex, optional);
+function getOrCompute(cache, key, compute) {
+	let value = cache.get(key);
+	if (value === void 0) {
+		value = compute();
+		cache.set(key, value);
+	}
+	return value;
 }
 //#endregion
 //#region src/archetype/archetype.ts
@@ -957,424 +1160,202 @@ var Archetype = class {
 		if (this.componentTypeSet.has(componentType)) {
 			const data = this.getComponentData(componentType)[index];
 			if (data === MISSING_COMPONENT) throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
-			return data;
-		}
-		if (this.sparseRelations.getValue(entityId, componentType) !== void 0 || this.sparseRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return this.sparseRelations.getValue(entityId, componentType);
-		throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
-	}
-	getOptional(entityId, componentType) {
-		const index = this.entityToIndex.get(entityId);
-		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
-		if (this.componentTypeSet.has(componentType)) {
-			const data = this.getComponentData(componentType)[index];
-			if (data === MISSING_COMPONENT) return void 0;
-			return { value: data };
-		}
-		const value = this.sparseRelations.getValue(entityId, componentType);
-		if (value !== void 0) return { value };
-		if (this.sparseRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return { value: this.sparseRelations.getValue(entityId, componentType) };
-	}
-	set(entityId, componentType, data) {
-		const index = this.entityToIndex.get(entityId);
-		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
-		if (this.componentData.has(componentType)) {
-			this.getComponentData(componentType)[index] = data;
-			return;
-		}
-		const detailedType = getDetailedIdType(componentType);
-		if (isRelationType(detailedType) && isSparseComponent(detailedType.componentId)) {
-			this.sparseRelations.setValue(entityId, componentType, data);
-			return;
-		}
-		throw new Error(`Component type ${componentType} is not in this archetype`);
-	}
-	getEntities() {
-		return this.entities;
-	}
-	getEntityToIndexMap() {
-		return this.entityToIndex;
-	}
-	getComponentData(componentType) {
-		const data = this.componentData.get(componentType);
-		if (!data) throw new Error(`Component type ${componentType} is not in this archetype`);
-		return data;
-	}
-	getOptionalComponentData(componentType) {
-		return this.componentData.get(componentType);
-	}
-	getCachedComponentDataSources(componentTypes) {
-		const cacheKey = buildCacheKey(componentTypes);
-		return getOrCompute(this.componentDataSourcesCache, cacheKey, () => componentTypes.map((compType) => this.getComponentDataSource(compType)));
-	}
-	getComponentDataSource(compType) {
-		const optional = isOptionalEntityId(compType);
-		const actualType = optional ? compType.optional : compType;
-		if (getIdType(actualType) === "wildcard-relation") {
-			const componentId = getComponentIdFromRelationId(actualType);
-			return getWildcardRelationDataSource(this.componentTypes, componentId, optional);
-		}
-		return optional ? this.getOptionalComponentData(actualType) : this.getComponentData(actualType);
-	}
-	buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entityId) {
-		return componentDataSources.map((dataSource, i) => buildSingleComponent(componentTypes[i], dataSource, entityIndex, entityId, (type) => this.getComponentData(type), this.sparseRelations));
-	}
-	getEntitiesWithComponents(componentTypes) {
-		const result = [];
-		this.appendEntitiesWithComponents(componentTypes, result);
-		return result;
-	}
-	appendEntitiesWithComponents(componentTypes, result) {
-		this.forEachWithComponents(componentTypes, (entity, ...components) => {
-			result.push({
-				entity,
-				components
-			});
-		});
-	}
-	*iterateWithComponents(componentTypes) {
-		const componentDataSources = this.getCachedComponentDataSources(componentTypes);
-		for (let entityIndex = 0; entityIndex < this.entities.length; entityIndex++) {
-			const entity = this.entities[entityIndex];
-			yield [entity, ...this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entity)];
-		}
-	}
-	forEachWithComponents(componentTypes, callback) {
-		const componentDataSources = this.getCachedComponentDataSources(componentTypes);
-		for (let entityIndex = 0; entityIndex < this.entities.length; entityIndex++) {
-			const entity = this.entities[entityIndex];
-			callback(entity, ...this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entity));
-		}
-	}
-	forEach(callback) {
-		for (let i = 0; i < this.entities.length; i++) {
-			const entity = this.entities[i];
-			const components = /* @__PURE__ */ new Map();
-			for (const componentType of this.componentTypes) {
-				const data = this.getComponentData(componentType)[i];
-				components.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
-			}
-			const sparseTuples = this.sparseRelations.getAllForEntity(entity);
-			for (const [componentType, data] of sparseTuples) components.set(componentType, data);
-			callback(entity, components);
-		}
-	}
-	hasRelationWithComponentId(componentId) {
-		for (const componentType of this.componentTypes) {
-			const detailedType = getDetailedIdType(componentType);
-			if (isRelationType(detailedType) && detailedType.componentId === componentId) return true;
-		}
-		for (const entityId of this.entities) if (this.sparseRelations.getRelationsForComponent(entityId, componentId).length > 0) return true;
-		return false;
-	}
-};
-//#endregion
-//#region src/archetype/store.ts
-/**
-* Production implementation of SparseStore.
-*
-* Internal layout (optimized):
-* - byComponent: baseComponentId → (entityId → RelationEntry)
-*   RelationEntry uses a single-value form for the common exclusive case (1 target),
-*   avoiding Map allocation for the vast majority of usage.
-* - entityIndex: entityId → Set<baseComponentId>
-*   Lightweight reverse index.
-*/
-var SparseStoreImpl = class {
-	/**
-	* Primary storage, keyed by the base relation component ID.
-	*/
-	byComponent = /* @__PURE__ */ new Map();
-	/**
-	* Reverse index: which base component kinds an entity participates in.
-	* Only required to support getAllForEntity and deleteEntity efficiently.
-	* The primary storage (byComponent) is deliberately not optimized for these operations.
-	*/
-	entityIndex = /* @__PURE__ */ new Map();
-	getValue(entityId, relationType) {
-		const componentId = getComponentIdFromRelationId(relationType);
-		if (componentId === void 0) return void 0;
-		const entities = this.byComponent.get(componentId);
-		if (!entities) return void 0;
-		const entry = entities.get(entityId);
-		if (!entry) return void 0;
-		const targetId = getTargetIdFromRelationId(relationType);
-		if (entry.type === "single") return entry.target === targetId ? entry.data : void 0;
-		else {
-			const item = entry.targets.get(targetId);
-			return item ? item.data : void 0;
-		}
-	}
-	setValue(entityId, relationType, data) {
-		const componentId = getComponentIdFromRelationId(relationType);
-		if (componentId === void 0) throw new Error("setValue called with a non-relation type on SparseStore");
-		let entities = this.byComponent.get(componentId);
-		if (!entities) {
-			entities = /* @__PURE__ */ new Map();
-			this.byComponent.set(componentId, entities);
-		}
-		const targetId = getTargetIdFromRelationId(relationType);
-		let entry = entities.get(entityId);
-		if (!entry) {
-			entry = {
-				type: "single",
-				relationType,
-				target: targetId,
-				data
-			};
-			entities.set(entityId, entry);
-		} else if (entry.type === "single") if (entry.target === targetId) {
-			entry.data = data;
-			entry.relationType = relationType;
-		} else {
-			const targets = /* @__PURE__ */ new Map();
-			targets.set(entry.target, {
-				relationType: entry.relationType,
-				data: entry.data
-			});
-			targets.set(targetId, {
-				relationType,
-				data
-			});
-			entities.set(entityId, {
-				type: "multi",
-				targets
-			});
-		}
-		else entry.targets.set(targetId, {
-			relationType,
-			data
-		});
-		let components = this.entityIndex.get(entityId);
-		if (!components) {
-			components = /* @__PURE__ */ new Set();
-			this.entityIndex.set(entityId, components);
-		}
-		components.add(componentId);
-	}
-	deleteValue(entityId, relationType) {
-		const componentId = getComponentIdFromRelationId(relationType);
-		if (componentId === void 0) return false;
-		const entities = this.byComponent.get(componentId);
-		if (!entities) return false;
-		const entry = entities.get(entityId);
-		if (!entry) return false;
-		const targetId = getTargetIdFromRelationId(relationType);
-		let existed = false;
-		if (entry.type === "single") {
-			if (entry.target === targetId) {
-				existed = true;
-				entities.delete(entityId);
-			}
-		} else {
-			existed = entry.targets.delete(targetId);
-			if (entry.targets.size === 0) entities.delete(entityId);
-			else if (entry.targets.size === 1) {
-				const [first] = entry.targets.entries();
-				const [t, item] = first;
-				entities.set(entityId, {
-					type: "single",
-					relationType: item.relationType,
-					target: t,
-					data: item.data
-				});
-			}
+			return data;
 		}
-		if (!entities.has(entityId) && entities.size === 0) this.byComponent.delete(componentId);
-		const components = this.entityIndex.get(entityId);
-		if (components && !entities.has(entityId)) {
-			components.delete(componentId);
-			if (components.size === 0) this.entityIndex.delete(entityId);
+		if (this.sparseRelations.getValue(entityId, componentType) !== void 0 || this.sparseRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return this.sparseRelations.getValue(entityId, componentType);
+		throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
+	}
+	getOptional(entityId, componentType) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
+		if (this.componentTypeSet.has(componentType)) {
+			const data = this.getComponentData(componentType)[index];
+			if (data === MISSING_COMPONENT) return void 0;
+			return { value: data };
 		}
-		return existed;
+		const value = this.sparseRelations.getValue(entityId, componentType);
+		if (value !== void 0) return { value };
+		if (this.sparseRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return { value: this.sparseRelations.getValue(entityId, componentType) };
 	}
-	hasAnyForComponent(componentId) {
-		const entities = this.byComponent.get(componentId);
-		return entities !== void 0 && entities.size > 0;
+	set(entityId, componentType, data) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
+		if (this.componentData.has(componentType)) {
+			this.getComponentData(componentType)[index] = data;
+			return;
+		}
+		const detailedType = getDetailedIdType(componentType);
+		if (isRelationType(detailedType) && isSparseComponent(detailedType.componentId)) {
+			this.sparseRelations.setValue(entityId, componentType, data);
+			return;
+		}
+		throw new Error(`Component type ${componentType} is not in this archetype`);
 	}
-	getRelationsForComponent(entityId, componentId) {
-		const result = [];
-		const entities = this.byComponent.get(componentId);
-		if (!entities) return result;
-		const entry = entities.get(entityId);
-		if (!entry) return result;
-		if (entry.type === "single") result.push([entry.target, entry.data]);
-		else for (const [target, item] of entry.targets) result.push([target, item.data]);
-		return result;
+	getEntities() {
+		return this.entities;
 	}
-	getAllForEntity(entityId) {
-		const components = this.entityIndex.get(entityId);
-		if (!components || components.size === 0) return [];
-		const result = [];
-		for (const componentId of components) {
-			const entry = this.byComponent.get(componentId)?.get(entityId);
-			if (entry) if (entry.type === "single") result.push([entry.relationType, entry.data]);
-			else for (const item of entry.targets.values()) result.push([item.relationType, item.data]);
-		}
-		return result;
+	getEntityToIndexMap() {
+		return this.entityToIndex;
 	}
-	deleteEntity(entityId) {
-		const components = this.entityIndex.get(entityId);
-		if (!components) return;
-		for (const componentId of components) {
-			const entities = this.byComponent.get(componentId);
-			if (entities) {
-				entities.delete(entityId);
-				if (entities.size === 0) this.byComponent.delete(componentId);
-			}
-		}
-		this.entityIndex.delete(entityId);
+	getComponentData(componentType) {
+		const data = this.componentData.get(componentType);
+		if (!data) throw new Error(`Component type ${componentType} is not in this archetype`);
+		return data;
 	}
-	getAllForEntities(entityIds) {
-		const result = /* @__PURE__ */ new Map();
-		for (const eid of entityIds) {
-			const data = this.getAllForEntity(eid);
-			if (data.length > 0) result.set(eid, data);
+	getOptionalComponentData(componentType) {
+		return this.componentData.get(componentType);
+	}
+	getCachedComponentDataSources(componentTypes) {
+		const cacheKey = buildCacheKey(componentTypes);
+		return getOrCompute(this.componentDataSourcesCache, cacheKey, () => componentTypes.map((compType) => this.getComponentDataSource(compType)));
+	}
+	getComponentDataSource(compType) {
+		const optional = isOptionalEntityId(compType);
+		const actualType = optional ? compType.optional : compType;
+		if (getIdType(actualType) === "wildcard-relation") {
+			const componentId = getComponentIdFromRelationId(actualType);
+			return getWildcardRelationDataSource(this.componentTypes, componentId, optional);
 		}
-		return result;
+		return optional ? this.getOptionalComponentData(actualType) : this.getComponentData(actualType);
 	}
-};
-//#endregion
-//#region src/commands/buffer.ts
-/**
-* Maximum number of command buffer execution iterations to prevent infinite loops
-*/
-const MAX_COMMAND_ITERATIONS = 100;
-/**
-* Command buffer for deferred structural changes
-*/
-var CommandBuffer = class {
-	commands = [];
-	swapBuffer = [];
-	/** Reusable map to group commands by entity, avoids per-sync allocations */
-	entityCommands = /* @__PURE__ */ new Map();
-	executeEntityCommands;
-	/**
-	* Create a command buffer with an executor function
-	*/
-	constructor(executeEntityCommands) {
-		this.executeEntityCommands = executeEntityCommands;
+	buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entityId) {
+		return componentDataSources.map((dataSource, i) => buildSingleComponent(componentTypes[i], dataSource, entityIndex, entityId, (type) => this.getComponentData(type), this.sparseRelations));
 	}
-	set(entityId, componentType, component) {
-		this.commands.push({
-			type: "set",
-			entityId,
-			componentType,
-			component
-		});
+	getEntitiesWithComponents(componentTypes) {
+		const result = [];
+		this.appendEntitiesWithComponents(componentTypes, result);
+		return result;
 	}
-	/**
-	* Remove a component from an entity (deferred)
-	*/
-	remove(entityId, componentType) {
-		this.commands.push({
-			type: "delete",
-			entityId,
-			componentType
+	appendEntitiesWithComponents(componentTypes, result) {
+		this.forEachWithComponents(componentTypes, (entity, ...components) => {
+			result.push({
+				entity,
+				components
+			});
 		});
 	}
-	/**
-	* Destroy an entity (deferred)
-	*/
-	delete(entityId) {
-		this.commands.push({
-			type: "destroy",
-			entityId
-		});
+	*iterateWithComponents(componentTypes) {
+		const componentDataSources = this.getCachedComponentDataSources(componentTypes);
+		for (let entityIndex = 0; entityIndex < this.entities.length; entityIndex++) {
+			const entity = this.entities[entityIndex];
+			yield [entity, ...this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entity)];
+		}
 	}
-	/**
-	* Execute all commands and clear the buffer.
-	* Returns the number of iterations performed (for debug stats).
-	*/
-	execute() {
-		let iterations = 0;
-		while (this.commands.length > 0) {
-			if (iterations >= MAX_COMMAND_ITERATIONS) throw new Error("Command execution exceeded maximum iterations, possible infinite loop");
-			iterations++;
-			const currentCommands = this.commands;
-			this.commands = this.swapBuffer;
-			const entityCommands = this.entityCommands;
-			for (const cmd of currentCommands) {
-				const existing = entityCommands.get(cmd.entityId);
-				if (existing !== void 0) existing.push(cmd);
-				else entityCommands.set(cmd.entityId, [cmd]);
-			}
-			currentCommands.length = 0;
-			this.swapBuffer = currentCommands;
-			for (const [entityId, commands] of entityCommands) this.executeEntityCommands(entityId, commands);
-			entityCommands.clear();
+	forEachWithComponents(componentTypes, callback) {
+		const componentDataSources = this.getCachedComponentDataSources(componentTypes);
+		for (let entityIndex = 0; entityIndex < this.entities.length; entityIndex++) {
+			const entity = this.entities[entityIndex];
+			callback(entity, ...this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entity));
 		}
-		return iterations;
 	}
-	/**
-	* Get current commands (for testing)
-	*/
-	getCommands() {
-		return [...this.commands];
+	forEach(callback) {
+		for (let i = 0; i < this.entities.length; i++) {
+			const entity = this.entities[i];
+			const components = /* @__PURE__ */ new Map();
+			for (const componentType of this.componentTypes) {
+				const data = this.getComponentData(componentType)[i];
+				components.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
+			}
+			const sparseTuples = this.sparseRelations.getAllForEntity(entity);
+			for (const [componentType, data] of sparseTuples) components.set(componentType, data);
+			callback(entity, components);
+		}
 	}
-	/**
-	* Clear all commands
-	*/
-	clear() {
-		this.commands = [];
+	hasRelationWithComponentId(componentId) {
+		for (const componentType of this.componentTypes) {
+			const detailedType = getDetailedIdType(componentType);
+			if (isRelationType(detailedType) && detailedType.componentId === componentId) return true;
+		}
+		for (const entityId of this.entities) if (this.sparseRelations.getRelationsForComponent(entityId, componentId).length > 0) return true;
+		return false;
 	}
 };
 //#endregion
-//#region src/commands/changeset.ts
+//#region src/archetype/helpers.ts
 /**
-* @internal Represents a set of component changes to be applied to an entity
+* Check if a components map has any wildcard relations matching a component ID
+* @param components - Component entity's components map
+* @param wildcardComponentId - The component ID to match
+* @returns True if at least one matching relation exists
 */
-var ComponentChangeset = class {
-	adds = /* @__PURE__ */ new Map();
-	removes = /* @__PURE__ */ new Set();
-	/**
-	* Add a component to the changeset
-	*/
-	set(componentType, component) {
-		this.adds.set(componentType, component);
-		this.removes.delete(componentType);
-	}
-	/**
-	* Remove a component from the changeset
-	*/
-	delete(componentType) {
-		this.removes.add(componentType);
-		this.adds.delete(componentType);
+function hasWildcardRelation(components, wildcardComponentId) {
+	for (const relId of components.keys()) if (isRelationId(relId)) {
+		if (getComponentIdFromRelationId(relId) === wildcardComponentId) return true;
 	}
-	/**
-	* Check if the changeset has any changes
-	*/
-	hasChanges() {
-		return this.adds.size > 0 || this.removes.size > 0;
+	return false;
+}
+/**
+* Check if a detailed type represents a relation (entity or component)
+*/
+function isRelationType(detailedType) {
+	return detailedType.type === "entity-relation" || detailedType.type === "component-relation";
+}
+/**
+* Check if a component type matches a given component ID for relations
+*/
+function matchesRelationComponentId(componentType, componentId) {
+	const detailedType = getDetailedIdType(componentType);
+	return isRelationType(detailedType) && detailedType.componentId === componentId;
+}
+/**
+* Build cache key for component types
+*/
+function buildCacheKey(componentTypes) {
+	return componentTypes.map((id) => isOptionalEntityId(id) ? `opt(${id.optional})` : `${id}`).join(",");
+}
+/**
+* Get data source for wildcard relations from component types
+*/
+function getWildcardRelationDataSource(componentTypes, componentId, optional) {
+	const matchingRelations = componentTypes.filter((ct) => matchesRelationComponentId(ct, componentId));
+	return optional ? matchingRelations.length > 0 ? matchingRelations : void 0 : matchingRelations;
+}
+/**
+* Build wildcard relation value from matching relations.
+* Receives the SparseStore directly for efficient per-component lookups.
+*/
+function buildWildcardRelationValue(wildcardRelationType, matchingRelations, getDataAtIndex, sparseStore, entityId, optional) {
+	const relations = [];
+	const targetComponentId = getComponentIdFromRelationId(wildcardRelationType);
+	for (const relType of matchingRelations || []) {
+		const data = getDataAtIndex(relType);
+		const targetId = getTargetIdFromRelationId(relType);
+		relations.push([targetId, data === MISSING_COMPONENT ? void 0 : data]);
 	}
-	/**
-	* Clear all changes
-	*/
-	clear() {
-		this.adds.clear();
-		this.removes.clear();
+	if (targetComponentId !== void 0) {
+		const dfMatches = sparseStore.getRelationsForComponent(entityId, targetComponentId);
+		for (const m of dfMatches) relations.push(m);
 	}
-	/**
-	* Merge another changeset into this one
-	*/
-	merge(other) {
-		for (const [componentType, component] of other.adds) {
-			this.adds.set(componentType, component);
-			this.removes.delete(componentType);
-		}
-		for (const componentType of other.removes) {
-			this.removes.add(componentType);
-			this.adds.delete(componentType);
+	if (relations.length === 0) {
+		if (!optional) {
+			const componentId = getComponentIdFromRelationId(wildcardRelationType);
+			throw new Error(`No matching relations found for mandatory wildcard relation component ${componentId} on entity ${entityId}`);
 		}
+		return;
 	}
-	/**
-	* Apply the changeset to existing components and return the final state
-	*/
-	applyTo(existingComponents) {
-		for (const componentType of this.removes) existingComponents.delete(componentType);
-		for (const [componentType, component] of this.adds) existingComponents.set(componentType, component);
-		return existingComponents;
+	return optional ? { value: relations } : relations;
+}
+/**
+* Build regular component value from data source
+*/
+function buildRegularComponentValue(dataSource, entityIndex, optional) {
+	if (dataSource === void 0) {
+		if (optional) return void 0;
+		throw new Error(`Component data not found for mandatory component type`);
 	}
-};
+	const data = dataSource[entityIndex];
+	const result = data === MISSING_COMPONENT ? void 0 : data;
+	return optional ? { value: result } : result;
+}
+/**
+* Build a single component value based on its type
+*/
+function buildSingleComponent(compType, dataSource, entityIndex, entityId, getComponentData, sparseRelations) {
+	const optional = isOptionalEntityId(compType);
+	const actualType = optional ? compType.optional : compType;
+	if (getIdType(actualType) === "wildcard-relation") return buildWildcardRelationValue(actualType, dataSource, (relType) => getComponentData(relType)[entityIndex], sparseRelations, entityId, optional);
+	else return buildRegularComponentValue(dataSource, entityIndex, optional);
+}
 //#endregion
 //#region src/component/entity-store.ts
 /**
@@ -1934,78 +1915,299 @@ function maybeRemoveWildcardMarker(entityId, archetype, removedComponentType, co
 		if (changeset.removes.has(otherComponentType)) continue;
 		if (getComponentIdFromRelationId(otherComponentType) === componentId) return;
 	}
-	for (const addedType of changeset.adds.keys()) {
-		if (addedType === removedComponentType) continue;
-		if (getComponentIdFromRelationId(addedType) === componentId) return;
+	for (const addedType of changeset.adds.keys()) {
+		if (addedType === removedComponentType) continue;
+		if (getComponentIdFromRelationId(addedType) === componentId) return;
+	}
+	changeset.delete(wildcardMarker);
+}
+function hasEntityComponent(archetype, entityId, componentType) {
+	if (archetype.componentTypeSet.has(componentType)) return true;
+	return archetype.getEntitySparseRelations(entityId)?.has(componentType) ?? false;
+}
+function pruneMissingRemovals(changeset, archetype, entityId) {
+	let toPrune;
+	for (const componentType of changeset.removes) if (!hasEntityComponent(archetype, entityId, componentType)) {
+		if (toPrune === void 0) toPrune = [];
+		toPrune.push(componentType);
+	}
+	if (toPrune !== void 0) for (const componentType of toPrune) changeset.removes.delete(componentType);
+}
+function hasArchetypeStructuralChange(changeset, currentArchetype) {
+	for (const componentType of changeset.removes) if (!isSparseRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) return true;
+	for (const componentType of changeset.adds.keys()) if (!isSparseRelation(componentType) && !currentArchetype.componentTypeSet.has(componentType)) return true;
+	return false;
+}
+function buildFinalRegularComponentTypes(currentArchetype, changeset) {
+	const finalRegularTypes = new Set(currentArchetype.componentTypes);
+	for (const componentType of changeset.removes) if (!isSparseRelation(componentType)) finalRegularTypes.delete(componentType);
+	for (const [componentType] of changeset.adds) if (!isSparseRelation(componentType)) finalRegularTypes.add(componentType);
+	return Array.from(finalRegularTypes);
+}
+function applyChangeset(ctx, entityId, currentArchetype, changeset, entityToArchetype, removedComponents) {
+	pruneMissingRemovals(changeset, currentArchetype, entityId);
+	if (hasArchetypeStructuralChange(changeset, currentArchetype)) {
+		const finalRegularTypes = buildFinalRegularComponentTypes(currentArchetype, changeset);
+		const newArchetype = ctx.ensureArchetype(finalRegularTypes);
+		const currentComponents = currentArchetype.removeEntity(entityId);
+		if (removedComponents !== null) for (const componentType of changeset.removes) removedComponents.set(componentType, currentComponents.get(componentType));
+		newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
+		entityToArchetype.set(entityId, newArchetype);
+		return newArchetype;
+	}
+	if (removedComponents !== null) applySparseChanges(ctx.sparseStore, entityId, changeset, removedComponents);
+	else applySparseChangesNoHooks(ctx.sparseStore, entityId, changeset);
+	for (const [componentType, component] of changeset.adds) {
+		if (isSparseRelation(componentType)) continue;
+		currentArchetype.set(entityId, componentType, component);
+	}
+	return currentArchetype;
+}
+function applySparseChanges(sparseStore, entityId, changeset, removedComponents) {
+	for (const componentType of changeset.removes) if (isSparseRelation(componentType)) {
+		const removedValue = sparseStore.getValue(entityId, componentType);
+		if (removedValue !== void 0 || sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)) removedComponents.set(componentType, removedValue);
+		sparseStore.deleteValue(entityId, componentType);
+	}
+	for (const [componentType, component] of changeset.adds) if (isSparseRelation(componentType)) sparseStore.setValue(entityId, componentType, component);
+}
+function applySparseChangesNoHooks(sparseStore, entityId, changeset) {
+	for (const componentType of changeset.removes) if (isSparseRelation(componentType)) sparseStore.deleteValue(entityId, componentType);
+	for (const [componentType, component] of changeset.adds) if (isSparseRelation(componentType)) sparseStore.setValue(entityId, componentType, component);
+}
+function filterRegularComponentTypes(componentTypes) {
+	const regularTypes = [];
+	for (const componentType of componentTypes) {
+		if (isSparseWildcard(componentType)) {
+			regularTypes.push(componentType);
+			continue;
+		}
+		if (isSparseRelation(componentType)) continue;
+		regularTypes.push(componentType);
+	}
+	return regularTypes;
+}
+//#endregion
+//#region src/world/archetype-manager.ts
+/**
+* Encapsulates all archetype storage, indexing, creation, removal, and reverse
+* referencing logic that was previously scattered as private methods + maps
+* directly on the World class.
+*
+* Responsibilities:
+* - Archetype memoization by signature
+* - Component-type reverse index (archetypesByComponent)
+* - Entity → current Archetype map
+* - Reverse "who references this entity via component/relation" index
+* - Creation + removal with proper notifications to QueryRegistry + hook matching
+* - Cleanup of empty archetypes after entity cascades
+*
+* This extraction shrinks World while keeping the same behavior and hot-path characteristics.
+*/
+var ArchetypeManager = class {
+	archetypes = [];
+	archetypeBySignature = /* @__PURE__ */ new Map();
+	entityToArchetype = /* @__PURE__ */ new Map();
+	archetypesByComponent = /* @__PURE__ */ new Map();
+	entityToReferencingArchetypes = /* @__PURE__ */ new Map();
+	sparseStore;
+	ctx;
+	constructor(ctx, sparseStore) {
+		this.ctx = ctx;
+		this.sparseStore = sparseStore;
+	}
+	/** Primary entry point — memoized archetype creation/lookup. */
+	ensureArchetype(componentTypes) {
+		const sortedTypes = normalizeComponentTypes(filterRegularComponentTypes(componentTypes));
+		const hashKey = this.createArchetypeSignature(sortedTypes);
+		return getOrCompute(this.archetypeBySignature, hashKey, () => this.createNewArchetype(sortedTypes));
+	}
+	getArchetypeForEntity(entityId) {
+		return this.entityToArchetype.get(entityId);
+	}
+	setEntityToArchetype(entityId, archetype) {
+		this.entityToArchetype.set(entityId, archetype);
+	}
+	getMatchingArchetypes(componentTypes) {
+		if (componentTypes.length === 0) return [...this.archetypes];
+		const regularComponents = [];
+		const wildcardRelations = [];
+		for (const componentType of componentTypes) if (isWildcardRelationId(componentType)) {
+			const componentId = getComponentIdFromRelationId(componentType);
+			if (componentId !== void 0) 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;
+	}
+	getArchetypesWithComponents(componentTypes) {
+		if (componentTypes.length === 0) return [...this.archetypes];
+		if (componentTypes.length === 1) {
+			const set = this.archetypesByComponent.get(componentTypes[0]);
+			return set ? Array.from(set) : [];
+		}
+		const sets = componentTypes.map((type) => this.archetypesByComponent.get(type)).filter((s) => s !== void 0 && s.size > 0).sort((a, b) => a.size - b.size);
+		if (sets.length === 0) return [];
+		if (sets.length < componentTypes.length) return [];
+		const smallest = sets[0];
+		if (sets.length === 2) {
+			const other = sets[1];
+			return Array.from(smallest).filter((a) => other.has(a));
+		}
+		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);
+	}
+	createArchetypeSignature(componentTypes) {
+		return componentTypes.join(",");
+	}
+	/** Deduplicated version of the original pair of methods. */
+	updateReferencingIndex(componentType, archetype, isAdd) {
+		const detailedType = getDetailedIdType(componentType);
+		let entityId;
+		if (detailedType.type === "entity") entityId = componentType;
+		else if (detailedType.type === "entity-relation") entityId = detailedType.targetId;
+		if (entityId !== void 0) {
+			let refs = this.entityToReferencingArchetypes.get(entityId);
+			if (isAdd) {
+				if (!refs) {
+					refs = /* @__PURE__ */ new Set();
+					this.entityToReferencingArchetypes.set(entityId, refs);
+				}
+				refs.add(archetype);
+			} else if (refs) {
+				refs.delete(archetype);
+				if (refs.size === 0) this.entityToReferencingArchetypes.delete(entityId);
+			}
+		}
+	}
+	createNewArchetype(componentTypes) {
+		const newArchetype = new Archetype(componentTypes, this.sparseStore);
+		this.archetypes.push(newArchetype);
+		this.ctx.recordArchetypeCreated?.();
+		for (const componentType of componentTypes) {
+			let archetypes = this.archetypesByComponent.get(componentType);
+			if (!archetypes) {
+				archetypes = /* @__PURE__ */ new Set();
+				this.archetypesByComponent.set(componentType, archetypes);
+			}
+			archetypes.add(newArchetype);
+			this.updateReferencingIndex(componentType, newArchetype, true);
+		}
+		this.ctx.queryRegistry.onNewArchetype(newArchetype);
+		this.updateArchetypeHookMatches(newArchetype);
+		return newArchetype;
+	}
+	updateArchetypeHookMatches(archetype) {
+		for (const entry of this.ctx.hooks) if (this.archetypeMatchesHook(archetype, entry)) {
+			archetype.matchingMultiHooks.add(entry);
+			if (entry.matchedArchetypes) entry.matchedArchetypes.add(archetype);
+		}
+	}
+	archetypeMatchesHook(archetype, entry) {
+		return entry.requiredComponents.every((c) => {
+			if (isWildcardRelationId(c)) {
+				if (isSparseWildcard(c)) return true;
+				const componentId = getComponentIdFromRelationId(c);
+				return componentId !== void 0 && archetype.hasRelationWithComponentId(componentId);
+			}
+			return archetype.componentTypeSet.has(c) || isSparseRelation(c);
+		}) && matchesFilter(archetype, entry.filter);
+	}
+	/** Called during cascade deletion cleanup. */
+	cleanupArchetypesReferencingEntity(entityId) {
+		const refs = this.entityToReferencingArchetypes.get(entityId);
+		if (!refs) return;
+		for (const archetype of refs) if (archetype.getEntities().length === 0) this.removeArchetype(archetype);
+		this.entityToReferencingArchetypes.delete(entityId);
 	}
-	changeset.delete(wildcardMarker);
-}
-function hasEntityComponent(archetype, entityId, componentType) {
-	if (archetype.componentTypeSet.has(componentType)) return true;
-	return archetype.getEntitySparseRelations(entityId)?.has(componentType) ?? false;
-}
-function pruneMissingRemovals(changeset, archetype, entityId) {
-	let toPrune;
-	for (const componentType of changeset.removes) if (!hasEntityComponent(archetype, entityId, componentType)) {
-		if (toPrune === void 0) toPrune = [];
-		toPrune.push(componentType);
+	removeArchetype(archetype) {
+		const index = this.archetypes.indexOf(archetype);
+		if (index !== -1) {
+			const last = this.archetypes[this.archetypes.length - 1];
+			this.archetypes[index] = last;
+			this.archetypes.pop();
+		}
+		this.ctx.recordArchetypeRemoved?.();
+		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);
+			}
+			this.updateReferencingIndex(componentType, archetype, false);
+		}
+		this.ctx.queryRegistry.onArchetypeRemoved(archetype);
 	}
-	if (toPrune !== void 0) for (const componentType of toPrune) changeset.removes.delete(componentType);
-}
-function hasArchetypeStructuralChange(changeset, currentArchetype) {
-	for (const componentType of changeset.removes) if (!isSparseRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) return true;
-	for (const componentType of changeset.adds.keys()) if (!isSparseRelation(componentType) && !currentArchetype.componentTypeSet.has(componentType)) return true;
-	return false;
-}
-function buildFinalRegularComponentTypes(currentArchetype, changeset) {
-	const finalRegularTypes = new Set(currentArchetype.componentTypes);
-	for (const componentType of changeset.removes) if (!isSparseRelation(componentType)) finalRegularTypes.delete(componentType);
-	for (const [componentType] of changeset.adds) if (!isSparseRelation(componentType)) finalRegularTypes.add(componentType);
-	return Array.from(finalRegularTypes);
-}
-function applyChangeset(ctx, entityId, currentArchetype, changeset, entityToArchetype, removedComponents) {
-	pruneMissingRemovals(changeset, currentArchetype, entityId);
-	if (hasArchetypeStructuralChange(changeset, currentArchetype)) {
-		const finalRegularTypes = buildFinalRegularComponentTypes(currentArchetype, changeset);
-		const newArchetype = ctx.ensureArchetype(finalRegularTypes);
-		const currentComponents = currentArchetype.removeEntity(entityId);
-		if (removedComponents !== null) for (const componentType of changeset.removes) removedComponents.set(componentType, currentComponents.get(componentType));
-		newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
-		entityToArchetype.set(entityId, newArchetype);
-		return newArchetype;
+};
+//#endregion
+//#region src/commands/changeset.ts
+/**
+* @internal Represents a set of component changes to be applied to an entity
+*/
+var ComponentChangeset = class {
+	adds = /* @__PURE__ */ new Map();
+	removes = /* @__PURE__ */ new Set();
+	/**
+	* Add a component to the changeset
+	*/
+	set(componentType, component) {
+		this.adds.set(componentType, component);
+		this.removes.delete(componentType);
 	}
-	if (removedComponents !== null) applySparseChanges(ctx.sparseStore, entityId, changeset, removedComponents);
-	else applySparseChangesNoHooks(ctx.sparseStore, entityId, changeset);
-	for (const [componentType, component] of changeset.adds) {
-		if (isSparseRelation(componentType)) continue;
-		currentArchetype.set(entityId, componentType, component);
+	/**
+	* Remove a component from the changeset
+	*/
+	delete(componentType) {
+		this.removes.add(componentType);
+		this.adds.delete(componentType);
 	}
-	return currentArchetype;
-}
-function applySparseChanges(sparseStore, entityId, changeset, removedComponents) {
-	for (const componentType of changeset.removes) if (isSparseRelation(componentType)) {
-		const removedValue = sparseStore.getValue(entityId, componentType);
-		if (removedValue !== void 0 || sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)) removedComponents.set(componentType, removedValue);
-		sparseStore.deleteValue(entityId, componentType);
+	/**
+	* Check if the changeset has any changes
+	*/
+	hasChanges() {
+		return this.adds.size > 0 || this.removes.size > 0;
 	}
-	for (const [componentType, component] of changeset.adds) if (isSparseRelation(componentType)) sparseStore.setValue(entityId, componentType, component);
-}
-function applySparseChangesNoHooks(sparseStore, entityId, changeset) {
-	for (const componentType of changeset.removes) if (isSparseRelation(componentType)) sparseStore.deleteValue(entityId, componentType);
-	for (const [componentType, component] of changeset.adds) if (isSparseRelation(componentType)) sparseStore.setValue(entityId, componentType, component);
-}
-function filterRegularComponentTypes(componentTypes) {
-	const regularTypes = [];
-	for (const componentType of componentTypes) {
-		if (isSparseWildcard(componentType)) {
-			regularTypes.push(componentType);
-			continue;
+	/**
+	* Clear all changes
+	*/
+	clear() {
+		this.adds.clear();
+		this.removes.clear();
+	}
+	/**
+	* Merge another changeset into this one
+	*/
+	merge(other) {
+		for (const [componentType, component] of other.adds) {
+			this.adds.set(componentType, component);
+			this.removes.delete(componentType);
+		}
+		for (const componentType of other.removes) {
+			this.removes.add(componentType);
+			this.adds.delete(componentType);
 		}
-		if (isSparseRelation(componentType)) continue;
-		regularTypes.push(componentType);
 	}
-	return regularTypes;
-}
+	/**
+	* Apply the changeset to existing components and return the final state
+	*/
+	applyTo(existingComponents) {
+		for (const componentType of this.removes) existingComponents.delete(componentType);
+		for (const [componentType, component] of this.adds) existingComponents.set(componentType, component);
+		return existingComponents;
+	}
+};
 //#endregion
 //#region src/world/hooks.ts
 /**
@@ -2310,8 +2512,282 @@ function untrackEntityReference(entityReferences, sourceEntityId, componentType,
 *
 * @internal
 */
-function getEntityReferences(entityReferences, targetEntityId) {
-	return entityReferences.get(targetEntityId) ?? new MultiMap();
+function getEntityReferences(entityReferences, targetEntityId) {
+	return entityReferences.get(targetEntityId) ?? new MultiMap();
+}
+//#endregion
+//#region src/world/command-executor.ts
+/**
+* Encapsulates the command execution pipeline, reusable changesets,
+* and related orchestration that was previously private methods + fields on World.
+*
+* Responsibilities:
+* - executeEntityCommands (routing for singletons / destroy / structural changes)
+* - applyEntityCommands (changeset processing + exclusive relations + apply + refs + hooks)
+* - removeComponentImmediate (used by cascade deletion)
+* - updateEntityReferences (keeps the reverse index in sync)
+*
+* This extraction significantly reduces World line count while preserving
+* every fast-path branch and allocation-avoidance characteristic.
+*/
+var CommandExecutor = class {
+	ctx;
+	_changeset = new ComponentChangeset();
+	_removeChangeset = new ComponentChangeset();
+	_commandCtx;
+	_hooksCtx;
+	constructor(ctx) {
+		this.ctx = ctx;
+		this._commandCtx = {
+			sparseStore: ctx.sparseStore,
+			ensureArchetype: ctx.ensureArchetype
+		};
+		this._hooksCtx = {
+			multiHooks: ctx.hooks,
+			has: ctx.has,
+			get: ctx.get,
+			getOptional: ctx.getOptional
+		};
+	}
+	/**
+	* Entry point used by the CommandBuffer.
+	* Routes to singleton handling, destroy fast path, or structural apply.
+	*/
+	executeEntityCommands(entityId, commands) {
+		this._changeset.clear();
+		if (this.ctx.componentEntities.exists(entityId)) {
+			this.ctx.componentEntities.executeCommands(entityId, commands);
+			return;
+		}
+		if (commands.some((cmd) => cmd.type === "destroy")) {
+			this.ctx.destroyEntityImmediate(entityId);
+			return;
+		}
+		this.applyEntityCommands(entityId, commands);
+	}
+	applyEntityCommands(entityId, commands) {
+		const currentArchetype = this.ctx.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.ctx.hooks.size === 0) {
+			const newArchetype = applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.ctx.entityToArchetype, null);
+			if (hasStructuralChange) this.updateEntityReferences(entityId, changeset);
+			if (newArchetype !== currentArchetype) this.ctx.incrementMigrations();
+			return;
+		}
+		const removedComponents = /* @__PURE__ */ new Map();
+		const newArchetype = applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.ctx.entityToArchetype, removedComponents);
+		if (hasStructuralChange) this.updateEntityReferences(entityId, changeset);
+		if (newArchetype !== currentArchetype) this.ctx.incrementMigrations();
+		this.ctx.triggerLifecycleHooks(this._hooksCtx, entityId, changeset.adds, removedComponents, currentArchetype, newArchetype);
+	}
+	/**
+	* Immediate (non-buffered) component removal used during cascade deletion.
+	* Called from destroy* paths (which remain in World).
+	*/
+	removeComponentImmediate(entityId, componentType, targetEntityId) {
+		const sourceArchetype = this.ctx.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.ctx.entityToArchetype, null);
+		untrackEntityReference(this.ctx.entityReferences, entityId, componentType, targetEntityId);
+		this.ctx.triggerLifecycleHooks(this._hooksCtx, entityId, /* @__PURE__ */ new Map(), new Map([[componentType, removedComponent]]), sourceArchetype, newArchetype);
+	}
+	/**
+	* Keeps the entity reference reverse index in sync after structural changes.
+	* Called from apply paths.
+	*/
+	updateEntityReferences(entityId, changeset) {
+		for (const componentType of changeset.removes) if (isEntityRelation(componentType)) {
+			const targetId = getTargetIdFromRelationId(componentType);
+			untrackEntityReference(this.ctx.entityReferences, entityId, componentType, targetId);
+		} else if (componentType >= 1024) untrackEntityReference(this.ctx.entityReferences, entityId, componentType, componentType);
+		for (const [componentType] of changeset.adds) if (isEntityRelation(componentType)) {
+			const targetId = getTargetIdFromRelationId(componentType);
+			trackEntityReference(this.ctx.entityReferences, entityId, componentType, targetId);
+		} else if (componentType >= 1024) trackEntityReference(this.ctx.entityReferences, entityId, componentType, componentType);
+	}
+	/**
+	* Exposed for any future direct needs (currently not required outside the executor).
+	*/
+	getHooksContext() {
+		return this._hooksCtx;
+	}
+};
+//#endregion
+//#region src/world/debug-stats.ts
+/**
+* Manages debug stats collectors and transient activity counters for World#sync().
+*
+* Extracted from World to shrink the main class while keeping the entire debug/observability
+* path isolated, zero-cost when no collectors are active, and easy to test/maintain.
+*
+* Follows the same context/callback injection style as ArchetypeManager, CommandProcessorContext,
+* and HooksContext to avoid tight coupling.
+*
+* All collectors receive the *exact same* stats object for a given sync (as before).
+* Exceptions in user callbacks are swallowed (as before).
+*/
+var DebugStatsManager = class {
+	collectors = /* @__PURE__ */ new Set();
+	migrations = 0;
+	archetypesCreated = 0;
+	archetypesRemoved = 0;
+	/** Fast check used to arm timing + reset + counting in hot paths. */
+	hasActiveCollectors() {
+		return this.collectors.size > 0;
+	}
+	/**
+	* Registers a collector. Returns a disposable handle (supports `using`).
+	* Collection stops when the handle is disposed.
+	*/
+	createCollector(callback) {
+		this.collectors.add(callback);
+		return { [Symbol.dispose]: () => {
+			this.collectors.delete(callback);
+		} };
+	}
+	recordArchetypeCreated() {
+		if (this.hasActiveCollectors()) this.archetypesCreated++;
+	}
+	recordArchetypeRemoved() {
+		if (this.hasActiveCollectors()) this.archetypesRemoved++;
+	}
+	incrementMigrations() {
+		if (this.hasActiveCollectors()) this.migrations++;
+	}
+	/** Reset all activity counters + the shared hook execution counter. Called at start of an armed sync. */
+	resetActivity() {
+		this.migrations = 0;
+		this.archetypesCreated = 0;
+		this.archetypesRemoved = 0;
+		debugHookExecutionCounter.value = 0;
+	}
+	/**
+	* Build and deliver a SyncDebugStats payload to every active collector.
+	* World supplies the pre-computed snapshot numbers (keeps debug manager decoupled from
+	* internal World maps/registries while preserving exact original stats shape and values).
+	*/
+	deliver(timings, data) {
+		const stats = {
+			timestamps: {
+				syncStart: timings.syncStart,
+				syncEnd: timings.syncEnd,
+				commandBufferStart: timings.commandBufferStart,
+				commandBufferEnd: timings.commandBufferEnd
+			},
+			commandIterations: timings.commandIterations,
+			entities: {
+				total: data.entityCount,
+				freelistSize: data.freelistSize,
+				nextId: data.nextId
+			},
+			archetypes: {
+				total: data.archetypeCount,
+				empty: data.emptyArchetypes
+			},
+			queries: {
+				cached: data.cachedQueryCount,
+				registered: data.registeredQueryCount
+			},
+			hooks: { total: data.hookCount },
+			indices: {
+				entityReferences: data.entityReferencesSize,
+				entityToReferencingArchetypes: data.entityToReferencingArchetypesSize,
+				archetypesByComponent: data.archetypesByComponentSize
+			},
+			activity: {
+				migrations: this.migrations,
+				hooksExecuted: debugHookExecutionCounter.value,
+				archetypesCreated: this.archetypesCreated,
+				archetypesRemoved: this.archetypesRemoved
+			}
+		};
+		for (const cb of this.collectors) try {
+			cb(stats);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/world/operations.ts
+/**
+* Validation and overload-resolution helpers extracted from World.
+*
+* These were previously private methods on World. Moving them reduces line count
+* in the core class with almost zero coupling (the only dep is a liveness predicate
+* for assertEntityExists, supplied by the caller).
+*
+* Pure type checks (assert*TypeValid) and the resolve* helpers for set/remove
+* overloads live here.
+*/
+/**
+* Assert that an entity (or component-entity) is alive in the world.
+* The caller supplies the liveness check (World.exists or equivalent) to keep
+* this module free of direct references to stores.
+*/
+function assertEntityExists(entityId, label, exists) {
+	if (!exists(entityId)) throw new Error(`${label} ${entityId} does not exist`);
+}
+function assertComponentTypeValid(componentType) {
+	if (getDetailedIdType(componentType).type === "invalid") throw new Error(`Invalid component type: ${componentType}`);
+}
+function assertSetComponentTypeValid(componentType) {
+	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}`);
+}
+/**
+* Resolve the (entity, componentType, value) for a set() call.
+*/
+function resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, argCount = 3, exists = () => true) {
+	const targetEntityId = entityId;
+	if (argCount === 2 && isComponentId(targetEntityId) && typeof componentTypeOrComponent !== "number") {
+		assertEntityExists(targetEntityId, "Component entity", exists);
+		return {
+			entityId: targetEntityId,
+			componentType: targetEntityId,
+			component: componentTypeOrComponent,
+			deprecatedSingletonShorthand: true
+		};
+	}
+	const componentType = componentTypeOrComponent;
+	assertEntityExists(targetEntityId, "Entity", exists);
+	assertSetComponentTypeValid(componentType);
+	return {
+		entityId: targetEntityId,
+		componentType,
+		component: maybeComponent,
+		deprecatedSingletonShorthand: false
+	};
+}
+/**
+* Resolve the (entity, componentType) for a remove() call, handling the
+* singleton component overload (remove(componentId)).
+*/
+function resolveRemoveOperation(entityId, componentType, exists = () => true) {
+	if (componentType === void 0) {
+		const componentId = entityId;
+		assertEntityExists(componentId, "Component entity", exists);
+		return {
+			entityId: componentId,
+			componentType: componentId
+		};
+	}
+	const targetEntityId = entityId;
+	assertEntityExists(targetEntityId, "Entity", exists);
+	assertComponentTypeValid(componentType);
+	return {
+		entityId: targetEntityId,
+		componentType
+	};
 }
 //#endregion
 //#region src/storage/serialization.ts
@@ -2479,51 +2955,63 @@ function deserializeWorld(ctx, snapshot) {
 * World class for ECS architecture
 * Manages entities and components
 */
-var World = class {
+var World = class World {
+	static DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING = "world.set(componentId, value) for singleton components is deprecated; use world.singleton(componentId).set(value) or world.set(componentId, componentId, value) instead.";
 	entityIdManager = new EntityIdManager();
-	archetypes = [];
-	archetypeBySignature = /* @__PURE__ */ new Map();
-	entityToArchetype = /* @__PURE__ */ new Map();
-	archetypesByComponent = /* @__PURE__ */ new Map();
 	entityReferences = /* @__PURE__ */ new Map();
-	/** Reverse index: entity ID → set of archetypes whose componentTypes include that entity ID */
-	entityToReferencingArchetypes = /* @__PURE__ */ new Map();
 	/** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
 	sparseStore = new SparseStoreImpl();
 	/** Component entity (singleton) storage */
 	componentEntities = new ComponentEntityStore();
+	archetypeManager;
+	get archetypes() {
+		return this.archetypeManager.archetypes;
+	}
+	get entityToArchetype() {
+		return this.archetypeManager.entityToArchetype;
+	}
+	get archetypesByComponent() {
+		return this.archetypeManager.archetypesByComponent;
+	}
+	get entityToReferencingArchetypes() {
+		return this.archetypeManager.entityToReferencingArchetypes;
+	}
 	queryRegistry = new QueryRegistry();
 	hooks = /* @__PURE__ */ new Set();
-	_debugCollectors = /* @__PURE__ */ new Set();
-	_debugMigrations = 0;
-	_debugArchetypesCreated = 0;
-	_debugArchetypesRemoved = 0;
-	commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
-	_changeset = new ComponentChangeset();
-	_removeChangeset = new ComponentChangeset();
-	/** Cached command processor context to avoid per-entity object allocation */
-	_commandCtx = {
-		sparseStore: this.sparseStore,
-		ensureArchetype: (ct) => this.ensureArchetype(ct)
-	};
-	/** Cached hooks context to avoid per-entity object allocation */
-	_hooksCtx = {
-		multiHooks: this.hooks,
-		has: (eid, ct) => this.has(eid, ct),
-		get: (eid, ct) => this.get(eid, ct),
-		getOptional: (eid, ct) => this.getOptional(eid, ct)
-	};
+	debugStats = new DebugStatsManager();
+	commandBuffer;
+	commandExecutor;
 	constructor(snapshot) {
+		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({
 			entityIdManager: this.entityIdManager,
 			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);
-	}
-	createArchetypeSignature(componentTypes) {
-		return componentTypes.join(",");
+		const execCtx = {
+			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));
 	}
 	/**
 	* Creates a new entity.
@@ -2619,64 +3107,13 @@ var World = class {
 		if (this.componentEntities.exists(entityId)) return true;
 		return this.entityToArchetype.has(entityId);
 	}
-	assertEntityExists(entityId, label) {
-		if (!this.exists(entityId)) throw new Error(`${label} ${entityId} does not exist`);
-	}
-	assertComponentTypeValid(componentType) {
-		if (getDetailedIdType(componentType).type === "invalid") throw new Error(`Invalid component type: ${componentType}`);
-	}
-	assertSetComponentTypeValid(componentType) {
-		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}`);
-	}
-	resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent) {
-		if (maybeComponent === void 0 && componentTypeOrComponent !== void 0) {
-			const detailedType = getDetailedIdType(entityId);
-			if (detailedType.type === "component" || detailedType.type === "component-relation") {
-				const componentId = entityId;
-				this.assertEntityExists(componentId, "Component entity");
-				this.assertSetComponentTypeValid(componentId);
-				return {
-					entityId: componentId,
-					componentType: componentId,
-					component: componentTypeOrComponent
-				};
-			}
-		}
-		const targetEntityId = entityId;
-		const componentType = componentTypeOrComponent;
-		this.assertEntityExists(targetEntityId, "Entity");
-		this.assertSetComponentTypeValid(componentType);
-		return {
-			entityId: targetEntityId,
-			componentType,
-			component: maybeComponent
-		};
-	}
-	resolveRemoveOperation(entityId, componentType) {
-		if (componentType === void 0) {
-			const componentId = entityId;
-			this.assertEntityExists(componentId, "Component entity");
-			return {
-				entityId: componentId,
-				componentType: componentId
-			};
-		}
-		const targetEntityId = entityId;
-		this.assertEntityExists(targetEntityId, "Entity");
-		this.assertComponentTypeValid(componentType);
-		return {
-			entityId: targetEntityId,
-			componentType
-		};
-	}
 	set(entityId, componentTypeOrComponent, maybeComponent) {
-		const { entityId: targetEntityId, componentType, component } = this.resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent);
+		const { entityId: targetEntityId, componentType, component, deprecatedSingletonShorthand } = resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, arguments.length, (id) => this.exists(id));
+		if (deprecatedSingletonShorthand) console.warn(World.DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING);
 		this.commandBuffer.set(targetEntityId, componentType, component);
 	}
 	remove(entityId, componentType) {
-		const { entityId: targetEntityId, componentType: targetComponentType } = this.resolveRemoveOperation(entityId, componentType);
+		const { entityId: targetEntityId, componentType: targetComponentType } = resolveRemoveOperation(entityId, componentType, (id) => this.exists(id));
 		this.commandBuffer.remove(targetEntityId, targetComponentType);
 	}
 	/**
@@ -2693,6 +3130,30 @@ var World = class {
 	delete(entityId) {
 		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(componentId) {
+		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, value);
+			}
+		});
+	}
 	has(entityId, componentType) {
 		if (componentType === void 0) {
 			const componentId = entityId;
@@ -2763,7 +3224,7 @@ var World = class {
 	* // world.getChildren(parent, ChildOf), world.getParent(child, ChildOf)
 	*/
 	getRelationTargets(entityId, relationComp) {
-		this.assertEntityExists(entityId, "Entity");
+		assertEntityExists(entityId, "Entity", (id) => this.exists(id));
 		const wildcard = relation(relationComp, "*");
 		if (this.componentEntities.exists(entityId)) return this.componentEntities.getWildcard(entityId, wildcard);
 		return this.get(entityId, wildcard);
@@ -2793,7 +3254,7 @@ var World = class {
 	* given base component.
 	*/
 	hasRelation(entityId, relationComp, targetId) {
-		this.assertEntityExists(entityId, "Entity");
+		assertEntityExists(entityId, "Entity", (id) => this.exists(id));
 		if (targetId !== void 0) {
 			const specific = relation(relationComp, targetId);
 			return this.has(entityId, specific);
@@ -2804,7 +3265,7 @@ var World = class {
 	* Returns the number of relations of the given base component held by the entity.
 	*/
 	countRelations(entityId, relationComp) {
-		this.assertEntityExists(entityId, "Entity");
+		assertEntityExists(entityId, "Entity", (id) => this.exists(id));
 		return this.getRelationTargets(entityId, relationComp).length;
 	}
 	/**
@@ -2951,60 +3412,7 @@ var World = class {
 	* This is intended for development/debugging and leak detection.
 	*/
 	createDebugStatsCollector(callback) {
-		this._debugCollectors.add(callback);
-		return { [Symbol.dispose]: () => {
-			this._debugCollectors.delete(callback);
-		} };
-	}
-	_resetDebugActivityCounters() {
-		this._debugMigrations = 0;
-		this._debugArchetypesCreated = 0;
-		this._debugArchetypesRemoved = 0;
-		debugHookExecutionCounter.value = 0;
-	}
-	_deliverDebugStats(timings) {
-		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 = {
-			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.cache?.size ?? 0,
-				registered: this.queryRegistry.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 {}
+		return this.debugStats.createCollector(callback);
 	}
 	/**
 	* Synchronizes all buffered commands (set/remove/delete) to the world.
@@ -3017,19 +3425,39 @@ var World = class {
 	* world.sync(); // Apply all buffered changes
 	*/
 	sync() {
-		const hasCollectors = this._debugCollectors.size > 0;
-		const syncStart = hasCollectors ? performance.now() : 0;
-		if (hasCollectors) this._resetDebugActivityCounters();
-		const commandBufferStart = hasCollectors ? performance.now() : 0;
+		if (!this.debugStats.hasActiveCollectors()) {
+			this.commandBuffer.execute();
+			return;
+		}
+		const syncStart = performance.now();
+		this.debugStats.resetActivity();
+		const commandBufferStart = performance.now();
 		const commandIterations = this.commandBuffer.execute();
-		const commandBufferEnd = hasCollectors ? performance.now() : 0;
-		const syncEnd = hasCollectors ? performance.now() : 0;
-		if (hasCollectors) this._deliverDebugStats({
+		const commandBufferEnd = performance.now();
+		const syncEnd = performance.now();
+		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.cache?.size ?? 0,
+			registeredQueryCount: this.queryRegistry.queries?.size ?? 0,
+			hookCount: this.hooks.size,
+			entityReferencesSize: this.entityReferences.size,
+			entityToReferencingArchetypesSize: this.entityToReferencingArchetypes.size
 		});
 	}
 	/**
@@ -3066,7 +3494,7 @@ var World = class {
 	createQuery(componentTypes, filter = {}) {
 		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);
 	}
 	/**
@@ -3132,44 +3560,7 @@ var World = class {
 	* @internal
 	*/
 	getMatchingArchetypes(componentTypes) {
-		if (componentTypes.length === 0) return [...this.archetypes];
-		const regularComponents = [];
-		const wildcardRelations = [];
-		for (const componentType of componentTypes) if (isWildcardRelationId(componentType)) {
-			const componentId = getComponentIdFromRelationId(componentType);
-			if (componentId !== void 0) 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;
-	}
-	getArchetypesWithComponents(componentTypes) {
-		if (componentTypes.length === 0) return [...this.archetypes];
-		if (componentTypes.length === 1) {
-			const set = this.archetypesByComponent.get(componentTypes[0]);
-			return set ? Array.from(set) : [];
-		}
-		const sets = componentTypes.map((type) => this.archetypesByComponent.get(type)).filter((s) => s !== void 0 && s.size > 0).sort((a, b) => a.size - b.size);
-		if (sets.length === 0) return [];
-		if (sets.length < componentTypes.length) return [];
-		const smallest = sets[0];
-		if (sets.length === 2) {
-			const other = sets[1];
-			return Array.from(smallest).filter((a) => other.has(a));
-		}
-		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);
 	}
 	query(componentTypes, includeComponents) {
 		const matchingArchetypes = this.getMatchingArchetypes(componentTypes);
@@ -3183,154 +3574,14 @@ var World = class {
 			return result;
 		}
 	}
-	executeEntityCommands(entityId, commands) {
-		this._changeset.clear();
-		if (this.componentEntities.exists(entityId)) {
-			this.componentEntities.executeCommands(entityId, commands);
-			return;
-		}
-		if (commands.some((cmd) => cmd.type === "destroy")) {
-			this.destroyEntityImmediate(entityId);
-			return;
-		}
-		this.applyEntityCommands(entityId, commands);
-	}
-	applyEntityCommands(entityId, commands) {
-		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) {
-			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 = /* @__PURE__ */ new Map();
-		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);
-	}
-	createHooksContext() {
-		return this._hooksCtx;
-	}
-	removeComponentImmediate(entityId, componentType, targetEntityId) {
-		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, /* @__PURE__ */ new Map(), new Map([[componentType, removedComponent]]), sourceArchetype, newArchetype);
-	}
-	updateEntityReferences(entityId, changeset) {
-		for (const componentType of changeset.removes) if (isEntityRelation(componentType)) {
-			const targetId = getTargetIdFromRelationId(componentType);
-			untrackEntityReference(this.entityReferences, entityId, componentType, targetId);
-		} else if (componentType >= 1024) 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 >= 1024) trackEntityReference(this.entityReferences, entityId, componentType, componentType);
-	}
 	ensureArchetype(componentTypes) {
-		const sortedTypes = normalizeComponentTypes(filterRegularComponentTypes(componentTypes));
-		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 */
-	addToReferencingIndex(componentType, archetype) {
-		const detailedType = getDetailedIdType(componentType);
-		let entityId;
-		if (detailedType.type === "entity") entityId = componentType;
-		else if (detailedType.type === "entity-relation") entityId = detailedType.targetId;
-		if (entityId !== void 0) {
-			let refs = this.entityToReferencingArchetypes.get(entityId);
-			if (!refs) {
-				refs = /* @__PURE__ */ new Set();
-				this.entityToReferencingArchetypes.set(entityId, refs);
-			}
-			refs.add(archetype);
-		}
-	}
-	/** Remove componentType from the reverse index */
-	removeFromReferencingIndex(componentType, archetype) {
-		const detailedType = getDetailedIdType(componentType);
-		let entityId;
-		if (detailedType.type === "entity") entityId = componentType;
-		else if (detailedType.type === "entity-relation") entityId = detailedType.targetId;
-		if (entityId !== void 0) {
-			const refs = this.entityToReferencingArchetypes.get(entityId);
-			if (refs) {
-				refs.delete(archetype);
-				if (refs.size === 0) this.entityToReferencingArchetypes.delete(entityId);
-			}
-		}
-	}
-	createNewArchetype(componentTypes) {
-		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 = /* @__PURE__ */ new Set();
-				this.archetypesByComponent.set(componentType, archetypes);
-			}
-			archetypes.add(newArchetype);
-			this.addToReferencingIndex(componentType, newArchetype);
-		}
-		this.queryRegistry.onNewArchetype(newArchetype);
-		this.updateArchetypeHookMatches(newArchetype);
-		return newArchetype;
-	}
-	updateArchetypeHookMatches(archetype) {
-		for (const entry of this.hooks) if (this.archetypeMatchesHook(archetype, entry)) {
-			archetype.matchingMultiHooks.add(entry);
-			if (entry.matchedArchetypes) entry.matchedArchetypes.add(archetype);
-		}
-	}
-	archetypeMatchesHook(archetype, entry) {
-		return entry.requiredComponents.every((c) => {
-			if (isWildcardRelationId(c)) {
-				if (isSparseWildcard(c)) return true;
-				const componentId = getComponentIdFromRelationId(c);
-				return componentId !== void 0 && archetype.hasRelationWithComponentId(componentId);
-			}
-			return archetype.componentTypeSet.has(c) || isSparseRelation(c);
-		}) && matchesFilter(archetype, entry.filter);
+		return this.archetypeManager.ensureArchetype(componentTypes);
 	}
 	cleanupArchetypesReferencingEntity(entityId) {
-		const refs = this.entityToReferencingArchetypes.get(entityId);
-		if (!refs) return;
-		for (const archetype of refs) if (archetype.getEntities().length === 0) this.removeArchetype(archetype);
-		this.entityToReferencingArchetypes.delete(entityId);
+		this.archetypeManager.cleanupArchetypesReferencingEntity(entityId);
 	}
-	removeArchetype(archetype) {
-		const index = this.archetypes.indexOf(archetype);
-		if (index !== -1) {
-			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);
-			}
-			this.removeFromReferencingIndex(componentType, archetype);
-		}
-		this.queryRegistry.onArchetypeRemoved(archetype);
+	archetypeMatchesHook(archetype, entry) {
+		return this.archetypeManager.archetypeMatchesHook(archetype, entry);
 	}
 	/**
 	* Serializes the entire world state to a plain JavaScript object.
@@ -3353,11 +3604,22 @@ var World = class {
 	* const savedData = JSON.parse(localStorage.getItem('save'));
 	* const newWorld = new World(savedData);
 	*/
+	removeComponentImmediate(entityId, componentType, targetEntityId) {
+		this.commandExecutor.removeComponentImmediate(entityId, componentType, targetEntityId);
+	}
+	createHooksContext() {
+		return this.commandExecutor.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() {
-		return serializeWorld(this.archetypes, this.componentEntities, this.entityIdManager);
+		return serializeWorld(this.archetypeManager.archetypes, this.componentEntities, this.entityIdManager);
 	}
 };
 //#endregion
-export { getComponentIdByName as a, isSparseRelation as c, isWildcardRelationId as d, relation as f, isRelationId as h, component as i, isSparseWildcard as l, isEntityId as m, Query as n, getComponentNameById as o, isComponentId as p, EntityBuilder as r, isSparseComponent as s, World as t, decodeRelationId as u };
+export { component as a, isSparseComponent as c, decodeRelationId as d, isWildcardRelationId as f, isRelationId as g, isEntityId as h, EntityBuilder as i, isSparseRelation as l, isComponentId as m, Query as n, getComponentIdByName as o, relation as p, SingletonHandle as r, getComponentNameById as s, World as t, isSparseWildcard as u };
 
 //# sourceMappingURL=world.mjs.map