@alife-sdk/core 0.1.0

package/dist/ai/GOAPPlanner.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A*-based GOAP (Goal-Oriented Action Planning) solver.
+ *
+ * The planner treats the problem as a graph search:
+ *   - Each NODE is a world state reachable by applying a sequence of actions.
+ *   - Each EDGE is a GOAPAction whose preconditions are satisfied by the
+ *     node's world state and whose effects advance toward the goal.
+ *   - The cost of a path is the sum of action cost values along it.
+ *   - The heuristic is state.distanceTo(goal) -- the count of unsatisfied
+ *     goal properties (admissible, since each action satisfies at most one).
+ *
+ * Complexity:
+ *   Time:  O(b^d) where b = |availableActions|, d = plan depth (<= maxDepth)
+ *   Space: O(b^d) for the open/closed sets, bounded by maxDepth
+ */
+import type { GOAPAction } from './GOAPAction';
+import type { WorldState } from './WorldState';
+export declare class GOAPPlanner {
+    private readonly actions;
+    private readonly defaultMaxDepth;
+    private _sortedKeys;
+    private readonly _closed;
+    private readonly _actionKeys;
+    private readonly _open;
+    constructor(defaultMaxDepth?: number);
+    /** Register an action that the planner can use when building plans. */
+    registerAction(action: GOAPAction): void;
+    /**
+     * Find the optimal action sequence from the current state to the goal.
+     *
+     * @param currentState - Live world state snapshot for the agent.
+     * @param goal         - Desired world state the agent wants to achieve.
+     * @param maxDepth     - Maximum plan depth (default 10).
+     * @returns Ordered action list (index 0 = first), or null if no plan found.
+     */
+    plan(currentState: WorldState, goal: WorldState, maxDepth?: number): GOAPAction[] | null;
+    /** Walk from goal node to root, collecting actions in execution order. */
+    private reconstructPlan;
+    /** Push a node onto the min-heap. */
+    private _heapPush;
+    /** Pop the node with the smallest f value from the min-heap. */
+    private _heapPop;
+    /** Restore heap property upward from index i. */
+    private _heapSiftUp;
+    /** Restore heap property downward from index i. */
+    private _heapSiftDown;
+    /**
+     * Create a compact numeric fingerprint of ALL world-state values.
+     *
+     * For boolean-only states (the common case with DEFAULT_WORLD_PROPERTY_BUILDERS),
+     * encodes as a 31-bit bitmask — zero allocations. Result is always non-negative
+     * (0 to 2^31-1). Falls back to djb2 hash when:
+     *   - key universe exceeds 31 keys (C2: avoids sign-bit corruption at i=31)
+     *   - an explicit `false` value is present (C1: distinguishes false from absent)
+     *   - a non-boolean value is present
+     * djb2 results are tagged with 0x80000000, making them always negative and
+     * thus disjoint from the bitmask domain (C3: no cross-domain collisions).
+     */
+    private fingerprint;
+    /**
+     * Build the sorted key universe from current state, goal, and cached
+     * action keys. Ensures the bitmask fingerprint covers every key that
+     * can appear during planning.
+     *
+     * P21: Action keys are accumulated incrementally in registerAction(),
+     * so this method only needs to union them with state/goal keys.
+     */
+    private _buildKeyUniverse;
+    /**
+     * djb2 hash fallback for WorldStates containing non-boolean values,
+     * explicit `false` keys, or key universes larger than 31.
+     *
+     * C3: Result is always tagged with 0x80000000, making it a negative
+     * int32. This keeps the djb2 domain (negative) disjoint from the
+     * bitmask domain (non-negative, 0 to 2^30), preventing cross-domain
+     * fingerprint collisions.
+     */
+    private fingerprintHash;
+}
+//# sourceMappingURL=GOAPPlanner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GOAPPlanner.d.ts","sourceRoot":"","sources":["../../src/ai/GOAPPlanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAiC/C,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAGzC,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAG7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IAGjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;gBAE5B,eAAe,GAAE,MAA0B;IAIvD,uEAAuE;IACvE,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAQxC;;;;;;;OAOG;IACH,IAAI,CACF,YAAY,EAAE,UAAU,EACxB,IAAI,EAAE,UAAU,EAChB,QAAQ,GAAE,MAA6B,GACtC,UAAU,EAAE,GAAG,IAAI;IA+EtB,0EAA0E;IAC1E,OAAO,CAAC,eAAe;IAiBvB,qCAAqC;IACrC,OAAO,CAAC,SAAS;IAKjB,gEAAgE;IAChE,OAAO,CAAC,QAAQ;IAchB,iDAAiD;IACjD,OAAO,CAAC,WAAW;IAYnB,mDAAmD;IACnD,OAAO,CAAC,aAAa;IAiBrB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,WAAW;IA2BnB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;CAYxB"}

