playlist-data-engine 1.1.0

package/dist/core/sensors/EnvironmentalSensors.d.ts

@@ -0,0 +1,301 @@
+import type { SensorType, SensorPermission, EnvironmentalContext, SensorStatus, SensorFailureLog, SensorRetryConfig, SensorRecoveryNotification, XpModifierBreakdown, SolarInfo } from '../types/Environmental';
+import type { GeolocationSensorConfig, WeatherSensorConfig, XPModifierConfig, RetryConfig } from '../config/sensorConfig.js';
+import { type SevereWeatherAlert } from './WeatherAPIClient';
+import { type DashboardConfig } from '../../utils/sensorDashboard.js';
+/**
+ * Environmental sensor integration with error recovery
+ *
+ * Aggregates data from:
+ * - GPS/Geolocation (latitude, longitude, altitude)
+ * - Motion sensors (accelerometer, gyroscope, activity detection)
+ * - Weather API (temperature, humidity, conditions)
+ *
+ * Calculates environmental XP modifiers (1.0x - 3.0x) based on activity
+ * type, weather conditions, altitude, and time of day.
+ *
+ * Error Recovery Features:
+ * - Retry logic with exponential backoff for failed sensor reads
+ * - Sensor health monitoring and status tracking
+ * - "Last known good" fallback values when sensors fail
+ * - Graceful degradation when individual sensors fail
+ * - Failure logging with timestamps
+ * - Recovery notifications
+ */
+export declare class EnvironmentalSensors {
+    private permissions;
+    private geolocation;
+    private motion;
+    private weather;
+    private logger;
+    private context;
+    private sensorStatuses;
+    private failureLog;
+    private lastKnownGood;
+    private recoveryCallbacks;
+    private retryConfig;
+    private xpConfig;
+    /**
+     * Initialize environmental sensors with optional weather API key, retry config, or full config
+     *
+     * Supports multiple constructor signatures for backward compatibility:
+     * - new EnvironmentalSensors(apiKey)
+     * - new EnvironmentalSensors(apiKey, retryConfig)
+     * - new EnvironmentalSensors({ weather: { apiKey }, retry: {...} })
+     *
+     * @param {string | { weather?: Partial<WeatherSensorConfig>, geolocation?: Partial<GeolocationSensorConfig>, retry?: Partial<RetryConfig>, xpModifier?: Partial<XPModifierConfig> }} [weatherApiKeyOrConfig] - Weather API key or configuration object
+     * @param {Partial<SensorRetryConfig>} [retryConfig] - Optional custom retry configuration
+     *
+     * @example
+     * const sensors = new EnvironmentalSensors(process.env.WEATHER_API_KEY);
+     * const sensors2 = new EnvironmentalSensors({ weather: { apiKey }, retry: { maxRetries: 5 } });
+     */
+    constructor(weatherApiKeyOrConfig?: string | {
+        weather?: Partial<WeatherSensorConfig>;
+        geolocation?: Partial<GeolocationSensorConfig>;
+        retry?: Partial<RetryConfig>;
+        xpModifier?: Partial<XPModifierConfig>;
+    }, retryConfig?: Partial<SensorRetryConfig>);
+    /**
+     * Initialize sensor statuses to 'unknown' state
+     */
+    private initializeSensorStatuses;
+    /**
+     * Update sensor health status after a success or failure
+     */
+    private updateSensorStatus;
+    /**
+     * Notify registered callbacks of sensor recovery events
+     */
+    private notifyRecovery;
+    /**
+     * Log a sensor failure event
+     */
+    private logFailure;
+    /**
+     * Store last known good value for a sensor
+     */
+    private storeLastKnownGood;
+    /**
+     * Execute a sensor operation with retry logic and exponential backoff
+     */
+    private retrySensorOperation;
+    /**
+     * Delay helper for retry backoff
+     */
+    private delay;
+    /**
+     * Register a callback for sensor recovery notifications
+     *
+     * @param callback - Function to call when sensor status changes
+     * @returns Unsubscribe function
+     */
+    onSensorRecovery(callback: (notification: SensorRecoveryNotification) => void): () => void;
+    /**
+     * Get current status of a specific sensor
+     */
+    getSensorStatus(sensorType: SensorType): SensorStatus | null;
+    /**
+     * Get status of all sensors
+     */
+    getAllSensorStatuses(): SensorStatus[];
+    /**
+     * Get failure log entries
+     *
+     * @param sensorType - Optional filter by sensor type
+     * @param limit - Maximum number of entries to return (default: all)
+     */
+    getFailureLog(sensorType?: SensorType, limit?: number): SensorFailureLog[];
+    /**
+     * Get last known good value for a sensor
+     */
+    getLastKnownGood(sensorType: SensorType): any;
+    /**
+     * Clear failure log
+     */
+    clearFailureLog(): void;
+    /**
+     * Update retry configuration
+     */
+    updateRetryConfig(config: Partial<SensorRetryConfig>): void;
+    /**
+     * Request user permissions for specific sensor types
+     *
+     * Requests browser/device permissions for GPS, motion, and weather sensors.
+     * User must explicitly grant permissions before data can be accessed.
+     *
+     * @param {SensorType[]} types - Array of sensor types to request ('geolocation' | 'motion' | 'weather')
+     * @returns {Promise<SensorPermission[]>} Array of permission results (granted/denied)
+     *
+     * @example
+     * const permissions = await sensors.requestPermissions(['geolocation', 'motion']);
+     */
+    requestPermissions(types: SensorType[]): Promise<SensorPermission[]>;
+    /**
+     * Start monitoring enabled sensors
+     */
+    startMonitoring(callback?: (context: EnvironmentalContext) => void): void;
+    /**
+     * Stop all monitoring
+     */
+    stopMonitoring(): void;
+    /**
+     * Manually update snapshot of pull-based sensors (Geo, Weather) with retry logic
+     */
+    updateSnapshot(): Promise<EnvironmentalContext>;
+    /**
+     * Calculate XP modifier based on environmental factors
+     * Uses last known good values if current readings are unavailable
+     * Uses configured max modifier cap (default: 3.0x)
+     */
+    calculateXPModifier(): number;
+    /**
+     * Get detailed breakdown of XP modifier with active bonus sources
+     * Uses last known good values if current readings are unavailable
+     * @returns XpModifierBreakdown with total, sources, and active bonuses
+     */
+    getXpModifierBreakdown(): XpModifierBreakdown;
+    /**
+     * Calculate XP modifier based on environmental factors including forecast
+     * Considers incoming weather for bonus XP
+     * Uses configured max modifier cap (default: 3.0x)
+     * @param forecastHours Hours ahead to check for incoming weather (default: 12)
+     * @returns Promise resolving to XP modifier value
+     */
+    calculateXPModifierWithForecast(forecastHours?: number): Promise<number>;
+    /**
+     * Calculate XP modifier based on environmental factors including severe weather detection
+     * Considers current severe weather conditions for maximum XP bonus
+     * Uses configured max modifier cap (default: 3.0x)
+     * @returns Promise resolving to XP modifier value and any severe weather alert
+     */
+    calculateXPModifierWithSevereWeather(): Promise<{
+        modifier: number;
+        severeWeatherAlert: SevereWeatherAlert | null;
+        safetyWarning: string | null;
+    }>;
+    /**
+     * Detect severe weather from current environmental conditions
+     * Falls back to last known good weather if current is unavailable
+     * @returns Severe weather alert or null if conditions are normal
+     */
+    detectSevereWeather(): SevereWeatherAlert | null;
+    /**
+     * Get safety warning for current severe weather conditions
+     * @returns Safety warning message or null if no severe weather
+     */
+    getSevereWeatherWarning(): string | null;
+    getPermissions(): SensorPermission[];
+    checkAvailability(type: SensorType): boolean;
+    private requestGeolocationPermission;
+    private requestMotionPermission;
+    /**
+     * Get current activity type with fallback to last known good
+     */
+    getCurrentActivity(): 'stationary' | 'walking' | 'running' | 'driving' | 'unknown';
+    /**
+     * Get comprehensive diagnostic information for troubleshooting
+     * Returns structured data about all sensor states, cache statistics, and recent failures
+     *
+     * @returns Diagnostic report containing sensor statuses, cache stats, performance metrics, and recent errors
+     */
+    getDiagnostics(): {
+        timestamp: number;
+        diagnosticMode: boolean;
+        sensors: {
+            type: SensorType;
+            status: SensorStatus;
+            permission: boolean;
+            availability: boolean;
+            lastKnownGood: any;
+        }[];
+        cache: {
+            geolocation: {
+                age: number | null;
+                isExpired: boolean;
+                stats: {
+                    hits: number;
+                    misses: number;
+                };
+            };
+            weather: {
+                size: number;
+                stats: {
+                    hits: number;
+                    misses: number;
+                };
+                ttl: number;
+            };
+        };
+        performance: {
+            weatherApi: {
+                average: number;
+                min: number;
+                max: number;
+                totalCalls: number;
+                successRate: number;
+                p95: number;
+                p99: number;
+            };
+            forecastApi: {
+                average: number;
+                min: number;
+                max: number;
+                totalCalls: number;
+                successRate: number;
+                p95: number;
+                p99: number;
+            };
+        };
+        recentFailures: SensorFailureLog[];
+        permissions: SensorPermission[];
+        context: {
+            hasGeolocation: boolean;
+            hasMotion: boolean;
+            hasWeather: boolean;
+            hasBiome: boolean;
+            timestamp: number;
+        };
+    };
+    /**
+     * Enable diagnostic mode for enhanced logging and debugging
+     * Sets global logger to DEBUG level
+     */
+    enableDiagnosticMode(): void;
+    /**
+     * Disable diagnostic mode and reset to normal logging
+     * Resets global logger to INFO level
+     */
+    disableDiagnosticMode(): void;
+    /**
+     * Print a formatted dashboard to the console with sensor status information
+     * Useful for debugging and monitoring during development
+     *
+     * @param config Optional dashboard configuration (colors, compact mode, etc.)
+     *
+     * @example
+     * sensors.printDashboard();
+     * sensors.printDashboard({ useColors: false, compact: true });
+     */
+    printDashboard(config?: DashboardConfig): void;
+    /**
+     * Get solar information including sunrise, sunset, and day stage.
+     * Works WITHOUT API key using astronomical calculations (NOAA algorithm).
+     * Uses current geolocation if available.
+     *
+     * @param date - Optional date for calculation (defaults to now)
+     * @returns SolarInfo object with sunrise, sunset, solar noon, and day stage, or null if no location available
+     */
+    getSolarInfo(date?: Date): SolarInfo | null;
+    /**
+     * Get solar information for specific coordinates.
+     * Works WITHOUT API key using astronomical calculations (NOAA algorithm).
+     * Use this when you have coordinates from an external source (e.g., persisted React state).
+     *
+     * @param latitude - Latitude in decimal degrees (-90 to 90)
+     * @param longitude - Longitude in decimal degrees (-180 to 180)
+     * @param date - Optional date for calculation (defaults to now)
+     * @returns SolarInfo object with sunrise, sunset, solar noon, and day stage
+     */
+    getSolarInfoForCoords(latitude: number, longitude: number, date?: Date): SolarInfo;
+}
+//# sourceMappingURL=EnvironmentalSensors.d.ts.map

