@aguacerowx/javascript-sdk 0.0.20 → 0.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aguacerowx/javascript-sdk",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "private": false,
   "publishConfig": {
     "access": "public"

package/src/AguaceroCore.js

@@ -11,14 +11,15 @@ import { processCompressedGrid } from './gridDecodePipeline.js';
 import { getBundleId } from './getBundleId';
 import {
     SATELLITE_FRAMES_URL,
-    buildSatelliteTimelineForKey,
-    SATELLITE_DURATION_CONFIG,
-    TIMELINE_DURATION_HOUR_VALUES,
-    normalizeTimelineDurationValue,
+    buildSatelliteTimelineForSelection,
+    formatTimelineDurationValue,
+    resolveSatelliteSectorLabel,
+    resolveSatelliteDurationOption,
     parseTimelineDurationHours,
 } from './satellite_support.js';
 import {
     fetchNexradTimesListing,
+    inferNexradDataSourceForProduct,
     nexradColormapFldKey,
     variableToNexradGroup,
     getAvailableNexradTilts,
@@ -140,17 +141,40 @@ export class AguaceroCore extends EventEmitter {
 
         const initialSatellite = initialMode === 'satellite';
         const initialNexrad = initialMode === 'nexrad';
-        const initialNexradDs = userLayerOptions.nexradDataSource || 'level2';
         const initialNexradProd = userLayerOptions.nexradProduct || 'REF';
+        const initialNexradDs =
+            userLayerOptions.nexradDataSource != null
+                ? userLayerOptions.nexradDataSource === 'level3'
+                    ? 'level3'
+                    : 'level2'
+                : inferNexradDataSourceForProduct(initialNexradProd);
         const initialNexradFld = initialNexrad
             ? nexradColormapFldKey(initialNexradDs, initialNexradProd)
             : initialVariable;
+        let initialSatelliteInstrumentId = null;
+        let initialSatelliteSectorLabel = null;
+        let initialSatelliteChannel = null;
+        if (initialSatellite) {
+            initialSatelliteInstrumentId = userLayerOptions.satelliteId ?? 'GOES19-EAST';
+            initialSatelliteSectorLabel = resolveSatelliteSectorLabel(
+                userLayerOptions.satelliteSector ?? userLayerOptions.sector ?? 'conus',
+            );
+            initialSatelliteChannel =
+                userLayerOptions.satelliteProduct ??
+                userLayerOptions.satelliteChannel ??
+                initialVariable ??
+                'C13';
+        }
         this.state = {
             model: userLayerOptions.model || 'gfs',
             // EDIT: Set isMRMS based on the initial mode
             isMRMS: initialMode === 'mrms' && !initialSatellite && !initialNexrad,
             mrmsTimestamp: null,
-            variable: initialNexrad ? initialNexradFld : initialVariable,
+            variable: initialNexrad
+                ? initialNexradFld
+                : initialSatellite && initialSatelliteInstrumentId
+                  ? initialSatelliteChannel
+                  : initialVariable,
             date: null,
             run: null,
             forecastHour: 0,
@@ -159,21 +183,20 @@ export class AguaceroCore extends EventEmitter {
             units: options.initialUnit || 'imperial',
             shaderSmoothingEnabled: options.shaderSmoothingEnabled ?? true,
             isSatellite: initialSatellite,
-            satelliteKey: userLayerOptions.satelliteKey || null,
+            satelliteInstrumentId: initialSatelliteInstrumentId,
+            satelliteSectorLabel: initialSatelliteSectorLabel,
+            satelliteChannel: initialSatelliteChannel,
             satelliteTimestamp: userLayerOptions.satelliteTimestamp != null ? Number(userLayerOptions.satelliteTimestamp) : null,
             satelliteTier: userLayerOptions.satelliteTier || 'basic',
-            satelliteDurationValue: (() => {
-                const n = normalizeTimelineDurationValue(
-                    userLayerOptions.satelliteDurationValue != null ? userLayerOptions.satelliteDurationValue : '1'
-                );
-                return TIMELINE_DURATION_HOUR_VALUES.includes(n) ? n : '1';
-            })(),
-            mrmsDurationValue: (() => {
-                const n = normalizeTimelineDurationValue(
-                    userLayerOptions.mrmsDurationValue != null ? userLayerOptions.mrmsDurationValue : '1'
-                );
-                return TIMELINE_DURATION_HOUR_VALUES.includes(n) ? n : '1';
-            })(),
+            satelliteDurationValue: formatTimelineDurationValue(
+                userLayerOptions.satelliteDurationValue != null ? userLayerOptions.satelliteDurationValue : '1',
+            ),
+            mrmsDurationValue: formatTimelineDurationValue(
+                userLayerOptions.mrmsDurationValue != null ? userLayerOptions.mrmsDurationValue : '1',
+            ),
+            nexradDurationValue: formatTimelineDurationValue(
+                userLayerOptions.nexradDurationValue != null ? userLayerOptions.nexradDurationValue : '1',
+            ),
             isNexrad: initialNexrad,
             nexradSite: userLayerOptions.nexradSite ?? null,
             nexradDataSource: initialNexradDs,
@@ -200,6 +223,7 @@ export class AguaceroCore extends EventEmitter {
 
     async setState(newState) {
         const patch = { ...newState };
+        if ('satelliteKey' in patch) delete patch.satelliteKey;
         if ('forecastHour' in patch && patch.forecastHour != null) {
             patch.forecastHour = Number(patch.forecastHour);
         }
@@ -210,12 +234,13 @@ export class AguaceroCore extends EventEmitter {
             patch.satelliteTimestamp = Number(patch.satelliteTimestamp);
         }
         if ('satelliteDurationValue' in patch && patch.satelliteDurationValue != null) {
-            const n = normalizeTimelineDurationValue(patch.satelliteDurationValue);
-            patch.satelliteDurationValue = TIMELINE_DURATION_HOUR_VALUES.includes(n) ? n : '1';
+            patch.satelliteDurationValue = formatTimelineDurationValue(patch.satelliteDurationValue);
         }
         if ('mrmsDurationValue' in patch && patch.mrmsDurationValue != null) {
-            const n = normalizeTimelineDurationValue(patch.mrmsDurationValue);
-            patch.mrmsDurationValue = TIMELINE_DURATION_HOUR_VALUES.includes(n) ? n : '1';
+            patch.mrmsDurationValue = formatTimelineDurationValue(patch.mrmsDurationValue);
+        }
+        if ('nexradDurationValue' in patch && patch.nexradDurationValue != null) {
+            patch.nexradDurationValue = formatTimelineDurationValue(patch.nexradDurationValue);
         }
         if ('nexradTimestamp' in patch && patch.nexradTimestamp != null) {
             patch.nexradTimestamp = Number(patch.nexradTimestamp);
@@ -253,23 +278,23 @@ export class AguaceroCore extends EventEmitter {
     }
 
     _computeSatelliteTimeline() {
-        if (!this.state.satelliteKey || !this.satelliteListing?.objects) {
+        const { satelliteInstrumentId, satelliteSectorLabel, satelliteChannel } = this.state;
+        if (!satelliteInstrumentId || !satelliteSectorLabel || !satelliteChannel || !this.satelliteListing?.objects) {
             return { unixTimes: [], timeToFileMap: {} };
         }
         const allFiles = this.satelliteListing.objects.map((o) => o.key);
-        const sectorName = this.state.satelliteKey.split('.')[1] || 'GOES-EAST CONUS';
-        let sectorType = 'CONUS';
-        if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';
-        else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+        const sectorName = satelliteSectorLabel;
         const tier = this.state.satelliteTier || 'basic';
-        const tierConfig =
-            SATELLITE_DURATION_CONFIG[sectorType]?.[tier] || SATELLITE_DURATION_CONFIG.CONUS.basic;
-        const durationKey = normalizeTimelineDurationValue(this.state.satelliteDurationValue);
-        const durationOpt =
-            tierConfig.find((o) => String(o.value) === String(durationKey)) ||
-            tierConfig.find((o) => o.value === '1') ||
-            tierConfig[0];
-        return buildSatelliteTimelineForKey(this.state.satelliteKey, allFiles, durationOpt);
+        const durationOpt = resolveSatelliteDurationOption(sectorName, tier, this.state.satelliteDurationValue);
+        return buildSatelliteTimelineForSelection(
+            {
+                satelliteInstrumentId,
+                satelliteSectorLabel,
+                satelliteChannel,
+            },
+            allFiles,
+            durationOpt,
+        );
     }
 
     /**
@@ -295,7 +320,7 @@ export class AguaceroCore extends EventEmitter {
     }
 
     _nexradListingWindowHours() {
-        return parseTimelineDurationHours(this.state.mrmsDurationValue);
+        return parseTimelineDurationHours(this.state.nexradDurationValue);
     }
 
     _getFilteredNexradTimestampsForVariable(rawList) {
@@ -357,7 +382,7 @@ export class AguaceroCore extends EventEmitter {
 
         let availableSatelliteTimestamps = [];
         let satelliteTimeToFileMap = {};
-        if (this.state.isSatellite && this.state.satelliteKey) {
+        if (this.state.isSatellite && this.state.satelliteInstrumentId) {
             const timeline = this._computeSatelliteTimeline();
             satelliteTimeToFileMap = timeline.timeToFileMap || {};
             availableSatelliteTimestamps = [...(timeline.unixTimes || [])]
@@ -416,7 +441,7 @@ export class AguaceroCore extends EventEmitter {
 
         let initialState = { ...this.state };
 
-        if (initialState.isSatellite && initialState.satelliteKey) {
+        if (initialState.isSatellite && initialState.satelliteInstrumentId) {
             const timeline = this._computeSatelliteTimeline();
             const tsList = [...(timeline.unixTimes || [])].sort((a, b) => a - b);
             if (initialState.satelliteTimestamp == null && tsList.length > 0) {
@@ -625,7 +650,13 @@ export class AguaceroCore extends EventEmitter {
     async setModel(modelName) {
         if (modelName === this.state.model || !this.modelStatus?.[modelName]) return;
         if (this.state.isSatellite) {
-            await this.setState({ isSatellite: false, satelliteKey: null, satelliteTimestamp: null });
+            await this.setState({
+                isSatellite: false,
+                satelliteInstrumentId: null,
+                satelliteSectorLabel: null,
+                satelliteChannel: null,
+                satelliteTimestamp: null,
+            });
         }
         const latestRun = findLatestModelRun(this.modelStatus, modelName);
         if (latestRun) {
@@ -674,7 +705,9 @@ export class AguaceroCore extends EventEmitter {
             variable,
             isMRMS: true,
             isSatellite: false,
-            satelliteKey: null,
+            satelliteInstrumentId: null,
+            satelliteSectorLabel: null,
+            satelliteChannel: null,
             satelliteTimestamp: null,
             mrmsTimestamp: initialTimestamp,
         });
@@ -691,14 +724,13 @@ export class AguaceroCore extends EventEmitter {
     }
 
     /**
-     * How many hours of satellite frames to include in the timeline (1, 4, 6, or 12).
+     * How many hours of satellite frames to include in the timeline (positive, at most 12 hours).
      * API default: `layerOptions.satelliteDurationValue` on construction.
      */
     async setSatelliteDurationValue(value) {
-        const v = normalizeTimelineDurationValue(value);
-        if (!TIMELINE_DURATION_HOUR_VALUES.includes(v)) return;
+        const v = formatTimelineDurationValue(value);
         await this.setState({ satelliteDurationValue: v });
-        if (!this.state.isSatellite || !this.state.satelliteKey) return;
+        if (!this.state.isSatellite || !this.state.satelliteInstrumentId) return;
         const timeline = this._computeSatelliteTimeline();
         const tsList = [...(timeline.unixTimes || [])]
             .map((t) => Number(t))
@@ -713,30 +745,35 @@ export class AguaceroCore extends EventEmitter {
     }
 
     /**
-     * How many hours of MRMS frames to include in the timeline (1, 4, 6, or 12).
+     * Set satellite view using spacecraft id, sector, and channel/product.
+     * Omitted fields keep the current selection; when not in satellite mode, missing fields use GOES-19 East CONUS / C13 defaults.
+     * @param {{ satelliteId?: string, sector?: string, satelliteSector?: string, satelliteProduct?: string, satelliteChannel?: string, satelliteTimestamp?: number|null }} opts
+     */
+    async setSatelliteSelection(opts = {}) {
+        const cur = this.state.isSatellite ? this.state : null;
+        const tsArg =
+            opts.satelliteTimestamp !== undefined
+                ? opts.satelliteTimestamp
+                : this.state.isSatellite && this.state.satelliteTimestamp != null
+                  ? Number(this.state.satelliteTimestamp)
+                  : undefined;
+        return this.switchMode({
+            mode: 'satellite',
+            satelliteId: opts.satelliteId ?? cur?.satelliteInstrumentId ?? 'GOES19-EAST',
+            satelliteSector: opts.satelliteSector ?? opts.sector ?? cur?.satelliteSectorLabel ?? 'conus',
+            satelliteProduct:
+                opts.satelliteProduct ?? opts.satelliteChannel ?? cur?.satelliteChannel ?? 'C13',
+            satelliteTimestamp: tsArg,
+        });
+    }
+
+    /**
+     * How many hours of MRMS frames to include in the timeline (positive, at most 12 hours).
      * API default: `layerOptions.mrmsDurationValue` on construction.
      */
     async setMRMSDurationValue(value) {
-        const v = normalizeTimelineDurationValue(value);
-        if (!TIMELINE_DURATION_HOUR_VALUES.includes(v)) return;
+        const v = formatTimelineDurationValue(value);
         await this.setState({ mrmsDurationValue: v });
-        // NEXRAD listings are fetched with `hours` from this value (see _nexradListingWindowHours). Without a
-        // refresh, expanding 1h→4h only re-filters the old in-memory sweep list — new frames never appear until
-        // site/product changes trigger refreshNexradTimes.
-        if (this.state.isNexrad && this.state.nexradSite) {
-            await this.refreshNexradTimes();
-            const nk = this._nexradTimesCacheKey();
-            const filtered = this._getFilteredNexradTimestampsForVariable(
-                nk ? this.nexradTimesByStation[nk]?.unixTimes || [] : [],
-            );
-            if (filtered.length === 0) return;
-            const cur = this.state.nexradTimestamp;
-            const curN = cur == null ? null : Number(cur);
-            if (curN == null || !filtered.includes(curN)) {
-                await this.setState({ nexradTimestamp: filtered[filtered.length - 1] });
-            }
-            return;
-        }
         if (!this.state.isMRMS || !this.state.variable) return;
         const filtered = this._getFilteredMrmsTimestampsForVariable(this.state.variable);
         if (filtered.length === 0) return;
@@ -747,8 +784,29 @@ export class AguaceroCore extends EventEmitter {
         }
     }
 
+    /**
+     * NEXRAD sweep listing / scrub window in hours (independent of MRMS duration).
+     * API default: `layerOptions.nexradDurationValue` on construction.
+     */
+    async setNexradDurationValue(value) {
+        const v = formatTimelineDurationValue(value);
+        await this.setState({ nexradDurationValue: v });
+        if (!this.state.isNexrad || !this.state.nexradSite) return;
+        await this.refreshNexradTimes();
+        const nk = this._nexradTimesCacheKey();
+        const filtered = this._getFilteredNexradTimestampsForVariable(
+            nk ? this.nexradTimesByStation[nk]?.unixTimes || [] : [],
+        );
+        if (filtered.length === 0) return;
+        const cur = this.state.nexradTimestamp;
+        const curN = cur == null ? null : Number(cur);
+        if (curN == null || !filtered.includes(curN)) {
+            await this.setState({ nexradTimestamp: filtered[filtered.length - 1] });
+        }
+    }
+
     async switchMode(options) {
-        const { mode, variable, model, forecastHour, mrmsTimestamp, satelliteKey, satelliteTimestamp } = options;
+        let { mode, variable, model, forecastHour, mrmsTimestamp, satelliteTimestamp } = options;
         if (!mode) {
             return;
         }
@@ -758,18 +816,23 @@ export class AguaceroCore extends EventEmitter {
         if ((mode === 'mrms' || mode === 'model') && !variable) {
             return;
         }
-        if (mode === 'satellite' && !satelliteKey) {
-            return;
-        }
         let targetState = {};
         if (mode === 'satellite') {
-            const channelToken = satelliteKey.split('.').pop() || variable || 'C13';
+            const satelliteInstrumentId = options.satelliteId ?? 'GOES19-EAST';
+            const satelliteSectorLabel = resolveSatelliteSectorLabel(
+                options.satelliteSector ?? options.sector ?? 'conus',
+            );
+            const satelliteChannel =
+                options.satelliteProduct ?? options.satelliteChannel ?? variable ?? 'C13';
+            const channelToken = satelliteChannel;
             // Emit satellite mode immediately so map layers (e.g. model grid) clear before listing fetch finishes.
             await this.setState({
                 isSatellite: true,
                 isMRMS: false,
                 isNexrad: false,
-                satelliteKey,
+                satelliteInstrumentId,
+                satelliteSectorLabel,
+                satelliteChannel,
                 variable: channelToken,
                 satelliteTimestamp: null,
                 mrmsTimestamp: null,
@@ -780,19 +843,14 @@ export class AguaceroCore extends EventEmitter {
 
             await this.fetchSatelliteListing(true);
             const allFiles = this.satelliteListing?.objects?.map((o) => o.key) || [];
-            const sectorName = satelliteKey.split('.')[1] || 'GOES-EAST CONUS';
-            let sectorType = 'CONUS';
-            if (sectorName.includes('FULL DISK')) sectorType = 'FULL_DISK';
-            else if (sectorName.includes('MESOSCALE')) sectorType = 'MESOSCALE';
+            const sectorName = satelliteSectorLabel;
             const tier = this.state.satelliteTier || 'basic';
-            const tierConfig =
-                SATELLITE_DURATION_CONFIG[sectorType]?.[tier] || SATELLITE_DURATION_CONFIG.CONUS.basic;
-            const durationKey = normalizeTimelineDurationValue(this.state.satelliteDurationValue);
-            const durationOpt =
-                tierConfig.find((o) => String(o.value) === String(durationKey)) ||
-                tierConfig.find((o) => o.value === '1') ||
-                tierConfig[0];
-            const timeline = buildSatelliteTimelineForKey(satelliteKey, allFiles, durationOpt);
+            const durationOpt = resolveSatelliteDurationOption(sectorName, tier, this.state.satelliteDurationValue);
+            const timeline = buildSatelliteTimelineForSelection(
+                { satelliteInstrumentId, satelliteSectorLabel, satelliteChannel },
+                allFiles,
+                durationOpt,
+            );
             const tsList = [...(timeline.unixTimes || [])].sort((a, b) => a - b);
             let finalTs = satelliteTimestamp !== undefined ? satelliteTimestamp : null;
             if (finalTs == null && tsList.length > 0) {
@@ -821,7 +879,9 @@ export class AguaceroCore extends EventEmitter {
                 variable: variable,
                 mrmsTimestamp: finalTimestamp,
                 model: this.state.model, date: null, run: null, forecastHour: 0,
-                satelliteKey: null,
+                satelliteInstrumentId: null,
+                satelliteSectorLabel: null,
+                satelliteChannel: null,
                 satelliteTimestamp: null,
             };
         } else if (mode === 'model') {
@@ -855,12 +915,19 @@ export class AguaceroCore extends EventEmitter {
                 run: latestRun.run,
                 forecastHour: initialHour,  // <-- Changed
                 mrmsTimestamp: null,
-                satelliteKey: null,
+                satelliteInstrumentId: null,
+                satelliteSectorLabel: null,
+                satelliteChannel: null,
                 satelliteTimestamp: null,
             };
         } else if (mode === 'nexrad') {
-            const nexradDataSource = options.nexradDataSource || 'level2';
             const nexradProduct = options.nexradProduct || 'REF';
+            const nexradDataSource =
+                options.nexradDataSource != null
+                    ? options.nexradDataSource === 'level3'
+                        ? 'level3'
+                        : 'level2'
+                    : inferNexradDataSourceForProduct(nexradProduct);
             const fld = nexradColormapFldKey(nexradDataSource, nexradProduct);
             const site = options.nexradSite ?? null;
             let tilt =
@@ -881,8 +948,13 @@ export class AguaceroCore extends EventEmitter {
                 nexradTimestamp: options.nexradTimestamp != null ? Number(options.nexradTimestamp) : null,
                 nexradStormRelative: options.nexradStormRelative === true,
                 nexradShowSitesPicker: options.nexradShowSitesPicker !== false,
+                ...(options.nexradDurationValue != null
+                    ? { nexradDurationValue: formatTimelineDurationValue(options.nexradDurationValue) }
+                    : {}),
                 mrmsTimestamp: null,
-                satelliteKey: null,
+                satelliteInstrumentId: null,
+                satelliteSectorLabel: null,
+                satelliteChannel: null,
                 satelliteTimestamp: null,
                 date: null,
                 run: null,
@@ -995,10 +1067,10 @@ export class AguaceroCore extends EventEmitter {
     async setNexradProduct(product) {
         if (!this.state.isNexrad) return;
         const p = (product || 'REF').toUpperCase();
-        const ds = this.state.nexradDataSource || 'level2';
+        const ds = inferNexradDataSourceForProduct(p);
         const fld = nexradColormapFldKey(ds, p);
         const nexradStormRelative = this._nexradStormRelativeFor(ds, p);
-        await this.setState({ nexradProduct: p, variable: fld, nexradStormRelative });
+        await this.setState({ nexradProduct: p, nexradDataSource: ds, variable: fld, nexradStormRelative });
         await this.refreshNexradTimes();
         const filtered = this._getFilteredNexradTimestampsForVariable(
             this.nexradTimesByStation[this._nexradTimesCacheKey()]?.unixTimes || [],
@@ -1025,8 +1097,9 @@ export class AguaceroCore extends EventEmitter {
     }
 
     /**
-     * Sets NEXRAD product and archive source together (single refresh). Used when the UI exposes one
-     * combined menu instead of separate “Level II / Level III” controls.
+     * Sets NEXRAD product and archive source together (single refresh). Prefer {@link setNexradProduct}
+     * for product-only changes (Level II vs III is inferred). Use this when you must force a specific
+     * archive source (rare).
      * @param {'level2'|'level3'} dataSource
      * @param {string} product - Level-II variable (REF, VEL, …) or Level-III radar key (N0H, HHC, …)
      */

package/src/index.js

@@ -13,14 +13,18 @@ export {
     GOES_SATELLITE_CHANNELS,
     GOES_SATELLITE_CHANNEL_LABELS,
     SATELLITE_DURATION_CONFIG,
+    TIMELINE_DURATION_MAX_HOURS,
     TIMELINE_DURATION_HOUR_VALUES,
+    formatTimelineDurationValue,
     normalizeTimelineDurationValue,
     parseTimelineDurationHours,
+    resolveSatelliteDurationOption,
     getDefaultSatelliteDurationOption,
-    buildSatelliteTimelineForKey,
-    getAllGoesEastSatelliteKeys,
+    buildSatelliteTimelineForSelection,
+    getAllGoesEastSatelliteSelections,
     calculateUnixTimeFromSatelliteKey,
     resolveSatelliteS3FileName,
+    resolveSatelliteSectorLabel,
 } from './satellite_support.js';
 
 // Now, export them all so other packages can import them.

package/src/nexrad_support.js

@@ -14,6 +14,17 @@ import {
     getNexradLevel3EntryByRadarKey,
 } from './nexrad_level3_catalog.js';
 
+/**
+ * Whether listings and archive fetches for this product use Level-II sweep lambda vs Level-III S3 products.
+ * AguaceroCore applies this from the product key; set `nexradDataSource` in layer options only to override (rare).
+ * @param {string} [nexradProduct] - Radar variable key (e.g. REF, KDP, VEL).
+ * @returns {'level2'|'level3'}
+ */
+export function inferNexradDataSourceForProduct(nexradProduct) {
+    const p = (nexradProduct || 'REF').toUpperCase();
+    return getNexradLevel3EntryByRadarKey(p) ? 'level3' : 'level2';
+}
+
 /** Colormap / DICTIONARIES.fld key for customColormaps (matches frontend userDefaultColormap). */
 export function nexradColormapFldKey(nexradDataSource, nexradProduct) {
     const p = (nexradProduct || 'REF').toUpperCase();

package/src/satellite_support.js

@@ -13,6 +13,33 @@ export const GOES_EAST_SATELLITE_SECTORS = [
     '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'],
@@ -75,8 +102,12 @@ const SATELLITE_RGB_PRODUCT_UPPER = new Set([
 ]);
 
 /**
- * Allowed timeline window lengths (hours) for satellite and MRMS in the Web SDK.
- * Values are stringified for state and API parity with satellite duration options.
+ * 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'];
 
@@ -113,24 +144,54 @@ export const SATELLITE_DURATION_CONFIG = {
 };
 
 /**
- * Normalizes satellite or MRMS duration option values (including legacy '0.5' → '1').
+ * 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) {
-    const s = value == null ? '1' : String(value);
-    return LEGACY_SATELLITE_DURATION_ALIASES[s] || s;
+    return formatTimelineDurationValue(value);
 }
 
 /**
- * @param {string|number} value
- * @returns {number} Hours in [1, 4, 6, 12], defaulting to 1.
+ * 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 parseTimelineDurationHours(value) {
-    const s = normalizeTimelineDurationValue(value);
-    const n = Number(s);
-    if (TIMELINE_DURATION_HOUR_VALUES.includes(s) && [1, 4, 6, 12].includes(n)) return n;
-    return 1;
+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') {
@@ -160,16 +221,17 @@ export function calculateUnixTimeFromSatelliteKey(fileKey) {
 }
 
 /**
- * @param {string} satelliteKey e.g. "GOES19-EAST.GOES-EAST CONUS.C13"
+ * @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 buildSatelliteTimelineForKey(satelliteKey, allFiles, durationOption) {
-    const parts = satelliteKey.split('.');
-    if (parts.length < 3) {
+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 [satelliteName, categoryName, channelName] = parts;
 
     const SECTOR_CODE_MAP_LOCAL = {
         'GOES-EAST CONUS': 'C',
@@ -274,23 +336,32 @@ export function buildSatelliteTimelineForKey(satelliteKey, allFiles, durationOpt
 }
 
 /**
- * Full satellite keys for GOES-19 East (same naming as production).
+ * 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 getAllGoesEastSatelliteKeys(satelliteName = 'GOES19-EAST') {
-    const keys = [];
+export function getAllGoesEastSatelliteSelections(satelliteInstrumentId = 'GOES19-EAST') {
+    const out = [];
     for (const sector of GOES_EAST_SATELLITE_SECTORS) {
         for (const ch of GOES_SATELLITE_CHANNELS) {
-            keys.push(`${satelliteName}.${sector}.${ch}`);
+            out.push({
+                satelliteInstrumentId,
+                satelliteSectorLabel: sector,
+                satelliteChannel: ch,
+            });
         }
     }
-    return keys;
+    return out;
 }
 
-export function resolveSatelliteS3FileName(satelliteKey, timeToFileMap, satelliteTimestamp) {
+/**
+ * @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] = satelliteKey.split('.');
-    const channelNameUpper = channelName.toUpperCase();
+    const channelName = satelliteChannel;
+    const channelNameUpper = String(channelName).toUpperCase();
     let name = fileFromMap || '';
     if (!name && satelliteTimestamp != null) {
         const suffix = `_${String(Math.floor(Number(satelliteTimestamp)))}`;