@aguacerowx/javascript-sdk 0.0.20 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aguacerowx/javascript-sdk",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -25,6 +25,11 @@
       "import": "./src/nexrad_support.js",
       "require": "./src/nexrad_support.js",
       "default": "./src/nexrad_support.js"
+    },
+    "./nexradTiltCoalesce.js": {
+      "import": "./src/nexradTiltCoalesce.js",
+      "require": "./src/nexradTiltCoalesce.js",
+      "default": "./src/nexradTiltCoalesce.js"
     }
   },
   "files": [

package/src/AguaceroCore.js

@@ -11,18 +11,21 @@ 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,
+    getRawNexradTiltsForCoalesce,
 } from './nexrad_support.js';
+import { nexradLayerTiltToDisplayOption } from './nexradTiltCoalesce.js';
 import { NEXRAD_LEVEL3_ELEV, getNexradLevel3EntryByRadarKey } from './nexrad_level3_catalog.js';
 import {
     setRadarTiltsManifest,
@@ -140,17 +143,35 @@ 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 = 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 +180,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 +220,20 @@ export class AguaceroCore extends EventEmitter {
 
     async setState(newState) {
         const patch = { ...newState };
+        if ('satelliteKey' in patch) delete patch.satelliteKey;
+        if ('nexradDataSource' in patch && !('nexradProduct' in patch)) {
+            delete patch.nexradDataSource;
+        }
+        const willBeNexrad =
+            patch.isNexrad !== undefined ? Boolean(patch.isNexrad) : this.state.isNexrad;
+        if (willBeNexrad && 'nexradProduct' in patch && patch.nexradProduct != null) {
+            const p = (patch.nexradProduct || 'REF').toUpperCase();
+            const ds = inferNexradDataSourceForProduct(p);
+            patch.nexradProduct = p;
+            patch.nexradDataSource = ds;
+            patch.variable = nexradColormapFldKey(ds, p);
+            patch.nexradStormRelative = this._nexradStormRelativeFor(ds, p);
+        }
         if ('forecastHour' in patch && patch.forecastHour != null) {
             patch.forecastHour = Number(patch.forecastHour);
         }
@@ -210,12 +244,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 +288,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 +330,7 @@ export class AguaceroCore extends EventEmitter {
     }
 
     _nexradListingWindowHours() {
-        return parseTimelineDurationHours(this.state.mrmsDurationValue);
+        return parseTimelineDurationHours(this.state.nexradDurationValue);
     }
 
     _getFilteredNexradTimestampsForVariable(rawList) {
@@ -357,7 +392,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 +451,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 +660,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 +715,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 +734,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 +755,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 +794,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 +826,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 +853,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 +889,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,13 +925,14 @@ 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 fld = nexradColormapFldKey(nexradDataSource, nexradProduct);
+            const p = nexradProduct.toUpperCase();
             const site = options.nexradSite ?? null;
             let tilt =
                 options.nexradTilt != null
@@ -873,16 +944,19 @@ export class AguaceroCore extends EventEmitter {
                 isNexrad: true,
                 isMRMS: false,
                 isSatellite: false,
-                variable: fld,
                 nexradSite: site,
-                nexradDataSource,
-                nexradProduct,
+                nexradProduct: p,
                 nexradTilt: tilt,
                 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,
@@ -913,26 +987,23 @@ export class AguaceroCore extends EventEmitter {
     }
 
     /**
-     * Keep `nexradTilt` on an angle returned by {@link getAvailableNexradTilts} (matches aguacero-frontend elevation buttons).
+     * Keep `nexradTilt` on a coalesced elevation (same rules as aguacero-frontend tilt controls).
      */
     async _snapNexradTiltToAvailableOptions() {
         const s = this.state;
         if (!s.isNexrad || !s.nexradSite) return;
-        const tilts = getAvailableNexradTilts(
+        const raw = getRawNexradTiltsForCoalesce(
             s.nexradSite,
             s.nexradDataSource || 'level2',
             s.nexradProduct || 'REF',
         );
-        if (!tilts.length) return;
+        if (!raw.length) return;
         const t = s.nexradTilt;
-        const match = (a, b) => Math.abs(Number(a) - Number(b)) < 1e-4;
-        if (t != null && tilts.some((x) => match(x, t))) return;
         const target = t != null && Number.isFinite(Number(t)) ? Number(t) : getDefaultRadarTilt(s.nexradSite);
-        let best = tilts[0];
-        for (const x of tilts) {
-            if (Math.abs(x - target) < Math.abs(best - target)) best = x;
-        }
-        await this.setState({ nexradTilt: best });
+        const canonical = nexradLayerTiltToDisplayOption(target, raw);
+        const match = (a, b) => Math.abs(Number(a) - Number(b)) < 1e-4;
+        if (match(s.nexradTilt, canonical)) return;
+        await this.setState({ nexradTilt: canonical });
     }
 
     async refreshNexradTimes() {
@@ -972,6 +1043,18 @@ export class AguaceroCore extends EventEmitter {
                 listWindowHours: listingHours,
             };
         }
+        const filtered = this._getFilteredNexradTimestampsForVariable(out.unixTimes || []);
+        const map = out.timeToKeyMap || {};
+        if (filtered.length > 0) {
+            const cur = this.state.nexradTimestamp != null ? Number(this.state.nexradTimestamp) : null;
+            const hasKey = cur != null && Object.prototype.hasOwnProperty.call(map, String(cur));
+            const inWindow = cur != null && filtered.includes(cur);
+            if (cur == null || !inWindow || !hasKey) {
+                this.state.nexradTimestamp = filtered[filtered.length - 1];
+            }
+        } else if (this.state.nexradTimestamp != null) {
+            this.state.nexradTimestamp = null;
+        }
         this._emitStateChange();
     }
 
@@ -995,48 +1078,7 @@ 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 fld = nexradColormapFldKey(ds, p);
-        const nexradStormRelative = this._nexradStormRelativeFor(ds, p);
-        await this.setState({ nexradProduct: p, variable: fld, nexradStormRelative });
-        await this.refreshNexradTimes();
-        const filtered = this._getFilteredNexradTimestampsForVariable(
-            this.nexradTimesByStation[this._nexradTimesCacheKey()]?.unixTimes || [],
-        );
-        if (filtered.length > 0) {
-            await this.setState({ nexradTimestamp: filtered[filtered.length - 1] });
-        }
-    }
-
-    async setNexradDataSource(source) {
-        if (!this.state.isNexrad) return;
-        const ds = source === 'level3' ? 'level3' : 'level2';
-        const p = (this.state.nexradProduct || 'REF').toUpperCase();
-        const fld = nexradColormapFldKey(ds, p);
-        const nexradStormRelative = this._nexradStormRelativeFor(ds, p);
-        await this.setState({ nexradDataSource: ds, variable: fld, nexradStormRelative });
-        await this.refreshNexradTimes();
-        const filtered = this._getFilteredNexradTimestampsForVariable(
-            this.nexradTimesByStation[this._nexradTimesCacheKey()]?.unixTimes || [],
-        );
-        if (filtered.length > 0) {
-            await this.setState({ nexradTimestamp: filtered[filtered.length - 1] });
-        }
-    }
-
-    /**
-     * 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.
-     * @param {'level2'|'level3'} dataSource
-     * @param {string} product - Level-II variable (REF, VEL, …) or Level-III radar key (N0H, HHC, …)
-     */
-    async setNexradProductMode(dataSource, product) {
-        if (!this.state.isNexrad) return;
-        const ds = dataSource === 'level3' ? 'level3' : 'level2';
-        const p = (product || 'REF').toUpperCase();
-        const fld = nexradColormapFldKey(ds, p);
-        const nexradStormRelative = this._nexradStormRelativeFor(ds, p);
-        await this.setState({ nexradDataSource: ds, nexradProduct: p, variable: fld, nexradStormRelative });
+        await this.setState({ nexradProduct: p });
         await this.refreshNexradTimes();
         const filtered = this._getFilteredNexradTimestampsForVariable(
             this.nexradTimesByStation[this._nexradTimesCacheKey()]?.unixTimes || [],

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.
@@ -35,4 +39,5 @@ export {
 
 /** NEXRAD tilt + listing helpers (also importable via subpaths; root re-export fixes Vite/esbuild subpath resolution). */
 export * from './nexradTilts.js';
+export * from './nexradTiltCoalesce.js';
 export * from './nexrad_support.js';

package/src/nexradTiltCoalesce.js

@@ -0,0 +1,95 @@
+/**
+ * NEXRAD tilt coalescing (matches aguacero-frontend `nexradTiltCoalesce.ts`).
+ * Adjacent manifest tilts within {@link NEXRAD_TILT_COALESCE_MAX_GAP}° are merged for UI/listings:
+ * pairs → higher tilt; runs of three or more consecutive steps merge the first two into the lower tilt.
+ */
+
+/** Adjacent tilts (sorted) within this gap share one listing / control. */
+export const NEXRAD_TILT_COALESCE_MAX_GAP = 0.1;
+
+/**
+ * @param {number[]} segment
+ * @param {Map<number, number>} map
+ */
+function mergeCoalesceSegment(segment, map) {
+    if (segment.length === 0) return;
+    if (segment.length === 1) {
+        map.set(segment[0], segment[0]);
+        return;
+    }
+    if (segment.length === 2) {
+        const canonical = Math.max(segment[0], segment[1]);
+        map.set(segment[0], canonical);
+        map.set(segment[1], canonical);
+        return;
+    }
+    const low = segment[0];
+    map.set(segment[0], low);
+    map.set(segment[1], low);
+    mergeCoalesceSegment(segment.slice(2), map);
+}
+
+/**
+ * @param {number[]} sortedUnique
+ * @returns {Map<number, number>}
+ */
+export function chainCoalesceToCanonical(sortedUnique) {
+    const map = new Map();
+    let i = 0;
+    while (i < sortedUnique.length) {
+        let j = i + 1;
+        while (
+            j < sortedUnique.length &&
+            sortedUnique[j] - sortedUnique[j - 1] <= NEXRAD_TILT_COALESCE_MAX_GAP + 1e-9
+        ) {
+            j++;
+        }
+        const segment = sortedUnique.slice(i, j);
+        mergeCoalesceSegment(segment, map);
+        i = j;
+    }
+    return map;
+}
+
+/**
+ * Manifest tilt list with adjacent options merged (pairs → higher; triple+ splits per merge rules).
+ * @param {number[]} tilts
+ * @returns {number[]}
+ */
+export function coalesceNexradTiltOptionsForDisplay(tilts) {
+    const sorted = [...new Set(tilts)]
+        .filter((t) => Number.isFinite(t))
+        .sort((a, b) => a - b);
+    if (sorted.length <= 1) return sorted;
+    const tiltToCanonical = chainCoalesceToCanonical(sorted);
+    const reps = [];
+    let prevRep;
+    for (const t of sorted) {
+        const c = tiltToCanonical.get(t);
+        if (c === undefined) continue;
+        if (c !== prevRep) {
+            reps.push(c);
+            prevRep = c;
+        }
+    }
+    return reps;
+}
+
+/**
+ * Map stored/clamped tilt to the coalesced elevation value (same rules as {@link coalesceNexradTiltOptionsForDisplay}).
+ * @param {number} layerTilt
+ * @param {number[]} manifestTilts raw manifest tilts (before coalescing)
+ * @returns {number}
+ */
+export function nexradLayerTiltToDisplayOption(layerTilt, manifestTilts) {
+    const sorted = [...new Set(manifestTilts)]
+        .filter((t) => Number.isFinite(t))
+        .sort((a, b) => a - b);
+    if (sorted.length === 0) return layerTilt;
+    const tiltToCanonical = chainCoalesceToCanonical(sorted);
+    if (tiltToCanonical.has(layerTilt)) return tiltToCanonical.get(layerTilt);
+    const nearest = sorted.reduce((best, x) =>
+        Math.abs(x - layerTilt) < Math.abs(best - layerTilt) ? x : best,
+    sorted[0]);
+    return tiltToCanonical.get(nearest) ?? layerTilt;
+}

package/src/nexrad_support.js

@@ -8,12 +8,24 @@ import {
     getDefaultRadarTilt,
     getRadarTilts,
 } from './nexradTilts.js';
+import { coalesceNexradTiltOptionsForDisplay } from './nexradTiltCoalesce.js';
 import {
     NEXRAD_LEVEL3_ELEV,
     NEXRAD_LEVEL3_MOTION_PRODUCT,
     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 derives this from the product key only (not user-configurable).
+ * @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();
@@ -252,13 +264,15 @@ export async function fetchNexradTimesListing(opts) {
 const L3_TILT_INDEX_MANIFEST_SLOTS = 6;
 
 /**
- * Tilt angles for the UI (manifest-driven L2 list; Level III KDP/N0H use the first slots like aguacero-frontend).
+ * Raw manifest tilt list before coalescing (same rules as aguacero-frontend `radarTiltOptionsRaw`).
+ * Use {@link coalesceNexradTiltOptionsForDisplay} or {@link getAvailableNexradTilts} for UI controls.
+ *
  * @param {string} siteId
  * @param {'level2'|'level3'} nexradDataSource
  * @param {string} [nexradProduct]
  * @returns {number[]}
  */
-export function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
+export function getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct) {
     if (!siteId) return [];
     const v = (nexradProduct || 'REF').toUpperCase();
     const ds = nexradDataSource === 'level3' ? 'level3' : 'level2';
@@ -274,3 +288,18 @@ export function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct)
     }
     return [];
 }
+
+/**
+ * Tilt angles for the UI: manifest tilts with adjacent 0.1° steps merged like aguacero-frontend
+ * ({@link coalesceNexradTiltOptionsForDisplay}).
+ *
+ * @param {string} siteId
+ * @param {'level2'|'level3'} nexradDataSource
+ * @param {string} [nexradProduct]
+ * @returns {number[]}
+ */
+export function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
+    const raw = getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct);
+    if (!raw.length) return [];
+    return coalesceNexradTiltOptionsForDisplay(raw);
+}

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)))}`;