@codehz/ecs 0.8.1 → 0.9.0

package/examples/debug-observability.ts

@@ -0,0 +1,92 @@
+/**
+ * Example: Using the Debug Stats Collector for development & leak detection.
+ *
+ * Run with:
+ *   bun run examples/debug-observability.ts
+ */
+
+import { component, relation, World } from "../src";
+
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+
+// Components
+const Position = component<Position>();
+const Velocity = component<Velocity>();
+const ChildOf = component<void>({ exclusive: true, sparse: true });
+
+const world = new World();
+
+// Create a debug stats collector
+const collector = world.createDebugStatsCollector((stats) => {
+  console.log("=== Debug Stats ===");
+  console.log(`Sync time: ${(stats.timestamps.syncEnd - stats.timestamps.syncStart).toFixed(3)}ms`);
+  console.log(`Command buffer iterations: ${stats.commandIterations}`);
+  console.log(`Entities: ${stats.entities.total} (freelist: ${stats.entities.freelistSize})`);
+  console.log(`Archetypes: ${stats.archetypes.total} (empty: ${stats.archetypes.empty})`);
+  console.log(`Queries (cached/registered): ${stats.queries.cached}/${stats.queries.registered}`);
+  console.log(`Hooks: ${stats.hooks.total}`);
+  console.log(`Indices:`, stats.indices);
+
+  const act = stats.activity;
+  console.log("Activity this sync:");
+  console.log(`  Migrations: ${act.migrations}`);
+  console.log(`  Hooks executed: ${act.hooksExecuted}`);
+  console.log(`  Archetypes created: ${act.archetypesCreated}`);
+  console.log(`  Archetypes removed: ${act.archetypesRemoved}`);
+  console.log("===================\n");
+});
+
+// Setup some entities
+const parent = world.new();
+world.set(parent, Position, { x: 0, y: 0 });
+
+const children: any[] = [];
+for (let i = 0; i < 5; i++) {
+  const child = world.new();
+  world.set(child, Position, { x: i * 10, y: 0 });
+  world.set(child, Velocity, { x: 1, y: 0.5 });
+  world.set(child, relation(ChildOf, parent));
+  children.push(child);
+}
+
+console.log("Initial sync (should create archetypes + relations)");
+world.sync();
+
+// Cause some migrations by adding/removing components
+console.log("Adding/removing components to trigger migrations...");
+for (const c of children) {
+  world.remove(c, Velocity);
+}
+world.sync();
+
+world.set(children[0], Velocity, { x: 2, y: 0 });
+world.sync();
+
+// Add a hook to observe hook execution counting
+world.hook([Position, Velocity], {
+  on_set: () => {},
+});
+
+console.log("Triggering hook + more structural changes");
+world.set(children[1], Velocity, { x: 3, y: 1 });
+world.sync();
+
+// Clean up some entities to potentially remove archetypes
+console.log("Deleting some children...");
+world.delete(children[2]);
+world.delete(children[3]);
+world.sync();
+
+// Dispose the collector when done
+collector[Symbol.dispose]();
+
+console.log("Collector disposed. Further syncs will not trigger callbacks.");
+world.set(parent, Position, { x: 100, y: 100 });
+world.sync();
+
+console.log("Done. This demonstrates typical usage for spotting:");
+console.log("- Unexpected archetype growth (fragmentation)");
+console.log("- High migration or hook execution counts");
+console.log("- Command buffer iteration spikes");
+console.log("- Leaking entities or relations (watch entity/freelist numbers over time)");

package/examples/inventory-system-relations.ts

@@ -9,7 +9,7 @@ const ItemName = component<ItemName>({ name: "ItemName" });
 const Stackable = component<Stackable>({ name: "Stackable" });
 const Gold = component<Gold>({ name: "Gold" });
 const EquipmentSlot = component<EquipmentSlot>({ name: "EquipmentSlot" });
-const InInventory = component<void>({ name: "InInventory", dontFragment: true });
+const InInventory = component<void>({ name: "InInventory", sparse: true });
 
 const world = new World();
 

package/examples/parent-child-hierarchy.ts

@@ -1,5 +1,5 @@
 import { pipeline } from "@codehz/pipeline";
