@codehz/ecs 0.6.10 → 0.7.0

package/builder.d.mts

@@ -1,4 +1,4 @@
-//#region src/core/entity-types.d.ts
+//#region src/entity/types.d.ts
 /**
  * Unique symbol brand for associating component type information with EntityId
  */
@@ -14,14 +14,53 @@ declare const __entityIdTypeTag: unique symbol;
  * - Entity IDs: 1024+
  * - Relation IDs: negative numbers encoding component and entity associations
  */
+/**
+ * Branded numeric type representing an ECS identifier.
+ *
+ * - {@link ComponentId}: positive values in range `1–1023`
+ * - Entity IDs: values `1024+`
+ * - {@link RelationId}: negative values encoding `(componentId, targetId)`
+ *
+ * @template T - The data type associated with this ID
+ * @template U - Discriminant for the ID kind (e.g. `"component"`, `"entity-relation"`)
+ */
 type EntityId<T = unknown, U$1 = unknown> = number & {
   readonly [__componentTypeMarker]: T;
   readonly [__entityIdTypeTag]: U$1;
 };
+/**
+ * Component identifier. Valid values are `1` through `1023`.
+ * Created with {@link component}.
+ *
+ * @template T - The data type stored by this component (`void` for tag components)
+ */
 type ComponentId<T = void> = EntityId<T, "component">;
+/**
+ * Relation identifier targeting an entity.
+ * Created with {@link relation}.
+ *
+ * @template T - The data type stored by this relation
+ */
 type EntityRelationId<T = void> = EntityId<T, "entity-relation">;
+/**
+ * Relation identifier targeting another component (singleton relation).
+ * Created with {@link relation}.
+ *
+ * @template T - The data type stored by this relation
+ */
 type ComponentRelationId<T = void> = EntityId<T, "component-relation">;
+/**
+ * Wildcard relation identifier used to query all targets of a given relation component.
+ * Created with `relation(componentId, "*")`.
+ *
+ * @template T - The data type stored by the relation
+ */
 type WildcardRelationId<T = void> = EntityId<T, "wildcard-relation">;
+/**
+ * Union of all relation identifier kinds.
+ *
+ * @template T - The data type stored by the relation
+ */
 type RelationId<T = void> = EntityRelationId<T> | ComponentRelationId<T> | WildcardRelationId<T>;
 /**
  * Check if an ID is a component ID
@@ -36,20 +75,42 @@ declare function isEntityId<T>(id: EntityId<T>): id is EntityId<T>;
  */
 declare function isRelationId<T>(id: EntityId<T>): id is RelationId<T>;
 //#endregion
