@codehz/ecs 0.8.2 → 0.9.0

package/README.en.md

@@ -78,7 +78,7 @@ const ChildOf = component({ exclusive: true, name: "ChildOf" });
 | `name`          | `string`            | Component name, used for serialization/debugging                                                                                                                                                                                           |
 | `exclusive`     | `boolean`           | Relation components only: an entity can have at most one relation of the same base component                                                                                                                                               |
 | `cascadeDelete` | `boolean`           | Entity relations only: when the target entity is deleted, the **entire referencing entity** is deleted. Differs from default behavior (default only cleans up the relation component, the entity survives). Supports transitive cascading. |
-| `dontFragment`  | `boolean`           | Relation components only: relations with different target entities are stored in the same Archetype, preventing excessive fragmentation                                                                                                    |
+| `sparse`        | `boolean`           | Relation components only: relations with different target entities are stored in the same Archetype, preventing excessive fragmentation (legacy `dontFragment` alias remains fully supported)                                              |
 | `merge`         | `(prev, next) => T` | Merge strategy when `set()` is called multiple times on the same component within a single sync batch                                                                                                                                      |
 
 ### Lifecycle Hooks
@@ -274,7 +274,7 @@ component<T>();
 // With a name
 component<T>("Name");
 // With options
-component<T>({ name?: string, exclusive?: boolean, cascadeDelete?: boolean, dontFragment?: boolean, merge?: (prev, next) => T });
+component<T>({ name?: string, exclusive?: boolean, cascadeDelete?: boolean, sparse?: boolean, dontFragment?: boolean /* legacy alias, fully compatible */, merge?: (prev, next) => T });
 ```
 
 ### relation()
@@ -288,6 +288,29 @@ relation(componentId, "*");
 relation(componentId, otherComponentId);
 ```
 
+### Relation & Hierarchy Companion Tools (New)
+
+To stop users from repeatedly hand-writing `buildChildrenByParent` + recursive descent for parent-child hierarchies and inventory systems, we now ship first-class helpers:
+
+```typescript
+const ChildOf = component<void>({ exclusive: true, sparse: true });
+const world = new World();
+// ... build hierarchy ...
+
+// Recommended usage (standalone functions removed to simplify API surface)
+const kids = world.getChildren(parent, ChildOf);
+const p = world.getParent(child, ChildOf);
+
+for (const { entity, depth } of world.iterateDescendants(root, ChildOf)) { ... }
+
+const items = world.getRelationTargets(player, InInventory);
+const owners = world.getRelationSources(sword, InInventory);
+```
+
+The same functionality is also available as methods on `World` instances. All helpers are fully compatible with data-bearing relations, exclusive/non-exclusive, and post-`sync()` semantics.
+
+See `src/relations/hierarchy.ts` and the new test suite for details.
+
 ### Component / Entity ID Rules
 
 - Component ID: `1` – `1023`
@@ -391,7 +414,7 @@ src/
 │   ├── component-registry.ts # Component registry
 │   ├── component-entity-store.ts # Singleton component storage
 │   ├── component-type-utils.ts   # Component type utilities
-│   ├── dont-fragment-store.ts    # DontFragment storage
+│   ├── store.ts                  # SparseStore (internal sparse storage)
 │   ├── entity.ts            # Entity/component/relation type exports (aggregate)
 │   ├── entity-types.ts      # Entity ID type definitions & constants
 │   ├── entity-relation.ts   # Relation ID encoding/decoding

package/README.md

@@ -78,7 +78,7 @@ const ChildOf = component({ exclusive: true, name: "ChildOf" });
 | `name`          | `string`            | 组件名称，用于序列化/调试                                                                                                      |
 | `exclusive`     | `boolean`           | 仅关系组件：同一实体对同一基础组件最多只能有一个关系                                                                           |
 | `cascadeDelete` | `boolean`           | 仅实体关系：删除目标实体时，持有该关系的**整个实体**也会被删除。区别于默认行为（默认仅清理关系组件，实体保留）。支持传递级联。 |
-| `dontFragment`  | `boolean`           | 仅关系组件：不同目标实体的关系存放在同一 Archetype，防止因目标不同而过度碎片化                                                 |
+| `sparse`        | `boolean`           | 仅关系组件：不同目标实体的关系存放在同一 Archetype，防止因目标不同而过度碎片化（旧别名 `dontFragment` 仍完全兼容）             |
 | `merge`         | `(prev, next) => T` | 在同一 sync 批次中对同一组件反复 `set()` 时的合并策略                                                                          |
 
 ### 生命周期钩子
@@ -274,7 +274,7 @@ component<T>();
 // 指定名称
 component<T>("Name");
 // 带选项
-component<T>({ name?: string, exclusive?: boolean, cascadeDelete?: boolean, dontFragment?: boolean, merge?: (prev, next) => T });
+component<T>({ name?: string, exclusive?: boolean, cascadeDelete?: boolean, sparse?: boolean, dontFragment?: boolean /* 旧别名，完全兼容 */, merge?: (prev, next) => T });
 ```
 
 ### relation()
@@ -288,6 +288,31 @@ relation(componentId, "*");
 relation(componentId, otherComponentId);
 ```
 
