@codehz/ecs 0.8.2 → 0.10.0

package/dist/builder.d.mts

@@ -248,7 +248,7 @@ interface ComponentOptions<T = any> {
    *   `cascadeDelete`, deleting the target entity will both (a) delete the
    *   referencing entity, and (b) the exclusivity constraint prevents the
    *   entity from having multiple cascade-delete relations of the same type.
-   * - **`dontFragment`**: Compatible. Exclusivity is enforced at the data level
+   * - **`sparse`**: Compatible. Exclusivity is enforced at the data level
    *   regardless of whether the archetype is fragmented.
    *
    * @example
@@ -306,7 +306,8 @@ interface ComponentOptions<T = any> {
    */
   cascadeDelete?: boolean;
   /**
-   * If true, relations with this component will not cause archetype fragmentation.
+   * If true, relations with this component use sparse storage and will not cause
+   * archetype fragmentation.
    *
    * **Problem it solves**: By default, each unique relation pair `(component, target)`
    * creates a **separate archetype**. If 100 entities each have a `ChildOf` relation
@@ -314,28 +315,28 @@ interface ComponentOptions<T = any> {
    * Queries that iterate over all entities with a `ChildOf` relation must check all
    * 100 archetypes, which degrades iteration performance and increases memory overhead.
    *
-   * **How it works**: When `dontFragment` is enabled, the relation's target does **not**
-   * contribute to the archetype signature. Entities with different targets for the same
-   * relation component share a **single archetype**, and the per-entity target data is
-   * stored in a separate `DontFragmentStore` (a `Map<EntityId, Map<EntityId, any>>`).
-   * A wildcard relation marker (`relation(Comp, "*")`) is placed in the archetype
-   * component list so queries can still discover matching archetypes.
+   * **How it works (sparse storage)**: When `sparse` is enabled, the relation's target
+   * does **not** contribute to the archetype signature. Entities with different targets
+   * for the same relation component share a **single archetype**, and the per-entity
+   * target data is stored in a separate side store (historically called
+   * `DontFragmentStore`, now `SparseStore`). A wildcard relation marker (`relation(Comp, "*")`) is placed
+   * in the archetype component list so queries can still discover matching archetypes.
    *
    * **Use cases**:
    * - **Hierarchy/ownership**: `ChildOf` relations where thousands of entities each
    *   point to different parent entities.
    * - **Dynamic targeting**: Relations where targets change frequently (e.g., AI
-   *   targeting, inventory slots) — without `dontFragment`, each target change would
-   *   cause an archetype migration, which is expensive.
+   *   targeting, inventory slots) — without `sparse`, each target change would cause
+   *   an archetype migration, which is expensive.
    * - **High-cardinality relations**: Any relation where the number of unique targets
    *   is large compared to the number of entities.
    *
    * **Performance implications**:
-   * - **Without `dontFragment`**: Archetype count grows linearly with unique targets.
+   * - **Without `sparse`**: Archetype count grows linearly with unique targets.
    *   Each archetype migration (changing a relation target) requires moving the entity's
    *   data between component arrays.
-   * - **With `dontFragment`**: Archetype count stays constant regardless of target
-   *   diversity. Changing a relation target is an O(1) update in the `DontFragmentStore`.
+   * - **With `sparse`**: Archetype count stays constant regardless of target diversity.
+   *   Changing a relation target is an O(1) update in the sparse side store.
    *   The trade-off is an extra map lookup when accessing the relation data.
    *
    * **Constraints**:
@@ -344,13 +345,16 @@ interface ComponentOptions<T = any> {
    *   archetype carries a wildcard marker so queries can discover it.
    * - Works with `exclusive` and `cascadeDelete` simultaneously.
    *
+   * **Backward compatibility**: The legacy key `dontFragment` is still accepted and
+   * behaves identically. Prefer `sparse` in new code.
+   *
    * @example
    * ```ts
-   * // Without dontFragment: 100 entities with different parents = 100 archetypes
+   * // Without sparse: 100 entities with different parents = 100 archetypes
    * const ChildOf = component(); // default: fragmentation happens
    *
-   * // With dontFragment: 100 entities with different parents = 1 archetype
-   * const ChildOf = component({ dontFragment: true });
+   * // With sparse: 100 entities with different parents = 1 archetype
+   * const ChildOf = component({ sparse: true });
    *
    * for (let i = 0; i < 100; i++) {
    *   const parent = world.new();
@@ -359,11 +363,17 @@ interface ComponentOptions<T = any> {
    *   world.set(child, relation(ChildOf, parent));
    * }
    * world.sync();
-   * // dontFragment: 1 archetype for all 100 entities
+   * // sparse: 1 archetype for all 100 entities
    * // without: 100 archetypes, one per unique parent
    * ```
    *
-   * Inspired by Flecs' `DontFragment` trait.
+   * Inspired by Flecs' `DontFragment` trait (now exposed as the clearer `sparse` option).
+   */
+  sparse?: boolean;
+  /**
+   * @deprecated Use `sparse: true` instead. This key is kept solely for backward
+   * compatibility; `component({ dontFragment: true })` continues to work exactly
+   * as before and is equivalent to `sparse: true`.
    */
   dontFragment?: boolean;
   /**
@@ -453,6 +463,53 @@ declare function getComponentIdByName(name: string): ComponentId<any> | undefine
  * @returns The component name if found, undefined otherwise
  */
 declare function getComponentNameById(id: ComponentId<any>): string | undefined;
+/**
+ * Check if a component is marked as `sparse` (sparse storage for relations).
+ *
+ * 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 `sparse: true` (or the
+ *   legacy `dontFragment: true`).
+ *
+ * @see {@link ComponentOptions.sparse} for the full explanation of sparse storage.
+ */
+declare function isSparseComponent(id: ComponentId<any>): boolean;
+/**
+ * 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.
+ *
+ * @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 `sparse: true` (or legacy `dontFragment: true`).
+ *
+ * @see {@link isSparseWildcard} for the wildcard variant.
+ * @see {@link ComponentOptions.sparse} for the full explanation.
+ */
+declare function isSparseRelation(id: EntityId<any>): boolean;
+/**
+ * Check if an ID is a wildcard relation (`relation(Comp, "*")`) backed by a
+ * `sparse` component.
+ *
+ * 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 `sparse: true` (or legacy `dontFragment: true`).
+ *
+ * @see {@link isSparseRelation} for the specific-target variant.
+ * @see {@link ComponentOptions.sparse} for the full explanation.
+ */
+declare function isSparseWildcard(id: EntityId<any>): boolean;
 //#endregion
 //#region src/storage/serialization.d.ts
 type SerializedEntityId = number | string | {
@@ -558,24 +615,78 @@ interface LifecycleHookEntry {
   /** Archetypes that match this hook, used for precise cleanup on unsubscription */
   matchedArchetypes?: Set<any>;
 }
+/**
+ * Statistics payload delivered to callbacks registered via `World.createDebugStatsCollector`.
+ *
+ * All structural counts are snapshots taken after the sync that triggered delivery.
+ * `activity` always reflects work performed during that specific sync.
+ *
+ * Timestamps are raw `performance.now()` values suitable for `performance.measure`.
+ */
+interface SyncDebugStats {
+  readonly timestamps: {
+    readonly syncStart: number;
+    readonly syncEnd: number;
+    readonly commandBufferStart: number;
+    readonly commandBufferEnd: number;
+  };
+  /** Number of iterations the internal command buffer loop performed during this sync. */
+  readonly commandIterations: number;
+  readonly entities: {
+    readonly total: number;
+    readonly freelistSize: number;
+    readonly nextId: number;
+  };
+  readonly archetypes: {
+    readonly total: number;
+    readonly empty: number;
+  };
+  readonly queries: {
+    readonly cached: number;
+    readonly registered: number;
+  };
+  readonly hooks: {
+    readonly total: number;
+  };
+  /** Sizes of stable internal reverse indices (conservative set). */
+  readonly indices: {
+    readonly entityReferences: number;
+    readonly entityToReferencingArchetypes: number;
+    readonly archetypesByComponent: number;
+  };
+  /**
+   * Activity that occurred as a direct result of this sync.
+   * All fields are always present (never optional).
+   */
+  readonly activity: {
+    /** Number of entities that performed an archetype migration (hasArchetypeStructuralChange was true). */readonly migrations: number; /** Total number of individual hook callback invocations (invokeHook calls). */
+    readonly hooksExecuted: number; /** Number of new archetypes created during this sync. */
+    readonly archetypesCreated: number; /** Number of archetypes removed during this sync. */
+    readonly archetypesRemoved: number;
+  };
+}
+/**
+ * Handle returned by `World.createDebugStatsCollector`.
+ * The object itself carries no data — its only responsibility is lifetime management.
+ * Use with `using` or call `[Symbol.dispose]()` when you no longer need collection.
+ */
+interface DebugStatsCollector {
+  [Symbol.dispose](): void;
+}
 //#endregion
 //#region src/archetype/store.d.ts
 /**
- * Interface for storing dontFragment relation data.
- *
- * Storage is now primarily keyed by relation ComponentId (the "kind" of relation)
- * rather than by entity. This provides O(1) or near-O(1) answers for the hot
- * wildcard-related paths (hasRelationWithComponentId, wildcard materialization
- * during iteration, hook matching, etc.).
+ * Interface for the sparse side store used by components declared with `sparse: true`
+ * (or the legacy `dontFragment: true` alias).
  *
- * A lightweight reverse index (entity -> Set of base ComponentIds) is maintained
- * to efficiently support the infrequent "get all dontFragment data for this entity"
- * operations (removeEntity, dump, getEntity, serialization).
+ * Relation data for these components lives here instead of in archetype columns,
+ * preventing fragmentation for high-cardinality or frequently-changing relations.
  *
- * The interface no longer leaks internal Map structures. Callers work with
- * semantic operations only.
+ * Storage is primarily keyed by base relation ComponentId. This enables efficient
+ * per-component lookups required by wildcard queries (relation(Comp, "*")) and
+ * archetype filtering, while still supporting full-entity enumeration when needed.
  */
-interface DontFragmentStore {
+interface SparseStore {
   getValue(entityId: EntityId, relationType: EntityId<any>): any | undefined;
   setValue(entityId: EntityId, relationType: EntityId<any>, data: any): void;
   deleteValue(entityId: EntityId, relationType: EntityId<any>): boolean;
@@ -583,6 +694,12 @@ interface DontFragmentStore {
   getRelationsForComponent(entityId: EntityId, componentId: EntityId<any>): [target: EntityId, data: any][];
   getAllForEntity(entityId: EntityId): Array<[relationType: EntityId<any>, data: any]>;
   deleteEntity(entityId: EntityId): void;
+  /**
+   * @internal Bulk helper for serialization of many entities.
+   * Default implementation simply loops getAllForEntity; subclasses / future
+   * implementations can provide a more efficient fused walk.
+   */
+  getAllForEntities(entityIds: readonly EntityId[]): Map<EntityId, Array<[EntityId<any>, any]>>;
 }
 //#endregion
 //#region src/archetype/archetype.d.ts
@@ -614,11 +731,10 @@ declare class Archetype {
    */
   private entityToIndex;
   /**
-   * 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.
    */
-  private dontFragmentRelations;
+  private sparseRelations;
   /**
    * Multi-hooks that match this archetype
    */
@@ -627,7 +743,7 @@ declare class Archetype {
    * Cache for pre-computed component data sources to avoid repeated calculations
    */
   private componentDataSourcesCache;
-  constructor(componentTypes: EntityId<any>[], dontFragmentRelations: DontFragmentStore);
+  constructor(componentTypes: EntityId<any>[], sparseStore: SparseStore);
   get size(): number;
   /**
    * Check if the given component types match this archetype
@@ -637,19 +753,34 @@ declare class Archetype {
    */
   matches(componentTypes: EntityId<any>[]): boolean;
   addEntity(entityId: EntityId, componentData: Map<EntityId<any>, any>): void;
-  private addDontFragmentRelations;
+  private addSparseRelations;
   getEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
   /**
-   * 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: EntityId): Map<EntityId<any>, any> | undefined;
+  getEntitySparseRelations(entityId: EntityId): Map<EntityId<any>, any> | undefined;
   dump(): Array<{
     entity: EntityId;
     components: Map<EntityId<any>, any>;
   }>;
+  /**
+   * @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: SerializedEntity[], encode: (id: EntityId<any>) => SerializedEntityId, encodedComponentTypes: SerializedEntityId[], sparseByEntity?: Map<EntityId, Array<[EntityId<any>, any]>>): void;
   removeEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
   exists(entityId: EntityId): boolean;
   get<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][];
@@ -764,8 +895,8 @@ declare class Query {
   _cacheKey: string | undefined;
   /** Cached wildcard component types for faster entity filtering */
   private wildcardTypes;
-  /** Cached specific dontFragment relation types that need entity-level filtering */
-  private specificDontFragmentTypes;
+  /** Cached specific sparse relation types that need entity-level filtering */
+  private specificSparseRelationTypes;
   /**
    * @internal Queries should be created via {@link World.createQuery}, not instantiated directly.
    */
@@ -787,7 +918,7 @@ declare class Query {
    */
   getEntities(): EntityId[];
   /**
-   * Check if entity matches all query requirements (wildcards and specific dontFragment relations)
+   * Check if entity matches all query requirements (wildcards and specific sparse relations)
    */
   private entityMatchesQuery;
   /**
@@ -878,6 +1009,41 @@ declare class Query {
   get disposed(): boolean;
 }
 //#endregion
+//#region src/world/singleton.d.ts
+interface SingletonHandleOps<T> {
+  has(): boolean;
+  get(): T;
+  getOptional(): {
+    value: T;
+  } | undefined;
+  remove(): void;
+  set(value: T | undefined): void;
+}
+/**
+ * Explicit handle for a singleton component (component-as-entity).
+ *
+ * This provides an explicit and concise API for singleton components without
+ * overloading `world.set()` semantics.
+ *
+ * @example
+ * const config = world.singleton(Config);
+ * config.set({ debug: true });
+ * world.sync();
+ * console.log(config.get());
+ */
+declare class SingletonHandle<T = void> {
+  readonly componentId: ComponentId<T>;
+  private readonly ops;
+  constructor(componentId: ComponentId<T>, ops: SingletonHandleOps<T>);
+  has(): boolean;
+  get(): T;
+  getOptional(): {
+    value: T;
+  } | undefined;
+  remove(): void;
+  set(...args: T extends void ? [] : [value: NoInfer<T>]): void;
+}
+//#endregion
 //#region src/world/world.d.ts
 /**
  * World class for ECS architecture
@@ -885,28 +1051,22 @@ declare class Query {
  */
 declare class World {
   private entityIdManager;
-  private archetypes;
-  private archetypeBySignature;
-  private entityToArchetype;
-  private archetypesByComponent;
   private entityReferences;
-  /** Reverse index: entity ID → set of archetypes whose componentTypes include that entity ID */
-  private entityToReferencingArchetypes;
-  /** DontFragment relation storage, shared with all Archetype instances */
-  private readonly dontFragmentStore;
+  /** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
+  private readonly sparseStore;
   /** Component entity (singleton) storage */
   private readonly componentEntities;
+  private archetypeManager;
+  private get archetypes();
+  private get entityToArchetype();
+  private get archetypesByComponent();
+  private get entityToReferencingArchetypes();
   private readonly queryRegistry;
   private hooks;
+  private readonly debugStats;
   private commandBuffer;
-  private readonly _changeset;
-  private readonly _removeChangeset;
-  /** Cached command processor context to avoid per-entity object allocation */
-  private readonly _commandCtx;
-  /** Cached hooks context to avoid per-entity object allocation */
-  private readonly _hooksCtx;
+  private commandExecutor;
   constructor(snapshot?: SerializedWorld);
-  private createArchetypeSignature;
   /**
    * Creates a new entity.
    * The entity is created with an empty component set and can be configured using `set()`.
@@ -951,11 +1111,6 @@ declare class World {
    * if (world.has(entity, Position)) { ... }
    */
   exists(entityId: EntityId): boolean;
-  private assertEntityExists;
-  private assertComponentTypeValid;
-  private assertSetComponentTypeValid;
-  private resolveSetOperation;
-  private resolveRemoveOperation;
   /**
    * Adds or updates a component on an entity (or marks void component as present).
    * The change is buffered and takes effect after calling `world.sync()`.
@@ -967,21 +1122,17 @@ declare class World {
    * @overload set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void
    * Adds or updates a component with data on the entity
    *
-   * @overload set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void
-   * Adds or updates a singleton component (shorthand for set(componentId, componentId, component))
-   *
    * @throws {Error} If the entity does not exist
    * @throws {Error} If the component type is invalid or is a wildcard relation
    *
    * @example
    * world.set(entity, Position, { x: 10, y: 20 });
    * world.set(entity, Marker); // void component
-   * world.set(GlobalConfig, { debug: true }); // singleton component
+   * world.singleton(GlobalConfig).set({ debug: true }); // singleton component
    * world.sync(); // Apply changes
    */
   set(entityId: EntityId, componentType: EntityId<void>): void;
   set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
-  set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void;
   /**
    * Removes a component from an entity.
    * The change is buffered and takes effect after calling `world.sync()`.
@@ -1019,6 +1170,18 @@ declare class World {
    * world.sync(); // Apply changes
    */
   delete(entityId: EntityId): void;
+  /**
+   * Returns an explicit handle for a singleton component (component-as-entity).
+   *
+   * This is the preferred API for singleton components.
+   *
+   * @example
+   * const config = world.singleton(GlobalConfig);
+   * config.set({ debug: true });
+   * world.sync();
+   * console.log(config.get());
+   */
+  singleton<T>(componentId: ComponentId<T>): SingletonHandle<T>;
   /**
    * Checks if a specific **component** is present on an entity.
    *
@@ -1112,6 +1275,106 @@ declare class World {
   getOptional<T>(entityId: EntityId, componentType: EntityId<T>): {
     value: T;
   } | undefined;
+  /**
+   * 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<T = void>(entityId: EntityId, relationComp: ComponentId<T>): [target: EntityId<unknown>, data: T | undefined][];
+  /**
+   * 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: EntityId, relationComp: ComponentId<any>): EntityId[];
+  /**
+   * Returns true if the entity has any (or a specific-target) relation of the
+   * given base component.
+   */
+  hasRelation(entityId: EntityId, relationComp: ComponentId<any>, targetId?: EntityId): boolean;
+  /**
+   * Returns the number of relations of the given base component held by the entity.
+   */
+  countRelations(entityId: EntityId, relationComp: ComponentId<any>): number;
+  /**
+   * 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<T = void>(entityId: EntityId, relationComp: ComponentId<T>): EntityId | undefined;
+  /**
+   * 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: EntityId, childOf: ComponentId<any>): EntityId[];
+  /**
+   * 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: EntityId, childOf: ComponentId<any>): EntityId | undefined;
+  /**
+   * 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: EntityId, childOf: ComponentId<any>): EntityId[];
+  /**
+   * 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: EntityId, childOf: ComponentId<any>, opts?: {
+    includeSelf?: boolean;
+    maxDepth?: number;
+  }): IterableIterator<{
+    entity: EntityId;
+    depth: number;
+    parent: EntityId | null;
+  }>;
+  /**
+   * Callback-based descendant traversal (hot path friendly).
+   * Return `false` from the visitor to stop early.
+   */
+  traverseDescendants(root: EntityId, childOf: ComponentId<any>, visitor: (entity: EntityId, depth: number, parent: EntityId | null) => void | boolean, opts?: {
+    includeSelf?: boolean;
+    maxDepth?: number;
+  }): void;
   /**
    * Registers a lifecycle hook that responds to component changes.
    * The hook callback is invoked when components matching the specified types are added, updated, or removed.
@@ -1153,6 +1416,19 @@ declare class World {
    * );
    */
   hook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T> | LifecycleCallback<T>, filter?: QueryFilter): () => void;
+  /**
+   * 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: (stats: SyncDebugStats) => void): DebugStatsCollector;
   /**
    * 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.
@@ -1248,7 +1524,6 @@ declare class World {
    * @internal
    */
   getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[];
-  private getArchetypesWithComponents;
   /**
    * Queries entities with specific components.
    * For simpler use cases, prefer using `createQuery()` with `forEach()` which is cached and more efficient.
@@ -1281,21 +1556,9 @@ declare class World {
     entity: EntityId;
     components: ComponentTuple<T>;
   }>;
-  private executeEntityCommands;
-  private applyEntityCommands;
-  private createHooksContext;
-  private removeComponentImmediate;
-  private updateEntityReferences;
   private ensureArchetype;
-  /** Add componentType to the reverse index if it contains an entity ID */
-  private addToReferencingIndex;
-  /** Remove componentType from the reverse index */
-  private removeFromReferencingIndex;
-  private createNewArchetype;
-  private updateArchetypeHookMatches;
-  private archetypeMatchesHook;
   private cleanupArchetypesReferencingEntity;
-  private removeArchetype;
+  private archetypeMatchesHook;
   /**
    * Serializes the entire world state to a plain JavaScript object.
    * This creates a "memory snapshot" that can be stored or transmitted.
@@ -1317,6 +1580,8 @@ declare class World {
    * const savedData = JSON.parse(localStorage.getItem('save'));
    * const newWorld = new World(savedData);
    */
+  private removeComponentImmediate;
+  private createHooksContext;
   serialize(): SerializedWorld;
 }
 //#endregion
@@ -1393,5 +1658,5 @@ declare class EntityBuilder {
   build(): EntityId;
 }
 //#endregion
-export { EntityRelationId as C, isEntityId as D, isComponentId as E, isRelationId as O, EntityId as S, WildcardRelationId as T, decodeRelationId as _, ComponentTuple as a, ComponentId as b, LifecycleHook as c, SerializedEntityId as d, SerializedWorld as f, getComponentNameById as g, getComponentIdByName as h, Query as i, SerializedComponent as l, component as m, EntityBuilder as n, ComponentType as o, ComponentOptions as p, World as r, LifecycleCallback as s, ComponentDef as t, SerializedEntity as u, isWildcardRelationId as v, RelationId as w, ComponentRelationId as x, relation as y };
+export { EntityRelationId as A, isSparseWildcard as C, ComponentId as D, relation as E, isRelationId as F, WildcardRelationId as M, isComponentId as N, ComponentRelationId as O, isEntityId as P, isSparseRelation as S, isWildcardRelationId as T, ComponentOptions as _, SingletonHandleOps as a, getComponentNameById as b, ComponentType as c, LifecycleHook as d, SyncDebugStats as f, SerializedWorld as g, SerializedEntityId as h, SingletonHandle as i, RelationId as j, EntityId as k, DebugStatsCollector as l, SerializedEntity as m, EntityBuilder as n, Query as o, SerializedComponent as p, World as r, ComponentTuple as s, ComponentDef as t, LifecycleCallback as u, component as v, decodeRelationId as w, isSparseComponent as x, getComponentIdByName as y };
 //# sourceMappingURL=builder.d.mts.map

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { C as EntityRelationId, D as isEntityId, E as isComponentId, O as isRelationId, S as EntityId, T as WildcardRelationId, _ as decodeRelationId, a as ComponentTuple, b as ComponentId, c as LifecycleHook, d as SerializedEntityId, f as SerializedWorld, g as getComponentNameById, h as getComponentIdByName, i as Query, l as SerializedComponent, m as component, n as EntityBuilder, o as ComponentType, p as ComponentOptions, r as World, s as LifecycleCallback, t as ComponentDef, u as SerializedEntity, v as isWildcardRelationId, w as RelationId, x as ComponentRelationId, y as relation } from "./builder.mjs";
-export { type ComponentDef, type ComponentId, type ComponentOptions, type ComponentRelationId, type ComponentTuple, type ComponentType, EntityBuilder, type EntityId, type EntityRelationId, type LifecycleCallback, type LifecycleHook, Query, type RelationId, type SerializedComponent, type SerializedEntity, type SerializedEntityId, type SerializedWorld, type WildcardRelationId, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isEntityId, isRelationId, isWildcardRelationId, relation };
+import { A as EntityRelationId, C as isSparseWildcard, D as ComponentId, E as relation, F as isRelationId, M as WildcardRelationId, N as isComponentId, O as ComponentRelationId, P as isEntityId, S as isSparseRelation, T as isWildcardRelationId, _ as ComponentOptions, a as SingletonHandleOps, b as getComponentNameById, c as ComponentType, d as LifecycleHook, f as SyncDebugStats, g as SerializedWorld, h as SerializedEntityId, i as SingletonHandle, j as RelationId, k as EntityId, l as DebugStatsCollector, m as SerializedEntity, n as EntityBuilder, o as Query, p as SerializedComponent, r as World, s as ComponentTuple, t as ComponentDef, u as LifecycleCallback, v as component, w as decodeRelationId, x as isSparseComponent, y as getComponentIdByName } from "./builder.mjs";
+export { type ComponentDef, type ComponentId, type ComponentOptions, type ComponentRelationId, type ComponentTuple, type ComponentType, type DebugStatsCollector, EntityBuilder, type EntityId, type EntityRelationId, type LifecycleCallback, type LifecycleHook, Query, type RelationId, type SerializedComponent, type SerializedEntity, type SerializedEntityId, type SerializedWorld, SingletonHandle, type SingletonHandleOps, type SyncDebugStats, type WildcardRelationId, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isSparseComponent as isDontFragmentComponent, isSparseComponent, isSparseRelation as isDontFragmentRelation, isSparseRelation, isSparseWildcard as isDontFragmentWildcard, isSparseWildcard, isEntityId, isRelationId, isWildcardRelationId, relation };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as getComponentIdByName, c as isWildcardRelationId, d as isEntityId, f as isRelationId, i as component, l as relation, n as Query, o as getComponentNameById, r as EntityBuilder, s as decodeRelationId, t as World, u as isComponentId } from "./world.mjs";
-export { EntityBuilder, Query, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isEntityId, isRelationId, isWildcardRelationId, relation };
+import { a as component, c as isSparseComponent, d as decodeRelationId, f as isWildcardRelationId, g as isRelationId, h as isEntityId, i as EntityBuilder, l as isSparseRelation, m as isComponentId, n as Query, o as getComponentIdByName, p as relation, r as SingletonHandle, s as getComponentNameById, t as World, u as isSparseWildcard } from "./world.mjs";
+export { EntityBuilder, Query, SingletonHandle, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isSparseComponent as isDontFragmentComponent, isSparseComponent, isSparseRelation as isDontFragmentRelation, isSparseRelation, isSparseWildcard as isDontFragmentWildcard, isSparseWildcard, isEntityId, isRelationId, isWildcardRelationId, relation };

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { S as EntityId, T as WildcardRelationId, b as ComponentId, c as LifecycleHook, i as Query, m as component, n as EntityBuilder, r as World, s as LifecycleCallback, t as ComponentDef, w as RelationId, y as relation } from "./builder.mjs";
+import { D as ComponentId, E as relation, M as WildcardRelationId, d as LifecycleHook, j as RelationId, k as EntityId, n as EntityBuilder, o as Query, r as World, t as ComponentDef, u as LifecycleCallback, v as component } from "./builder.mjs";
 
 //#region src/testing/index.d.ts
 /**