@alife-sdk/ai 0.1.0

package/dist/navigation/RestrictedZoneManager.js

@@ -0,0 +1,179 @@
+// navigation/RestrictedZoneManager.ts
+// Instance-based restricted zone management.
+// Handles hard constraints (IN/OUT) and soft danger avoidance.
+/**
+ * Zone restriction types.
+ * - IN: NPC must stay inside the zone.
+ * - OUT: NPC cannot enter the zone.
+ * - DANGER: Soft avoidance — NPC prefers to avoid but can enter.
+ */
+export const RestrictionType = {
+    IN: 0,
+    OUT: 1,
+    DANGER: 2,
+};
+/**
+ * Manages circular no-go and soft-avoidance zones for NPC movement.
+ *
+ * Instance-based — create one per simulation. No global state.
+ *
+ * @example
+ * ```ts
+ * const zones = new RestrictedZoneManager(20); // 20px safety margin
+ * zones.addZone({ id: 'rad_1', type: RestrictionType.OUT, x: 100, y: 100, radius: 50, active: true });
+ *
+ * if (!zones.accessible(110, 110)) {
+ *   const safe = zones.getSafeDirection(110, 110);
+ *   // Move NPC along safe.dx, safe.dy
+ * }
+ * ```
+ */
+export class RestrictedZoneManager {
+    constructor(safeMargin) {
+        this.zones = new Map();
+        this.safeMargin = safeMargin;
+    }
+    // -----------------------------------------------------------------
+    // Zone Lifecycle
+    // -----------------------------------------------------------------
+    addZone(zone) {
+        this.zones.set(zone.id, zone);
+    }
+    removeZone(id) {
+        this.zones.delete(id);
+    }
+    setActive(id, active) {
+        const zone = this.zones.get(id);
+        if (zone)
+            zone.active = active;
+    }
+    removeByMetadata(tag) {
+        const toDelete = [];
+        for (const [id, zone] of this.zones) {
+            if (zone.metadata === tag)
+                toDelete.push(id);
+        }
+        for (const id of toDelete)
+            this.zones.delete(id);
+    }
+    getAllZones() {
+        return [...this.zones.values()];
+    }
+    getZonesAt(x, y) {
+        const result = [];
+        for (const zone of this.zones.values()) {
+            if (!zone.active)
+                continue;
+            const dx = x - zone.x;
+            const dy = y - zone.y;
+            if (dx * dx + dy * dy <= zone.radius * zone.radius) {
+                result.push(zone);
+            }
+        }
+        return result;
+    }
+    get size() {
+        return this.zones.size;
+    }
+    clear() {
+        this.zones.clear();
+    }
+    // -----------------------------------------------------------------
+    // Hard Constraint Check
+    // -----------------------------------------------------------------
+    /**
+     * Check if a position satisfies all hard zone constraints.
+     *
+     * - OUT zones: position must be outside (radius + safeMargin).
+     * - IN zones: position must be inside zone radius.
+     * - DANGER zones: ignored (soft avoidance only).
+     *
+     * Uses squared-distance for performance. Early-exit on first violation.
+     */
+    accessible(x, y) {
+        for (const zone of this.zones.values()) {
+            if (!zone.active)
+                continue;
+            const dx = x - zone.x;
+            const dy = y - zone.y;
+            const distSq = dx * dx + dy * dy;
+            if (zone.type === RestrictionType.OUT) {
+                const effectiveR = zone.radius + this.safeMargin;
+                if (distSq < effectiveR * effectiveR)
+                    return false;
+            }
+            else if (zone.type === RestrictionType.IN) {
+                if (distSq > zone.radius * zone.radius)
+                    return false;
+            }
+        }
+        return true;
+    }
+    // -----------------------------------------------------------------
+    // Soft Danger Check
+    // -----------------------------------------------------------------
+    /**
+     * Check if a position is inside any active DANGER zone.
+     * Does not prevent movement — used to trigger escape behavior.
+     */
+    isDangerous(x, y) {
+        for (const zone of this.zones.values()) {
+            if (!zone.active || zone.type !== RestrictionType.DANGER)
+                continue;
+            const dx = x - zone.x;
+            const dy = y - zone.y;
+            if (dx * dx + dy * dy <= zone.radius * zone.radius)
+                return true;
+        }
+        return false;
+    }
+    // -----------------------------------------------------------------
+    // Escape Direction
+    // -----------------------------------------------------------------
+    /**
+     * Compute a normalized direction vector to move away from the nearest
+     * active OUT or DANGER zone that contains this point.
+     *
+     * @returns Unit vector `{x, y}` pointing away from the zone center,
+     *          or null if the position is already safe.
+     */
+    getSafeDirection(x, y) {
+        let nearest = null;
+        let nearestDistSq = Infinity;
+        for (const zone of this.zones.values()) {
+            if (!zone.active)
+                continue;
+            if (zone.type !== RestrictionType.OUT && zone.type !== RestrictionType.DANGER)
+                continue;
+            const dx = x - zone.x;
+            const dy = y - zone.y;
+            const distSq = dx * dx + dy * dy;
+            const effectiveR = zone.type === RestrictionType.OUT
+                ? zone.radius + this.safeMargin
+                : zone.radius;
+            if (distSq < effectiveR * effectiveR && distSq < nearestDistSq) {
+                nearestDistSq = distSq;
+                nearest = zone;
+            }
+        }
+        if (!nearest)
+            return null;
+        const dx = x - nearest.x;
+        const dy = y - nearest.y;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        if (dist < 1e-6)
+            return { x: 1, y: 0 };
+        return { x: dx / dist, y: dy / dist };
+    }
+    // -----------------------------------------------------------------
+    // Waypoint Filtering
+    // -----------------------------------------------------------------
+    /**
+     * Filter a list of waypoints to only those in accessible positions.
+     * O(waypoints × zones).
+     */
+    filterAccessibleWaypoints(waypoints) {
+        return waypoints.filter((wp) => this.accessible(wp.x, wp.y));
+    }
+}
+//# sourceMappingURL=RestrictedZoneManager.js.map

