@codehz/ecs 0.8.2 → 0.9.0

package/dist/world.mjs

@@ -366,7 +366,7 @@ const ComponentIdForNames = /* @__PURE__ */ new Map();
 const componentNames = new Array(COMPONENT_ID_MAX + 1);
 const exclusiveFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const cascadeDeleteFlags = new BitSet(COMPONENT_ID_MAX + 1);
-const dontFragmentFlags = new BitSet(COMPONENT_ID_MAX + 1);
+const sparseFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const componentMerges = new Array(COMPONENT_ID_MAX + 1);
 /**
 * Allocate a new component ID from the global allocator.
@@ -399,7 +399,7 @@ function component(nameOrOptions) {
 	if (options) {
 		if (options.exclusive) exclusiveFlags.set(id);
 		if (options.cascadeDelete) cascadeDeleteFlags.set(id);
-		if (options.dontFragment) dontFragmentFlags.set(id);
+		if (options.sparse || options.dontFragment) sparseFlags.set(id);
 		if (options.merge) componentMerges[id] = options.merge;
 	}
 	return id;
@@ -468,20 +468,21 @@ function isExclusiveComponent(id) {
 	return exclusiveFlags.has(id);
 }
 /**
-* Check if a component is marked as `dontFragment`.
+* Check if a component is marked as `sparse` (sparse storage for relations).
 *
-* When a component has `dontFragment: true`, relations using it do not cause
-* archetype fragmentation — entities with different relation targets can share
-* the same archetype. This is a fast O(1) bitset lookup.
+* When a component has `sparse: true`, relations using it do not cause archetype
+* fragmentation — entities with different relation targets can share the same
+* archetype. This is a fast O(1) bitset lookup. The legacy `dontFragment` key
+* is still accepted and sets the same internal flag.
 *
 * @param id - The component ID to check.
-* @returns `true` if the component was created with `dontFragment: true`.
+* @returns `true` if the component was created with `sparse: true` (or the
+*   legacy `dontFragment: true`).
 *
-* @see {@link ComponentOptions.dontFragment} for the full explanation of how
-*   `dontFragment` prevents archetype fragmentation.
+* @see {@link ComponentOptions.sparse} for the full explanation of sparse storage.
 */
