@aguacerowx/javascript-sdk 0.0.27 → 0.0.28

package/src/satellite_support.js

@@ -1,376 +1,376 @@
-/**
- * Satellite listing / timeline helpers aligned with aguacero-frontend (ActiveTimeContext + satelliteAvailability).
- * Used by AguaceroCore for GOES-East WebGL satellite mode.
- */
-
-export const SATELLITE_FRAMES_URL = 'https://rhnq3edhcry5n6nljn6my4o3h40zwxze.lambda-url.us-east-2.on.aws/';
-
-/** Same sector labels as production bundle / ActiveTimeContext SECTOR_CODE_MAP (inverse). */
-export const GOES_EAST_SATELLITE_SECTORS = [
-    'GOES-EAST CONUS',
-    'GOES-EAST FULL DISK',
-    'GOES-EAST MESOSCALE 1',
-    'GOES-EAST MESOSCALE 2',
-];
-
-const SECTOR_SYNONYM_TO_LABEL = {
-    conus: 'GOES-EAST CONUS',
-    full_disk: 'GOES-EAST FULL DISK',
-    fulldisk: 'GOES-EAST FULL DISK',
-    mesoscale_1: 'GOES-EAST MESOSCALE 1',
-    mesoscale1: 'GOES-EAST MESOSCALE 1',
-    m1: 'GOES-EAST MESOSCALE 1',
-    mesoscale_2: 'GOES-EAST MESOSCALE 2',
-    mesoscale2: 'GOES-EAST MESOSCALE 2',
-    m2: 'GOES-EAST MESOSCALE 2',
-};
-
-/**
- * Normalizes a sector argument to the listing sector label (middle segment; must match archive paths).
- * Accepts short tokens (<code>conus</code>, <code>full_disk</code>, …), synonyms (<code>m1</code>, <code>fulldisk</code>, …), or full labels (passthrough for West / custom feeds).
- * @param {string} [sector]
- * @returns {string}
- */
-export function resolveSatelliteSectorLabel(sector) {
-    if (sector == null || sector === '') return 'GOES-EAST CONUS';
-    const raw = String(sector).trim();
-    const norm = raw.toLowerCase().replace(/[\s-]+/g, '_');
-    if (SECTOR_SYNONYM_TO_LABEL[norm]) return SECTOR_SYNONYM_TO_LABEL[norm];
-    if (GOES_EAST_SATELLITE_SECTORS.includes(raw)) return raw;
-    return raw;
-}
-
-/** Flat channel ids matching CHANNEL_CATEGORIES in frontend dictionaries. */
-export const GOES_SATELLITE_CHANNELS = [
-    ...['true_color', 'geocolor', 'ntmicro', 'day_cloud_phase', 'day_land_cloud_fire', 'air_mass', 'sandwich', 'simple_water_vapor', 'dust', 'fire_temperature'],
-    'C01', 'C02', 'C03', 'C04', 'C05', 'C06', 'C07', 'C08', 'C09', 'C10', 'C11', 'C12', 'C13', 'C14', 'C15', 'C16',
-];
-
-/**
- * Human-readable labels for {@link GOES_SATELLITE_CHANNELS}, aligned with aguacero-frontend `CHANNEL_LABELS`.
- */
-export const GOES_SATELLITE_CHANNEL_LABELS = {
-    true_color: 'True Color',
-    ntmicro: 'Night Microphysics',
-    day_cloud_phase: 'Day Cloud Phase',
-    day_land_cloud_fire: 'Natural Color Fire',
-    air_mass: 'Air Mass',
-    sandwich: 'Sandwich',
-    simple_water_vapor: 'Simple Water Vapor',
-    dust: 'Dust',
-    geocolor: 'Geocolor',
-    fire_temperature: 'Fire Temperature',
-    C01: 'Blue - Visible',
-    C02: 'Red - Visible',
-    C03: 'Veggie - Near IR',
-    C04: 'Cirrus - Near IR',
-    C05: 'Snow/Ice - Near IR',
-    C06: 'Cloud Particle - Near IR',
-    C07: 'Shortwave Window - IR',
-    C08: 'Upper-Level Water Vapor - IR',
-    C09: 'Mid-Level Water Vapor - IR',
-    C10: 'Lower-Level Water Vapor - IR',
-    C11: 'Cloud Top - IR',
-    C12: 'Ozone - IR',
-    C13: 'Clean Longwave Window - IR',
-    C14: 'Longwave Window - IR',
-    C15: 'Dirty Longwave Window - IR',
-    C16: 'CO2 Longwave - IR',
-};
-
-const SECTOR_CODE_MAP = {
-    'GOES-EAST CONUS': 'C',
-    'GOES-EAST FULL DISK': 'F',
-    'GOES-EAST MESOSCALE 1': 'M1',
-    'GOES-EAST MESOSCALE 2': 'M2',
-};
-
-const LUMPED_MULTIBAND_SATELLITE_SECTORS = new Set(['GOES-EAST CONUS', 'GOES-EAST FULL DISK']);
-
-/** Uppercase RGB channel tokens as in production (CHANNEL_CATEGORIES.RGB). */
-const SATELLITE_RGB_PRODUCT_UPPER = new Set([
-    'TRUE_COLOR',
-    'GEOCOLOR',
-    'NTMICRO',
-    'DAY_CLOUD_PHASE',
-    'DAY_LAND_CLOUD_FIRE',
-    'AIR_MASS',
-    'SANDWICH',
-    'SIMPLE_WATER_VAPOR',
-    'DUST',
-    'FIRE_TEMPERATURE',
-]);
-
-/**
- * Maximum timeline window length in hours for satellite, MRMS, and NEXRAD. Values are clamped to (0, this].
- */
-export const TIMELINE_DURATION_MAX_HOURS = 12;
-
-/**
- * Preset hour buttons (UI). Any positive duration ≤ {@link TIMELINE_DURATION_MAX_HOURS} is valid via {@link formatTimelineDurationValue}.
- */
-export const TIMELINE_DURATION_HOUR_VALUES = ['1', '4', '6', '12'];
-
-const LEGACY_SATELLITE_DURATION_ALIASES = {
-    '0.5': '1',
-};
-
-/** Tier keys used in SATELLITE_DURATION_CONFIG (frontend dictionaries). */
-export const SATELLITE_DURATION_CONFIG = {
-    CONUS: {
-        basic: [
-            { label: '1 Hr', value: '1', interval: 300 },
-            { label: '4 Hr', value: '4', interval: 300 },
-            { label: '6 Hr', value: '6', interval: 300 },
-            { label: '12 Hr', value: '12', interval: 300 },
-        ],
-    },
-    FULL_DISK: {
-        basic: [
-            { label: '1 Hr', value: '1', interval: 600 },
-            { label: '4 Hr', value: '4', interval: 600 },
-            { label: '6 Hr', value: '6', interval: 600 },
-            { label: '12 Hr', value: '12', interval: 600 },
-        ],
-    },
-    MESOSCALE: {
-        basic: [
-            { label: '1 Hr', value: '1', interval: 120 },
-            { label: '4 Hr', value: '4', interval: 120 },
-            { label: '6 Hr', value: '6', interval: 120 },
-            { label: '12 Hr', value: '12', interval: 120 },
-        ],
-    },
-};
-
-/**
- * Parses a user duration to hours, then clamps to a positive value not exceeding {@link TIMELINE_DURATION_MAX_HOURS}.
- * @param {string|number} value
- * @returns {number}
- */
-export function parseTimelineDurationHours(value) {
-    let s = value == null ? '1' : String(value).trim();
-    s = LEGACY_SATELLITE_DURATION_ALIASES[s] || s;
-    const n = Number(s);
-    if (!Number.isFinite(n) || n <= 0) return 1;
-    if (n > TIMELINE_DURATION_MAX_HOURS) return TIMELINE_DURATION_MAX_HOURS;
-    return n;
-}
-
-/**
- * Canonical string for AguaceroCore state (stable for equality checks). Supports fractional hours (e.g. <code>'2.5'</code>).
- * @param {string|number} value
- * @returns {string}
- */
-export function formatTimelineDurationValue(value) {
-    const n = parseTimelineDurationHours(value);
-    if (Math.abs(n - Math.round(n)) < 1e-6) return String(Math.round(n));
-    return String(Math.round(n * 10000) / 10000);
-}
-
-/** @returns {string} Same as {@link formatTimelineDurationValue} (backward-compatible name). */
-export function normalizeTimelineDurationValue(value) {
-    return formatTimelineDurationValue(value);
-}
-
-/**
- * Picks a preset GOES duration option when one matches; otherwise builds a custom option using the same cadence as the 1&nbsp;hr preset for that sector/tier.
- * @param {string} sectorName - e.g. <code>GOES-EAST CONUS</code>
- * @param {string} [tier='basic']
- * @param {string|number} durationValue
- * @returns {{ label: string, value: string, interval: number }}
- */
-export function resolveSatelliteDurationOption(sectorName, tier, durationValue) {
-    let sectorType = 'CONUS';
-    if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';
-    else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
-    const t = tier || 'basic';
-    const tierConfig =
-        SATELLITE_DURATION_CONFIG[sectorType]?.[t] || SATELLITE_DURATION_CONFIG.CONUS.basic;
-    const key = formatTimelineDurationValue(durationValue);
-    const preset = tierConfig.find((o) => String(o.value) === String(key));
-    if (preset) return preset;
-    const interval = tierConfig.find((o) => o.value === '1')?.interval || 300;
-    return { label: `${key} Hr`, value: key, interval };
-}
-
-export function getDefaultSatelliteDurationOption(sectorName, tier = 'basic') {
-    let sectorType = 'CONUS';
-    if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';
-    else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
-    const tierConfig = SATELLITE_DURATION_CONFIG[sectorType]?.[tier] || SATELLITE_DURATION_CONFIG.CONUS.basic;
-    return tierConfig.find((o) => o.value === '1') || tierConfig[0];
-}
-
-export function calculateUnixTimeFromSatelliteKey(fileKey) {
-    try {
-        const match = fileKey.match(/_(\d{10})(?:\.ktx2)?$/);
-        if (match) return parseInt(match[1], 10);
-        const oldMatch = fileKey.match(/_s(\d{4})(\d{3})(\d{2})(\d{2})(\d{2})/);
-        if (oldMatch) {
-            const [, year, dayOfYear, hour, minute, second] = oldMatch.map(Number);
-            const date = new Date(Date.UTC(year, 0, 1));
-            date.setUTCDate(dayOfYear);
-            date.setUTCHours(hour, minute, second, 0);
-            return date.getTime() / 1000;
-        }
-        return 0;
-    } catch {
-        return 0;
-    }
-}
-
-/**
- * @param {{ satelliteInstrumentId: string, satelliteSectorLabel: string, satelliteChannel: string }} selection
- * @param {string[]} allFiles S3 keys from satellite listing API
- * @param {{ value: string, interval: number }} durationOption
- */
-export function buildSatelliteTimelineForSelection(selection, allFiles, durationOption) {
-    const satelliteName = selection?.satelliteInstrumentId;
-    const categoryName = selection?.satelliteSectorLabel;
-    const channelName = selection?.satelliteChannel;
-    if (!satelliteName || !categoryName || !channelName) {
-        return { unixTimes: [], fileList: [], timeToFileMap: {} };
-    }
-
-    const SECTOR_CODE_MAP_LOCAL = {
-        'GOES-EAST CONUS': 'C',
-        'GOES-EAST FULL DISK': 'F',
-        'GOES-EAST MESOSCALE 1': 'M1',
-        'GOES-EAST MESOSCALE 2': 'M2',
-    };
-
-    const satelliteNum = satelliteName.replace('GOES', '').replace('-EAST', '').replace('-WEST', '');
-    const satId = `G${satelliteNum}`;
-    const sectorCode = SECTOR_CODE_MAP_LOCAL[categoryName] || 'C';
-
-    let sectorType = 'CONUS';
-    if (categoryName.includes('FULL DISK')) sectorType = 'FULL_DISK';
-    else if (categoryName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
-
-    const intervalSeconds = durationOption?.interval || 300;
-    const durationHours = durationOption?.value ? parseFloat(durationOption.value) : 1;
-
-    const filePrefix = `${sectorCode}_${satId}_`;
-
-    let searchProduct = channelName.toUpperCase();
-    if (!/^C\d{2}$/.test(searchProduct)) {
-        if (SATELLITE_RGB_PRODUCT_UPPER.has(searchProduct)) {
-            searchProduct = LUMPED_MULTIBAND_SATELLITE_SECTORS.has(categoryName) ? 'MULTI' : searchProduct;
-        } else {
-            searchProduct = 'MULTI';
-        }
-    }
-
-    const matchString = `${filePrefix}${searchProduct}`;
-
-    let relevantFiles = allFiles.filter((file) => file.startsWith(matchString));
-
-    if (relevantFiles.length === 0) {
-        return { unixTimes: [], fileList: [], timeToFileMap: {} };
-    }
-
-    relevantFiles.sort((a, b) => {
-        const timeA = calculateUnixTimeFromSatelliteKey(a);
-        const timeB = calculateUnixTimeFromSatelliteKey(b);
-        return timeA - timeB;
-    });
-
-    let cutoffTime = 0;
-    if (durationHours > 0) {
-        const latestTime = calculateUnixTimeFromSatelliteKey(relevantFiles[relevantFiles.length - 1]);
-        cutoffTime = latestTime - durationHours * 3600;
-    }
-
-    let processedFiles = relevantFiles.filter((f) => calculateUnixTimeFromSatelliteKey(f) >= cutoffTime);
-
-    if (intervalSeconds > 0 && processedFiles.length > 0) {
-        const intervalMinutes = intervalSeconds / 60;
-
-        if (sectorType === 'MESOSCALE') {
-            processedFiles = processedFiles.filter((file) => {
-                if (intervalMinutes <= 1.1) return true;
-                const t = calculateUnixTimeFromSatelliteKey(file);
-                const date = new Date(t * 1000);
-                const minutes = date.getUTCMinutes();
-                return minutes % intervalMinutes === 0;
-            });
-        } else {
-            if (intervalSeconds >= 300) {
-                processedFiles = processedFiles.filter((file) => {
-                    if (Math.abs(intervalMinutes - 5) < 0.1) return true;
-                    const t = calculateUnixTimeFromSatelliteKey(file);
-                    const minutes = new Date(t * 1000).getUTCMinutes();
-                    const remainder = minutes % intervalMinutes;
-                    const distToInterval = Math.min(remainder, intervalMinutes - remainder);
-                    return distToInterval < 2.5;
-                });
-            } else {
-                processedFiles = processedFiles.filter((file) => {
-                    const t = calculateUnixTimeFromSatelliteKey(file);
-                    const minutes = new Date(t * 1000).getUTCMinutes();
-                    return minutes % intervalMinutes === 0;
-                });
-            }
-        }
-
-        if (processedFiles.length === 0 && relevantFiles.length > 0) {
-            processedFiles = relevantFiles.slice(-1);
-        }
-    }
-
-    const unixTimes = [];
-    const timeToFileMap = {};
-    processedFiles.forEach((file) => {
-        const unixTime = calculateUnixTimeFromSatelliteKey(file);
-        if (unixTime > 0) {
-            unixTimes.push(unixTime);
-            timeToFileMap[unixTime] = file;
-        }
-    });
-
-    // Chronological (oldest → newest): matches standard time sliders (earlier left, later right).
-    unixTimes.sort((a, b) => a - b);
-
-    return { unixTimes, fileList: processedFiles, timeToFileMap };
-}
-
-/**
- * All GOES-East spacecraft / sector / channel combinations the SDK knows (same naming as production).
- * @param {string} [satelliteInstrumentId='GOES19-EAST']
- * @returns {Array<{ satelliteInstrumentId: string, satelliteSectorLabel: string, satelliteChannel: string }>}
- */
-export function getAllGoesEastSatelliteSelections(satelliteInstrumentId = 'GOES19-EAST') {
-    const out = [];
-    for (const sector of GOES_EAST_SATELLITE_SECTORS) {
-        for (const ch of GOES_SATELLITE_CHANNELS) {
-            out.push({
-                satelliteInstrumentId,
-                satelliteSectorLabel: sector,
-                satelliteChannel: ch,
-            });
-        }
-    }
-    return out;
-}
-
-/**
- * @param {string} satelliteChannel — band or RGB id (third segment of the archive descriptor)
- */
-export function resolveSatelliteS3FileName(satelliteChannel, timeToFileMap, satelliteTimestamp) {
-    const fileFromMap = timeToFileMap?.[satelliteTimestamp];
-    if (fileFromMap) return fileFromMap;
-    const channelName = satelliteChannel;
-    const channelNameUpper = String(channelName).toUpperCase();
-    let name = fileFromMap || '';
-    if (!name && satelliteTimestamp != null) {
-        const suffix = `_${String(Math.floor(Number(satelliteTimestamp)))}`;
-        const multiName = Object.values(timeToFileMap || {}).find((f) => f.includes('MULTI') && f.includes(suffix));
-        if (multiName) {
-            name = multiName.replace('MULTI', channelNameUpper);
-        }
-    }
-    return name;
-}
-
-export { SECTOR_CODE_MAP };
+/**
+ * Satellite listing / timeline helpers aligned with aguacero-frontend (ActiveTimeContext + satelliteAvailability).
+ * Used by AguaceroCore for GOES-East WebGL satellite mode.
+ */
+
+export const SATELLITE_FRAMES_URL = 'https://rhnq3edhcry5n6nljn6my4o3h40zwxze.lambda-url.us-east-2.on.aws/';
+
+/** Same sector labels as production bundle / ActiveTimeContext SECTOR_CODE_MAP (inverse). */
+export const GOES_EAST_SATELLITE_SECTORS = [
+    'GOES-EAST CONUS',
+    'GOES-EAST FULL DISK',
+    'GOES-EAST MESOSCALE 1',
+    'GOES-EAST MESOSCALE 2',
+];
+
+const SECTOR_SYNONYM_TO_LABEL = {
+    conus: 'GOES-EAST CONUS',
+    full_disk: 'GOES-EAST FULL DISK',
+    fulldisk: 'GOES-EAST FULL DISK',
+    mesoscale_1: 'GOES-EAST MESOSCALE 1',
+    mesoscale1: 'GOES-EAST MESOSCALE 1',
+    m1: 'GOES-EAST MESOSCALE 1',
+    mesoscale_2: 'GOES-EAST MESOSCALE 2',
+    mesoscale2: 'GOES-EAST MESOSCALE 2',
+    m2: 'GOES-EAST MESOSCALE 2',
+};
+
+/**
+ * Normalizes a sector argument to the listing sector label (middle segment; must match archive paths).
+ * Accepts short tokens (<code>conus</code>, <code>full_disk</code>, …), synonyms (<code>m1</code>, <code>fulldisk</code>, …), or full labels (passthrough for West / custom feeds).
+ * @param {string} [sector]
+ * @returns {string}
+ */
+export function resolveSatelliteSectorLabel(sector) {
+    if (sector == null || sector === '') return 'GOES-EAST CONUS';
+    const raw = String(sector).trim();
+    const norm = raw.toLowerCase().replace(/[\s-]+/g, '_');
+    if (SECTOR_SYNONYM_TO_LABEL[norm]) return SECTOR_SYNONYM_TO_LABEL[norm];
+    if (GOES_EAST_SATELLITE_SECTORS.includes(raw)) return raw;
+    return raw;
+}
+
+/** Flat channel ids matching CHANNEL_CATEGORIES in frontend dictionaries. */
+export const GOES_SATELLITE_CHANNELS = [
+    ...['true_color', 'geocolor', 'ntmicro', 'day_cloud_phase', 'day_land_cloud_fire', 'air_mass', 'sandwich', 'simple_water_vapor', 'dust', 'fire_temperature'],
+    'C01', 'C02', 'C03', 'C04', 'C05', 'C06', 'C07', 'C08', 'C09', 'C10', 'C11', 'C12', 'C13', 'C14', 'C15', 'C16',
+];
+
+/**
+ * Human-readable labels for {@link GOES_SATELLITE_CHANNELS}, aligned with aguacero-frontend `CHANNEL_LABELS`.
+ */
+export const GOES_SATELLITE_CHANNEL_LABELS = {
+    true_color: 'True Color',
+    ntmicro: 'Night Microphysics',
+    day_cloud_phase: 'Day Cloud Phase',
+    day_land_cloud_fire: 'Natural Color Fire',
+    air_mass: 'Air Mass',
+    sandwich: 'Sandwich',
+    simple_water_vapor: 'Simple Water Vapor',
+    dust: 'Dust',
+    geocolor: 'Geocolor',
+    fire_temperature: 'Fire Temperature',
+    C01: 'Blue - Visible',
+    C02: 'Red - Visible',
+    C03: 'Veggie - Near IR',
+    C04: 'Cirrus - Near IR',
+    C05: 'Snow/Ice - Near IR',
+    C06: 'Cloud Particle - Near IR',
+    C07: 'Shortwave Window - IR',
+    C08: 'Upper-Level Water Vapor - IR',
+    C09: 'Mid-Level Water Vapor - IR',
+    C10: 'Lower-Level Water Vapor - IR',
+    C11: 'Cloud Top - IR',
+    C12: 'Ozone - IR',
+    C13: 'Clean Longwave Window - IR',
+    C14: 'Longwave Window - IR',
+    C15: 'Dirty Longwave Window - IR',
+    C16: 'CO2 Longwave - IR',
+};
+
+const SECTOR_CODE_MAP = {
+    'GOES-EAST CONUS': 'C',
+    'GOES-EAST FULL DISK': 'F',
+    'GOES-EAST MESOSCALE 1': 'M1',
+    'GOES-EAST MESOSCALE 2': 'M2',
+};
+
+const LUMPED_MULTIBAND_SATELLITE_SECTORS = new Set(['GOES-EAST CONUS', 'GOES-EAST FULL DISK']);
+
+/** Uppercase RGB channel tokens as in production (CHANNEL_CATEGORIES.RGB). */
+const SATELLITE_RGB_PRODUCT_UPPER = new Set([
+    'TRUE_COLOR',
+    'GEOCOLOR',
+    'NTMICRO',
+    'DAY_CLOUD_PHASE',
+    'DAY_LAND_CLOUD_FIRE',
+    'AIR_MASS',
+    'SANDWICH',
+    'SIMPLE_WATER_VAPOR',
+    'DUST',
+    'FIRE_TEMPERATURE',
+]);
+
+/**
+ * Maximum timeline window length in hours for satellite, MRMS, and NEXRAD. Values are clamped to (0, this].
+ */
+export const TIMELINE_DURATION_MAX_HOURS = 12;
+
+/**
+ * Preset hour buttons (UI). Any positive duration ≤ {@link TIMELINE_DURATION_MAX_HOURS} is valid via {@link formatTimelineDurationValue}.
+ */
+export const TIMELINE_DURATION_HOUR_VALUES = ['1', '4', '6', '12'];
+
+const LEGACY_SATELLITE_DURATION_ALIASES = {
+    '0.5': '1',
+};
+
+/** Tier keys used in SATELLITE_DURATION_CONFIG (frontend dictionaries). */
+export const SATELLITE_DURATION_CONFIG = {
+    CONUS: {
+        basic: [
+            { label: '1 Hr', value: '1', interval: 300 },
+            { label: '4 Hr', value: '4', interval: 300 },
+            { label: '6 Hr', value: '6', interval: 300 },
+            { label: '12 Hr', value: '12', interval: 300 },
+        ],
+    },
+    FULL_DISK: {
+        basic: [
+            { label: '1 Hr', value: '1', interval: 600 },
+            { label: '4 Hr', value: '4', interval: 600 },
+            { label: '6 Hr', value: '6', interval: 600 },
+            { label: '12 Hr', value: '12', interval: 600 },
+        ],
+    },
+    MESOSCALE: {
+        basic: [
+            { label: '1 Hr', value: '1', interval: 120 },
+            { label: '4 Hr', value: '4', interval: 120 },
+            { label: '6 Hr', value: '6', interval: 120 },
+            { label: '12 Hr', value: '12', interval: 120 },
+        ],
+    },
+};
+
+/**
+ * Parses a user duration to hours, then clamps to a positive value not exceeding {@link TIMELINE_DURATION_MAX_HOURS}.
+ * @param {string|number} value
+ * @returns {number}
+ */
+export function parseTimelineDurationHours(value) {
+    let s = value == null ? '1' : String(value).trim();
+    s = LEGACY_SATELLITE_DURATION_ALIASES[s] || s;
+    const n = Number(s);
+    if (!Number.isFinite(n) || n <= 0) return 1;
+    if (n > TIMELINE_DURATION_MAX_HOURS) return TIMELINE_DURATION_MAX_HOURS;
+    return n;
+}
+
+/**
+ * Canonical string for AguaceroCore state (stable for equality checks). Supports fractional hours (e.g. <code>'2.5'</code>).
+ * @param {string|number} value
+ * @returns {string}
+ */
+export function formatTimelineDurationValue(value) {
+    const n = parseTimelineDurationHours(value);
+    if (Math.abs(n - Math.round(n)) < 1e-6) return String(Math.round(n));
+    return String(Math.round(n * 10000) / 10000);
+}
+
+/** @returns {string} Same as {@link formatTimelineDurationValue} (backward-compatible name). */
+export function normalizeTimelineDurationValue(value) {
+    return formatTimelineDurationValue(value);
+}
+
+/**
+ * Picks a preset GOES duration option when one matches; otherwise builds a custom option using the same cadence as the 1&nbsp;hr preset for that sector/tier.
+ * @param {string} sectorName - e.g. <code>GOES-EAST CONUS</code>
+ * @param {string} [tier='basic']
+ * @param {string|number} durationValue
+ * @returns {{ label: string, value: string, interval: number }}
+ */
+export function resolveSatelliteDurationOption(sectorName, tier, durationValue) {
+    let sectorType = 'CONUS';
+    if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';
+    else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+    const t = tier || 'basic';
+    const tierConfig =
+        SATELLITE_DURATION_CONFIG[sectorType]?.[t] || SATELLITE_DURATION_CONFIG.CONUS.basic;
+    const key = formatTimelineDurationValue(durationValue);
+    const preset = tierConfig.find((o) => String(o.value) === String(key));
+    if (preset) return preset;
+    const interval = tierConfig.find((o) => o.value === '1')?.interval || 300;
+    return { label: `${key} Hr`, value: key, interval };
+}
+
+export function getDefaultSatelliteDurationOption(sectorName, tier = 'basic') {
+    let sectorType = 'CONUS';
+    if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';
+    else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+    const tierConfig = SATELLITE_DURATION_CONFIG[sectorType]?.[tier] || SATELLITE_DURATION_CONFIG.CONUS.basic;
+    return tierConfig.find((o) => o.value === '1') || tierConfig[0];
+}
+
+export function calculateUnixTimeFromSatelliteKey(fileKey) {
+    try {
+        const match = fileKey.match(/_(\d{10})(?:\.ktx2)?$/);
+        if (match) return parseInt(match[1], 10);
+        const oldMatch = fileKey.match(/_s(\d{4})(\d{3})(\d{2})(\d{2})(\d{2})/);
+        if (oldMatch) {
+            const [, year, dayOfYear, hour, minute, second] = oldMatch.map(Number);
+            const date = new Date(Date.UTC(year, 0, 1));
+            date.setUTCDate(dayOfYear);
+            date.setUTCHours(hour, minute, second, 0);
+            return date.getTime() / 1000;
+        }
+        return 0;
+    } catch {
+        return 0;
+    }
+}
+
+/**
+ * @param {{ satelliteInstrumentId: string, satelliteSectorLabel: string, satelliteChannel: string }} selection
+ * @param {string[]} allFiles S3 keys from satellite listing API
+ * @param {{ value: string, interval: number }} durationOption
+ */
+export function buildSatelliteTimelineForSelection(selection, allFiles, durationOption) {
+    const satelliteName = selection?.satelliteInstrumentId;
+    const categoryName = selection?.satelliteSectorLabel;
+    const channelName = selection?.satelliteChannel;
+    if (!satelliteName || !categoryName || !channelName) {
+        return { unixTimes: [], fileList: [], timeToFileMap: {} };
+    }
+
+    const SECTOR_CODE_MAP_LOCAL = {
+        'GOES-EAST CONUS': 'C',
+        'GOES-EAST FULL DISK': 'F',
+        'GOES-EAST MESOSCALE 1': 'M1',
+        'GOES-EAST MESOSCALE 2': 'M2',
+    };
+
+    const satelliteNum = satelliteName.replace('GOES', '').replace('-EAST', '').replace('-WEST', '');
+    const satId = `G${satelliteNum}`;
+    const sectorCode = SECTOR_CODE_MAP_LOCAL[categoryName] || 'C';
+
+    let sectorType = 'CONUS';
+    if (categoryName.includes('FULL DISK')) sectorType = 'FULL_DISK';
+    else if (categoryName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+
+    const intervalSeconds = durationOption?.interval || 300;
+    const durationHours = durationOption?.value ? parseFloat(durationOption.value) : 1;
+
+    const filePrefix = `${sectorCode}_${satId}_`;
+
+    let searchProduct = channelName.toUpperCase();
+    if (!/^C\d{2}$/.test(searchProduct)) {
+        if (SATELLITE_RGB_PRODUCT_UPPER.has(searchProduct)) {
+            searchProduct = LUMPED_MULTIBAND_SATELLITE_SECTORS.has(categoryName) ? 'MULTI' : searchProduct;
+        } else {
+            searchProduct = 'MULTI';
+        }
+    }
+
+    const matchString = `${filePrefix}${searchProduct}`;
+
+    let relevantFiles = allFiles.filter((file) => file.startsWith(matchString));
+
+    if (relevantFiles.length === 0) {
+        return { unixTimes: [], fileList: [], timeToFileMap: {} };
+    }
+
+    relevantFiles.sort((a, b) => {
+        const timeA = calculateUnixTimeFromSatelliteKey(a);
+        const timeB = calculateUnixTimeFromSatelliteKey(b);
+        return timeA - timeB;
+    });
+
+    let cutoffTime = 0;
+    if (durationHours > 0) {
+        const latestTime = calculateUnixTimeFromSatelliteKey(relevantFiles[relevantFiles.length - 1]);
+        cutoffTime = latestTime - durationHours * 3600;
+    }
+
+    let processedFiles = relevantFiles.filter((f) => calculateUnixTimeFromSatelliteKey(f) >= cutoffTime);
+
+    if (intervalSeconds > 0 && processedFiles.length > 0) {
+        const intervalMinutes = intervalSeconds / 60;
+
+        if (sectorType === 'MESOSCALE') {
+            processedFiles = processedFiles.filter((file) => {
+                if (intervalMinutes <= 1.1) return true;
+                const t = calculateUnixTimeFromSatelliteKey(file);
+                const date = new Date(t * 1000);
+                const minutes = date.getUTCMinutes();
+                return minutes % intervalMinutes === 0;
+            });
+        } else {
+            if (intervalSeconds >= 300) {
+                processedFiles = processedFiles.filter((file) => {
+                    if (Math.abs(intervalMinutes - 5) < 0.1) return true;
+                    const t = calculateUnixTimeFromSatelliteKey(file);
+                    const minutes = new Date(t * 1000).getUTCMinutes();
+                    const remainder = minutes % intervalMinutes;
+                    const distToInterval = Math.min(remainder, intervalMinutes - remainder);
+                    return distToInterval < 2.5;
+                });
+            } else {
+                processedFiles = processedFiles.filter((file) => {
+                    const t = calculateUnixTimeFromSatelliteKey(file);
+                    const minutes = new Date(t * 1000).getUTCMinutes();
+                    return minutes % intervalMinutes === 0;
+                });
+            }
+        }
+
+        if (processedFiles.length === 0 && relevantFiles.length > 0) {
+            processedFiles = relevantFiles.slice(-1);
+        }
+    }
+
+    const unixTimes = [];
+    const timeToFileMap = {};
+    processedFiles.forEach((file) => {
+        const unixTime = calculateUnixTimeFromSatelliteKey(file);
+        if (unixTime > 0) {
+            unixTimes.push(unixTime);
+            timeToFileMap[unixTime] = file;
+        }
+    });
+
+    // Chronological (oldest → newest): matches standard time sliders (earlier left, later right).
+    unixTimes.sort((a, b) => a - b);
+
+    return { unixTimes, fileList: processedFiles, timeToFileMap };
+}
+
+/**
+ * All GOES-East spacecraft / sector / channel combinations the SDK knows (same naming as production).
+ * @param {string} [satelliteInstrumentId='GOES19-EAST']
+ * @returns {Array<{ satelliteInstrumentId: string, satelliteSectorLabel: string, satelliteChannel: string }>}
+ */
+export function getAllGoesEastSatelliteSelections(satelliteInstrumentId = 'GOES19-EAST') {
+    const out = [];
+    for (const sector of GOES_EAST_SATELLITE_SECTORS) {
+        for (const ch of GOES_SATELLITE_CHANNELS) {
+            out.push({
+                satelliteInstrumentId,
+                satelliteSectorLabel: sector,
+                satelliteChannel: ch,
+            });
+        }
+    }
+    return out;
+}
+
+/**
+ * @param {string} satelliteChannel — band or RGB id (third segment of the archive descriptor)
+ */
+export function resolveSatelliteS3FileName(satelliteChannel, timeToFileMap, satelliteTimestamp) {
+    const fileFromMap = timeToFileMap?.[satelliteTimestamp];
+    if (fileFromMap) return fileFromMap;
+    const channelName = satelliteChannel;
+    const channelNameUpper = String(channelName).toUpperCase();
+    let name = fileFromMap || '';
+    if (!name && satelliteTimestamp != null) {
+        const suffix = `_${String(Math.floor(Number(satelliteTimestamp)))}`;
+        const multiName = Object.values(timeToFileMap || {}).find((f) => f.includes('MULTI') && f.includes(suffix));
+        if (multiName) {
+            name = multiName.replace('MULTI', channelNameUpper);
+        }
+    }
+    return name;
+}
+
+export { SECTOR_CODE_MAP };