package/dist/navigation/RestrictedZoneManager.js.map

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

package/dist/navigation/SmoothPathFollower.d.ts

@@ -0,0 +1,55 @@
+import type { Vec2 } from '@alife-sdk/core';
+import type { INavigationConfig } from '../types/IOnlineAIConfig';
+/**
+ * Tracks an NPC's progress along a smooth dense path.
+ *
+ * The follower advances a cursor through the point array and
+ * provides a curvature-derived velocity multiplier with smooth
+ * easing between speed bands.
+ *
+ * @example
+ * ```ts
+ * const follower = new SmoothPathFollower(densePoints, config);
+ *
+ * // Each frame:
+ * follower.updatePosition(npc.x, npc.y);
+ * const target = follower.getCurrentTarget();
+ * const speed = baseSpeed * follower.getCurrentVelocityMultiplier();
+ * ```
+ */
+export declare class SmoothPathFollower {
+    private readonly points;
+    private readonly velocityMultipliers;
+    private readonly thresholdSq;
+    private readonly transitionRate;
+    private currentIndex;
+    private currentVelocityMultiplier;
+    constructor(points: readonly Vec2[], config: INavigationConfig);
+    /**
+     * Advance the cursor if the NPC is close enough to the current target.
+     * @returns `true` if the cursor advanced, `false` if not yet arrived.
+     */
+    updatePosition(x: number, y: number): boolean;
+    /** Current waypoint the NPC should move toward, or null if path is done. */
+    getCurrentTarget(): Vec2 | null;
+    /** Whether the NPC has reached the end of the path. */
+    isComplete(): boolean;
+    /**
+     * Smoothed velocity multiplier for the current path segment.
+     * Value in approximately [velocitySlow, velocityFast] — transitions
+     * gradually between speed bands.
+     */
+    getCurrentVelocityMultiplier(): number;
+    /** Reset cursor to the start (for looping patrols). */
+    reset(): void;
+    /** Normalized progress [0, 1]. */
+    getProgress(): number;
+    /** Number of dense points in the smooth path. */
+    getPointCount(): number;
+    /**
+     * Pre-compute a velocity multiplier for each point based on local curvature.
+     * Sharp turns get slow multipliers, straight segments get fast.
+     */
+    private calculateVelocityProfile;
+}
+//# sourceMappingURL=SmoothPathFollower.d.ts.map