-function isDontFragmentComponent(id) {
-	return dontFragmentFlags.has(id);
+function isSparseComponent(id) {
+	return sparseFlags.has(id);
 }
 /**
 * Generic optimized function to check whether a relation ID's base component
@@ -491,9 +492,8 @@ function isDontFragmentComponent(id) {
 * ID and checking: (1) the ID is a valid relation, (2) the component ID is in the
 * valid range, (3) the target satisfies the condition, and (4) the flag bit is set.
 *
-* Used as the fast-path implementation for `isDontFragmentRelation`,
-* `isDontFragmentWildcard`, `isExclusiveRelation`, `isExclusiveWildcard`,
-* and `isCascadeDeleteRelation`.
+* Used as the fast-path implementation for `isSparseRelation`, `isSparseWildcard`,
+* `isExclusiveRelation`, `isExclusiveWildcard`, and `isCascadeDeleteRelation`.
 *
 * @param id - The entity/relation ID to check.
 * @param flagBitSet - The bitset tracking which component IDs have the flag.
@@ -509,52 +509,40 @@ function checkRelationFlag(id, flagBitSet, targetCondition) {
 	return isValidComponentId(componentId) && targetCondition(targetId) && flagBitSet.has(componentId);
 }
 /**
-* Check if an ID is a specific (non-wildcard) relation backed by a `dontFragment`
-* component.
+* Check if an ID is a specific (non-wildcard) relation backed by a `sparse`
+* component (i.e. stored in the side sparse store rather than the archetype).
 *
 * This is used in hot paths (archetype resolution, command processing) to determine
-* whether a relation should be excluded from the archetype signature. Relations with
-* `dontFragment` components are stored in the shared {@link DontFragmentStore} instead
-* of being part of the archetype's component type list.
-*
-* This is an optimized function that avoids the overhead of `getDetailedIdType`
-* by directly decoding and checking the relation's component ID against the
-* `dontFragment` bitset.
+* whether a relation should be excluded from the archetype signature.
 *
 * @param id - The entity/relation ID to check (must be a relation ID, not a plain
 *   component ID).
 * @returns `true` if this is a specific-target relation (not wildcard) whose base
-*   component was created with `dontFragment: true`.
+*   component was created with `sparse: true` (or legacy `dontFragment: true`).
 *
-* @see {@link isDontFragmentWildcard} for the wildcard variant.
-* @see {@link ComponentOptions.dontFragment} for the full explanation.
+* @see {@link isSparseWildcard} for the wildcard variant.
+* @see {@link ComponentOptions.sparse} for the full explanation.
 */
-function isDontFragmentRelation(id) {
-	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== 0);
+function isSparseRelation(id) {
+	return checkRelationFlag(id, sparseFlags, (targetId) => targetId !== 0);
 }
 /**
 * Check if an ID is a wildcard relation (`relation(Comp, "*")`) backed by a
-* `dontFragment` component.
-*
-* Wildcard markers for `dontFragment` components are placed in the archetype
-* component list so that queries can discover archetypes containing entities
-* with that relation type. This function is used in `filterRegularComponentTypes`
-* to **keep** these wildcard markers in the archetype signature while stripping
-* out specific-target `dontFragment` relations.
+* `sparse` component.
 *
-* This is an optimized function that avoids the overhead of `getDetailedIdType`
-* by directly decoding and checking the relation's component ID against the
-* `dontFragment` bitset.
+* Wildcard markers for sparse components are placed in the archetype component
+* list so that queries can discover archetypes containing entities with that
+* relation type.
 *
 * @param id - The entity/relation ID to check.
 * @returns `true` if this is a wildcard relation (`"*"` target) whose base
-*   component was created with `dontFragment: true`.
+*   component was created with `sparse: true` (or legacy `dontFragment: true`).
 *
-* @see {@link isDontFragmentRelation} for the specific-target variant.
-* @see {@link ComponentOptions.dontFragment} for the full explanation.
+* @see {@link isSparseRelation} for the specific-target variant.
+* @see {@link ComponentOptions.sparse} for the full explanation.
 */
-function isDontFragmentWildcard(id) {
-	return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === 0);
+function isSparseWildcard(id) {
+	return checkRelationFlag(id, sparseFlags, (targetId) => targetId === 0);
 }
 /**
 * Check if a relation ID is a cascade delete entity-relation.
@@ -709,9 +697,9 @@ function getWildcardRelationDataSource(componentTypes, componentId, optional) {
 }
 /**
 * Build wildcard relation value from matching relations.
-* Now receives the DontFragmentStore directly for efficient per-component lookups.
+* Receives the SparseStore directly for efficient per-component lookups.
 */
-function buildWildcardRelationValue(wildcardRelationType, matchingRelations, getDataAtIndex, dontFragmentStore, entityId, optional) {
+function buildWildcardRelationValue(wildcardRelationType, matchingRelations, getDataAtIndex, sparseStore, entityId, optional) {
 	const relations = [];
 	const targetComponentId = getComponentIdFromRelationId(wildcardRelationType);
 	for (const relType of matchingRelations || []) {
@@ -720,7 +708,7 @@ function buildWildcardRelationValue(wildcardRelationType, matchingRelations, get
 		relations.push([targetId, data === MISSING_COMPONENT ? void 0 : data]);
 	}
 	if (targetComponentId !== void 0) {
-		const dfMatches = dontFragmentStore.getRelationsForComponent(entityId, targetComponentId);
+		const dfMatches = sparseStore.getRelationsForComponent(entityId, targetComponentId);
 		for (const m of dfMatches) relations.push(m);
 	}
 	if (relations.length === 0) {
@@ -747,10 +735,10 @@ function buildRegularComponentValue(dataSource, entityIndex, optional) {
 /**
 * Build a single component value based on its type
 */
-function buildSingleComponent(compType, dataSource, entityIndex, entityId, getComponentData, dontFragmentRelations) {
+function buildSingleComponent(compType, dataSource, entityIndex, entityId, getComponentData, sparseRelations) {
 	const optional = isOptionalEntityId(compType);
 	const actualType = optional ? compType.optional : compType;
-	if (getIdType(actualType) === "wildcard-relation") return buildWildcardRelationValue(actualType, dataSource, (relType) => getComponentData(relType)[entityIndex], dontFragmentRelations, entityId, optional);
+	if (getIdType(actualType) === "wildcard-relation") return buildWildcardRelationValue(actualType, dataSource, (relType) => getComponentData(relType)[entityIndex], sparseRelations, entityId, optional);
 	else return buildRegularComponentValue(dataSource, entityIndex, optional);
 }
 //#endregion
@@ -787,11 +775,10 @@ var Archetype = class {
 	*/
 	entityToIndex = /* @__PURE__ */ new Map();
 	/**
-	* DontFragmentStore (keyed primarily by relation ComponentId).
-	* Uses optimized RelationEntry (single/multi) for the common exclusive case.
+	* SparseStore used for relations declared with `sparse: true`.
 	* See store.ts for implementation details.
 	*/
-	dontFragmentRelations;
+	sparseRelations;
 	/**
 	* Multi-hooks that match this archetype
 	*/
@@ -800,10 +787,10 @@ var Archetype = class {
 	* Cache for pre-computed component data sources to avoid repeated calculations
 	*/
 	componentDataSourcesCache = /* @__PURE__ */ new Map();
-	constructor(componentTypes, dontFragmentRelations) {
+	constructor(componentTypes, sparseStore) {
 		this.componentTypes = normalizeComponentTypes(componentTypes);
 		this.componentTypeSet = new Set(this.componentTypes);
-		this.dontFragmentRelations = dontFragmentRelations;
+		this.sparseRelations = sparseStore;
 		for (const componentType of this.componentTypes) this.componentData.set(componentType, []);
 	}
 	get size() {
@@ -829,13 +816,13 @@ var Archetype = class {
 			const data = componentData.get(componentType);
 			this.getComponentData(componentType).push(!componentData.has(componentType) ? MISSING_COMPONENT : data);
 		}
-		this.addDontFragmentRelations(entityId, componentData);
+		this.addSparseRelations(entityId, componentData);
 	}
-	addDontFragmentRelations(entityId, componentData) {
+	addSparseRelations(entityId, componentData) {
 		for (const [componentType, data] of componentData) {
 			if (this.componentTypeSet.has(componentType)) continue;
 			const detailedType = getDetailedIdType(componentType);
-			if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId)) this.dontFragmentRelations.setValue(entityId, componentType, data);
+			if (isRelationType(detailedType) && isSparseComponent(detailedType.componentId)) this.sparseRelations.setValue(entityId, componentType, data);
 		}
 	}
 	getEntity(entityId) {
@@ -846,18 +833,16 @@ var Archetype = class {
 			const data = this.getComponentData(componentType)[index];
 			entityData.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
 		}
-		const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entityId);
-		for (const [componentType, data] of dontFragmentTuples) entityData.set(componentType, data);
+		const sparseTuples = this.sparseRelations.getAllForEntity(entityId);
+		for (const [componentType, data] of sparseTuples) entityData.set(componentType, data);
 		return entityData;
 	}
 	/**
-	* Returns all dontFragment relations for the given entity as an array of tuples.
-	* This is a compatibility adapter during the store refactor.
-	*
-	* Prefer the new DontFragmentStore methods when possible.
+	* Returns all sparse-stored relations for the given entity.
+	* Internal helper used by command processing and tests.
 	*/
-	getEntityDontFragmentRelations(entityId) {
-		const tuples = this.dontFragmentRelations.getAllForEntity(entityId);
+	getEntitySparseRelations(entityId) {
+		const tuples = this.sparseRelations.getAllForEntity(entityId);
 		if (tuples.length === 0) return void 0;
 		const map = /* @__PURE__ */ new Map();
 		for (const [relType, data] of tuples) map.set(relType, data);
@@ -870,22 +855,61 @@ var Archetype = class {
 				const data = this.getComponentData(componentType)[i];
 				components.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
 			}
-			const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entity);
-			for (const [componentType, data] of dontFragmentTuples) components.set(componentType, data);
+			const sparseTuples = this.sparseRelations.getAllForEntity(entity);
+			for (const [componentType, data] of sparseTuples) components.set(componentType, data);
 			return {
 				entity,
 				components
 			};
 		});
 	}
+	/**
+	* @internal Serialization fast-path.
+	*
+	* Appends SerializedEntity records directly from the archetype's column storage
+	* (componentData arrays) plus sparse relations, avoiding per-entity Map
+	* allocation and repeated Array.from(entries()).
+	*
+	* Component type IDs should be pre-encoded by the caller (once per archetype)
+	* and passed in `encodedComponentTypes` (same order and length as this.componentTypes).
+	*
+	* The provided `encode` function should be the cached variant for best performance
+	* on entity IDs and any sparse relation type IDs.
+	*
+	* `sparseByEntity` is an optional pre-fetched map from a bulk
+	* `SparseStore.getAllForEntities` call (further reduces per-entity calls).
+	*/
+	appendSerializedEntities(out, encode, encodedComponentTypes, sparseByEntity) {
+		if (encodedComponentTypes.length !== this.componentTypes.length) throw new Error("encodedComponentTypes length must match archetype componentTypes");
+		for (let i = 0; i < this.entities.length; i++) {
+			const entity = this.entities[i];
+			const components = [];
+			for (let c = 0; c < this.componentTypes.length; c++) {
+				const data = this.getComponentData(this.componentTypes[c])[i];
+				components.push({
+					type: encodedComponentTypes[c],
+					value: data === MISSING_COMPONENT ? void 0 : data
+				});
+			}
+			const sparseTuples = sparseByEntity?.get(entity) ?? this.sparseRelations.getAllForEntity(entity);
+			for (const [componentType, data] of sparseTuples) components.push({
+				type: encode(componentType),
+				value: data
+			});
+			out.push({
+				id: encode(entity),
+				components
+			});
+		}
+	}
 	removeEntity(entityId) {
 		const index = this.entityToIndex.get(entityId);
 		if (index === void 0) return void 0;
 		const removedData = /* @__PURE__ */ new Map();
 		for (const componentType of this.componentTypes) removedData.set(componentType, this.getComponentData(componentType)[index]);
-		const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entityId);
-		for (const [componentType, data] of dontFragmentTuples) removedData.set(componentType, data);
-		this.dontFragmentRelations.deleteEntity(entityId);
+		const sparseTuples = this.sparseRelations.getAllForEntity(entityId);
+		for (const [componentType, data] of sparseTuples) removedData.set(componentType, data);
+		this.sparseRelations.deleteEntity(entityId);
 		this.entityToIndex.delete(entityId);
 		const lastIndex = this.entities.length - 1;
 		if (index !== lastIndex) {
@@ -924,7 +948,7 @@ var Archetype = class {
 			}
 		}
 		if (componentId !== void 0) {
-			const matches = this.dontFragmentRelations.getRelationsForComponent(entityId, componentId);
+			const matches = this.sparseRelations.getRelationsForComponent(entityId, componentId);
 			for (const m of matches) relations.push(m);
 		}
 		return relations;
@@ -935,7 +959,7 @@ var Archetype = class {
 			if (data === MISSING_COMPONENT) throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
 			return data;
 		}
-		if (this.dontFragmentRelations.getValue(entityId, componentType) !== void 0 || this.dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return this.dontFragmentRelations.getValue(entityId, componentType);
+		if (this.sparseRelations.getValue(entityId, componentType) !== void 0 || this.sparseRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return this.sparseRelations.getValue(entityId, componentType);
 		throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
 	}
 	getOptional(entityId, componentType) {
@@ -946,9 +970,9 @@ var Archetype = class {
 			if (data === MISSING_COMPONENT) return void 0;
 			return { value: data };
 		}
-		const value = this.dontFragmentRelations.getValue(entityId, componentType);
+		const value = this.sparseRelations.getValue(entityId, componentType);
 		if (value !== void 0) return { value };
-		if (this.dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return { value: this.dontFragmentRelations.getValue(entityId, componentType) };
+		if (this.sparseRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) return { value: this.sparseRelations.getValue(entityId, componentType) };
 	}
 	set(entityId, componentType, data) {
 		const index = this.entityToIndex.get(entityId);
@@ -958,8 +982,8 @@ var Archetype = class {
 			return;
 		}
 		const detailedType = getDetailedIdType(componentType);
-		if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId)) {
-			this.dontFragmentRelations.setValue(entityId, componentType, data);
+		if (isRelationType(detailedType) && isSparseComponent(detailedType.componentId)) {
+			this.sparseRelations.setValue(entityId, componentType, data);
 			return;
 		}
 		throw new Error(`Component type ${componentType} is not in this archetype`);
@@ -992,7 +1016,7 @@ var Archetype = class {
 		return optional ? this.getOptionalComponentData(actualType) : this.getComponentData(actualType);
 	}
 	buildComponentsForIndex(componentTypes, componentDataSources, entityIndex, entityId) {
-		return componentDataSources.map((dataSource, i) => buildSingleComponent(componentTypes[i], dataSource, entityIndex, entityId, (type) => this.getComponentData(type), this.dontFragmentRelations));
+		return componentDataSources.map((dataSource, i) => buildSingleComponent(componentTypes[i], dataSource, entityIndex, entityId, (type) => this.getComponentData(type), this.sparseRelations));
 	}
 	getEntitiesWithComponents(componentTypes) {
 		const result = [];
@@ -1029,8 +1053,8 @@ var Archetype = class {
 				const data = this.getComponentData(componentType)[i];
 				components.set(componentType, data === MISSING_COMPONENT ? void 0 : data);
 			}
-			const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entity);
-			for (const [componentType, data] of dontFragmentTuples) components.set(componentType, data);
+			const sparseTuples = this.sparseRelations.getAllForEntity(entity);
+			for (const [componentType, data] of sparseTuples) components.set(componentType, data);
 			callback(entity, components);
 		}
 	}
@@ -1039,30 +1063,31 @@ var Archetype = class {
 			const detailedType = getDetailedIdType(componentType);
 			if (isRelationType(detailedType) && detailedType.componentId === componentId) return true;
 		}
-		for (const entityId of this.entities) if (this.dontFragmentRelations.getRelationsForComponent(entityId, componentId).length > 0) return true;
+		for (const entityId of this.entities) if (this.sparseRelations.getRelationsForComponent(entityId, componentId).length > 0) return true;
 		return false;
 	}
 };
 //#endregion
 //#region src/archetype/store.ts
 /**
-* Production implementation of DontFragmentStore.
+* Production implementation of SparseStore.
 *
 * Internal layout (optimized):
 * - byComponent: baseComponentId → (entityId → RelationEntry)
 *   RelationEntry uses a single-value form for the common exclusive case (1 target),
-*   avoiding Map allocation entirely for the vast majority of dontFragment usage.
+*   avoiding Map allocation for the vast majority of usage.
 * - entityIndex: entityId → Set<baseComponentId>
 *   Lightweight reverse index.
 */
-var DontFragmentStoreImpl = class {
+var SparseStoreImpl = class {
 	/**
 	* Primary storage, keyed by the base relation component ID.
 	*/
 	byComponent = /* @__PURE__ */ new Map();
 	/**
 	* Reverse index: which base component kinds an entity participates in.
-	* Used only by the infrequent getAllForEntity / deleteEntity paths.
+	* Only required to support getAllForEntity and deleteEntity efficiently.
+	* The primary storage (byComponent) is deliberately not optimized for these operations.
 	*/
 	entityIndex = /* @__PURE__ */ new Map();
 	getValue(entityId, relationType) {
@@ -1081,7 +1106,7 @@ var DontFragmentStoreImpl = class {
 	}
 	setValue(entityId, relationType, data) {
 		const componentId = getComponentIdFromRelationId(relationType);
-		if (componentId === void 0) throw new Error("setValue called with a non-relation type on DontFragmentStore");
+		if (componentId === void 0) throw new Error("setValue called with a non-relation type on SparseStore");
 		let entities = this.byComponent.get(componentId);
 		if (!entities) {
 			entities = /* @__PURE__ */ new Map();
@@ -1199,6 +1224,14 @@ var DontFragmentStoreImpl = class {
 		}
 		this.entityIndex.delete(entityId);
 	}
+	getAllForEntities(entityIds) {
+		const result = /* @__PURE__ */ new Map();
+		for (const eid of entityIds) {
+			const data = this.getAllForEntity(eid);
+			if (data.length > 0) result.set(eid, data);
+		}
+		return result;
+	}
 };
 //#endregion
 //#region src/commands/buffer.ts
@@ -1249,7 +1282,8 @@ var CommandBuffer = class {
 		});
 	}
 	/**
-	* Execute all commands and clear the buffer
+	* Execute all commands and clear the buffer.
+	* Returns the number of iterations performed (for debug stats).
 	*/
 	execute() {
 		let iterations = 0;
@@ -1269,6 +1303,7 @@ var CommandBuffer = class {
 			for (const [entityId, commands] of entityCommands) this.executeEntityCommands(entityId, commands);
 			entityCommands.clear();
 		}
+		return iterations;
 	}
 	/**
 	* Get current commands (for testing)
@@ -1339,29 +1374,6 @@ var ComponentChangeset = class {
 		for (const [componentType, component] of this.adds) existingComponents.set(componentType, component);
 		return existingComponents;
 	}
-	/**
-	* 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;
-			}
-			changed = true;
-			finalComponentTypes.delete(componentType);
-		}
-		for (const componentType of this.adds.keys()) {
-			if (finalComponentTypes.has(componentType)) continue;
-			changed = true;
-			finalComponentTypes.add(componentType);
-		}
-		return changed ? Array.from(finalComponentTypes) : void 0;
-	}
 };
 //#endregion
 //#region src/component/entity-store.ts
@@ -1550,7 +1562,7 @@ function matchesComponentTypes(archetype, componentTypes) {
 			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)) {
+		else if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId !== void 0 && isSparseComponent(detailedType.componentId)) {
 			const wildcardMarker = relation(detailedType.componentId, "*");
 			return archetype.componentTypeSet.has(wildcardMarker);
 		} else return archetype.componentTypeSet.has(type);
@@ -1597,8 +1609,8 @@ var Query = class {
 	_cacheKey;
 	/** Cached wildcard component types for faster entity filtering */
 	wildcardTypes;
-	/** Cached specific dontFragment relation types that need entity-level filtering */
-	specificDontFragmentTypes;
+	/** Cached specific sparse relation types that need entity-level filtering */
+	specificSparseRelationTypes;
 	/**
 	* @internal Queries should be created via {@link World.createQuery}, not instantiated directly.
 	*/
@@ -1607,9 +1619,9 @@ var Query = class {
 		this.componentTypes = normalizeComponentTypes(componentTypes);
 		this.filter = filter;
 		this.wildcardTypes = this.componentTypes.filter((ct) => getDetailedIdType(ct).type === "wildcard-relation");
-		this.specificDontFragmentTypes = this.componentTypes.filter((ct) => {
+		this.specificSparseRelationTypes = this.componentTypes.filter((ct) => {
 			const detailedType = getDetailedIdType(ct);
-			return (detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId !== void 0 && isDontFragmentComponent(detailedType.componentId);
+			return (detailedType.type === "entity-relation" || detailedType.type === "component-relation") && detailedType.componentId !== void 0 && isSparseComponent(detailedType.componentId);
 		});
 		this.updateCache();
 		if (registry) registry.register(this);
@@ -1633,7 +1645,7 @@ var Query = class {
 	*/
 	getEntities() {
 		this.ensureNotDisposed();
-		if (this.wildcardTypes.length === 0 && this.specificDontFragmentTypes.length === 0) {
+		if (this.wildcardTypes.length === 0 && this.specificSparseRelationTypes.length === 0) {
 			const result = [];
 			for (const archetype of this.cachedArchetypes) for (const entity of archetype.getEntities()) result.push(entity);
 			return result;
@@ -1643,14 +1655,14 @@ var Query = class {
 		return result;
 	}
 	/**
-	* Check if entity matches all query requirements (wildcards and specific dontFragment relations)
+	* Check if entity matches all query requirements (wildcards and specific sparse 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;
+		for (const specificType of this.specificSparseRelationTypes) if (archetype.getOptional(entity, specificType) === void 0) return false;
 		return true;
 	}
 	/**
@@ -1872,7 +1884,7 @@ function processSetCommand(entityId, currentArchetype, componentType, component,
 	const componentId = getComponentIdFromRelationId(componentType);
 	if (componentId !== void 0) {
 		handleExclusiveRelation(entityId, currentArchetype, componentId);
-		if (isDontFragmentComponent(componentId)) {
+		if (isSparseComponent(componentId)) {
 			const wildcardMarker = relation(componentId, "*");
 			if (!currentArchetype.componentTypeSet.has(wildcardMarker)) changeset.set(wildcardMarker, void 0);
 		}
@@ -1898,17 +1910,17 @@ function removeMatchingRelations(entityId, archetype, baseComponentId, changeset
 		if (isWildcardRelationId(componentType)) continue;
 		if (getComponentIdFromRelationId(componentType) === baseComponentId) changeset.delete(componentType);
 	}
-	const dontFragmentData = archetype.getEntityDontFragmentRelations(entityId);
-	if (dontFragmentData) {
-		for (const componentType of dontFragmentData.keys()) if (getComponentIdFromRelationId(componentType) === baseComponentId) changeset.delete(componentType);
+	const sparseData = archetype.getEntitySparseRelations(entityId);
+	if (sparseData) {
+		for (const componentType of sparseData.keys()) if (getComponentIdFromRelationId(componentType) === baseComponentId) changeset.delete(componentType);
 	}
 }
 function removeWildcardRelations(entityId, currentArchetype, baseComponentId, changeset) {
 	removeMatchingRelations(entityId, currentArchetype, baseComponentId, changeset);
-	if (isDontFragmentComponent(baseComponentId)) changeset.delete(relation(baseComponentId, "*"));
+	if (isSparseComponent(baseComponentId)) changeset.delete(relation(baseComponentId, "*"));
 }
 function maybeRemoveWildcardMarker(entityId, archetype, removedComponentType, componentId, changeset) {
-	if (componentId === void 0 || !isDontFragmentComponent(componentId)) return;
+	if (componentId === void 0 || !isSparseComponent(componentId)) return;
 	const wildcardMarker = relation(componentId, "*");
 	for (const otherComponentType of archetype.componentTypes) {
 		if (otherComponentType === removedComponentType) continue;
@@ -1916,8 +1928,8 @@ function maybeRemoveWildcardMarker(entityId, archetype, removedComponentType, co
 		if (changeset.removes.has(otherComponentType)) continue;
 		if (getComponentIdFromRelationId(otherComponentType) === componentId) return;
 	}
-	const dontFragmentData = archetype.getEntityDontFragmentRelations(entityId);
-	if (dontFragmentData) for (const otherComponentType of dontFragmentData.keys()) {
+	const sparseData = archetype.getEntitySparseRelations(entityId);
+	if (sparseData) for (const otherComponentType of sparseData.keys()) {
 		if (otherComponentType === removedComponentType) continue;
 		if (changeset.removes.has(otherComponentType)) continue;
 		if (getComponentIdFromRelationId(otherComponentType) === componentId) return;
@@ -1930,7 +1942,7 @@ function maybeRemoveWildcardMarker(entityId, archetype, removedComponentType, co
 }
 function hasEntityComponent(archetype, entityId, componentType) {
 	if (archetype.componentTypeSet.has(componentType)) return true;
-	return archetype.getEntityDontFragmentRelations(entityId)?.has(componentType) ?? false;
+	return archetype.getEntitySparseRelations(entityId)?.has(componentType) ?? false;
 }
 function pruneMissingRemovals(changeset, archetype, entityId) {
 	let toPrune;
@@ -1941,14 +1953,14 @@ function pruneMissingRemovals(changeset, archetype, entityId) {
 	if (toPrune !== void 0) for (const componentType of toPrune) changeset.removes.delete(componentType);
 }
 function hasArchetypeStructuralChange(changeset, currentArchetype) {
-	for (const componentType of changeset.removes) if (!isDontFragmentRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) return true;
-	for (const componentType of changeset.adds.keys()) if (!isDontFragmentRelation(componentType) && !currentArchetype.componentTypeSet.has(componentType)) return true;
+	for (const componentType of changeset.removes) if (!isSparseRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) return true;
+	for (const componentType of changeset.adds.keys()) if (!isSparseRelation(componentType) && !currentArchetype.componentTypeSet.has(componentType)) return true;
 	return false;
 }
 function buildFinalRegularComponentTypes(currentArchetype, changeset) {
 	const finalRegularTypes = new Set(currentArchetype.componentTypes);
-	for (const componentType of changeset.removes) if (!isDontFragmentRelation(componentType)) finalRegularTypes.delete(componentType);
-	for (const [componentType] of changeset.adds) if (!isDontFragmentRelation(componentType)) finalRegularTypes.add(componentType);
+	for (const componentType of changeset.removes) if (!isSparseRelation(componentType)) finalRegularTypes.delete(componentType);
+	for (const [componentType] of changeset.adds) if (!isSparseRelation(componentType)) finalRegularTypes.add(componentType);
 	return Array.from(finalRegularTypes);
 }
 function applyChangeset(ctx, entityId, currentArchetype, changeset, entityToArchetype, removedComponents) {
@@ -1962,39 +1974,34 @@ function applyChangeset(ctx, entityId, currentArchetype, changeset, entityToArch
 		entityToArchetype.set(entityId, newArchetype);
 		return newArchetype;
 	}
-	if (removedComponents !== null) applyDontFragmentChanges(ctx.dontFragmentStore, entityId, changeset, removedComponents);
-	else applyDontFragmentChangesNoHooks(ctx.dontFragmentStore, entityId, changeset);
+	if (removedComponents !== null) applySparseChanges(ctx.sparseStore, entityId, changeset, removedComponents);
+	else applySparseChangesNoHooks(ctx.sparseStore, entityId, changeset);
 	for (const [componentType, component] of changeset.adds) {
-		if (isDontFragmentRelation(componentType)) continue;
+		if (isSparseRelation(componentType)) continue;
 		currentArchetype.set(entityId, componentType, component);
 	}
 	return currentArchetype;
 }
-/**
-* No-hooks variant of applyDontFragmentChanges that skips tracking removed component data.
-*
-* Rewritten for the new DontFragmentStore interface (ComponentId-primary storage).
-*/
-function applyDontFragmentChanges(dontFragmentRelations, entityId, changeset, removedComponents) {
-	for (const componentType of changeset.removes) if (isDontFragmentRelation(componentType)) {
-		const removedValue = dontFragmentRelations.getValue(entityId, componentType);
-		if (removedValue !== void 0 || dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) removedComponents.set(componentType, removedValue);
-		dontFragmentRelations.deleteValue(entityId, componentType);
+function applySparseChanges(sparseStore, entityId, changeset, removedComponents) {
+	for (const componentType of changeset.removes) if (isSparseRelation(componentType)) {
+		const removedValue = sparseStore.getValue(entityId, componentType);
+		if (removedValue !== void 0 || sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)) removedComponents.set(componentType, removedValue);
+		sparseStore.deleteValue(entityId, componentType);
 	}
-	for (const [componentType, component] of changeset.adds) if (isDontFragmentRelation(componentType)) dontFragmentRelations.setValue(entityId, componentType, component);
+	for (const [componentType, component] of changeset.adds) if (isSparseRelation(componentType)) sparseStore.setValue(entityId, componentType, component);
 }
-function applyDontFragmentChangesNoHooks(dontFragmentRelations, entityId, changeset) {
-	for (const componentType of changeset.removes) if (isDontFragmentRelation(componentType)) dontFragmentRelations.deleteValue(entityId, componentType);
-	for (const [componentType, component] of changeset.adds) if (isDontFragmentRelation(componentType)) dontFragmentRelations.setValue(entityId, componentType, component);
+function applySparseChangesNoHooks(sparseStore, entityId, changeset) {
+	for (const componentType of changeset.removes) if (isSparseRelation(componentType)) sparseStore.deleteValue(entityId, componentType);
+	for (const [componentType, component] of changeset.adds) if (isSparseRelation(componentType)) sparseStore.setValue(entityId, componentType, component);
 }
 function filterRegularComponentTypes(componentTypes) {
 	const regularTypes = [];
 	for (const componentType of componentTypes) {
-		if (isDontFragmentWildcard(componentType)) {
+		if (isSparseWildcard(componentType)) {
 			regularTypes.push(componentType);
 			continue;
 		}
-		if (isDontFragmentRelation(componentType)) continue;
+		if (isSparseRelation(componentType)) continue;
 		regularTypes.push(componentType);
 	}
 	return regularTypes;
@@ -2002,9 +2009,15 @@ function filterRegularComponentTypes(componentTypes) {
 //#endregion
 //#region src/world/hooks.ts
 /**
+* Debug-only counter incremented on every invokeHook call when armed.
+* World reads and resets this during armed syncs.
+*/
+const debugHookExecutionCounter = { value: 0 };
+/**
 * Unified hook invocation: prefers entry.callback (callback style) over hook.on_* (object style).
 */
 function invokeHook(entry, event, entityId, components) {
+	debugHookExecutionCounter.value++;
 	if (entry.callback) {
 		entry.callback(event, entityId, ...components);
 		return;
@@ -2303,9 +2316,9 @@ function getEntityReferences(entityReferences, targetEntityId) {
 //#endregion
 //#region src/storage/serialization.ts
 /**
-* Encode an internal EntityId into a SerializedEntityId for snapshots
+* Core encoding logic (no cache). Extracted so cached wrapper can reuse it without duplication.
 */
-function encodeEntityId(id) {
+function encodeEntityIdCore(id) {
 	const detailed = getDetailedIdType(id);
 	switch (detailed.type) {
 		case "component": {
@@ -2343,6 +2356,20 @@ function encodeEntityId(id) {
 	}
 }
 /**
+* Encode an EntityId, using an optional cache Map to avoid repeated getDetailedIdType
+* + name lookup work for IDs that appear many times (typical during full world snapshot).
+*/
+function encodeEntityIdCached(id, cache) {
+	if (cache) {
+		const cached = cache.get(id);
+		if (cached !== void 0) return cached;
+		const result = encodeEntityIdCore(id);
+		cache.set(id, result);
+		return result;
+	}
+	return encodeEntityIdCore(id);
+}
+/**
 * Decode a SerializedEntityId back into an internal EntityId
 */
 function decodeSerializedId(sid) {
@@ -2383,24 +2410,16 @@ function decodeSerializedId(sid) {
 * Serializes the full world state to a plain JS object suitable for JSON encoding.
 */
 function serializeWorld(archetypes, componentEntities, entityIdManager) {
+	const idCache = /* @__PURE__ */ new Map();
 	const entities = [];
 	for (const archetype of archetypes) {
-		const dumpedEntities = archetype.dump();
-		for (const { entity, components } of dumpedEntities) entities.push({
-			id: encodeEntityId(entity),
-			components: Array.from(components.entries()).map(([rawType, value]) => ({
-				type: encodeEntityId(rawType),
-				value: value === MISSING_COMPONENT ? void 0 : value
-			}))
-		});
+		const encodedComponentTypes = archetype.componentTypes.map((t) => encodeEntityIdCached(t, idCache));
+		archetype.appendSerializedEntities(entities, (id) => encodeEntityIdCached(id, idCache), encodedComponentTypes);
 	}
 	const componentEntitiesArr = [];
 	for (const [entityId, components] of componentEntities.entries()) componentEntitiesArr.push({
-		id: encodeEntityId(entityId),
-		components: Array.from(components.entries()).map(([rawType, value]) => ({
-			type: encodeEntityId(rawType),
-			value: value === MISSING_COMPONENT ? void 0 : value
-		}))
+		id: encodeEntityIdCached(entityId, idCache),
+		components: serializeComponentsFromMap(components, idCache)
 	});
 	return {
 		version: 1,
@@ -2409,6 +2428,15 @@ function serializeWorld(archetypes, componentEntities, entityIdManager) {
 		componentEntities: componentEntitiesArr
 	};
 }
+/** Small helper to avoid duplicating the "Map → SerializedComponent[] with cache" pattern. */
+function serializeComponentsFromMap(components, idCache) {
+	const result = [];
+	for (const [rawType, value] of components) result.push({
+		type: encodeEntityIdCached(rawType, idCache),
+		value: value === MISSING_COMPONENT ? void 0 : value
+	});
+	return result;
+}
 /**
 * Restores world state from a snapshot into the provided context.
 * Intended to be called from `World`'s constructor.
@@ -2430,12 +2458,11 @@ function deserializeWorld(ctx, snapshot) {
 		const entityId = decodeSerializedId(entry.id);
 		const componentsArray = entry.components || [];
 		const componentMap = /* @__PURE__ */ new Map();
-		const componentTypes = [];
 		for (const componentEntry of componentsArray) {
 			const componentType = decodeSerializedId(componentEntry.type);
 			componentMap.set(componentType, componentEntry.value);
-			componentTypes.push(componentType);
 		}
+		const componentTypes = Array.from(componentMap.keys());
 		const archetype = ctx.ensureArchetype(componentTypes);
 		archetype.addEntity(entityId, componentMap);
 		ctx.setEntityToArchetype(entityId, archetype);
@@ -2461,18 +2488,22 @@ var World = class {
 	entityReferences = /* @__PURE__ */ new Map();
 	/** Reverse index: entity ID → set of archetypes whose componentTypes include that entity ID */
 	entityToReferencingArchetypes = /* @__PURE__ */ new Map();
-	/** DontFragment relation storage, shared with all Archetype instances */
-	dontFragmentStore = new DontFragmentStoreImpl();
+	/** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
+	sparseStore = new SparseStoreImpl();
 	/** Component entity (singleton) storage */
 	componentEntities = new ComponentEntityStore();
 	queryRegistry = new QueryRegistry();
 	hooks = /* @__PURE__ */ new Set();
+	_debugCollectors = /* @__PURE__ */ new Set();
+	_debugMigrations = 0;
+	_debugArchetypesCreated = 0;
+	_debugArchetypesRemoved = 0;
 	commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
 	_changeset = new ComponentChangeset();
 	_removeChangeset = new ComponentChangeset();
 	/** Cached command processor context to avoid per-entity object allocation */
 	_commandCtx = {
-		dontFragmentStore: this.dontFragmentStore,
+		sparseStore: this.sparseStore,
 		ensureArchetype: (ct) => this.ensureArchetype(ct)
 	};
 	/** Cached hooks context to avoid per-entity object allocation */
@@ -2678,9 +2709,9 @@ var World = class {
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) return false;
 		if (archetype.componentTypeSet.has(componentType)) return true;
-		if (isDontFragmentRelation(componentType)) {
-			if (this.dontFragmentStore.getValue(entityId, componentType) !== void 0) return true;
-			return this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType);
+		if (isSparseRelation(componentType)) {
+			if (this.sparseStore.getValue(entityId, componentType) !== void 0) return true;
+			return this.sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType);
 		}
 		return false;
 	}
@@ -2693,8 +2724,8 @@ var World = class {
 		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
 		if (componentType >= 0 || componentType % RELATION_SHIFT !== 0) {
 			const inArchetype = archetype.componentTypeSet.has(componentType);
-			const hasDontFragment = isDontFragmentRelation(componentType);
-			if (!(inArchetype || hasDontFragment && (this.dontFragmentStore.getValue(entityId, componentType) !== void 0 || this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType)))) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
+			const hasSparse = isSparseRelation(componentType);
+			if (!(inArchetype || hasSparse && (this.sparseStore.getValue(entityId, componentType) !== void 0 || this.sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)))) throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
 		}
 		return archetype.get(entityId, componentType);
 	}
@@ -2716,6 +2747,163 @@ var World = class {
 		}
 		return archetype.getOptional(entityId, componentType);
 	}
+	/**
+	* Retrieves all targets (and their associated data) for relations of a given
+	* base component on an entity.
+	*
+	* This is the ergonomic replacement for the common pattern:
+	*   world.get(entity, relation(Comp, "*"))
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const children = world.getRelationTargets(parent, ChildOf); // usually []
+	* const items = world.getRelationTargets(player, InInventory);
+	*
+	* // For common hierarchy use cases, prefer the higher-level helpers:
+	* // world.getChildren(parent, ChildOf), world.getParent(child, ChildOf)
+	*/
+	getRelationTargets(entityId, relationComp) {
+		this.assertEntityExists(entityId, "Entity");
+		const wildcard = relation(relationComp, "*");
+		if (this.componentEntities.exists(entityId)) return this.componentEntities.getWildcard(entityId, wildcard);
+		return this.get(entityId, wildcard);
+	}
+	/**
+	* Returns every entity that currently holds a relation of the given base
+	* component pointing at `targetId`.
+	*
+	* This is the efficient **reverse** lookup. For common hierarchy cases,
+	* prefer the higher-level `world.getChildren(parent, ChildOf)` instead.
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const directChildren = world.getRelationSources(ship, ChildOf);
+	*/
+	getRelationSources(targetId, relationComp) {
+		const refs = getEntityReferences(this.entityReferences, targetId);
+		const result = [];
+		for (const [source, relType] of refs) {
+			if (!this.entityToArchetype.has(source) && !this.componentEntities.exists(source)) continue;
+			if (getComponentIdFromRelationId(relType) === relationComp) result.push(source);
+		}
+		return result;
+	}
+	/**
+	* Returns true if the entity has any (or a specific-target) relation of the
+	* given base component.
+	*/
+	hasRelation(entityId, relationComp, targetId) {
+		this.assertEntityExists(entityId, "Entity");
+		if (targetId !== void 0) {
+			const specific = relation(relationComp, targetId);
+			return this.has(entityId, specific);
+		}
+		return this.getRelationTargets(entityId, relationComp).length > 0;
+	}
+	/**
+	* Returns the number of relations of the given base component held by the entity.
+	*/
+	countRelations(entityId, relationComp) {
+		this.assertEntityExists(entityId, "Entity");
+		return this.getRelationTargets(entityId, relationComp).length;
+	}
+	/**
+	* For an *exclusive* relation (e.g. ChildOf, Owner), returns the single
+	* target entity (or undefined if none).
+	*
+	* When the component was declared `exclusive: true`, this is the preferred
+	* accessor (clearer intent than array destructuring).
+	*/
+	getSingleRelationTarget(entityId, relationComp) {
+		const targets = this.getRelationTargets(entityId, relationComp);
+		return targets.length > 0 ? targets[0][0] : void 0;
+	}
+	/**
+	* Returns the direct children of `parent` for the given relationship component
+	* (typically a `ChildOf` or similar exclusive `sparse` relation).
+	*
+	* This is the recommended high-level API for hierarchy traversal.
+	* It uses the internal reverse reference index for efficiency.
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const kids = world.getChildren(ship, ChildOf);
+	*/
+	getChildren(parent, childOf) {
+		return this.getRelationSources(parent, childOf);
+	}
+	/**
+	* Returns the parent of `child` for the given relationship component
+	* (typically an exclusive `ChildOf` relation).
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const parent = world.getParent(turret, ChildOf);
+	*/
+	getParent(child, childOf) {
+		return this.getSingleRelationTarget(child, childOf);
+	}
+	/**
+	* Returns the ancestor chain from the immediate parent up to (but not
+	* including) the root for the given relationship component.
+	*
+	* @example
+	* const ChildOf = component({ exclusive: true, sparse: true });
+	* const ancestors = world.getAncestors(muzzle, ChildOf); // [turret, ship]
+	*/
+	getAncestors(entity, childOf) {
+		const ancestors = [];
+		let cur = this.getParent(entity, childOf);
+		while (cur !== void 0) {
+			ancestors.push(cur);
+			cur = this.getParent(cur, childOf);
+		}
+		return ancestors;
+	}
+	/**
+	* Iteratively traverses all descendants of `root` in DFS pre-order.
+	* This is a generator and is safe for very deep hierarchies.
+	*
+	* @example
+	* for (const { entity, depth, parent } of world.iterateDescendants(root, ChildOf)) {
+	*   console.log(depth, entity);
+	* }
+	*/
+	*iterateDescendants(root, childOf, opts = {}) {
+		const { includeSelf = false, maxDepth } = opts;
+		const stack = [];
+		if (includeSelf) stack.push({
+			entity: root,
+			depth: 0,
+			parent: null
+		});
+		else for (const child of this.getChildren(root, childOf)) stack.push({
+			entity: child,
+			depth: 1,
+			parent: root
+		});
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (maxDepth !== void 0 && current.depth > maxDepth) continue;
+			yield current;
+			const kids = this.getChildren(current.entity, childOf);
+			for (let i = kids.length - 1; i >= 0; i--) {
+				const k = kids[i];
+				stack.push({
+					entity: k,
+					depth: current.depth + 1,
+					parent: current.entity
+				});
+			}
+		}
+	}
+	/**
+	* Callback-based descendant traversal (hot path friendly).
+	* Return `false` from the visitor to stop early.
+	*/
+	traverseDescendants(root, childOf, visitor, opts = {}) {
+		for (const { entity, depth, parent } of this.iterateDescendants(root, childOf, opts)) if (visitor(entity, depth, parent) === false) return;
+	}
 	hook(componentTypes, hook, filter) {
 		const isCallback = typeof hook === "function";
 		const callback = isCallback ? hook : void 0;
@@ -2751,6 +2939,74 @@ var World = class {
 		};
 	}
 	/**
+	* Creates a debug stats collector that will receive a `SyncDebugStats` payload
+	* after every subsequent `sync()`.
+	*
+	* The returned object is a pure lifecycle handle. It does not store data.
+	* Collection stops when you call `[Symbol.dispose]()` (or use a `using` declaration).
+	*
+	* All active collectors receive the exact same stats object for a given sync.
+	* Exceptions thrown by callbacks are ignored.
+	*
+	* This is intended for development/debugging and leak detection.
+	*/
+	createDebugStatsCollector(callback) {
+		this._debugCollectors.add(callback);
+		return { [Symbol.dispose]: () => {
+			this._debugCollectors.delete(callback);
+		} };
+	}
+	_resetDebugActivityCounters() {
+		this._debugMigrations = 0;
+		this._debugArchetypesCreated = 0;
+		this._debugArchetypesRemoved = 0;
+		debugHookExecutionCounter.value = 0;
+	}
+	_deliverDebugStats(timings) {
+		const entityCount = this.entityToArchetype.size;
+		let emptyArchetypes = 0;
+		for (const arch of this.archetypes) if (arch.size === 0) emptyArchetypes++;
+		let archetypesByComponentSize = 0;
+		for (const set of this.archetypesByComponent.values()) archetypesByComponentSize += set.size;
+		const stats = {
+			timestamps: {
+				syncStart: timings.syncStart,
+				syncEnd: timings.syncEnd,
+				commandBufferStart: timings.commandBufferStart,
+				commandBufferEnd: timings.commandBufferEnd
+			},
+			commandIterations: timings.commandIterations,
+			entities: {
+				total: entityCount,
+				freelistSize: this.entityIdManager.getFreelistSize(),
+				nextId: this.entityIdManager.getNextId()
+			},
+			archetypes: {
+				total: this.archetypes.length,
+				empty: emptyArchetypes
+			},
+			queries: {
+				cached: this.queryRegistry.cache?.size ?? 0,
+				registered: this.queryRegistry.queries?.size ?? 0
+			},
+			hooks: { total: this.hooks.size },
+			indices: {
+				entityReferences: this.entityReferences.size,
+				entityToReferencingArchetypes: this.entityToReferencingArchetypes.size,
+				archetypesByComponent: archetypesByComponentSize
+			},
+			activity: {
+				migrations: this._debugMigrations,
+				hooksExecuted: debugHookExecutionCounter.value,
+				archetypesCreated: this._debugArchetypesCreated,
+				archetypesRemoved: this._debugArchetypesRemoved
+			}
+		};
+		for (const cb of this._debugCollectors) try {
+			cb(stats);
+		} catch {}
+	}
+	/**
 	* Synchronizes all buffered commands (set/remove/delete) to the world.
 	* This method must be called after making changes via `set()`, `remove()`, or `delete()` for them to take effect.
 	* Typically called once per frame at the end of your game loop.
@@ -2761,7 +3017,20 @@ var World = class {
 	* world.sync(); // Apply all buffered changes
 	*/
 	sync() {
-		this.commandBuffer.execute();
+		const hasCollectors = this._debugCollectors.size > 0;
+		const syncStart = hasCollectors ? performance.now() : 0;
+		if (hasCollectors) this._resetDebugActivityCounters();
+		const commandBufferStart = hasCollectors ? performance.now() : 0;
+		const commandIterations = this.commandBuffer.execute();
+		const commandBufferEnd = hasCollectors ? performance.now() : 0;
+		const syncEnd = hasCollectors ? performance.now() : 0;
+		if (hasCollectors) this._deliverDebugStats({
+			syncStart,
+			syncEnd,
+			commandBufferStart,
+			commandBufferEnd,
+			commandIterations
+		});
 	}
 	/**
 	* Creates a cached query for efficiently iterating entities with specific components.
@@ -2935,13 +3204,15 @@ var World = class {
 		});
 		const hasStructuralChange = changeset.removes.size > 0 || changeset.adds.size > 0;
 		if (this.hooks.size === 0) {
-			applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype, null);
+			const newArchetype = applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype, null);
 			if (hasStructuralChange) this.updateEntityReferences(entityId, changeset);
+			if (this._debugCollectors.size > 0 && newArchetype !== currentArchetype) this._debugMigrations++;
 			return;
 		}
 		const removedComponents = /* @__PURE__ */ new Map();
 		const newArchetype = applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype, removedComponents);
 		if (hasStructuralChange) this.updateEntityReferences(entityId, changeset);
+		if (this._debugCollectors.size > 0 && newArchetype !== currentArchetype) this._debugMigrations++;
 		triggerLifecycleHooks(this.createHooksContext(), entityId, changeset.adds, removedComponents, currentArchetype, newArchetype);
 	}
 	createHooksContext() {
@@ -3004,8 +3275,9 @@ var World = class {
 		}
 	}
 	createNewArchetype(componentTypes) {
-		const newArchetype = new Archetype(componentTypes, this.dontFragmentStore);
+		const newArchetype = new Archetype(componentTypes, this.sparseStore);
 		this.archetypes.push(newArchetype);
+		if (this._debugCollectors.size > 0) this._debugArchetypesCreated++;
 		for (const componentType of componentTypes) {
 			let archetypes = this.archetypesByComponent.get(componentType);
 			if (!archetypes) {
@@ -3028,11 +3300,11 @@ var World = class {
 	archetypeMatchesHook(archetype, entry) {
 		return entry.requiredComponents.every((c) => {
 			if (isWildcardRelationId(c)) {
-				if (isDontFragmentWildcard(c)) return true;
+				if (isSparseWildcard(c)) return true;
 				const componentId = getComponentIdFromRelationId(c);
 				return componentId !== void 0 && archetype.hasRelationWithComponentId(componentId);
 			}
-			return archetype.componentTypeSet.has(c) || isDontFragmentRelation(c);
+			return archetype.componentTypeSet.has(c) || isSparseRelation(c);
 		}) && matchesFilter(archetype, entry.filter);
 	}
 	cleanupArchetypesReferencingEntity(entityId) {
@@ -3048,6 +3320,7 @@ var World = class {
 			this.archetypes[index] = last;
 			this.archetypes.pop();
 		}
+		if (this._debugCollectors.size > 0) this._debugArchetypesRemoved++;
 		this.archetypeBySignature.delete(this.createArchetypeSignature(archetype.componentTypes));
 		for (const componentType of archetype.componentTypes) {
 			const archetypes = this.archetypesByComponent.get(componentType);
@@ -3085,6 +3358,6 @@ var World = class {
 	}
 };
 //#endregion
-export { getComponentIdByName as a, isWildcardRelationId as c, isEntityId as d, isRelationId as f, component as i, relation as l, Query as n, getComponentNameById as o, EntityBuilder as r, decodeRelationId as s, World as t, isComponentId as u };
+export { getComponentIdByName as a, isSparseRelation as c, isWildcardRelationId as d, relation as f, isRelationId as h, component as i, isSparseWildcard as l, isEntityId as m, Query as n, getComponentNameById as o, isComponentId as p, EntityBuilder as r, isSparseComponent as s, World as t, decodeRelationId as u };
 
 //# sourceMappingURL=world.mjs.map