@codehz/ecs 0.8.2 → 0.10.0

package/dist/world.mjs

@@ -366,7 +366,7 @@ const ComponentIdForNames = /* @__PURE__ */ new Map();
 const componentNames = new Array(COMPONENT_ID_MAX + 1);
 const exclusiveFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const cascadeDeleteFlags = new BitSet(COMPONENT_ID_MAX + 1);
-const dontFragmentFlags = new BitSet(COMPONENT_ID_MAX + 1);
+const sparseFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const componentMerges = new Array(COMPONENT_ID_MAX + 1);
 /**
 * Allocate a new component ID from the global allocator.
@@ -399,7 +399,7 @@ function component(nameOrOptions) {
 	if (options) {
 		if (options.exclusive) exclusiveFlags.set(id);
 		if (options.cascadeDelete) cascadeDeleteFlags.set(id);
-		if (options.dontFragment) dontFragmentFlags.set(id);
+		if (options.sparse || options.dontFragment) sparseFlags.set(id);
 		if (options.merge) componentMerges[id] = options.merge;
 	}
 	return id;
@@ -468,20 +468,21 @@ function isExclusiveComponent(id) {
 	return exclusiveFlags.has(id);
 }
 /**
-* Check if a component is marked as `dontFragment`.
+* Check if a component is marked as `sparse` (sparse storage for relations).
 *
-* When a component has `dontFragment: true`, relations using it do not cause
-* archetype fragmentation — entities with different relation targets can share
-* the same archetype. This is a fast O(1) bitset lookup.
+* When a component has `sparse: true`, relations using it do not cause archetype
+* fragmentation — entities with different relation targets can share the same
+* archetype. This is a fast O(1) bitset lookup. The legacy `dontFragment` key
+* is still accepted and sets the same internal flag.
 *
 * @param id - The component ID to check.
-* @returns `true` if the component was created with `dontFragment: true`.
+* @returns `true` if the component was created with `sparse: true` (or the
+*   legacy `dontFragment: true`).
 *
-* @see {@link ComponentOptions.dontFragment} for the full explanation of how
-*   `dontFragment` prevents archetype fragmentation.
+* @see {@link ComponentOptions.sparse} for the full explanation of sparse storage.
 */