package/dist/navigation/SmoothPathFollower.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SmoothPathFollower.d.ts","sourceRoot":"","sources":["../../src/navigation/SmoothPathFollower.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAKlE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAoB;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,yBAAyB,CAAS;gBAE9B,MAAM,EAAE,SAAS,IAAI,EAAE,EAAE,MAAM,EAAE,iBAAiB;IAQ9D;;;OAGG;IACH,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAgB7C,4EAA4E;IAC5E,gBAAgB,IAAI,IAAI,GAAG,IAAI;IAI/B,uDAAuD;IACvD,UAAU,IAAI,OAAO;IAIrB;;;;OAIG;IACH,4BAA4B,IAAI,MAAM;IAStC,uDAAuD;IACvD,KAAK,IAAI,IAAI;IAQb,kCAAkC;IAClC,WAAW,IAAI,MAAM;IAKrB,iDAAiD;IACjD,aAAa,IAAI,MAAM;IAIvB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;CA8CjC"}

package/dist/navigation/SmoothPathFollower.js

@@ -0,0 +1,132 @@
+// navigation/SmoothPathFollower.ts
+// Per-NPC smooth path cursor with curvature-based velocity profiles.
+// Stateful but framework-agnostic — no rendering, no physics.
+const CURVATURE_HIGH_THRESHOLD = 0.04;
+const CURVATURE_MEDIUM_THRESHOLD = 0.015;
+/**
+ * Tracks an NPC's progress along a smooth dense path.
+ *
+ * The follower advances a cursor through the point array and
+ * provides a curvature-derived velocity multiplier with smooth
+ * easing between speed bands.
+ *
+ * @example
+ * ```ts
+ * const follower = new SmoothPathFollower(densePoints, config);
+ *
+ * // Each frame:
+ * follower.updatePosition(npc.x, npc.y);
+ * const target = follower.getCurrentTarget();
+ * const speed = baseSpeed * follower.getCurrentVelocityMultiplier();
+ * ```
+ */
+export class SmoothPathFollower {
+    constructor(points, config) {
+        this.currentIndex = 0;
+        this.points = points;
+        this.thresholdSq = config.arrivalThreshold * config.arrivalThreshold;
+        this.transitionRate = config.velocityTransitionRate;
+        this.velocityMultipliers = this.calculateVelocityProfile(config);
+        this.currentVelocityMultiplier = config.velocityCurveFast;
+    }
+    /**
+     * Advance the cursor if the NPC is close enough to the current target.
+     * @returns `true` if the cursor advanced, `false` if not yet arrived.
+     */
+    updatePosition(x, y) {
+        if (this.isComplete())
+            return false;
+        const target = this.points[this.currentIndex];
+        const dx = target.x - x;
+        const dy = target.y - y;
+        const distSq = dx * dx + dy * dy;
+        if (distSq <= this.thresholdSq) {
+            this.currentIndex++;
+            return true;
+        }
+        return false;
+    }
+    /** Current waypoint the NPC should move toward, or null if path is done. */
+    getCurrentTarget() {
+        return this.isComplete() ? null : this.points[this.currentIndex];
+    }
+    /** Whether the NPC has reached the end of the path. */
+    isComplete() {
+        return this.currentIndex >= this.points.length;
+    }
+    /**
+     * Smoothed velocity multiplier for the current path segment.
+     * Value in approximately [velocitySlow, velocityFast] — transitions
+     * gradually between speed bands.
+     */
+    getCurrentVelocityMultiplier() {
+        if (this.isComplete())
+            return 1.0;
+        const target = this.velocityMultipliers[this.currentIndex] ?? 1.0;
+        this.currentVelocityMultiplier +=
+            (target - this.currentVelocityMultiplier) * this.transitionRate;
+        return this.currentVelocityMultiplier;
+    }
+    /** Reset cursor to the start (for looping patrols). */
+    reset() {
+        this.currentIndex = 0;
+        this.currentVelocityMultiplier =
+            this.velocityMultipliers.length > 0
+                ? this.velocityMultipliers[0]
+                : 1.0;
+    }
+    /** Normalized progress [0, 1]. */
+    getProgress() {
+        if (this.points.length === 0)
+            return 1;
+        return Math.min(1, this.currentIndex / this.points.length);
+    }
+    /** Number of dense points in the smooth path. */
+    getPointCount() {
+        return this.points.length;
+    }
+    /**
+     * Pre-compute a velocity multiplier for each point based on local curvature.
+     * Sharp turns get slow multipliers, straight segments get fast.
+     */
+    calculateVelocityProfile(config) {
+        const pts = this.points;
+        if (pts.length < 3) {
+            return pts.map(() => config.velocityCurveFast);
+        }
+        const profile = new Array(pts.length);
+        for (let i = 1; i < pts.length - 1; i++) {
+            const a = pts[i - 1];
+            const b = pts[i];
+            const c = pts[i + 1];
+            const abx = b.x - a.x;
+            const aby = b.y - a.y;
+            const bcx = c.x - b.x;
+            const bcy = c.y - b.y;
+            const abLen = Math.sqrt(abx * abx + aby * aby);
+            const bcLen = Math.sqrt(bcx * bcx + bcy * bcy);
+            if (abLen < 1e-6 || bcLen < 1e-6) {
+                profile[i] = config.velocityCurveFast;
+                continue;
+            }
+            const dot = (abx * bcx + aby * bcy) / (abLen * bcLen);
+            const theta = Math.acos(Math.max(-1, Math.min(1, dot)));
+            const arcLen = (abLen + bcLen) / 2;
+            const kappa = arcLen > 1e-6 ? theta / arcLen : 0;
+            if (kappa > CURVATURE_HIGH_THRESHOLD) {
+                profile[i] = config.velocityCurveSlow;
+            }
+            else if (kappa > CURVATURE_MEDIUM_THRESHOLD) {
+                profile[i] = config.velocityCurveMedium;
+            }
+            else {
+                profile[i] = config.velocityCurveFast;
+            }
+        }
+        // Endpoints inherit nearest interior value.
+        profile[0] = profile[1] ?? config.velocityCurveFast;
+        profile[pts.length - 1] = profile[pts.length - 2] ?? config.velocityCurveFast;
+        return profile;
+    }
+}
+//# sourceMappingURL=SmoothPathFollower.js.map

