@jablum/weather-mcp 1.7.0

package/dist/utils/distance.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Utility functions for calculating distances between coordinates
+ */
+/**
+ * Calculate the great-circle distance between two points on Earth using the Haversine formula
+ * @param lat1 Latitude of first point in degrees
+ * @param lon1 Longitude of first point in degrees
+ * @param lat2 Latitude of second point in degrees
+ * @param lon2 Longitude of second point in degrees
+ * @returns Distance in kilometers
+ */
+export declare function calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Convert kilometers to miles
+ * @param km Distance in kilometers
+ * @returns Distance in miles
+ */
+export declare function kmToMiles(km: number): number;
+/**
+ * Convert miles to kilometers
+ * @param miles Distance in miles
+ * @returns Distance in kilometers
+ */
+export declare function milesToKm(miles: number): number;
+//# sourceMappingURL=distance.d.ts.map

package/dist/utils/distance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distance.d.ts","sourceRoot":"","sources":["../../src/utils/distance.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CAcR;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/utils/distance.js

@@ -0,0 +1,40 @@
+/**
+ * Utility functions for calculating distances between coordinates
+ */
+/**
+ * Calculate the great-circle distance between two points on Earth using the Haversine formula
+ * @param lat1 Latitude of first point in degrees
+ * @param lon1 Longitude of first point in degrees
+ * @param lat2 Latitude of second point in degrees
+ * @param lon2 Longitude of second point in degrees
+ * @returns Distance in kilometers
+ */
+export function calculateDistance(lat1, lon1, lat2, lon2) {
+    const R = 6371; // Earth's radius in km
+    const dLat = ((lat2 - lat1) * Math.PI) / 180;
+    const dLon = ((lon2 - lon1) * Math.PI) / 180;
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos((lat1 * Math.PI) / 180) *
+            Math.cos((lat2 * Math.PI) / 180) *
+            Math.sin(dLon / 2) *
+            Math.sin(dLon / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+}
+/**
+ * Convert kilometers to miles
+ * @param km Distance in kilometers
+ * @returns Distance in miles
+ */
+export function kmToMiles(km) {
+    return km * 0.621371;
+}
+/**
+ * Convert miles to kilometers
+ * @param miles Distance in miles
+ * @returns Distance in kilometers
+ */
+export function milesToKm(miles) {
+    return miles / 0.621371;
+}
+//# sourceMappingURL=distance.js.map

package/dist/utils/distance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distance.js","sourceRoot":"","sources":["../../src/utils/distance.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,IAAY,EACZ,IAAY,EACZ,IAAY;IAEZ,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,uBAAuB;IACvC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;IAC7C,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;IAE7C,MAAM,CAAC,GACL,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;YAC9B,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;YAClB,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAEvB,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,OAAO,EAAE,GAAG,QAAQ,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,KAAK,GAAG,QAAQ,CAAC;AAC1B,CAAC"}

package/dist/utils/fireWeather.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Fire weather utility functions for interpreting fire danger indices
+ */
+/**
+ * Haines Index category information
+ * The Haines Index measures atmospheric stability and dryness that affect fire growth potential
+ * Scale: 2-6 (Low, Moderate, High fire growth potential)
+ */
+export interface HainesCategory {
+    level: string;
+    description: string;
+    fireGrowthPotential: string;
+    color: string;
+}
+/**
+ * Get Haines Index category
+ * Haines Index: 2-6 scale measuring atmospheric contribution to fire growth
+ * - Low elevation (< 3,000 ft): 2-3 = Low, 4 = Moderate, 5-6 = High
+ * - Mid elevation (3,000-10,000 ft): Same scale
+ * - High elevation (> 10,000 ft): Same scale
+ */
+export declare function getHainesCategory(hainesValue: number): HainesCategory;
+/**
+ * Get grassland fire danger category
+ * Scale: 1-4 (Low, Moderate, High, Very High)
+ */
+export declare function getGrasslandFireDangerCategory(value: number): {
+    level: string;
+    description: string;
+    color: string;
+};
+/**
+ * Get red flag threat index category
+ * Indicates potential for Red Flag Warning conditions
+ */
+export declare function getRedFlagCategory(value: number): {
+    level: string;
+    description: string;
+    color: string;
+};
+/**
+ * Get current fire weather value from gridpoint data series
+ * Returns the value for the current time period
+ */
+export declare function getCurrentFireWeatherValue(dataSeries: {
+    values: Array<{
+        validTime: string;
+        value: number;
+    }>;
+} | undefined): number | null;
+/**
+ * Format mixing height value
+ * Mixing height indicates how high smoke and pollutants can rise
+ * Higher is generally better for smoke dispersion
+ */
+export declare function formatMixingHeight(heightFt: number | null): string;
+/**
+ * Interpret transport wind speed for fire behavior
+ * Transport winds carry smoke and can influence fire spread
+ */
+export declare function interpretTransportWind(speedMph: number | null): string;
+/**
+ * Fire weather context information for when indices aren't available
+ */
+export interface FireWeatherContext {
+    hasIndices: boolean;
+    reason: string;
+    seasonalRisk: 'Low' | 'Moderate' | 'Elevated' | 'High';
+    explanatoryText: string;
+}
+/**
+ * Determine fire weather context and why indices may not be available
+ * Provides user-friendly explanations for missing fire weather data
+ */
+export declare function getFireWeatherContext(latitude: number, longitude: number, timestamp: string, hainesValue: number | null, grasslandValue: number | null, redFlagValue: number | null, humidity?: number | null): FireWeatherContext;
+//# sourceMappingURL=fireWeather.d.ts.map

package/dist/utils/fireWeather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fireWeather.d.ts","sourceRoot":"","sources":["../../src/utils/fireWeather.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CA8BrE;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CA0BA;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf,CA0BA;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQzI;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAclE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CActE;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,KAAK,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACvD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,EAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,kBAAkB,CAsEpB"}

package/dist/utils/fireWeather.js

@@ -0,0 +1,243 @@
+/**
+ * Fire weather utility functions for interpreting fire danger indices
+ */
+/**
+ * Get Haines Index category
+ * Haines Index: 2-6 scale measuring atmospheric contribution to fire growth
+ * - Low elevation (< 3,000 ft): 2-3 = Low, 4 = Moderate, 5-6 = High
+ * - Mid elevation (3,000-10,000 ft): Same scale
+ * - High elevation (> 10,000 ft): Same scale
+ */
+export function getHainesCategory(hainesValue) {
+    if (hainesValue <= 3) {
+        return {
+            level: 'Low',
+            description: 'Low fire growth potential',
+            fireGrowthPotential: 'Very low likelihood of large plume-dominated fire growth. Fires should remain relatively easy to control.',
+            color: 'Green'
+        };
+    }
+    else if (hainesValue === 4) {
+        return {
+            level: 'Moderate',
+            description: 'Moderate fire growth potential',
+            fireGrowthPotential: 'Moderate likelihood of plume-dominated fire growth. Fires may develop rapidly and become difficult to control.',
+            color: 'Yellow'
+        };
+    }
+    else if (hainesValue === 5) {
+        return {
+            level: 'High',
+            description: 'High fire growth potential',
+            fireGrowthPotential: 'High likelihood of plume-dominated fire growth. Fires may exhibit extreme behavior and become very difficult to control.',
+            color: 'Orange'
+        };
+    }
+    else {
+        return {
+            level: 'Very High',
+            description: 'Very high fire growth potential',
+            fireGrowthPotential: 'Very high likelihood of extreme fire behavior. Fires will likely exhibit blow-up characteristics and be extremely difficult to control.',
+            color: 'Red'
+        };
+    }
+}
+/**
+ * Get grassland fire danger category
+ * Scale: 1-4 (Low, Moderate, High, Very High)
+ */
+export function getGrasslandFireDangerCategory(value) {
+    if (value <= 1) {
+        return {
+            level: 'Low',
+            description: 'Low fire danger in grassland/rangeland fuels',
+            color: 'Green'
+        };
+    }
+    else if (value === 2) {
+        return {
+            level: 'Moderate',
+            description: 'Moderate fire danger in grassland/rangeland fuels',
+            color: 'Yellow'
+        };
+    }
+    else if (value === 3) {
+        return {
+            level: 'High',
+            description: 'High fire danger in grassland/rangeland fuels',
+            color: 'Orange'
+        };
+    }
+    else {
+        return {
+            level: 'Very High',
+            description: 'Very high fire danger in grassland/rangeland fuels',
+            color: 'Red'
+        };
+    }
+}
+/**
+ * Get red flag threat index category
+ * Indicates potential for Red Flag Warning conditions
+ */
+export function getRedFlagCategory(value) {
+    if (value < 30) {
+        return {
+            level: 'Low',
+            description: 'Low threat of Red Flag Warning conditions',
+            color: 'Green'
+        };
+    }
+    else if (value < 60) {
+        return {
+            level: 'Moderate',
+            description: 'Moderate threat of Red Flag Warning conditions',
+            color: 'Yellow'
+        };
+    }
+    else if (value < 80) {
+        return {
+            level: 'High',
+            description: 'High threat of Red Flag Warning conditions',
+            color: 'Orange'
+        };
+    }
+    else {
+        return {
+            level: 'Very High',
+            description: 'Very high threat - Red Flag Warning likely',
+            color: 'Red'
+        };
+    }
+}
+/**
+ * Get current fire weather value from gridpoint data series
+ * Returns the value for the current time period
+ */
+export function getCurrentFireWeatherValue(dataSeries) {
+    if (!dataSeries || !dataSeries.values || dataSeries.values.length === 0) {
+        return null;
+    }
+    // Get the first value (most recent/current)
+    // NOAA gridpoint data is ordered with current/near-future values first
+    return dataSeries.values[0]?.value ?? null;
+}
+/**
+ * Format mixing height value
+ * Mixing height indicates how high smoke and pollutants can rise
+ * Higher is generally better for smoke dispersion
+ */
+export function formatMixingHeight(heightFt) {
+    if (heightFt === null) {
+        return 'N/A';
+    }
+    if (heightFt < 1000) {
+        return `${Math.round(heightFt)} ft (very poor dispersion)`;
+    }
+    else if (heightFt < 3000) {
+        return `${Math.round(heightFt)} ft (poor dispersion)`;
+    }
+    else if (heightFt < 6000) {
+        return `${Math.round(heightFt)} ft (moderate dispersion)`;
+    }
+    else {
+        return `${Math.round(heightFt)} ft (good dispersion)`;
+    }
+}
+/**
+ * Interpret transport wind speed for fire behavior
+ * Transport winds carry smoke and can influence fire spread
+ */
+export function interpretTransportWind(speedMph) {
+    if (speedMph === null) {
+        return 'N/A';
+    }
+    if (speedMph < 5) {
+        return `${Math.round(speedMph)} mph (light - poor smoke transport)`;
+    }
+    else if (speedMph < 15) {
+        return `${Math.round(speedMph)} mph (moderate smoke transport)`;
+    }
+    else if (speedMph < 25) {
+        return `${Math.round(speedMph)} mph (good smoke transport)`;
+    }
+    else {
+        return `${Math.round(speedMph)} mph (strong - rapid fire spread potential)`;
+    }
+}
+/**
+ * Determine fire weather context and why indices may not be available
+ * Provides user-friendly explanations for missing fire weather data
+ */
+export function getFireWeatherContext(latitude, longitude, timestamp, hainesValue, grasslandValue, redFlagValue, humidity) {
+    const hasIndices = hainesValue !== null || grasslandValue !== null || redFlagValue !== null;
+    // Parse month from timestamp
+    const date = new Date(timestamp);
+    const month = date.getMonth() + 1; // 1-12
+    // Determine geographic region
+    const isWestern = longitude < -100; // Western US (higher fire risk regions)
+    const isSouthwest = latitude < 40 && longitude < -100; // Southwest US
+    const isCalifornia = latitude > 32 && latitude < 42 && longitude > -124 && longitude < -114;
+    const isSouthern = latitude < 35; // Southern states
+    // Determine seasonal fire risk
+    let seasonalRisk = 'Low';
+    let reason = '';
+    let explanatoryText = '';
+    if (hasIndices) {
+        // Indices are present - fire conditions warrant monitoring
+        seasonalRisk = 'Elevated';
+        reason = 'Fire conditions warrant monitoring';
+        explanatoryText = 'Current atmospheric conditions support potential fire weather concerns.';
+    }
+    else {
+        // Indices not present - determine why
+        // Check if it's winter (low fire season everywhere)
+        if (month >= 11 || month <= 3) {
+            seasonalRisk = 'Low';
+            reason = 'Winter/low fire season';
+            if (isCalifornia) {
+                // California can have winter fires (Santa Ana season)
+                explanatoryText = 'Out of peak fire season. Fire danger indices are calculated during elevated risk periods (typically spring-fall, or during Santa Ana wind events).';
+            }
+            else if (isSouthern) {
+                explanatoryText = 'Winter season with minimal fire risk. Fire danger indices are calculated during dry periods with elevated fire potential.';
+            }
+            else {
+                explanatoryText = 'Winter season with minimal fire risk due to cold temperatures, snow cover, or high humidity. Fire danger indices are calculated during dry, warm periods with elevated fire potential.';
+            }
+        }
+        else if (month >= 4 && month <= 10) {
+            // Fire season months - but indices still not present
+            if (humidity !== null && humidity !== undefined && humidity > 70) {
+                seasonalRisk = 'Low';
+                reason = 'High humidity/recent precipitation';
+                explanatoryText = 'Current conditions (high humidity, recent precipitation) do not support significant fire weather threats. Fire danger indices are calculated when atmospheric conditions favor fire growth.';
+            }
+            else if (isWestern || isSouthwest || isCalifornia) {
+                // Western US during fire season - indices should typically be present
+                seasonalRisk = 'Moderate';
+                reason = 'Favorable conditions';
+                explanatoryText = 'Current conditions do not meet thresholds for fire weather concerns. Fire danger indices are calculated during periods of low humidity, high temperatures, and strong winds.';
+            }
+            else {
+                // Eastern US during summer
+                seasonalRisk = 'Low';
+                reason = 'Regional/seasonal factors';
+                explanatoryText = 'Low regional fire risk. Fire danger indices are primarily calculated for western states and during periods of drought or extreme fire weather conditions.';
+            }
+        }
+        else {
+            // Shoulder season (early spring/late fall)
+            seasonalRisk = 'Low';
+            reason = 'Seasonal conditions';
+            explanatoryText = 'Current seasonal conditions do not support significant fire weather threats. Fire danger indices are calculated during periods of elevated fire risk.';
+        }
+    }
+    return {
+        hasIndices,
+        reason,
+        seasonalRisk,
+        explanatoryText
+    };
+}
+//# sourceMappingURL=fireWeather.js.map

package/dist/utils/fireWeather.js.map

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

package/dist/utils/geography.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Geographic utility functions for location detection and classification
+ */
+/**
+ * Bounding box for a geographic region
+ */
+interface BoundingBox {
+    minLat: number;
+    maxLat: number;
+    minLon: number;
+    maxLon: number;
+}
+/**
+ * Geographic region with bounding box and metadata
+ */
+interface GeographicRegion {
+    name: string;
+    bbox: BoundingBox;
+    description?: string;
+}
+/**
+ * Check if coordinates are within the Great Lakes region
+ * @param latitude Latitude coordinate
+ * @param longitude Longitude coordinate
+ * @returns The Great Lake name if in region, null otherwise
+ */
+export declare function getGreatLakeRegion(latitude: number, longitude: number): string | null;
+/**
+ * Check if coordinates are within a major US coastal bay or large inland lake
+ * @param latitude Latitude coordinate
+ * @param longitude Longitude coordinate
+ * @returns The bay/lake name if in region, null otherwise
+ */
+export declare function getMajorCoastalBayRegion(latitude: number, longitude: number): string | null;
+/**
+ * Check if coordinates should use NOAA marine data (Great Lakes or major coastal bays)
+ * @param latitude Latitude coordinate
+ * @param longitude Longitude coordinate
+ * @returns Object with detection results
+ */
+export declare function shouldUseNOAAMarine(latitude: number, longitude: number): {
+    useNOAA: boolean;
+    region: string | null;
+    source: 'great-lakes' | 'coastal-bay' | 'ocean';
+};
+/**
+ * Get a human-readable description of the marine region
+ * @param latitude Latitude coordinate
+ * @param longitude Longitude coordinate
+ * @returns Description string
+ */
+export declare function getMarineRegionDescription(latitude: number, longitude: number): string;
+/**
+ * Get all Great Lakes regions (for testing and documentation)
+ */
+export declare function getGreatLakesRegions(): GeographicRegion[];
+/**
+ * Get all major coastal bay regions (for testing and documentation)
+ */
+export declare function getMajorCoastalBayRegions(): GeographicRegion[];
+/**
+ * Approximate country/region detection from coordinates
+ * PRIVACY: Intentionally vague - only major regions for privacy
+ * ACCURACY: This is a ROUGH approximation with known inaccuracies:
+ *   - Mexico, Caribbean, Central America -> OTHER
+ *   - Some border regions may be misclassified
+ *   - Alaska and Hawaii have special handling
+ *
+ * This is called OUTSIDE the analytics module to ensure coordinates
+ * never enter the analytics boundary. Trade-off: Privacy (no reverse geocoding)
+ * vs Accuracy (bounding boxes)
+ *
+ * @param lat Latitude (-90 to 90)
+ * @param lon Longitude (-180 to 180)
+ * @returns ISO 3166-1 alpha-2 region code (US, CA, EU, AP, SA, AF, OC, OTHER)
+ */
+export declare function getCountryFromCoordinates(lat: number, lon: number): string;
+export {};
+//# sourceMappingURL=geography.d.ts.map

package/dist/utils/geography.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geography.d.ts","sourceRoot":"","sources":["../../src/utils/geography.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAgID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOrF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO3F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC;CACjD,CA2BA;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQtF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,EAAE,CAEzD;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,gBAAgB,EAAE,CAE9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAgD1E"}