package/dist/ai/GOAPPlanner.js

@@ -0,0 +1,259 @@
+/**
+ * A*-based GOAP (Goal-Oriented Action Planning) solver.
+ *
+ * The planner treats the problem as a graph search:
+ *   - Each NODE is a world state reachable by applying a sequence of actions.
+ *   - Each EDGE is a GOAPAction whose preconditions are satisfied by the
+ *     node's world state and whose effects advance toward the goal.
+ *   - The cost of a path is the sum of action cost values along it.
+ *   - The heuristic is state.distanceTo(goal) -- the count of unsatisfied
+ *     goal properties (admissible, since each action satisfies at most one).
+ *
+ * Complexity:
+ *   Time:  O(b^d) where b = |availableActions|, d = plan depth (<= maxDepth)
+ *   Space: O(b^d) for the open/closed sets, bounded by maxDepth
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_DEPTH = 10;
+// ---------------------------------------------------------------------------
+// GOAPPlanner
+// ---------------------------------------------------------------------------
+export class GOAPPlanner {
+    constructor(defaultMaxDepth = DEFAULT_MAX_DEPTH) {
+        this.actions = [];
+        // Scratch fields — reused across plan() calls
+        this._sortedKeys = null;
+        this._closed = new Set();
+        // P21: Incrementally accumulated keys from all registered actions.
+        this._actionKeys = new Set();
+        // P19: Binary min-heap storage for the open set (reused across plan() calls).
+        this._open = [];
+        this.defaultMaxDepth = defaultMaxDepth;
+    }
+    /** Register an action that the planner can use when building plans. */
+    registerAction(action) {
+        this.actions.push(action);
+        // P21: Cache action keys incrementally.
+        for (const k of action.getPreconditions().keys())
+            this._actionKeys.add(k);
+        for (const k of action.getEffects().keys())
+            this._actionKeys.add(k);
+    }
+    /**
+     * Find the optimal action sequence from the current state to the goal.
+     *
+     * @param currentState - Live world state snapshot for the agent.
+     * @param goal         - Desired world state the agent wants to achieve.
+     * @param maxDepth     - Maximum plan depth (default 10).
+     * @returns Ordered action list (index 0 = first), or null if no plan found.
+     */
+    plan(currentState, goal, maxDepth = this.defaultMaxDepth) {
+        const root = {
+            state: currentState.clone(),
+            action: null,
+            parent: null,
+            g: 0,
+            h: currentState.distanceTo(goal),
+            f: currentState.distanceTo(goal),
+            depth: 0,
+        };
+        // P19: Reuse heap storage, clear from previous plan() call.
+        const open = this._open;
+        open.length = 0;
+        this._heapPush(root);
+        // Build sorted key universe from current state + goal + cached action keys.
+        // This ensures the bitmask covers ALL keys that can appear during planning.
+        this._buildKeyUniverse(currentState, goal);
+        // Closed set: bitmask fingerprints to prevent re-expansion.
+        this._closed.clear();
+        while (open.length > 0) {
+            const current = this._heapPop();
+            // Goal check.
+            if (current.state.satisfies(goal)) {
+                return this.reconstructPlan(current);
+            }
+            // P20: Depth limit using stored depth.
+            if (current.depth >= maxDepth) {
+                continue;
+            }
+            // Mark visited.
+            const stateKey = this.fingerprint(current.state);
+            if (this._closed.has(stateKey)) {
+                continue;
+            }
+            this._closed.add(stateKey);
+            // Expand: try each action whose preconditions are met.
+            for (const action of this.actions) {
+                if (!current.state.satisfies(action.getPreconditions())) {
+                    continue;
+                }
+                // Apply action effects using WorldState's public API.
+                const nextState = current.state.applyEffects(action.getEffects());
+                const g = current.g + action.cost;
+                const h = nextState.distanceTo(goal);
+                const successor = {
+                    state: nextState,
+                    action,
+                    parent: current,
+                    g,
+                    h,
+                    f: g + h,
+                    depth: current.depth + 1,
+                };
+                const successorKey = this.fingerprint(nextState);
+                if (!this._closed.has(successorKey)) {
+                    this._heapPush(successor);
+                }
+            }
+        }
+        // No plan found.
+        return null;
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    /** Walk from goal node to root, collecting actions in execution order. */
+    reconstructPlan(goalNode) {
+        const plan = [];
+        let node = goalNode;
+        while (node !== null && node.action !== null) {
+            plan.push(node.action);
+            node = node.parent;
+        }
+        plan.reverse();
+        return plan;
+    }
+    // -----------------------------------------------------------------------
+    // P19: Binary min-heap (keyed on f)
+    // -----------------------------------------------------------------------
+    /** Push a node onto the min-heap. */
+    _heapPush(node) {
+        this._open.push(node);
+        this._heapSiftUp(this._open.length - 1);
+    }
+    /** Pop the node with the smallest f value from the min-heap. */
+    _heapPop() {
+        const heap = this._open;
+        if (heap.length === 0) {
+            throw new Error('GOAPPlanner._heapPop: heap is empty');
+        }
+        const top = heap[0];
+        const last = heap.pop();
+        if (heap.length > 0) {
+            heap[0] = last;
+            this._heapSiftDown(0);
+        }
+        return top;
+    }
+    /** Restore heap property upward from index i. */
+    _heapSiftUp(i) {
+        const heap = this._open;
+        const node = heap[i];
+        while (i > 0) {
+            const parentIdx = (i - 1) >>> 1;
+            if (heap[parentIdx].f <= node.f)
+                break;
+            heap[i] = heap[parentIdx];
+            i = parentIdx;
+        }
+        heap[i] = node;
+    }
+    /** Restore heap property downward from index i. */
+    _heapSiftDown(i) {
+        const heap = this._open;
+        const len = heap.length;
+        const node = heap[i];
+        while (true) {
+            let smallest = i;
+            const left = 2 * i + 1;
+            const right = 2 * i + 2;
+            if (left < len && heap[left].f < heap[smallest].f)
+                smallest = left;
+            if (right < len && heap[right].f < heap[smallest].f)
+                smallest = right;
+            if (smallest === i)
+                break;
+            heap[i] = heap[smallest];
+            i = smallest;
+        }
+        heap[i] = node;
+    }
+    /**
+     * Create a compact numeric fingerprint of ALL world-state values.
+     *
+     * For boolean-only states (the common case with DEFAULT_WORLD_PROPERTY_BUILDERS),
+     * encodes as a 31-bit bitmask — zero allocations. Result is always non-negative
+     * (0 to 2^31-1). Falls back to djb2 hash when:
+     *   - key universe exceeds 31 keys (C2: avoids sign-bit corruption at i=31)
+     *   - an explicit `false` value is present (C1: distinguishes false from absent)
+     *   - a non-boolean value is present
+     * djb2 results are tagged with 0x80000000, making them always negative and
+     * thus disjoint from the bitmask domain (C3: no cross-domain collisions).
+     */
+    fingerprint(state) {
+        const keys = this._sortedKeys;
+        // C2: fall through to hash when key universe exceeds safe bitmask capacity.
+        // Using 31 bits avoids sign-bit issues with `1 << 31` in 32-bit signed int.
+        if (keys.length >= 31) {
+            return this.fingerprintHash(state);
+        }
+        let mask = 0;
+        for (let i = 0; i < keys.length; i++) {
+            const val = state.get(keys[i]);
+            if (val === true) {
+                mask |= (1 << i);
+            }
+            else if (val === false) {
+                // C1: explicit false vs absent key (undefined) are semantically different
+                // in WorldState.satisfies() — must use hash to distinguish them.
+                return this.fingerprintHash(state);
+            }
+            else if (val !== undefined) {
+                // Non-boolean value — use hash.
+                return this.fingerprintHash(state);
+            }
+            // undefined (absent key): bit stays 0.
+        }
+        return mask; // Non-negative: 0 to 2^30
+    }
+    /**
+     * Build the sorted key universe from current state, goal, and cached
+     * action keys. Ensures the bitmask fingerprint covers every key that
+     * can appear during planning.
+     *
+     * P21: Action keys are accumulated incrementally in registerAction(),
+     * so this method only needs to union them with state/goal keys.
+     */
+    _buildKeyUniverse(currentState, goal) {
+        const keySet = new Set(this._actionKeys);
+        for (const k of currentState.keys())
+            keySet.add(k);
+        for (const k of goal.keys())
+            keySet.add(k);
+        this._sortedKeys = [...keySet].sort();
+    }
+    /**
+     * djb2 hash fallback for WorldStates containing non-boolean values,
+     * explicit `false` keys, or key universes larger than 31.
+     *
+     * C3: Result is always tagged with 0x80000000, making it a negative
+     * int32. This keeps the djb2 domain (negative) disjoint from the
+     * bitmask domain (non-negative, 0 to 2^30), preventing cross-domain
+     * fingerprint collisions.
+     */
+    fingerprintHash(state) {
+        let h = 5381;
+        for (const key of this._sortedKeys) {
+            const val = state.get(key);
+            const str = `${key}:${val}`;
+            for (let i = 0; i < str.length; i++) {
+                h = ((h << 5) + h) + str.charCodeAt(i);
+            }
+        }
+        // Tag with high bit: result is always negative (int32), disjoint from bitmask.
+        return h | 0x80000000;
+    }
+}
+//# sourceMappingURL=GOAPPlanner.js.map

