@codehz/ecs 0.6.11 → 0.7.0

package/world.mjs

@@ -1,4 +1,4 @@
-//#region src/core/entity-types.ts
+//#region src/entity/types.ts
 const COMPONENT_ID_MAX = 1023;
 const ENTITY_ID_START = 1024;
 /**
@@ -32,7 +32,7 @@ function isRelationId(id) {
 }
 
 //#endregion
-//#region src/core/entity-relation.ts
+//#region src/entity/relation.ts
 /**
 * Internal function to decode a relation ID into raw component and target IDs
 * @param id The EntityId to decode
@@ -57,7 +57,10 @@ function relation(componentId, targetId) {
 	return -(componentId * RELATION_SHIFT + actualTargetId);
 }
 /**
-* Check if an ID is a wildcard relation id
+* Check if an ID is a wildcard relation (created with `relation(componentId, "*")`).
+*
+* @param id - The ID to check
+* @returns `true` if the ID is a wildcard relation, `false` otherwise
 */
 function isWildcardRelationId(id) {
 	const decoded = decodeRelationRaw(id);
@@ -169,7 +172,7 @@ function isEntityRelation(id) {
 }
 
 //#endregion
-//#region src/core/entity-manager.ts
+//#region src/entity/manager.ts
 /**
 * Entity ID Manager for automatic allocation and freelist recycling
 */
@@ -362,7 +365,7 @@ var BitSet = class {
 };
 
 //#endregion
-//#region src/core/component-registry.ts
+//#region src/component/registry.ts
 const globalComponentIdAllocator = new ComponentIdAllocator();
 const ComponentIdForNames = /* @__PURE__ */ new Map();
 const componentNames = new Array(COMPONENT_ID_MAX + 1);
@@ -428,8 +431,16 @@ function getBaseComponentId(componentType) {
 	return isValidComponentId(decoded.componentId) ? decoded.componentId : void 0;
 }
 /**
-* Get merge callback for a componentType (including relation component types).
-* Returns undefined if the base component has no merge callback.
+* Get the merge callback for a component type (including relation component types).
+*
+* Looks up the base component's merge function, resolving through relation wrappers.
+* For example, if `ChildOf` has a merge function and you pass `relation(ChildOf, parent)`,
+* the same merge function is returned.
+*
+* @param componentType - A raw component ID or a relation-wrapped component type
+*   (e.g., `relation(MyComp, targetEntity)`).
+* @returns The merge callback if one was registered via {@link ComponentOptions.merge},
+*   or `undefined` if no merge was configured for the base component.
 */
 function getComponentMerge(componentType) {
 	const baseComponentId = getBaseComponentId(componentType);
@@ -437,27 +448,64 @@ function getComponentMerge(componentType) {
 	return componentMerges[baseComponentId];
 }
 /**
-* Check if a component is marked as exclusive
-* @param id The component ID
-* @returns true if the component is exclusive, false otherwise
+* Check if a component was created with `exclusive: true`.
+*
+* This is a fast O(1) bitset lookup that determines whether the component enforces
+* the one-to-one relation constraint — an entity can have at most one relation of
+* this component type, and setting a new relation target automatically removes the
+* previous one.
+*
+* **Note**: This only checks the component's intrinsic property, not whether a
+* specific entity/relation ID is actually an exclusive relation. For checking
+* runtime relation IDs (including wildcards), use {@link isExclusiveRelation}
+* or {@link isExclusiveWildcard}.
+*
+* @param id - The component ID to check. Must be a plain component ID (1–1023),
+*   not a relation-wrapped ID.
+* @returns `true` if the component was created with `exclusive: true`.
+*
+* @see {@link ComponentOptions.exclusive} for the full explanation of exclusive
+*   relation behavior.
+* @see {@link isExclusiveRelation} for checking specific-target exclusive relations.
+* @see {@link isExclusiveWildcard} for checking wildcard exclusive relations.
 */
 function isExclusiveComponent(id) {
 	return exclusiveFlags.has(id);
 }
 /**
-* Check if a component is marked as dontFragment
-* @param id The component ID
-* @returns true if the component is dontFragment, false otherwise
+* Check if a component is marked as `dontFragment`.
+*
+* 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.
+*
+* @param id - The component ID to check.
+* @returns `true` if the component was created with `dontFragment: true`.
+*
+* @see {@link ComponentOptions.dontFragment} for the full explanation of how
+*   `dontFragment` prevents archetype fragmentation.
 */
 function isDontFragmentComponent(id) {
 	return dontFragmentFlags.has(id);
 }
 /**
-* Generic function to check relation flags with specific target conditions
-* @param id The entity/relation ID to check
-* @param flagBitSet The bitset for the flag
-* @param targetCondition Function to check target ID condition
-* @returns true if the condition is met, false otherwise
+* Generic optimized function to check whether a relation ID's base component
+* has a specific flag in a bitset.
+*
+* Avoids the overhead of `getDetailedIdType` by directly decoding the relation
+* 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`.
+*
+* @param id - The entity/relation ID to check.
+* @param flagBitSet - The bitset tracking which component IDs have the flag.
+* @param targetCondition - Predicate on the target ID (e.g., check for wildcard
+*   vs. specific entity target).
+* @returns `true` if the relation's base component has the flag and the target
+*   condition is met.
 */
 function checkRelationFlag(id, flagBitSet, targetCondition) {
 	const decoded = decodeRelationRaw(id);
@@ -466,42 +514,104 @@ function checkRelationFlag(id, flagBitSet, targetCondition) {
 	return isValidComponentId(componentId) && targetCondition(targetId) && flagBitSet.has(componentId);
 }
 /**
-* Check if a relation ID is a dontFragment relation (entity-relation or component-relation with dontFragment component)
-* This is an optimized function that avoids the overhead of getDetailedIdType
-* @param id The entity/relation ID to check
-* @returns true if this is a dontFragment relation, false otherwise
+* Check if an ID is a specific (non-wildcard) relation backed by a `dontFragment`
+* component.
+*
+* 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.
+*
+* @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`.
+*
+* @see {@link isDontFragmentWildcard} for the wildcard variant.
+* @see {@link ComponentOptions.dontFragment} for the full explanation.
 */
 function isDontFragmentRelation(id) {
 	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
 }
 /**
-* Check if an ID is a wildcard relation with dontFragment component
-* This is an optimized function for filtering archetype component types
-* @param id The entity/relation ID to check
-* @returns true if this is a wildcard relation with dontFragment component, false otherwise
+* 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.
+*
+* 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.
+*
+* @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`.
+*
+* @see {@link isDontFragmentRelation} for the specific-target variant.
+* @see {@link ComponentOptions.dontFragment} for the full explanation.
 */
 function isDontFragmentWildcard(id) {
 	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
 }
 /**
-* Check if a relation ID is a cascade delete entity-relation
-* This is an optimized function that avoids the overhead of getDetailedIdType
-* Note: Cascade delete only applies to entity-relations (not component-relations or wildcards)
+* Check if a relation ID is a cascade delete entity-relation.
+*
+* This is an optimized function that avoids the overhead of getDetailedIdType.
+*
+* Cascade delete only applies to entity-relations (not component-relations or
+* wildcards). When a cascade-delete-marked relation's target entity is deleted,
+* the **entire source entity** (the one holding the relation) is deleted — not
+* just the relation component. Without cascade delete, the relation component
+* is simply removed (which is the default cleanup for all relations when their
+* target is deleted).
+*
 * @param id The entity/relation ID to check
 * @returns true if this is an entity-relation with cascade delete, false otherwise
+* @see {@link ComponentOptions.cascadeDelete}
 */
 function isCascadeDeleteRelation(id) {
 	return checkRelationFlag(id, cascadeDeleteFlags, (targetId) => targetId !== WILDCARD_TARGET_ID && targetId >= ENTITY_ID_START);
 }
 
 //#endregion
-//#region src/core/builder.ts
+//#region src/world/builder.ts
+/**
+* Fluent API for constructing entities with multiple components.
+* Create instances via {@link World.spawn}.
+*
+* @example
+* const entity = world.spawn()
+*   .with(Position, { x: 0, y: 0 })
+*   .withRelation(Parent, parentEntity)
+*   .build();
+* world.sync();
+*/
 var EntityBuilder = class {
 	world;
 	components = [];
 	constructor(world) {
 		this.world = world;
 	}
+	/**
+	* Add a regular component to the entity under construction.
+	*
+	* @template T - The component data type
+	* @param componentId - The component type to add
+	* @param args - Component data (omit for void components)
+	* @returns This builder for chaining
+	*
+	* @example
+	* builder.with(Position, { x: 10, y: 20 });
+	* builder.with(Marker); // void component
+	*/
 	with(componentId, ...args) {
 		const value = args.length > 0 ? args[0] : void 0;
 		this.components.push({
@@ -512,16 +622,18 @@ var EntityBuilder = class {
 		return this;
 	}
 	/**
-	* @deprecated Use `with(componentId)` instead for void components
+	* Add a relation component to the entity under construction.
+	*
+	* @template T - The relation data type
+	* @param componentId - The base component type for the relation
+	* @param targetEntity - The target entity or component for the relation
+	* @param args - Relation data (omit for void relations)
+	* @returns This builder for chaining
+	*
+	* @example
+	* builder.withRelation(Parent, parentEntity);
+	* builder.withRelation(ChildOf, childEntity, { order: 1 });
 	*/
-	withTag(componentId) {
-		this.components.push({
-			type: "component",
-			id: componentId,
-			value: void 0
-		});
-		return this;
-	}
 	withRelation(componentId, targetEntity, ...args) {
 		const value = args.length > 0 ? args[0] : void 0;
 		this.components.push({
@@ -533,22 +645,16 @@ var EntityBuilder = class {
 		return this;
 	}
 	/**
-	* @deprecated Use `withRelation(componentId, targetEntity)` instead for void relations
-	*/
-	withRelationTag(componentId, targetEntity) {
-		this.components.push({
-			type: "relation",
-			componentId,
-			targetId: targetEntity,
-			value: void 0
-		});
-		return this;
-	}
-	/**
-	* Create an entity and enqueue components to be applied. This method
-	* does NOT call `world.sync()` automatically; callers must invoke
-	* `world.sync()` to apply deferred commands.
-	* (Previously auto-synced; now a breaking change — buildDeferred() removed.)
+	* Create the entity and enqueue all configured components.
+	* The entity and components are only materialised after {@link World.sync} is called.
+	*
+	* @returns The newly created entity ID
+	*
+	* @example
+	* const entity = world.spawn()
+	*   .with(Position, { x: 0, y: 0 })
+	*   .build();
+	* world.sync(); // Apply changes
 	*/
 	build() {
 		const entity = this.world.new();
@@ -562,867 +668,1115 @@ var EntityBuilder = class {
 };
 
 //#endregion
-//#region src/commands/changeset.ts
+//#region src/component/type-utils.ts
 /**
-* @internal Represents a set of component changes to be applied to an entity
+* Normalize component type collections into a stable ascending order.
+* This keeps cache keys and archetype signatures deterministic.
 */
-var ComponentChangeset = class {
-	adds = /* @__PURE__ */ new Map();
-	removes = /* @__PURE__ */ new Set();
+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
+*/
+/**
+* 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/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;
+	}
+	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;
+}
+/**
+* Find all relations in dontFragment data that match a component ID
+*/
+function findMatchingDontFragmentRelations(dontFragmentData, componentId, relations = []) {
+	if (!dontFragmentData) return relations;
+	for (const [relType, data] of dontFragmentData) {
+		const relDetailed = getDetailedIdType(relType);
+		if (isRelationType(relDetailed) && relDetailed.componentId === componentId) relations.push([relDetailed.targetId, data]);
+	}
+	return relations;
+}
+/**
+* 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
+*/
+function buildWildcardRelationValue(wildcardRelationType, matchingRelations, getDataAtIndex, dontFragmentData, 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]);
+	}
+	if (targetComponentId !== void 0) findMatchingDontFragmentRelations(dontFragmentData, targetComponentId, relations);
+	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;
+	}
+	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, 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.get(entityId), 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");
+/**
+* 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 {
 	/**
-	* Add a component to the changeset
+	* The component types that define this archetype
 	*/
-	set(componentType, component$1) {
-		this.adds.set(componentType, component$1);
-		this.removes.delete(componentType);
-	}
+	componentTypes;
 	/**
-	* Remove a component from the changeset
+	* Set version of componentTypes for O(1) lookups in hot paths
 	*/
-	delete(componentType) {
-		this.removes.add(componentType);
-		this.adds.delete(componentType);
-	}
+	componentTypeSet;
 	/**
-	* Check if the changeset has any changes
+	* List of entities in this archetype
 	*/
-	hasChanges() {
-		return this.adds.size > 0 || this.removes.size > 0;
-	}
+	entities = [];
 	/**
-	* Clear all changes
+	* Component data storage - maps component type to array of component data
+	* Each array index corresponds to the entity index in the entities array
 	*/
-	clear() {
-		this.adds.clear();
-		this.removes.clear();
-	}
+	componentData = /* @__PURE__ */ new Map();
 	/**
-	* Merge another changeset into this one
+	* Reverse mapping from entity to its index in this archetype
 	*/
-	merge(other) {
-		for (const [componentType, component$1] of other.adds) {
-			this.adds.set(componentType, component$1);
-			this.removes.delete(componentType);
-		}
-		for (const componentType of other.removes) {
-			this.removes.add(componentType);
-			this.adds.delete(componentType);
-		}
-	}
+	entityToIndex = /* @__PURE__ */ new Map();
 	/**
-	* Apply the changeset to existing components and return the final state
+	* DontFragmentStore for relation data keyed by entity ID.
+	* This allows entities with different relation targets to share the same archetype
+	* without migration overhead when entities change archetypes.
 	*/
-	applyTo(existingComponents) {
-		for (const componentType of this.removes) existingComponents.delete(componentType);
-		for (const [componentType, component$1] of this.adds) existingComponents.set(componentType, component$1);
-		return existingComponents;
-	}
+	dontFragmentRelations;
 	/**
-	* 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
+	* Multi-hooks that match this archetype
 	*/
-	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/commands/command-buffer.ts
-/**
-* Maximum number of command buffer execution iterations to prevent infinite loops
-*/
-const MAX_COMMAND_ITERATIONS = 100;
-/**
-* Command buffer for deferred structural changes
-*/
-var CommandBuffer = class {
-	commands = [];
-	swapBuffer = [];
-	/** Reusable map to group commands by entity, avoids per-sync allocations */
-	entityCommands = /* @__PURE__ */ new Map();
-	executeEntityCommands;
+	matchingMultiHooks = /* @__PURE__ */ new Set();
 	/**
-	* Create a command buffer with an executor function
+	* Cache for pre-computed component data sources to avoid repeated calculations
 	*/
-	constructor(executeEntityCommands) {
-		this.executeEntityCommands = executeEntityCommands;
+	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, []);
 	}
-	set(entityId, componentType, component$1) {
-		this.commands.push({
-			type: "set",
-			entityId,
-			componentType,
-			component: component$1
-		});
+	get size() {
+		return this.entities.length;
 	}
 	/**
-	* Remove a component from an entity (deferred)
+	* 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
 	*/
-	remove(entityId, componentType) {
-		this.commands.push({
-			type: "delete",
-			entityId,
-			componentType
-		});
+	matches(componentTypes) {
+		if (this.componentTypes.length !== componentTypes.length) return false;
+		const sortedTypes = normalizeComponentTypes(componentTypes);
+		return this.componentTypes.every((type, index) => type === sortedTypes[index]);
 	}
-	/**
-	* Destroy an entity (deferred)
-	*/
-	delete(entityId) {
-		this.commands.push({
-			type: "destroy",
-			entityId
+	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.addDontFragmentRelations(entityId, componentData);
+	}
+	addDontFragmentRelations(entityId, componentData) {
+		const dontFragmentData = /* @__PURE__ */ new Map();
+		for (const [componentType, data] of componentData) {
+			if (this.componentTypeSet.has(componentType)) continue;
+			const detailedType = getDetailedIdType(componentType);
+			if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId)) dontFragmentData.set(componentType, data);
+		}
+		if (dontFragmentData.size > 0) this.dontFragmentRelations.set(entityId, dontFragmentData);
+	}
+	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 dontFragmentData = this.dontFragmentRelations.get(entityId);
+		if (dontFragmentData) for (const [componentType, data] of dontFragmentData) entityData.set(componentType, data);
+		return entityData;
+	}
+	getEntityDontFragmentRelations(entityId) {
+		return this.dontFragmentRelations.get(entityId);
+	}
+	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 dontFragmentData = this.dontFragmentRelations.get(entity);
+			if (dontFragmentData) for (const [componentType, data] of dontFragmentData) components.set(componentType, data);
+			return {
+				entity,
+				components
+			};
 		});
 	}
-	/**
-	* Execute all commands and clear the buffer
-	*/
-	execute() {
-		let iterations = 0;
-		while (this.commands.length > 0) {
-			if (iterations >= MAX_COMMAND_ITERATIONS) throw new Error("Command execution exceeded maximum iterations, possible infinite loop");
-			iterations++;
-			const currentCommands = this.commands;
-			this.commands = this.swapBuffer;
-			const entityCommands = this.entityCommands;
-			for (const cmd of currentCommands) {
-				const existing = entityCommands.get(cmd.entityId);
-				if (existing !== void 0) existing.push(cmd);
-				else entityCommands.set(cmd.entityId, [cmd]);
+	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 dontFragmentData = this.dontFragmentRelations.get(entityId);
+		if (dontFragmentData) {
+			for (const [componentType, data] of dontFragmentData) removedData.set(componentType, data);
+			this.dontFragmentRelations.delete(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];
 			}
-			currentCommands.length = 0;
-			this.swapBuffer = currentCommands;
-			for (const [entityId, commands] of entityCommands) this.executeEntityCommands(entityId, commands);
-			entityCommands.clear();
 		}
+		this.entities.pop();
+		for (const componentType of this.componentTypes) this.getComponentData(componentType).pop();
+		return removedData;
 	}
-	/**
-	* Get current commands (for testing)
-	*/
-	getCommands() {
-		return [...this.commands];
+	exists(entityId) {
+		return this.entityToIndex.has(entityId);
 	}
-	/**
-	* Clear all commands
-	*/
-	clear() {
-		this.commands = [];
+	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);
 	}
-};
-
-//#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 && isDontFragmentComponent(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/core/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/query/query.ts
-/**
-* Query class for efficient entity queries with cached archetypes
-*/
-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;
-	constructor(world, componentTypes, filter = {}) {
-		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();
-		world._registerQuery(this);
+	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) findMatchingDontFragmentRelations(this.dontFragmentRelations.get(entityId), componentId, relations);
+		return relations;
 	}
-	/**
-	* Check if query is disposed and throw error if so
-	*/
-	ensureNotDisposed() {
-		if (this.isDisposed) throw new Error("Query has been disposed");
+	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;
+		}
+		const dontFragmentData = this.dontFragmentRelations.get(entityId);
+		if (dontFragmentData?.has(componentType)) return dontFragmentData.get(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 dontFragmentData = this.dontFragmentRelations.get(entityId);
+		if (dontFragmentData?.has(componentType)) return { value: dontFragmentData.get(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)) {
+			let dontFragmentData = this.dontFragmentRelations.get(entityId);
+			if (!dontFragmentData) {
+				dontFragmentData = /* @__PURE__ */ new Map();
+				this.dontFragmentRelations.set(entityId, dontFragmentData);
+			}
+			dontFragmentData.set(componentType, data);
+			return;
+		}
+		throw new Error(`Component type ${componentType} is not in this archetype`);
 	}
-	/**
-	* Get all entities matching the query
-	*/
 	getEntities() {
-		this.ensureNotDisposed();
-		if (this.wildcardTypes.length === 0 && this.specificDontFragmentTypes.length === 0) {
-			const result$1 = [];
-			for (const archetype of this.cachedArchetypes) result$1.push(...archetype.getEntities());
-			return result$1;
-		}
-		const result = [];
-		for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) if (this.entityMatchesQuery(archetype, entity)) result.push(entity);
-		return result;
+		return this.entities;
 	}
-	/**
-	* 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;
-		}
-		for (const specificType of this.specificDontFragmentTypes) if (archetype.getOptional(entity, specificType) === void 0) return false;
-		return true;
+	getEntityToIndexMap() {
+		return this.entityToIndex;
 	}
-	/**
-	* Get entities with their component data
-	* @param componentTypes Array of component types to retrieve
-	* @returns Array of objects with entity and component data
-	*/
-	getEntitiesWithComponents(componentTypes) {
-		this.ensureNotDisposed();
-		const result = [];
-		for (const archetype of this.cachedArchetypes) {
-			const entitiesWithData = archetype.getEntitiesWithComponents(componentTypes);
-			result.push(...entitiesWithData);
-		}
-		return result;
+	getComponentData(componentType) {
+		const data = this.componentData.get(componentType);
+		if (!data) throw new Error(`Component type ${componentType} is not in this archetype`);
+		return data;
 	}
-	/**
-	* Iterate over entities with their component data
-	* @param componentTypes Array of component types to retrieve
-	* @param callback Function called for each entity with its components
-	*/
-	forEach(componentTypes, callback) {
-		this.ensureNotDisposed();
-		for (const archetype of this.cachedArchetypes) archetype.forEachWithComponents(componentTypes, callback);
+	getOptionalComponentData(componentType) {
+		return this.componentData.get(componentType);
 	}
-	/**
-	* Iterate over entities with their component data (generator)
-	* @param componentTypes Array of component types to retrieve
-	*/
-	*iterate(componentTypes) {
-		this.ensureNotDisposed();
-		for (const archetype of this.cachedArchetypes) yield* archetype.iterateWithComponents(componentTypes);
+	getCachedComponentDataSources(componentTypes) {
+		const cacheKey = buildCacheKey(componentTypes);
+		return getOrCompute(this.componentDataSourcesCache, cacheKey, () => componentTypes.map((compType) => this.getComponentDataSource(compType)));
 	}
-	/**
-	* Get component data arrays for all matching entities
-	* @param componentType The component type to retrieve
-	* @returns Array of component data for all matching entities
-	*/
-	getComponentData(componentType) {
-		this.ensureNotDisposed();
-		const result = [];
-		for (const archetype of this.cachedArchetypes) result.push(...archetype.getComponentData(componentType));
-		return result;
+	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);
 	}
-	/**
-	* Update the cached archetypes
-	* Called when new archetypes are created
-	*/
-	updateCache() {
-		if (this.isDisposed) return;
-		this.cachedArchetypes = this.world.getMatchingArchetypes(this.componentTypes).filter((archetype) => matchesFilter(archetype, this.filter));
+	buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entityId) {
+		return componentDataSources.map((dataSource, i) => buildSingleComponent(componentTypes[i], dataSource, entityIndex, entityId, (type) => this.getComponentData(type), this.dontFragmentRelations));
 	}
-	/**
-	* Check if a new archetype matches this query and add to cache if it does
-	*/
-	checkNewArchetype(archetype) {
-		if (this.isDisposed) return;
-		if (matchesComponentTypes(archetype, this.componentTypes) && matchesFilter(archetype, this.filter) && !this.cachedArchetypes.includes(archetype)) this.cachedArchetypes.push(archetype);
+	getEntitiesWithComponents(componentTypes) {
+		const result = [];
+		this.appendEntitiesWithComponents(componentTypes, result);
+		return result;
 	}
-	/**
-	* Remove an archetype from the cached archetypes
-	*/
-	removeArchetype(archetype) {
-		if (this.isDisposed) return;
-		const index = this.cachedArchetypes.indexOf(archetype);
-		if (index !== -1) this.cachedArchetypes.splice(index, 1);
+	appendEntitiesWithComponents(componentTypes, result) {
+		this.forEachWithComponents(componentTypes, (entity, ...components) => {
+			result.push({
+				entity,
+				components
+			});
+		});
 	}
-	/**
-	* 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);
+	*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)];
+		}
 	}
-	/**
-	* Internal full dispose called by World when refCount reaches zero.
-	*/
-	_disposeInternal() {
-		if (!this.isDisposed) {
-			this.world._unregisterQuery(this);
-			this.cachedArchetypes = [];
-			this.isDisposed = true;
+	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));
 		}
 	}
-	/**
-	* Symbol.dispose implementation for automatic resource management
-	*/
-	[Symbol.dispose]() {
-		this.dispose();
+	forEach(callback) {
+		for (let i = 0; i < this.entities.length; 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);
+			}
+			callback(this.entities[i], components);
+		}
 	}
-	/**
-	* Check if the query has been disposed
-	*/
-	get disposed() {
-		return this.isDisposed;
+	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) {
+			const entityDontFragmentRelations = this.dontFragmentRelations.get(entityId);
+			if (entityDontFragmentRelations) for (const relationType of entityDontFragmentRelations.keys()) {
+				const detailedType = getDetailedIdType(relationType);
+				if (isRelationType(detailedType) && detailedType.componentId === componentId) return true;
+			}
+		}
+		return false;
 	}
 };
 
 //#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/core/types.ts
-function isOptionalEntityId(type) {
-	return typeof type === "object" && type !== null && "optional" in type;
-}
-
-//#endregion
-//#region src/core/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;
-	}
-	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;
-}
-/**
-* Find all relations in dontFragment data that match a component ID
-*/
-function findMatchingDontFragmentRelations(dontFragmentData, componentId) {
-	const relations = [];
-	if (!dontFragmentData) return relations;
-	for (const [relType, data] of dontFragmentData) {
-		const relDetailed = getDetailedIdType(relType);
-		if (isRelationType(relDetailed) && relDetailed.componentId === componentId) relations.push([relDetailed.targetId, data]);
-	}
-	return relations;
-}
-/**
-* 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;
-}
+//#region src/archetype/store.ts
 /**
-* Build wildcard relation value from matching relations
+* Default implementation backed by a plain `Map`.
+* Created once by `World` and shared with every `Archetype`.
 */
-function buildWildcardRelationValue(wildcardRelationType, matchingRelations, getDataAtIndex, dontFragmentData, 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]);
-	}
-	if (targetComponentId !== void 0) relations.push(...findMatchingDontFragmentRelations(dontFragmentData, targetComponentId));
-	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;
+var DontFragmentStoreImpl = class {
+	data = /* @__PURE__ */ new Map();
+	get(entityId) {
+		return this.data.get(entityId);
 	}
-	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(entityId, data) {
+		this.data.set(entityId, data);
 	}
-	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.get(entityId), entityId, optional);
-	else return buildRegularComponentValue(dataSource, entityIndex, optional);
-}
+	delete(entityId) {
+		this.data.delete(entityId);
+	}
+};
 
 //#endregion