-function isDontFragmentComponent(id) {
-	return dontFragmentFlags.has(id);
+function isSparseComponent(id) {
+	return sparseFlags.has(id);
 }
 /**
 * Generic optimized function to check whether a relation ID's base component
@@ -491,9 +492,8 @@ function isDontFragmentComponent(id) {
 * ID and checking: (1) the ID is a valid relation, (2) the component ID is in the
 * valid range, (3) the target satisfies the condition, and (4) the flag bit is set.
 *
-* Used as the fast-path implementation for `isDontFragmentRelation`,
-* `isDontFragmentWildcard`, `isExclusiveRelation`, `isExclusiveWildcard`,
-* and `isCascadeDeleteRelation`.
+* Used as the fast-path implementation for `isSparseRelation`, `isSparseWildcard`,
+* `isExclusiveRelation`, `isExclusiveWildcard`, and `isCascadeDeleteRelation`.
 *
 * @param id - The entity/relation ID to check.
 * @param flagBitSet - The bitset tracking which component IDs have the flag.
@@ -509,52 +509,40 @@ function checkRelationFlag(id, flagBitSet, targetCondition) {
 	return isValidComponentId(componentId) && targetCondition(targetId) && flagBitSet.has(componentId);
 }
 /**
-* Check if an ID is a specific (non-wildcard) relation backed by a `dontFragment`
-* component.
+* Check if an ID is a specific (non-wildcard) relation backed by a `sparse`
+* component (i.e. stored in the side sparse store rather than the archetype).
 *
 * This is used in hot paths (archetype resolution, command processing) to determine
-* whether a relation should be excluded from the archetype signature. Relations with
-* `dontFragment` components are stored in the shared {@link DontFragmentStore} instead
-* of being part of the archetype's component type list.
-*
-* This is an optimized function that avoids the overhead of `getDetailedIdType`
-* by directly decoding and checking the relation's component ID against the
-* `dontFragment` bitset.
+* whether a relation should be excluded from the archetype signature.
 *
 * @param id - The entity/relation ID to check (must be a relation ID, not a plain
 *   component ID).
 * @returns `true` if this is a specific-target relation (not wildcard) whose base
-*   component was created with `dontFragment: true`.
+*   component was created with `sparse: true` (or legacy `dontFragment: true`).
 *
-* @see {@link isDontFragmentWildcard} for the wildcard variant.
-* @see {@link ComponentOptions.dontFragment} for the full explanation.
+* @see {@link isSparseWildcard} for the wildcard variant.
+* @see {@link ComponentOptions.sparse} for the full explanation.
 */
-function isDontFragmentRelation(id) {
-	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== 0);
+function isSparseRelation(id) {
+	return checkRelationFlag(id, sparseFlags, (targetId) => targetId !== 0);
 }
 /**
 * Check if an ID is a wildcard relation (`relation(Comp, "*")`) backed by a
-* `dontFragment` component.
-*
-* Wildcard markers for `dontFragment` components are placed in the archetype
-* component list so that queries can discover archetypes containing entities
-* with that relation type. This function is used in `filterRegularComponentTypes`
-* to **keep** these wildcard markers in the archetype signature while stripping
-* out specific-target `dontFragment` relations.
+* `sparse` component.
 *
-* This is an optimized function that avoids the overhead of `getDetailedIdType`
-* by directly decoding and checking the relation's component ID against the
-* `dontFragment` bitset.
+* Wildcard markers for sparse components are placed in the archetype component
+* list so that queries can discover archetypes containing entities with that
+* relation type.
 *
 * @param id - The entity/relation ID to check.
 * @returns `true` if this is a wildcard relation (`"*"` target) whose base
-*   component was created with `dontFragment: true`.
+*   component was created with `sparse: true` (or legacy `dontFragment: true`).
 *
-* @see {@link isDontFragmentRelation} for the specific-target variant.
-* @see {@link ComponentOptions.dontFragment} for the full explanation.
+* @see {@link isSparseRelation} for the specific-target variant.
+* @see {@link ComponentOptions.sparse} for the full explanation.
 */
-function isDontFragmentWildcard(id) {
-	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === 0);
+function isSparseWildcard(id) {
+	return checkRelationFlag(id, sparseFlags, (targetId) => targetId === 0);
 }
 /**
 * Check if a relation ID is a cascade delete entity-relation.
@@ -634,497 +622,125 @@ 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
-/**
-* Utility functions for ECS library
-*/
+//#region src/world/singleton.ts
 /**
-* 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 provides an explicit and concise API for singleton components without
+* overloading `world.set()` semantics.
+*
+* @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;
-}
-//#endregion
-//#region src/archetype/helpers.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
-*/
-function hasWildcardRelation(components, wildcardComponentId) {
-	for (const relId of components.keys()) if (isRelationId(relId)) {
-		if (getComponentIdFromRelationId(relId) === wildcardComponentId) return true;
+	has() {
+		return this.ops.has();
 	}
-	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.
-* Now receives the DontFragmentStore directly for efficient per-component lookups.
-*/
-function buildWildcardRelationValue(wildcardRelationType, matchingRelations, getDataAtIndex, dontFragmentStore, 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]);
+	get() {
+		return this.ops.get();
 	}
-	if (targetComponentId !== void 0) {
-		const dfMatches = dontFragmentStore.getRelationsForComponent(entityId, targetComponentId);
-		for (const m of dfMatches) relations.push(m);
+	getOptional() {
+		return this.ops.getOptional();
 	}
-	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;
+	remove() {
+		this.ops.remove();
 	}
-	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`);
+	set(...args) {
+		this.ops.set(args[0]);
 	}
-	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, dontFragmentRelations) {
-	const optional = isOptionalEntityId(compType);
-	const actualType = optional ? compType.optional : compType;
-	if (getIdType(actualType) === "wildcard-relation") return buildWildcardRelationValue(actualType, dataSource, (relType) => getComponentData(relType)[entityIndex], dontFragmentRelations, entityId, optional);
-	else return buildRegularComponentValue(dataSource, entityIndex, optional);
-}
+};
 //#endregion
-//#region src/archetype/archetype.ts
-/**
-* Special value to represent missing component data
-*/
-const MISSING_COMPONENT = Symbol("missing component");
+//#region src/archetype/store.ts
 /**
-* Archetype class for ECS architecture
-* Represents a group of entities that share the same set of components
-* Optimized for fast iteration and component access
+* 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 Archetype = class {
-	/**
-	* The component types that define this archetype
-	*/
-	componentTypes;
-	/**
-	* Set version of componentTypes for O(1) lookups in hot paths
-	*/
-	componentTypeSet;
-	/**
-	* List of entities in this archetype
-	*/
-	entities = [];
-	/**
-	* Component data storage - maps component type to array of component data
-	* Each array index corresponds to the entity index in the entities array
-	*/
-	componentData = /* @__PURE__ */ new Map();
-	/**
-	* Reverse mapping from entity to its index in this archetype
-	*/
-	entityToIndex = /* @__PURE__ */ new Map();
-	/**
-	* DontFragmentStore (keyed primarily by relation ComponentId).
-	* Uses optimized RelationEntry (single/multi) for the common exclusive case.
-	* See store.ts for implementation details.
-	*/
-	dontFragmentRelations;
-	/**
-	* Multi-hooks that match this archetype
-	*/
-	matchingMultiHooks = /* @__PURE__ */ new Set();
+var SparseStoreImpl = class {
 	/**
-	* Cache for pre-computed component data sources to avoid repeated calculations
+	* Primary storage, keyed by the base relation component ID.
 	*/
-	componentDataSourcesCache = /* @__PURE__ */ new Map();
-	constructor(componentTypes, dontFragmentRelations) {
-		this.componentTypes = normalizeComponentTypes(componentTypes);
-		this.componentTypeSet = new Set(this.componentTypes);
-		this.dontFragmentRelations = dontFragmentRelations;
-		for (const componentType of this.componentTypes) this.componentData.set(componentType, []);
-	}
-	get size() {
-		return this.entities.length;
-	}
+	byComponent = /* @__PURE__ */ new Map();
 	/**
-	* Check if the given component types match this archetype
-	* @param componentTypes - Component types to check (can be in any order)
-	* @returns true if the types match this archetype's component set
-	* @note This method handles unsorted input by internally sorting for comparison
+	* 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.
 	*/
-	matches(componentTypes) {
-		if (this.componentTypes.length !== componentTypes.length) return false;
-		const sortedTypes = normalizeComponentTypes(componentTypes);
-		return this.componentTypes.every((type, index) => type === sortedTypes[index]);
-	}
-	addEntity(entityId, componentData) {
-		if (this.entityToIndex.has(entityId)) throw new Error(`Entity ${entityId} is already in this archetype`);
-		const index = this.entities.length;
-		this.entities.push(entityId);
-		this.entityToIndex.set(entityId, index);
-		for (const componentType of this.componentTypes) {
-			const data = componentData.get(componentType);
-			this.getComponentData(componentType).push(!componentData.has(componentType) ? MISSING_COMPONENT : data);
+	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;
 		}
-		this.addDontFragmentRelations(entityId, componentData);
 	}
-	addDontFragmentRelations(entityId, componentData) {
-		for (const [componentType, data] of componentData) {
-			if (this.componentTypeSet.has(componentType)) continue;
-			const detailedType = getDetailedIdType(componentType);
-			if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId)) this.dontFragmentRelations.setValue(entityId, componentType, data);
+	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);
 		}
-	}
-	getEntity(entityId) {
-		const index = this.entityToIndex.get(entityId);
-		if (index === void 0) return void 0;
-		const entityData = /* @__PURE__ */ new Map();
-		for (const componentType of this.componentTypes) {
-			const data = this.getComponentData(componentType)[index];
-			entityData.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
+		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
+			});
 		}
-		const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entityId);
-		for (const [componentType, data] of dontFragmentTuples) entityData.set(componentType, data);
-		return entityData;
-	}
-	/**
-	* Returns all dontFragment relations for the given entity as an array of tuples.
-	* This is a compatibility adapter during the store refactor.
-	*
-	* Prefer the new DontFragmentStore methods when possible.
-	*/
-	getEntityDontFragmentRelations(entityId) {
-		const tuples = this.dontFragmentRelations.getAllForEntity(entityId);
-		if (tuples.length === 0) return void 0;
-		const map = /* @__PURE__ */ new Map();
-		for (const [relType, data] of tuples) map.set(relType, data);
-		return map;
-	}
-	dump() {
-		return this.entities.map((entity, 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 dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entity);
-			for (const [componentType, data] of dontFragmentTuples) components.set(componentType, data);
-			return {
-				entity,
-				components
-			};
-		});
-	}
-	removeEntity(entityId) {
-		const index = this.entityToIndex.get(entityId);
-		if (index === void 0) return void 0;
-		const removedData = /* @__PURE__ */ new Map();
-		for (const componentType of this.componentTypes) removedData.set(componentType, this.getComponentData(componentType)[index]);
-		const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entityId);
-		for (const [componentType, data] of dontFragmentTuples) removedData.set(componentType, data);
-		this.dontFragmentRelations.deleteEntity(entityId);
-		this.entityToIndex.delete(entityId);
-		const lastIndex = this.entities.length - 1;
-		if (index !== lastIndex) {
-			const lastEntity = this.entities[lastIndex];
-			this.entities[index] = lastEntity;
-			this.entityToIndex.set(lastEntity, index);
-			for (const componentType of this.componentTypes) {
-				const dataArray = this.getComponentData(componentType);
-				dataArray[index] = dataArray[lastIndex];
-			}
-		}
-		this.entities.pop();
-		for (const componentType of this.componentTypes) this.getComponentData(componentType).pop();
-		return removedData;
-	}
-	exists(entityId) {
-		return this.entityToIndex.has(entityId);
-	}
-	get(entityId, componentType) {
-		const index = this.entityToIndex.get(entityId);
-		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
-		if (isWildcardRelationId(componentType)) return this.getWildcardRelations(entityId, index, componentType);
-		return this.getRegularComponent(entityId, index, componentType);
-	}
-	getWildcardRelations(entityId, index, componentType) {
-		const componentId = getComponentIdFromRelationId(componentType);
-		const relations = [];
-		for (const relType of this.componentTypes) {
-			const relDetailed = getDetailedIdType(relType);
-			if (isRelationType(relDetailed) && relDetailed.componentId === componentId) {
-				const dataArray = this.getComponentData(relType);
-				if (dataArray && dataArray[index] !== void 0) {
-					const data = dataArray[index];
-					relations.push([relDetailed.targetId, data === MISSING_COMPONENT ? void 0 : data]);
-				}
-			}
-		}
-		if (componentId !== void 0) {
-			const matches = this.dontFragmentRelations.getRelationsForComponent(entityId, componentId);
-			for (const m of matches) relations.push(m);
-		}
-		return relations;
-	}
-	getRegularComponent(entityId, index, componentType) {
-		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.dontFragmentRelations.getValue(entityId, componentType) !== void 0 || this.dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return this.dontFragmentRelations.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.dontFragmentRelations.getValue(entityId, componentType);
-		if (value !== void 0) return { value };
-		if (this.dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return { value: this.dontFragmentRelations.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) && isDontFragmentComponent(detailedType.componentId)) {
-			this.dontFragmentRelations.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.dontFragmentRelations));
-	}
-	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 dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entity);
-			for (const [componentType, data] of dontFragmentTuples) 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.dontFragmentRelations.getRelationsForComponent(entityId, componentId).length > 0) return true;
-		return false;
-	}
-};
-//#endregion
-//#region src/archetype/store.ts
-/**
-* Production implementation of DontFragmentStore.
-*
-* Internal layout (optimized):
-* - byComponent: baseComponentId → (entityId → RelationEntry)
-*   RelationEntry uses a single-value form for the common exclusive case (1 target),
-*   avoiding Map allocation entirely for the vast majority of dontFragment usage.
-* - entityIndex: entityId → Set<baseComponentId>
-*   Lightweight reverse index.
-*/
-var DontFragmentStoreImpl = class {
-	/**
-	* Primary storage, keyed by the base relation component ID.
-	*/
-	byComponent = /* @__PURE__ */ new Map();
-	/**
-	* Reverse index: which base component kinds an entity participates in.
-	* Used only by the infrequent getAllForEntity / deleteEntity paths.
-	*/
-	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 DontFragmentStore");
-		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);
+		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);
@@ -1199,6 +815,14 @@ var DontFragmentStoreImpl = class {
 		}
 		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
@@ -1249,7 +873,8 @@ var CommandBuffer = class {
 		});
 	}
 	/**
-	* Execute all commands and clear the buffer
+	* Execute all commands and clear the buffer.
+	* Returns the number of iterations performed (for debug stats).
 	*/
 	execute() {
 		let iterations = 0;
@@ -1269,6 +894,7 @@ var CommandBuffer = class {
 			for (const [entityId, commands] of entityCommands) this.executeEntityCommands(entityId, commands);
 			entityCommands.clear();
 		}
+		return iterations;
 	}
 	/**
 	* Get current commands (for testing)
@@ -1284,727 +910,1315 @@ var CommandBuffer = class {
 	}
 };
 //#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);
+//#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
+/**
+* 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
+*/
+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
+/**
+* Special value to represent missing component data
+*/
+const MISSING_COMPONENT = Symbol("missing component");
+/**
+* Archetype class for ECS architecture
+* Represents a group of entities that share the same set of components
+* Optimized for fast iteration and component access
+*/
+var Archetype = class {
 	/**
-	* Remove a component from the changeset
+	* The component types that define this archetype
 	*/
-	delete(componentType) {
-		this.removes.add(componentType);
-		this.adds.delete(componentType);
-	}
+	componentTypes;
 	/**
-	* Check if the changeset has any changes
+	* Set version of componentTypes for O(1) lookups in hot paths
 	*/
-	hasChanges() {
-		return this.adds.size > 0 || this.removes.size > 0;
-	}
+	componentTypeSet;
 	/**
-	* Clear all changes
+	* List of entities in this archetype
 	*/
-	clear() {
-		this.adds.clear();
-		this.removes.clear();
-	}
+	entities = [];
 	/**
-	* Merge another changeset into this one
+	* Component data storage - maps component type to array of component data
+	* Each array index corresponds to the entity index in the entities array
 	*/
-	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);
-		}
-	}
+	componentData = /* @__PURE__ */ new Map();
 	/**
-	* Apply the changeset to existing components and return the final state
+	* Reverse mapping from entity to its index in this archetype
 	*/
-	applyTo(existingComponents) {
-		for (const componentType of this.removes) existingComponents.delete(componentType);
-		for (const [componentType, component] of this.adds) existingComponents.set(componentType, component);
-		return existingComponents;
-	}
+	entityToIndex = /* @__PURE__ */ new Map();
 	/**
-	* Get the final component types after applying the changeset
-	* @param existingComponentTypes - The current component types on the entity
-	* @returns The final component types or undefined if no changes
+	* SparseStore used for relations declared with `sparse: true`.
+	* See store.ts for implementation details.
 	*/
-	getFinalComponentTypes(existingComponentTypes) {
-		const finalComponentTypes = new Set(existingComponentTypes);
-		let changed = false;
-		for (const componentType of this.removes) {
-			if (!finalComponentTypes.has(componentType)) {
-				this.removes.delete(componentType);
-				continue;
-			}
-			changed = true;
-			finalComponentTypes.delete(componentType);
-		}
-		for (const componentType of this.adds.keys()) {
-			if (finalComponentTypes.has(componentType)) continue;
-			changed = true;
-			finalComponentTypes.add(componentType);
-		}
-		return changed ? Array.from(finalComponentTypes) : void 0;
-	}
-};
-//#endregion
-//#region src/component/entity-store.ts
-/**
-* Manages component entity (singleton) storage.
-*
-* Component entities use a flat Map-based storage rather than the Archetype-based
-* storage used for regular entities. Their IDs are in the component ID range
-* (or are relation IDs), distinguishing them from regular entity IDs.
-*/
-var ComponentEntityStore = class {
-	componentEntityComponents = /* @__PURE__ */ new Map();
-	relationEntityIdsByTarget = /* @__PURE__ */ new Map();
+	sparseRelations;
 	/**
-	* Check if an entity ID is a component entity type.
-	* Returns true for component IDs, component-relation IDs, and entity-relation IDs —
-	* i.e. anything that is NOT a plain entity or an invalid ID.
+	* Multi-hooks that match this archetype
 	*/
-	exists(entityId) {
-		const detailed = getDetailedIdType(entityId);
-		return detailed.type !== "entity" && detailed.type !== "invalid";
-	}
+	matchingMultiHooks = /* @__PURE__ */ new Set();
 	/**
-	* Check if a component entity has a specific component.
+	* Cache for pre-computed component data sources to avoid repeated calculations
 	*/
-	has(entityId, componentType) {
-		return this.componentEntityComponents.get(entityId)?.has(componentType) ?? false;
+	componentDataSourcesCache = /* @__PURE__ */ new Map();
+	constructor(componentTypes, sparseStore) {
+		this.componentTypes = normalizeComponentTypes(componentTypes);
+		this.componentTypeSet = new Set(this.componentTypes);
+		this.sparseRelations = sparseStore;
+		for (const componentType of this.componentTypes) this.componentData.set(componentType, []);
 	}
-	/**
-	* Check if a singleton component has data — the has(componentId) overload.
-	* In singleton usage the entity ID and the component type are the same value.
-	*/
-	hasSingleton(componentId) {
-		return this.componentEntityComponents.get(componentId)?.has(componentId) ?? false;
+	get size() {
+		return this.entities.length;
 	}
 	/**
-	* Check if a component entity has any wildcard relations matching a component ID.
+	* Check if the given component types match this archetype
+	* @param componentTypes - Component types to check (can be in any order)
+	* @returns true if the types match this archetype's component set
+	* @note This method handles unsorted input by internally sorting for comparison
 	*/
-	hasWildcard(entityId, componentId) {
-		const data = this.componentEntityComponents.get(entityId);
-		if (!data) return false;
-		return hasWildcardRelation(data, componentId);
+	matches(componentTypes) {
+		if (this.componentTypes.length !== componentTypes.length) return false;
+		const sortedTypes = normalizeComponentTypes(componentTypes);
+		return this.componentTypes.every((type, index) => type === sortedTypes[index]);
 	}
-	/**
-	* Get a component value from a component entity.
-	* Throws if the component does not exist.
-	*/
-	get(entityId, componentType) {
-		const data = this.componentEntityComponents.get(entityId);
-		if (!data || !data.has(componentType)) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
-		return data.get(componentType);
+	addEntity(entityId, componentData) {
+		if (this.entityToIndex.has(entityId)) throw new Error(`Entity ${entityId} is already in this archetype`);
+		const index = this.entities.length;
+		this.entities.push(entityId);
+		this.entityToIndex.set(entityId, index);
+		for (const componentType of this.componentTypes) {
+			const data = componentData.get(componentType);
+			this.getComponentData(componentType).push(!componentData.has(componentType) ? MISSING_COMPONENT : data);
+		}
+		this.addSparseRelations(entityId, componentData);
 	}
-	/**
-	* Get an optional component value from a component entity.
-	* Returns undefined if the component does not exist.
-	*/
-	getOptional(entityId, componentType) {
-		const data = this.componentEntityComponents.get(entityId);
-		if (!data || !data.has(componentType)) return void 0;
-		return { value: data.get(componentType) };
+	addSparseRelations(entityId, componentData) {
+		for (const [componentType, data] of componentData) {
+			if (this.componentTypeSet.has(componentType)) continue;
+			const detailedType = getDetailedIdType(componentType);
+			if (isRelationType(detailedType) && isSparseComponent(detailedType.componentId)) this.sparseRelations.setValue(entityId, componentType, data);
+		}
 	}
-	/**
-	* Get all wildcard relations of a given type from a component entity.
-	*/
-	getWildcard(entityId, wildcardComponentType) {
-		const componentId = getComponentIdFromRelationId(wildcardComponentType);
-		const data = this.componentEntityComponents.get(entityId);
-		if (componentId === void 0 || !data) return [];
-		const relations = [];
-		for (const [key, value] of data.entries()) {
-			if (getComponentIdFromRelationId(key) !== componentId) continue;
-			const detailed = getDetailedIdType(key);
-			if (detailed.type === "entity-relation" || detailed.type === "component-relation") relations.push([detailed.targetId, value]);
+	getEntity(entityId) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) return void 0;
+		const entityData = /* @__PURE__ */ new Map();
+		for (const componentType of this.componentTypes) {
+			const data = this.getComponentData(componentType)[index];
+			entityData.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
 		}
-		return relations;
+		const sparseTuples = this.sparseRelations.getAllForEntity(entityId);
+		for (const [componentType, data] of sparseTuples) entityData.set(componentType, data);
+		return entityData;
 	}
 	/**
-	* Clear all data for a component entity.
+	* Returns all sparse-stored relations for the given entity.
+	* Internal helper used by command processing and tests.
 	*/
-	clear(entityId) {
-		if (this.componentEntityComponents.delete(entityId)) this.unregisterRelationEntityId(entityId);
+	getEntitySparseRelations(entityId) {
+		const tuples = this.sparseRelations.getAllForEntity(entityId);
+		if (tuples.length === 0) return void 0;
+		const map = /* @__PURE__ */ new Map();
+		for (const [relType, data] of tuples) map.set(relType, data);
+		return map;
 	}
-	/**
-	* Cleanup all component entities that reference a given target entity.
-	* Called when a target entity is destroyed.
-	*/
-	cleanupReferencesTo(targetId) {
-		const relationEntities = this.relationEntityIdsByTarget.get(targetId);
-		if (!relationEntities) return;
-		for (const relationEntityId of relationEntities) this.componentEntityComponents.delete(relationEntityId);
-		this.relationEntityIdsByTarget.delete(targetId);
+	dump() {
+		return this.entities.map((entity, 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);
+			return {
+				entity,
+				components
+			};
+		});
 	}
 	/**
-	* Execute a batch of commands for a component entity.
+	* @internal Serialization fast-path.
+	*
+	* Appends SerializedEntity records directly from the archetype's column storage
+	* (componentData arrays) plus sparse relations, avoiding per-entity Map
+	* allocation and repeated Array.from(entries()).
+	*
+	* Component type IDs should be pre-encoded by the caller (once per archetype)
+	* and passed in `encodedComponentTypes` (same order and length as this.componentTypes).
+	*
+	* The provided `encode` function should be the cached variant for best performance
+	* on entity IDs and any sparse relation type IDs.
+	*
+	* `sparseByEntity` is an optional pre-fetched map from a bulk
+	* `SparseStore.getAllForEntities` call (further reduces per-entity calls).
 	*/
-	executeCommands(entityId, commands) {
-		if (commands.some((cmd) => cmd.type === "destroy")) {
-			this.clear(entityId);
-			return;
-		}
-		const pendingSetValues = /* @__PURE__ */ new Map();
-		for (const command of commands) if (command.type === "set" && command.componentType) {
-			const merge = getComponentMerge(command.componentType);
-			let nextValue = command.component;
-			if (merge !== void 0 && pendingSetValues.has(command.componentType)) nextValue = merge(pendingSetValues.get(command.componentType), command.component);
-			pendingSetValues.set(command.componentType, nextValue);
-			let data = this.componentEntityComponents.get(entityId);
-			if (!data) {
-				data = /* @__PURE__ */ new Map();
-				this.componentEntityComponents.set(entityId, data);
-				this.registerRelationEntityId(entityId);
+	appendSerializedEntities(out, encode, encodedComponentTypes, sparseByEntity) {
+		if (encodedComponentTypes.length !== this.componentTypes.length) throw new Error("encodedComponentTypes length must match archetype componentTypes");
+		for (let i = 0; i < this.entities.length; i++) {
+			const entity = this.entities[i];
+			const components = [];
+			for (let c = 0; c < this.componentTypes.length; c++) {
+				const data = this.getComponentData(this.componentTypes[c])[i];
+				components.push({
+					type: encodedComponentTypes[c],
+					value: data === MISSING_COMPONENT ? void 0 : data
+				});
 			}
-			data.set(command.componentType, nextValue);
-		} else if (command.type === "delete" && command.componentType) {
-			const data = this.componentEntityComponents.get(entityId);
-			if (isWildcardRelationId(command.componentType)) {
-				const componentId = getComponentIdFromRelationId(command.componentType);
-				if (componentId !== void 0) {
-					if (data) {
-						for (const key of Array.from(data.keys())) if (getComponentIdFromRelationId(key) === componentId) data.delete(key);
-					}
-					for (const key of Array.from(pendingSetValues.keys())) if (getComponentIdFromRelationId(key) === componentId) pendingSetValues.delete(key);
+			const sparseTuples = sparseByEntity?.get(entity) ?? this.sparseRelations.getAllForEntity(entity);
+			for (const [componentType, data] of sparseTuples) components.push({
+				type: encode(componentType),
+				value: data
+			});
+			out.push({
+				id: encode(entity),
+				components
+			});
+		}
+	}
+	removeEntity(entityId) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) return void 0;
+		const removedData = /* @__PURE__ */ new Map();
+		for (const componentType of this.componentTypes) removedData.set(componentType, this.getComponentData(componentType)[index]);
+		const sparseTuples = this.sparseRelations.getAllForEntity(entityId);
+		for (const [componentType, data] of sparseTuples) removedData.set(componentType, data);
+		this.sparseRelations.deleteEntity(entityId);
+		this.entityToIndex.delete(entityId);
+		const lastIndex = this.entities.length - 1;
+		if (index !== lastIndex) {
+			const lastEntity = this.entities[lastIndex];
+			this.entities[index] = lastEntity;
+			this.entityToIndex.set(lastEntity, index);
+			for (const componentType of this.componentTypes) {
+				const dataArray = this.getComponentData(componentType);
+				dataArray[index] = dataArray[lastIndex];
+			}
+		}
+		this.entities.pop();
+		for (const componentType of this.componentTypes) this.getComponentData(componentType).pop();
+		return removedData;
+	}
+	exists(entityId) {
+		return this.entityToIndex.has(entityId);
+	}
+	get(entityId, componentType) {
+		const index = this.entityToIndex.get(entityId);
+		if (index === void 0) throw new Error(`Entity ${entityId} is not in this archetype`);
+		if (isWildcardRelationId(componentType)) return this.getWildcardRelations(entityId, index, componentType);
+		return this.getRegularComponent(entityId, index, componentType);
+	}
+	getWildcardRelations(entityId, index, componentType) {
+		const componentId = getComponentIdFromRelationId(componentType);
+		const relations = [];
+		for (const relType of this.componentTypes) {
+			const relDetailed = getDetailedIdType(relType);
+			if (isRelationType(relDetailed) && relDetailed.componentId === componentId) {
+				const dataArray = this.getComponentData(relType);
+				if (dataArray && dataArray[index] !== void 0) {
+					const data = dataArray[index];
+					relations.push([relDetailed.targetId, data === MISSING_COMPONENT ? void 0 : data]);
 				}
-			} else {
-				data?.delete(command.componentType);
-				pendingSetValues.delete(command.componentType);
 			}
-			if (data?.size === 0) this.clear(entityId);
 		}
+		if (componentId !== void 0) {
+			const matches = this.sparseRelations.getRelationsForComponent(entityId, componentId);
+			for (const m of matches) relations.push(m);
+		}
+		return relations;
 	}
-	/**
-	* Initialize a component entity from a deserialization snapshot.
-	*/
-	initFromSnapshot(entityId, componentMap) {
-		this.componentEntityComponents.set(entityId, componentMap);
-		this.registerRelationEntityId(entityId);
+	getRegularComponent(entityId, index, componentType) {
+		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}`);
 	}
-	/**
-	* Iterate over all component entity entries.
-	* Used for serialization.
-	*/
-	entries() {
-		return this.componentEntityComponents.entries();
+	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) };
 	}