-import { World, component, relation, type EntityId, type Query } from "../src";
+import { World, component, relation, type Query } from "../src";
 
 // Define component types
 type Transform = { x: number; y: number; rotation: number; scale: number };
@@ -13,7 +13,7 @@ const LocalTransform = component<Transform>({ name: "LocalTransform" });
 const WorldTransform = component<Transform>({ name: "WorldTransform" });
 const LinearVelocity = component<LinearVelocity>({ name: "LinearVelocity" });
 const AngularVelocity = component<AngularVelocity>({ name: "AngularVelocity" });
-const ChildOf = component<void>({ exclusive: true, dontFragment: true, name: "ChildOf" });
+const ChildOf = component<void>({ exclusive: true, sparse: true, name: "ChildOf" });
 
 // Create the world
 const world = new World();
@@ -22,7 +22,6 @@ const world = new World();
 const movementQuery: Query = world.createQuery([LocalTransform, LinearVelocity]);
 const rotationQuery: Query = world.createQuery([LocalTransform, AngularVelocity]);
 const transformQuery: Query = world.createQuery([Name, LocalTransform, WorldTransform]);
-const childQuery: Query = world.createQuery([relation(ChildOf, "*")]);
 const renderQuery: Query = world.createQuery([Name, WorldTransform]);
 
 function toRadians(degrees: number): number {
@@ -59,38 +58,9 @@ function formatTransform(transform: Transform): string {
   return `pos=(${transform.x.toFixed(2)}, ${transform.y.toFixed(2)}) rot=${transform.rotation.toFixed(1)}deg scale=${transform.scale.toFixed(2)}`;
 }
 
-function buildChildrenByParent(): Map<EntityId, EntityId[]> {
-  const childrenByParent = new Map<EntityId, EntityId[]>();
-
-  childQuery.forEach([relation(ChildOf, "*")], (child, parents) => {
-    const parent = parents[0]?.[0];
-    if (parent === undefined) return;
-
-    const children = childrenByParent.get(parent) ?? [];
-    children.push(child);
-    childrenByParent.set(parent, children);
-  });
-
-  return childrenByParent;
-}
-
-function propagateChildren(
-  parent: EntityId,
-  parentWorld: Transform,
-  childrenByParent: Map<EntityId, EntityId[]>,
-): void {
-  const children = childrenByParent.get(parent);
-  if (!children) return;
-
-  for (const child of children) {
-    const name = world.get(child, Name);
-    const local = world.get(child, LocalTransform);
-    const worldTransform = world.get(child, WorldTransform);
-    copyTransform(worldTransform, composeTransform(local, parentWorld));
-    console.log(`  Child ${name.value}: ${formatTransform(worldTransform)}`);
-    propagateChildren(child, worldTransform, childrenByParent);
-  }
-}
+// NOTE: Before the relation/hierarchy companion tools, this required manually
+// building a children map every frame + writing recursive propagation.
+// Now we can use the built-in efficient helpers (getChildren + traverseDescendants).
 
 // Build game loop using pipeline
 // Pass execution order is determined by addition order; no need to manually manage dependencies
@@ -115,16 +85,26 @@ const gameLoop = pipeline<{ deltaTime: number }>()
     });
   })
   // Hierarchy pass - propagate parent transforms into world transforms
+  // (modernized with the new relation/hierarchy companion tools)
   .addPass(() => {
     console.log(`[HierarchyPass] Propagating world transforms`);
-    const childrenByParent = buildChildrenByParent();
 
     transformQuery.forEach([Name, LocalTransform, WorldTransform], (entity, name, localTransform, worldTransform) => {
-      if (world.has(entity, relation(ChildOf, "*"))) return;
+      if (world.has(entity, relation(ChildOf, "*"))) return; // skip non-roots
 
       copyTransform(worldTransform, composeTransform(localTransform));
       console.log(`  Root ${name.value}: ${formatTransform(worldTransform)}`);
-      propagateChildren(entity, worldTransform, childrenByParent);
+
+      // Use the efficient built-in traverser (replaces manual Map + recursion)
+      world.traverseDescendants(entity, ChildOf, (child, _depth, parent) => {
+        if (!parent) return;
+        const childName = world.get(child, Name);
+        const local = world.get(child, LocalTransform);
+        const childWorld = world.get(child, WorldTransform);
+        const parentWorldT = world.get(parent, WorldTransform);
+        copyTransform(childWorld, composeTransform(local, parentWorldT));
+        console.log(`  Child ${childName.value}: ${formatTransform(childWorld)}`);
+      });
     });
   })
   // Render pass - render propagated world transforms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "license": "MIT",
   "module": "src/index.ts",
   "type": "module",