-//#region src/core/archetype.ts
+//#region src/commands/buffer.ts
 /**
-* Special value to represent missing component data
+* Maximum number of command buffer execution iterations to prevent infinite loops
 */
-const MISSING_COMPONENT = Symbol("missing component");
+const MAX_COMMAND_ITERATIONS = 100;
 /**
-* Archetype class for ECS architecture
-* Represents a group of entities that share the same set of components
-* Optimized for fast iteration and component access
+* Command buffer for deferred structural changes
 */
-var Archetype = class {
+var CommandBuffer = class {
+	commands = [];
+	swapBuffer = [];
+	/** Reusable map to group commands by entity, avoids per-sync allocations */
+	entityCommands = /* @__PURE__ */ new Map();
+	executeEntityCommands;
 	/**
-	* The component types that define this archetype
+	* Create a command buffer with an executor function
 	*/
-	componentTypes;
+	constructor(executeEntityCommands) {
+		this.executeEntityCommands = executeEntityCommands;
+	}
+	set(entityId, componentType, component$1) {
+		this.commands.push({
+			type: "set",
+			entityId,
+			componentType,
+			component: component$1
+		});
+	}
 	/**
-	* Set version of componentTypes for O(1) lookups in hot paths
+	* Remove a component from an entity (deferred)
 	*/
-	componentTypeSet;
+	remove(entityId, componentType) {
+		this.commands.push({
+			type: "delete",
+			entityId,
+			componentType
+		});
+	}
 	/**
-	* List of entities in this archetype
+	* Destroy an entity (deferred)
 	*/
-	entities = [];
+	delete(entityId) {
+		this.commands.push({
+			type: "destroy",
+			entityId
+		});
+	}
 	/**
-	* Component data storage - maps component type to array of component data
-	* Each array index corresponds to the entity index in the entities array
+	* Execute all commands and clear the buffer
 	*/
-	componentData = /* @__PURE__ */ new Map();
+	execute() {
+		let iterations = 0;
+		while (this.commands.length > 0) {
+			if (iterations >= MAX_COMMAND_ITERATIONS) throw new Error("Command execution exceeded maximum iterations, possible infinite loop");
+			iterations++;
+			const currentCommands = this.commands;
+			this.commands = this.swapBuffer;
+			const entityCommands = this.entityCommands;
+			for (const cmd of currentCommands) {
+				const existing = entityCommands.get(cmd.entityId);
+				if (existing !== void 0) existing.push(cmd);
+				else entityCommands.set(cmd.entityId, [cmd]);
+			}
+			currentCommands.length = 0;
+			this.swapBuffer = currentCommands;
+			for (const [entityId, commands] of entityCommands) this.executeEntityCommands(entityId, commands);
+			entityCommands.clear();
+		}
+	}
 	/**
-	* Reverse mapping from entity to its index in this archetype
+	* Get current commands (for testing)
 	*/
-	entityToIndex = /* @__PURE__ */ new Map();
+	getCommands() {
+		return [...this.commands];
+	}
 	/**
-	* Reference to dontFragment relations storage from World
-	* This allows entities with different relation targets to share the same archetype
-	* Stored in World to avoid migration overhead when entities change archetypes
+	* Clear all commands
 	*/
-	dontFragmentRelations;
+	clear() {
+		this.commands = [];
+	}
+};
+
+//#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();
 	/**
-	* Multi-hooks that match this archetype
+	* Add a component to the changeset
 	*/
-	matchingMultiHooks = /* @__PURE__ */ new Set();
+	set(componentType, component$1) {
+		this.adds.set(componentType, component$1);
+		this.removes.delete(componentType);
+	}
 	/**
-	* Cache for pre-computed component data sources to avoid repeated calculations
+	* Remove a component from the changeset
 	*/
-	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;
+	delete(componentType) {
+		this.removes.add(componentType);
+		this.adds.delete(componentType);
 	}
 	/**
-	* 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
+	* Check if the changeset has any changes
 	*/
-	matches(componentTypes) {
-		if (this.componentTypes.length !== componentTypes.length) return false;
-		const sortedTypes = normalizeComponentTypes(componentTypes);
-		return this.componentTypes.every((type, index) => type === sortedTypes[index]);
+	hasChanges() {
+		return this.adds.size > 0 || this.removes.size > 0;
 	}
-	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.addDontFragmentRelations(entityId, componentData);
+	/**
+	* Clear all changes
+	*/
+	clear() {
+		this.adds.clear();
+		this.removes.clear();
 	}
-	addDontFragmentRelations(entityId, componentData) {
-		const dontFragmentData = /* @__PURE__ */ new Map();
-		for (const [componentType, data] of componentData) {
-			if (this.componentTypeSet.has(componentType)) continue;
-			const detailedType = getDetailedIdType(componentType);
-			if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId)) dontFragmentData.set(componentType, data);
+	/**
+	* Merge another changeset into this one
+	*/
+	merge(other) {
+		for (const [componentType, component$1] of other.adds) {
+			this.adds.set(componentType, component$1);
+			this.removes.delete(componentType);
 		}
-		if (dontFragmentData.size > 0) this.dontFragmentRelations.set(entityId, dontFragmentData);
-	}
-	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);
+		for (const componentType of other.removes) {
+			this.removes.add(componentType);
+			this.adds.delete(componentType);
 		}
-		const dontFragmentData = this.dontFragmentRelations.get(entityId);
-		if (dontFragmentData) for (const [componentType, data] of dontFragmentData) entityData.set(componentType, data);
-		return entityData;
 	}
