@alife-sdk/core 0.1.0 → 0.3.0

package/dist/ai/StateMachine.js

@@ -12,9 +12,15 @@
  */
 export class StateMachine {
     constructor(entity, registry, initialState) {
+        this.previousStateId = null;
+        this.enterListeners = new Map();
+        this.exitListeners = new Map();
+        this.changeListeners = new Set();
+        this.historyLog = [];
         this.entity = entity;
         this.registry = registry;
         this.currentStateId = initialState;
+        this.stateEnterTime = Date.now();
         const definition = this.registry.get(this.currentStateId);
         definition.handler.enter(this.entity);
     }
@@ -25,6 +31,68 @@ export class StateMachine {
     get state() {
         return this.currentStateId;
     }
+    /** Previous state identifier, or `null` if no transition has occurred yet. */
+    get previous() {
+        return this.previousStateId;
+    }
+    /** Milliseconds elapsed since entering the current state. */
+    get currentStateDuration() {
+        return Date.now() - this.stateEnterTime;
+    }
+    // -----------------------------------------------------------------------
+    // Tag queries
+    // -----------------------------------------------------------------------
+    /** Returns `true` if the current state has the given tag. */
+    hasTag(tag) {
+        const def = this.registry.tryGet(this.currentStateId);
+        return def?.tags?.includes(tag) ?? false;
+    }
+    /** Returns the metadata object of the current state, or `undefined`. */
+    get metadata() {
+        return this.registry.tryGet(this.currentStateId)?.metadata;
+    }
+    // -----------------------------------------------------------------------
+    // Event subscriptions
+    // -----------------------------------------------------------------------
+    /**
+     * Subscribe to the moment the FSM enters `state`.
+     * @returns Unsubscribe function.
+     */
+    onEnter(state, callback) {
+        if (!this.enterListeners.has(state))
+            this.enterListeners.set(state, new Set());
+        this.enterListeners.get(state).add(callback);
+        return () => this.enterListeners.get(state)?.delete(callback);
+    }
+    /**
+     * Subscribe to the moment the FSM exits `state`.
+     * @returns Unsubscribe function.
+     */
+    onExit(state, callback) {
+        if (!this.exitListeners.has(state))
+            this.exitListeners.set(state, new Set());
+        this.exitListeners.get(state).add(callback);
+        return () => this.exitListeners.get(state)?.delete(callback);
+    }
+    /**
+     * Subscribe to any state change.
+     * @returns Unsubscribe function.
+     */
+    onChange(callback) {
+        this.changeListeners.add(callback);
+        return () => this.changeListeners.delete(callback);
+    }
+    // -----------------------------------------------------------------------
+    // History
+    // -----------------------------------------------------------------------
+    /** Returns a snapshot of the transition history (oldest first). */
+    getHistory() {
+        return [...this.historyLog];
+    }
+    /** Clears the transition history. */
+    clearHistory() {
+        this.historyLog.length = 0;
+    }
     // -----------------------------------------------------------------------
     // Transitions
     // -----------------------------------------------------------------------
@@ -46,9 +114,21 @@ export class StateMachine {
             return { success: false, reason: 'exit_guard' };
         if (newDefinition.canEnter?.(this.entity, this.currentStateId) === false)
             return { success: false, reason: 'enter_guard' };
+        const from = this.currentStateId;
+        // Exit
         oldDefinition.handler.exit(this.entity);
+        this.exitListeners.get(from)?.forEach(cb => cb(newState));
+        // Advance state
+        this.previousStateId = from;
         this.currentStateId = newState;
+        this.stateEnterTime = Date.now();
+        // Record history
+        this.historyLog.push({ from, to: newState, timestamp: this.stateEnterTime });
+        // Notify change listeners
+        this.changeListeners.forEach(cb => cb(from, newState));
+        // Enter
         newDefinition.handler.enter(this.entity);
+        this.enterListeners.get(newState)?.forEach(cb => cb(from));
         return { success: true };
     }
     // -----------------------------------------------------------------------

package/dist/ai/StateMachine.js.map

@@ -1 +1 @@
-{"version":3,"file":"StateMachine.js","sourceRoot":"","sources":["../../src/ai/StateMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,MAAM,OAAO,YAAY;IAKvB,YAAY,MAAe,EAAE,QAAyB,EAAE,YAAoB;QAC1E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,YAAY,CAAC;QAEnC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC1D,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,0EAA0E;IAC1E,YAAY;IACZ,0EAA0E;IAE1E,uCAAuC;IACvC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,0EAA0E;IAC1E,cAAc;IACd,0EAA0E;IAE1E;;;;;;OAMG;IACH,UAAU,CAAC,QAAgB;QACzB,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC7D,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAElD,oFAAoF;QACpF,IAAI,aAAa,CAAC,kBAAkB,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7F,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QACnD,CAAC;QAED,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,KAAK;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;QAC9G,IAAI,aAAa,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC,KAAK,KAAK;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QAE3H,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;QAC/B,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,0EAA0E;IAC1E,SAAS;IACT,0EAA0E;IAE1E;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAa;QAClB,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC1D,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAE9C,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CACjD,IAAI,CAAC,cAAc,EACnB,IAAI,CAAC,MAAM,CACZ,CAAC;QAEF,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,UAAU;IACV,0EAA0E;IAE1E,iEAAiE;IACjE,OAAO;QACL,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC1D,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"StateMachine.js","sourceRoot":"","sources":["../../src/ai/StateMachine.ts"],"names":[],"mappings":"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"}

package/dist/ai/index.d.ts

@@ -1,5 +1,5 @@
 export { StateMachine } from './StateMachine';
-export type { TransitionResult } from './StateMachine';
+export type { TransitionResult, StateTransitionEvent } from './StateMachine';
 export { MemoryBank, MemoryChannel } from './MemorySystem';
 export type { MemoryRecord, IMemoryBankConfig, IMemoryInput } from './MemorySystem';
 export { DangerManager, DangerType } from './DangerManager';
@@ -7,4 +7,6 @@ export type { IDangerEntry } from './DangerManager';
 export { WorldState } from './WorldState';
 export { GOAPPlanner } from './GOAPPlanner';
 export { GOAPAction, ActionStatus } from './GOAPAction';
+export { Blackboard, Task, Condition, Sequence, Selector, Parallel, Inverter, AlwaysSucceed, AlwaysFail, Repeater, Cooldown } from './BehaviorTree';
+export type { TaskStatus, ITreeNode, ParallelPolicy } from './BehaviorTree';
 //# sourceMappingURL=index.d.ts.map

package/dist/ai/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACpJ,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/ai/index.js

@@ -5,4 +5,5 @@ export { DangerManager, DangerType } from './DangerManager';
 export { WorldState } from './WorldState';
 export { GOAPPlanner } from './GOAPPlanner';
 export { GOAPAction, ActionStatus } from './GOAPAction';
+export { Blackboard, Task, Condition, Sequence, Selector, Parallel, Inverter, AlwaysSucceed, AlwaysFail, Repeater, Cooldown } from './BehaviorTree';
 //# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,qBAAqB;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/core/ReactiveQuery.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ReactiveQuery — observe when entities enter and exit a filtered set.
+ *
+ * Instead of polling the entire entity set every frame, a ReactiveQuery
+ * maintains a stable "matched" set and fires change notifications only when
+ * entities enter or leave the query (i.e. when the predicate result changes).
+ *
+ * Usage pattern:
+ *   1. Create a query with a predicate.
+ *   2. Subscribe to `onChange` to react to structural changes.
+ *   3. Call `update(allEntities)` each tick to re-evaluate.
+ *
+ * @example
+ * ```ts
+ * const hostileQuery = new ReactiveQuery<IEntity>(
+ *   (e) => e.isAlive && e.hasComponent('hostile')
+ * );
+ *
+ * hostileQuery.onChange(({ added, removed }) => {
+ *   added.forEach(e => combatSystem.track(e));
+ *   removed.forEach(e => combatSystem.untrack(e));
+ * });
+ *
+ * // Each tick:
+ * hostileQuery.update(world.entities());
+ * ```
+ */
+/** Changes detected since the last `update()` call. */
+export interface QueryChanges<T> {
+    /** Entities that newly matched the predicate this update. */
+    readonly added: readonly T[];
+    /** Entities that no longer match the predicate this update. */
+    readonly removed: readonly T[];
+    /** All entities currently matching the predicate after this update. */
+    readonly current: readonly T[];
+}
+/** Callback invoked when any entities are added or removed from the query. */
+export type QueryChangeListener<T> = (changes: QueryChanges<T>) => void;
+/**
+ * Tracks which entities satisfy a predicate and fires change events when
+ * the matched set changes.
+ */
+export declare class ReactiveQuery<T> {
+    private readonly predicate;
+    private readonly matched;
+    private readonly listeners;
+    constructor(predicate: (entity: T) => boolean);
+    /**
+     * Re-evaluate the predicate against `allEntities`.
+     *
+     * Fires `onChange` listeners if the matched set changed.
+     * Call this once per tick from the owning system.
+     */
+    update(allEntities: Iterable<T>): void;
+    /**
+     * Subscribe to change events. Called whenever entities enter or exit the
+     * matched set.
+     *
+     * @returns Unsubscribe function.
+     */
+    onChange(listener: QueryChangeListener<T>): () => void;
+    /** All entities currently matching the predicate (stable snapshot). */
+    get current(): readonly T[];
+    /** Number of currently matched entities. */
+    get size(): number;
+    /** Return `true` if the entity is currently in the matched set. */
+    has(entity: T): boolean;
+    /**
+     * Manually add an entity to the matched set without re-evaluating the
+     * predicate. Fires `onChange` with the single addition.
+     *
+     * Useful when external code creates entities and knows they should match.
+     */
+    track(entity: T): void;
+    /**
+     * Manually remove an entity from the matched set.
+     * Fires `onChange` with the single removal.
+     *
+     * Useful when entities are destroyed mid-tick.
+     */
+    untrack(entity: T): void;
+    /** Remove all entities and clear all listeners. */
+    dispose(): void;
+}
+//# sourceMappingURL=ReactiveQuery.d.ts.map

package/dist/core/ReactiveQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactiveQuery.d.ts","sourceRoot":"","sources":["../../src/core/ReactiveQuery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,uDAAuD;AACvD,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;CAChC;AAED,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAMxE;;;GAGG;AACH,qBAAa,aAAa,CAAC,CAAC;IAId,OAAO,CAAC,QAAQ,CAAC,SAAS;IAHtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;gBAElC,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO;IAM9D;;;;;OAKG;IACH,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAwCtC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAStD,uEAAuE;IACvE,IAAI,OAAO,IAAI,SAAS,CAAC,EAAE,CAE1B;IAED,4CAA4C;IAC5C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mEAAmE;IACnE,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO;IAIvB;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI;IAatB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI;IAaxB,mDAAmD;IACnD,OAAO,IAAI,IAAI;CAIhB"}

package/dist/core/ReactiveQuery.js

@@ -0,0 +1,154 @@
+/**
+ * ReactiveQuery — observe when entities enter and exit a filtered set.
+ *
+ * Instead of polling the entire entity set every frame, a ReactiveQuery
+ * maintains a stable "matched" set and fires change notifications only when
+ * entities enter or leave the query (i.e. when the predicate result changes).
+ *
+ * Usage pattern:
+ *   1. Create a query with a predicate.
+ *   2. Subscribe to `onChange` to react to structural changes.
+ *   3. Call `update(allEntities)` each tick to re-evaluate.
+ *
+ * @example
+ * ```ts
+ * const hostileQuery = new ReactiveQuery<IEntity>(
+ *   (e) => e.isAlive && e.hasComponent('hostile')
+ * );
+ *
+ * hostileQuery.onChange(({ added, removed }) => {
+ *   added.forEach(e => combatSystem.track(e));
+ *   removed.forEach(e => combatSystem.untrack(e));
+ * });
+ *
+ * // Each tick:
+ * hostileQuery.update(world.entities());
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// ReactiveQuery
+// ---------------------------------------------------------------------------
+/**
+ * Tracks which entities satisfy a predicate and fires change events when
+ * the matched set changes.
+ */
+export class ReactiveQuery {
+    constructor(predicate) {
+        this.predicate = predicate;
+        this.matched = new Set();
+        this.listeners = new Set();
+    }
+    // -------------------------------------------------------------------------
+    // Update
+    // -------------------------------------------------------------------------
+    /**
+     * Re-evaluate the predicate against `allEntities`.
+     *
+     * Fires `onChange` listeners if the matched set changed.
+     * Call this once per tick from the owning system.
+     */
+    update(allEntities) {
+        const added = [];
+        const removed = [];
+        const nextMatched = new Set();
+        for (const entity of allEntities) {
+            if (this.predicate(entity)) {
+                nextMatched.add(entity);
+                if (!this.matched.has(entity)) {
+                    added.push(entity);
+                }
+            }
+        }
+        for (const entity of this.matched) {
+            if (!nextMatched.has(entity)) {
+                removed.push(entity);
+            }
+        }
+        // Commit new matched set
+        this.matched.clear();
+        for (const e of nextMatched)
+            this.matched.add(e);
+        if (added.length > 0 || removed.length > 0) {
+            const changes = {
+                added,
+                removed,
+                current: [...this.matched],
+            };
+            for (const listener of this.listeners) {
+                listener(changes);
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Subscriptions
+    // -------------------------------------------------------------------------
+    /**
+     * Subscribe to change events. Called whenever entities enter or exit the
+     * matched set.
+     *
+     * @returns Unsubscribe function.
+     */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    // -------------------------------------------------------------------------
+    // Accessors
+    // -------------------------------------------------------------------------
+    /** All entities currently matching the predicate (stable snapshot). */
+    get current() {
+        return [...this.matched];
+    }
+    /** Number of currently matched entities. */
+    get size() {
+        return this.matched.size;
+    }
+    /** Return `true` if the entity is currently in the matched set. */
+    has(entity) {
+        return this.matched.has(entity);
+    }
+    /**
+     * Manually add an entity to the matched set without re-evaluating the
+     * predicate. Fires `onChange` with the single addition.
+     *
+     * Useful when external code creates entities and knows they should match.
+     */
+    track(entity) {
+        if (this.matched.has(entity))
+            return;
+        this.matched.add(entity);
+        const changes = {
+            added: [entity],
+            removed: [],
+            current: [...this.matched],
+        };
+        for (const listener of this.listeners) {
+            listener(changes);
+        }
+    }
+    /**
+     * Manually remove an entity from the matched set.
+     * Fires `onChange` with the single removal.
+     *
+     * Useful when entities are destroyed mid-tick.
+     */
+    untrack(entity) {
+        if (!this.matched.has(entity))
+            return;
+        this.matched.delete(entity);
+        const changes = {
+            added: [],
+            removed: [entity],
+            current: [...this.matched],
+        };
+        for (const listener of this.listeners) {
+            listener(changes);
+        }
+    }
+    /** Remove all entities and clear all listeners. */
+    dispose() {
+        this.matched.clear();
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=ReactiveQuery.js.map

package/dist/core/ReactiveQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactiveQuery.js","sourceRoot":"","sources":["../../src/core/ReactiveQuery.ts"],"names":[],"mappings":"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"}

package/dist/entity/EntityHandle.d.ts

@@ -0,0 +1,76 @@
+/**
+ * EntityHandle — versioned entity references with use-after-free protection.
+ *
+ * Instead of holding raw entity references that can become dangling after an
+ * entity is destroyed, systems hold an EntityHandle. The handle encodes both
+ * the entity's slot index and a generation counter. When a slot is reused for
+ * a new entity the generation is bumped, making all old handles stale.
+ *
+ * Bit layout (fits in a JavaScript safe integer):
+ *   [47..20] generation  (28 bits, up to ~268 M versions per slot)
+ *   [19.. 0] index       (20 bits, up to ~1 M concurrent slots)
+ *
+ * Usage:
+ *   const manager = new EntityHandleManager();
+ *   const handle  = manager.alloc('wolf-1');
+ *   manager.resolve(handle);   // → 'wolf-1'
+ *   manager.free(handle);
+ *   manager.resolve(handle);   // → null  (stale)
+ */
+/** Opaque numeric type that encodes (generation, index). */
+export type EntityHandle = number & {
+    readonly __brand: 'EntityHandle';
+};
+/** Sentinel value for an absent or invalid handle. */
+export declare const NULL_HANDLE: EntityHandle;
+/** Pack (index, generation) into a single handle. */
+export declare function makeHandle(index: number, generation: number): EntityHandle;
+/** Extract the slot index from a handle. */
+export declare function indexOf(handle: EntityHandle): number;
+/** Extract the generation counter from a handle. */
+export declare function genOf(handle: EntityHandle): number;
+/** Return `true` if the handle is not the null sentinel. */
+export declare function isValidHandle(handle: EntityHandle): boolean;
+/** Human-readable description for logging / debugging. */
+export declare function handleToString(handle: EntityHandle): string;
+/**
+ * Central registry that owns the slot → entity-id mapping.
+ *
+ * Recycles freed slots so slot count stays bounded. Old handles pointing at
+ * recycled slots resolve to `null` because their stored generation no longer
+ * matches the slot's current generation.
+ */
+export declare class EntityHandleManager<TId = string> {
+    /** Generation counter per slot (index = slot index). */
+    private readonly generations;
+    /** Entity ID stored in each live slot. `null` = free. */
+    private readonly ids;
+    /** Slot indices available for reuse. */
+    private readonly freeList;
+    /** Next slot to allocate when freeList is empty. */
+    private nextSlot;
+    /**
+     * Allocate a new handle for the given entity id.
+     * @throws if the slot limit is exhausted.
+     */
+    alloc(id: TId): EntityHandle;
+    /**
+     * Release a handle, incrementing the slot's generation.
+     * All existing handles pointing at this slot become stale.
+     *
+     * Does nothing (and does not throw) if the handle is already stale.
+     */
+    free(handle: EntityHandle): void;
+    /**
+     * Resolve a handle to its entity id.
+     * Returns `null` if the handle is stale (entity was freed) or null.
+     */
+    resolve(handle: EntityHandle): TId | null;
+    /**
+     * Return `true` if the handle points to a currently-live slot.
+     */
+    isAlive(handle: EntityHandle): boolean;
+    /** Number of currently-live slots. */
+    get size(): number;
+}
+//# sourceMappingURL=EntityHandle.d.ts.map

package/dist/entity/EntityHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityHandle.d.ts","sourceRoot":"","sources":["../../src/entity/EntityHandle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgBH,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAEzE,sDAAsD;AACtD,eAAO,MAAM,WAAW,EAAQ,YAAY,CAAC;AAE7C,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAG1E;AAED,4CAA4C;AAC5C,wBAAgB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEpD;AAED,oDAAoD;AACpD,wBAAgB,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAElD;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAE3D;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAG3D;AAMD;;;;;;GAMG;AACH,qBAAa,mBAAmB,CAAC,GAAG,GAAG,MAAM;IAC3C,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsB;IAC1C,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAK;IAErB;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,GAAG,GAAG,YAAY;IAiB5B;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAQhC;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,GAAG,GAAG,IAAI;IAOzC;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO;IAMtC,sCAAsC;IACtC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/entity/EntityHandle.js

@@ -0,0 +1,133 @@
+/**
+ * EntityHandle — versioned entity references with use-after-free protection.
+ *
+ * Instead of holding raw entity references that can become dangling after an
+ * entity is destroyed, systems hold an EntityHandle. The handle encodes both
+ * the entity's slot index and a generation counter. When a slot is reused for
+ * a new entity the generation is bumped, making all old handles stale.
+ *
+ * Bit layout (fits in a JavaScript safe integer):
+ *   [47..20] generation  (28 bits, up to ~268 M versions per slot)
+ *   [19.. 0] index       (20 bits, up to ~1 M concurrent slots)
+ *
+ * Usage:
+ *   const manager = new EntityHandleManager();
+ *   const handle  = manager.alloc('wolf-1');
+ *   manager.resolve(handle);   // → 'wolf-1'
+ *   manager.free(handle);
+ *   manager.resolve(handle);   // → null  (stale)
+ */
+// ---------------------------------------------------------------------------
+// Bit-layout constants
+// ---------------------------------------------------------------------------
+const INDEX_BITS = 20;
+const GEN_BITS = 28;
+const INDEX_MASK = (1 << INDEX_BITS) - 1; // 0x000FFFFF — 1 048 575 max slots
+const GEN_MASK = (1 << GEN_BITS) - 1; // 0x0FFFFFFF — 268 435 455 max gen
+const MAX_SLOTS = 1 << INDEX_BITS;
+/** Sentinel value for an absent or invalid handle. */
+export const NULL_HANDLE = 0;
+/** Pack (index, generation) into a single handle. */
+export function makeHandle(index, generation) {
+    // Use multiplication instead of bit-shift to avoid 32-bit truncation.
+    return ((generation & GEN_MASK) * MAX_SLOTS + (index & INDEX_MASK));
+}
+/** Extract the slot index from a handle. */
+export function indexOf(handle) {
+    return handle & INDEX_MASK;
+}
+/** Extract the generation counter from a handle. */
+export function genOf(handle) {
+    return Math.floor(handle / MAX_SLOTS) & GEN_MASK;
+}
+/** Return `true` if the handle is not the null sentinel. */
+export function isValidHandle(handle) {
+    return handle !== NULL_HANDLE;
+}
+/** Human-readable description for logging / debugging. */
+export function handleToString(handle) {
+    if (!isValidHandle(handle))
+        return 'Entity(NULL)';
+    return `Entity(idx=${indexOf(handle)}, gen=${genOf(handle)})`;
+}
+// ---------------------------------------------------------------------------
+// EntityHandleManager
+// ---------------------------------------------------------------------------
+/**
+ * Central registry that owns the slot → entity-id mapping.
+ *
+ * Recycles freed slots so slot count stays bounded. Old handles pointing at
+ * recycled slots resolve to `null` because their stored generation no longer
+ * matches the slot's current generation.
+ */
+export class EntityHandleManager {
+    constructor() {
+        /** Generation counter per slot (index = slot index). */
+        this.generations = [];
+        /** Entity ID stored in each live slot. `null` = free. */
+        this.ids = [];
+        /** Slot indices available for reuse. */
+        this.freeList = [];
+        /** Next slot to allocate when freeList is empty. */
+        this.nextSlot = 0;
+    }
+    /**
+     * Allocate a new handle for the given entity id.
+     * @throws if the slot limit is exhausted.
+     */
+    alloc(id) {
+        let index;
+        if (this.freeList.length > 0) {
+            index = this.freeList.pop();
+        }
+        else {
+            if (this.nextSlot >= MAX_SLOTS) {
+                throw new Error(`EntityHandleManager: slot limit (${MAX_SLOTS}) reached`);
+            }
+            index = this.nextSlot++;
+            this.generations[index] = 1;
+        }
+        this.ids[index] = id;
+        return makeHandle(index, this.generations[index]);
+    }
+    /**
+     * Release a handle, incrementing the slot's generation.
+     * All existing handles pointing at this slot become stale.
+     *
+     * Does nothing (and does not throw) if the handle is already stale.
+     */
+    free(handle) {
+        if (!this.isAlive(handle))
+            return;
+        const index = indexOf(handle);
+        this.ids[index] = null;
+        this.generations[index] = (this.generations[index] + 1) & GEN_MASK || 1; // skip 0
+        this.freeList.push(index);
+    }
+    /**
+     * Resolve a handle to its entity id.
+     * Returns `null` if the handle is stale (entity was freed) or null.
+     */
+    resolve(handle) {
+        if (!isValidHandle(handle))
+            return null;
+        const index = indexOf(handle);
+        if (this.generations[index] !== genOf(handle))
+            return null;
+        return this.ids[index] ?? null;
+    }
+    /**
+     * Return `true` if the handle points to a currently-live slot.
+     */
+    isAlive(handle) {
+        if (!isValidHandle(handle))
+            return false;
+        const index = indexOf(handle);
+        return this.generations[index] === genOf(handle) && this.ids[index] !== null;
+    }
+    /** Number of currently-live slots. */
+    get size() {
+        return this.nextSlot - this.freeList.length;
+    }
+}
+//# sourceMappingURL=EntityHandle.js.map

package/dist/entity/EntityHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityHandle.js","sourceRoot":"","sources":["../../src/entity/EntityHandle.ts"],"names":[],"mappings":"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"}

package/dist/entity/index.d.ts

@@ -1,3 +1,5 @@
 export type { IEntity } from './IEntity';
 export type { IComponent } from './IComponent';
+export type { EntityHandle } from './EntityHandle';
+export { NULL_HANDLE, makeHandle, indexOf, genOf, isValidHandle, handleToString, EntityHandleManager, } from './EntityHandle';
 //# sourceMappingURL=index.d.ts.map

package/dist/entity/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EACL,WAAW,EACX,UAAU,EACV,OAAO,EACP,KAAK,EACL,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/entity/index.js

@@ -1,2 +1,2 @@
-export {};
+export { NULL_HANDLE, makeHandle, indexOf, genOf, isValidHandle, handleToString, EntityHandleManager, } from './EntityHandle';
 //# sourceMappingURL=index.js.map

package/dist/entity/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,WAAW,EACX,UAAU,EACV,OAAO,EACP,KAAK,EACL,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}