package/skills/ecs/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: ecs
+description: "Guide for using @codehz/ecs — a high-performance ECS (Entity Component System) library in TypeScript. Use when: writing application code with @codehz/ecs; understanding deferred command buffering, archetype storage, queries, relations, lifecycle hooks, and sync() semantics; avoiding common ECS pitfalls like stale reads, dangling EntityId references, or sync() inside iteration."
+---
+
 # @codehz/ecs — User Guide for AI Coding Assistants
 
 **Purpose**: This document defines the strict usage contract for `@codehz/ecs`. Follow these rules when writing application code. Violating them is the most common source of subtle, hard-to-debug errors.
@@ -29,7 +34,7 @@ The library uses **archetype storage + deferred command buffering**. All structu
 7. **NEVER** call `sync()` inside `forEach`, hooks, or while iterating query results.
 8. **NEVER** confuse `remove(entity, Component)` with `delete(entity)`.
 9. **MUST** use relation components (`relation(Comp, target)`) instead of storing `EntityId` in data when you need to reference other entities.
-10. **MUST** understand the three relation flags (`exclusive`, `cascadeDelete`, `dontFragment`) before using relations.
+10. **MUST** understand the three relation flags (`exclusive`, `cascadeDelete`, `sparse` / legacy `dontFragment`) before using relations.
 
 ---
 
@@ -200,7 +205,7 @@ Use `relation(Component, target)` to create entity-to-entity references.
 - When the target entity is deleted, **the entire referencing entity is deleted**.
 - This is transitive and powerful. Use deliberately.
 
-**`dontFragment: true`**
+**`sparse: true`** (preferred; legacy key `dontFragment` is fully equivalent and supported)
 
 - Prevents archetype fragmentation when many different targets exist.
 - **Required** for relations with high cardinality or frequent target changes (e.g. `ChildOf` with thousands of children, AI targeting, inventory).
@@ -209,8 +214,8 @@ Use `relation(Component, target)` to create entity-to-entity references.
 
 ```ts
 const ChildOf = component({ exclusive: true, cascadeDelete: true });
-const Targeting = component({ exclusive: true, dontFragment: true });
-const InventorySlot = component({ dontFragment: true });
+const Targeting = component({ exclusive: true, sparse: true });
+const InventorySlot = component({ sparse: true });
 ```
 
 ### 8. Referencing Other Entities — Never Store Raw EntityId

package/src/__tests__/component/singleton.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
-import { component } from "../../entity";
+import { ComponentEntityStore } from "../../component/entity-store";
+import { component, createEntityId, relation, type EntityId } from "../../entity";
 import { World } from "../../world/world";
 
 describe("World - Singleton Component", () => {
@@ -145,4 +146,42 @@ describe("World - Singleton Component", () => {
     expect(world1.has(GlobalConfigId)).toBe(world2.has(GlobalConfigId, GlobalConfigId));
     expect(world1.has(GlobalConfigId)).toBe(false);
   });
+
+  it("should cover ComponentEntityStore hasWildcard, getWildcard, wildcard delete paths", () => {
+    const store = new ComponentEntityStore();
+    const compE = GlobalConfigId as EntityId; // reuse as component entity id (valid in range)
+    const target1 = createEntityId(1024);
+    const target2 = createEntityId(1025);
+    const relComp = relation(GlobalConfigId, target1); // entity-relation on the comp entity
+    const relComp2 = relation(GlobalConfigId, target2);
+    const wildcard = relation(GlobalConfigId, "*");
+
+    // Setup via internal? Use executeCommands to populate (simulates)
+    store.executeCommands(compE, [
+      { type: "set", componentType: relComp, component: { dist: 1 } } as any,
+      { type: "set", componentType: relComp2, component: { dist: 2 } } as any,
+    ]);
+
+    // hasWildcard
+    expect(store.hasWildcard(compE, GlobalConfigId as any)).toBe(true);
+    expect(store.hasWildcard(compE, GameStateId as any)).toBe(false);
+    expect(store.hasWildcard(createEntityId(9999), GlobalConfigId as any)).toBe(false); // no data
+
+    // getWildcard
+    const w1 = store.getWildcard(compE, wildcard as any);
+    expect(w1.length).toBe(2);
+
+    // wildcard delete via executeCommands
+    store.executeCommands(compE, [{ type: "delete", componentType: wildcard } as any]);
+    const afterDel = store.getWildcard(compE, wildcard as any);
+    expect(afterDel.length).toBe(0);
+
+    // also test get on non exist throws
+    expect(() => store.get(compE, createEntityId(5000) as any)).toThrow();
+    expect(store.getOptional(compE, createEntityId(5000) as any)).toBeUndefined();
+
+    // clear
+    store.clear(compE);
+    expect(store.has(compE, relComp)).toBe(false);
+  });
 });