-	getEntityDontFragmentRelations(entityId) {
-		return this.dontFragmentRelations.get(entityId);
+	/**
+	* Apply the changeset to existing components and return the final state
+	*/
+	applyTo(existingComponents) {
+		for (const componentType of this.removes) existingComponents.delete(componentType);
+		for (const [componentType, component$1] of this.adds) existingComponents.set(componentType, component$1);
+		return existingComponents;
 	}
-	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);
+	/**
+	* 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
+	*/
+	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;
 			}
-			const dontFragmentData = this.dontFragmentRelations.get(entity);
-			if (dontFragmentData) for (const [componentType, data] of dontFragmentData) 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 dontFragmentData = this.dontFragmentRelations.get(entityId);
-		if (dontFragmentData) {
-			for (const [componentType, data] of dontFragmentData) removedData.set(componentType, data);
-			this.dontFragmentRelations.delete(entityId);
+			changed = true;
+			finalComponentTypes.delete(componentType);
 		}
-		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];
-			}
+		for (const componentType of this.adds.keys()) {
+			if (finalComponentTypes.has(componentType)) continue;
+			changed = true;
+			finalComponentTypes.add(componentType);
 		}
-		this.entities.pop();
-		for (const componentType of this.componentTypes) this.getComponentData(componentType).pop();
-		return removedData;
+		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();
+	/**
+	* 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.
+	*/
+	exists(entityId) {
+		const detailed = getDetailedIdType(entityId);
+		return detailed.type !== "entity" && detailed.type !== "invalid";
+	}
+	/**
+	* Check if a component entity has a specific component.
+	*/
+	has(entityId, componentType) {
+		return this.componentEntityComponents.get(entityId)?.has(componentType) ?? false;
+	}
+	/**
+	* 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;
 	}
-	exists(entityId) {
-		return this.entityToIndex.has(entityId);
+	/**
+	* Check if a component entity has any wildcard relations matching a component ID.
+	*/
+	hasWildcard(entityId, componentId) {
+		const data = this.componentEntityComponents.get(entityId);
+		if (!data) return false;
+		return hasWildcardRelation(data, componentId);
 	}