package/dist/core/sensors/EnvironmentalSensors.d.ts.map

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

package/dist/core/sensors/GamingPlatformSensors.d.ts

@@ -0,0 +1,162 @@
+import type { GamingContext } from '../types/Progression';
+import type { GamingSensorConfig } from '../config/sensorConfig.js';
+import { type DashboardConfig } from '../../utils/sensorDashboard.js';
+/**
+ * GamingPlatformSensors - Unified interface for gaming detection
+ * Monitors active games and calculates gaming-based XP bonuses
+ *
+ * Game detection uses Steam API only.
+ */
+export declare class GamingPlatformSensors {
+    private steam;
+    private steamUserId?;
+    private steamApiKey?;
+    private pollIntervalMs;
+    private pollingInterval;
+    private exponentialBackoff;
+    private maxBackoffMs;
+    private logger;
+    private xpConfig;
+    private gamingContext;
+    private contextCallback;
+    private gameMetadataCache;
+    private cacheExpiryMs;
+    /**
+     * Initialize GamingPlatformSensors with optional Steam configuration
+     * Matches specification from specs/001-core-engine/SPEC.md
+     *
+     * Supports both legacy config format and new GamingSensorConfig format
+     */
+    constructor(config?: {
+        steam?: {
+            apiKey: string;
+            steamId?: string;
+            pollInterval?: number;
+        };
+    } | GamingSensorConfig);
+    /**
+     * Authenticate with Steam
+     */
+    authenticate(steamUserId?: string): Promise<boolean>;
+    /**
+     * Start polling for gaming activity
+     */
+    startMonitoring(callback?: (context: GamingContext) => void): void;
+    /**
+     * Stop monitoring gaming activity
+     */
+    stopMonitoring(): void;
+    /**
+     * Update gaming status from Steam
+     * Note: Only Steam API is used for game activity detection.
+     */
+    private updateGamingStatus;
+    /**
+     * Apply exponential backoff for polling on errors
+     */
+    private applyExponentialBackoff;
+    /**
+     * Get cached game metadata or fetch it
+     */
+    private getGameMetadata;
+    /**
+     * Check if currently playing a specific game
+     */
+    isPlayingGame(gameName: string): boolean;
+    /**
+     * Calculate gaming XP bonus multiplier
+     * Base: +25% for any gaming
+     * Genre bonuses: RPG +20%, Action +15%, Strategy +10%
+     * Multiplayer: +15% for party size > 1
+     * Session duration: up to +20% for 4+ hours
+     * Capped at configured max gaming modifier (default: 1.75x)
+     */
+    calculateGamingBonus(): number;
+    /**
+     * Get current gaming context
+     */
+    getContext(): GamingContext;
+    /**
+     * Add game to list of games played while listening
+     */
+    recordGameSession(gameName: string, durationMinutes: number): void;
+    /**
+     * Get comprehensive diagnostic information for troubleshooting
+     * Returns structured data about gaming platform connection states, cache, and performance metrics
+     *
+     * @returns Diagnostic report containing Steam connection state, cache, and API performance
+     */
+    getDiagnostics(): {
+        timestamp: number;
+        steam: {
+            isAuthenticated: boolean;
+            userId?: string;
+            apiKey: boolean;
+        };
+        gamingContext: GamingContext;
+        polling: {
+            isActive: boolean;
+            intervalMs: number;
+            exponentialBackoff: number;
+        };
+        cache: {
+            gameMetadataCacheSize: number;
+            cachedGames: string[];
+        };
+        performance: {
+            currentGameApi: {
+                average: number;
+                min: number;
+                max: number;
+                totalCalls: number;
+                successRate: number;
+                p95: number;
+                p99: number;
+            };
+            metadataApi: {
+                average: number;
+                min: number;
+                max: number;
+                totalCalls: number;
+                successRate: number;
+                p95: number;
+                p99: number;
+            };
+        };
+    };
+    /**
+     * Get game schema (achievements, stats) for a Steam app
+     * @param appId Steam app ID
+     * @returns Game schema containing achievements and player stats, or null if unavailable
+     */
+    fetchGameSchema(appId: number): Promise<{
+        gameName?: string;
+        gameVersion?: string;
+        availableGameStats?: {
+            achievements?: Array<{
+                name: string;
+                displayName: string;
+                description?: string;
+                icon?: string;
+                hidden?: number;
+            }>;
+            stats?: Array<{
+                name: string;
+                displayName?: string;
+                value: number;
+            }>;
+        };
+    } | null>;
+    /**
+     * Print a formatted dashboard to the console with gaming sensor status information
+     * Useful for debugging and monitoring during development
+     *
+     * @param config Optional dashboard configuration (colors, compact mode, etc.)
+     *
+     * @example
+     * gamingSensors.printDashboard();
+     * gamingSensors.printDashboard({ useColors: false, compact: true });
+     */
+    printDashboard(config?: DashboardConfig): void;
+}
+//# sourceMappingURL=GamingPlatformSensors.d.ts.map

