@austencloud/backgrounds 0.1.0

package/dist/backgrounds/deep-ocean/services/implementations/FishPropulsionCalculator.d.ts

@@ -0,0 +1,29 @@
+import type { FishMarineLife } from "../../domain/models/DeepOceanModels.js";
+import type { IFishPropulsionCalculator } from "../contracts/IFishPropulsionCalculator.js";
+/**
+ * FishPropulsionCalculator - Derives forward thrust from tail physics
+ *
+ * Physics model:
+ * - Tail position: sin(swimPhase) - oscillates side to side
+ * - Tail velocity: cos(swimPhase) - derivative, peaks at center crossing
+ * - Thrust: |cos(swimPhase)| - magnitude of velocity generates thrust
+ *
+ * This creates realistic behavior:
+ * - Fish accelerate as tail crosses center (fastest sweep)
+ * - Fish coast slightly at extremes (tail reversing direction)
+ * - Speed varies naturally with swimming intensity
+ */
+export declare class FishPropulsionCalculator implements IFishPropulsionCalculator {
+    calculateThrust(fish: FishMarineLife): number;
+    calculateTargetSpeed(fish: FishMarineLife): number;
+    getTailVelocity(fish: FishMarineLife): {
+        lateral: number;
+        angular: number;
+    };
+}
+/**
+ * Smoothly interpolate speed toward target
+ * Used by movement controller to prevent jerky speed changes
+ */
+export declare function smoothSpeed(currentSpeed: number, targetSpeed: number, deltaSeconds: number): number;
+//# sourceMappingURL=FishPropulsionCalculator.d.ts.map

package/dist/backgrounds/deep-ocean/services/implementations/FishPropulsionCalculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishPropulsionCalculator.d.ts","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishPropulsionCalculator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAC7E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AAyC3F;;;;;;;;;;;;GAYG;AACH,qBAAa,wBAAyB,YAAW,yBAAyB;IACxE,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IA2C7C,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM;IAQlD,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAkB5E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,MAAM,CAGR"}

package/dist/backgrounds/deep-ocean/services/implementations/FishPropulsionCalculator.js