+	/**
+	* Get a component value from a component entity.
+	* Throws if the component does not exist.
+	*/
 	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);
+		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);
 	}
-	getWildcardRelations(entityId, index, componentType) {
-		const componentId = getComponentIdFromRelationId(componentType);
+	/**
+	* 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) };
+	}
+	/**
+	* 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 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]);
-				}
-			}
+		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]);
 		}
-		if (componentId !== void 0) relations.push(...findMatchingDontFragmentRelations(this.dontFragmentRelations.get(entityId), componentId));
 		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;
-		}
-		const dontFragmentData = this.dontFragmentRelations.get(entityId);
-		if (dontFragmentData?.has(componentType)) return dontFragmentData.get(componentType);
-		throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
+	/**
+	* Clear all data for a component entity.
+	*/
+	clear(entityId) {
+		if (this.componentEntityComponents.delete(entityId)) this.unregisterRelationEntityId(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 dontFragmentData = this.dontFragmentRelations.get(entityId);
-		if (dontFragmentData?.has(componentType)) return { value: dontFragmentData.get(componentType) };
+	/**
+	* 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);
 	}
-	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;
+	/**
+	* Execute a batch of commands for a component entity.
+	*/
+	executeCommands(entityId, commands) {
+		if (commands.some((cmd) => cmd.type === "destroy")) {
+			this.clear(entityId);
 			return;
 		}
-		const detailedType = getDetailedIdType(componentType);
-		if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId)) {
-			let dontFragmentData = this.dontFragmentRelations.get(entityId);
-			if (!dontFragmentData) {
-				dontFragmentData = /* @__PURE__ */ new Map();
-				this.dontFragmentRelations.set(entityId, dontFragmentData);
+		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);
 			}
-			dontFragmentData.set(componentType, 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);
+				}
+			} 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;
 		}
-		throw new Error(`Component type ${componentType} is not in this archetype`);
+		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 && isDontFragmentComponent(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.
+*
+* 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;
+* });
+*/
+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");
 	}
+	/**
+	* 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() {
-		return this.entities;
+		this.ensureNotDisposed();
+		if (this.wildcardTypes.length === 0 && this.specificDontFragmentTypes.length === 0) {
+			const result$1 = [];
+			for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) result$1.push(entity);
+			return result$1;
+		}
+		const result = [];
+		for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) if (this.entityMatchesQuery(archetype, entity)) result.push(entity);
+		return result;
+	}
+	/**
+	* 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;
+		}
+		for (const specificType of this.specificDontFragmentTypes) 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);
 	}
-	getEntityToIndexMap() {
-		return this.entityToIndex;
+	/**
+	* 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) {
-		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)));
+		this.ensureNotDisposed();
+		const result = [];
+		for (const archetype of this.cachedArchetypes) for (const data of archetype.getComponentData(componentType)) result.push(data);
+		return result;
 	}
-	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);
+	/**
+	* @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));
 	}
-	buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entityId) {
-		return componentDataSources.map((dataSource, i) => buildSingleComponent(componentTypes[i], dataSource, entityIndex, entityId, (type) => this.getComponentData(type), this.dontFragmentRelations));
+	/**
+	* @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);
 	}
-	getEntitiesWithComponents(componentTypes) {
-		const result = [];
-		this.forEachWithComponents(componentTypes, (entity, ...components) => {
-			result.push({
-				entity,
-				components
-			});
-		});
-		return result;
+	/**
+	* @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);
 	}
-	*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)];
-		}
+	/**
+	* 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);
 	}
-	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));
+	/**
+	* @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;
 		}
 	}
-	forEach(callback) {
-		for (let i = 0; i < this.entities.length; 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);
-			}
-			callback(this.entities[i], components);
-		}
+	/**
+	* 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();
 	}
-	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) {
-			const entityDontFragmentRelations = this.dontFragmentRelations.get(entityId);
-			if (entityDontFragmentRelations) for (const relationType of entityDontFragmentRelations.keys()) {
-				const detailedType = getDetailedIdType(relationType);
-				if (isRelationType(detailedType) && detailedType.componentId === componentId) return true;
-			}
-		}
-		return false;
+	/**
+	* Whether the query has been disposed and can no longer be used.
+	*/
+	get disposed() {
+		return this.isDisposed;
 	}
 };
 
 //#endregion
-//#region src/core/serialization.ts
+//#region src/query/registry.ts
 /**
-* Encode an internal EntityId into a SerializedEntityId for snapshots
+* 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.
 */
