@codehz/ecs 0.8.2 → 0.10.0

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();
+    });
+  });
 });

package/src/__tests__/perf/comprehensive.perf.test.ts

@@ -117,7 +117,7 @@ describe("Comprehensive ECS performance benchmarks", () => {
     }
     world.sync();
 
-    const movementQuery = world.createQuery([Position, Velocity]);
+    using movementQuery = world.createQuery([Position, Velocity]);
 
     // Pure iteration (no writes)
     const readAvg = benchmark("10k entities: forEach read-only query", 2, 6, () => {
@@ -137,8 +137,6 @@ describe("Comprehensive ECS performance benchmarks", () => {
       });
     });
 
-    movementQuery.dispose();
-
     console.log(`Sum X (to prevent optimization): ${sumX}`);
     expect(readAvg).toBeLessThan(20);
     expect(updateAvg).toBeLessThan(20);
@@ -195,7 +193,7 @@ describe("Comprehensive ECS performance benchmarks", () => {
     }
     world.sync();
 
-    const movementQuery = world.createQuery([Position, Health]);
+    using movementQuery = world.createQuery([Position, Health]);
 
     const mixedAvg = benchmark("2k entities: mixed ops (update 90%, spawn 5%, delete 5%) + sync", 2, 6, (round) => {
       const deleteCount = Math.floor(entities.length * 0.05);
@@ -226,7 +224,6 @@ describe("Comprehensive ECS performance benchmarks", () => {
       world.sync();
     });
 
-    movementQuery.dispose();
     expect(mixedAvg).toBeLessThan(300);
   });
 
@@ -265,12 +262,12 @@ describe("Comprehensive ECS performance benchmarks", () => {
   });
 
   /**
-   * Benchmark 7: dontFragment relation updates (the existing benchmark scenario)
+   * Benchmark 7: sparse relation updates
    */
-  it("should handle dontFragment exclusive relation flips efficiently", () => {
+  it("should handle exclusive sparse relation flips efficiently", () => {
     const world = new World();
     const Position = component<{ x: number; y: number }>();
-    const ChildOf = component({ dontFragment: true, exclusive: true });
+    const ChildOf = component({ sparse: true, exclusive: true });
 
     const parentA = world.new();
     const parentB = world.new();
@@ -285,7 +282,7 @@ describe("Comprehensive ECS performance benchmarks", () => {
     }
     world.sync();
 
-    const relationFlipAvg = benchmark("4k entities: exclusive dontFragment relation flip + sync", 2, 8, (round) => {
+    const relationFlipAvg = benchmark("4k entities: exclusive sparse relation flip + sync", 2, 8, (round) => {
       const target = round % 2 === 0 ? parentB : parentA;
       for (let i = 0; i < entities.length; i++) {
         world.set(entities[i]!, relation(ChildOf, target));

package/src/__tests__/perf/serialization.perf.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it } from "bun:test";
+import { component, relation, type EntityId } from "../../entity";
+import { World } from "../../world/world";
+
+function benchmark(label: string, warmupRounds: number, measuredRounds: number, fn: (round: number) => void): number {
+  const durations: number[] = [];
+
+  const totalRounds = warmupRounds + measuredRounds;
+  for (let round = 0; round < totalRounds; round++) {
+    const start = performance.now();
+    fn(round);
+    const duration = performance.now() - start;
+    if (round >= warmupRounds) {
+      durations.push(duration);
+    }
+  }
+
+  const average = durations.reduce((sum, duration) => sum + duration, 0) / durations.length;
+  console.log(
+    `${label}: avg ${average.toFixed(2)}ms after ${warmupRounds} warmup rounds (${durations
+      .map((d) => d.toFixed(2))
+      .join("ms, ")}ms per measured round)`,
+  );
+  return average;
+}
+
+/**
+ * Serialization performance benchmarks.
+ *
+ * These benchmarks validate the post-optimization serialization path
+ * (see optimization plan for src/world/serialization.ts):
+ *
+ * Key optimizations exercised:
+ * - Column-oriented direct export from Archetype (bypasses per-entity Map + dump())
+ * - Per-archetype pre-encoding of component type IDs
+ * - ID encoding cache (encodeEntityIdCached) for repeated component/relation IDs
+ * - Removal of redundant per-entity work in deserialization
+ *
+ * Target scale: 8k–12k entities across multiple archetypes + relations.
+ * This is large enough to show meaningful differences while keeping test runtime reasonable.
+ */
+describe("Serialization performance (post-optimization baseline)", () => {
+  it("should serialize and deserialize large mixed worlds efficiently", () => {
+    const world = new World();
+
+    // Named components (realistic serialization path with name lookup)
+    const Position = component<{ x: number; y: number }>("Position");
+    const Velocity = component<{ vx: number; vy: number }>("Velocity");
+    const Health = component<{ hp: number; maxHp: number }>("Health");
+    const Name = component<{ value: string }>("Name");
+    const Inventory = component<{ items: string[] }>("Inventory");
+
+    // Entity-valued component (creates entity references)
+    const Target = component<{ entity: EntityId }>("Target");
+
+    // Relations
+    const ChildOf = component<void>("ChildOf");
+
+    const entityCount = 12_000;
+    const entities: EntityId[] = [];
+
+    // Distribute entities across several archetypes for realistic archetype diversity
+    // Archetype A: Position + Velocity + Health
+    // Archetype B: Position + Name + Inventory
+    // Archetype C: Position + Velocity + Target (entity-valued component)
+    // Archetype D: Position only (minimal)
+
+    const parents: EntityId[] = [];
+
+    for (let i = 0; i < entityCount; i++) {
+      const entity = world.new();
+      entities.push(entity);
+
+      const archetypeKind = i % 4;
+
+      world.set(entity, Position, { x: i, y: i * 2 });
+
+      if (archetypeKind === 0) {
+        // Archetype A
+        world.set(entity, Velocity, { vx: 1, vy: 0.5 });
+        world.set(entity, Health, { hp: 100, maxHp: 100 });
+      } else if (archetypeKind === 1) {
+        // Archetype B
+        world.set(entity, Name, { value: `Entity-${i}` });
+        world.set(entity, Inventory, { items: ["sword", "potion"] });
+      } else if (archetypeKind === 2) {
+        // Archetype C — has entity reference
+        world.set(entity, Velocity, { vx: 0.2, vy: -1 });
+        // Point to a previous entity (creates realistic entity-valued component)
+        const targetIdx = Math.max(0, i - 7);
+        world.set(entity, Target, { entity: entities[targetIdx]! });
+      } else {
+        // Archetype D — minimal
+        // Only Position
+      }
+
+      // Every 17th entity becomes a parent and gets some children via relations
+      if (i % 17 === 0) {
+        parents.push(entity);
+      }
+    }
+
+    // Add relations (ChildOf) — creates entity-relation IDs that must be encoded
+    for (let i = 0; i < entityCount; i++) {
+      const parentIdx = Math.floor(i / 8) % Math.max(1, parents.length);
+      const parent = parents[parentIdx] ?? entities[0]!;
+      if (parent !== entities[i]) {
+        world.set(entities[i]!, relation(ChildOf, parent));
+      }
+    }
+
+    world.sync();
+
+    expect(entities.length).toBe(entityCount);
+
+    const warmup = 2;
+    const measured = 5;
+
+    // === Serialize ===
+    let lastSnapshot: ReturnType<World["serialize"]> | null = null;
+
+    const serializeAvg = benchmark(
+      `serialize ${entityCount} entities (mixed archetypes + relations)`,
+      warmup,
+      measured,
+      () => {
+        lastSnapshot = world.serialize();
+      },
+    );
+
+    expect(lastSnapshot).toBeDefined();
+    expect(lastSnapshot!.entities.length).toBeGreaterThanOrEqual(entityCount * 0.9); // rough sanity
+
+    // Measure rough heap impact of a serialize call.
+    // Note: Bun may require --smol or explicit GC for more stable allocation numbers.
+    if (typeof Bun !== "undefined" && Bun.gc) {
+      Bun.gc(true);
+    }
+    const memBefore = process.memoryUsage();
+    void world.serialize();
+    const memAfter = process.memoryUsage();
+    const heapDeltaMB = ((memAfter.heapUsed - memBefore.heapUsed) / 1024 / 1024).toFixed(2);
+    console.log(
+      `serialize heap delta (one call): ~${heapDeltaMB} MB (rss delta: ${((memAfter.rss - memBefore.rss) / 1024 / 1024).toFixed(2)} MB)`,
+    );
+
+    // === Deserialize (new World from snapshot) ===
+    const deserializeAvg = benchmark(
+      `deserialize ${entityCount} entities (new World(snapshot))`,
+      warmup,
+      measured,
+      () => {
+        // We create and immediately let go of the world to measure allocation + construction cost
+        const restored = new World(lastSnapshot!);
+        // Touch one value to prevent dead-code elimination in theory
+        if (restored.exists(entities[0]!)) {
+          void restored.get(entities[0]!, Position);
+        }
+      },
+    );
+
+    // === Full JSON roundtrip (very common user pattern) ===
+    const jsonRoundtripAvg = benchmark(
+      `full JSON roundtrip (stringify + parse + new World) — ${entityCount} entities`,
+      warmup,
+      measured,
+      () => {
+        const json = JSON.stringify(world.serialize());
+        const parsed = JSON.parse(json);
+        const restored = new World(parsed);
+        if (restored.exists(entities[42]!)) {
+          void restored.get(entities[42]!, Position);
+        }
+      },
+    );
+
+    // Loose upper bounds — these act as regression guards.
+    // The numbers are intentionally generous to account for CI machine variance.
+    // The main value is the detailed console output for manual before/after comparison.
+    expect(serializeAvg).toBeLessThan(80); // ~12k entities serialize
+    expect(deserializeAvg).toBeLessThan(120); // new World(snapshot) tends to be heavier
+    expect(jsonRoundtripAvg).toBeLessThan(200); // includes JSON + full deserialize
+
+    // Final sanity: the last deserialized world should still have most entities
+    const finalRestored = new World(lastSnapshot!);
+    expect(finalRestored.exists(entities[0]!)).toBe(true);
+    expect(finalRestored.exists(entities[entityCount - 1]!)).toBe(true);
+  });
+
+  it("should handle worlds with heavy entity-relation usage", () => {
+    const world = new World();
+
+    const Position = component<{ x: number; y: number }>("Pos");
+    const Owes = component<{ amount: number }>("Owes"); // used for relations
+
+    const entityCount = 8_000;
+    const entities: EntityId[] = [];
+
+    for (let i = 0; i < entityCount; i++) {
+      const e = world.new();
+      entities.push(e);
+      world.set(e, Position, { x: i, y: i });
+    }
+
+    // Create a dense web of entity-relations (every entity owes 3 others)
+    for (let i = 0; i < entityCount; i++) {
+      for (let j = 1; j <= 3; j++) {
+        const target = entities[(i + j * 17) % entityCount]!;
+        if (target !== entities[i]) {
+          world.set(entities[i]!, relation(Owes, target), { amount: (i + j) % 100 });
+        }
+      }
+    }
+
+    world.sync();
+
+    const warmup = 1;
+    const measured = 4;
+
+    const serializeAvg = benchmark(
+      `serialize ${entityCount} entities (dense entity-relations)`,
+      warmup,
+      measured,
+      () => {
+        void world.serialize();
+      },
+    );
+
+    // Deserialize with many relations exercises decode + reference tracking
+    let snapshot: ReturnType<World["serialize"]> | undefined;
+
+    const deserializeAvg = benchmark(`deserialize ${entityCount} entities (dense relations)`, warmup, measured, () => {
+      if (!snapshot) snapshot = world.serialize();
+      const w = new World(snapshot);
+      void w;
+    });
+
+    // Very loose bounds — this scenario is intentionally expensive
+    expect(serializeAvg).toBeLessThan(150);
+    expect(deserializeAvg).toBeLessThan(220);
+  });
+});