@@ -0,0 +1,109 @@
+/**
+ * Propulsion configuration constants
+ */
+const PROPULSION_CONFIG = {
+    /**
+     * Base thrust coefficient - scales how much tail motion affects speed
+     * Higher = more responsive to tail steps
+     */
+    thrustCoefficient: 0.8,
+    /**
+     * Minimum thrust multiplier (fish never completely stops from thrust alone)
+     */
+    minThrustMultiplier: 0.3,
+    /**
+     * Maximum thrust multiplier (limits top speed boost from vigorous swimming)
+     */
+    maxThrustMultiplier: 1.6,
+    /**
+     * How quickly speed responds to thrust changes (0-1, lower = smoother)
+     * Prevents jerky speed changes
+     */
+    speedSmoothing: 0.15,
+    /**
+     * Amplitude influence - how much tail amplitude affects thrust
+     * Larger amplitude = more water displaced = more thrust
+     */
+    amplitudeInfluence: 0.5,
+    /**
+     * Frequency influence - how much swim speed affects thrust
+     * Faster tail steps = more thrust
+     */
+    frequencyInfluence: 0.5,
+};
+/**
+ * FishPropulsionCalculator - Derives forward thrust from tail physics
+ *
+ * Physics model:
+ * - Tail position: sin(swimPhase) - oscillates side to side
+ * - Tail velocity: cos(swimPhase) - derivative, peaks at center crossing
+ * - Thrust: |cos(swimPhase)| - magnitude of velocity generates thrust
+ *
+ * This creates realistic behavior:
+ * - Fish accelerate as tail crosses center (fastest sweep)
+ * - Fish coast slightly at extremes (tail reversing direction)
+ * - Speed varies naturally with swimming intensity
+ */
+export class FishPropulsionCalculator {
+    calculateThrust(fish) {
+        // Must have spine chain data for propulsion
+        if (!fish.useSpineChain || fish.swimPhase === undefined) {
+            return 1.0; // Legacy fish: constant thrust
+        }
+        const swimPhase = fish.swimPhase;
+        const swimSpeed = fish.swimSpeed ?? 0.08;
+        const tailAmplitude = fish.tailAmplitude ?? 8;
+        // Core thrust calculation:
+        // cos(swimPhase) gives instantaneous lateral velocity
+        // Absolute value because thrust is generated in both directions
+        const instantaneousVelocity = Math.abs(Math.cos(swimPhase));
+        // Scale by tail amplitude (bigger tail = more thrust)
+        // Normalize by a reference amplitude (~10 pixels)
+        const amplitudeScale = 1.0 +
+            (tailAmplitude / 10 - 1.0) * PROPULSION_CONFIG.amplitudeInfluence;
+        // Scale by swim frequency (faster steps = more thrust)
+        // Normalize by reference frequency (~0.08)
+        const frequencyScale = 1.0 +
+            (swimSpeed / 0.08 - 1.0) * PROPULSION_CONFIG.frequencyInfluence;
+        // Combine factors
+        let thrust = instantaneousVelocity *
+            amplitudeScale *
+            frequencyScale *
+            PROPULSION_CONFIG.thrustCoefficient;
+        // Add base thrust so fish don't completely stop
+        thrust =
+            PROPULSION_CONFIG.minThrustMultiplier +
+                thrust * (1 - PROPULSION_CONFIG.minThrustMultiplier);
+        // Clamp to max
+        return Math.min(thrust, PROPULSION_CONFIG.maxThrustMultiplier);
+    }
+    calculateTargetSpeed(fish) {
+        const thrust = this.calculateThrust(fish);
+        const baseSpeed = fish.baseSpeed;
+        // Target speed is base speed modulated by thrust
+        return baseSpeed * thrust;
+    }
+    getTailVelocity(fish) {
+        if (!fish.useSpineChain || fish.swimPhase === undefined) {
+            return { lateral: 0, angular: 0 };
+        }
+        const swimPhase = fish.swimPhase;
+        const swimSpeed = fish.swimSpeed ?? 0.08;
+        const tailAmplitude = fish.tailAmplitude ?? 8;
+        // Lateral velocity: derivative of sin(phase) = cos(phase), scaled by amplitude and frequency
+        const lateral = Math.cos(swimPhase) * tailAmplitude * swimSpeed;
+        // Angular velocity: rate of angle change at tail
+        // Approximated as derivative of the angle offset
+        const angular = -Math.sin(swimPhase) * 0.15 * swimSpeed;
+        return { lateral, angular };
+    }
+}
+/**
+ * Smoothly interpolate speed toward target
+ * Used by movement controller to prevent jerky speed changes
+ */
+export function smoothSpeed(currentSpeed, targetSpeed, deltaSeconds) {
+    const smoothingFactor = 1 - Math.pow(1 - PROPULSION_CONFIG.speedSmoothing, deltaSeconds * 60);
+    return currentSpeed + (targetSpeed - currentSpeed) * smoothingFactor;
+}
+//# sourceMappingURL=FishPropulsionCalculator.js.map

package/dist/backgrounds/deep-ocean/services/implementations/FishPropulsionCalculator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishPropulsionCalculator.js","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishPropulsionCalculator.ts"],"names":[],"mappings":"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"}

package/dist/backgrounds/deep-ocean/services/implementations/FishRareBehaviorHandler.d.ts