-function encodeEntityId(id) {
-	const detailed = getDetailedIdType(id);
-	switch (detailed.type) {
-		case "component": {
-			const name = getComponentNameById(id);
-			if (!name) console.warn(`Component ID ${id} has no registered name, serializing as number`);
-			return name || id;
-		}
-		case "entity-relation": {
-			const componentName = getComponentNameById(detailed.componentId);
-			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
-			return {
-				component: componentName || detailed.componentId.toString(),
-				target: detailed.targetId
-			};
-		}
-		case "component-relation": {
-			const componentName = getComponentNameById(detailed.componentId);
-			const targetName = getComponentNameById(detailed.targetId);
-			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
-			if (!targetName) console.warn(`Target component ID ${detailed.targetId} in relation has no registered name`);
-			return {
-				component: componentName || detailed.componentId.toString(),
-				target: targetName || detailed.targetId
-			};
-		}
-		case "wildcard-relation": {
-			const componentName = getComponentNameById(detailed.componentId);
-			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
-			return {
-				component: componentName || detailed.componentId.toString(),
-				target: "*"
-			};
+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;
 		}
-		default: return id;
+		const query = new Query(world, sortedTypes, filter, this);
+		this.cacheKeys.set(query, key);
+		this.cache.set(key, {
+			query,
+			refCount: 1
+		});
+		return query;
 	}
-}
-/**
-* Decode a SerializedEntityId back into an internal EntityId
-*/
-function decodeSerializedId(sid) {
-	if (typeof sid === "number") return sid;
-	if (typeof sid === "string") {
-		const id = getComponentIdByName(sid);
-		if (id === void 0) {
-			const num = parseInt(sid, 10);
-			if (!isNaN(num)) return num;
-			throw new Error(`Unknown component name in snapshot: ${sid}`);
+	/**
+	* 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);
 		}
-		return id;
 	}
-	if (typeof sid === "object" && sid !== null && typeof sid.component === "string") {
-		let compId = getComponentIdByName(sid.component);
-		if (compId === void 0) {
-			const num = parseInt(sid.component, 10);
-			if (!isNaN(num)) compId = num;
-		}
-		if (compId === void 0) throw new Error(`Unknown component name in snapshot: ${sid.component}`);
-		if (sid.target === "*") return relation(compId, "*");
-		let targetId;
-		if (typeof sid.target === "string") {
-			const tid = getComponentIdByName(sid.target);
-			if (tid === void 0) {
-				const num = parseInt(sid.target, 10);
-				if (!isNaN(num)) targetId = num;
-				else throw new Error(`Unknown target component name in snapshot: ${sid.target}`);
-			} else targetId = tid;
-		} else targetId = sid.target;
-		return relation(compId, targetId);
+	/**
+	* Registers a query so it receives future archetype notifications.
+	* Called automatically by the `Query` constructor via `world._registerQuery`.
+	*/
+	register(query) {
+		this.queries.add(query);
 	}
-	throw new Error(`Invalid ID in snapshot: ${JSON.stringify(sid)}`);
-}
+	/**
+	* 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/core/world-commands.ts
+//#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);
@@ -1503,69 +1857,31 @@ function hasArchetypeStructuralChange(changeset, currentArchetype) {
 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.keys()) if (!isDontFragmentRelation(componentType)) finalRegularTypes.add(componentType);
+	for (const [componentType] of changeset.adds) if (!isDontFragmentRelation(componentType)) finalRegularTypes.add(componentType);
 	return Array.from(finalRegularTypes);
 }
-function applyChangeset(ctx, entityId, currentArchetype, changeset, entityToArchetype) {
-	const removedComponents = /* @__PURE__ */ new Map();
+function applyChangeset(ctx, entityId, currentArchetype, changeset, entityToArchetype, removedComponents) {
 	pruneMissingRemovals(changeset, currentArchetype, entityId);
-	if (hasArchetypeStructuralChange(changeset, currentArchetype)) return {
-		removedComponents,
-		newArchetype: moveEntityToNewArchetype(ctx, entityId, currentArchetype, buildFinalRegularComponentTypes(currentArchetype, changeset), changeset, removedComponents, entityToArchetype)
-	};
-	updateEntityInSameArchetype(ctx, entityId, currentArchetype, changeset, removedComponents);
-	return {
-		removedComponents,
-		newArchetype: currentArchetype
-	};
-}
-/**
-* Optimized variant of applyChangeset for when no lifecycle hooks are registered.
-* Skips creating the removedComponents map, reducing allocations in the hot path.
-*/
-function applyChangesetNoHooks(ctx, entityId, currentArchetype, changeset, entityToArchetype) {
-	pruneMissingRemovals(changeset, currentArchetype, entityId);
-	if (hasArchetypeStructuralChange(changeset, currentArchetype)) return moveEntityToNewArchetypeNoHooks(ctx, entityId, currentArchetype, buildFinalRegularComponentTypes(currentArchetype, changeset), changeset, entityToArchetype);
-	updateEntityInSameArchetypeNoHooks(ctx, entityId, currentArchetype, changeset);
-	return currentArchetype;
-}
-function moveEntityToNewArchetype(ctx, entityId, currentArchetype, finalComponentTypes, changeset, removedComponents, entityToArchetype) {
-	const newArchetype = ctx.ensureArchetype(finalComponentTypes);
-	const currentComponents = currentArchetype.removeEntity(entityId);
-	for (const componentType of changeset.removes) removedComponents.set(componentType, currentComponents.get(componentType));
-	newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
-	entityToArchetype.set(entityId, newArchetype);
-	return newArchetype;
-}
-function updateEntityInSameArchetype(ctx, entityId, currentArchetype, changeset, removedComponents) {
-	applyDontFragmentChanges(ctx.dontFragmentRelations, entityId, changeset, removedComponents);
+	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$1] of changeset.adds) {
 		if (isDontFragmentRelation(componentType)) continue;
 		currentArchetype.set(entityId, componentType, component$1);
 	}
+	return currentArchetype;
 }
 /**
-* No-hooks variant: moves entity to new archetype without collecting removed component data.
-* Only called from applyChangesetNoHooks when no lifecycle hooks are registered.
-*/
-function moveEntityToNewArchetypeNoHooks(ctx, entityId, currentArchetype, finalComponentTypes, changeset, entityToArchetype) {
-	const newArchetype = ctx.ensureArchetype(finalComponentTypes);
-	const currentComponents = currentArchetype.removeEntity(entityId);
-	newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
-	entityToArchetype.set(entityId, newArchetype);
-	return newArchetype;
-}
-/**
-* No-hooks variant: updates entity in same archetype without tracking removed component data.
-* Only called from applyChangesetNoHooks when no lifecycle hooks are registered.
+* No-hooks variant of applyDontFragmentChanges that skips tracking removed component data.
 */
