@alife-sdk/core 0.1.1 → 0.4.0

package/dist/ai/StateMachine.d.ts

@@ -18,13 +18,51 @@ export type TransitionResult = {
     readonly success: false;
     readonly reason: 'not_allowed' | 'exit_guard' | 'enter_guard';
 };
+export interface StateTransitionEvent {
+    readonly from: string;
+    readonly to: string;
+    readonly timestamp: number;
+}
 export declare class StateMachine {
     private currentStateId;
+    private previousStateId;
+    private stateEnterTime;
     private readonly registry;
     private readonly entity;
+    private readonly enterListeners;
+    private readonly exitListeners;
+    private readonly changeListeners;
+    private readonly historyLog;
     constructor(entity: IEntity, registry: AIStateRegistry, initialState: string);
     /** Current active state identifier. */
     get state(): string;
+    /** Previous state identifier, or `null` if no transition has occurred yet. */
+    get previous(): string | null;
+    /** Milliseconds elapsed since entering the current state. */
+    get currentStateDuration(): number;
+    /** Returns `true` if the current state has the given tag. */
+    hasTag(tag: string): boolean;
+    /** Returns the metadata object of the current state, or `undefined`. */
+    get metadata(): Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Subscribe to the moment the FSM enters `state`.
+     * @returns Unsubscribe function.
+     */
+    onEnter(state: string, callback: (from: string | null) => void): () => void;
+    /**
+     * Subscribe to the moment the FSM exits `state`.
+     * @returns Unsubscribe function.
+     */
+    onExit(state: string, callback: (to: string) => void): () => void;
+    /**
+     * Subscribe to any state change.
+     * @returns Unsubscribe function.
+     */
+    onChange(callback: (from: string, to: string) => void): () => void;
+    /** Returns a snapshot of the transition history (oldest first). */
+    getHistory(): readonly StateTransitionEvent[];
+    /** Clears the transition history. */
+    clearHistory(): void;
     /**
      * Force transition to a new state.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"StateMachine.d.ts","sourceRoot":"","sources":["../../src/ai/StateMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,GAAG,aAAa,CAAA;CAAE,CAAC;AAE/F,qBAAa,YAAY;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;gBAErB,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM;IAa5E,uCAAuC;IACvC,IAAI,KAAK,IAAI,MAAM,CAElB;IAMD;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAsB9C;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAkB3B,iEAAiE;IACjE,OAAO,IAAI,IAAI;CAIhB"}
+{"version":3,"file":"StateMachine.d.ts","sourceRoot":"","sources":["../../src/ai/StateMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,GAAG,aAAa,CAAA;CAAE,CAAC;AAE/F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IAEjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyD;IACxF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgD;IAC9E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiD;IACjF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;gBAE7C,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM;IAc5E,uCAAuC;IACvC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,8EAA8E;IAC9E,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,6DAA6D;IAC7D,IAAI,oBAAoB,IAAI,MAAM,CAEjC;IAMD,6DAA6D;IAC7D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK5B,wEAAwE;IACxE,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAE5D;IAMD;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI;IAM3E;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAMjE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IASlE,mEAAmE;IACnE,UAAU,IAAI,SAAS,oBAAoB,EAAE;IAI7C,qCAAqC;IACrC,YAAY,IAAI,IAAI;IAQpB;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAwC9C;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAkB3B,iEAAiE;IACjE,OAAO,IAAI,IAAI;CAIhB"}

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":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,OAAO,YAAY;IAYvB,YAAY,MAAe,EAAE,QAAyB,EAAE,YAAoB;QAVpE,oBAAe,GAAkB,IAAI,CAAC;QAK7B,mBAAc,GAAG,IAAI,GAAG,EAA8C,CAAC;QACvE,kBAAa,GAAG,IAAI,GAAG,EAAqC,CAAC;QAC7D,oBAAe,GAAG,IAAI,GAAG,EAAsC,CAAC;QAChE,eAAU,GAA2B,EAAE,CAAC;QAGvD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,cAAc,GAAG,YAAY,CAAC;QACnC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEjC,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,8EAA8E;IAC9E,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED,6DAA6D;IAC7D,IAAI,oBAAoB;QACtB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC;IAC1C,CAAC;IAED,0EAA0E;IAC1E,cAAc;IACd,0EAA0E;IAE1E,6DAA6D;IAC7D,MAAM,CAAC,GAAW;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACtD,OAAO,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC;IAC3C,CAAC;IAED,wEAAwE;IACxE,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC7D,CAAC;IAED,0EAA0E;IAC1E,sBAAsB;IACtB,0EAA0E;IAE1E;;;OAGG;IACH,OAAO,CAAC,KAAa,EAAE,QAAuC;QAC5D,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QAC/E,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9C,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChE,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAa,EAAE,QAA8B;QAClD,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QAC7E,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7C,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/D,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,QAA4C;QACnD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED,0EAA0E;IAC1E,UAAU;IACV,0EAA0E;IAE1E,mEAAmE;IACnE,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,qCAAqC;IACrC,YAAY;QACV,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,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,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,CAAC;QAEjC,OAAO;QACP,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QAE1D,gBAAgB;QAChB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;QAC/B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEjC,iBAAiB;QACjB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QAE7E,0BAA0B;QAC1B,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;QAEvD,QAAQ;QACR,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QAE3D,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"}

package/dist/ai/WorldState.d.ts

@@ -17,6 +17,14 @@ export type WorldStateValue = boolean | number | string;
 export declare class WorldState {
     private readonly properties;
     set(key: string, value: WorldStateValue): void;
+    /**
+     * Create a WorldState from a plain object.
+     * Equivalent to calling set() for each key-value pair.
+     *
+     * @example
+     * const ws = WorldState.from({ hasAmmo: true, underFire: false, ammoCount: 3 });
+     */
+    static from(props: Record<string, WorldStateValue>): WorldState;
     get(key: string): WorldStateValue | undefined;
     has(key: string): boolean;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"WorldState.d.ts","sourceRoot":"","sources":["../../src/ai/WorldState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IAMjE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAQ9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI7C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQzB;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAQpC,0BAA0B;IAC1B,KAAK,IAAI,UAAU;IAQnB;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IAUrC;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU;IAQ7C,8EAA8E;IAC9E,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;CAGjC"}
+{"version":3,"file":"WorldState.d.ts","sourceRoot":"","sources":["../../src/ai/WorldState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IAMjE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAI9C;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,UAAU;IAY/D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI7C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQzB;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAQpC,0BAA0B;IAC1B,KAAK,IAAI,UAAU;IAQnB;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IAUrC;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU;IAQ7C,8EAA8E;IAC9E,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;CAGjC"}

package/dist/ai/WorldState.js

@@ -23,6 +23,20 @@ export class WorldState {
     set(key, value) {
         this.properties.set(key, value);
     }
+    /**
+     * Create a WorldState from a plain object.
+     * Equivalent to calling set() for each key-value pair.
+     *
+     * @example
+     * const ws = WorldState.from({ hasAmmo: true, underFire: false, ammoCount: 3 });
+     */
+    static from(props) {
+        const state = new WorldState();
+        for (const [key, value] of Object.entries(props)) {
+            state.set(key, value);
+        }
+        return state;
+    }
     // -----------------------------------------------------------------------
     // Accessors
     // -----------------------------------------------------------------------

package/dist/ai/WorldState.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorldState.js","sourceRoot":"","sources":["../../src/ai/WorldState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,OAAO,UAAU;IAAvB;QACmB,eAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;IAmFnE,CAAC;IAjFC,0EAA0E;IAC1E,WAAW;IACX,0EAA0E;IAE1E,GAAG,CAAC,GAAW,EAAE,KAAsB;QACrC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,0EAA0E;IAC1E,YAAY;IACZ,0EAA0E;IAE1E,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,0EAA0E;IAC1E,qBAAqB;IACrB,0EAA0E;IAE1E;;;;;;OAMG;IACH,SAAS,CAAC,IAAgB;QACxB,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,YAAY,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0BAA0B;IAC1B,KAAK;QACH,MAAM,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,KAAiB;QAC1B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC;gBACvC,KAAK,EAAE,CAAC;YACV,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,OAAmB;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8EAA8E;IAC9E,IAAI;QACF,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IAChC,CAAC;CACF"}
+{"version":3,"file":"WorldState.js","sourceRoot":"","sources":["../../src/ai/WorldState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,OAAO,UAAU;IAAvB;QACmB,eAAU,GAAG,IAAI,GAAG,EAA2B,CAAC;IAkGnE,CAAC;IAhGC,0EAA0E;IAC1E,WAAW;IACX,0EAA0E;IAE1E,GAAG,CAAC,GAAW,EAAE,KAAsB;QACrC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,KAAsC;QAChD,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0EAA0E;IAC1E,YAAY;IACZ,0EAA0E;IAE1E,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,0EAA0E;IAC1E,qBAAqB;IACrB,0EAA0E;IAE1E;;;;;;OAMG;IACH,SAAS,CAAC,IAAgB;QACxB,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC/C,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,YAAY,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0BAA0B;IAC1B,KAAK;QACH,MAAM,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,KAAiB;QAC1B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC;gBACvC,KAAK,EAAE,CAAC;YACV,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,OAAmB;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YAC9C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8EAA8E;IAC9E,IAAI;QACF,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IAChC,CAAC;CACF"}

package/dist/ai/index.d.ts

@@ -1,10 +1,14 @@
 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';
 export type { IDangerEntry } from './DangerManager';
 export { WorldState } from './WorldState';
+export type { WorldStateValue } from './WorldState';
 export { GOAPPlanner } from './GOAPPlanner';
 export { GOAPAction, ActionStatus } from './GOAPAction';
+export type { GOAPActionDef } 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,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,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;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAExD,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"}