-//#region src/core/entity-relation.d.ts
+//#region src/entity/relation.d.ts
 /**
  * Type for relation ID based on component and target types
  */
 type RelationIdType<T, R> = R extends ComponentId<infer U> ? U extends void ? ComponentRelationId<T> : ComponentRelationId<T extends void ? U : T> : R extends EntityId<any> ? EntityRelationId<T> : never;
 /**
- * Create a relation ID by associating a component with another ID (entity or component)
- * @param componentId The component ID (0-1023)
- * @param targetId The target ID (entity, component, or '*' for wildcard)
+ * Create a relation ID by associating a component with a target entity, component, or wildcard.
+ *
+ * Relations are encoded as negative numbers and can be used anywhere a regular component ID is accepted.
+ * Use `"*"` as the target to create a wildcard relation for querying all targets of a given relation type.
+ *
+ * @param componentId - The base component ID (must be a valid component)
+ * @param targetId - The target entity ID, component ID, or `"*"` for wildcard
+ * @returns A relation ID that encodes both the component and target
+ *
+ * @throws {Error} If `componentId` is not a valid component ID
+ * @throws {Error} If `targetId` is not a valid entity, component, or `"*"`
+ *
+ * @example
+ * const ChildOf = component();
+ * const parent = world.new();
+ *
+ * // Entity relation
+ * const childRelation = relation(ChildOf, parent);
+ * world.set(child, childRelation);
+ *
+ * // Wildcard relation (queries all targets)
+ * const allChildren = world.createQuery([relation(ChildOf, "*")]);
  */
 declare function relation<T>(componentId: ComponentId<T>, targetId: "*"): WildcardRelationId<T>;
 declare function relation<T, R extends EntityId<any>>(componentId: ComponentId<T>, targetId: R): RelationIdType<T, R>;
 /**
- * Check if an ID is a wildcard relation id
+ * Check if an ID is a wildcard relation (created with `relation(componentId, "*")`).
+ *
+ * @param id - The ID to check
+ * @returns `true` if the ID is a wildcard relation, `false` otherwise
  */
 declare function isWildcardRelationId<T>(id: EntityId<T>): id is WildcardRelationId<T>;
 /**
@@ -63,39 +124,306 @@ declare function decodeRelationId(relationId: RelationId<any>): {
   type: "entity" | "component" | "wildcard";
 };
 //#endregion
-//#region src/core/component-registry.d.ts
+//#region src/component/registry.d.ts
+/**
+ * Merge function type for combining repeated `set()` values within a single sync batch.
+ *
+ * When `world.set(entity, componentType, value)` is called **multiple times** for the
+ * same entity and same component type **before** the next `world.sync()`, the merge
+ * callback is invoked to combine the values instead of simply overwriting. This allows
+ * additive or custom composition of component data in a single frame.
+ *
+ * @typeParam T - The component's value type.
+ *
+ * @param prev - The value from the **previous** `set()` call (or the merged result of
+ *   earlier calls) for this entity/componentType pair within the current sync batch.
+ * @param next - The value from the **current** `set()` call being processed.
+ *
+ * @returns The merged value to be stored. This becomes `prev` if another `set()` for
+ *   the same entity and componentType is encountered later in the same batch.
+ *
+ * @remarks
+ * **Idempotency**: Merge functions **must be idempotent**. The ECS does not guarantee
+ * that `world.sync()` won't be called multiple times in edge cases (e.g., intermediate
+ * syncs during pipeline execution), so the merge result should not depend on call
+ * count or non-deterministic state.
+ *
+ * **Single-batch scope**: Merging only applies to `set()` calls within the **same sync
+ * batch** (i.e., between two `world.sync()` calls). After `world.sync()`, the component
+ * value is committed to storage, and the next `set()` starts with a fresh `prev` value.
+ *
+ * @example
+ * ```ts
+ * // Accumulate damage events in a single frame
+ * const DamageEvents = component<DamageEvent[]>({
+ *   merge: (prev, next) => [...prev, ...next],
+ * });
+ *
+ * world.set(player, DamageEvents, [{ source: "fire", amount: 10 }]);
+ * world.set(player, DamageEvents, [{ source: "ice", amount: 5 }]);
+ * // After sync: player has [{ source: "fire", amount: 10 }, { source: "ice", amount: 5 }]
+ * ```
+ */
 type ComponentMerge<T = any> = (prev: T, next: T) => T;
 /**
  * Component options that define intrinsic properties
  */
 interface ComponentOptions<T = any> {
   /**
-   * Optional name for the component (for serialization/debugging)
+   * An optional human-readable name for the component, used for debugging and
+   * serialization.
+   *
+   * While `name` is **optional** at registration time, omitting it can cause
+   * problems when serializing and later deserializing the world:
+   *
+   * 1. **Cross-session portability**: Without a name, the component is
+   *    serialized as a raw numeric ID. Component IDs are allocated sequentially
+   *    at registration time, so if the order of `component()` calls changes
+   *    between sessions (e.g. due to code refactoring, lazy-loading, or
+   *    tree-shaking), those numeric IDs will no longer point to the same
+   *    component type, leading to **silent data corruption** on restore.
+   *
+   * 2. **Runtime warnings**: `encodeEntityId` logs a `console.warn` for every
+   *    unnamed component it encounters during `world.serialize()`, which can be
+   *    noisy in production when serialization is used for save-games or
+   *    snapshots.
+   *
+   * 3. **Debugging ergonomics**: Named components make serialized snapshots
+   *    human-readable (e.g. `"Position"` instead of `42`), which is invaluable
+   *    when inspecting save files or network dumps.
+   *
+   * **Recommendation**: Always provide a `name` for any component that may
+   * appear in a serialized world — even if it's just the same string as the
+   * variable name.
+   *
+   * @example
+   * ```ts
+   * // ✅ Good: explicit name ensures stable serialization
+   * const Position = component<{ x: number; y: number }>({ name: "Position" });
+   *
+   * // ⚠️ Risky: no name — serialization falls back to numeric ID
+   * const Velocity = component<{ dx: number; dy: number }>();
+   * ```
    */
   name?: string;
   /**
-   * If true, an entity can have at most one relation per base component.
-   * When adding a new relation with the same base component, any existing relations
-   * with that base component are automatically removed.
-   * Only applicable to relation components.
+   * If `true`, an entity can have **at most one** relation per base component type.
+   * When a new relation with the same base component is added, any existing relations
+   * with that base component are **automatically removed** before the new one is applied.
+   *
+   * **Only applicable to relation components** — components used via
+   * `relation(componentId, target)`. Regular (non-relation) components ignore this flag.
+   *
+   * ## Behavior
+   *
+   * Exclusive relations enforce a **one-to-one** constraint at the entity level:
+   * each entity can hold at most one relation of a given exclusive component type.
+   *
+   * - **Same base component, different targets**: `set(entity, relation(Comp, A))`
+   *   followed by `set(entity, relation(Comp, B))` results in only `(Comp, B)` —
+   *   the `(Comp, A)` relation is automatically removed.
+   * - **Same base component, same target**: Re-setting the same relation target
+   *   simply updates the component value (no extra removal overhead).
+   * - **Different exclusive components**: Independent — `exclusive` on `CompA` does
+   *   not affect relations using `CompB`.
+   *
+   * The removal happens **during `world.sync()`**, as part of the command buffer
+   * processing, so it respects the same deferred execution model as other structural
+   * changes.
+   *
+   * ## Use cases
+   *
+   * - **Ownership**: An entity can only be owned by one parent at a time
+   *   (`ChildOf` with `exclusive: true`).
+   * - **Equipment slots**: An item can only be in one slot at a time
+   *   (`EquippedBy` with `exclusive: true`).
+   * - **Targeting**: An AI agent can only track one target at a time
+   *   (`Targeting` with `exclusive: true`).
+   * - **State machines**: An entity can only have one active state from a set
+   *   (`ActiveState` with `exclusive: true`).
+   *
+   * ## Interaction with other options
+   *
+   * - **`cascadeDelete`**: Compatible. When an exclusive relation uses
+   *   `cascadeDelete`, deleting the target entity will both (a) delete the
+   *   referencing entity, and (b) the exclusivity constraint prevents the
+   *   entity from having multiple cascade-delete relations of the same type.
+   * - **`dontFragment`**: Compatible. Exclusivity is enforced at the data level
+   *   regardless of whether the archetype is fragmented.
+   *
+   * @example
+   * ```ts
+   * // Without exclusive: entity can have multiple ChildOf relations
+   * const ChildOf = component();
+   * world.set(child, relation(ChildOf, parentA));
+   * world.set(child, relation(ChildOf, parentB));
+   * world.sync();
+   * // child now has TWO ChildOf relations (parentA and parentB)
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With exclusive: only the last relation survives
+   * const ChildOf = component({ exclusive: true });
+   * world.set(child, relation(ChildOf, parentA));
+   * world.set(child, relation(ChildOf, parentB));
+   * world.sync();
+   * // child has only (ChildOf, parentB); (ChildOf, parentA) was auto-removed
+   * ```
    */
   exclusive?: boolean;
   /**
    * If true, when a relation target entity is deleted, all entities that reference
    * it through this component will also be deleted (cascade delete).
+   *
    * Only applicable to entity-relation components.
+   *
+   * **Important distinction from default cleanup**:
+   * By default, the ECS library **always** cleans up relation components that point
+   * to a deleted entity — the relation component is removed from the referencing
+   * entity, but the referencing entity itself **survives**. When `cascadeDelete` is
+   * enabled, the **entire referencing entity** is deleted, not just the relation
+   * component. This deletion is transitive: if entity C references entity B (which
+   * is cascade-deleted), entity C will also be deleted, and so on.
+   *
+   * @example
+   * // Without cascadeDelete (default behavior):
+   * const ChildOf = component(); // no cascadeDelete
+   * world.set(child, relation(ChildOf, parent));
+   * world.sync();
+   * world.delete(parent);
+   * world.sync();
+   * // child still exists, but the ChildOf relation is cleaned up
+   *
+   * @example
+   * // With cascadeDelete:
+   * const ChildOf = component({ cascadeDelete: true });
+   * world.set(child, relation(ChildOf, parent));
+   * world.sync();
+   * world.delete(parent);
+   * world.sync();
+   * // child is also deleted (entity deleted, not just relation cleaned up)
    */
   cascadeDelete?: boolean;
   /**
    * If true, relations with this component will not cause archetype fragmentation.
-   * Entities with different target entities for this relation component will be stored
-   * in the same archetype, preventing fragmentation when there are many different targets.
-   * Only applicable to relation components.
-   * Inspired by Flecs' DontFragment trait.
+   *
+   * **Problem it solves**: By default, each unique relation pair `(component, target)`
+   * creates a **separate archetype**. If 100 entities each have a `ChildOf` relation
+   * to a different parent, you get 100 archetypes — this is **archetype fragmentation**.
+   * Queries that iterate over all entities with a `ChildOf` relation must check all
+   * 100 archetypes, which degrades iteration performance and increases memory overhead.
+   *
+   * **How it works**: When `dontFragment` is enabled, the relation's target does **not**
+   * contribute to the archetype signature. Entities with different targets for the same
+   * relation component share a **single archetype**, and the per-entity target data is
+   * stored in a separate `DontFragmentStore` (a `Map<EntityId, Map<EntityId, any>>`).
+   * A wildcard relation marker (`relation(Comp, "*")`) is placed in the archetype
+   * component list so queries can still discover matching archetypes.
+   *
+   * **Use cases**:
+   * - **Hierarchy/ownership**: `ChildOf` relations where thousands of entities each
+   *   point to different parent entities.
+   * - **Dynamic targeting**: Relations where targets change frequently (e.g., AI
+   *   targeting, inventory slots) — without `dontFragment`, each target change would
+   *   cause an archetype migration, which is expensive.
+   * - **High-cardinality relations**: Any relation where the number of unique targets
+   *   is large compared to the number of entities.
+   *
+   * **Performance implications**:
+   * - **Without `dontFragment`**: Archetype count grows linearly with unique targets.
+   *   Each archetype migration (changing a relation target) requires moving the entity's
+   *   data between component arrays.
+   * - **With `dontFragment`**: Archetype count stays constant regardless of target
+   *   diversity. Changing a relation target is an O(1) update in the `DontFragmentStore`.
+   *   The trade-off is an extra map lookup when accessing the relation data.
+   *
+   * **Constraints**:
+   * - Only applicable to **relation components** (components used with `relation()`).
+   * - Wildcard queries (e.g., `relation(Comp, "*")`) still work correctly — the
+   *   archetype carries a wildcard marker so queries can discover it.
+   * - Works with `exclusive` and `cascadeDelete` simultaneously.
+   *
+   * @example
+   * ```ts
+   * // Without dontFragment: 100 entities with different parents = 100 archetypes
+   * const ChildOf = component(); // default: fragmentation happens
+   *
+   * // With dontFragment: 100 entities with different parents = 1 archetype
+   * const ChildOf = component({ dontFragment: true });
+   *
+   * for (let i = 0; i < 100; i++) {
+   *   const parent = world.new();
+   *   const child = world.new();
+   *   world.set(child, Position);
+   *   world.set(child, relation(ChildOf, parent));
+   * }
+   * world.sync();
+   * // dontFragment: 1 archetype for all 100 entities
+   * // without: 100 archetypes, one per unique parent
+   * ```
+   *
+   * Inspired by Flecs' `DontFragment` trait.
    */
   dontFragment?: boolean;
   /**
-   * Custom merge behavior for repeated set() of the same componentType in a single sync batch.
+   * Custom merge behavior for repeated `set()` of the same component type on the
+   * same entity within a single sync batch.
+   *
+   * By default, calling `world.set(entity, comp, value)` multiple times for the same
+   * entity and component before `world.sync()` simply overwrites the previous value —
+   * the last `set()` wins. When `merge` is provided, the values are combined using
+   * your function instead.
+   *
+   * @remarks
+   * **Use cases**:
+   * - **Accumulation**: Collecting events, tags, or modifiers that multiple systems
+   *   contribute to within the same frame.
+   * - **Composition**: Merging partial updates into a single component value (e.g.,
+   *   applying multiple `Vec3` deltas to a position).
+   * - **Conflict resolution**: Choosing the max/min/latest value when multiple
+   *   systems want to set the same component.
+   *
+   * **Scope**: This only affects `set()` calls on the **same entity** with the **same
+   * component type** within **one sync batch** (i.e., between `world.sync()` calls).
+   * It does NOT merge values across different entities or across sync boundaries.
+   *
+   * **Relation support**: If the component is used as a relation (via
+   * `relation(componentId, target)`), the merge function also applies per-target.
+   * `set(entity, relation(Comp, A), v1)` and `set(entity, relation(Comp, A), v2)`
+   * will be merged, but `set(entity, relation(Comp, B), v)` is independent.
+   *
+   * **Idempotency required**: Your merge function should be idempotent — calling it
+   * multiple times with the same inputs must produce the same result. The ECS
+   * runtime does not guarantee exactly-once `sync()` execution in all scenarios.
+   *
+   * **Return value**: The function **must return** the merged value. It should not
+   * mutate `prev` or `next` in place unless you intentionally want shared mutable
+   * state (which is discouraged).
+   *
+   * @example
+   * ```ts
+   * // Collect tags from multiple systems in one frame
+   * const Tags = component<string[]>({
+   *   merge: (prev, next) => [...prev, ...next],
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Only keep the highest priority value
+   * const Alert = component<{ level: number; msg: string }>({
+   *   merge: (prev, next) => prev.level >= next.level ? prev : next,
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Accumulate numeric deltas (e.g., for movement)
+   * const Velocity = component<{ x: number; y: number }>({
+   *   merge: (prev, next) => ({ x: prev.x + next.x, y: prev.y + next.y }),
+   * });
+   * ```
    */
   merge?: ComponentMerge<T>;
 }