package/dist/core/sensors/GamingPlatformSensors.d.ts.map

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

package/dist/core/sensors/GeolocationProvider.d.ts

@@ -0,0 +1,156 @@
+import type { GeolocationData } from '../types/Environmental';
+import type { GeolocationSensorConfig } from '../config/sensorConfig.js';
+interface CacheStatistics {
+    hits: number;
+    misses: number;
+}
+export declare class GeolocationProvider {
+    private cache;
+    private cacheTTL;
+    private cacheStats;
+    private useLocalStorage;
+    private logger;
+    constructor(cacheTTLMinutes?: number, useLocalStorage?: boolean);
+    constructor(config: GeolocationSensorConfig);
+    /**
+     * Check if localStorage is available
+     */
+    private isLocalStorageAvailable;
+    /**
+     * Load cache from localStorage
+     */
+    private loadFromLocalStorage;
+    /**
+     * Save cache to localStorage
+     */
+    private saveToLocalStorage;
+    /**
+     * Check if a cache entry is still valid
+     * @param entry Cache entry to validate
+     * @returns True if entry is valid and within TTL
+     */
+    private isCacheEntryValid;
+    /**
+     * Get the age of the cached position in milliseconds
+     * @returns Age in milliseconds, or null if no cache exists
+     */
+    getCacheAge(): number | null;
+    /**
+     * Get the current position using the Geolocation API
+     * @param forceRefresh If true, bypass cache and fetch fresh position
+     * @returns Promise resolving to GeolocationData or null if failed/denied
+     */
+    getCurrentPosition(forceRefresh?: boolean): Promise<GeolocationData | null>;
+    /**
+     * Invalidate all cached geolocation data
+     */
+    invalidateCache(): void;
+    /**
+     * Get cache statistics
+     * @returns Cache statistics object
+     */
+    getCacheStats(): CacheStatistics;
+    /**
+     * Reset cache statistics
+     */
+    resetCacheStats(): void;
+    /**
+     * Check if cache is expired
+     * @returns True if cache is expired or doesn't exist
+     */
+    isCacheExpired(): boolean;
+    /**
+     * Get the cached position without checking TTL
+     * @returns Cached position data or null if no cache exists
+     */
+    getCachedPosition(): GeolocationData | null;
+    /**
+     * Calculate the biome based on coordinates (improved with longitude-based detection)
+     * In a real app, this would query a GIS service or use a sophisticated map.
+     * Here we use simple latitude/longitude heuristics for demonstration.
+     *
+     * The detection now considers:
+     * - Latitude bands (polar, temperate, tropical)
+     * - Longitude-based regional characteristics (continental vs coastal, desert belts)
+     * - Regional biome patterns based on global geography
+     * - Coastal vs inland detection (oceans, seas, islands, peninsulas)
+     * - Elevation/altitude when available (mountains, valleys)
+     *
+     * @param latitude Latitude coordinate
+     * @param longitude Longitude coordinate
+     * @param altitude Optional altitude in meters (null if unavailable)
+     * @returns Biome type string (may include _coastal suffix for coastal variants)
+     */
+    getBiome(latitude: number, longitude: number, altitude?: number | null): string;
+    /**
+     * Determine biome based on elevation/altitude
+     *
+     * Elevation thresholds (based on common geographical classifications):
+     * - High mountain: >3500m (11,500ft) - permanent snow, alpine
+     * - Mountain: 1500-3500m (4,900-11,500ft) - mountain ranges
+     * - High plateau: 500-1500m (1,600-4,900ft) - transitional
+     * - Valley/below sea level: <0m - depressions, rift valleys
+     *
+     * When altitude data is valid and indicates mountain or valley terrain,
+     * return the appropriate biome. Otherwise return null to fall back to
+     * coordinate-based detection.
+     *
+     * @param altitude Altitude in meters
+     * @param coastalSuffix The coastal suffix to apply if needed
+     * @returns Biome string if elevation indicates mountain/valley, null otherwise
+     */
+    private getElevationBiome;
+    /**
+     * Normalize longitude to 0-360 range for easier region checking
+     */
+    private normalizeLongitude;
+    /**
+     * Check if coordinates fall within jungle regions (dense tropical rainforests)
+     * Jungle is a subtype of forest - specifically dense tropical forests
+     */
+    private isInJungleRegion;
+    /**
+     * Check if coordinates fall within swamp/wetland regions
+     */
+    private isInSwampRegion;
+    /**
+     * Check if coordinates fall within taiga (boreal forest) regions
+     * Taiga is between 50-70° latitude in northern hemisphere
+     */
+    private isInTaigaRegion;
+    /**
+     * Check if coordinates fall within savanna (tropical grassland) regions
+     */
+    private isInSavannaRegion;
+    /**
+     * Check if coordinates fall within known desert regions
+     * Uses latitude bands around 30° N/S and longitude ranges for major deserts
+     */
+    private isInDesertRegion;
+    /**
+     * Check if coordinates are near a coastline (coastal vs inland detection)
+     * Uses heuristic patterns based on proximity to oceans and major coastlines
+     *
+     * This is a simplified heuristic approach. In a production system, this would use:
+     * - A GIS service with coastline proximity data
+     * - A pre-computed coastline database with distance calculations
+     * - Or reverse geocoding to check for "ocean" in location names
+     *
+     * @param latitude Latitude coordinate
+     * @param longitude Longitude coordinate (normalized 0-360)
+     * @returns true if the location is likely coastal, false if inland
+     */
+    private isCoastal;
+    /**
+     * Check if coordinates are in a small island region
+     * Small islands are always considered coastal
+     */
+    private isInSmallIslandRegion;
+    /**
+     * Check if coordinates are in a narrow landmass (isthmus or peninsula)
+     * These regions are typically coastal on at least one side
+     */
+    private isInNarrowLandmass;
+}
+export {};
+//# sourceMappingURL=GeolocationProvider.d.ts.map

package/dist/core/sensors/GeolocationProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeolocationProvider.d.ts","sourceRoot":"","sources":["../../../src/core/sensors/GeolocationProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAQzE,UAAU,eAAe;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAClB;AAWD,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,UAAU,CAA2C;IAC7D,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,MAAM,CAAqC;gBAEvC,eAAe,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,OAAO;gBACnD,MAAM,EAAE,uBAAuB;IAiB3C;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAW/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAiB5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;OAGG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI;IAK5B;;;;OAIG;IACG,kBAAkB,CAAC,YAAY,GAAE,OAAe,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAkDxF;;OAEG;IACH,eAAe,IAAI,IAAI;IAWvB;;;OAGG;IACH,aAAa,IAAI,eAAe;IAIhC;;OAEG;IACH,eAAe,IAAI,IAAI;IAIvB;;;OAGG;IACH,cAAc,IAAI,OAAO;IAIzB;;;OAGG;IACH,iBAAiB,IAAI,eAAe,GAAG,IAAI;IAI3C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM;IAyIrF;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoCxB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;IAgEjB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAsC7B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CA4B7B"}