package/dist/ai/GOAPPlanner.js.map

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

package/dist/ai/IStateHandler.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Convenience re-exports from AIStateRegistry for clean import paths.
+ *
+ * Consumers can import directly from this module:
+ *   import type { IStateHandler } from '../ai/IStateHandler';
+ */
+export type { IStateHandler, ITransitionCondition, IAIStateDefinition, } from '../registry/AIStateRegistry';
+//# sourceMappingURL=IStateHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IStateHandler.d.ts","sourceRoot":"","sources":["../../src/ai/IStateHandler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC"}

package/dist/ai/IStateHandler.js

@@ -0,0 +1,8 @@
+/**
+ * Convenience re-exports from AIStateRegistry for clean import paths.
+ *
+ * Consumers can import directly from this module:
+ *   import type { IStateHandler } from '../ai/IStateHandler';
+ */
+export {};
+//# sourceMappingURL=IStateHandler.js.map

package/dist/ai/IStateHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IStateHandler.js","sourceRoot":"","sources":["../../src/ai/IStateHandler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/ai/MemorySystem.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Multi-channel memory bank with confidence decay.
+ *
+ * MemoryBank provides per-NPC episodic memory storage. Memories are
+ * categorised by channel (visual, sound, hit, danger) and decay over time.
+ * Records below the minimum confidence threshold are pruned automatically
+ * during update().
+ *
+ * Storage layout: Map keyed by sourceId for O(1) read/write per entry.
+ * A single entity may have at most one record per sourceId; newer
+ * observations overwrite older ones.
+ */
+import type { Vec2 } from '../core/Vec2';
+export declare const MemoryChannel: {
+    readonly VISUAL: "visual";
+    readonly SOUND: "sound";
+    readonly HIT: "hit";
+    readonly DANGER: "danger";
+};
+export type MemoryChannel = (typeof MemoryChannel)[keyof typeof MemoryChannel] | (string & {});
+export interface MemoryRecord {
+    readonly sourceId: string;
+    readonly channel: MemoryChannel;
+    readonly position: Vec2;
+    /** Confidence level in [0, 1]. Decays over time. */
+    readonly confidence: number;
+    /** Timestamp (accumulated delta or game time) when record was last updated. */
+    readonly timestamp: number;
+}
+/** Configuration for MemoryBank construction. */
+export interface IMemoryBankConfig {
+    /** Time provider for timestamps. Required for deterministic behavior. */
+    readonly timeFn: () => number;
+    /** Maximum memory entries kept per NPC. Default: 32. */
+    readonly maxRecords?: number;
+    /** Confidence decay rate per second. Default: 0.1. */
+    readonly decayRate?: number;
+    /** Confidence below which a record is pruned. Default: 0.05. */
+    readonly minConfidence?: number;
+    /** Per-channel decay rate overrides. Keys are MemoryChannel values. Falls back to global decayRate when a channel is not present. */
+    readonly channelDecayRates?: Readonly<Record<string, number>>;
+}
+export interface IMemoryInput {
+    readonly sourceId: string;
+    readonly channel: MemoryChannel;
+    readonly position: Vec2;
+    readonly confidence?: number;
+}
+export declare class MemoryBank {
+    private readonly records;
+    private readonly byChannel;
+    private readonly maxRecords;
+    private readonly decayRate;
+    private readonly minConfidence;
+    private readonly timeFn;
+    private readonly channelDecayRates?;
+    private readonly _toDelete;
+    constructor(config: IMemoryBankConfig);
+    /**
+     * Add or update a memory record.
+     *
+     * If a record for this sourceId already exists, its position and timestamp
+     * are updated and confidence is reset to the provided value (default 1.0).
+     * If the bank is at capacity, the lowest-confidence record is evicted.
+     */
+    remember(input: IMemoryInput): void;
+    /** Get memory of a specific source. */
+    recall(sourceId: string): MemoryRecord | undefined;
+    /** Get all records on a specific channel. */
+    getByChannel(channel: MemoryChannel): MemoryRecord[];
+    /** Get the highest-confidence record, or undefined if the bank is empty. */
+    getMostConfident(): MemoryRecord | undefined;
+    /**
+     * Decay all records and remove those below the minimum confidence threshold.
+     *
+     * @param deltaSec      - Seconds elapsed since the last update.
+     * @param minConfidence - Records below this threshold are pruned.
+     */
+    update(deltaSec: number): void;
+    /** Forget a specific source. */
+    forget(sourceId: string): void;
+    /** Clear all memories. */
+    clear(): void;
+    get size(): number;
+    serialize(): MemoryRecord[];
+    restore(records: MemoryRecord[]): void;
+    /** Evict the record with the lowest confidence to make room. */
+    private evictLowestConfidence;
+    /** Add a record to the byChannel secondary index. */
+    private addToChannelIndex;
+    /** Remove a record from the byChannel secondary index. */
+    private removeFromChannelIndex;
+}
+//# sourceMappingURL=MemorySystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemorySystem.d.ts","sourceRoot":"","sources":["../../src/ai/MemorySystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAMzC,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAM/F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAcD,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qIAAqI;IACrI,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC/D;AAMD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAmC;IACtE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,MAAM,EAAE,iBAAiB;IAYrC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAoCnC,uCAAuC;IACvC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIlD,6CAA6C;IAC7C,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,EAAE;IAMpD,4EAA4E;IAC5E,gBAAgB,IAAI,YAAY,GAAG,SAAS;IAgB5C;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAsB9B,gCAAgC;IAChC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ9B,0BAA0B;IAC1B,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI,MAAM,CAEjB;IAMD,SAAS,IAAI,YAAY,EAAE;IAU3B,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI;IActC,gEAAgE;IAChE,OAAO,CAAC,qBAAqB;IAoB7B,qDAAqD;IACrD,OAAO,CAAC,iBAAiB;IASzB,0DAA0D;IAC1D,OAAO,CAAC,sBAAsB;CAM/B"}