@@ -126,98 +454,86 @@ declare function getComponentIdByName(name: string): ComponentId<any> | undefine
  */
 declare function getComponentNameById(id: ComponentId<any>): string | undefined;
 //#endregion
-//#region src/commands/changeset.d.ts
+//#region src/storage/serialization.d.ts
+type SerializedEntityId = number | string | {
+  component: string;
+  target: number | string | "*";
+};
 /**
- * @internal Represents a set of component changes to be applied to an entity
+ * Serialized state of EntityIdManager
  */
-declare class ComponentChangeset {
-  readonly adds: Map<EntityId<any>, any>;
-  readonly removes: Set<EntityId<any>>;
-  /**
-   * Add a component to the changeset
-   */
-  set<T>(componentType: EntityId<T>, component: T): void;
-  /**
-   * Remove a component from the changeset
-   */
-  delete<T>(componentType: EntityId<T>): void;
-  /**
-   * Check if the changeset has any changes
-   */
-  hasChanges(): boolean;
-  /**
-   * Clear all changes
-   */
-  clear(): void;
-  /**
-   * Merge another changeset into this one
-   */
-  merge(other: ComponentChangeset): void;
-  /**
-   * Apply the changeset to existing components and return the final state
-   */
-  applyTo(existingComponents: Map<EntityId<any>, any>): Map<EntityId<any>, any>;
-  /**
-   * Get the final component types after applying the changeset
-   * @param existingComponentTypes - The current component types on the entity
-   * @returns The final component types or undefined if no changes
-   */
-  getFinalComponentTypes(existingComponentTypes: EntityId<any>[]): EntityId<any>[] | undefined;
+interface SerializedEntityIdManager {
+  nextId: number;
+  freelist?: number[];
 }
+type SerializedWorld = {
+  version: number;
+  entityManager: SerializedEntityIdManager;
+  entities: SerializedEntity[];
+  componentEntities?: SerializedEntity[];
+};
+type SerializedEntity = {
+  id: SerializedEntityId;
+  components: SerializedComponent[];
+};
+type SerializedComponent = {
+  type: SerializedEntityId;
+  value: any;
+};
 //#endregion
-//#region src/commands/command-buffer.d.ts
+//#region src/query/filter.d.ts
 /**
- * Command for deferred execution
- * Uses discriminated union for type safety
+ * Filter options for queries
  */
-type Command = {
-  type: "set";
-  entityId: EntityId;
-  componentType: EntityId<any>;
-  component: any;
-} | {
-  type: "delete";
-  entityId: EntityId;
-  componentType: EntityId<any>;
-} | {
-  type: "destroy";
-  entityId: EntityId;
-};
+interface QueryFilter {
+  negativeComponentTypes?: EntityId<any>[];
+}
 //#endregion
-//#region src/core/types.d.ts
+//#region src/types/index.d.ts
 /**
- * Hook types for component lifecycle events
+ * Lifecycle hook definition for reacting to component additions, updates, and removals.
+ * Register hooks with {@link World.hook}.
  */
-interface LegacyLifecycleHook<T = unknown> {
+interface LifecycleHook<T extends readonly ComponentType<any>[]> {
   /**
-   * Called when a component is added to an entity
+   * Called once for each entity that already matches the hook's component types
+   * when the hook is first registered, and then for every new matching entity.
    */
-  on_init?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+  on_init?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
   /**
-   * Called when a component is updated on an entity
+   * Called whenever a matching entity's component data is updated via `set()`.
    */
-  on_set?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+  on_set?: (entityId: EntityId, ...components: ComponentTuple<T>) => void;
   /**
-   * Called when a component is deleted from an entity
+   * Called whenever a matching entity loses one of the required components
+   * or is deleted.
    */
-  on_remove?: (entityId: EntityId, componentType: EntityId<T>, component: 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
+ * Shorthand callback style for multi-component lifecycle hooks.
+ * The same function receives all three events distinguished by the `type` parameter.
+ *
+ * @example
+ * world.hook([Position, Velocity], (type, entityId, position, velocity) => {
+ *   if (type === "init") console.log("spawned");
+ *   if (type === "set") console.log("updated");
+ *   if (type === "remove") console.log("despawned");
+ * });
  */
-type LegacyLifecycleCallback<T = unknown> = (type: "init" | "set" | "remove", entityId: EntityId, componentType: EntityId<T>, component: T) => void;
+type LifecycleCallback<T extends readonly ComponentType<any>[]> = (type: "init" | "set" | "remove", entityId: EntityId, ...components: ComponentTuple<T>) => void;
 /**
- * Convenience function type for multi-component lifecycle events
- * Combines on_init, on_set, and on_remove into a single callback
+ * A component type used in queries and hooks.
+ * Can be a plain {@link EntityId} or an {@link OptionalEntityId} wrapped with `.optional`.
  */
-type LifecycleCallback<T extends readonly ComponentType<any>[]> = (type: "init" | "set" | "remove", entityId: EntityId, ...components: ComponentTuple<T>) => void;
 type ComponentType<T> = EntityId<T> | OptionalEntityId<T>;
+/**
+ * Wrapper that marks a component as optional in queries and hooks.
+ * When a component is optional, entities missing it are still included in results.
+ *
+ * @example
+ * world.createQuery([Position, { optional: Velocity }]);
+ */
 type OptionalEntityId<T> = {
   optional: EntityId<T>;
 };
@@ -227,17 +543,36 @@ type ComponentTypeToData<T> = T extends {
   value: ComponentTypeToData<U>;
 } | undefined : T extends WildcardRelationId<infer U> ? [EntityId<unknown>, U][] : T extends EntityId<infer U> ? U : never;
 /**
- * Type helper for component tuples extracted from EntityId array
+ * Maps an array of {@link ComponentType} to their corresponding data tuples.
+ * Used by {@link World.query} and {@link Query.forEach} to type component results.
  */
 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>[];
+  filter: QueryFilter;
   hook: LifecycleHook<any>;
+  /** Raw callback function; takes precedence over hook.on_* when present */
+  callback?: LifecycleCallback<any>;
+  /** Archetypes that match this hook, used for precise cleanup on unsubscription */
+  matchedArchetypes?: Set<any>;
+}
+//#endregion
+//#region src/archetype/store.d.ts
+/**
+ * Minimal interface for storing dontFragment relation data keyed by entity ID.
+ *
+ * Using an interface here decouples `Archetype` (and `world-commands.ts`) from
+ * the concrete `Map` used by `World`, making archetypes independently testable.
+ */
+interface DontFragmentStore {
+  get(entityId: EntityId): Map<EntityId<any>, any> | undefined;
+  set(entityId: EntityId, data: Map<EntityId<any>, any>): void;
+  delete(entityId: EntityId): void;
 }
 //#endregion
-//#region src/core/archetype.d.ts
+//#region src/archetype/archetype.d.ts
 /**
  * Archetype class for ECS architecture
  * Represents a group of entities that share the same set of components
@@ -266,9 +601,9 @@ declare class Archetype {
    */
   private entityToIndex;
   /**
-   * Reference to dontFragment relations storage from World
+   * DontFragmentStore for relation data keyed by entity ID.
    * This allows entities with different relation targets to share the same archetype
-   * Stored in World to avoid migration overhead when entities change archetypes
+   * without migration overhead when entities change archetypes.
    */
   private dontFragmentRelations;
   /**
@@ -279,7 +614,7 @@ declare class Archetype {
    * Cache for pre-computed component data sources to avoid repeated calculations
    */
   private componentDataSourcesCache;
-  constructor(componentTypes: EntityId<any>[], dontFragmentRelations: Map<EntityId, Map<EntityId<any>, any>>);
+  constructor(componentTypes: EntityId<any>[], dontFragmentRelations: DontFragmentStore);
   get size(): number;
   /**
    * Check if the given component types match this archetype
@@ -317,23 +652,88 @@ declare class Archetype {
     entity: EntityId;
     components: ComponentTuple<T>;
   }>;
+  appendEntitiesWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T, result: Array<{
+    entity: EntityId;
+    components: ComponentTuple<T>;
+  }>): void;
   iterateWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): IterableIterator<[EntityId, ...ComponentTuple<T>]>;
   forEachWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
   forEach(callback: (entityId: EntityId, components: Map<EntityId<any>, any>) => void): void;
   hasRelationWithComponentId(componentId: EntityId<any>): boolean;
 }
 //#endregion
-//#region src/query/filter.d.ts
+//#region src/query/registry.d.ts
 /**
- * Filter options for queries
+ * Manages the lifecycle and caching of `Query` instances.
+ *
+ * Responsibilities:
+ * - Create / reuse cached queries keyed by component-type + filter signature.
+ * - Track reference counts so queries are only disposed when truly unused.
+ * - Notify registered queries when new archetypes are created or destroyed.
+ *
+ * The `_cacheKey` string that was previously attached directly to `Query` is now
+ * kept in a private `WeakMap` so the `Query` class doesn't need to expose it.
  */
-interface QueryFilter {
-  negativeComponentTypes?: EntityId<any>[];
+declare class QueryRegistry {
+  /** All live queries that should receive archetype notifications. */
+  private readonly queries;
+  /** Cache of reusable queries keyed by a deterministic signature string. */
+  private readonly cache;
+  /** Maps each query to its cache key without polluting the Query public API. */
+  private readonly cacheKeys;
+  /**
+   * Returns (or creates) a cached query for the given component types and filter.
+   * Increments the reference count on cache hits.
+   *
+   * @param world       The world that owns this registry.
+   * @param sortedTypes  Normalized (sorted) component types.
+   * @param key          Combined cache key (`types|filter`).
+   * @param filter       The raw query filter (used when creating a new Query).
+   */
+  getOrCreate(world: World, sortedTypes: EntityId<any>[], key: string, filter: QueryFilter): Query;
+  /**
+   * Decrements the reference count for the given query.
+   * When the count reaches zero the query is fully disposed.
+   */
+  release(query: Query): void;
+  /**
+   * Registers a query so it receives future archetype notifications.
+   * Called automatically by the `Query` constructor via `world._registerQuery`.
+   */
+  register(query: Query): void;
+  /**
+   * Removes a query from the notification list.
+   * Called by `Query._disposeInternal` via `world._unregisterQuery`.
+   */
+  unregister(query: Query): void;
+  /**
+   * Notifies all live queries that a new archetype has been created.
+   * Queries will add the archetype to their cache if it matches.
+   */
+  onNewArchetype(archetype: Archetype): void;
+  /**
+   * Notifies all live queries that an archetype has been destroyed.
+   * Queries will remove the archetype from their internal cache.
+   */
+  onArchetypeRemoved(archetype: Archetype): void;
 }
 //#endregion
 //#region src/query/query.d.ts
 /**
- * Query class for efficient entity queries with cached archetypes
+ * Cached query for efficiently iterating entities with specific components.
+ *
+ * Queries are created via {@link World.createQuery} and should be **reused across frames**
+ * for optimal performance. The world automatically keeps the query's internal archetype cache
+ * up to date as entities are created and destroyed.
+ *
+ * @example
+ * const movementQuery = world.createQuery([Position, Velocity]);
+ *
+ * // In the game loop
+ * movementQuery.forEach([Position, Velocity], (entity, pos, vel) => {
+ *   pos.x += vel.x;
+ *   pos.y += vel.y;
+ * });
  */
 declare class Query {
   private world;
@@ -347,13 +747,24 @@ declare class Query {
   private wildcardTypes;
   /** Cached specific dontFragment relation types that need entity-level filtering */
   private specificDontFragmentTypes;
-  constructor(world: World, componentTypes: EntityId<any>[], filter?: QueryFilter);
+  /**
+   * @internal Queries should be created via {@link World.createQuery}, not instantiated directly.
+   */
+  constructor(world: World, componentTypes: EntityId<any>[], filter?: QueryFilter, registry?: QueryRegistry);
   /**
    * Check if query is disposed and throw error if so
    */
   private ensureNotDisposed;
   /**
-   * Get all entities matching the query
+   * Returns all entity IDs that match this query.
+   *
+   * @returns Array of matching entity IDs
+   *
+   * @example
+   * const entities = query.getEntities();
+   * for (const entity of entities) {
+   *   const pos = world.get(entity, Position);
+   * }
    */
   getEntities(): EntityId[];
   /**
@@ -361,42 +772,67 @@ declare class Query {
    */
   private entityMatchesQuery;
   /**
-   * Get entities with their component data
-   * @param componentTypes Array of component types to retrieve
-   * @returns Array of objects with entity and component data
+   * Returns all matching entities along with their component data.
+   *
+   * @param componentTypes - Array of component types to retrieve
+   * @returns Array of objects containing the entity ID and its component tuple
+   *
+   * @example
+   * const results = query.getEntitiesWithComponents([Position, Velocity]);
+   * results.forEach(({ entity, components: [pos, vel] }) => {
+   *   pos.x += vel.x;
+   * });
    */
   getEntitiesWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): Array<{
     entity: EntityId;
     components: ComponentTuple<T>;
   }>;
   /**
-   * Iterate over entities with their component data
-   * @param componentTypes Array of component types to retrieve
-   * @param callback Function called for each entity with its components
+   * Iterates over all matching entities and invokes the callback with their component data.
+   * This is the preferred way to read and mutate components in a hot loop.
+   *
+   * @param componentTypes - Array of component types to retrieve
+   * @param callback - Function called for each matching entity with its components
+   *
+   * @example
+   * query.forEach([Position, Velocity], (entity, pos, vel) => {
+   *   pos.x += vel.x;
+   *   pos.y += vel.y;
+   * });
    */
   forEach<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
   /**
-   * Iterate over entities with their component data (generator)
-   * @param componentTypes Array of component types to retrieve
+   * Generator that yields each matching entity together with its component data.
+   *
+   * @param componentTypes - Array of component types to retrieve
+   * @yields Tuples of `[entityId, ...components]`
+   *
+   * @example
+   * for (const [entity, pos, vel] of query.iterate([Position, Velocity])) {
+   *   pos.x += vel.x;
+   * }
    */
   iterate<const T extends readonly ComponentType<any>[]>(componentTypes: T): IterableIterator<[EntityId, ...ComponentTuple<T>]>;
   /**
-   * Get component data arrays for all matching entities
-   * @param componentType The component type to retrieve
-   * @returns Array of component data for all matching entities
+   * Returns an array containing the data of a single component for every matching entity.
+   *
+   * @param componentType - The component type to retrieve
+   * @returns Array of component data (one entry per matching entity)
+   *
+   * @example
+   * const positions = query.getComponentData(Position);
    */
   getComponentData<T>(componentType: EntityId<T>): T[];
   /**
-   * Update the cached archetypes
-   * Called when new archetypes are created
+   * @internal Rebuilds the cached archetype list. Called automatically by the world.
    */
   updateCache(): void;
   /**
-   * Check if a new archetype matches this query and add to cache if it does
+   * @internal Called by the world when a new archetype is created.
    */
   checkNewArchetype(archetype: Archetype): void;
   /**
-   * Remove an archetype from the cached archetypes
+   * @internal Called by the world when an archetype is destroyed.
    */
   removeArchetype(archetype: Archetype): void;
   /**
@@ -406,47 +842,24 @@ declare class Query {
    */
   dispose(): void;
   /**
-   * Internal full dispose called by World when refCount reaches zero.
+   * @internal Fully disposes the query when the world's refCount reaches zero.
    */
-  _disposeInternal(): void;
+  _disposeInternal(registry?: QueryRegistry): void;
   /**
-   * Symbol.dispose implementation for automatic resource management
+   * Using-with-disposals support. Calls {@link dispose} automatically.
+   *
+   * @example
+   * using query = world.createQuery([Position]);
+   * // query is released automatically when the block exits
    */
   [Symbol.dispose](): void;
   /**
-   * Check if the query has been disposed
+   * Whether the query has been disposed and can no longer be used.
    */
   get disposed(): boolean;
 }
 //#endregion
-//#region src/core/serialization.d.ts
-type SerializedEntityId = number | string | {
-  component: string;
-  target: number | string | "*";
-};
-/**
- * Serialized state of EntityIdManager
- */
-interface SerializedEntityIdManager {
-  nextId: number;
-  freelist?: number[];
-}
-type SerializedWorld = {
-  version: number;
-  entityManager: SerializedEntityIdManager;
-  entities: SerializedEntity[];
-  componentEntities?: SerializedEntity[];
-};
-type SerializedEntity = {
-  id: SerializedEntityId;
-  components: SerializedComponent[];
-};
-type SerializedComponent = {
-  type: SerializedEntityId;
-  value: any;
-};
-//#endregion
-//#region src/core/world.d.ts
+//#region src/world/world.d.ts
 /**
  * World class for ECS architecture
  * Manages entities and components
@@ -458,21 +871,22 @@ declare class World {
   private entityToArchetype;
   private archetypesByComponent;
   private entityReferences;
-  private dontFragmentRelations;
-  private componentEntityComponents;
-  private relationEntityIdsByTarget;
-  private queries;
-  private queryCache;
-  private legacyHooks;
+  /** Reverse index: entity ID → set of archetypes whose componentTypes include that entity ID */
+  private entityToReferencingArchetypes;
+  /** DontFragment relation storage, shared with all Archetype instances */
+  private readonly dontFragmentStore;
+  /** Component entity (singleton) storage */
+  private readonly componentEntities;
+  private readonly queryRegistry;
   private hooks;
   private commandBuffer;
   private readonly _changeset;
+  private readonly _removeChangeset;
   /** Cached command processor context to avoid per-entity object allocation */
   private readonly _commandCtx;
   /** Cached hooks context to avoid per-entity object allocation */
   private readonly _hooksCtx;
   constructor(snapshot?: SerializedWorld);
-  private deserializeSnapshot;
   private createArchetypeSignature;
   /**
    * Creates a new entity.
@@ -487,23 +901,35 @@ declare class World {
    * world.sync();
    */
   new<T = void>(): EntityId<T>;
-  private isComponentEntityId;
-  private registerRelationEntityId;
-  private unregisterRelationEntityId;
-  private getComponentEntityComponents;
-  private clearComponentEntityComponents;
-  private cleanupComponentEntitiesReferencingEntity;
+  /**
+   * Semantic alias for `new()` to avoid confusion with the `new` keyword.
+   * Creates a new entity with an empty component set.
+   *
+   * @example
+   * const entity = world.create<MyComponent>();
+   */
+  create<T = void>(): EntityId<T>;
+  /** Fast path: destroy an entity that is not referenced by any other entity, skipping BFS */
+  private destroySingleEntity;
   private destroyEntityImmediate;
   /**
-   * Checks if an entity exists in the world.
+   * Checks if an **entity** (not a component) exists in the world.
+   *
+   * This is specifically for checking entity liveness — whether the given entity ID
+   * is currently alive in the world. For checking if a component is present on an
+   * entity, use {@link has} instead.
    *
    * @param entityId - The entity identifier to check
    * @returns `true` if the entity exists, `false` otherwise
    *
    * @example
+   * // Check if an entity is alive
    * if (world.exists(entityId)) {
    *   console.log("Entity exists");
    * }
+   *
+   * // To check for a component, use has() instead:
+   * if (world.has(entity, Position)) { ... }
    */
   exists(entityId: EntityId): boolean;
   private assertEntityExists;
@@ -511,7 +937,6 @@ declare class World {
   private assertSetComponentTypeValid;
   private resolveSetOperation;
   private resolveRemoveOperation;
-  private getComponentEntityWildcardRelations;
   /**
    * Adds or updates a component on an entity (or marks void component as present).
    * The change is buffered and takes effect after calling `world.sync()`.
@@ -576,27 +1001,39 @@ declare class World {
    */
   delete(entityId: EntityId): void;
   /**
-   * Checks if an entity has a specific component.
+   * Checks if a specific **component** is present on an entity.
+   *
+   * This is for component membership checks — does the given entity have this
+   * component type? For checking whether an entity itself is alive, use
+   * {@link exists} instead.
+   *
    * Immediately reflects the current state without waiting for `sync()`.
    *
    * @overload has<T>(entityId: EntityId, componentType: EntityId<T>): boolean
    * Checks if a specific component type is present on the entity.
    *
    * @overload has<T>(componentId: ComponentId<T>): boolean
-   * Checks if a singleton component has data (shorthand for has(componentId, componentId)).
+   * Shorthand for checking a **singleton component** — a component that is its own
+   * entity (component-as-entity pattern). Equivalent to `has(componentId, componentId)`.
    *
    * @template T - The component data type
-   * @param entityId - The entity identifier
+   * @param entityId - The entity identifier, or a singleton component ID
    * @param componentType - The component type to check
    * @returns `true` if the entity has the component, `false` otherwise
    *
    * @example
+   * // Check if an entity has a component
    * if (world.has(entity, Position)) {
    *   const pos = world.get(entity, Position);
    * }
+   *
+   * // Check a singleton component (component-as-entity)
    * if (world.has(GlobalConfig)) {
    *   const config = world.get(GlobalConfig);
    * }
+   *
+   * // Use exists() for entity liveness checks
+   * if (world.exists(entity)) { ... }
    */
   has<T>(componentId: ComponentId<T>): boolean;
   has<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
@@ -653,27 +1090,22 @@ declare class World {
   /**
    * Registers a lifecycle hook that responds to component changes.
    * The hook callback is invoked when components matching the specified types are added, updated, or removed.
-   *
-   * @deprecated For single components, use the array overload with LifecycleCallback for better multi-component support
-   *
-   * @overload hook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T> | LegacyLifecycleCallback<T>): () => void
-   * Registers a hook for a single component type (legacy API).
-   *
    * @overload hook<const T extends readonly ComponentType<any>[]>(
    *   componentTypes: T,
    *   hook: LifecycleHook<T> | LifecycleCallback<T>,
+   *   filter?: QueryFilter,
    * ): () => void
    * Registers a hook for multiple component types.
-   * The hook is triggered when all required components change together.
+   * The hook is triggered when entities enter/exit the matching set.
    *
-   * @param componentTypesOrSingle - A single component type or an array of component types
+   * @param componentTypes - Component types that define the matching entity set
    * @param hook - Either a hook object with on_init/on_set/on_remove handlers, or a callback function
+   * @param filter - Optional query-style filter applied to the hook match set
    * @returns A function that unsubscribes the hook when called
    *
    * @throws {Error} If no required components are specified in array overload
    *
    * @example
-   * // Array overload (recommended)
    * const unsubscribe = world.hook([Position, Velocity], {
    *   on_init: (entityId, position, velocity) => console.log("Initialized"),
    *   on_set: (entityId, position, velocity) => console.log("Updated"),
@@ -685,13 +1117,17 @@ declare class World {
    * const unsubscribe = world.hook([Position], (event, entityId, position) => {
    *   if (event === "init") console.log("Initialized");
    * });
+   *
+   * // With filter
+   * const unsubscribe2 = world.hook(
+   *   [Position, Velocity],
+   *   {
+   *     on_set: (entityId, position, velocity) => console.log(entityId, position, velocity),
+   *   },
+   *   { negativeComponentTypes: [Disabled] },
+   * );
    */
-  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;
-  /** @deprecated use the unsubscribe function returned by hook() instead */
-  unhook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T>): void;
-  /** @deprecated use the unsubscribe function returned by hook() instead */
-  unhook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T>): void;
+  hook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T> | LifecycleCallback<T>, filter?: QueryFilter): () => void;
   /**
    * Synchronizes all buffered commands (set/remove/delete) to the world.
    * This method must be called after making changes via `set()`, `remove()`, or `delete()` for them to take effect.
@@ -763,8 +1199,6 @@ declare class World {
    * world.sync();
    */
   spawnMany(count: number, configure: (builder: EntityBuilder, index: number) => EntityBuilder): EntityId[];
-  _registerQuery(query: Query): void;
-  _unregisterQuery(query: Query): void;
   /**
    * Releases a cached query and frees its resources if no longer needed.
    * Call this when you're done using a query to allow the world to clean up its cache entry.
@@ -819,16 +1253,19 @@ declare class World {
     entity: EntityId;
     components: ComponentTuple<T>;
   }>;
-  executeEntityCommands(entityId: EntityId, commands: Command[]): ComponentChangeset;
-  private executeComponentEntityCommands;
+  private executeEntityCommands;
+  private applyEntityCommands;
   private createHooksContext;
   private removeComponentImmediate;
   private updateEntityReferences;
   private ensureArchetype;
+  /** Add componentType to the reverse index if it contains an entity ID */
+  private addToReferencingIndex;
+  /** Remove componentType from the reverse index */
+  private removeFromReferencingIndex;
   private createNewArchetype;
   private updateArchetypeHookMatches;
   private archetypeMatchesHook;
-  private archetypeReferencesEntity;
   private cleanupArchetypesReferencingEntity;
   private removeArchetype;
   /**
@@ -855,7 +1292,7 @@ declare class World {
   serialize(): SerializedWorld;
 }
 //#endregion
-//#region src/core/builder.d.ts
+//#region src/world/builder.d.ts
 /**
  * A component definition for entity building, supporting both regular components and relations
  */
@@ -869,28 +1306,62 @@ type ComponentDef<T = unknown> = {
   targetId: EntityId<any>;
   value: T;
 };
+/**
+ * Fluent API for constructing entities with multiple components.
+ * Create instances via {@link World.spawn}.
+ *
+ * @example
+ * const entity = world.spawn()
+ *   .with(Position, { x: 0, y: 0 })
+ *   .withRelation(Parent, parentEntity)
+ *   .build();
+ * world.sync();
+ */
 declare class EntityBuilder {
   private world;
   private components;
   constructor(world: World);
-  with<T>(componentId: EntityId<T>, ...args: T extends void ? [] | [void] : [T]): this;
   /**
-   * @deprecated Use `with(componentId)` instead for void components
+   * Add a regular component to the entity under construction.
+   *
+   * @template T - The component data type
+   * @param componentId - The component type to add
+   * @param args - Component data (omit for void components)
+   * @returns This builder for chaining
+   *
+   * @example
+   * builder.with(Position, { x: 10, y: 20 });
+   * builder.with(Marker); // void component
    */
-  withTag(componentId: EntityId<void>): this;
-  withRelation<T>(componentId: ComponentId<T>, targetEntity: EntityId<any>, ...args: T extends void ? [] | [void] : [T]): this;
+  with<T>(componentId: EntityId<T>, ...args: T extends void ? [] | [void] : [T]): this;
   /**
-   * @deprecated Use `withRelation(componentId, targetEntity)` instead for void relations
+   * Add a relation component to the entity under construction.
+   *
+   * @template T - The relation data type
+   * @param componentId - The base component type for the relation
+   * @param targetEntity - The target entity or component for the relation
+   * @param args - Relation data (omit for void relations)
+   * @returns This builder for chaining
+   *
+   * @example
+   * builder.withRelation(Parent, parentEntity);
+   * builder.withRelation(ChildOf, childEntity, { order: 1 });
    */
-  withRelationTag(componentId: ComponentId<void>, targetEntity: EntityId<any>): this;
+  withRelation<T>(componentId: ComponentId<T>, targetEntity: EntityId<any>, ...args: T extends void ? [] | [void] : [T]): this;
   /**
-   * Create an entity and enqueue components to be applied. This method
-   * does NOT call `world.sync()` automatically; callers must invoke
-   * `world.sync()` to apply deferred commands.
-   * (Previously auto-synced; now a breaking change — buildDeferred() removed.)
+   * Create the entity and enqueue all configured components.
+   * The entity and components are only materialised after {@link World.sync} is called.
+   *
+   * @returns The newly created entity ID
+   *
+   * @example
+   * const entity = world.spawn()
+   *   .with(Position, { x: 0, y: 0 })
+   *   .build();
+   * world.sync(); // Apply changes
    */
   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, 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 };
+export { EntityRelationId as C, isEntityId as D, isComponentId as E, isRelationId as O, EntityId as S, WildcardRelationId as T, decodeRelationId as _, ComponentTuple as a, ComponentId as b, LifecycleHook as c, SerializedEntityId as d, SerializedWorld as f, getComponentNameById as g, getComponentIdByName as h, Query as i, SerializedComponent as l, component as m, EntityBuilder as n, ComponentType as o, ComponentOptions as p, World as r, LifecycleCallback as s, ComponentDef as t, SerializedEntity as u, isWildcardRelationId as v, RelationId as w, ComponentRelationId as x, relation as y };
 //# sourceMappingURL=builder.d.mts.map