package/dist/navigation/SmoothPathFollower.js.map

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

package/dist/navigation/SteeringBehaviors.d.ts

@@ -0,0 +1,123 @@
+import type { Vec2 } from '@alife-sdk/core';
+/**
+ * Tuning parameters for steering / flocking behaviors.
+ * All fields have sensible defaults via {@link createDefaultSteeringConfig}.
+ */
+export interface ISteeringConfig {
+    /** Minimum distance between agents before separation force kicks in (px). @default 40 */
+    readonly separationRadius: number;
+    /** Weight of the separation repulsion force. @default 1.5 */
+    readonly separationWeight: number;
+    /** Radius within which neighbors are considered for cohesion (px). @default 150 */
+    readonly neighborRadius: number;
+    /** Weight of the cohesion attraction force. @default 0.5 */
+    readonly cohesionWeight: number;
+    /** Weight of the alignment direction force (applied by caller via combineForces). @default 0.3 */
+    readonly alignmentWeight: number;
+    /** Maximum magnitude of the final combined steering force (px/s). @default 80 */
+    readonly maxSteeringForce: number;
+}
+/**
+ * Create an {@link ISteeringConfig} with production defaults.
+ * Pass a partial override object to tune individual values without touching the rest.
+ *
+ * @example
+ * const cfg = createDefaultSteeringConfig({ separationRadius: 60 });
+ */
+export declare function createDefaultSteeringConfig(overrides?: Partial<ISteeringConfig>): ISteeringConfig;
+/**
+ * Compute the separation steering force — repulsion away from any neighbor
+ * that is closer than {@link ISteeringConfig.separationRadius}.
+ *
+ * The force is inversely proportional to distance: the closer the neighbor,
+ * the stronger the push.  Neighbors outside the radius are ignored.
+ * Returns {@link ZERO} when `neighbors` is empty or none are within radius.
+ *
+ * @param self      - Position of the NPC computing the force.
+ * @param neighbors - Positions of nearby agents (e.g. from getVisibleAllies()).
+ * @param config    - Steering configuration.
+ */
+export declare function separation(self: Vec2, neighbors: readonly Vec2[], config: ISteeringConfig): Vec2;
+/**
+ * Compute the cohesion steering force — attraction toward the average position
+ * (center of mass) of neighbors within {@link ISteeringConfig.neighborRadius}.
+ *
+ * Returns {@link ZERO} when `neighbors` is empty or none are within the radius.
+ *
+ * @param self      - Position of the NPC computing the force.
+ * @param neighbors - Positions of nearby agents.
+ * @param config    - Steering configuration.
+ */
+export declare function cohesion(self: Vec2, neighbors: readonly Vec2[], config: ISteeringConfig): Vec2;
+/**
+ * Compute the alignment steering force — the average of all provided desired
+ * directions (normalized).
+ *
+ * **API note:** `self` is intentionally absent — alignment depends only on
+ * neighbor directions, not on the caller's own position.  The caller is
+ * responsible for computing `neighborDirections`
+ * (e.g. `normalize(target − npcPos)` for each neighbor's target vector).
+ *
+ * The `alignmentWeight` from config is applied by the caller via
+ * {@link combineForces}, consistent with how separation / cohesion weights work.
+ *
+ * Returns {@link ZERO} when `neighborDirections` is empty.
+ *
+ * @param neighborDirections - Desired movement directions of nearby agents.
+ */
+export declare function alignment(neighborDirections: readonly Vec2[]): Vec2;
+/**
+ * Compute a weighted sum of arbitrary steering forces, clamped to `maxMagnitude`.
+ *
+ * This is the **extensibility escape-hatch**: SDK users can compose any mix of
+ * built-in forces (separation, cohesion, alignment) with their own custom forces
+ * without modifying the SDK.
+ *
+ * @example
+ * const combined = combineForces([
+ *   { force: sep,         weight: cfg.separationWeight },
+ *   { force: coh,         weight: cfg.cohesionWeight   },
+ *   { force: myFormation, weight: 2.0                  },
+ * ], cfg.maxSteeringForce);
+ *
+ * @param forces       - Array of `{ force, weight }` entries to blend.
+ * @param maxMagnitude - Maximum allowed magnitude of the result (px/s).
+ */
+export declare function combineForces(forces: ReadonlyArray<{
+    force: Vec2;
+    weight: number;
+}>, maxMagnitude: number): Vec2;
+/**
+ * Compute the combined separation + cohesion steering force, clamped to
+ * {@link ISteeringConfig.maxSteeringForce}.
+ *
+ * Does **not** include alignment — alignment requires caller-supplied desired
+ * directions (see {@link alignment}).  Use {@link combineForces} to add it.
+ *
+ * Returns {@link ZERO} when `neighbors` is empty.
+ *
+ * @param self      - Position of the NPC.
+ * @param neighbors - Positions of nearby agents.
+ * @param config    - Steering configuration.
+ */
+export declare function computePackSteering(self: Vec2, neighbors: readonly Vec2[], config: ISteeringConfig): Vec2;
+/**
+ * Blend a normalised primary movement direction with a computed steering force.
+ *
+ * Returns `{ vx, vy }` ready for `ctx.setVelocity()` — consistent with the
+ * positional-tuple style used by `moveToward` / `awayFrom` in `_utils.ts`.
+ *
+ * The result is re-normalised to `speed` so the final magnitude is always
+ * consistent regardless of the blend ratio.
+ *
+ * @param primaryVx    - Normalised X component of the desired direction (toward target, etc.).
+ * @param primaryVy    - Normalised Y component of the desired direction.
+ * @param steeringForce - Steering correction force (e.g. from computePackSteering).
+ * @param speed         - Base movement speed (px/s).
+ * @param weight        - Blend weight: 0 = pure primary × speed, 1 = pure steering.
+ */
+export declare function blendWithPrimary(primaryVx: number, primaryVy: number, steeringForce: Vec2, speed: number, weight: number): {
+    vx: number;
+    vy: number;
+};
+//# sourceMappingURL=SteeringBehaviors.d.ts.map

package/dist/navigation/SteeringBehaviors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SteeringBehaviors.d.ts","sourceRoot":"","sources":["../../src/navigation/SteeringBehaviors.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAO5C;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,yFAAyF;IACzF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,6DAA6D;IAC7D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,kGAAkG;IAClG,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,iFAAiF;IACjF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GACnC,eAAe,CAUjB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,IAAI,EAAE,EAC1B,MAAM,EAAE,eAAe,GACtB,IAAI,CAwBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,IAAI,EAAE,EAC1B,MAAM,EAAE,eAAe,GACtB,IAAI,CAqBN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CACvB,kBAAkB,EAAE,SAAS,IAAI,EAAE,GAClC,IAAI,CAaN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EACtD,YAAY,EAAE,MAAM,GACnB,IAAI,CAgBN;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,IAAI,EAAE,EAC1B,MAAM,EAAE,eAAe,GACtB,IAAI,CAaN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,IAAI,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAe5B"}