@@ -0,0 +1,30 @@
+import type { FishMarineLife } from "../../domain/models/DeepOceanModels.js";
+import type { IFishRareBehaviorHandler, RareBehaviorResult, RareBehaviorType } from "../contracts/IFishRareBehaviorHandler.js";
+import type { IFishWobbleAnimator } from "../contracts/IFishWobbleAnimator.js";
+/**
+ * FishRareBehaviorHandler - Creates memorable "did that fish just...?" moments
+ *
+ * Low-probability behaviors that surprise and delight users:
+ * - Barrel rolls when playful
+ * - Freeze-then-dart when alert
+ * - Double-takes when curious
+ * - Happy flips when energetic
+ * - Synchronized swimming with friends
+ */
+export declare class FishRareBehaviorHandler implements IFishRareBehaviorHandler {
+    private wobbleAnimator;
+    /** Cooldown timers per fish */
+    private cooldowns;
+    constructor(wobbleAnimator?: IFishWobbleAnimator);
+    checkRareBehaviors(fish: FishMarineLife[], deltaSeconds: number): RareBehaviorResult[];
+    applyRareBehavior(result: RareBehaviorResult): void;
+    triggerRareBehavior(fish: FishMarineLife, type: RareBehaviorType, partner?: FishMarineLife): void;
+    private updateCooldowns;
+    private isOnCooldown;
+    private setCooldown;
+    private checkBehaviorsForFish;
+    private findNearbyFriend;
+    private createResult;
+    private addToSocialMemory;
+}
+//# sourceMappingURL=FishRareBehaviorHandler.d.ts.map

package/dist/backgrounds/deep-ocean/services/implementations/FishRareBehaviorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishRareBehaviorHandler.d.ts","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishRareBehaviorHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAC7E,OAAO,KAAK,EACV,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAsC/E;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,YAAW,wBAAwB;IAKpE,OAAO,CAAC,cAAc;IAJxB,+BAA+B;IAC/B,OAAO,CAAC,SAAS,CAAyC;gBAGhD,cAAc,GAAE,mBAA8C;IAGxE,kBAAkB,CAChB,IAAI,EAAE,cAAc,EAAE,EACtB,YAAY,EAAE,MAAM,GACnB,kBAAkB,EAAE;IAsBvB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IA4BnD,mBAAmB,CACjB,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,gBAAgB,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,IAAI;IAWP,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,qBAAqB;IA2G7B,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,iBAAiB;CAiB1B"}

package/dist/backgrounds/deep-ocean/services/implementations/FishRareBehaviorHandler.js