-	registerRelationEntityId(entityId) {
-		const detailed = getDetailedIdType(entityId);
-		if (detailed.type !== "entity-relation") return;
-		const targetId = detailed.targetId;
-		if (targetId === void 0) return;
-		const existing = this.relationEntityIdsByTarget.get(targetId);
-		if (existing) {
-			existing.add(entityId);
+	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;
 		}
-		this.relationEntityIdsByTarget.set(targetId, new Set([entityId]));
+		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`);
 	}
-	unregisterRelationEntityId(entityId) {
-		const detailed = getDetailedIdType(entityId);
-		if (detailed.type !== "entity-relation") return;
-		const targetId = detailed.targetId;
-		if (targetId === void 0) return;
-		const existing = this.relationEntityIdsByTarget.get(targetId);
-		if (!existing) return;
-		existing.delete(entityId);
-		if (existing.size === 0) this.relationEntityIdsByTarget.delete(targetId);
+	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/query/filter.ts
+//#region src/archetype/helpers.ts
 /**
-* Serialize a QueryFilter into a deterministic string suitable for cache keys.
-* Currently only serializes `negativeComponentTypes`.
+* 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
 */
-function serializeQueryFilter(filter = {}) {
-	const negative = (filter.negativeComponentTypes || []).slice().sort((a, b) => a - b);
-	if (negative.length === 0) return "";
-	return `neg:${negative.join(",")}`;
+function hasWildcardRelation(components, wildcardComponentId) {
+	for (const relId of components.keys()) if (isRelationId(relId)) {
+		if (getComponentIdFromRelationId(relId) === wildcardComponentId) return true;
+	}
+	return false;
 }
 /**
-* Check if an archetype matches the given component types
+* Check if a detailed type represents a relation (entity or component)
 */
-function matchesComponentTypes(archetype, componentTypes) {
-	return componentTypes.every((type) => {
-		const detailedType = getDetailedIdType(type);
-		if (detailedType.type === "wildcard-relation") return archetype.componentTypes.some((archetypeType) => {
-			if (!isRelationId(archetypeType)) return false;
-			return getComponentIdFromRelationId(archetypeType) === detailedType.componentId;
-		});
-		else if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId !== void 0 && isDontFragmentComponent(detailedType.componentId)) {
-			const wildcardMarker = relation(detailedType.componentId, "*");
-			return archetype.componentTypeSet.has(wildcardMarker);
-		} else return archetype.componentTypeSet.has(type);
-	});
+function isRelationType(detailedType) {
+	return detailedType.type === "entity-relation" || detailedType.type === "component-relation";
 }
 /**
-* Check if an archetype matches the filter conditions (only filtering logic)
+* Check if a component type matches a given component ID for relations
 */
-function matchesFilter(archetype, filter) {
-	return (filter.negativeComponentTypes || []).every((type) => {
-		const detailedType = getDetailedIdType(type);
-		if (detailedType.type === "wildcard-relation") return !archetype.componentTypes.some((archetypeType) => {
-			if (!isRelationId(archetypeType)) return false;
-			return getComponentIdFromRelationId(archetypeType) === detailedType.componentId;
-		});
-		else return !archetype.componentTypeSet.has(type);
-	});
+function matchesRelationComponentId(componentType, componentId) {
+	const detailedType = getDetailedIdType(componentType);
+	return isRelationType(detailedType) && detailedType.componentId === componentId;
 }
-//#endregion
-//#region src/query/query.ts
 /**
-* Cached query for efficiently iterating entities with specific components.
-*
-* Queries are created via {@link World.createQuery} and should be **reused across frames**
-* for optimal performance. The world automatically keeps the query's internal archetype cache
-* up to date as entities are created and destroyed.
-*
-* @example
-* const movementQuery = world.createQuery([Position, Velocity]);
-*
-* // In the game loop
-* movementQuery.forEach([Position, Velocity], (entity, pos, vel) => {
-*   pos.x += vel.x;
-*   pos.y += vel.y;
-* });
+* Build cache key for component types
 */
-var Query = class {
-	world;
-	componentTypes;
-	filter;
-	cachedArchetypes = [];
-	isDisposed = false;
-	/** Cache key assigned by World for O(1) releaseQuery lookup */
-	_cacheKey;
-	/** Cached wildcard component types for faster entity filtering */
-	wildcardTypes;
-	/** Cached specific dontFragment relation types that need entity-level filtering */
-	specificDontFragmentTypes;
-	/**
-	* @internal Queries should be created via {@link World.createQuery}, not instantiated directly.
-	*/
-	constructor(world, componentTypes, filter = {}, registry) {
-		this.world = world;
-		this.componentTypes = normalizeComponentTypes(componentTypes);
-		this.filter = filter;
-		this.wildcardTypes = this.componentTypes.filter((ct) => getDetailedIdType(ct).type === "wildcard-relation");
-		this.specificDontFragmentTypes = this.componentTypes.filter((ct) => {
-			const detailedType = getDetailedIdType(ct);
-			return (detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId !== void 0 && isDontFragmentComponent(detailedType.componentId);
-		});
-		this.updateCache();
-		if (registry) registry.register(this);
-	}
-	/**
-	* Check if query is disposed and throw error if so
-	*/
-	ensureNotDisposed() {
-		if (this.isDisposed) throw new Error("Query has been disposed");
+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]);
 	}
-	/**
-	* Returns all entity IDs that match this query.
-	*
-	* @returns Array of matching entity IDs
-	*
-	* @example
-	* const entities = query.getEntities();
-	* for (const entity of entities) {
-	*   const pos = world.get(entity, Position);
-	* }
-	*/
-	getEntities() {
-		this.ensureNotDisposed();
-		if (this.wildcardTypes.length === 0 && this.specificDontFragmentTypes.length === 0) {
-			const result = [];
-			for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) result.push(entity);
-			return result;
-		}
-		const result = [];
-		for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) if (this.entityMatchesQuery(archetype, entity)) result.push(entity);
-		return result;
+	if (targetComponentId !== void 0) {
+		const dfMatches = sparseStore.getRelationsForComponent(entityId, targetComponentId);
+		for (const m of dfMatches) relations.push(m);
 	}
-	/**
-	* Check if entity matches all query requirements (wildcards and specific dontFragment relations)
-	*/
-	entityMatchesQuery(archetype, entity) {
-		for (const wildcardType of this.wildcardTypes) {
-			const relations = archetype.get(entity, wildcardType);
-			if (!relations || relations.length === 0) return false;
+	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}`);
 		}