+### 关系/层级配套工具（新）
+
+为避免用户在父子层级（`ChildOf`）和库存系统（`InInventory`）中反复手写 `buildChildrenByParent` + 递归遍历逻辑，我们提供了配套工具：
+
+```typescript
+const ChildOf = component<void>({ exclusive: true, sparse: true });
+const world = new World();
+// ... 创建层级 ...
+
+// 推荐直接在 World 实例上使用（API 表面已简化）
+const kids = world.getChildren(parent, ChildOf);
+const p = world.getParent(child, ChildOf);
+
+for (const { entity, depth, parent } of world.iterateDescendants(root, ChildOf)) {
+  // ...
+}
+
+const items = world.getRelationTargets(player, InInventory);
+const owners = world.getRelationSources(sword, InInventory);
+```
+
+这些工具全部在 `world` 实例方法上也有对应（`world.getChildren(...)` 等），并完整支持数据负载关系、独占/非独占、删除后一致性。
+
+详见 `src/relations/hierarchy.ts` 和新增的测试。
+
 ### 组件 / 实体 ID 规则
 
 - 组件 ID：`1` ~ `1023`
@@ -391,7 +416,7 @@ src/
 │   ├── component-registry.ts # 组件注册表
 │   ├── component-entity-store.ts # 单例组件存储
 │   ├── component-type-utils.ts   # 组件类型工具
-│   ├── dont-fragment-store.ts    # DontFragment 存储
+│   ├── store.ts                  # SparseStore (内部稀疏存储)
 │   ├── entity.ts            # 实体/组件/关系类型导出（聚合）
 │   ├── entity-types.ts      # 实体 ID 类型定义与常量
 │   ├── entity-relation.ts   # 关系 ID 编码/解码

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;
   /**
@@ -892,12 +1023,16 @@ declare class World {
   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 readonly queryRegistry;
   private hooks;
+  private readonly _debugCollectors;
+  private _debugMigrations;
+  private _debugArchetypesCreated;
+  private _debugArchetypesRemoved;
   private commandBuffer;
   private readonly _changeset;
   private readonly _removeChangeset;
@@ -1112,6 +1247,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 +1388,21 @@ 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;
+  private _resetDebugActivityCounters;
+  private _deliverDebugStats;
   /**
    * 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.
@@ -1393,5 +1643,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 { WildcardRelationId as A, isWildcardRelationId as C, EntityId as D, ComponentRelationId as E, isEntityId as M, isRelationId as N, EntityRelationId as O, decodeRelationId as S, ComponentId as T, getComponentIdByName as _, ComponentTuple as a, isSparseRelation as b, LifecycleCallback as c, SerializedComponent as d, SerializedEntity as f, component as g, ComponentOptions as h, Query as i, isComponentId as j, RelationId as k, LifecycleHook as l, SerializedWorld as m, EntityBuilder as n, ComponentType as o, SerializedEntityId as p, World as r, DebugStatsCollector as s, ComponentDef as t, SyncDebugStats as u, getComponentNameById as v, relation as w, isSparseWildcard as x, isSparseComponent 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 WildcardRelationId, C as isWildcardRelationId, D as EntityId, E as ComponentRelationId, M as isEntityId, N as isRelationId, O as EntityRelationId, S as decodeRelationId, T as ComponentId, _ as getComponentIdByName, a as ComponentTuple, b as isSparseRelation, c as LifecycleCallback, d as SerializedComponent, f as SerializedEntity, g as component, h as ComponentOptions, i as Query, j as isComponentId, k as RelationId, l as LifecycleHook, m as SerializedWorld, n as EntityBuilder, o as ComponentType, p as SerializedEntityId, r as World, s as DebugStatsCollector, t as ComponentDef, u as SyncDebugStats, v as getComponentNameById, w as relation, x as isSparseWildcard, y as isSparseComponent } 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, 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 getComponentIdByName, c as isSparseRelation, d as isWildcardRelationId, f as relation, h as isRelationId, i as component, l as isSparseWildcard, m as isEntityId, n as Query, o as getComponentNameById, p as isComponentId, r as EntityBuilder, s as isSparseComponent, t as World, u as decodeRelationId } from "./world.mjs";
+export { EntityBuilder, Query, 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 { A as WildcardRelationId, D as EntityId, T as ComponentId, c as LifecycleCallback, g as component, i as Query, k as RelationId, l as LifecycleHook, n as EntityBuilder, r as World, t as ComponentDef, w as relation } from "./builder.mjs";
 
 //#region src/testing/index.d.ts
 /**

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { c as isWildcardRelationId, i as component, l as relation, r as EntityBuilder, t as World } from "./world.mjs";
+import { d as isWildcardRelationId, f as relation, i as component, r as EntityBuilder, t as World } from "./world.mjs";
 //#region src/testing/index.ts
 /**
 * A test fixture that manages a World instance and provides convenient