@@ -0,0 +1,254 @@
+import { FishWobbleAnimator } from "./FishWobbleAnimator.js";
+/**
+ * Configuration for rare behavior probabilities and conditions
+ */
+const RARE_BEHAVIOR_CONFIG = {
+    /** Base probability per second for each behavior type */
+    baseProbabilities: {
+        barrel_roll: 0.003, // ~0.3% per second when playful
+        freeze: 0.005, // ~0.5% per second when alert
+        double_take: 0.004, // ~0.4% per second when curious
+        happy_flip: 0.002, // ~0.2% per second when high energy
+        sync_swim: 0.006, // ~0.6% per second when near friend
+    },
+    /** Mood requirements for each behavior */
+    moodRequirements: {
+        barrel_roll: ["playful"],
+        freeze: ["alert"],
+        double_take: ["curious"],
+        happy_flip: ["playful", "calm"],
+        sync_swim: ["social", "calm", "playful"],
+    },
+    /** Minimum energy level for energy-dependent behaviors */
+    minEnergyForFlip: 0.7,
+    /** Distance threshold for sync swim (pixels) */
+    syncSwimDistance: 80,
+    /** Cooldown between rare behaviors per fish (seconds) */
+    cooldownDuration: 8,
+    /** Minimum sociability for sync swim */
+    minSociabilityForSync: 0.5,
+};
+/**
+ * FishRareBehaviorHandler - Creates memorable "did that fish just...?" moments
+ *
+ * Low-probability behaviors that surprise and delight users:
+ * - Barrel rolls when playful
+ * - Freeze-then-dart when alert
+ * - Double-takes when curious
+ * - Happy flips when energetic
+ * - Synchronized swimming with friends
+ */
+export class FishRareBehaviorHandler {
+    wobbleAnimator;
+    /** Cooldown timers per fish */
+    cooldowns = new WeakMap();
+    constructor(wobbleAnimator = new FishWobbleAnimator()) {
+        this.wobbleAnimator = wobbleAnimator;
+    }
+    checkRareBehaviors(fish, deltaSeconds) {
+        const results = [];
+        // Update cooldowns
+        this.updateCooldowns(fish, deltaSeconds);
+        for (const f of fish) {
+            // Skip if on cooldown or currently wobbling
+            if (this.isOnCooldown(f))
+                continue;
+            if (this.wobbleAnimator.isWobbling(f))
+                continue;
+            // Check each rare behavior type
+            const result = this.checkBehaviorsForFish(f, fish, deltaSeconds);
+            if (result) {
+                results.push(result);
+                this.setCooldown(f);
+            }
+        }
+        return results;
+    }
+    applyRareBehavior(result) {
+        const { fish, wobbleType, partner, type } = result;
+        // Trigger the wobble animation
+        this.wobbleAnimator.triggerWobble(fish, wobbleType, 1.0);
+        // For sync swim, also trigger on partner
+        if (type === "sync_swim" && partner) {
+            this.wobbleAnimator.triggerWobble(partner, "sync_pulse", 0.8);
+            // Add each other to social memory
+            this.addToSocialMemory(fish, partner);
+            this.addToSocialMemory(partner, fish);
+        }
+        // For freeze, we need to temporarily pause movement
+        if (type === "freeze") {
+            const originalSpeed = fish.speed;
+            fish.speed = 0;
+            // Restore after wobble duration
+            setTimeout(() => {
+                if (fish.speed === 0) {
+                    fish.speed = originalSpeed * 1.5; // Dart after freeze
+                }
+            }, 600);
+        }
+    }
+    triggerRareBehavior(fish, type, partner) {
+        const result = this.createResult(fish, type, partner);
+        if (result) {
+            this.applyRareBehavior(result);
+        }
+    }
+    // ============================================================================
+    // PRIVATE METHODS
+    // ============================================================================
+    updateCooldowns(fish, deltaSeconds) {
+        for (const f of fish) {
+            const remaining = this.cooldowns.get(f);
+            if (remaining !== undefined && remaining > 0) {
+                this.cooldowns.set(f, remaining - deltaSeconds);
+            }
+        }
+    }
+    isOnCooldown(fish) {
+        const remaining = this.cooldowns.get(fish);
+        return remaining !== undefined && remaining > 0;
+    }
+    setCooldown(fish) {
+        // Add randomness to prevent synchronized behaviors
+        const cooldown = RARE_BEHAVIOR_CONFIG.cooldownDuration * (0.7 + Math.random() * 0.6);
+        this.cooldowns.set(fish, cooldown);
+    }
+    checkBehaviorsForFish(fish, allFish, deltaSeconds) {
+        const mood = fish.mood ?? "calm";
+        const personality = fish.personality;
+        const energy = fish.energy ?? 0.8;
+        // Check each behavior type in priority order
+        const behaviorChecks = [
+            {
+                type: "barrel_roll",
+                check: () => {
+                    if (!RARE_BEHAVIOR_CONFIG.moodRequirements.barrel_roll.includes(mood))
+                        return false;
+                    const prob = RARE_BEHAVIOR_CONFIG.baseProbabilities.barrel_roll *
+                        deltaSeconds *
+                        (personality?.activity ?? 0.5) *
+                        2;
+                    return Math.random() < prob;
+                },
+            },
+            {
+                type: "freeze",
+                check: () => {
+                    if (!RARE_BEHAVIOR_CONFIG.moodRequirements.freeze.includes(mood))
+                        return false;
+                    const prob = RARE_BEHAVIOR_CONFIG.baseProbabilities.freeze *
+                        deltaSeconds *
+                        (1 - (personality?.boldness ?? 0.5)); // Shy fish freeze more
+                    return Math.random() < prob;
+                },
+            },
+            {
+                type: "double_take",
+                check: () => {
+                    if (!RARE_BEHAVIOR_CONFIG.moodRequirements.double_take.includes(mood))
+                        return false;
+                    const prob = RARE_BEHAVIOR_CONFIG.baseProbabilities.double_take *
+                        deltaSeconds *
+                        (personality?.curiosity ?? 0.5) *
+                        2;
+                    return Math.random() < prob;
+                },
+            },
+            {
+                type: "happy_flip",
+                check: () => {
+                    if (energy < RARE_BEHAVIOR_CONFIG.minEnergyForFlip)
+                        return false;
+                    if (!RARE_BEHAVIOR_CONFIG.moodRequirements.happy_flip.includes(mood))
+                        return false;
+                    const prob = RARE_BEHAVIOR_CONFIG.baseProbabilities.happy_flip *
+                        deltaSeconds *
+                        energy *
+                        (personality?.activity ?? 0.5) *
+                        2;
+                    return Math.random() < prob;
+                },
+            },
+            {
+                type: "sync_swim",
+                check: () => {
+                    if (!RARE_BEHAVIOR_CONFIG.moodRequirements.sync_swim.includes(mood))
+                        return false;
+                    if ((personality?.sociability ?? 0.5) <
+                        RARE_BEHAVIOR_CONFIG.minSociabilityForSync)
+                        return false;
+                    // Check for nearby friends
+                    const nearbyFriend = this.findNearbyFriend(fish, allFish);
+                    if (!nearbyFriend)
+                        return false;
+                    const prob = RARE_BEHAVIOR_CONFIG.baseProbabilities.sync_swim *
+                        deltaSeconds *
+                        (personality?.sociability ?? 0.5) *
+                        2;
+                    return Math.random() < prob;
+                },
+            },
+        ];
+        for (const { type, check } of behaviorChecks) {
+            if (check()) {
+                const partner = type === "sync_swim" ? this.findNearbyFriend(fish, allFish) : undefined;
+                return this.createResult(fish, type, partner ?? undefined);
+            }
+        }
+        return null;
+    }
+    findNearbyFriend(fish, allFish) {
+        const socialMemory = fish.socialMemory;
+        for (const other of allFish) {
+            if (other === fish)
+                continue;
+            // Check distance
+            const dx = Math.abs(fish.x - other.x);
+            const dy = Math.abs(fish.y - other.y);
+            if (dx > RARE_BEHAVIOR_CONFIG.syncSwimDistance)
+                continue;
+            if (dy > RARE_BEHAVIOR_CONFIG.syncSwimDistance * 0.6)
+                continue;
+            // Prefer fish we've interacted with before (friends)
+            if (socialMemory && other.fishId && socialMemory.has(other.fishId)) {
+                return other;
+            }
+            // Or just any nearby social fish
+            if ((other.personality?.sociability ?? 0.5) > 0.5) {
+                return other;
+            }
+        }
+        return null;
+    }
+    createResult(fish, type, partner) {
+        const wobbleMap = {
+            barrel_roll: "barrel_roll",
+            freeze: "freeze",
+            double_take: "double_take",
+            happy_flip: "happy_flip",
+            sync_swim: "sync_pulse",
+        };
+        return {
+            type,
+            fish,
+            partner,
+            wobbleType: wobbleMap[type],
+        };
+    }
+    addToSocialMemory(fish, other) {
+        if (!other.fishId)
+            return;
+        if (!fish.socialMemory) {
+            fish.socialMemory = new Set();
+        }
+        fish.socialMemory.add(other.fishId);
+        // Limit memory size to prevent unbounded growth
+        if (fish.socialMemory.size > 10) {
+            const first = fish.socialMemory.values().next().value;
+            if (first !== undefined) {
+                fish.socialMemory.delete(first);
+            }
+        }
+    }
+}
+//# sourceMappingURL=FishRareBehaviorHandler.js.map