-		for (const specificType of this.specificDontFragmentTypes) if (archetype.getOptional(entity, specificType) === void 0) return false;
-		return true;
+		return;
 	}
-	/**
-	* Returns all matching entities along with their component data.
-	*
-	* @param componentTypes - Array of component types to retrieve
-	* @returns Array of objects containing the entity ID and its component tuple
-	*
-	* @example
-	* const results = query.getEntitiesWithComponents([Position, Velocity]);
-	* results.forEach(({ entity, components: [pos, vel] }) => {
-	*   pos.x += vel.x;
-	* });
-	*/
-	getEntitiesWithComponents(componentTypes) {
-		this.ensureNotDisposed();
-		const result = [];
-		for (const archetype of this.cachedArchetypes) archetype.appendEntitiesWithComponents(componentTypes, result);
-		return result;
+	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
+/**
+* Manages component entity (singleton) storage.
+*
+* Component entities use a flat Map-based storage rather than the Archetype-based
+* storage used for regular entities. Their IDs are in the component ID range
+* (or are relation IDs), distinguishing them from regular entity IDs.
+*/
+var ComponentEntityStore = class {
+	componentEntityComponents = /* @__PURE__ */ new Map();
+	relationEntityIdsByTarget = /* @__PURE__ */ new Map();
 	/**
-	* Iterates over all matching entities and invokes the callback with their component data.
-	* This is the preferred way to read and mutate components in a hot loop.
-	*
-	* @param componentTypes - Array of component types to retrieve
-	* @param callback - Function called for each matching entity with its components
-	*
-	* @example
-	* query.forEach([Position, Velocity], (entity, pos, vel) => {
-	*   pos.x += vel.x;
-	*   pos.y += vel.y;
-	* });
+	* Check if an entity ID is a component entity type.
+	* Returns true for component IDs, component-relation IDs, and entity-relation IDs —
+	* i.e. anything that is NOT a plain entity or an invalid ID.
 	*/
-	forEach(componentTypes, callback) {
-		this.ensureNotDisposed();
-		for (const archetype of this.cachedArchetypes) archetype.forEachWithComponents(componentTypes, callback);
+	exists(entityId) {
+		const detailed = getDetailedIdType(entityId);
+		return detailed.type !== "entity" && detailed.type !== "invalid";
 	}
 	/**
-	* Generator that yields each matching entity together with its component data.
-	*
-	* @param componentTypes - Array of component types to retrieve
-	* @yields Tuples of `[entityId, ...components]`
-	*
-	* @example
-	* for (const [entity, pos, vel] of query.iterate([Position, Velocity])) {
-	*   pos.x += vel.x;
-	* }
+	* Check if a component entity has a specific component.
 	*/
-	*iterate(componentTypes) {
-		this.ensureNotDisposed();
-		for (const archetype of this.cachedArchetypes) yield* archetype.iterateWithComponents(componentTypes);
+	has(entityId, componentType) {
+		return this.componentEntityComponents.get(entityId)?.has(componentType) ?? false;
 	}
 	/**
-	* Returns an array containing the data of a single component for every matching entity.
-	*
-	* @param componentType - The component type to retrieve
-	* @returns Array of component data (one entry per matching entity)
-	*
-	* @example
-	* const positions = query.getComponentData(Position);
+	* Check if a singleton component has data — the has(componentId) overload.
+	* In singleton usage the entity ID and the component type are the same value.
 	*/
-	getComponentData(componentType) {
-		this.ensureNotDisposed();
-		const result = [];
-		for (const archetype of this.cachedArchetypes) for (const data of archetype.getComponentData(componentType)) result.push(data);
-		return result;
+	hasSingleton(componentId) {
+		return this.componentEntityComponents.get(componentId)?.has(componentId) ?? false;
 	}
 	/**
-	* @internal Rebuilds the cached archetype list. Called automatically by the world.
+	* Check if a component entity has any wildcard relations matching a component ID.
 	*/
-	updateCache() {
-		if (this.isDisposed) return;
-		this.cachedArchetypes = this.world.getMatchingArchetypes(this.componentTypes).filter((archetype) => matchesFilter(archetype, this.filter));
+	hasWildcard(entityId, componentId) {
+		const data = this.componentEntityComponents.get(entityId);
+		if (!data) return false;
+		return hasWildcardRelation(data, componentId);
 	}
 	/**
-	* @internal Called by the world when a new archetype is created.
+	* Get a component value from a component entity.
+	* Throws if the component does not exist.
 	*/
-	checkNewArchetype(archetype) {
-		if (this.isDisposed) return;
-		if (matchesComponentTypes(archetype, this.componentTypes) && matchesFilter(archetype, this.filter) && !this.cachedArchetypes.includes(archetype)) this.cachedArchetypes.push(archetype);
+	get(entityId, componentType) {
+		const data = this.componentEntityComponents.get(entityId);
+		if (!data || !data.has(componentType)) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
+		return data.get(componentType);
 	}
 	/**
-	* @internal Called by the world when an archetype is destroyed.
+	* Get an optional component value from a component entity.
+	* Returns undefined if the component does not exist.
 	*/
-	removeArchetype(archetype) {
-		if (this.isDisposed) return;
-		const index = this.cachedArchetypes.indexOf(archetype);
-		if (index !== -1) this.cachedArchetypes.splice(index, 1);
+	getOptional(entityId, componentType) {
+		const data = this.componentEntityComponents.get(entityId);
+		if (!data || !data.has(componentType)) return void 0;
+		return { value: data.get(componentType) };
 	}
 	/**
-	* Request disposal of this query.
-	* This will decrement the world's reference count for the query.
-	* The query will only be fully disposed when the ref count reaches zero.
+	* Get all wildcard relations of a given type from a component entity.
 	*/
-	dispose() {
-		this.world.releaseQuery(this);
+	getWildcard(entityId, wildcardComponentType) {
+		const componentId = getComponentIdFromRelationId(wildcardComponentType);
+		const data = this.componentEntityComponents.get(entityId);
+		if (componentId === void 0 || !data) return [];
+		const relations = [];
+		for (const [key, value] of data.entries()) {
+			if (getComponentIdFromRelationId(key) !== componentId) continue;
+			const detailed = getDetailedIdType(key);
+			if (detailed.type === "entity-relation" || detailed.type === "component-relation") relations.push([detailed.targetId, value]);
+		}
+		return relations;
 	}
 	/**
-	* @internal Fully disposes the query when the world's refCount reaches zero.
+	* Clear all data for a component entity.
 	*/
-	_disposeInternal(registry) {
-		if (!this.isDisposed) {
-			if (registry) registry.unregister(this);
-			this.cachedArchetypes = [];
-			this.isDisposed = true;
-		}
+	clear(entityId) {
+		if (this.componentEntityComponents.delete(entityId)) this.unregisterRelationEntityId(entityId);
 	}
 	/**
-	* Using-with-disposals support. Calls {@link dispose} automatically.
-	*
-	* @example
-	* using query = world.createQuery([Position]);
-	* // query is released automatically when the block exits
+	* Cleanup all component entities that reference a given target entity.
+	* Called when a target entity is destroyed.
 	*/
-	[Symbol.dispose]() {
-		this.dispose();
+	cleanupReferencesTo(targetId) {
+		const relationEntities = this.relationEntityIdsByTarget.get(targetId);
+		if (!relationEntities) return;
+		for (const relationEntityId of relationEntities) this.componentEntityComponents.delete(relationEntityId);
+		this.relationEntityIdsByTarget.delete(targetId);
 	}
 	/**
-	* Whether the query has been disposed and can no longer be used.
+	* Execute a batch of commands for a component entity.
 	*/
-	get disposed() {
-		return this.isDisposed;
-	}
-};
-//#endregion
-//#region src/query/registry.ts
-/**
-* Manages the lifecycle and caching of `Query` instances.
+	executeCommands(entityId, commands) {
+		if (commands.some((cmd) => cmd.type === "destroy")) {
+			this.clear(entityId);
+			return;
+		}
+		const pendingSetValues = /* @__PURE__ */ new Map();
+		for (const command of commands) if (command.type === "set" && command.componentType) {
+			const merge = getComponentMerge(command.componentType);
+			let nextValue = command.component;
+			if (merge !== void 0 && pendingSetValues.has(command.componentType)) nextValue = merge(pendingSetValues.get(command.componentType), command.component);
+			pendingSetValues.set(command.componentType, nextValue);
+			let data = this.componentEntityComponents.get(entityId);
+			if (!data) {
+				data = /* @__PURE__ */ new Map();
+				this.componentEntityComponents.set(entityId, data);
+				this.registerRelationEntityId(entityId);
+			}
+			data.set(command.componentType, nextValue);
+		} else if (command.type === "delete" && command.componentType) {
+			const data = this.componentEntityComponents.get(entityId);
+			if (isWildcardRelationId(command.componentType)) {
+				const componentId = getComponentIdFromRelationId(command.componentType);
+				if (componentId !== void 0) {
+					if (data) {
+						for (const key of Array.from(data.keys())) if (getComponentIdFromRelationId(key) === componentId) data.delete(key);
+					}
+					for (const key of Array.from(pendingSetValues.keys())) if (getComponentIdFromRelationId(key) === componentId) pendingSetValues.delete(key);
+				}
+			} else {
+				data?.delete(command.componentType);
+				pendingSetValues.delete(command.componentType);
+			}
+			if (data?.size === 0) this.clear(entityId);
+		}
+	}
+	/**
+	* Initialize a component entity from a deserialization snapshot.
+	*/
+	initFromSnapshot(entityId, componentMap) {
+		this.componentEntityComponents.set(entityId, componentMap);
+		this.registerRelationEntityId(entityId);
+	}
+	/**
+	* Iterate over all component entity entries.
+	* Used for serialization.
+	*/
+	entries() {
+		return this.componentEntityComponents.entries();
+	}
+	registerRelationEntityId(entityId) {
+		const detailed = getDetailedIdType(entityId);
+		if (detailed.type !== "entity-relation") return;
+		const targetId = detailed.targetId;
+		if (targetId === void 0) return;
+		const existing = this.relationEntityIdsByTarget.get(targetId);
+		if (existing) {
+			existing.add(entityId);
+			return;
+		}
+		this.relationEntityIdsByTarget.set(targetId, new Set([entityId]));
+	}
+	unregisterRelationEntityId(entityId) {
+		const detailed = getDetailedIdType(entityId);
+		if (detailed.type !== "entity-relation") return;
+		const targetId = detailed.targetId;
+		if (targetId === void 0) return;
+		const existing = this.relationEntityIdsByTarget.get(targetId);
+		if (!existing) return;
+		existing.delete(entityId);
+		if (existing.size === 0) this.relationEntityIdsByTarget.delete(targetId);
+	}
+};
+//#endregion
+//#region src/query/filter.ts
+/**
+* Serialize a QueryFilter into a deterministic string suitable for cache keys.
+* Currently only serializes `negativeComponentTypes`.
+*/
+function serializeQueryFilter(filter = {}) {
+	const negative = (filter.negativeComponentTypes || []).slice().sort((a, b) => a - b);
+	if (negative.length === 0) return "";
+	return `neg:${negative.join(",")}`;
+}
+/**
+* Check if an archetype matches the given component types
+*/
+function matchesComponentTypes(archetype, componentTypes) {
+	return componentTypes.every((type) => {
+		const detailedType = getDetailedIdType(type);
+		if (detailedType.type === "wildcard-relation") return archetype.componentTypes.some((archetypeType) => {
+			if (!isRelationId(archetypeType)) return false;
+			return getComponentIdFromRelationId(archetypeType) === detailedType.componentId;
+		});
+		else if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId !== void 0 && isSparseComponent(detailedType.componentId)) {
+			const wildcardMarker = relation(detailedType.componentId, "*");
+			return archetype.componentTypeSet.has(wildcardMarker);
+		} else return archetype.componentTypeSet.has(type);
+	});
+}
+/**
+* Check if an archetype matches the filter conditions (only filtering logic)
+*/
+function matchesFilter(archetype, filter) {
+	return (filter.negativeComponentTypes || []).every((type) => {
+		const detailedType = getDetailedIdType(type);
+		if (detailedType.type === "wildcard-relation") return !archetype.componentTypes.some((archetypeType) => {
+			if (!isRelationId(archetypeType)) return false;
+			return getComponentIdFromRelationId(archetypeType) === detailedType.componentId;
+		});
+		else return !archetype.componentTypeSet.has(type);
+	});
+}
+//#endregion
+//#region src/query/query.ts
+/**
+* Cached query for efficiently iterating entities with specific components.
 *
-* Responsibilities:
-* - Create / reuse cached queries keyed by component-type + filter signature.
-* - Track reference counts so queries are only disposed when truly unused.
-* - Notify registered queries when new archetypes are created or destroyed.
+* Queries are created via {@link World.createQuery} and should be **reused across frames**
+* for optimal performance. The world automatically keeps the query's internal archetype cache
+* up to date as entities are created and destroyed.
 *
-* The `_cacheKey` string that was previously attached directly to `Query` is now
-* kept in a private `WeakMap` so the `Query` class doesn't need to expose it.
+* @example
+* const movementQuery = world.createQuery([Position, Velocity]);
+*
+* // In the game loop
+* movementQuery.forEach([Position, Velocity], (entity, pos, vel) => {
+*   pos.x += vel.x;
+*   pos.y += vel.y;
+* });
 */
-var QueryRegistry = class {
-	/** All live queries that should receive archetype notifications. */
-	queries = /* @__PURE__ */ new Set();
-	/** Cache of reusable queries keyed by a deterministic signature string. */
-	cache = /* @__PURE__ */ new Map();
-	/** Maps each query to its cache key without polluting the Query public API. */
-	cacheKeys = /* @__PURE__ */ new WeakMap();
+var Query = class {
+	world;
+	componentTypes;
+	filter;
+	cachedArchetypes = [];
+	isDisposed = false;
+	/** Cache key assigned by World for O(1) releaseQuery lookup */
+	_cacheKey;
+	/** Cached wildcard component types for faster entity filtering */
+	wildcardTypes;
+	/** Cached specific sparse relation types that need entity-level filtering */
+	specificSparseRelationTypes;
 	/**
-	* Returns (or creates) a cached query for the given component types and filter.
-	* Increments the reference count on cache hits.
+	* @internal Queries should be created via {@link World.createQuery}, not instantiated directly.
+	*/
+	constructor(world, componentTypes, filter = {}, registry) {
+		this.world = world;
+		this.componentTypes = normalizeComponentTypes(componentTypes);
+		this.filter = filter;
+		this.wildcardTypes = this.componentTypes.filter((ct) => getDetailedIdType(ct).type === "wildcard-relation");
+		this.specificSparseRelationTypes = this.componentTypes.filter((ct) => {
+			const detailedType = getDetailedIdType(ct);
+			return (detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId !== void 0 && isSparseComponent(detailedType.componentId);
+		});
+		this.updateCache();
+		if (registry) registry.register(this);
+	}
+	/**
+	* Check if query is disposed and throw error if so
+	*/
+	ensureNotDisposed() {
+		if (this.isDisposed) throw new Error("Query has been disposed");
+	}
+	/**
+	* Returns all entity IDs that match this query.
 	*
-	* @param world       The world that owns this registry.
-	* @param sortedTypes  Normalized (sorted) component types.
-	* @param key          Combined cache key (`types|filter`).
-	* @param filter       The raw query filter (used when creating a new Query).
+	* @returns Array of matching entity IDs
+	*
+	* @example
+	* const entities = query.getEntities();
+	* for (const entity of entities) {
+	*   const pos = world.get(entity, Position);
+	* }
 	*/
-	getOrCreate(world, sortedTypes, key, filter) {
-		const cached = this.cache.get(key);
-		if (cached) {
-			cached.refCount++;
-			return cached.query;
+	getEntities() {
+		this.ensureNotDisposed();
+		if (this.wildcardTypes.length === 0 && this.specificSparseRelationTypes.length === 0) {
+			const result = [];
+			for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) result.push(entity);
+			return result;
 		}
-		const query = new Query(world, sortedTypes, filter, this);
-		this.cacheKeys.set(query, key);
-		this.cache.set(key, {
-			query,
-			refCount: 1
-		});
-		return query;
+		const result = [];
+		for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) if (this.entityMatchesQuery(archetype, entity)) result.push(entity);
+		return result;
 	}
 	/**
-	* Decrements the reference count for the given query.
-	* When the count reaches zero the query is fully disposed.
+	* Check if entity matches all query requirements (wildcards and specific sparse relations)
 	*/
-	release(query) {
-		const key = this.cacheKeys.get(query);
-		if (!key) return;
-		const cached = this.cache.get(key);
-		if (!cached || cached.query !== query) return;
-		cached.refCount--;
-		if (cached.refCount <= 0) {
-			this.cache.delete(key);
-			cached.query._disposeInternal(this);
+	entityMatchesQuery(archetype, entity) {
+		for (const wildcardType of this.wildcardTypes) {
+			const relations = archetype.get(entity, wildcardType);
+			if (!relations || relations.length === 0) return false;
 		}
+		for (const specificType of this.specificSparseRelationTypes) if (archetype.getOptional(entity, specificType) === void 0) return false;
+		return true;
+	}
+	/**
+	* Returns all matching entities along with their component data.
+	*
+	* @param componentTypes - Array of component types to retrieve
+	* @returns Array of objects containing the entity ID and its component tuple
+	*
+	* @example
+	* const results = query.getEntitiesWithComponents([Position, Velocity]);
+	* results.forEach(({ entity, components: [pos, vel] }) => {
+	*   pos.x += vel.x;
+	* });
+	*/
+	getEntitiesWithComponents(componentTypes) {
+		this.ensureNotDisposed();
+		const result = [];
+		for (const archetype of this.cachedArchetypes) archetype.appendEntitiesWithComponents(componentTypes, result);
+		return result;
+	}
+	/**
+	* Iterates over all matching entities and invokes the callback with their component data.
+	* This is the preferred way to read and mutate components in a hot loop.
+	*
+	* @param componentTypes - Array of component types to retrieve
+	* @param callback - Function called for each matching entity with its components
+	*
+	* @example
+	* query.forEach([Position, Velocity], (entity, pos, vel) => {
+	*   pos.x += vel.x;
+	*   pos.y += vel.y;
+	* });
+	*/
+	forEach(componentTypes, callback) {
+		this.ensureNotDisposed();
+		for (const archetype of this.cachedArchetypes) archetype.forEachWithComponents(componentTypes, callback);
+	}
+	/**
+	* Generator that yields each matching entity together with its component data.
+	*
+	* @param componentTypes - Array of component types to retrieve
+	* @yields Tuples of `[entityId, ...components]`
+	*
+	* @example
+	* for (const [entity, pos, vel] of query.iterate([Position, Velocity])) {
+	*   pos.x += vel.x;
+	* }
+	*/
+	*iterate(componentTypes) {
+		this.ensureNotDisposed();
+		for (const archetype of this.cachedArchetypes) yield* archetype.iterateWithComponents(componentTypes);
+	}
+	/**
+	* Returns an array containing the data of a single component for every matching entity.
+	*
+	* @param componentType - The component type to retrieve
+	* @returns Array of component data (one entry per matching entity)
+	*
+	* @example
+	* const positions = query.getComponentData(Position);
+	*/
+	getComponentData(componentType) {
+		this.ensureNotDisposed();
+		const result = [];
+		for (const archetype of this.cachedArchetypes) for (const data of archetype.getComponentData(componentType)) result.push(data);
+		return result;
+	}
+	/**
+	* @internal Rebuilds the cached archetype list. Called automatically by the world.
+	*/
+	updateCache() {
+		if (this.isDisposed) return;
+		this.cachedArchetypes = this.world.getMatchingArchetypes(this.componentTypes).filter((archetype) => matchesFilter(archetype, this.filter));
+	}
+	/**
+	* @internal Called by the world when a new archetype is created.
+	*/
+	checkNewArchetype(archetype) {
+		if (this.isDisposed) return;
+		if (matchesComponentTypes(archetype, this.componentTypes) && matchesFilter(archetype, this.filter) && !this.cachedArchetypes.includes(archetype)) this.cachedArchetypes.push(archetype);
+	}
+	/**
+	* @internal Called by the world when an archetype is destroyed.
+	*/
+	removeArchetype(archetype) {
+		if (this.isDisposed) return;
+		const index = this.cachedArchetypes.indexOf(archetype);
+		if (index !== -1) this.cachedArchetypes.splice(index, 1);
+	}
+	/**
+	* Request disposal of this query.
+	* This will decrement the world's reference count for the query.
+	* The query will only be fully disposed when the ref count reaches zero.
+	*/
+	dispose() {
+		this.world.releaseQuery(this);
+	}
+	/**
+	* @internal Fully disposes the query when the world's refCount reaches zero.
+	*/
+	_disposeInternal(registry) {
+		if (!this.isDisposed) {
+			if (registry) registry.unregister(this);
+			this.cachedArchetypes = [];
+			this.isDisposed = true;
+		}
+	}
+	/**
+	* Using-with-disposals support. Calls {@link dispose} automatically.
+	*
+	* @example
+	* using query = world.createQuery([Position]);
+	* // query is released automatically when the block exits
+	*/
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+	/**
+	* Whether the query has been disposed and can no longer be used.
+	*/
+	get disposed() {
+		return this.isDisposed;
+	}
+};
+//#endregion
+//#region src/query/registry.ts
+/**
+* Manages the lifecycle and caching of `Query` instances.
+*
+* Responsibilities:
+* - Create / reuse cached queries keyed by component-type + filter signature.
+* - Track reference counts so queries are only disposed when truly unused.
+* - Notify registered queries when new archetypes are created or destroyed.
+*
+* The `_cacheKey` string that was previously attached directly to `Query` is now
+* kept in a private `WeakMap` so the `Query` class doesn't need to expose it.
+*/
+var QueryRegistry = class {
+	/** All live queries that should receive archetype notifications. */
+	queries = /* @__PURE__ */ new Set();
+	/** Cache of reusable queries keyed by a deterministic signature string. */
+	cache = /* @__PURE__ */ new Map();
+	/** Maps each query to its cache key without polluting the Query public API. */
+	cacheKeys = /* @__PURE__ */ new WeakMap();
+	/**
+	* Returns (or creates) a cached query for the given component types and filter.
+	* Increments the reference count on cache hits.
+	*
+	* @param world       The world that owns this registry.
+	* @param sortedTypes  Normalized (sorted) component types.
+	* @param key          Combined cache key (`types|filter`).
+	* @param filter       The raw query filter (used when creating a new Query).
+	*/
+	getOrCreate(world, sortedTypes, key, filter) {
+		const cached = this.cache.get(key);
+		if (cached) {
+			cached.refCount++;
+			return cached.query;
+		}
+		const query = new Query(world, sortedTypes, filter, this);
+		this.cacheKeys.set(query, key);
+		this.cache.set(key, {
+			query,
+			refCount: 1
+		});
+		return query;
+	}
+	/**
+	* Decrements the reference count for the given query.
+	* When the count reaches zero the query is fully disposed.
+	*/
+	release(query) {
+		const key = this.cacheKeys.get(query);
+		if (!key) return;
+		const cached = this.cache.get(key);
+		if (!cached || cached.query !== query) return;
+		cached.refCount--;
+		if (cached.refCount <= 0) {
+			this.cache.delete(key);
+			cached.query._disposeInternal(this);
+		}
+	}
+	/**
+	* Registers a query so it receives future archetype notifications.
+	* Called automatically by the `Query` constructor via `world._registerQuery`.
+	*/
+	register(query) {
+		this.queries.add(query);
+	}
+	/**
+	* Removes a query from the notification list.
+	* Called by `Query._disposeInternal` via `world._unregisterQuery`.
+	*/
+	unregister(query) {
+		this.queries.delete(query);
+	}
+	/**
+	* Notifies all live queries that a new archetype has been created.
+	* Queries will add the archetype to their cache if it matches.
+	*/
+	onNewArchetype(archetype) {
+		for (const query of this.queries) query.checkNewArchetype(archetype);
+	}
+	/**
+	* Notifies all live queries that an archetype has been destroyed.
+	* Queries will remove the archetype from their internal cache.
+	*/
+	onArchetypeRemoved(archetype) {
+		for (const query of this.queries) query.removeArchetype(archetype);
+	}
+};
+//#endregion
+//#region src/world/commands.ts
+function processCommands(entityId, currentArchetype, commands, changeset, handleExclusiveRelation) {
+	for (const command of commands) if (command.type === "set") processSetCommand(entityId, currentArchetype, command.componentType, command.component, changeset, handleExclusiveRelation);
+	else if (command.type === "delete") processDeleteCommand(entityId, currentArchetype, command.componentType, changeset);
+}
+function processSetCommand(entityId, currentArchetype, componentType, component, changeset, handleExclusiveRelation) {
+	const componentId = getComponentIdFromRelationId(componentType);
+	if (componentId !== void 0) {
+		handleExclusiveRelation(entityId, currentArchetype, componentId);
+		if (isSparseComponent(componentId)) {
+			const wildcardMarker = relation(componentId, "*");
+			if (!currentArchetype.componentTypeSet.has(wildcardMarker)) changeset.set(wildcardMarker, void 0);
+		}
+	}
+	const merge = getComponentMerge(componentType);
+	if (merge !== void 0 && changeset.adds.has(componentType)) {
+		const prev = changeset.adds.get(componentType);
+		changeset.set(componentType, merge(prev, component));
+		return;
+	}
+	changeset.set(componentType, component);
+}
+function processDeleteCommand(entityId, currentArchetype, componentType, changeset) {
+	const componentId = getComponentIdFromRelationId(componentType);
+	if (isWildcardRelationId(componentType) && componentId !== void 0) removeWildcardRelations(entityId, currentArchetype, componentId, changeset);
+	else {
+		changeset.delete(componentType);
+		maybeRemoveWildcardMarker(entityId, currentArchetype, componentType, componentId, changeset);
+	}
+}
+function removeMatchingRelations(entityId, archetype, baseComponentId, changeset) {
+	for (const componentType of archetype.componentTypes) {
+		if (isWildcardRelationId(componentType)) continue;
+		if (getComponentIdFromRelationId(componentType) === baseComponentId) changeset.delete(componentType);
+	}
+	const sparseData = archetype.getEntitySparseRelations(entityId);
+	if (sparseData) {
+		for (const componentType of sparseData.keys()) if (getComponentIdFromRelationId(componentType) === baseComponentId) changeset.delete(componentType);
+	}
+}
+function removeWildcardRelations(entityId, currentArchetype, baseComponentId, changeset) {
+	removeMatchingRelations(entityId, currentArchetype, baseComponentId, changeset);
+	if (isSparseComponent(baseComponentId)) changeset.delete(relation(baseComponentId, "*"));
+}
+function maybeRemoveWildcardMarker(entityId, archetype, removedComponentType, componentId, changeset) {
+	if (componentId === void 0 || !isSparseComponent(componentId)) return;
+	const wildcardMarker = relation(componentId, "*");
+	for (const otherComponentType of archetype.componentTypes) {
+		if (otherComponentType === removedComponentType) continue;
+		if (otherComponentType === wildcardMarker) continue;
+		if (changeset.removes.has(otherComponentType)) continue;
+		if (getComponentIdFromRelationId(otherComponentType) === componentId) return;
+	}
+	const sparseData = archetype.getEntitySparseRelations(entityId);
+	if (sparseData) for (const otherComponentType of sparseData.keys()) {
+		if (otherComponentType === removedComponentType) continue;
+		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;
+	}
+	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);
+	}
+	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);
+	}
+};
+//#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);
+	}
+	/**
+	* Remove a component from the changeset
+	*/
+	delete(componentType) {
+		this.removes.add(componentType);
+		this.adds.delete(componentType);
 	}
 	/**
-	* Registers a query so it receives future archetype notifications.
-	* Called automatically by the `Query` constructor via `world._registerQuery`.
+	* Check if the changeset has any changes
 	*/
-	register(query) {
-		this.queries.add(query);
+	hasChanges() {
+		return this.adds.size > 0 || this.removes.size > 0;
 	}
 	/**
-	* Removes a query from the notification list.
-	* Called by `Query._disposeInternal` via `world._unregisterQuery`.
+	* Clear all changes
 	*/
-	unregister(query) {
-		this.queries.delete(query);
+	clear() {
+		this.adds.clear();
+		this.removes.clear();
 	}
 	/**
-	* Notifies all live queries that a new archetype has been created.
-	* Queries will add the archetype to their cache if it matches.
+	* Merge another changeset into this one
 	*/
-	onNewArchetype(archetype) {
-		for (const query of this.queries) query.checkNewArchetype(archetype);
+	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);
+		}
 	}
 	/**
-	* Notifies all live queries that an archetype has been destroyed.
-	* Queries will remove the archetype from their internal cache.
+	* Apply the changeset to existing components and return the final state
 	*/
-	onArchetypeRemoved(archetype) {
-		for (const query of this.queries) query.removeArchetype(archetype);
+	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/commands.ts
-function processCommands(entityId, currentArchetype, commands, changeset, handleExclusiveRelation) {
-	for (const command of commands) if (command.type === "set") processSetCommand(entityId, currentArchetype, command.componentType, command.component, changeset, handleExclusiveRelation);
-	else if (command.type === "delete") processDeleteCommand(entityId, currentArchetype, command.componentType, changeset);
-}
-function processSetCommand(entityId, currentArchetype, componentType, component, changeset, handleExclusiveRelation) {
-	const componentId = getComponentIdFromRelationId(componentType);
-	if (componentId !== void 0) {
-		handleExclusiveRelation(entityId, currentArchetype, componentId);
-		if (isDontFragmentComponent(componentId)) {
-			const wildcardMarker = relation(componentId, "*");
-			if (!currentArchetype.componentTypeSet.has(wildcardMarker)) changeset.set(wildcardMarker, void 0);
-		}
-	}
-	const merge = getComponentMerge(componentType);
-	if (merge !== void 0 && changeset.adds.has(componentType)) {
-		const prev = changeset.adds.get(componentType);
-		changeset.set(componentType, merge(prev, component));
-		return;
-	}
-	changeset.set(componentType, component);
-}
-function processDeleteCommand(entityId, currentArchetype, componentType, changeset) {
-	const componentId = getComponentIdFromRelationId(componentType);
-	if (isWildcardRelationId(componentType) && componentId !== void 0) removeWildcardRelations(entityId, currentArchetype, componentId, changeset);
-	else {
-		changeset.delete(componentType);
-		maybeRemoveWildcardMarker(entityId, currentArchetype, componentType, componentId, changeset);
-	}
-}
-function removeMatchingRelations(entityId, archetype, baseComponentId, changeset) {
-	for (const componentType of archetype.componentTypes) {
-		if (isWildcardRelationId(componentType)) continue;
-		if (getComponentIdFromRelationId(componentType) === baseComponentId) changeset.delete(componentType);
-	}
-	const dontFragmentData = archetype.getEntityDontFragmentRelations(entityId);
-	if (dontFragmentData) {
-		for (const componentType of dontFragmentData.keys()) if (getComponentIdFromRelationId(componentType) === baseComponentId) changeset.delete(componentType);
-	}
-}
-function removeWildcardRelations(entityId, currentArchetype, baseComponentId, changeset) {
-	removeMatchingRelations(entityId, currentArchetype, baseComponentId, changeset);
-	if (isDontFragmentComponent(baseComponentId)) changeset.delete(relation(baseComponentId, "*"));
-}
-function maybeRemoveWildcardMarker(entityId, archetype, removedComponentType, componentId, changeset) {
-	if (componentId === void 0 || !isDontFragmentComponent(componentId)) return;
-	const wildcardMarker = relation(componentId, "*");
-	for (const otherComponentType of archetype.componentTypes) {
-		if (otherComponentType === removedComponentType) continue;
-		if (otherComponentType === wildcardMarker) continue;
-		if (changeset.removes.has(otherComponentType)) continue;
-		if (getComponentIdFromRelationId(otherComponentType) === componentId) return;
-	}
-	const dontFragmentData = archetype.getEntityDontFragmentRelations(entityId);
-	if (dontFragmentData) for (const otherComponentType of dontFragmentData.keys()) {
-		if (otherComponentType === removedComponentType) continue;
-		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;
-	}
-	changeset.delete(wildcardMarker);
-}
-function hasEntityComponent(archetype, entityId, componentType) {
-	if (archetype.componentTypeSet.has(componentType)) return true;
-	return archetype.getEntityDontFragmentRelations(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 (!isDontFragmentRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) return true;
-	for (const componentType of changeset.adds.keys()) if (!isDontFragmentRelation(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 (!isDontFragmentRelation(componentType)) finalRegularTypes.delete(componentType);
-	for (const [componentType] of changeset.adds) if (!isDontFragmentRelation(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) applyDontFragmentChanges(ctx.dontFragmentStore, entityId, changeset, removedComponents);
-	else applyDontFragmentChangesNoHooks(ctx.dontFragmentStore, entityId, changeset);
-	for (const [componentType, component] of changeset.adds) {
-		if (isDontFragmentRelation(componentType)) continue;
-		currentArchetype.set(entityId, componentType, component);
-	}
-	return currentArchetype;
-}
+//#region src/world/hooks.ts
 /**
-* No-hooks variant of applyDontFragmentChanges that skips tracking removed component data.
-*
-* Rewritten for the new DontFragmentStore interface (ComponentId-primary storage).
+* Debug-only counter incremented on every invokeHook call when armed.
+* World reads and resets this during armed syncs.
 */
-function applyDontFragmentChanges(dontFragmentRelations, entityId, changeset, removedComponents) {
-	for (const componentType of changeset.removes) if (isDontFragmentRelation(componentType)) {
-		const removedValue = dontFragmentRelations.getValue(entityId, componentType);
-		if (removedValue !== void 0 || dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) removedComponents.set(componentType, removedValue);
-		dontFragmentRelations.deleteValue(entityId, componentType);
-	}
-	for (const [componentType, component] of changeset.adds) if (isDontFragmentRelation(componentType)) dontFragmentRelations.setValue(entityId, componentType, component);
-}
-function applyDontFragmentChangesNoHooks(dontFragmentRelations, entityId, changeset) {
-	for (const componentType of changeset.removes) if (isDontFragmentRelation(componentType)) dontFragmentRelations.deleteValue(entityId, componentType);
-	for (const [componentType, component] of changeset.adds) if (isDontFragmentRelation(componentType)) dontFragmentRelations.setValue(entityId, componentType, component);
-}
-function filterRegularComponentTypes(componentTypes) {
-	const regularTypes = [];
-	for (const componentType of componentTypes) {
-		if (isDontFragmentWildcard(componentType)) {
-			regularTypes.push(componentType);
-			continue;
-		}
-		if (isDontFragmentRelation(componentType)) continue;
-		regularTypes.push(componentType);
-	}
-	return regularTypes;
-}
-//#endregion
-//#region src/world/hooks.ts
+const debugHookExecutionCounter = { value: 0 };
 /**
 * Unified hook invocation: prefers entry.callback (callback style) over hook.on_* (object style).
 */
 function invokeHook(entry, event, entityId, components) {
+	debugHookExecutionCounter.value++;
 	if (entry.callback) {
 		entry.callback(event, entityId, ...components);
 		return;
@@ -2301,11 +2515,275 @@ 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, exists = () => true) {
+	const targetEntityId = entityId;
+	const componentType = componentTypeOrComponent;
+	assertEntityExists(targetEntityId, "Entity", exists);
+	assertSetComponentTypeValid(componentType);
+	return {
+		entityId: targetEntityId,
+		componentType,
+		component: maybeComponent
+	};
+}
+/**
+* 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
 /**
-* Encode an internal EntityId into a SerializedEntityId for snapshots
+* Core encoding logic (no cache). Extracted so cached wrapper can reuse it without duplication.
 */
-function encodeEntityId(id) {
+function encodeEntityIdCore(id) {
 	const detailed = getDetailedIdType(id);
 	switch (detailed.type) {
 		case "component": {
@@ -2343,6 +2821,20 @@ function encodeEntityId(id) {
 	}
 }
 /**
+* Encode an EntityId, using an optional cache Map to avoid repeated getDetailedIdType
+* + name lookup work for IDs that appear many times (typical during full world snapshot).
+*/
+function encodeEntityIdCached(id, cache) {
+	if (cache) {
+		const cached = cache.get(id);
+		if (cached !== void 0) return cached;
+		const result = encodeEntityIdCore(id);
+		cache.set(id, result);
+		return result;
+	}
+	return encodeEntityIdCore(id);
+}
+/**
 * Decode a SerializedEntityId back into an internal EntityId
 */
 function decodeSerializedId(sid) {
@@ -2383,24 +2875,16 @@ function decodeSerializedId(sid) {
 * Serializes the full world state to a plain JS object suitable for JSON encoding.
 */
 function serializeWorld(archetypes, componentEntities, entityIdManager) {
+	const idCache = /* @__PURE__ */ new Map();
 	const entities = [];
 	for (const archetype of archetypes) {
-		const dumpedEntities = archetype.dump();
-		for (const { entity, components } of dumpedEntities) entities.push({
-			id: encodeEntityId(entity),
-			components: Array.from(components.entries()).map(([rawType, value]) => ({
-				type: encodeEntityId(rawType),
-				value: value === MISSING_COMPONENT ? void 0 : value
-			}))
-		});
+		const encodedComponentTypes = archetype.componentTypes.map((t) => encodeEntityIdCached(t, idCache));
+		archetype.appendSerializedEntities(entities, (id) => encodeEntityIdCached(id, idCache), encodedComponentTypes);
 	}
 	const componentEntitiesArr = [];
 	for (const [entityId, components] of componentEntities.entries()) componentEntitiesArr.push({
-		id: encodeEntityId(entityId),
-		components: Array.from(components.entries()).map(([rawType, value]) => ({
-			type: encodeEntityId(rawType),
-			value: value === MISSING_COMPONENT ? void 0 : value
-		}))
+		id: encodeEntityIdCached(entityId, idCache),
+		components: serializeComponentsFromMap(components, idCache)
 	});
 	return {
 		version: 1,
@@ -2409,6 +2893,15 @@ function serializeWorld(archetypes, componentEntities, entityIdManager) {
 		componentEntities: componentEntitiesArr
 	};
 }
+/** Small helper to avoid duplicating the "Map → SerializedComponent[] with cache" pattern. */
+function serializeComponentsFromMap(components, idCache) {
+	const result = [];
+	for (const [rawType, value] of components) result.push({
+		type: encodeEntityIdCached(rawType, idCache),
+		value: value === MISSING_COMPONENT ? void 0 : value
+	});
+	return result;
+}
 /**
 * Restores world state from a snapshot into the provided context.
 * Intended to be called from `World`'s constructor.
@@ -2430,12 +2923,11 @@ function deserializeWorld(ctx, snapshot) {
 		const entityId = decodeSerializedId(entry.id);
 		const componentsArray = entry.components || [];
 		const componentMap = /* @__PURE__ */ new Map();
-		const componentTypes = [];
 		for (const componentEntry of componentsArray) {
 			const componentType = decodeSerializedId(componentEntry.type);
 			componentMap.set(componentType, componentEntry.value);
-			componentTypes.push(componentType);
 		}
+		const componentTypes = Array.from(componentMap.keys());
 		const archetype = ctx.ensureArchetype(componentTypes);
 		archetype.addEntity(entityId, componentMap);
 		ctx.setEntityToArchetype(entityId, archetype);
@@ -2454,45 +2946,60 @@ function deserializeWorld(ctx, snapshot) {
 */
 var World = class {
 	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();
-	/** DontFragment relation storage, shared with all Archetype instances */
-	dontFragmentStore = new DontFragmentStoreImpl();
+	/** 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();
-	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 = {
-		dontFragmentStore: this.dontFragmentStore,
-		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.
@@ -2588,64 +3095,12 @@ 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 } = resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, (id) => this.exists(id));
 		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);
 	}
 	/**
@@ -2662,6 +3117,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;
@@ -2678,9 +3157,9 @@ var World = class {
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) return false;
 		if (archetype.componentTypeSet.has(componentType)) return true;
-		if (isDontFragmentRelation(componentType)) {
-			if (this.dontFragmentStore.getValue(entityId, componentType) !== void 0) return true;
-			return this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType);
+		if (isSparseRelation(componentType)) {
+			if (this.sparseStore.getValue(entityId, componentType) !== void 0) return true;
+			return this.sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType);
 		}
 		return false;
 	}
@@ -2693,8 +3172,8 @@ var World = class {
 		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
 		if (componentType >= 0 || componentType % RELATION_SHIFT !== 0) {
 			const inArchetype = archetype.componentTypeSet.has(componentType);
-			const hasDontFragment = isDontFragmentRelation(componentType);
-			if (!(inArchetype || hasDontFragment && (this.dontFragmentStore.getValue(entityId, componentType) !== void 0 || this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType)))) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
+			const hasSparse = isSparseRelation(componentType);
+			if (!(inArchetype || hasSparse && (this.sparseStore.getValue(entityId, componentType) !== void 0 || this.sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)))) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
 		}
 		return archetype.get(entityId, componentType);
 	}
@@ -2716,6 +3195,163 @@ var World = class {
 		}
 		return archetype.getOptional(entityId, componentType);
 	}
+	/**
+	* Retrieves all targets (and their associated data) for relations of a given
+	* base component on an entity.
+	*
+	* This is the ergonomic replacement for the common pattern:
+	*   world.get(entity, relation(Comp, "*"))
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const children = world.getRelationTargets(parent, ChildOf); // usually []
+	* const items = world.getRelationTargets(player, InInventory);
+	*
+	* // For common hierarchy use cases, prefer the higher-level helpers:
+	* // world.getChildren(parent, ChildOf), world.getParent(child, ChildOf)
+	*/
+	getRelationTargets(entityId, relationComp) {
+		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);
+	}
+	/**
+	* Returns every entity that currently holds a relation of the given base
+	* component pointing at `targetId`.
+	*
+	* This is the efficient **reverse** lookup. For common hierarchy cases,
+	* prefer the higher-level `world.getChildren(parent, ChildOf)` instead.
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const directChildren = world.getRelationSources(ship, ChildOf);
+	*/
+	getRelationSources(targetId, relationComp) {
+		const refs = getEntityReferences(this.entityReferences, targetId);
+		const result = [];
+		for (const [source, relType] of refs) {
+			if (!this.entityToArchetype.has(source) && !this.componentEntities.exists(source)) continue;
+			if (getComponentIdFromRelationId(relType) === relationComp) result.push(source);
+		}
+		return result;
+	}
+	/**
+	* Returns true if the entity has any (or a specific-target) relation of the
+	* given base component.
+	*/
+	hasRelation(entityId, relationComp, targetId) {
+		assertEntityExists(entityId, "Entity", (id) => this.exists(id));
+		if (targetId !== void 0) {
+			const specific = relation(relationComp, targetId);
+			return this.has(entityId, specific);
+		}
+		return this.getRelationTargets(entityId, relationComp).length > 0;
+	}
+	/**
+	* Returns the number of relations of the given base component held by the entity.
+	*/
+	countRelations(entityId, relationComp) {
+		assertEntityExists(entityId, "Entity", (id) => this.exists(id));
+		return this.getRelationTargets(entityId, relationComp).length;
+	}
+	/**
+	* For an *exclusive* relation (e.g. ChildOf, Owner), returns the single
+	* target entity (or undefined if none).
+	*
+	* When the component was declared `exclusive: true`, this is the preferred
+	* accessor (clearer intent than array destructuring).
+	*/
+	getSingleRelationTarget(entityId, relationComp) {
+		const targets = this.getRelationTargets(entityId, relationComp);
+		return targets.length > 0 ? targets[0][0] : void 0;
+	}
+	/**
+	* Returns the direct children of `parent` for the given relationship component
+	* (typically a `ChildOf` or similar exclusive `sparse` relation).
+	*
+	* This is the recommended high-level API for hierarchy traversal.
+	* It uses the internal reverse reference index for efficiency.
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const kids = world.getChildren(ship, ChildOf);
+	*/
+	getChildren(parent, childOf) {
+		return this.getRelationSources(parent, childOf);
+	}
+	/**
+	* Returns the parent of `child` for the given relationship component
+	* (typically an exclusive `ChildOf` relation).
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const parent = world.getParent(turret, ChildOf);
+	*/
+	getParent(child, childOf) {
+		return this.getSingleRelationTarget(child, childOf);
+	}
+	/**
+	* Returns the ancestor chain from the immediate parent up to (but not
+	* including) the root for the given relationship component.
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const ancestors = world.getAncestors(muzzle, ChildOf); // [turret, ship]
+	*/
+	getAncestors(entity, childOf) {
+		const ancestors = [];
+		let cur = this.getParent(entity, childOf);
+		while (cur !== void 0) {
+			ancestors.push(cur);
+			cur = this.getParent(cur, childOf);
+		}
+		return ancestors;
+	}
+	/**
+	* Iteratively traverses all descendants of `root` in DFS pre-order.
+	* This is a generator and is safe for very deep hierarchies.
+	*
+	* @example
+	* for (const { entity, depth, parent } of world.iterateDescendants(root, ChildOf)) {
+	*   console.log(depth, entity);
+	* }
+	*/
+	*iterateDescendants(root, childOf, opts = {}) {
+		const { includeSelf = false, maxDepth } = opts;
+		const stack = [];
+		if (includeSelf) stack.push({
+			entity: root,
+			depth: 0,
+			parent: null
+		});
+		else for (const child of this.getChildren(root, childOf)) stack.push({
+			entity: child,
+			depth: 1,
+			parent: root
+		});
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (maxDepth !== void 0 && current.depth > maxDepth) continue;
+			yield current;
+			const kids = this.getChildren(current.entity, childOf);
+			for (let i = kids.length - 1; i >= 0; i--) {
+				const k = kids[i];
+				stack.push({
+					entity: k,
+					depth: current.depth + 1,
+					parent: current.entity
+				});
+			}
+		}
+	}
+	/**
+	* Callback-based descendant traversal (hot path friendly).
+	* Return `false` from the visitor to stop early.
+	*/
+	traverseDescendants(root, childOf, visitor, opts = {}) {
+		for (const { entity, depth, parent } of this.iterateDescendants(root, childOf, opts)) if (visitor(entity, depth, parent) === false) return;
+	}
 	hook(componentTypes, hook, filter) {
 		const isCallback = typeof hook === "function";
 		const callback = isCallback ? hook : void 0;
@@ -2751,6 +3387,21 @@ var World = class {
 		};
 	}
 	/**
+	* Creates a debug stats collector that will receive a `SyncDebugStats` payload
+	* after every subsequent `sync()`.
+	*
+	* The returned object is a pure lifecycle handle. It does not store data.
+	* Collection stops when you call `[Symbol.dispose]()` (or use a `using` declaration).
+	*
+	* All active collectors receive the exact same stats object for a given sync.
+	* Exceptions thrown by callbacks are ignored.
+	*
+	* This is intended for development/debugging and leak detection.
+	*/
+	createDebugStatsCollector(callback) {
+		return this.debugStats.createCollector(callback);
+	}
+	/**
 	* Synchronizes all buffered commands (set/remove/delete) to the world.
 	* This method must be called after making changes via `set()`, `remove()`, or `delete()` for them to take effect.
 	* Typically called once per frame at the end of your game loop.
@@ -2761,7 +3412,40 @@ var World = class {
 	* world.sync(); // Apply all buffered changes
 	*/
 	sync() {
-		this.commandBuffer.execute();
+		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 = 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
+		});
 	}
 	/**
 	* Creates a cached query for efficiently iterating entities with specific components.
@@ -2797,7 +3481,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);
 	}
 	/**
@@ -2863,44 +3547,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);
@@ -2914,150 +3561,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) {
-			applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype, null);
-			if (hasStructuralChange) this.updateEntityReferences(entityId, changeset);
-			return;
-		}
-		const removedComponents = /* @__PURE__ */ new Map();
-		const newArchetype = applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype, removedComponents);
-		if (hasStructuralChange) this.updateEntityReferences(entityId, changeset);
-		triggerLifecycleHooks(this.createHooksContext(), entityId, changeset.adds, removedComponents, currentArchetype, newArchetype);
-	}
-	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.dontFragmentStore);
-		this.archetypes.push(newArchetype);
-		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 (isDontFragmentWildcard(c)) return true;
-				const componentId = getComponentIdFromRelationId(c);
-				return componentId !== void 0 && archetype.hasRelationWithComponentId(componentId);
-			}
-			return archetype.componentTypeSet.has(c) || isDontFragmentRelation(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();
-		}
-		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.
@@ -3080,11 +3591,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, isWildcardRelationId as c, isEntityId as d, isRelationId as f, component as i, relation as l, Query as n, getComponentNameById as o, EntityBuilder as r, decodeRelationId as s, World as t, isComponentId 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