@codehz/ecs 0.5.4 → 0.6.0

package/builder.d.mts

@@ -175,7 +175,7 @@ interface Command {
 /**
  * Hook types for component lifecycle events
  */
-interface LifecycleHook<T = unknown> {
+interface LegacyLifecycleHook<T = unknown> {
   /**
    * Called when a component is added to an entity
    */
@@ -189,21 +189,21 @@ interface LifecycleHook<T = unknown> {
    */
   on_remove?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
 }
-interface MultiLifecycleHook<T extends readonly ComponentType<any>[]> {
-  on_init?: (entityId: EntityId, componentTypes: T, components: ComponentTuple<T>) => void;
-  on_set?: (entityId: EntityId, componentTypes: T, components: ComponentTuple<T>) => void;
-  on_remove?: (entityId: EntityId, componentTypes: T, components: ComponentTuple<T>) => void;
+interface LifecycleHook<T extends readonly ComponentType<any>[]> {
+  on_init?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
+  on_set?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
+  on_remove?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
 }
 /**
  * Convenience function type for single component lifecycle events
  * Combines on_init, on_set, and on_remove into a single callback
  */
-type LifecycleCallback<T = unknown> = (type: "init" | "set" | "remove", entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+type LegacyLifecycleCallback<T = unknown> = (type: "init" | "set" | "remove", entityId: EntityId, componentType: EntityId<T>, component: T) => void;
 /**
  * Convenience function type for multi-component lifecycle events
  * Combines on_init, on_set, and on_remove into a single callback
  */
-type MultiLifecycleCallback<T extends readonly ComponentType<any>[]> = (type: "init" | "set" | "remove", entityId: EntityId, componentTypes: T, components: ComponentTuple<T>) => void;
+type LifecycleCallback<T extends readonly ComponentType<any>[]> = (type: "init" | "set" | "remove", entityId: EntityId, ...components: ComponentTuple<T>) => void;
 type ComponentType<T> = EntityId<T> | OptionalEntityId<T>;
 type OptionalEntityId<T> = {
   optional: EntityId<T>;
@@ -217,6 +217,12 @@ type ComponentTypeToData<T> = T extends {
  * Type helper for component tuples extracted from EntityId array
  */
 type ComponentTuple<T extends readonly ComponentType<any>[]> = { readonly [K in keyof T]: ComponentTypeToData<T[K]> };
+interface LifecycleHookEntry {
+  componentTypes: readonly ComponentType<any>[];
+  requiredComponents: EntityId<any>[];
+  optionalComponents: EntityId<any>[];
+  hook: LifecycleHook<any>;
+}
 //#endregion
 //#region src/core/archetype.d.ts
 /**
@@ -248,6 +254,13 @@ declare class Archetype {
    * Stored in World to avoid migration overhead when entities change archetypes
    */
   private dontFragmentRelations;
+  /**
+   * Cache for pre-computed component data sources to avoid repeated calculations
+   */
+  /**
+   * Multi-hooks that match this archetype
+   */
+  readonly matchingMultiHooks: Set<LifecycleHookEntry>;
   /**
    * Cache for pre-computed component data sources to avoid repeated calculations
    */
@@ -416,8 +429,8 @@ declare class World {
   private queries;
   private queryCache;
   private commandBuffer;
+  private legacyHooks;
   private hooks;
-  private multiHooks;
   constructor(snapshot?: SerializedWorld);
   private deserializeSnapshot;
   private createArchetypeSignature;
@@ -434,10 +447,13 @@ declare class World {
   getOptional<T>(entityId: EntityId, componentType: EntityId<T>): {
     value: T;
   } | undefined;
-  hook<T>(componentType: EntityId<T>, hook: LifecycleHook<T> | LifecycleCallback<T>): void;
-  hook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: MultiLifecycleHook<T> | MultiLifecycleCallback<T>): void;
-  unhook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
-  unhook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: MultiLifecycleHook<T>): void;
+  /**
+   * @deprecated use array overload with LifecycleCallback
+   */
+  hook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T> | LegacyLifecycleCallback<T>): void;
+  hook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T> | LifecycleCallback<T>): void;
+  unhook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T>): void;
+  unhook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T>): void;
   sync(): void;
   createQuery(componentTypes: EntityId<any>[], filter?: QueryFilter): Query;
   spawn(): EntityBuilder;
@@ -458,6 +474,8 @@ declare class World {
   private updateEntityReferences;
   private ensureArchetype;
   private createNewArchetype;
+  private updateArchetypeHookMatches;
+  private archetypeMatchesHook;
   private archetypeReferencesEntity;
   private cleanupArchetypesReferencingEntity;
   private removeArchetype;
@@ -495,5 +513,5 @@ declare class EntityBuilder {
   build(): EntityId;
 }
 //#endregion
-export { isRelationId as A, ComponentRelationId as C, WildcardRelationId as D, RelationId as E, isComponentId as O, ComponentId as S, EntityRelationId as T, getComponentIdByName as _, SerializedEntity as a, isWildcardRelationId as b, Query as c, LifecycleCallback as d, LifecycleHook as f, component as g, ComponentOptions as h, SerializedComponent as i, isEntityId as k, ComponentTuple as l, MultiLifecycleHook as m, EntityBuilder as n, SerializedEntityId as o, MultiLifecycleCallback as p, World as r, SerializedWorld as s, ComponentDef as t, ComponentType as u, getComponentNameById as v, EntityId as w, relation as x, decodeRelationId as y };
+export { isRelationId as A, ComponentRelationId as C, WildcardRelationId as D, RelationId as E, isComponentId as O, ComponentId as S, EntityRelationId as T, getComponentIdByName as _, SerializedEntity as a, isWildcardRelationId as b, Query as c, LegacyLifecycleCallback as d, LegacyLifecycleHook as f, component as g, ComponentOptions as h, SerializedComponent as i, isEntityId as k, ComponentTuple as l, LifecycleHook as m, EntityBuilder as n, SerializedEntityId as o, LifecycleCallback as p, World as r, SerializedWorld as s, ComponentDef as t, ComponentType as u, getComponentNameById as v, EntityId as w, relation as x, decodeRelationId as y };
 //# sourceMappingURL=builder.d.mts.map

package/index.d.mts

@@ -1,2 +1,2 @@
-import { A as isRelationId, C as ComponentRelationId, D as WildcardRelationId, E as RelationId, O as isComponentId, S as ComponentId, T as EntityRelationId, _ as getComponentIdByName, a as SerializedEntity, b as isWildcardRelationId, c as Query, d as LifecycleCallback, f as LifecycleHook, g as component, h as ComponentOptions, i as SerializedComponent, k as isEntityId, l as ComponentTuple, m as MultiLifecycleHook, n as EntityBuilder, o as SerializedEntityId, p as MultiLifecycleCallback, r as World, s as SerializedWorld, t as ComponentDef, u as ComponentType, v as getComponentNameById, w as EntityId, x as relation, y as decodeRelationId } 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, type MultiLifecycleCallback, type MultiLifecycleHook, 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 isRelationId, C as ComponentRelationId, D as WildcardRelationId, E as RelationId, O as isComponentId, S as ComponentId, T as EntityRelationId, _ as getComponentIdByName, a as SerializedEntity, b as isWildcardRelationId, c as Query, d as LegacyLifecycleCallback, f as LegacyLifecycleHook, g as component, h as ComponentOptions, i as SerializedComponent, k as isEntityId, l as ComponentTuple, m as LifecycleHook, n as EntityBuilder, o as SerializedEntityId, p as LifecycleCallback, r as World, s as SerializedWorld, t as ComponentDef, u as ComponentType, v as getComponentNameById, w as EntityId, x as relation, y as decodeRelationId } from "./builder.mjs";
+export { type ComponentDef, type ComponentId, type ComponentOptions, type ComponentRelationId, type ComponentTuple, type ComponentType, EntityBuilder, type EntityId, type EntityRelationId, type LegacyLifecycleCallback as LifecycleCallback, type LegacyLifecycleHook as LifecycleHook, type LifecycleCallback as MultiLifecycleCallback, type LifecycleHook as MultiLifecycleHook, Query, type RelationId, type SerializedComponent, type SerializedEntity, type SerializedEntityId, type SerializedWorld, type WildcardRelationId, World, component, decodeRelationId, getComponentIdByName, getComponentNameById, isComponentId, isEntityId, isRelationId, isWildcardRelationId, relation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "repository": {
     "url": "https://github.com/codehz/ecs"
   },

package/testing.d.mts

@@ -1,4 +1,4 @@
-import { D as WildcardRelationId, E as RelationId, S as ComponentId, c as Query, d as LifecycleCallback, f as LifecycleHook, g as component, m as MultiLifecycleHook, n as EntityBuilder, p as MultiLifecycleCallback, r as World, t as ComponentDef, w as EntityId, x as relation } from "./builder.mjs";
+import { D as WildcardRelationId, E as RelationId, S as ComponentId, c as Query, d as LegacyLifecycleCallback, f as LegacyLifecycleHook, g as component, m as LifecycleHook, n as EntityBuilder, p as LifecycleCallback, r as World, t as ComponentDef, w as EntityId, x as relation } from "./builder.mjs";
 
 //#region src/testing/index.d.ts
 
@@ -254,5 +254,5 @@ declare class AssertionError extends Error {
   constructor(message: string);
 }
 //#endregion
-export { AssertionError, Assertions, type ComponentDef, type ComponentId, EntityBuilder, type EntityId, EntitySnapshot, type LifecycleCallback, type LifecycleHook, type MultiLifecycleCallback, type MultiLifecycleHook, type Query, type RelationId, Snapshot, SnapshotDiff, type WildcardRelationId, World, WorldFixture, WorldSnapshot, component, relation };
+export { AssertionError, Assertions, type ComponentDef, type ComponentId, EntityBuilder, type EntityId, EntitySnapshot, type LegacyLifecycleCallback as LifecycleCallback, type LegacyLifecycleHook as LifecycleHook, type LifecycleCallback as MultiLifecycleCallback, type LifecycleHook as MultiLifecycleHook, type Query, type RelationId, Snapshot, SnapshotDiff, type WildcardRelationId, World, WorldFixture, WorldSnapshot, component, relation };
 //# sourceMappingURL=testing.d.mts.map

package/testing.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"testing.mjs","names":["entitySnapshots: EntitySnapshot[]","addedEntities: EntityId[]","removedEntities: EntityId[]","componentChanges: SnapshotDiff[\"componentChanges\"]","result: Record<string, unknown>"],"sources":["../src/testing/index.ts"],"sourcesContent":["/**\n * @module testing\n * Testing utilities for ECS-based game logic\n *\n * This module provides framework-agnostic testing helpers that work with\n * bun:test, vitest, jest, or any other testing framework.\n *\n * @example\n * ```typescript\n * import { describe, expect, it } from \"bun:test\";\n * import { component } from \"@codehz/ecs\";\n * import { WorldFixture, EntityBuilder, Assertions } from \"@codehz/ecs/testing\";\n *\n * const PositionId = component<{ x: number; y: number }>();\n * const VelocityId = component<{ x: number; y: number }>();\n *\n * describe(\"Movement System\", () => {\n *   it(\"should update position based on velocity\", () => {\n *     const fixture = new WorldFixture();\n *     const entity = fixture\n *       .spawn()\n *       .with(PositionId, { x: 0, y: 0 })\n *       .with(VelocityId, { x: 1, y: 2 })\n *       .build();\n *\n *     // Run your game logic here\n *     movementSystem(fixture.world, 1.0);\n *\n *     expect(Assertions.hasComponent(fixture.world, entity, PositionId)).toBe(true);\n *     expect(Assertions.getComponent(fixture.world, entity, PositionId)).toEqual({ x: 1, y: 2 });\n *   });\n * });\n * ```\n */\n\nimport type { ComponentId, EntityId, WildcardRelationId } from \"../core/entity\";\nimport { isWildcardRelationId, relation } from \"../core/entity\";\nimport { World } from \"../core/world\";\nimport type { Query } from \"../query/query\";\nexport { EntityBuilder } from \"../core/builder\";\nexport type { ComponentDef } from \"../core/builder\";\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * A component definition for entity building, supporting both regular components and relations\n */\nimport type { EntityBuilder } from \"../core/builder\";\n\n/**\n * Snapshot of a single entity's component state\n */\nexport interface EntitySnapshot {\n  entity: EntityId;\n  components: Map<EntityId<any>, unknown>;\n}\n\n/**\n * Snapshot of multiple entities' component state\n */\nexport interface WorldSnapshot {\n  entities: EntitySnapshot[];\n}\n\n/**\n * Result of comparing two snapshots\n */\nexport interface SnapshotDiff {\n  /** Entities that exist in 'after' but not in 'before' */\n  addedEntities: EntityId[];\n  /** Entities that exist in 'before' but not in 'after' */\n  removedEntities: EntityId[];\n  /** Changes to components on existing entities */\n  componentChanges: Array<{\n    entity: EntityId;\n    componentId: EntityId<any>;\n    before: unknown | undefined;\n    after: unknown | undefined;\n    changeType: \"added\" | \"removed\" | \"modified\";\n  }>;\n}\n\n// =============================================================================\n// WorldFixture - Test World Factory\n// =============================================================================\n\n/**\n * A test fixture that manages a World instance and provides convenient\n * methods for setting up test scenarios.\n *\n * @example\n * ```typescript\n * const fixture = new WorldFixture();\n *\n * // Spawn entities with fluent API\n * const player = fixture\n *   .spawn()\n *   .with(PositionId, { x: 0, y: 0 })\n *   .with(HealthId, { current: 100, max: 100 })\n *   .build();\n *\n * // Access the world for running systems\n * movementSystem(fixture.world);\n *\n * // Clean up (optional - creates a fresh world)\n * fixture.reset();\n * ```\n */\nexport class WorldFixture {\n  private _world: World;\n  private _queries: Query[] = [];\n\n  constructor() {\n    this._world = new World();\n  }\n\n  /**\n   * Get the underlying World instance\n   */\n  get world(): World {\n    return this._world;\n  }\n\n  /**\n   * Create a new EntityBuilder for spawning an entity with components\n   */\n  spawn(): EntityBuilder {\n    return this._world.spawn();\n  }\n\n  /**\n   * Spawn multiple entities with the same component configuration\n   * @param count Number of entities to spawn\n   * @param configure Function to configure each entity builder\n   * @returns Array of created entity IDs\n   */\n  spawnMany(count: number, configure: (builder: EntityBuilder, index: number) => EntityBuilder): EntityId[] {\n    return this._world.spawnMany(count, configure);\n  }\n\n  /**\n   * Create a query and track it for automatic cleanup\n   * @param componentTypes Component types to query for\n   * @returns Query instance\n   */\n  createQuery(componentTypes: EntityId<any>[]): Query {\n    const query = this._world.createQuery(componentTypes);\n    this._queries.push(query);\n    return query;\n  }\n\n  /**\n   * Execute pending commands (alias for world.sync())\n   */\n  sync(): void {\n    this._world.sync();\n  }\n\n  /**\n   * Reset the fixture with a fresh World instance\n   * Disposes all tracked queries\n   */\n  reset(): void {\n    for (const query of this._queries) {\n      query.dispose();\n    }\n    this._queries = [];\n    this._world = new World();\n  }\n\n  /**\n   * Capture a snapshot of specified entities and their components\n   * @param entities Entities to capture\n   * @param componentIds Components to include in the snapshot\n   */\n  captureSnapshot(entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot {\n    return Snapshot.capture(this._world, entities, componentIds);\n  }\n\n  /**\n   * Symbol.dispose implementation for automatic resource management\n   */\n  [Symbol.dispose](): void {\n    this.reset();\n  }\n}\n\n// =============================================================================\n// EntityBuilder - Fluent Entity Creation\n// =============================================================================\n\n/**\n * Fluent builder for creating entities with components.\n * Supports both regular components and entity relations.\n *\n * @example\n * ```typescript\n * // Basic usage\n * // Note: build() will enqueue component commands but will NOT call world.sync().\n * // You must call world.sync() or fixture.sync() manually to apply commands.\n * const entity = new EntityBuilder(world)\n *   .with(PositionId, { x: 10, y: 20 })\n *   .with(VelocityId, { x: 1, y: 0 })\n *   .build();\n *   // Apply pending changes\n *   world.sync();\n *\n * // With relations\n * const child = new EntityBuilder(world)\n *   .with(PositionId, { x: 0, y: 0 })\n *   .withRelation(ParentId, parentEntity, { offset: { x: 5, y: 5 } })\n *   .build();\n *   world.sync();\n *\n * // Tag component (void type)\n * const tagged = new EntityBuilder(world)\n *   .withTag(PlayerTagId)\n *   .build();\n * ```\n */\n// EntityBuilder is exported from world.ts; testing utilities will use world.spawn()\n\n// =============================================================================\n// Assertions - Test Assertion Helpers\n// =============================================================================\n\n/**\n * Test assertion utilities that return boolean values or throw descriptive errors.\n * These work with any testing framework's expect() function.\n *\n * @example\n * ```typescript\n * // With bun:test or vitest\n * expect(Assertions.hasComponent(world, entity, PositionId)).toBe(true);\n * expect(Assertions.getComponent(world, entity, PositionId)).toEqual({ x: 10, y: 20 });\n *\n * // Direct assertion (throws on failure)\n * Assertions.assertHasComponent(world, entity, PositionId);\n * Assertions.assertComponentEquals(world, entity, PositionId, { x: 10, y: 20 });\n * ```\n */\nexport const Assertions = {\n  /**\n   * Check if an entity has a specific component\n   */\n  hasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean {\n    return world.exists(entity) && world.has(entity, componentId);\n  },\n\n  /**\n   * Check if an entity does not have a specific component\n   */\n  lacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean {\n    return !world.exists(entity) || !world.has(entity, componentId);\n  },\n\n  /**\n   * Get a component value (returns undefined if entity doesn't exist or doesn't have the component)\n   */\n  getComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): T | undefined {\n    if (!world.exists(entity) || !world.has(entity, componentId)) {\n      return undefined;\n    }\n    return world.get(entity, componentId);\n  },\n\n  /**\n   * Get all relation instances for a wildcard relation\n   */\n  getRelations<T>(world: World, entity: EntityId, componentId: ComponentId<T>): [EntityId<unknown>, T][] | undefined {\n    if (!world.exists(entity)) {\n      return undefined;\n    }\n    const wildcardId = relation(componentId, \"*\");\n    try {\n      return world.get(entity, wildcardId);\n    } catch {\n      return [];\n    }\n  },\n\n  /**\n   * Check if an entity has a relation to a specific target\n   */\n  hasRelation<T>(world: World, entity: EntityId, componentId: ComponentId<T>, targetEntity: EntityId<any>): boolean {\n    if (!world.exists(entity)) {\n      return false;\n    }\n    const relationId = relation(componentId, targetEntity);\n    return world.has(entity, relationId);\n  },\n\n  /**\n   * Check if an entity exists in the world\n   */\n  entityExists(world: World, entity: EntityId): boolean {\n    return world.exists(entity);\n  },\n\n  /**\n   * Check if a query contains specific entities\n   */\n  queryContains(query: Query, ...entities: EntityId[]): boolean {\n    const queryEntities = query.getEntities();\n    return entities.every((e) => queryEntities.includes(e));\n  },\n\n  /**\n   * Check if a query contains exactly the specified entities (no more, no less)\n   */\n  queryContainsExactly(query: Query, ...entities: EntityId[]): boolean {\n    const queryEntities = query.getEntities();\n    if (queryEntities.length !== entities.length) {\n      return false;\n    }\n    return entities.every((e) => queryEntities.includes(e));\n  },\n\n  /**\n   * Get the count of entities in a query\n   */\n  queryCount(query: Query): number {\n    return query.getEntities().length;\n  },\n\n  // === Throwing assertions ===\n\n  /**\n   * Assert that an entity has a component (throws if not)\n   */\n  assertHasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void {\n    if (!world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} does not exist`);\n    }\n    if (!world.has(entity, componentId)) {\n      throw new AssertionError(`Entity ${entity} does not have component ${componentId}`);\n    }\n  },\n\n  /**\n   * Assert that an entity lacks a component (throws if it has the component)\n   */\n  assertLacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void {\n    if (world.exists(entity) && world.has(entity, componentId)) {\n      throw new AssertionError(`Entity ${entity} unexpectedly has component ${componentId}`);\n    }\n  },\n\n  /**\n   * Assert that a component equals an expected value (throws if not)\n   */\n  assertComponentEquals<T>(world: World, entity: EntityId, componentId: EntityId<T>, expected: T): void {\n    this.assertHasComponent(world, entity, componentId);\n    const actual = world.get(entity, componentId);\n    if (!deepEquals(actual, expected)) {\n      throw new AssertionError(\n        `Component ${componentId} on entity ${entity} does not match expected value.\\n` +\n          `Expected: ${JSON.stringify(expected)}\\n` +\n          `Actual: ${JSON.stringify(actual)}`,\n      );\n    }\n  },\n\n  /**\n   * Assert that an entity exists (throws if not)\n   */\n  assertEntityExists(world: World, entity: EntityId): void {\n    if (!world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} does not exist`);\n    }\n  },\n\n  /**\n   * Assert that an entity does not exist (throws if it exists)\n   */\n  assertEntityNotExists(world: World, entity: EntityId): void {\n    if (world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} unexpectedly exists`);\n    }\n  },\n\n  /**\n   * Assert that a query contains specific entities (throws if not)\n   */\n  assertQueryContains(query: Query, ...entities: EntityId[]): void {\n    const queryEntities = query.getEntities();\n    for (const entity of entities) {\n      if (!queryEntities.includes(entity)) {\n        throw new AssertionError(\n          `Query does not contain entity ${entity}.\\n` + `Query entities: [${queryEntities.join(\", \")}]`,\n        );\n      }\n    }\n  },\n\n  /**\n   * Assert that a query does not contain specific entities (throws if it does)\n   */\n  assertQueryNotContains(query: Query, ...entities: EntityId[]): void {\n    const queryEntities = query.getEntities();\n    for (const entity of entities) {\n      if (queryEntities.includes(entity)) {\n        throw new AssertionError(\n          `Query unexpectedly contains entity ${entity}.\\n` + `Query entities: [${queryEntities.join(\", \")}]`,\n        );\n      }\n    }\n  },\n};\n\n// =============================================================================\n// Snapshot - State Capture and Comparison\n// =============================================================================\n\n/**\n * Utilities for capturing and comparing world state snapshots.\n * Useful for testing that systems produce expected state changes.\n *\n * @example\n * ```typescript\n * const before = Snapshot.capture(world, [entity], [PositionId, VelocityId]);\n *\n * // Run game logic\n * movementSystem(world, deltaTime);\n * world.sync();\n *\n * const after = Snapshot.capture(world, [entity], [PositionId, VelocityId]);\n * const diff = Snapshot.compare(before, after);\n *\n * expect(diff.componentChanges).toHaveLength(1);\n * expect(diff.componentChanges[0].changeType).toBe(\"modified\");\n * ```\n */\nexport const Snapshot = {\n  /**\n   * Capture a snapshot of specified entities and their components\n   * @param world The world to capture from\n   * @param entities Entities to include in the snapshot\n   * @param componentIds Components to capture for each entity\n   */\n  capture(world: World, entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot {\n    const entitySnapshots: EntitySnapshot[] = [];\n\n    for (const entity of entities) {\n      if (!world.exists(entity)) {\n        continue;\n      }\n\n      const components = new Map<EntityId<any>, unknown>();\n\n      for (const componentId of componentIds) {\n        if (isWildcardRelationId(componentId)) {\n          // For wildcard relations, capture all relation instances\n          try {\n            const relations = world.get(entity, componentId as WildcardRelationId<any>);\n            if (relations && relations.length > 0) {\n              components.set(componentId, deepClone(relations));\n            }\n          } catch {\n            // Entity doesn't have this relation type\n          }\n        } else if (world.has(entity, componentId)) {\n          components.set(componentId, deepClone(world.get(entity, componentId)));\n        }\n      }\n\n      entitySnapshots.push({ entity, components });\n    }\n\n    return { entities: entitySnapshots };\n  },\n\n  /**\n   * Compare two snapshots and return the differences\n   * @param before The 'before' snapshot\n   * @param after The 'after' snapshot\n   */\n  compare(before: WorldSnapshot, after: WorldSnapshot): SnapshotDiff {\n    const beforeEntities = new Set(before.entities.map((e) => e.entity));\n    const afterEntities = new Set(after.entities.map((e) => e.entity));\n\n    const addedEntities: EntityId[] = [];\n    const removedEntities: EntityId[] = [];\n    const componentChanges: SnapshotDiff[\"componentChanges\"] = [];\n\n    // Find added entities\n    for (const entity of afterEntities) {\n      if (!beforeEntities.has(entity)) {\n        addedEntities.push(entity);\n      }\n    }\n\n    // Find removed entities\n    for (const entity of beforeEntities) {\n      if (!afterEntities.has(entity)) {\n        removedEntities.push(entity);\n      }\n    }\n\n    // Find component changes on existing entities\n    const beforeMap = new Map(before.entities.map((e) => [e.entity, e]));\n    const afterMap = new Map(after.entities.map((e) => [e.entity, e]));\n\n    for (const entity of beforeEntities) {\n      if (!afterEntities.has(entity)) continue; // Skip removed entities\n\n      const beforeEntity = beforeMap.get(entity)!;\n      const afterEntity = afterMap.get(entity)!;\n\n      // Check for component changes\n      const allComponentIds = new Set([...beforeEntity.components.keys(), ...afterEntity.components.keys()]);\n\n      for (const componentId of allComponentIds) {\n        const beforeValue = beforeEntity.components.get(componentId);\n        const afterValue = afterEntity.components.get(componentId);\n\n        if (beforeValue === undefined && afterValue !== undefined) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: undefined,\n            after: afterValue,\n            changeType: \"added\",\n          });\n        } else if (beforeValue !== undefined && afterValue === undefined) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: beforeValue,\n            after: undefined,\n            changeType: \"removed\",\n          });\n        } else if (!deepEquals(beforeValue, afterValue)) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: beforeValue,\n            after: afterValue,\n            changeType: \"modified\",\n          });\n        }\n      }\n    }\n\n    return { addedEntities, removedEntities, componentChanges };\n  },\n\n  /**\n   * Check if two snapshots are equal\n   */\n  equals(a: WorldSnapshot, b: WorldSnapshot): boolean {\n    const diff = this.compare(a, b);\n    return diff.addedEntities.length === 0 && diff.removedEntities.length === 0 && diff.componentChanges.length === 0;\n  },\n};\n\n// =============================================================================\n// Utilities\n// =============================================================================\n\n/**\n * Custom assertion error for testing utilities\n */\nexport class AssertionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"AssertionError\";\n  }\n}\n\n/**\n * Deep equality check for comparing component values\n */\nfunction deepEquals(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (a === null || b === null) return false;\n  if (typeof a !== typeof b) return false;\n\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) return false;\n    for (let i = 0; i < a.length; i++) {\n      if (!deepEquals(a[i], b[i])) return false;\n    }\n    return true;\n  }\n\n  if (typeof a === \"object\" && typeof b === \"object\") {\n    const aObj = a as Record<string, unknown>;\n    const bObj = b as Record<string, unknown>;\n    const aKeys = Object.keys(aObj);\n    const bKeys = Object.keys(bObj);\n\n    if (aKeys.length !== bKeys.length) return false;\n\n    for (const key of aKeys) {\n      if (!Object.prototype.hasOwnProperty.call(bObj, key)) return false;\n      if (!deepEquals(aObj[key], bObj[key])) return false;\n    }\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Deep clone a value for snapshot isolation\n */\nfunction deepClone<T>(value: T): T {\n  if (value === null || typeof value !== \"object\") {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map(deepClone) as T;\n  }\n\n  const result: Record<string, unknown> = {};\n  for (const key of Object.keys(value)) {\n    result[key] = deepClone((value as Record<string, unknown>)[key]);\n  }\n  return result as T;\n}\n\n// =============================================================================\n// Re-exports for convenience\n// =============================================================================\n\nexport { component, relation } from \"../core/entity\";\nexport type { ComponentId, EntityId, RelationId, WildcardRelationId } from \"../core/entity\";\nexport type { LifecycleCallback, LifecycleHook, MultiLifecycleCallback, MultiLifecycleHook } from \"../core/types\";\nexport { World } from \"../core/world\";\nexport type { Query } from \"../query/query\";\n"],"mappings":"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"}
+{"version":3,"file":"testing.mjs","names":["entitySnapshots: EntitySnapshot[]","addedEntities: EntityId[]","removedEntities: EntityId[]","componentChanges: SnapshotDiff[\"componentChanges\"]","result: Record<string, unknown>"],"sources":["../src/testing/index.ts"],"sourcesContent":["/**\n * @module testing\n * Testing utilities for ECS-based game logic\n *\n * This module provides framework-agnostic testing helpers that work with\n * bun:test, vitest, jest, or any other testing framework.\n *\n * @example\n * ```typescript\n * import { describe, expect, it } from \"bun:test\";\n * import { component } from \"@codehz/ecs\";\n * import { WorldFixture, EntityBuilder, Assertions } from \"@codehz/ecs/testing\";\n *\n * const PositionId = component<{ x: number; y: number }>();\n * const VelocityId = component<{ x: number; y: number }>();\n *\n * describe(\"Movement System\", () => {\n *   it(\"should update position based on velocity\", () => {\n *     const fixture = new WorldFixture();\n *     const entity = fixture\n *       .spawn()\n *       .with(PositionId, { x: 0, y: 0 })\n *       .with(VelocityId, { x: 1, y: 2 })\n *       .build();\n *\n *     // Run your game logic here\n *     movementSystem(fixture.world, 1.0);\n *\n *     expect(Assertions.hasComponent(fixture.world, entity, PositionId)).toBe(true);\n *     expect(Assertions.getComponent(fixture.world, entity, PositionId)).toEqual({ x: 1, y: 2 });\n *   });\n * });\n * ```\n */\n\nimport type { ComponentId, EntityId, WildcardRelationId } from \"../core/entity\";\nimport { isWildcardRelationId, relation } from \"../core/entity\";\nimport { World } from \"../core/world\";\nimport type { Query } from \"../query/query\";\nexport { EntityBuilder } from \"../core/builder\";\nexport type { ComponentDef } from \"../core/builder\";\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * A component definition for entity building, supporting both regular components and relations\n */\nimport type { EntityBuilder } from \"../core/builder\";\n\n/**\n * Snapshot of a single entity's component state\n */\nexport interface EntitySnapshot {\n  entity: EntityId;\n  components: Map<EntityId<any>, unknown>;\n}\n\n/**\n * Snapshot of multiple entities' component state\n */\nexport interface WorldSnapshot {\n  entities: EntitySnapshot[];\n}\n\n/**\n * Result of comparing two snapshots\n */\nexport interface SnapshotDiff {\n  /** Entities that exist in 'after' but not in 'before' */\n  addedEntities: EntityId[];\n  /** Entities that exist in 'before' but not in 'after' */\n  removedEntities: EntityId[];\n  /** Changes to components on existing entities */\n  componentChanges: Array<{\n    entity: EntityId;\n    componentId: EntityId<any>;\n    before: unknown | undefined;\n    after: unknown | undefined;\n    changeType: \"added\" | \"removed\" | \"modified\";\n  }>;\n}\n\n// =============================================================================\n// WorldFixture - Test World Factory\n// =============================================================================\n\n/**\n * A test fixture that manages a World instance and provides convenient\n * methods for setting up test scenarios.\n *\n * @example\n * ```typescript\n * const fixture = new WorldFixture();\n *\n * // Spawn entities with fluent API\n * const player = fixture\n *   .spawn()\n *   .with(PositionId, { x: 0, y: 0 })\n *   .with(HealthId, { current: 100, max: 100 })\n *   .build();\n *\n * // Access the world for running systems\n * movementSystem(fixture.world);\n *\n * // Clean up (optional - creates a fresh world)\n * fixture.reset();\n * ```\n */\nexport class WorldFixture {\n  private _world: World;\n  private _queries: Query[] = [];\n\n  constructor() {\n    this._world = new World();\n  }\n\n  /**\n   * Get the underlying World instance\n   */\n  get world(): World {\n    return this._world;\n  }\n\n  /**\n   * Create a new EntityBuilder for spawning an entity with components\n   */\n  spawn(): EntityBuilder {\n    return this._world.spawn();\n  }\n\n  /**\n   * Spawn multiple entities with the same component configuration\n   * @param count Number of entities to spawn\n   * @param configure Function to configure each entity builder\n   * @returns Array of created entity IDs\n   */\n  spawnMany(count: number, configure: (builder: EntityBuilder, index: number) => EntityBuilder): EntityId[] {\n    return this._world.spawnMany(count, configure);\n  }\n\n  /**\n   * Create a query and track it for automatic cleanup\n   * @param componentTypes Component types to query for\n   * @returns Query instance\n   */\n  createQuery(componentTypes: EntityId<any>[]): Query {\n    const query = this._world.createQuery(componentTypes);\n    this._queries.push(query);\n    return query;\n  }\n\n  /**\n   * Execute pending commands (alias for world.sync())\n   */\n  sync(): void {\n    this._world.sync();\n  }\n\n  /**\n   * Reset the fixture with a fresh World instance\n   * Disposes all tracked queries\n   */\n  reset(): void {\n    for (const query of this._queries) {\n      query.dispose();\n    }\n    this._queries = [];\n    this._world = new World();\n  }\n\n  /**\n   * Capture a snapshot of specified entities and their components\n   * @param entities Entities to capture\n   * @param componentIds Components to include in the snapshot\n   */\n  captureSnapshot(entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot {\n    return Snapshot.capture(this._world, entities, componentIds);\n  }\n\n  /**\n   * Symbol.dispose implementation for automatic resource management\n   */\n  [Symbol.dispose](): void {\n    this.reset();\n  }\n}\n\n// =============================================================================\n// EntityBuilder - Fluent Entity Creation\n// =============================================================================\n\n/**\n * Fluent builder for creating entities with components.\n * Supports both regular components and entity relations.\n *\n * @example\n * ```typescript\n * // Basic usage\n * // Note: build() will enqueue component commands but will NOT call world.sync().\n * // You must call world.sync() or fixture.sync() manually to apply commands.\n * const entity = new EntityBuilder(world)\n *   .with(PositionId, { x: 10, y: 20 })\n *   .with(VelocityId, { x: 1, y: 0 })\n *   .build();\n *   // Apply pending changes\n *   world.sync();\n *\n * // With relations\n * const child = new EntityBuilder(world)\n *   .with(PositionId, { x: 0, y: 0 })\n *   .withRelation(ParentId, parentEntity, { offset: { x: 5, y: 5 } })\n *   .build();\n *   world.sync();\n *\n * // Tag component (void type)\n * const tagged = new EntityBuilder(world)\n *   .withTag(PlayerTagId)\n *   .build();\n * ```\n */\n// EntityBuilder is exported from world.ts; testing utilities will use world.spawn()\n\n// =============================================================================\n// Assertions - Test Assertion Helpers\n// =============================================================================\n\n/**\n * Test assertion utilities that return boolean values or throw descriptive errors.\n * These work with any testing framework's expect() function.\n *\n * @example\n * ```typescript\n * // With bun:test or vitest\n * expect(Assertions.hasComponent(world, entity, PositionId)).toBe(true);\n * expect(Assertions.getComponent(world, entity, PositionId)).toEqual({ x: 10, y: 20 });\n *\n * // Direct assertion (throws on failure)\n * Assertions.assertHasComponent(world, entity, PositionId);\n * Assertions.assertComponentEquals(world, entity, PositionId, { x: 10, y: 20 });\n * ```\n */\nexport const Assertions = {\n  /**\n   * Check if an entity has a specific component\n   */\n  hasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean {\n    return world.exists(entity) && world.has(entity, componentId);\n  },\n\n  /**\n   * Check if an entity does not have a specific component\n   */\n  lacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean {\n    return !world.exists(entity) || !world.has(entity, componentId);\n  },\n\n  /**\n   * Get a component value (returns undefined if entity doesn't exist or doesn't have the component)\n   */\n  getComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): T | undefined {\n    if (!world.exists(entity) || !world.has(entity, componentId)) {\n      return undefined;\n    }\n    return world.get(entity, componentId);\n  },\n\n  /**\n   * Get all relation instances for a wildcard relation\n   */\n  getRelations<T>(world: World, entity: EntityId, componentId: ComponentId<T>): [EntityId<unknown>, T][] | undefined {\n    if (!world.exists(entity)) {\n      return undefined;\n    }\n    const wildcardId = relation(componentId, \"*\");\n    try {\n      return world.get(entity, wildcardId);\n    } catch {\n      return [];\n    }\n  },\n\n  /**\n   * Check if an entity has a relation to a specific target\n   */\n  hasRelation<T>(world: World, entity: EntityId, componentId: ComponentId<T>, targetEntity: EntityId<any>): boolean {\n    if (!world.exists(entity)) {\n      return false;\n    }\n    const relationId = relation(componentId, targetEntity);\n    return world.has(entity, relationId);\n  },\n\n  /**\n   * Check if an entity exists in the world\n   */\n  entityExists(world: World, entity: EntityId): boolean {\n    return world.exists(entity);\n  },\n\n  /**\n   * Check if a query contains specific entities\n   */\n  queryContains(query: Query, ...entities: EntityId[]): boolean {\n    const queryEntities = query.getEntities();\n    return entities.every((e) => queryEntities.includes(e));\n  },\n\n  /**\n   * Check if a query contains exactly the specified entities (no more, no less)\n   */\n  queryContainsExactly(query: Query, ...entities: EntityId[]): boolean {\n    const queryEntities = query.getEntities();\n    if (queryEntities.length !== entities.length) {\n      return false;\n    }\n    return entities.every((e) => queryEntities.includes(e));\n  },\n\n  /**\n   * Get the count of entities in a query\n   */\n  queryCount(query: Query): number {\n    return query.getEntities().length;\n  },\n\n  // === Throwing assertions ===\n\n  /**\n   * Assert that an entity has a component (throws if not)\n   */\n  assertHasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void {\n    if (!world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} does not exist`);\n    }\n    if (!world.has(entity, componentId)) {\n      throw new AssertionError(`Entity ${entity} does not have component ${componentId}`);\n    }\n  },\n\n  /**\n   * Assert that an entity lacks a component (throws if it has the component)\n   */\n  assertLacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void {\n    if (world.exists(entity) && world.has(entity, componentId)) {\n      throw new AssertionError(`Entity ${entity} unexpectedly has component ${componentId}`);\n    }\n  },\n\n  /**\n   * Assert that a component equals an expected value (throws if not)\n   */\n  assertComponentEquals<T>(world: World, entity: EntityId, componentId: EntityId<T>, expected: T): void {\n    this.assertHasComponent(world, entity, componentId);\n    const actual = world.get(entity, componentId);\n    if (!deepEquals(actual, expected)) {\n      throw new AssertionError(\n        `Component ${componentId} on entity ${entity} does not match expected value.\\n` +\n          `Expected: ${JSON.stringify(expected)}\\n` +\n          `Actual: ${JSON.stringify(actual)}`,\n      );\n    }\n  },\n\n  /**\n   * Assert that an entity exists (throws if not)\n   */\n  assertEntityExists(world: World, entity: EntityId): void {\n    if (!world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} does not exist`);\n    }\n  },\n\n  /**\n   * Assert that an entity does not exist (throws if it exists)\n   */\n  assertEntityNotExists(world: World, entity: EntityId): void {\n    if (world.exists(entity)) {\n      throw new AssertionError(`Entity ${entity} unexpectedly exists`);\n    }\n  },\n\n  /**\n   * Assert that a query contains specific entities (throws if not)\n   */\n  assertQueryContains(query: Query, ...entities: EntityId[]): void {\n    const queryEntities = query.getEntities();\n    for (const entity of entities) {\n      if (!queryEntities.includes(entity)) {\n        throw new AssertionError(\n          `Query does not contain entity ${entity}.\\n` + `Query entities: [${queryEntities.join(\", \")}]`,\n        );\n      }\n    }\n  },\n\n  /**\n   * Assert that a query does not contain specific entities (throws if it does)\n   */\n  assertQueryNotContains(query: Query, ...entities: EntityId[]): void {\n    const queryEntities = query.getEntities();\n    for (const entity of entities) {\n      if (queryEntities.includes(entity)) {\n        throw new AssertionError(\n          `Query unexpectedly contains entity ${entity}.\\n` + `Query entities: [${queryEntities.join(\", \")}]`,\n        );\n      }\n    }\n  },\n};\n\n// =============================================================================\n// Snapshot - State Capture and Comparison\n// =============================================================================\n\n/**\n * Utilities for capturing and comparing world state snapshots.\n * Useful for testing that systems produce expected state changes.\n *\n * @example\n * ```typescript\n * const before = Snapshot.capture(world, [entity], [PositionId, VelocityId]);\n *\n * // Run game logic\n * movementSystem(world, deltaTime);\n * world.sync();\n *\n * const after = Snapshot.capture(world, [entity], [PositionId, VelocityId]);\n * const diff = Snapshot.compare(before, after);\n *\n * expect(diff.componentChanges).toHaveLength(1);\n * expect(diff.componentChanges[0].changeType).toBe(\"modified\");\n * ```\n */\nexport const Snapshot = {\n  /**\n   * Capture a snapshot of specified entities and their components\n   * @param world The world to capture from\n   * @param entities Entities to include in the snapshot\n   * @param componentIds Components to capture for each entity\n   */\n  capture(world: World, entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot {\n    const entitySnapshots: EntitySnapshot[] = [];\n\n    for (const entity of entities) {\n      if (!world.exists(entity)) {\n        continue;\n      }\n\n      const components = new Map<EntityId<any>, unknown>();\n\n      for (const componentId of componentIds) {\n        if (isWildcardRelationId(componentId)) {\n          // For wildcard relations, capture all relation instances\n          try {\n            const relations = world.get(entity, componentId as WildcardRelationId<any>);\n            if (relations && relations.length > 0) {\n              components.set(componentId, deepClone(relations));\n            }\n          } catch {\n            // Entity doesn't have this relation type\n          }\n        } else if (world.has(entity, componentId)) {\n          components.set(componentId, deepClone(world.get(entity, componentId)));\n        }\n      }\n\n      entitySnapshots.push({ entity, components });\n    }\n\n    return { entities: entitySnapshots };\n  },\n\n  /**\n   * Compare two snapshots and return the differences\n   * @param before The 'before' snapshot\n   * @param after The 'after' snapshot\n   */\n  compare(before: WorldSnapshot, after: WorldSnapshot): SnapshotDiff {\n    const beforeEntities = new Set(before.entities.map((e) => e.entity));\n    const afterEntities = new Set(after.entities.map((e) => e.entity));\n\n    const addedEntities: EntityId[] = [];\n    const removedEntities: EntityId[] = [];\n    const componentChanges: SnapshotDiff[\"componentChanges\"] = [];\n\n    // Find added entities\n    for (const entity of afterEntities) {\n      if (!beforeEntities.has(entity)) {\n        addedEntities.push(entity);\n      }\n    }\n\n    // Find removed entities\n    for (const entity of beforeEntities) {\n      if (!afterEntities.has(entity)) {\n        removedEntities.push(entity);\n      }\n    }\n\n    // Find component changes on existing entities\n    const beforeMap = new Map(before.entities.map((e) => [e.entity, e]));\n    const afterMap = new Map(after.entities.map((e) => [e.entity, e]));\n\n    for (const entity of beforeEntities) {\n      if (!afterEntities.has(entity)) continue; // Skip removed entities\n\n      const beforeEntity = beforeMap.get(entity)!;\n      const afterEntity = afterMap.get(entity)!;\n\n      // Check for component changes\n      const allComponentIds = new Set([...beforeEntity.components.keys(), ...afterEntity.components.keys()]);\n\n      for (const componentId of allComponentIds) {\n        const beforeValue = beforeEntity.components.get(componentId);\n        const afterValue = afterEntity.components.get(componentId);\n\n        if (beforeValue === undefined && afterValue !== undefined) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: undefined,\n            after: afterValue,\n            changeType: \"added\",\n          });\n        } else if (beforeValue !== undefined && afterValue === undefined) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: beforeValue,\n            after: undefined,\n            changeType: \"removed\",\n          });\n        } else if (!deepEquals(beforeValue, afterValue)) {\n          componentChanges.push({\n            entity,\n            componentId,\n            before: beforeValue,\n            after: afterValue,\n            changeType: \"modified\",\n          });\n        }\n      }\n    }\n\n    return { addedEntities, removedEntities, componentChanges };\n  },\n\n  /**\n   * Check if two snapshots are equal\n   */\n  equals(a: WorldSnapshot, b: WorldSnapshot): boolean {\n    const diff = this.compare(a, b);\n    return diff.addedEntities.length === 0 && diff.removedEntities.length === 0 && diff.componentChanges.length === 0;\n  },\n};\n\n// =============================================================================\n// Utilities\n// =============================================================================\n\n/**\n * Custom assertion error for testing utilities\n */\nexport class AssertionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"AssertionError\";\n  }\n}\n\n/**\n * Deep equality check for comparing component values\n */\nfunction deepEquals(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n  if (a === null || b === null) return false;\n  if (typeof a !== typeof b) return false;\n\n  if (Array.isArray(a) && Array.isArray(b)) {\n    if (a.length !== b.length) return false;\n    for (let i = 0; i < a.length; i++) {\n      if (!deepEquals(a[i], b[i])) return false;\n    }\n    return true;\n  }\n\n  if (typeof a === \"object\" && typeof b === \"object\") {\n    const aObj = a as Record<string, unknown>;\n    const bObj = b as Record<string, unknown>;\n    const aKeys = Object.keys(aObj);\n    const bKeys = Object.keys(bObj);\n\n    if (aKeys.length !== bKeys.length) return false;\n\n    for (const key of aKeys) {\n      if (!Object.prototype.hasOwnProperty.call(bObj, key)) return false;\n      if (!deepEquals(aObj[key], bObj[key])) return false;\n    }\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Deep clone a value for snapshot isolation\n */\nfunction deepClone<T>(value: T): T {\n  if (value === null || typeof value !== \"object\") {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map(deepClone) as T;\n  }\n\n  const result: Record<string, unknown> = {};\n  for (const key of Object.keys(value)) {\n    result[key] = deepClone((value as Record<string, unknown>)[key]);\n  }\n  return result as T;\n}\n\n// =============================================================================\n// Re-exports for convenience\n// =============================================================================\n\nexport { component, relation } from \"../core/entity\";\nexport type { ComponentId, EntityId, RelationId, WildcardRelationId } from \"../core/entity\";\nexport type {\n  LegacyLifecycleCallback as LifecycleCallback,\n  LegacyLifecycleHook as LifecycleHook,\n  LifecycleCallback as MultiLifecycleCallback,\n  LifecycleHook as MultiLifecycleHook,\n} from \"../core/types\";\nexport { World } from \"../core/world\";\nexport type { Query } from \"../query/query\";\n"],"mappings":"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"}

package/world.mjs

@@ -1039,6 +1039,13 @@ var Archetype = class {
 	/**
 	* Cache for pre-computed component data sources to avoid repeated calculations
 	*/
+	/**
+	* Multi-hooks that match this archetype
+	*/
+	matchingMultiHooks = /* @__PURE__ */ new Set();
+	/**
+	* Cache for pre-computed component data sources to avoid repeated calculations
+	*/
 	componentDataSourcesCache = /* @__PURE__ */ new Map();
 	constructor(componentTypes, dontFragmentRelations) {
 		this.componentTypes = [...componentTypes].sort((a, b) => a - b);
@@ -1406,10 +1413,16 @@ function applyChangeset(ctx, entityId, currentArchetype, changeset, entityToArch
 	const allCurrentComponentTypes = currentEntityData ? Array.from(currentEntityData.keys()) : currentArchetype.componentTypes;
 	const finalComponentTypes = changeset.getFinalComponentTypes(allCurrentComponentTypes);
 	const removedComponents = /* @__PURE__ */ new Map();
-	if (finalComponentTypes) if (!areComponentTypesEqual(filterRegularComponentTypes(allCurrentComponentTypes), filterRegularComponentTypes(finalComponentTypes))) moveEntityToNewArchetype(ctx, entityId, currentArchetype, finalComponentTypes, changeset, removedComponents, entityToArchetype);
+	if (finalComponentTypes) if (!areComponentTypesEqual(filterRegularComponentTypes(allCurrentComponentTypes), filterRegularComponentTypes(finalComponentTypes))) return {
+		removedComponents,
+		newArchetype: moveEntityToNewArchetype(ctx, entityId, currentArchetype, finalComponentTypes, changeset, removedComponents, entityToArchetype)
+	};
 	else updateEntityInSameArchetype(ctx, entityId, currentArchetype, changeset, removedComponents);
 	else updateEntityInSameArchetype(ctx, entityId, currentArchetype, changeset, removedComponents);
-	return removedComponents;
+	return {
+		removedComponents,
+		newArchetype: currentArchetype
+	};
 }
 function moveEntityToNewArchetype(ctx, entityId, currentArchetype, finalComponentTypes, changeset, removedComponents, entityToArchetype) {
 	const newArchetype = ctx.ensureArchetype(finalComponentTypes);
@@ -1417,6 +1430,7 @@ function moveEntityToNewArchetype(ctx, entityId, currentArchetype, finalComponen
 	for (const componentType of changeset.removes) removedComponents.set(componentType, currentComponents.get(componentType));
 	newArchetype.addEntity(entityId, changeset.applyTo(currentComponents));
 	entityToArchetype.set(entityId, newArchetype);
+	return newArchetype;
 }
 function updateEntityInSameArchetype(ctx, entityId, currentArchetype, changeset, removedComponents) {
 	applyDontFragmentChanges(ctx.dontFragmentRelations, entityId, changeset, removedComponents);
@@ -1466,10 +1480,38 @@ function areComponentTypesEqual(types1, types2) {
 
 //#endregion
 //#region src/core/world-hooks.ts
-function triggerLifecycleHooks(ctx, entityId, addedComponents, removedComponents) {
+/**
+* Check if a component change matches a hook component type.
+* Handles wildcard-relation matching: if hookComponent is a wildcard relation (e.g., relation(A, "*")),
+* it matches any concrete relation with the same component ID (e.g., relation(A, entity1)).
+*/
+function componentMatchesHookType(changedComponent, hookComponent) {
+	if (changedComponent === hookComponent) return true;
+	if (isWildcardRelationId(hookComponent)) {
+		const hookComponentId = getComponentIdFromRelationId(hookComponent);
+		const changedComponentId = getComponentIdFromRelationId(changedComponent);
+		if (hookComponentId !== void 0 && changedComponentId !== void 0) return hookComponentId === changedComponentId;
+	}
+	return false;
+}
+/**
+* Check if any component in the changes map matches a hook component type.
+*/
+function anyComponentMatches(changes, hookComponent) {
+	for (const changedComponent of changes.keys()) if (componentMatchesHookType(changedComponent, hookComponent)) return true;
+	return false;
+}
+/**
+* Find a matching component in the changes map that matches the hook component type.
+* Returns [componentId, value] if found, undefined otherwise.
+*/
+function findMatchingComponent(changes, hookComponent) {
+	for (const [changedComponent, value] of changes.entries()) if (componentMatchesHookType(changedComponent, hookComponent)) return [changedComponent, value];
+}
+function triggerLifecycleHooks(ctx, entityId, addedComponents, removedComponents, oldArchetype, newArchetype) {
 	invokeHooksForComponents(ctx.hooks, entityId, addedComponents, "on_set");
 	invokeHooksForComponents(ctx.hooks, entityId, removedComponents, "on_remove");
-	triggerMultiComponentHooks(ctx, entityId, addedComponents, removedComponents);
+	triggerMultiComponentHooks(ctx, entityId, addedComponents, removedComponents, oldArchetype, newArchetype);
 }
 function invokeHooksForComponents(hooks, entityId, components, hookType) {
 	for (const [componentType, component$1] of components) {
@@ -1482,20 +1524,42 @@ function invokeHooksForComponents(hooks, entityId, components, hookType) {
 		}
 	}
 }
-function triggerMultiComponentHooks(ctx, entityId, addedComponents, removedComponents) {
-	for (const { componentTypes, requiredComponents, optionalComponents, hook } of ctx.multiHooks) {
-		const anyRequiredAdded = requiredComponents.some((c) => addedComponents.has(c));
-		const anyOptionalAdded = optionalComponents.some((c) => addedComponents.has(c));
-		const anyRequiredRemoved = requiredComponents.some((c) => removedComponents.has(c));
-		if ((anyRequiredAdded || anyOptionalAdded) && hook.on_set && entityHasAllComponents(ctx, entityId, requiredComponents)) hook.on_set(entityId, componentTypes, collectMultiHookComponents(ctx, entityId, componentTypes));
-		if (anyRequiredRemoved && hook.on_remove && entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removedComponents)) hook.on_remove(entityId, componentTypes, collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents));
+function triggerMultiComponentHooks(ctx, entityId, addedComponents, removedComponents, oldArchetype, newArchetype) {
+	if (addedComponents.size > 0) for (const entry of newArchetype.matchingMultiHooks) {
+		const { hook, requiredComponents, optionalComponents, componentTypes } = entry;
+		if (!hook.on_set) continue;
+		const anyRequiredAdded = requiredComponents.some((c) => anyComponentMatches(addedComponents, c));
+		const anyOptionalAdded = optionalComponents.some((c) => anyComponentMatches(addedComponents, c));
+		if ((anyRequiredAdded || anyOptionalAdded) && entityHasAllComponents(ctx, entityId, requiredComponents)) hook.on_set(entityId, ...collectMultiHookComponents(ctx, entityId, componentTypes));
+	}
+	if (removedComponents.size > 0) for (const entry of oldArchetype.matchingMultiHooks) {
+		const { hook, requiredComponents, componentTypes } = entry;
+		if (!hook.on_remove) continue;
+		if (requiredComponents.some((c) => anyComponentMatches(removedComponents, c)) && entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removedComponents)) hook.on_remove(entityId, ...collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, removedComponents));
 	}
 }
 function entityHasAllComponents(ctx, entityId, requiredComponents) {
-	return requiredComponents.every((c) => ctx.has(entityId, c));
+	return requiredComponents.every((c) => {
+		if (isWildcardRelationId(c)) try {
+			const wildcardData = ctx.get(entityId, c);
+			return Array.isArray(wildcardData) && wildcardData.length > 0;
+		} catch {
+			return false;
+		}
+		return ctx.has(entityId, c);
+	});
 }
 function entityHadAllComponentsBefore(ctx, entityId, requiredComponents, removedComponents) {
-	return requiredComponents.every((c) => removedComponents.has(c) || ctx.has(entityId, c));
+	return requiredComponents.every((c) => {
+		if (anyComponentMatches(removedComponents, c)) return true;
+		if (isWildcardRelationId(c)) try {
+			const wildcardData = ctx.get(entityId, c);
+			return Array.isArray(wildcardData) && wildcardData.length > 0;
+		} catch {
+			return false;
+		}
+		return ctx.has(entityId, c);
+	});
 }
 function collectMultiHookComponents(ctx, entityId, componentTypes) {
 	return componentTypes.map((ct) => isOptionalEntityId(ct) ? ctx.getOptional(entityId, ct.optional) : ctx.get(entityId, ct));
@@ -1504,10 +1568,12 @@ function collectMultiHookComponentsWithRemoved(ctx, entityId, componentTypes, re
 	return componentTypes.map((ct) => {
 		if (isOptionalEntityId(ct)) {
 			const optionalId = ct.optional;
-			return removedComponents.has(optionalId) ? { value: removedComponents.get(optionalId) } : ctx.getOptional(entityId, optionalId);
+			const match$1 = findMatchingComponent(removedComponents, optionalId);
+			return match$1 ? { value: match$1[1] } : ctx.getOptional(entityId, optionalId);
 		}
 		const compId = ct;
-		return removedComponents.has(compId) ? removedComponents.get(compId) : ctx.get(entityId, compId);
+		const match = findMatchingComponent(removedComponents, compId);
+		return match ? match[1] : ctx.get(entityId, compId);
 	});
 }
 
@@ -1614,8 +1680,8 @@ var World = class {
 	queries = [];
 	queryCache = /* @__PURE__ */ new Map();
 	commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
-	hooks = /* @__PURE__ */ new Map();
-	multiHooks = /* @__PURE__ */ new Set();
+	legacyHooks = /* @__PURE__ */ new Map();
+	hooks = /* @__PURE__ */ new Set();
 	constructor(snapshot) {
 		if (snapshot && typeof snapshot === "object") this.deserializeSnapshot(snapshot);
 	}
@@ -1714,16 +1780,20 @@ var World = class {
 	getOptional(entityId, componentType) {
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
-		if (isWildcardRelationId(componentType)) return void 0;
+		if (isWildcardRelationId(componentType)) {
+			const wildcardData = archetype.get(entityId, componentType);
+			if (Array.isArray(wildcardData) && wildcardData.length > 0) return { value: wildcardData };
+			return;
+		}
 		return archetype.getOptional(entityId, componentType);
 	}
 	hook(componentTypesOrSingle, hook) {
 		if (typeof hook === "function") if (Array.isArray(componentTypesOrSingle)) {
 			const callback = hook;
 			hook = {
-				on_init: (entityId, componentTypes, components) => callback("init", entityId, componentTypes, components),
-				on_set: (entityId, componentTypes, components) => callback("set", entityId, componentTypes, components),
-				on_remove: (entityId, componentTypes, components) => callback("remove", entityId, componentTypes, components)
+				on_init: (entityId, ...components) => callback("init", entityId, ...components),
+				on_set: (entityId, ...components) => callback("set", entityId, ...components),
+				on_remove: (entityId, ...components) => callback("remove", entityId, ...components)
 			};
 		} else {
 			const callback = hook;
@@ -1745,19 +1815,20 @@ var World = class {
 				optionalComponents,
 				hook
 			};
-			this.multiHooks.add(entry);
+			this.hooks.add(entry);
+			for (const archetype of this.archetypes) if (this.archetypeMatchesHook(archetype, entry)) archetype.matchingMultiHooks.add(entry);
 			const multiHook = hook;
 			if (multiHook.on_init !== void 0) {
 				const matchingArchetypes = this.getMatchingArchetypes(requiredComponents);
 				for (const archetype of matchingArchetypes) for (const entityId of archetype.getEntities()) {
 					const components = collectMultiHookComponents(this.createHooksContext(), entityId, componentTypes);
-					multiHook.on_init(entityId, componentTypes, components);
+					multiHook.on_init(entityId, ...components);
 				}
 			}
 		} else {
 			const componentType = componentTypesOrSingle;
-			if (!this.hooks.has(componentType)) this.hooks.set(componentType, /* @__PURE__ */ new Set());
-			this.hooks.get(componentType).add(hook);
+			if (!this.legacyHooks.has(componentType)) this.legacyHooks.set(componentType, /* @__PURE__ */ new Set());
+			this.legacyHooks.get(componentType).add(hook);
 			const singleHook = hook;
 			if (singleHook.on_init !== void 0) this.archetypesByComponent.get(componentType)?.forEach((archetype) => {
 				const entities = archetype.getEntityToIndexMap();
@@ -1772,16 +1843,17 @@ var World = class {
 	}
 	unhook(componentTypesOrSingle, hook) {
 		if (Array.isArray(componentTypesOrSingle)) {
-			for (const entry of this.multiHooks) if (entry.hook === hook) {
-				this.multiHooks.delete(entry);
+			for (const entry of this.hooks) if (entry.hook === hook) {
+				this.hooks.delete(entry);
+				for (const archetype of this.archetypes) archetype.matchingMultiHooks.delete(entry);
 				break;
 			}
 		} else {
 			const componentType = componentTypesOrSingle;
-			const hooks = this.hooks.get(componentType);
+			const hooks = this.legacyHooks.get(componentType);
 			if (hooks) {
 				hooks.delete(hook);
-				if (hooks.size === 0) this.hooks.delete(componentType);
+				if (hooks.size === 0) this.legacyHooks.delete(componentType);
 			}
 		}
 	}
@@ -1880,18 +1952,18 @@ var World = class {
 		processCommands(entityId, currentArchetype, commands, changeset, (eid, arch, compId) => {
 			if (isExclusiveComponent(compId)) removeMatchingRelations(eid, arch, compId, changeset);
 		});
-		const removedComponents = applyChangeset({
+		const { removedComponents, newArchetype } = applyChangeset({
 			dontFragmentRelations: this.dontFragmentRelations,
 			ensureArchetype: (ct) => this.ensureArchetype(ct)
 		}, entityId, currentArchetype, changeset, this.entityToArchetype);
 		this.updateEntityReferences(entityId, changeset);
-		triggerLifecycleHooks(this.createHooksContext(), entityId, changeset.adds, removedComponents);
+		triggerLifecycleHooks(this.createHooksContext(), entityId, changeset.adds, removedComponents, currentArchetype, newArchetype);
 		return changeset;
 	}
 	createHooksContext() {
 		return {
-			hooks: this.hooks,
-			multiHooks: this.multiHooks,
+			hooks: this.legacyHooks,
+			multiHooks: this.hooks,
 			has: (eid, ct) => this.has(eid, ct),
 			get: (eid, ct) => this.get(eid, ct),
 			getOptional: (eid, ct) => this.getOptional(eid, ct)
@@ -1904,12 +1976,12 @@ var World = class {
 		changeset.delete(componentType);
 		maybeRemoveWildcardMarker(entityId, sourceArchetype, componentType, getComponentIdFromRelationId(componentType), changeset);
 		const removedComponent = sourceArchetype.get(entityId, componentType);
-		applyChangeset({
+		const { newArchetype } = applyChangeset({
 			dontFragmentRelations: this.dontFragmentRelations,
 			ensureArchetype: (ct) => this.ensureArchetype(ct)
 		}, entityId, sourceArchetype, changeset, this.entityToArchetype);
 		untrackEntityReference(this.entityReferences, entityId, componentType, targetEntityId);
-		triggerLifecycleHooks(this.createHooksContext(), entityId, /* @__PURE__ */ new Map(), new Map([[componentType, removedComponent]]));
+		triggerLifecycleHooks(this.createHooksContext(), entityId, /* @__PURE__ */ new Map(), new Map([[componentType, removedComponent]]), sourceArchetype, newArchetype);
 	}
 	updateEntityReferences(entityId, changeset) {
 		for (const componentType of changeset.removes) if (isEntityRelation(componentType)) {
@@ -1935,8 +2007,22 @@ var World = class {
 			this.archetypesByComponent.set(componentType, archetypes);
 		}
 		for (const query of this.queries) query.checkNewArchetype(newArchetype);
+		this.updateArchetypeHookMatches(newArchetype);
 		return newArchetype;
 	}
+	updateArchetypeHookMatches(archetype) {
+		for (const entry of this.hooks) if (this.archetypeMatchesHook(archetype, entry)) archetype.matchingMultiHooks.add(entry);
+	}
+	archetypeMatchesHook(archetype, entry) {
+		return entry.requiredComponents.every((c) => {
+			if (isWildcardRelationId(c)) {
+				if (isDontFragmentWildcard(c)) return true;
+				const componentId = getComponentIdFromRelationId(c);
+				return componentId !== void 0 && archetype.hasRelationWithComponentId(componentId);
+			}
+			return archetype.componentTypes.includes(c) || isDontFragmentRelation(c);
+		});
+	}
 	archetypeReferencesEntity(archetype, entityId) {
 		return archetype.componentTypes.some((ct) => ct === entityId || isEntityRelation(ct) && getTargetIdFromRelationId(ct) === entityId);
 	}