-function updateEntityInSameArchetypeNoHooks(ctx, entityId, currentArchetype, changeset) {
-	applyDontFragmentChangesNoHooks(ctx.dontFragmentRelations, entityId, changeset);
-	for (const [componentType, component$1] of changeset.adds) {
-		if (isDontFragmentRelation(componentType)) continue;
-		currentArchetype.set(entityId, componentType, component$1);
-	}
-}
 function applyDontFragmentChanges(dontFragmentRelations, entityId, changeset, removedComponents) {
 	let entityRelations = dontFragmentRelations.get(entityId);
 	for (const componentType of changeset.removes) if (isDontFragmentRelation(componentType)) {
@@ -1586,9 +1902,6 @@ function applyDontFragmentChanges(dontFragmentRelations, entityId, changeset, re
 	}
 	if (entityRelations && entityRelations.size === 0) dontFragmentRelations.delete(entityId);
 }
-/**
-* No-hooks variant of applyDontFragmentChanges that skips tracking removed component data.
-*/
 function applyDontFragmentChangesNoHooks(dontFragmentRelations, entityId, changeset) {
 	let entityRelations = dontFragmentRelations.get(entityId);
 	for (const componentType of changeset.removes) if (isDontFragmentRelation(componentType)) {
@@ -1615,9 +1928,22 @@ function filterRegularComponentTypes(componentTypes) {
 	}
 	return regularTypes;
 }
-
-//#endregion
-//#region src/core/world-hooks.ts
+
+//#endregion
+//#region src/world/hooks.ts
+/**
+* Unified hook invocation: prefers entry.callback (callback style) over hook.on_* (object style).
+*/
+function invokeHook(entry, event, entityId, components) {
+	if (entry.callback) {
+		entry.callback(event, entityId, ...components);
+		return;
+	}
+	const hook = entry.hook;
+	if (event === "init") hook.on_init?.(entityId, ...components);
+	else if (event === "set") hook.on_set?.(entityId, ...components);
+	else hook.on_remove?.(entityId, ...components);
+}
 /**
 * Check if a component change matches a hook component type.
 * Handles wildcard-relation matching: if hookComponent is a wildcard relation (e.g., relation(A, "*")),
@@ -1647,8 +1973,6 @@ function findMatchingComponent(changes, hookComponent) {
 	for (const [changedComponent, value] of changes.entries()) if (componentMatchesHookType(changedComponent, hookComponent)) return [changedComponent, value];
 }
 function triggerLifecycleHooks(ctx, entityId, addedComponents, removedComponents, oldArchetype, newArchetype) {
-	invokeHooksForComponents(ctx.hooks, entityId, addedComponents, "on_set");
-	invokeHooksForComponents(ctx.hooks, entityId, removedComponents, "on_remove");
 	triggerMultiComponentHooks(ctx, entityId, addedComponents, removedComponents, oldArchetype, newArchetype);
 }
 /**
@@ -1656,44 +1980,31 @@ function triggerLifecycleHooks(ctx, entityId, addedComponents, removedComponents
 * This avoids unnecessary archetype lookups and on_set checks since the entity
 * is being completely removed.
 */
-function triggerRemoveHooksForEntityDeletion(ctx, entityId, removedComponents, oldArchetype) {
+function triggerRemoveHooksForEntityDeletion(entityId, removedComponents, oldArchetype) {
 	if (removedComponents.size === 0) return;
-	invokeHooksForComponents(ctx.hooks, entityId, removedComponents, "on_remove");
 	for (const entry of oldArchetype.matchingMultiHooks) {
-		const { hook, requiredComponents, componentTypes } = entry;
-		if (!hook.on_remove) continue;
+		const { requiredComponents, componentTypes } = entry;
+		if (!entry.callback && !entry.hook.on_remove) continue;
 		if (!requiredComponents.some((c) => anyComponentMatches(removedComponents, c))) continue;
 		if (!requiredComponents.every((c) => anyComponentMatches(removedComponents, c))) continue;
-		const components = collectComponentsFromRemoved(componentTypes, removedComponents);
-		hook.on_remove(entityId, ...components);
-	}
-}
-function invokeHooksForComponents(hooks, entityId, components, hookType) {
-	for (const [componentType, component$1] of components) {
-		const directHooks = hooks.get(componentType);
-		if (directHooks) for (const hook of directHooks) hook[hookType]?.(entityId, componentType, component$1);
-		const componentId = getComponentIdFromRelationId(componentType);
-		if (componentId !== void 0) {
-			const wildcardHooks = hooks.get(relation(componentId, "*"));
-			if (wildcardHooks) for (const hook of wildcardHooks) hook[hookType]?.(entityId, componentType, component$1);
-		}
+		invokeHook(entry, "remove", entityId, collectComponentsFromRemoved(componentTypes, removedComponents));
 	}
 }
 function triggerMultiComponentHooks(ctx, entityId, addedComponents, removedComponents, oldArchetype, newArchetype) {
 	for (const entry of newArchetype.matchingMultiHooks) {
-		const { hook, requiredComponents, optionalComponents, componentTypes } = entry;
-		if (!hook.on_set) continue;
+		const { requiredComponents, optionalComponents, componentTypes } = entry;
+		if (!entry.callback && !entry.hook.on_set) continue;
 		const anyRequiredAdded = requiredComponents.some((c) => anyComponentMatches(addedComponents, c));
 		const anyOptionalAdded = optionalComponents.some((c) => anyComponentMatches(addedComponents, c));
 		const anyOptionalRemoved = optionalComponents.some((c) => anyComponentMatches(removedComponents, c));
-		if (!oldArchetype.matchingMultiHooks.has(entry) || (anyRequiredAdded || anyOptionalAdded || anyOptionalRemoved) && entityHasAllComponents(ctx, entityId, requiredComponents)) hook.on_set(entityId, ...collectMultiHookComponents(ctx, entityId, componentTypes));
+		if (!oldArchetype.matchingMultiHooks.has(entry) || (anyRequiredAdded || anyOptionalAdded || anyOptionalRemoved) && entityHasAllComponents(ctx, entityId, requiredComponents)) invokeHook(entry, "set", entityId, collectMultiHookComponents(ctx, entityId, componentTypes));
 	}
 	for (const entry of oldArchetype.matchingMultiHooks) {
-		const { hook, requiredComponents, componentTypes } = entry;
-		if (!hook.on_remove) continue;
+		const { requiredComponents, componentTypes } = entry;
+		if (!entry.callback && !entry.hook.on_remove) continue;
 		const lostRequiredMatch = requiredComponents.some((c) => anyComponentMatches(removedComponents, c)) && entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removedComponents) && !entityHasAllComponents(ctx, entityId, requiredComponents);
 		const exitedMatchingSet = !newArchetype.matchingMultiHooks.has(entry);
-		if (lostRequiredMatch || exitedMatchingSet) hook.on_remove(entityId, ...collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents));
+		if (lostRequiredMatch || exitedMatchingSet) invokeHook(entry, "remove", entityId, collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents));
 	}
 }
 function entityHasAllComponents(ctx, entityId, requiredComponents) {
@@ -1787,6 +2098,7 @@ function collectWildcardFromRemoved(wildcardId, removedComponents) {
 
 //#endregion
 //#region src/utils/multi-map.ts
+const _MISSING = Symbol("missing");
 var MultiMap = class {
 	map = /* @__PURE__ */ new Map();
 	_valueCount = 0;
@@ -1799,10 +2111,10 @@ var MultiMap = class {
 	hasKey(key) {
 		return this.map.has(key);
 	}
-	has(key, value) {
+	has(key, value = _MISSING) {
 		const set = this.map.get(key);
 		if (!set) return false;
-		if (arguments.length === 1) return true;
+		if (value === _MISSING) return true;
 		return set.has(value);
 	}
 	add(key, value) {
@@ -1855,7 +2167,7 @@ var MultiMap = class {
 };
 
 //#endregion
-//#region src/core/world-references.ts
+//#region src/world/references.ts
 function trackEntityReference(entityReferences, sourceEntityId, componentType, targetEntityId) {
 	if (!entityReferences.has(targetEntityId)) entityReferences.set(targetEntityId, new MultiMap());
 	entityReferences.get(targetEntityId).add(sourceEntityId, componentType);
@@ -1872,7 +2184,155 @@ function getEntityReferences(entityReferences, targetEntityId) {
 }
 
 //#endregion
-//#region src/core/world.ts
+//#region src/storage/serialization.ts
+/**
+* Encode an internal EntityId into a SerializedEntityId for snapshots
+*/
+function encodeEntityId(id) {
+	const detailed = getDetailedIdType(id);
+	switch (detailed.type) {
+		case "component": {
+			const name = getComponentNameById(id);
+			if (!name) console.warn(`Component ID ${id} has no registered name, serializing as number`);
+			return name || id;
+		}
+		case "entity-relation": {
+			const componentName = getComponentNameById(detailed.componentId);
+			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+			return {
+				component: componentName || detailed.componentId.toString(),
+				target: detailed.targetId
+			};
+		}
+		case "component-relation": {
+			const componentName = getComponentNameById(detailed.componentId);
+			const targetName = getComponentNameById(detailed.targetId);
+			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+			if (!targetName) console.warn(`Target component ID ${detailed.targetId} in relation has no registered name`);
+			return {
+				component: componentName || detailed.componentId.toString(),
+				target: targetName || detailed.targetId
+			};
+		}
+		case "wildcard-relation": {
+			const componentName = getComponentNameById(detailed.componentId);
+			if (!componentName) console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
+			return {
+				component: componentName || detailed.componentId.toString(),
+				target: "*"
+			};
+		}
+		default: return id;
+	}
+}
+/**
+* Decode a SerializedEntityId back into an internal EntityId
+*/
+function decodeSerializedId(sid) {
+	if (typeof sid === "number") return sid;
+	if (typeof sid === "string") {
+		const id = getComponentIdByName(sid);
+		if (id === void 0) {
+			const num = parseInt(sid, 10);
+			if (!isNaN(num)) return num;
+			throw new Error(`Unknown component name in snapshot: ${sid}`);
+		}
+		return id;
+	}
+	if (typeof sid === "object" && sid !== null && typeof sid.component === "string") {
+		let compId = getComponentIdByName(sid.component);
+		if (compId === void 0) {
+			const num = parseInt(sid.component, 10);
+			if (!isNaN(num)) compId = num;
+		}
+		if (compId === void 0) throw new Error(`Unknown component name in snapshot: ${sid.component}`);
+		if (sid.target === "*") return relation(compId, "*");
+		let targetId;
+		if (typeof sid.target === "string") {
+			const tid = getComponentIdByName(sid.target);
+			if (tid === void 0) {
+				const num = parseInt(sid.target, 10);
+				if (!isNaN(num)) targetId = num;
+				else throw new Error(`Unknown target component name in snapshot: ${sid.target}`);
+			} else targetId = tid;
+		} else targetId = sid.target;
+		return relation(compId, targetId);
+	}
+	throw new Error(`Invalid ID in snapshot: ${JSON.stringify(sid)}`);
+}
+
+//#endregion
+//#region src/world/serialization.ts
+/**
+* Serializes the full world state to a plain JS object suitable for JSON encoding.
+*/
+function serializeWorld(archetypes, componentEntities, entityIdManager) {
+	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 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
+		}))
+	});
+	return {
+		version: 1,
+		entityManager: entityIdManager.serializeState(),
+		entities,
+		componentEntities: componentEntitiesArr
+	};
+}
+/**
+* Restores world state from a snapshot into the provided context.
+* Intended to be called from `World`'s constructor.
+*/
+function deserializeWorld(ctx, snapshot) {
+	if (snapshot.entityManager) ctx.entityIdManager.deserializeState(snapshot.entityManager);
+	if (Array.isArray(snapshot.componentEntities)) for (const entry of snapshot.componentEntities) {
+		const entityId = decodeSerializedId(entry.id);
+		if (!ctx.componentEntities.exists(entityId)) continue;
+		const componentsArray = entry.components || [];
+		const componentMap = /* @__PURE__ */ new Map();
+		for (const componentEntry of componentsArray) {
+			const componentType = decodeSerializedId(componentEntry.type);
+			componentMap.set(componentType, componentEntry.value);
+		}
+		ctx.componentEntities.initFromSnapshot(entityId, componentMap);
+	}
+	if (Array.isArray(snapshot.entities)) for (const entry of snapshot.entities) {
+		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 archetype = ctx.ensureArchetype(componentTypes);
+		archetype.addEntity(entityId, componentMap);
+		ctx.setEntityToArchetype(entityId, archetype);
+		for (const compType of componentTypes) {
+			const detailedType = getDetailedIdType(compType);
+			if (detailedType.type === "entity-relation") trackEntityReference(ctx.entityReferences, entityId, compType, detailedType.targetId);
+			else if (detailedType.type === "entity") trackEntityReference(ctx.entityReferences, entityId, compType, compType);
+		}
+	}
+}
+
+//#endregion
+//#region src/world/world.ts
 /**
 * World class for ECS architecture
 * Manages entities and components
@@ -1884,64 +2344,37 @@ var World = class {
 	entityToArchetype = /* @__PURE__ */ new Map();
 	archetypesByComponent = /* @__PURE__ */ new Map();
 	entityReferences = /* @__PURE__ */ new Map();
-	dontFragmentRelations = /* @__PURE__ */ new Map();
-	componentEntityComponents = /* @__PURE__ */ new Map();
-	relationEntityIdsByTarget = /* @__PURE__ */ new Map();
-	queries = [];
-	queryCache = /* @__PURE__ */ new Map();
-	legacyHooks = /* @__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();
+	/** Component entity (singleton) storage */
+	componentEntities = new ComponentEntityStore();
+	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 = {
-		dontFragmentRelations: this.dontFragmentRelations,
+		dontFragmentStore: this.dontFragmentStore,
 		ensureArchetype: (ct) => this.ensureArchetype(ct)
 	};
 	/** Cached hooks context to avoid per-entity object allocation */
 	_hooksCtx = {
-		hooks: this.legacyHooks,
 		multiHooks: this.hooks,
 		has: (eid, ct) => this.has(eid, ct),
 		get: (eid, ct) => this.get(eid, ct),
 		getOptional: (eid, ct) => this.getOptional(eid, ct)
 	};
 	constructor(snapshot) {
-		if (snapshot && typeof snapshot === "object") this.deserializeSnapshot(snapshot);
-	}
-	deserializeSnapshot(snapshot) {
-		if (snapshot.entityManager) this.entityIdManager.deserializeState(snapshot.entityManager);
-		if (Array.isArray(snapshot.componentEntities)) for (const entry of snapshot.componentEntities) {
-			const entityId = decodeSerializedId(entry.id);
-			if (!this.isComponentEntityId(entityId)) continue;
-			const componentsArray = entry.components || [];
-			const componentMap = /* @__PURE__ */ new Map();
-			for (const componentEntry of componentsArray) {
-				const componentType = decodeSerializedId(componentEntry.type);
-				componentMap.set(componentType, componentEntry.value);
-			}
-			this.componentEntityComponents.set(entityId, componentMap);
-			this.registerRelationEntityId(entityId);
-		}
-		if (Array.isArray(snapshot.entities)) for (const entry of snapshot.entities) {
-			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 archetype = this.ensureArchetype(componentTypes);
-			archetype.addEntity(entityId, componentMap);
-			this.entityToArchetype.set(entityId, archetype);
-			for (const compType of componentTypes) {
-				const detailedType = getDetailedIdType(compType);
-				if (detailedType.type === "entity-relation") trackEntityReference(this.entityReferences, entityId, compType, detailedType.targetId);
-				else if (detailedType.type === "entity") trackEntityReference(this.entityReferences, entityId, compType, compType);
-			}
-		}
+		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)
+		}, snapshot);
 	}
 	createArchetypeSignature(componentTypes) {
 		return componentTypes.join(",");
@@ -1965,51 +2398,34 @@ var World = class {
 		this.entityToArchetype.set(entityId, emptyArchetype);
 		return entityId;
 	}
-	isComponentEntityId(entityId) {
-		const detailed = getDetailedIdType(entityId);
-		return detailed.type !== "entity" && detailed.type !== "invalid";
-	}
-	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);
-	}
-	getComponentEntityComponents(entityId, create) {
-		let data = this.componentEntityComponents.get(entityId);
-		if (!data && create) {
-			data = /* @__PURE__ */ new Map();
-			this.componentEntityComponents.set(entityId, data);
-			this.registerRelationEntityId(entityId);
-		}
-		return data;
-	}
-	clearComponentEntityComponents(entityId) {
-		if (this.componentEntityComponents.delete(entityId)) this.unregisterRelationEntityId(entityId);
+	/**
+	* Semantic alias for `new()` to avoid confusion with the `new` keyword.
+	* Creates a new entity with an empty component set.
+	*
+	* @example
+	* const entity = world.create<MyComponent>();
+	*/
+	create() {
+		return this.new();
 	}
-	cleanupComponentEntitiesReferencingEntity(targetId) {
-		const relationEntities = this.relationEntityIdsByTarget.get(targetId);
-		if (!relationEntities) return;
-		for (const relationEntityId of relationEntities) this.componentEntityComponents.delete(relationEntityId);
-		this.relationEntityIdsByTarget.delete(targetId);
+	/** Fast path: destroy an entity that is not referenced by any other entity, skipping BFS */
+	destroySingleEntity(entityId) {
+		const archetype = this.entityToArchetype.get(entityId);
+		if (!archetype) return;
+		for (const [sourceEntityId, componentType] of getEntityReferences(this.entityReferences, entityId)) if (this.entityToArchetype.has(sourceEntityId)) this.removeComponentImmediate(sourceEntityId, componentType, entityId);
+		this.entityReferences.delete(entityId);
+		const removedComponents = archetype.removeEntity(entityId);
+		this.entityToArchetype.delete(entityId);
+		triggerRemoveHooksForEntityDeletion(entityId, removedComponents, archetype);
+		this.cleanupArchetypesReferencingEntity(entityId);
+		this.entityIdManager.deallocate(entityId);
+		this.componentEntities.cleanupReferencesTo(entityId);
 	}
 	destroyEntityImmediate(entityId) {
+		if (!this.entityReferences.has(entityId)) {
+			this.destroySingleEntity(entityId);
+			return;
+		}
 		const queue = [entityId];
 		const visited = /* @__PURE__ */ new Set();
 		let queueIndex = 0;
@@ -2028,25 +2444,33 @@ var World = class {
 			this.entityReferences.delete(cur);
 			const removedComponents = archetype.removeEntity(cur);
 			this.entityToArchetype.delete(cur);
-			triggerRemoveHooksForEntityDeletion(this.createHooksContext(), cur, removedComponents, archetype);
+			triggerRemoveHooksForEntityDeletion(cur, removedComponents, archetype);
 			this.cleanupArchetypesReferencingEntity(cur);
 			this.entityIdManager.deallocate(cur);
-			this.cleanupComponentEntitiesReferencingEntity(cur);
+			this.componentEntities.cleanupReferencesTo(cur);
 		}
 	}
 	/**
-	* Checks if an entity exists in the world.
+	* Checks if an **entity** (not a component) exists in the world.
+	*
+	* This is specifically for checking entity liveness — whether the given entity ID
+	* is currently alive in the world. For checking if a component is present on an
+	* entity, use {@link has} instead.
 	*
 	* @param entityId - The entity identifier to check
 	* @returns `true` if the entity exists, `false` otherwise
 	*
 	* @example
+	* // Check if an entity is alive
 	* if (world.exists(entityId)) {
 	*   console.log("Entity exists");
 	* }
+	*
+	* // To check for a component, use has() instead:
+	* if (world.has(entity, Position)) { ... }
 	*/
 	exists(entityId) {
-		if (this.isComponentEntityId(entityId)) return true;
+		if (this.componentEntities.exists(entityId)) return true;
 		return this.entityToArchetype.has(entityId);
 	}
 	assertEntityExists(entityId, label) {
@@ -2101,18 +2525,6 @@ var World = class {
 			componentType
 		};
 	}
-	getComponentEntityWildcardRelations(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;
-	}
 	set(entityId, componentTypeOrComponent, maybeComponent) {
 		const { entityId: targetEntityId, componentType, component: component$1 } = this.resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent);
 		this.commandBuffer.set(targetEntityId, componentType, component$1);
@@ -2138,50 +2550,44 @@ var World = class {
 	has(entityId, componentType) {
 		if (componentType === void 0) {
 			const componentId = entityId;
-			return this.componentEntityComponents.get(componentId)?.has(componentId) ?? false;
+			return this.componentEntities.hasSingleton(componentId);
 		}
-		if (this.isComponentEntityId(entityId)) {
+		if (this.componentEntities.exists(entityId)) {
 			if (isWildcardRelationId(componentType)) {
 				const componentId = getComponentIdFromRelationId(componentType);
 				if (componentId === void 0) return false;
-				const data = this.componentEntityComponents.get(entityId);
-				if (!data) return false;
-				return hasWildcardRelation(data, componentId);
+				return this.componentEntities.hasWildcard(entityId, componentId);
 			}
-			return this.componentEntityComponents.get(entityId)?.has(componentType) ?? false;
+			return this.componentEntities.has(entityId, componentType);
 		}
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) return false;
 		if (archetype.componentTypeSet.has(componentType)) return true;
-		if (isDontFragmentRelation(componentType)) return this.dontFragmentRelations.get(entityId)?.has(componentType) ?? false;
+		if (isDontFragmentRelation(componentType)) return this.dontFragmentStore.get(entityId)?.has(componentType) ?? false;
 		return false;
 	}
 	get(entityId, componentType = entityId) {
-		if (this.isComponentEntityId(entityId)) {
-			if (isWildcardRelationId(componentType)) return this.getComponentEntityWildcardRelations(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);
+		if (this.componentEntities.exists(entityId)) {
+			if (isWildcardRelationId(componentType)) return this.componentEntities.getWildcard(entityId, componentType);
+			return this.componentEntities.get(entityId, componentType);
 		}
 		const archetype = this.entityToArchetype.get(entityId);
 		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.dontFragmentRelations.get(entityId)?.has(componentType))) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
+			if (!(inArchetype || hasDontFragment && this.dontFragmentStore.get(entityId)?.has(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);
 	}
 	getOptional(entityId, componentType = entityId) {
-		if (this.isComponentEntityId(entityId)) {
+		if (this.componentEntities.exists(entityId)) {
 			if (isWildcardRelationId(componentType)) {
-				const relations = this.getComponentEntityWildcardRelations(entityId, componentType);
+				const relations = this.componentEntities.getWildcard(entityId, componentType);
 				if (relations.length === 0) return void 0;
 				return { value: relations };
 			}
-			const data = this.componentEntityComponents.get(entityId);
-			if (!data || !data.has(componentType)) return void 0;
-			return { value: data.get(componentType) };
+			return this.componentEntities.getOptional(entityId, componentType);
 		}
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
@@ -2192,89 +2598,39 @@ var World = class {
 		}
 		return archetype.getOptional(entityId, componentType);
 	}
-	hook(componentTypesOrSingle, hook, filter) {
-		if (typeof hook === "function") if (Array.isArray(componentTypesOrSingle)) {
-			const callback = hook;
-			hook = {
-				on_init: (entityId, ...components) => callback("init", entityId, ...components),
-				on_set: (entityId, ...components) => callback("set", entityId, ...components),
-				on_remove: (entityId, ...components) => callback("remove", entityId, ...components)
-			};
-		} else {
-			const callback = hook;
-			hook = {
-				on_init: (entityId, componentType, component$1) => callback("init", entityId, componentType, component$1),
-				on_set: (entityId, componentType, component$1) => callback("set", entityId, componentType, component$1),
-				on_remove: (entityId, componentType, component$1) => callback("remove", entityId, componentType, component$1)
-			};
-		}
-		if (Array.isArray(componentTypesOrSingle)) {
-			const componentTypes = componentTypesOrSingle;
-			const requiredComponents = [];
-			const optionalComponents = [];
-			for (const ct of componentTypes) if (!isOptionalEntityId(ct)) requiredComponents.push(ct);
-			else optionalComponents.push(ct.optional);
-			if (requiredComponents.length === 0) throw new Error("Hook must have at least one required component");
-			const entry = {
-				componentTypes,
-				requiredComponents,
-				optionalComponents,
-				filter: filter || {},
-				hook
-			};
-			this.hooks.add(entry);
-			for (const archetype of this.archetypes) if (this.archetypeMatchesHook(archetype, entry)) archetype.matchingMultiHooks.add(entry);
-			const multiHook = hook;
-			if (multiHook.on_init !== void 0) for (const archetype of this.archetypes) {
-				if (!this.archetypeMatchesHook(archetype, entry)) continue;
-				for (const entityId of archetype.getEntities()) {
-					const components = collectMultiHookComponents(this.createHooksContext(), entityId, componentTypes);
-					multiHook.on_init(entityId, ...components);
-				}
-			}
-			return () => {
-				this.hooks.delete(entry);
-				for (const archetype of this.archetypes) archetype.matchingMultiHooks.delete(entry);
-			};
-		} else {
-			const componentType = componentTypesOrSingle;
-			if (!this.legacyHooks.has(componentType)) this.legacyHooks.set(componentType, /* @__PURE__ */ new Set());
-			const legacyHook = hook;
-			this.legacyHooks.get(componentType).add(legacyHook);
-			if (legacyHook.on_init !== void 0) this.archetypesByComponent.get(componentType)?.forEach((archetype) => {
-				const entities = archetype.getEntityToIndexMap();
-				const componentData = archetype.getComponentData(componentType);
-				for (const [entity, index] of entities) {
-					const data = componentData[index];
-					const value = data === MISSING_COMPONENT ? void 0 : data;
-					legacyHook.on_init?.(entity, componentType, value);
-				}
-			});
-			return () => {
-				const hooks = this.legacyHooks.get(componentType);
-				if (hooks) {
-					hooks.delete(legacyHook);
-					if (hooks.size === 0) this.legacyHooks.delete(componentType);
-				}
-			};
-		}
-	}
-	/** @deprecated use the unsubscribe function returned by hook() instead */
-	unhook(componentTypesOrSingle, hook) {
-		if (Array.isArray(componentTypesOrSingle)) {
-			for (const entry of this.hooks) if (entry.hook === hook) {
-				this.hooks.delete(entry);
-				for (const archetype of this.archetypes) archetype.matchingMultiHooks.delete(entry);
-				break;
-			}
-		} else {
-			const componentType = componentTypesOrSingle;
-			const hooks = this.legacyHooks.get(componentType);
-			if (hooks) {
-				hooks.delete(hook);
-				if (hooks.size === 0) this.legacyHooks.delete(componentType);
-			}
-		}
+	hook(componentTypes, hook, filter) {
+		const isCallback = typeof hook === "function";
+		const callback = isCallback ? hook : void 0;
+		const requiredComponents = [];
+		const optionalComponents = [];
+		for (const ct of componentTypes) if (!isOptionalEntityId(ct)) requiredComponents.push(ct);
+		else optionalComponents.push(ct.optional);
+		if (requiredComponents.length === 0) throw new Error("Hook must have at least one required component");
+		const entry = {
+			componentTypes,
+			requiredComponents,
+			optionalComponents,
+			filter: filter || {},
+			hook: isCallback ? {} : hook,
+			callback,
+			matchedArchetypes: /* @__PURE__ */ new Set()
+		};
+		this.hooks.add(entry);
+		const matchedArchetypes = [];
+		for (const archetype of this.archetypes) if (this.archetypeMatchesHook(archetype, entry)) {
+			archetype.matchingMultiHooks.add(entry);
+			entry.matchedArchetypes.add(archetype);
+			matchedArchetypes.push(archetype);
+		}
+		if (isCallback || hook.on_init !== void 0) for (const archetype of matchedArchetypes) for (const entityId of archetype.getEntities()) {
+			const components = collectMultiHookComponents(this.createHooksContext(), entityId, componentTypes);
+			if (isCallback) callback("init", entityId, ...components);
+			else hook.on_init(entityId, ...components);
+		}
+		return () => {
+			this.hooks.delete(entry);
+			if (entry.matchedArchetypes) for (const archetype of entry.matchedArchetypes) archetype.matchingMultiHooks.delete(entry);
+		};
 	}
 	/**
 	* Synchronizes all buffered commands (set/remove/delete) to the world.
@@ -2321,18 +2677,7 @@ var World = class {
 		const sortedTypes = normalizeComponentTypes(componentTypes);
 		const filterKey = serializeQueryFilter(filter);
 		const key = `${this.createArchetypeSignature(sortedTypes)}${filterKey ? `|${filterKey}` : ""}`;
-		const cached = this.queryCache.get(key);
-		if (cached) {
-			cached.refCount++;
-			return cached.query;
-		}
-		const query = new Query(this, sortedTypes, filter);
-		query._cacheKey = key;
-		this.queryCache.set(key, {
-			query,
-			refCount: 1
-		});
-		return query;
+		return this.queryRegistry.getOrCreate(this, sortedTypes, key, filter);
 	}
 	/**
 	* Creates a new entity builder for fluent entity configuration.
@@ -2374,13 +2719,6 @@ var World = class {
 		}
 		return entities;
 	}
-	_registerQuery(query) {
-		this.queries.push(query);
-	}
-	_unregisterQuery(query) {
-		const index = this.queries.indexOf(query);
-		if (index !== -1) this.queries.splice(index, 1);
-	}
 	/**
 	* Releases a cached query and frees its resources if no longer needed.
 	* Call this when you're done using a query to allow the world to clean up its cache entry.
@@ -2393,16 +2731,7 @@ var World = class {
 	* world.releaseQuery(query); // Optional cleanup
 	*/
 	releaseQuery(query) {
-		const key = query._cacheKey;
-		if (!key) return;
-		const cached = this.queryCache.get(key);
-		if (!cached || cached.query !== query) return;
-		cached.refCount--;
-		if (cached.refCount <= 0) {
-			this.queryCache.delete(key);
-			this._unregisterQuery(query);
-			cached.query._disposeInternal();
-		}
+		this.queryRegistry.release(query);
 	}
 	/**
 	* Returns all archetypes that contain entities with the specified components.
@@ -2425,26 +2754,29 @@ var World = class {
 		} else regularComponents.push(componentType);
 		let matchingArchetypes = this.getArchetypesWithComponents(regularComponents);
 		for (const { componentId, relationId } of wildcardRelations) {
-			const archetypesWithMarker = this.archetypesByComponent.get(relationId) || [];
-			matchingArchetypes = matchingArchetypes.length === 0 ? archetypesWithMarker : matchingArchetypes.filter((a) => archetypesWithMarker.includes(a) || a.hasRelationWithComponentId(componentId));
+			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) return this.archetypesByComponent.get(componentTypes[0]) || [];
-		const archetypeLists = componentTypes.map((type) => this.archetypesByComponent.get(type) || []).sort((a, b) => a.length - b.length);
-		const shortest = archetypeLists[0];
-		if (shortest.length === 0) return [];
-		if (archetypeLists.length === 2) {
-			const second = archetypeLists[1];
-			const secondSet = new Set(second);
-			return shortest.filter((a) => secondSet.has(a));
-		}
-		let result = new Set(shortest);
-		for (let i = 1; i < archetypeLists.length; i++) {
-			const listSet = new Set(archetypeLists[i]);
-			for (const item of result) if (!listSet.has(item)) result.delete(item);
+		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);
@@ -2453,70 +2785,43 @@ var World = class {
 		const matchingArchetypes = this.getMatchingArchetypes(componentTypes);
 		if (includeComponents) {
 			const result = [];
-			for (const archetype of matchingArchetypes) result.push(...archetype.getEntitiesWithComponents(componentTypes));
+			for (const archetype of matchingArchetypes) archetype.appendEntitiesWithComponents(componentTypes, result);
 			return result;
 		} else {
 			const result = [];
-			for (const archetype of matchingArchetypes) result.push(...archetype.getEntities());
+			for (const archetype of matchingArchetypes) for (const entity of archetype.getEntities()) result.push(entity);
 			return result;
 		}
 	}
 	executeEntityCommands(entityId, commands) {
-		const changeset = this._changeset;
-		changeset.clear();
-		if (this.isComponentEntityId(entityId)) {
-			this.executeComponentEntityCommands(entityId, commands);
-			return changeset;
+		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 changeset;
+			return;
 		}
+		this.applyEntityCommands(entityId, commands);
+	}
+	applyEntityCommands(entityId, commands) {
 		const currentArchetype = this.entityToArchetype.get(entityId);
-		if (!currentArchetype) return changeset;
+		if (!currentArchetype) return;
+		const changeset = this._changeset;
 		processCommands(entityId, currentArchetype, commands, changeset, (eid, arch, compId) => {
 			if (isExclusiveComponent(compId)) removeMatchingRelations(eid, arch, compId, changeset);
 		});
-		const hasHooks = this.legacyHooks.size > 0 || this.hooks.size > 0;
-		const hasEntityRefs = changeset.removes.size > 0 || changeset.adds.size > 0;
-		if (!hasHooks) {
-			applyChangesetNoHooks(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype);
-			if (hasEntityRefs) this.updateEntityReferences(entityId, changeset);
-			return changeset;
-		}
-		const { removedComponents, newArchetype } = applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype);
-		if (hasEntityRefs) this.updateEntityReferences(entityId, changeset);
-		triggerLifecycleHooks(this.createHooksContext(), entityId, changeset.adds, removedComponents, currentArchetype, newArchetype);
-		return changeset;
-	}
-	executeComponentEntityCommands(entityId, commands) {
-		if (commands.some((cmd) => cmd.type === "destroy")) {
-			this.clearComponentEntityComponents(entityId);
+		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 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);
-			this.getComponentEntityComponents(entityId, true).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.clearComponentEntityComponents(entityId);
-		}
+		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;
@@ -2524,11 +2829,12 @@ var World = class {
 	removeComponentImmediate(entityId, componentType, targetEntityId) {
 		const sourceArchetype = this.entityToArchetype.get(entityId);
 		if (!sourceArchetype) return;
-		const changeset = new ComponentChangeset();
+		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);
+		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);
 	}
@@ -2547,20 +2853,56 @@ var World = class {
 		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.dontFragmentRelations);
+		const newArchetype = new Archetype(componentTypes, this.dontFragmentStore);
 		this.archetypes.push(newArchetype);
 		for (const componentType of componentTypes) {
-			const archetypes = this.archetypesByComponent.get(componentType) || [];
-			archetypes.push(newArchetype);
-			this.archetypesByComponent.set(componentType, archetypes);
+			let archetypes = this.archetypesByComponent.get(componentType);
+			if (!archetypes) {
+				archetypes = /* @__PURE__ */ new Set();
+				this.archetypesByComponent.set(componentType, archetypes);
+			}
+			archetypes.add(newArchetype);
+			this.addToReferencingIndex(componentType, newArchetype);
 		}
-		for (const query of this.queries) query.checkNewArchetype(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);
+		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) => {
@@ -2572,30 +2914,29 @@ var World = class {
 			return archetype.componentTypeSet.has(c) || isDontFragmentRelation(c);
 		}) && matchesFilter(archetype, entry.filter);
 	}
-	archetypeReferencesEntity(archetype, entityId) {
-		return archetype.componentTypes.some((ct) => ct === entityId || isEntityRelation(ct) && getTargetIdFromRelationId(ct) === entityId);
-	}
 	cleanupArchetypesReferencingEntity(entityId) {
-		for (let i = this.archetypes.length - 1; i >= 0; i--) {
-			const archetype = this.archetypes[i];
-			if (archetype.getEntities().length === 0 && this.archetypeReferencesEntity(archetype, entityId)) this.removeArchetype(archetype);
-		}
+		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) this.archetypes.splice(index, 1);
+		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) {
-				const compIndex = archetypes.indexOf(archetype);
-				if (compIndex !== -1) {
-					archetypes.splice(compIndex, 1);
-					if (archetypes.length === 0) this.archetypesByComponent.delete(componentType);
-				}
+				archetypes.delete(archetype);
+				if (archetypes.size === 0) this.archetypesByComponent.delete(componentType);
 			}
+			this.removeFromReferencingIndex(componentType, archetype);
 		}
-		for (const query of this.queries) query.removeArchetype(archetype);
+		this.queryRegistry.onArchetypeRemoved(archetype);
 	}
 	/**
 	* Serializes the entire world state to a plain JavaScript object.
@@ -2619,31 +2960,7 @@ var World = class {
 	* const newWorld = new World(savedData);
 	*/
 	serialize() {
-		const entities = [];
-		for (const archetype of this.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 componentEntities = [];
-		for (const [entityId, components] of this.componentEntityComponents.entries()) componentEntities.push({
-			id: encodeEntityId(entityId),
-			components: Array.from(components.entries()).map(([rawType, value]) => ({
-				type: encodeEntityId(rawType),
-				value: value === MISSING_COMPONENT ? void 0 : value
-			}))
-		});
-		return {
-			version: 1,
-			entityManager: this.entityIdManager.serializeState(),
-			entities,
-			componentEntities
-		};
+		return serializeWorld(this.archetypes, this.componentEntities, this.entityIdManager);
 	}
 };