package/src/__tests__/core/archetype.test.ts

@@ -1,6 +1,17 @@
 import { describe, expect, it } from "bun:test";
 import { Archetype } from "../../archetype/archetype";
-import { DontFragmentStoreImpl } from "../../archetype/store";
+import {
+  buildCacheKey,
+  buildRegularComponentValue,
+  buildSingleComponent,
+  buildWildcardRelationValue,
+  findWildcardRelations,
+  getWildcardRelationDataSource,
+  hasWildcardRelation,
+  isRelationType,
+  matchesRelationComponentId,
+} from "../../archetype/helpers";
+import { SparseStoreImpl } from "../../archetype/store";
 import { component, createEntityId, relation, type EntityId } from "../../entity";
 
 describe("Archetype", () => {
@@ -10,25 +21,25 @@ describe("Archetype", () => {
   const positionComponent = component<Position>();
   const velocityComponent = component<Velocity>();
 
-  // Helper function to create a real DontFragmentStore for testing.
+  // Helper function to create a real SparseStore for testing.
   // We use the production implementation because the interface is now fully semantic.
-  const createDontFragmentRelations = () => new DontFragmentStoreImpl();
+  const createSparseStore = () => new SparseStoreImpl();
 
   it("should create an archetype with component types", () => {
-    const archetype = new Archetype([positionComponent, velocityComponent], createDontFragmentRelations());
+    const archetype = new Archetype([positionComponent, velocityComponent], createSparseStore());
     expect(archetype.componentTypes).toEqual([positionComponent, velocityComponent]);
     expect(archetype.size).toBe(0);
   });
 
   it("should match component types", () => {
-    const archetype = new Archetype([positionComponent, velocityComponent], createDontFragmentRelations());
+    const archetype = new Archetype([positionComponent, velocityComponent], createSparseStore());
     expect(archetype.matches([positionComponent, velocityComponent])).toBe(true);
     expect(archetype.matches([velocityComponent, positionComponent])).toBe(true); // Order doesn't matter
     expect(archetype.matches([positionComponent])).toBe(false);
   });
 
   it("should add and remove entities", () => {
-    const archetype = new Archetype([positionComponent, velocityComponent], createDontFragmentRelations());
+    const archetype = new Archetype([positionComponent, velocityComponent], createSparseStore());
     const entity1 = createEntityId(1024);
     const entity2 = createEntityId(1025);
 
@@ -57,7 +68,7 @@ describe("Archetype", () => {
   });
 
   it("should get and set component data", () => {
-    const archetype = new Archetype([positionComponent], createDontFragmentRelations());
+    const archetype = new Archetype([positionComponent], createSparseStore());
     const entity = createEntityId(1024);
     const initialPosition: Position = { x: 5, y: 5 };
 
@@ -83,7 +94,7 @@ describe("Archetype", () => {
     const entity = createEntityId(1024);
 
     // Archetype with multiple relations
-    const archetype = new Archetype([relation1, relation2], createDontFragmentRelations());
+    const archetype = new Archetype([relation1, relation2], createSparseStore());
 
     // Add entity with relations to target1 and target2
     archetype.addEntity(
@@ -109,7 +120,7 @@ describe("Archetype", () => {
   });
 
   it("should iterate over entities", () => {
-    const archetype = new Archetype([positionComponent], createDontFragmentRelations());
+    const archetype = new Archetype([positionComponent], createSparseStore());
     const entity1 = createEntityId(1024);
     const entity2 = createEntityId(1025);
 
@@ -125,7 +136,7 @@ describe("Archetype", () => {
   });
 
   it("should get component data arrays", () => {
-    const archetype = new Archetype([positionComponent], createDontFragmentRelations());
+    const archetype = new Archetype([positionComponent], createSparseStore());
     const entity1 = createEntityId(1024);
     const entity2 = createEntityId(1025);
     const pos1: Position = { x: 1, y: 1 };
@@ -153,8 +164,8 @@ describe("Archetype", () => {
     const relation3 = relation(positionComponent, createEntityId(1029)); // For entity2
 
     // Archetype with multiple relations
-    const archetype1 = new Archetype([relation1, relation2], createDontFragmentRelations());
-    const archetype2 = new Archetype([relation3], createDontFragmentRelations());
+    const archetype1 = new Archetype([relation1, relation2], createSparseStore());
+    const archetype2 = new Archetype([relation3], createSparseStore());
 
     // Add entity1 with relations to target1 and target2
     archetype1.addEntity(
@@ -200,7 +211,7 @@ describe("Archetype", () => {
     const relation2 = relation(positionComponent, target2);
     const wildcardPositionRelation = relation(positionComponent, "*");
 
-    const archetype = new Archetype([relation1, relation2], createDontFragmentRelations());
+    const archetype = new Archetype([relation1, relation2], createSparseStore());
 
     const entity1 = createEntityId(1024);
 
@@ -246,4 +257,135 @@ describe("Archetype", () => {
       [target1, { distance: 100 }], // Updated
     ]);
   });
+
+  it("should cover getEntity, dump, getEntitiesWithComponents, getEntityToIndexMap", () => {
+    const archetype = new Archetype([positionComponent], createSparseStore());
+    const entity = createEntityId(1024);
+    archetype.addEntity(entity, new Map([[positionComponent, { x: 1, y: 2 }]]));
+
+    // Cover getEntity
+    const data = archetype.getEntity(entity);
+    expect(data).toBeDefined();
+    expect(data!.get(positionComponent)).toEqual({ x: 1, y: 2 });
+
+    // Cover dump
+    const dumped = archetype.dump();
+    expect(dumped).toHaveLength(1);
+    expect(dumped[0]!.entity).toBe(entity);
+
+    // Cover getEntitiesWithComponents
+    const withComps = archetype.getEntitiesWithComponents([positionComponent]);
+    expect(withComps).toHaveLength(1);
+    expect(withComps[0]!.entity).toBe(entity);
+
+    // Cover getEntityToIndexMap
+    const map = archetype.getEntityToIndexMap();
+    expect(map.get(entity)).toBe(0);
+  });
+
+  it("should cover SparseStoreImpl extra methods (hasAnyForComponent, getAllForEntities, multi)", () => {
+    const store = new SparseStoreImpl();
+    const e1 = createEntityId(2000);
+    const e2 = createEntityId(2001);
+
+    // Actually create proper relations for a component
+    const targetC1 = createEntityId(4001);
+    const targetC2 = createEntityId(4002);
+    const r1 = relation(velocityComponent, targetC1);
+    const r2 = relation(velocityComponent, targetC2);
+    const baseComp = velocityComponent;
+
+    store.setValue(e1, r1, { v: 1 });
+    store.setValue(e1, r2, { v: 2 }); // promote to multi
+
+    // hasAnyForComponent
+    expect(store.hasAnyForComponent(baseComp)).toBe(true);
+    expect(store.hasAnyForComponent(positionComponent)).toBe(false);
+
+    // getAllForEntities bulk
+    const bulk = store.getAllForEntities([e1, e2, createEntityId(5000)]);
+    expect(bulk.has(e1)).toBe(true);
+    expect(bulk.get(e1)).toHaveLength(2);
+
+    // getAllForEntity on one without
+    expect(store.getAllForEntity(e2)).toEqual([]);
+
+    // deleteValue on multi
+    store.deleteValue(e1, r1);
+    expect(store.getValue(e1, r1)).toBeUndefined();
+    // still has the other
+    expect(store.getValue(e1, r2)).toEqual({ v: 2 });
+
+    // delete last demotes? after delete one left in multi, delete last
+    store.deleteValue(e1, r2);
+    expect(store.hasAnyForComponent(baseComp)).toBe(false);
+  });
+
+  it("should cover archetype helpers (find*, has*, build*, matchers, error paths)", () => {
+    const comps = new Map<EntityId, any>();
+    const relC = relation(positionComponent, createEntityId(5001));
+    const relD = relation(positionComponent, createEntityId(5002));
+    comps.set(relC, { d: 10 });
+    comps.set(relD, { d: 20 });
+    comps.set(positionComponent, { x: 1 }); // non-relation
+
+    // findWildcardRelations
+    const found = findWildcardRelations(comps, positionComponent);
+    expect(found).toHaveLength(2);
+
+    // hasWildcardRelation
+    expect(hasWildcardRelation(comps, positionComponent)).toBe(true);
+    expect(hasWildcardRelation(comps, velocityComponent)).toBe(false);
+
+    // matchesRelationComponentId
+    expect(matchesRelationComponentId(relC, positionComponent)).toBe(true);
+    expect(matchesRelationComponentId(positionComponent, positionComponent)).toBe(false);
+
+    // isRelationType
+    expect(
+      isRelationType({
+        type: "entity-relation",
+        componentId: positionComponent,
+        targetId: createEntityId(1024),
+      } as any),
+    ).toBe(true);
+    expect(isRelationType({ type: "component" } as any)).toBe(false);
+
+    // buildCacheKey
+    const key = buildCacheKey([positionComponent, velocityComponent]);
+    expect(typeof key).toBe("string");
+
+    // getWildcardRelationDataSource
+    const ds = getWildcardRelationDataSource([relC, relD], positionComponent, false);
+    expect(ds).toHaveLength(2);
+    const dsOpt = getWildcardRelationDataSource([], positionComponent, true);
+    expect(dsOpt).toBeUndefined();
+
+    // buildRegularComponentValue
+    expect(buildRegularComponentValue([{ x: 9 }], 0, false)).toEqual({ x: 9 });
+    expect(buildRegularComponentValue(undefined, 0, true)).toBeUndefined();
+    expect(() => buildRegularComponentValue(undefined, 0, false)).toThrow();
+
+    // buildWildcardRelationValue - optional empty -> undefined
+    const dfStore = createSparseStore();
+    const wildcard = relation(positionComponent, "*");
+    const valOpt = buildWildcardRelationValue(wildcard, [], () => null, dfStore, createEntityId(6000), true);
+    expect(valOpt).toBeUndefined();
+
+    // buildWildcardRelationValue - mandatory empty -> throws
+    expect(() => buildWildcardRelationValue(wildcard, [], () => null, dfStore, createEntityId(6001), false)).toThrow(
+      /No matching relations found/,
+    );
+
+    // buildSingleComponent regular path
+    const val = buildSingleComponent(
+      positionComponent,
+      [{ x: 42 }],
+      0,
+      createEntityId(7000),
+      (t) => (t === positionComponent ? [{ x: 42 }] : []),
+      dfStore,
+    );
+    expect(val).toEqual({ x: 42 });
+  });
 });

package/src/__tests__/core/bitset.test.ts

@@ -168,4 +168,16 @@ describe("BitSet word boundary tests", () => {
     expect(bitset.has(24)).toBe(false);
     expect(bitset.has(26)).toBe(false);
   });
+
+  it("should expose length and handle edge has/set/clear on bounds", () => {
+    const bitset = new BitSet(10);
+    expect(bitset.length).toBe(10);
+    expect(bitset.has(-1)).toBe(false);
+    expect(bitset.has(10)).toBe(false);
+    bitset.set(-1); // no-op
+    bitset.set(10); // no-op
+    bitset.clear(-1);
+    bitset.clear(10);
+    expect(bitset.has(0)).toBe(false);
+  });
 });

package/src/__tests__/entity/entity.test.ts

@@ -22,6 +22,7 @@ import {
   isEntityId,
   isExclusiveComponent,
   isRelationId,
+  isSparseComponent,
   isWildcardRelationId,
   relation,
 } from "../../entity";
@@ -503,6 +504,38 @@ describe("Component Options", () => {
     expect(isDontFragmentComponent(combinedComp)).toBe(true);
   });
 
+  it("should support the new `sparse` option (preferred name) and treat it identically to the legacy `dontFragment`", () => {
+    const sparseComp = component({ sparse: true });
+    const normalComp = component();
+
+    // New primary predicates
+    expect(isSparseComponent(sparseComp)).toBe(true);
+    expect(isSparseComponent(normalComp)).toBe(false);
+
+    // Old aliases must still work (BC)
+    expect(isDontFragmentComponent(sparseComp)).toBe(true);
+    expect(isDontFragmentComponent(normalComp)).toBe(false);
+
+    const options = getComponentOptions(sparseComp);
+    expect(options.sparse).toBe(true);
+    // Full BC: old key is also populated
+    expect(options.dontFragment).toBe(true);
+  });
+
+  it("should treat `sparse` and `dontFragment` as equivalent (both spellings set the same flag)", () => {
+    const viaSparse = component({ sparse: true });
+    const viaLegacy = component({ dontFragment: true });
+    const viaBoth = component({ sparse: true, dontFragment: true });
+
+    for (const c of [viaSparse, viaLegacy, viaBoth]) {
+      expect(isSparseComponent(c)).toBe(true);
+      expect(isDontFragmentComponent(c)).toBe(true);
+      const opts = getComponentOptions(c);
+      expect(opts.sparse).toBe(true);
+      expect(opts.dontFragment).toBe(true);
+    }
+  });
+
   it("should store and retrieve component merge callback", () => {
     const merge = (prev: number[], next: number[]) => [...prev, ...next];
     const mailboxComp = component<number[]>({ merge });

package/src/__tests__/entity/id-system.test.ts

@@ -6,12 +6,16 @@ import {
   createEntityId,
   decodeRelationId,
   ENTITY_ID_START,
+  getComponentIdFromRelationId,
   getDetailedIdType,
   getIdType,
+  getTargetIdFromRelationId,
   inspectEntityId,
   INVALID_COMPONENT_ID,
   isComponentId,
+  isComponentRelation,
   isEntityId,
+  isEntityRelation,
   isRelationId,
   isWildcardRelationId,
   relation,
@@ -257,4 +261,40 @@ describe("Entity ID System", () => {
       expect(decoded.type).toBe("entity");
     });
   });
+
+  describe("Error paths and additional relation utils", () => {
+    it("should throw on decodeRelationId for non-relation", () => {
+      expect(() => decodeRelationId(123 as any)).toThrow("ID is not a relation ID");
+    });
+
+    it("should throw on decodeRelationId for invalid component or target in relation", () => {
+      expect(() => decodeRelationId(-123456 as any)).toThrow();
+    });
+
+    it("should cover isEntityRelation and isComponentRelation", () => {
+      const entRel = relation(createComponentId(1), createEntityId(ENTITY_ID_START));
+      const compRel = relation(createComponentId(2), createComponentId(3));
+      const wild = relation(createComponentId(4), "*");
+      const plain = createEntityId(ENTITY_ID_START);
+
+      expect(isEntityRelation(entRel)).toBe(true);
+      expect(isEntityRelation(compRel)).toBe(false);
+      expect(isEntityRelation(wild)).toBe(false);
+      expect(isEntityRelation(plain)).toBe(false);
+
+      expect(isComponentRelation(compRel)).toBe(true);
+      expect(isComponentRelation(entRel)).toBe(false);
+      expect(isComponentRelation(wild)).toBe(false);
+    });
+
+    it("should cover getComponentIdFromRelationId and getTargetIdFromRelationId on valids and invalids", () => {
+      const r = relation(createComponentId(99), createEntityId(1024));
+      expect(getComponentIdFromRelationId(r)).toBe(createComponentId(99));
+      expect(getTargetIdFromRelationId(r)).toBe(createEntityId(1024));
+
+      expect(getComponentIdFromRelationId(123 as any)).toBeUndefined();
+      expect(getTargetIdFromRelationId(123 as any)).toBeUndefined();
+      expect(getComponentIdFromRelationId(-999999 as any)).toBeUndefined();
+    });
+  });
 });