package/dist/backgrounds/deep-ocean/services/implementations/FishRareBehaviorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishRareBehaviorHandler.js","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishRareBehaviorHandler.ts"],"names":[],"mappings":"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"}

package/dist/backgrounds/deep-ocean/services/implementations/FishRenderer.d.ts

@@ -0,0 +1,50 @@
+import type { FishMarineLife } from "../../domain/models/DeepOceanModels.js";
+import type { IFishRenderer } from "../contracts/IFishRenderer.js";
+import type { IFishEffectRenderer } from "../contracts/IFishEffectRenderer.js";
+import type { IFishFaceRenderer } from "../contracts/IFishFaceRenderer.js";
+import type { IFishFinRenderer } from "../contracts/IFishFinRenderer.js";
+import type { IFishPatternRenderer } from "../contracts/IFishPatternRenderer.js";
+import type { IFishBodyRenderer } from "../contracts/IFishBodyRenderer.js";
+/**
+ * Fish Rendering Orchestrator
+ *
+ * Coordinates specialized rendering services to draw anatomically accurate procedural fish:
+ * - Body shapes (FishBodyRenderer)
+ * - Fins with physics (FishFinRenderer)
+ * - Patterns and textures (FishPatternRenderer)
+ * - Facial features (FishFaceRenderer)
+ * - Effects like bioluminescence (FishEffectRenderer)
+ */
+export declare class FishRenderer implements IFishRenderer {
+    private effectRenderer;
+    private faceRenderer;
+    private finRenderer;
+    private patternRenderer;
+    private bodyRenderer;
+    private bodyOutlineCalculator;
+    constructor(effectRenderer: IFishEffectRenderer, faceRenderer: IFishFaceRenderer, finRenderer: IFishFinRenderer, patternRenderer: IFishPatternRenderer, bodyRenderer: IFishBodyRenderer);
+    drawFish(ctx: CanvasRenderingContext2D, fish: FishMarineLife[]): void;
+    /**
+     * Calculate depth-based rendering modifiers from z value.
+     * Uses DEPTH_TRANSITION constants for consistency.
+     */
+    private getDepthModifiers;
+    /**
+     * Draw fish using spine chain data for organic body shape
+     */
+    private drawSpineChainFish;
+    /**
+     * Create temporary SpineChain object from joint data
+     */
+    private createTempSpineFromJoints;
+    private drawSingleFish;
+    /**
+     * Wobble configuration matching FishWobbleAnimator
+     */
+    private static readonly WOBBLE_CONFIGS;
+    /**
+     * Calculate wobble offset from fish state
+     */
+    private calculateWobbleOffset;
+}
+//# sourceMappingURL=FishRenderer.d.ts.map

package/dist/backgrounds/deep-ocean/services/implementations/FishRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FishRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/backgrounds/deep-ocean/services/implementations/FishRenderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAM3E;;;;;;;;;GASG;AACH,qBAAa,YAAa,YAAW,aAAa;IAI9C,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,YAAY;IAPtB,OAAO,CAAC,qBAAqB,CAA+B;gBAGlD,cAAc,EAAE,mBAAmB,EACnC,YAAY,EAAE,iBAAiB,EAC/B,WAAW,EAAE,gBAAgB,EAC7B,eAAe,EAAE,oBAAoB,EACrC,YAAY,EAAE,iBAAiB;IAGzC,QAAQ,CAAC,GAAG,EAAE,wBAAwB,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,IAAI;IAerE;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkF1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAkCjC,OAAO,CAAC,cAAc;IAyCtB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAyEpC;IAEF;;OAEG;IACH,OAAO,CAAC,qBAAqB;CAsD9B"}