@aguacerowx/mapsgl 0.0.31 → 0.0.41

package/src/WeatherLayerManager.js

@@ -1,7 +1,12 @@
 // index.js - The main entry point for the @aguacerowx/web SDK
 
-import { AguaceroCore, EventEmitter, DICTIONARIES } from '@aguacerowx/javascript-sdk';
+import { AguaceroCore, EventEmitter, DICTIONARIES, resolveSatelliteS3FileName } from '@aguacerowx/javascript-sdk';
 import { GridRenderLayer } from './GridRenderLayer.js'; // <-- IMPORT THE WEB RENDERER!
+import { SatelliteShaderManager } from './SatelliteShaderManager.js';
+import { NexradWeatherController } from './NexradWeatherController.js';
+import { NexradSitesOverlay } from './NexradSitesOverlay.js';
+import { NwsWatchesWarningsOverlay } from './NwsWatchesWarningsOverlay.js';
+import WorkerPool from './WorkerPool.js';
 
 function findLatestModelRun(modelsData, modelName) {
     const model = modelsData?.[modelName];
@@ -20,28 +25,93 @@ function findLatestModelRun(modelsData, modelName) {
  * The WeatherLayerManager is the main class for the Aguacero Web SDK.
  * It acts as a "controller" that connects the headless AguaceroCore engine
  * to a visual Mapbox GL JS map instance.
+ *
+ * @param {import('mapbox-gl').Map} map
+ * @param {object} [options]
+ * @param {string} [options.layerId] - Mapbox **custom layer** id for model/MRMS grid (default: random `weather-layer-*`). Alias of `id`.
+ * @param {string} [options.id] - Same as `layerId` if `layerId` is omitted.
+ * @param {string} [options.belowID] - Style layer id to insert Aguacero weather layers **below** (default `AML_-_terrain` when present). Alias of `weatherBeforeLayerId`.
+ * @param {string} [options.weatherBeforeLayerId] - Same as `belowID`.
+ * @param {string} [options.nexradLayerId] - Override Mapbox id for the NEXRAD custom layer (default: derived from `layerId`).
  */
 export class WeatherLayerManager extends EventEmitter {
     constructor(map, options = {}) {
         super();
         if (!map) throw new Error('A Mapbox GL map instance is required.');
         this.map = map;
-        this.layerId = options.id || `weather-layer-${Math.random().toString(36).substr(2, 9)}`;
+        this.layerId =
+            options.layerId ||
+            options.id ||
+            `weather-layer-${Math.random().toString(36).substr(2, 9)}`;
+        /** Mapbox id for the NEXRAD custom layer (derived from `layerId` unless `nexradLayerId` is set). */
+        this._nexradLayerId =
+            options.nexradLayerId ||
+            (this.layerId.includes('weather-layer')
+                ? this.layerId.replace('weather-layer', 'nexrad-layer')
+                : `${this.layerId}-nexrad`);
         this.shaderLayer = null;
         this.currentLoadedTimeKey = null;
-        this.latestDataRequestToken = 0;
-
         this.autoRefreshEnabled = options.autoRefresh ?? false;
         this.autoRefreshIntervalSeconds = options.autoRefreshInterval ?? 60; // Default to 30 seconds
         this.autoRefreshIntervalId = null;
         this.currentRunKey = null;
         this.currentRebuildId = 0;
+        /** True while awaiting the first _loadGridData for the current shader layer rebuild */
+        this._initialGridLoadPending = false;
+        /** Timestep (forecast hour or MRMS ts) that the in-flight rebuild is fetching */
+        this._rebuildTargetTimeKey = null;
+
+        this.satelliteLayerId = options.satelliteLayerId || 'aguacero-satellite-layer';
+        this.basisBaseUrl = options.basisBaseUrl || '/basis/';
+        this.satelliteLayer = null;
+        this.satelliteWorkerPool = null;
+        this._satelliteRunKey = null;
+        /** Prevents duplicate background fetches for the same satellite timeline (MRMS-style preload). */
+        this._satellitePreloadedTimelineId = null;
+        /** Tracks MRMS timeline window so expanding hours triggers background preload of new frames. */
+        this._prevMrmsDurationValue = undefined;
+
+        /** Optional satellite colormap overrides (flat `[norm, '#hex', ...]` arrays, norm 0–100). */
+        this._satelliteColormap = options.satelliteColormap ?? null;
+        this._satelliteColormapIR = options.satelliteColormapIR ?? null;
+        this._satelliteColormapWV = options.satelliteColormapWV ?? null;
+        this._interpolateSatelliteColormap = options.interpolateSatelliteColormap !== false;
+
+        this._nexradController = null;
+        this._nexradSites = null;
+        this._nexradSitesBound = false;
+        /** Override URL for the NEXRAD site list (default: `/data/nexrad.json` — serve from app `public/data/`). */
+        this._nexradSitesUrl = options.nexradSitesUrl ?? null;
+
+        /** Latest payload from {@link AguaceroCore} `state:change` (includes `colormap` for NEXRAD readouts). */
+        this._lastEmittedState = null;
+
+        /**
+         * Optional NWS watches/warnings overlay (all alert types by default; optional user allowlist).
+         * See {@link configureWatchesWarnings}; not a separate “data mode” — overlays satellite / MRMS / NEXRAD only.
+         */
+        this._watchesWarningsOptions = {
+            alertInteractionEnabled: true,
+            ...(options.watchesWarnings ?? {}),
+        };
+        this._nwsOverlay = null;
+
+        /**
+         * Style layer id to insert custom weather layers below when using a non-Aguacero Mapbox style
+         * (set via {@link MapManager}, or pass `belowID` / `weatherBeforeLayerId` here).
+         */
+        this._weatherBeforeLayerId =
+            options.belowID ??
+            options.weatherBeforeLayerId ??
+            (map && map.__aguaceroMapsgl && map.__aguaceroMapsgl.weatherBeforeLayerId) ??
+            null;
 
         // 1. CREATE an instance of the core engine
         this.core = new AguaceroCore(options);
 
         // 2. LISTEN for events from the core engine
         this.core.on('state:change', (newState) => {
+            this._lastEmittedState = newState;
             // When the core's state changes, this controller's job
             // is to update the visual map layers accordingly.
             this._handleStateChange(newState);
@@ -58,6 +128,45 @@ export class WeatherLayerManager extends EventEmitter {
         this.map.on('mousemove', this._handleMouseMove);
     }
 
+    /**
+     * Resolves which style layer id to pass as Mapbox `addLayer(..., beforeId)` for satellite / grid / NEXRAD.
+     * Prefers an explicit id (custom styles), then the default Aguacero `AML_-_terrain` anchor when present.
+     * @returns {string | undefined}
+     */
+    _weatherInsertBeforeId() {
+        const tryId = (id) => {
+            if (!id || typeof id !== 'string') {
+                return undefined;
+            }
+            try {
+                return this.map.getLayer(id) ? id : undefined;
+            } catch {
+                return undefined;
+            }
+        };
+        return tryId(this._weatherBeforeLayerId) || tryId('AML_-_terrain') || undefined;
+    }
+
+    /**
+     * Lng/lat under the cursor — prefer `map.unproject(e.point)` (aguacero-frontend parity) so readouts
+     * align with custom layers / Web Mercator.
+     * @param {import('mapbox-gl').MapMouseEvent | { lngLat: { lng: number; lat: number }; point: import('mapbox-gl').Point }} e
+     * @returns {{ lng: number; lat: number }}
+     */
+    _mouseLngLatFromEvent(e) {
+        try {
+            if (this.map && typeof this.map.unproject === 'function') {
+                const u = this.map.unproject(e.point);
+                if (Number.isFinite(u.lng) && Number.isFinite(u.lat)) {
+                    return { lng: u.lng, lat: u.lat };
+                }
+            }
+        } catch {
+            /* style or map not ready */
+        }
+        return { lng: e.lngLat.lng, lat: e.lngLat.lat };
+    }
+
     /**
      * The main visual controller. It receives the new state from the core
      * and decides what visual update is needed.
@@ -65,23 +174,461 @@ export class WeatherLayerManager extends EventEmitter {
      * @private
      */
     _handleStateChange(state) {
-        const timeKey = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
-        const runKey = `${state.model}-${state.date}-${state.run}-${state.variable}`;
-        const existingRunKey = this.shaderLayer?.runKey ?? 'none';
-
-        if (!this.shaderLayer || this.shaderLayer.runKey !== runKey) {
-            //console.log(`[WLM._handleStateChange] → dispatching _rebuildLayerAndPreload (runKey changed: "${existingRunKey}" → "${runKey}")`);
-            this._rebuildLayerAndPreload(state);
-        } else if (this.currentLoadedTimeKey !== timeKey) {
-            //console.log(`[WLM._handleStateChange] → dispatching _updateLayerData (timeKey changed: ${this.currentLoadedTimeKey} → ${timeKey})`);
-            this._updateLayerData(state);
-        } else {
-            //console.log(`[WLM._handleStateChange] → style/opacity update only`);
+        /** NEXRAD setup is async (`sites.show`, frame fetch). `finally` would run before the radar layer exists, so NWS fill stacks above terrain instead of under the custom layer — defer sync until the handler settles. */
+        let deferNwsSyncUntilNexradReady = false;
+        try {
+            if (state.isSatellite) {
+                this._handleSatelliteStateChange(state);
+                return;
+            }
+
+            this._tearDownSatellite();
+
+            if (state.isNexrad) {
+                this._tearDownShaderGrid();
+                deferNwsSyncUntilNexradReady = true;
+                void this._handleNexradStateChange(state).finally(() => {
+                    const st = this._lastEmittedState ?? state;
+                    this._syncNwsOverlay(st);
+                });
+                return;
+            }
+
+            this._tearDownNexrad();
+
+            const prevMrmsDur = this._prevMrmsDurationValue;
+            this._prevMrmsDurationValue = state.mrmsDurationValue;
+            const mrmsDurationChanged =
+                state.isMRMS && prevMrmsDur !== undefined && prevMrmsDur !== state.mrmsDurationValue;
+
+            const timeKey = state.isMRMS
+                ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
+                : Number(state.forecastHour);
+            const runKey = `${state.model}-${state.date}-${state.run}-${state.variable}`;
+
+            if (!this.shaderLayer || this.shaderLayer.runKey !== runKey) {
+                this._rebuildLayerAndPreload(state);
+            } else if (this.currentLoadedTimeKey !== timeKey) {
+                const duplicateBeforeFirstPaint =
+                    this.currentLoadedTimeKey === null &&
+                    this._initialGridLoadPending &&
+                    timeKey === this._rebuildTargetTimeKey;
+                if (!duplicateBeforeFirstPaint) {
+                    this._updateLayerData(state);
+                }
+            }
+
+            if (this.shaderLayer) {
+                this.shaderLayer.updateStyle({ opacity: state.opacity });
+                this.shaderLayer.setSmoothing(!state.shaderSmoothingEnabled);
+                this.map.triggerRepaint();
+            }
+
+            if (state.isMRMS && this.shaderLayer && mrmsDurationChanged) {
+                this._preloadAllTimeSteps(state);
+            }
+        } finally {
+            if (!deferNwsSyncUntilNexradReady) {
+                this._syncNwsOverlay(state);
+            }
         }
+    }
 
+    /**
+     * NWS watches/warnings: same NWWS feed as aguacero-frontend, overlaid on satellite / MRMS / NEXRAD only
+     * (hidden on model grids). By default `nwsAlertSettings.alertScope` is `'all'`. Use `'user'` with
+     * `includedAlerts` (exact NWS `event_name` strings) to show only selected products.
+     *
+     * @param {object} partial
+     * @param {boolean} [partial.enabled] - Master switch; default false.
+     * @param {string} [partial.alertsBaseUrl] - API root (default `https://api.aguacerowx.com`).
+     * @param {boolean} [partial.alertInteractionEnabled=true] - When true, map fires `nws:alert:click` with alert details.
+     * @param {boolean} [partial.activeOnlyRealtime=false] - Match frontend “active only (realtime)” time filter.
+     * @param {object} [partial.nwsAlertSettings]
+     * @param {Record<string, string>} [partial.nwsAlertSettings.colors] - Fill color (`#rrggbb`) per `event_name` (same names as NWS / API).
+     * @param {Record<string, boolean>} [partial.nwsAlertSettings.fillHidden] - `true` = no fill for that product.
+     * @param {Record<string, boolean>} [partial.nwsAlertSettings.lineHidden] - `true` = no outline for that product.
+     * @param {Record<string, number>} [partial.nwsAlertSettings.fillOpacity] - 0–1 fill opacity multiplier per product (when fill is shown).
+     * @param {Record<string, object>} [partial.nwsAlertSettings.lineStyles] - Per-product line overrides (`innerColor`, `outerColor`, widths, `lineDash`, …).
+     * @param {string} [partial.nwsAlertSettings.lineDash] - Default dash style when a product has no `lineStyles` entry.
+     * @param {'all'|'user'} [partial.nwsAlertSettings.alertScope] - `all` (default): every alert with a resolved name. `user`: only `includedAlerts`.
+     * @param {string[]} [partial.nwsAlertSettings.includedAlerts] - When `alertScope` is `'user'`, list of exact NWS `event_name` values to render (optional colors per name in `colors`).
+     * @param {string} [partial.lineBeforeLayerId] - Mapbox style layer id to insert NWS **lines** below (default `AML_-_states`). Override if your style uses different ids.
+     * @param {string | null} [partial.fillBeforeLayerId] - Optional manual override: layer id NWS **fill** is inserted under. When omitted, placement uses the active weather layer and `AML_-_states` so fill stays under whichever is lower in the style.
+     */
+    configureWatchesWarnings(partial) {
+        this._watchesWarningsOptions = { ...this._watchesWarningsOptions, ...partial };
+        const st = this._lastEmittedState ?? this.core?.state;
+        if (st) {
+            this._syncNwsOverlay(st);
+        }
+    }
+
+    _syncNwsOverlay(state) {
+        const wopt = this._watchesWarningsOptions ?? {};
+        const masterEnabled = wopt.enabled === true;
+        const isModelMode = !state.isSatellite && !state.isNexrad && !state.isMRMS;
+        const enabled = masterEnabled && !isModelMode;
+
+        let timelineUnix = null;
+        if (state.isSatellite) {
+            timelineUnix = state.satelliteTimestamp == null ? null : Number(state.satelliteTimestamp);
+        } else if (state.isNexrad) {
+            timelineUnix = state.nexradTimestamp == null ? null : Number(state.nexradTimestamp);
+        } else if (state.isMRMS) {
+            timelineUnix = state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp);
+        }
+
+        if (!this._nwsOverlay) {
+            this._nwsOverlay = new NwsWatchesWarningsOverlay(this.map, {
+                ...wopt,
+                enabled: false,
+            });
+        }
+
+        const weatherLayerId = this._resolveNwsFillBeforeLayerId(state);
+        const fillBeforeLayerId = Object.prototype.hasOwnProperty.call(wopt, 'fillBeforeLayerId')
+            ? wopt.fillBeforeLayerId ?? null
+            : null;
+
+        this._nwsOverlay.updateOptions({
+            alertsBaseUrl: wopt.alertsBaseUrl,
+            alertInteractionEnabled: wopt.alertInteractionEnabled,
+            deltaDebounceMs: wopt.deltaDebounceMs,
+            fillOpacity: wopt.fillOpacity,
+            lineOpacity: wopt.lineOpacity,
+            lineWidth: wopt.lineWidth,
+            weatherLayerId,
+            fillBeforeLayerId,
+            lineBeforeLayerId: wopt.lineBeforeLayerId,
+            nwsAlertSettings: {
+                ...(wopt.nwsAlertSettings ?? {}),
+                ...(wopt.activeOnlyRealtime !== undefined ? { activeOnlyRealtime: wopt.activeOnlyRealtime } : {}),
+            },
+        });
+        this._nwsOverlay.syncWithMode({ enabled, timelineUnix });
+    }
+
+    /**
+     * Layer id for the active satellite / MRMS / NEXRAD custom layer (used with `AML_-_states` for NWS fill stacking).
+     * @param {object} state
+     * @returns {string | null}
+     */
+    _resolveNwsFillBeforeLayerId(state) {
+        try {
+            if (state.isSatellite && this.satelliteLayer?.id && this.map.getLayer(this.satelliteLayer.id)) {
+                return this.satelliteLayer.id;
+            }
+            if (state.isMRMS && this.shaderLayer?.id && this.map.getLayer(this.shaderLayer.id)) {
+                return this.shaderLayer.id;
+            }
+            if (state.isNexrad && this._nexradController?.mapboxLayer?.id && this.map.getLayer(this._nexradController.mapboxLayer.id)) {
+                return this._nexradController.mapboxLayer.id;
+            }
+        } catch {
+            /* map not ready */
+        }
+        return null;
+    }
+
+    _tearDownShaderGrid() {
+        if (!this.shaderLayer) return;
+        if (this.map.getLayer(this.shaderLayer.id)) {
+            this.map.removeLayer(this.shaderLayer.id);
+        }
+        try {
+            this.shaderLayer.onRemove?.();
+        } catch {
+            /* ignore */
+        }
+        this.shaderLayer = null;
+        this.currentLoadedTimeKey = null;
+    }
+
+    _tearDownNexrad() {
+        if (this._nexradController) {
+            this._nexradController.destroy();
+            this._nexradController = null;
+        }
+        if (this._nexradSites) {
+            this._nexradSites.destroy();
+            this._nexradSites = null;
+        }
+        this._nexradSitesBound = false;
+    }
+
+    async _handleNexradStateChange(state) {
+        if (!this._nexradController) {
+            this._nexradController = new NexradWeatherController(this.map, this.core, {
+                nexradLayerId: this._nexradLayerId,
+                interpolateNexradColormap: this.core.state?.shaderSmoothingEnabled !== false,
+                getInsertBeforeLayerId: () => this._weatherInsertBeforeId(),
+            });
+        }
+
+        const showSiteMarkers = state.nexradShowSitesPicker !== false;
+        if (showSiteMarkers) {
+            if (!this._nexradSites) {
+                this._nexradSites = new NexradSitesOverlay(this.map, {
+                    nexradSitesUrl: this._nexradSitesUrl || undefined,
+                });
+            }
+            await this._nexradSites.show();
+            if (!this._nexradSitesBound) {
+                this._nexradSites.bindClick((siteId) => {
+                    void this.core.setNexradSite(siteId);
+                });
+                this._nexradSitesBound = true;
+            }
+        } else if (this._nexradSites) {
+            this._nexradSites.destroy();
+            this._nexradSites = null;
+            this._nexradSitesBound = false;
+        }
+
+        this._nexradController.preloadAllAvailable(state);
+        await this._nexradController.sync(state);
+    }
+
+    _tearDownSatellite() {
+        if (!this.satelliteLayer) return;
+        if (this.map.getLayer(this.satelliteLayer.id)) {
+            this.map.removeLayer(this.satelliteLayer.id);
+        }
+        try {
+            this.satelliteLayer.onRemove?.();
+        } catch {
+            /* ignore */
+        }
+        this.satelliteLayer = null;
+        if (this.satelliteWorkerPool) {
+            this.satelliteWorkerPool.terminate();
+            this.satelliteWorkerPool = null;
+        }
+        this._satelliteRunKey = null;
+        this._satellitePreloadedTimelineId = null;
+    }
+
+    _handleSatelliteStateChange(state) {
+        this._tearDownNexrad();
         if (this.shaderLayer) {
-            this.shaderLayer.updateStyle({ opacity: state.opacity });
-            this.shaderLayer.setSmoothing(!state.shaderSmoothingEnabled);
+            if (this.map.getLayer(this.shaderLayer.id)) {
+                this.map.removeLayer(this.shaderLayer.id);
+            }
+            try {
+                this.shaderLayer.onRemove?.();
+            } catch {
+                /* ignore */
+            }
+            this.shaderLayer = null;
+            this.currentLoadedTimeKey = null;
+        }
+
+        if (!state.satelliteKey || state.satelliteTimestamp == null) {
+            this._tearDownSatellite();
+            this.map.triggerRepaint();
+            return;
+        }
+
+        const satRunKey = `${state.satelliteKey}|${state.variable || ''}`;
+        if (!this.satelliteLayer || this._satelliteRunKey !== satRunKey) {
+            this._rebuildSatelliteLayer(state, satRunKey);
+        }
+
+        // Preload the full timeline before syncing the visible frame. Slider / timestamp changes must never
+        // trigger fetches — only this preload pass (and listing refresh) may load KTX2 data.
+        if (this.satelliteLayer && state.satelliteTimeToFileMap) {
+            this._preloadAllSatelliteFrames(state);
+        }
+        this._syncSatelliteFrame(state);
+
+        if (this.satelliteLayer) {
+            this.satelliteLayer.updateLayerSettings(this._buildSatelliteLayerSettings(state));
+            this.map.triggerRepaint();
+        }
+    }
+
+    /**
+     * Merge core satellite state with optional colormap overrides for `SatelliteShaderManager`.
+     * @param {object} state - Core state snapshot
+     */
+    _buildSatelliteLayerSettings(state) {
+        return {
+            satelliteOpacity: state.opacity ?? 1,
+            satelliteVisibility: state.visible !== false,
+            fillSmoothing: state.shaderSmoothingEnabled ? 1 : 0,
+            interpolateColormap: this._interpolateSatelliteColormap,
+            satelliteColormap: this._satelliteColormap ?? undefined,
+            satelliteColormapIR: this._satelliteColormapIR ?? undefined,
+            satelliteColormapWV: this._satelliteColormapWV ?? undefined,
+        };
+    }
+
+    /**
+     * Set custom IR / WV / legacy colormap stops for the satellite layer. Pass `null` to clear an override.
+     * Stops are alternating `[norm0to100, '#rrggbb', ...]` (same encoding as aguacero-frontend satellite colormaps).
+     *
+     * @param {object} opts
+     * @param {number[]|string[]|null} [opts.colormap] - Single list; interpreted using the active frame (IR vs WV).
+     * @param {number[]|string[]|null} [opts.colormapIR] - Longwave IR bands (C13–C16).
+     * @param {number[]|string[]|null} [opts.colormapWV] - Water vapor bands (C08–C10).
+     * @param {boolean} [opts.interpolate=true] - Interpolate between stops when building the 1D LUT texture.
+     */
+    setSatelliteColormapOverrides(opts = {}) {
+        if (opts.colormap !== undefined) {
+            this._satelliteColormap = opts.colormap;
+        }
+        if (opts.colormapIR !== undefined) {
+            this._satelliteColormapIR = opts.colormapIR;
+        }
+        if (opts.colormapWV !== undefined) {
+            this._satelliteColormapWV = opts.colormapWV;
+        }
+        if (opts.interpolate !== undefined) {
+            this._interpolateSatelliteColormap = opts.interpolate;
+        }
+
+        if (this.satelliteLayer && this.core?.state?.isSatellite) {
+            this.satelliteLayer.updateLayerSettings(this._buildSatelliteLayerSettings(this.core.state));
+            this.map.triggerRepaint();
+        }
+    }
+
+    _rebuildSatelliteLayer(state, satRunKey) {
+        this._tearDownSatellite();
+
+        // Vite only rewrites workers when it sees `new Worker(new URL(..., import.meta.url))` here — not
+        // `super(url)` inside a Worker subclass (that leaves a file: URL and triggers fs allow-list errors).
+        this.satelliteWorkerPool = new WorkerPool(
+            () => new Worker(new URL('./satelliteKtxWorker.js', import.meta.url)),
+            Math.min(4, Math.max(2, Math.floor((typeof navigator !== 'undefined' && navigator.hardwareConcurrency) ? navigator.hardwareConcurrency * 0.5 : 2)))
+        );
+
+        this.satelliteLayer = new SatelliteShaderManager(
+            this.satelliteWorkerPool,
+            () => {},
+            { basisBaseUrl: this.basisBaseUrl }
+        );
+        this.satelliteLayer.id = this.satelliteLayerId;
+        this._satelliteRunKey = satRunKey;
+
+        const beforeId = this._weatherInsertBeforeId();
+        if (beforeId) {
+            this.map.addLayer(this.satelliteLayer, beforeId);
+        } else {
+            this.map.addLayer(this.satelliteLayer);
+        }
+    }
+
+    _satelliteTimelineId(state) {
+        const keys = Object.keys(state.satelliteTimeToFileMap || {}).sort((a, b) => Number(a) - Number(b));
+        return `${state.satelliteKey}|${state.variable || ''}|${keys.join(',')}`;
+    }
+
+    _getSatelliteFetchParts(state, satelliteTimestamp) {
+        const fileName = resolveSatelliteS3FileName(
+            state.satelliteKey,
+            state.satelliteTimeToFileMap,
+            satelliteTimestamp
+        );
+        if (!fileName) {
+            return null;
+        }
+        const parts = state.satelliteKey.split('.');
+        const channelName = parts[2] || state.variable;
+        const channelNameUpper = String(channelName).toUpperCase();
+        let s3FileName = fileName.replace('MULTI', channelNameUpper);
+        if (!s3FileName.endsWith('.ktx2')) {
+            s3FileName += '.ktx2';
+        }
+        let shaderFileName = s3FileName;
+        if (!channelNameUpper.startsWith('C') || channelNameUpper.length > 3) {
+            const token = channelNameUpper.toLowerCase().replace(/_/g, '');
+            shaderFileName = `${s3FileName}_${token}_`;
+        }
+        const apiKey = this.core.apiKey;
+        if (!apiKey) {
+            return null;
+        }
+        const uid = this.core.userId || 'sdk-user';
+        const url = `https://d3dc62msmxkrd7.cloudfront.net/satellite/${s3FileName}?userId=${encodeURIComponent(uid)}&apiKey=${encodeURIComponent(apiKey)}`;
+        return { url, shaderFileName, frameKey: Number(satelliteTimestamp), apiKey };
+    }
+
+    _preloadAllSatelliteFrames(state) {
+        if (!this.satelliteLayer || !state.satelliteTimeToFileMap) {
+            return;
+        }
+        const timelineId = this._satelliteTimelineId(state);
+        if (this._satellitePreloadedTimelineId === timelineId) {
+            return;
+        }
+        this._satellitePreloadedTimelineId = timelineId;
+
+        const runKey = this._satelliteRunKey;
+        const timestamps = Object.keys(state.satelliteTimeToFileMap)
+            .map((k) => Number(k))
+            .filter((t) => !Number.isNaN(t));
+
+        timestamps.forEach((ts) => {
+            if (!this.satelliteLayer || this._satelliteRunKey !== runKey) {
+                return;
+            }
+            if (this.satelliteLayer.frames.has(ts)) {
+                return;
+            }
+            void this._fetchSatelliteFrameAt(state, ts, runKey);
+        });
+    }
+
+    async _fetchSatelliteFrameAt(state, satelliteTimestamp, runKey) {
+        const parts = this._getSatelliteFetchParts(state, satelliteTimestamp);
+        if (!parts || !this.satelliteLayer) {
+            return;
+        }
+        const { url, shaderFileName, frameKey, apiKey } = parts;
+
+        if (this.satelliteLayer.frames.has(frameKey)) {
+            return;
+        }
+
+        try {
+            const response = await fetch(url, { headers: { 'x-api-key': apiKey } });
+            if (!response.ok) {
+                throw new Error(`${response.status} ${response.statusText}`);
+            }
+            const buffer = await response.arrayBuffer();
+            if (!this.satelliteLayer || this._satelliteRunKey !== runKey) {
+                return;
+            }
+            this.satelliteLayer.addFrame(new Uint8Array(buffer), frameKey, shaderFileName);
+            this.map.triggerRepaint();
+        } catch (err) {
+            console.warn('[WeatherLayerManager] Satellite frame fetch failed:', err);
+        }
+    }
+
+    /**
+     * Selects which decoded frame to show. Never performs network I/O — preloading owns all fetches.
+     * If the frame is not decoded yet, SatelliteShaderManager keeps targetFrameKey until addFrame runs.
+     */
+    _syncSatelliteFrame(state) {
+        if (!this.satelliteLayer) {
+            return;
+        }
+        if (!this.core.apiKey) {
+            console.warn('[WeatherLayerManager] apiKey is required to load satellite KTX2 tiles.');
+            return;
+        }
+
+        const parts = this._getSatelliteFetchParts(state, state.satelliteTimestamp);
+        if (!parts) {
+            return;
+        }
+        const { frameKey } = parts;
+
+        this.satelliteLayer.setActiveFrame(frameKey);
+        if (this.satelliteLayer.frames.has(frameKey)) {
             this.map.triggerRepaint();
         }
     }
@@ -114,68 +661,75 @@ export class WeatherLayerManager extends EventEmitter {
     async setMRMSTimestamp(timestamp) {
         return this.core.setMRMSTimestamp(timestamp);
     }
+    async setSatelliteTimestamp(timestamp) {
+        return this.core.setSatelliteTimestamp(timestamp);
+    }
+    async setSatelliteDurationValue(value) {
+        return this.core.setSatelliteDurationValue(value);
+    }
+    async setMRMSDurationValue(value) {
+        return this.core.setMRMSDurationValue(value);
+    }
+
+    /** Refreshes NEXRAD object-key listings for the current site / product / tilt (NEXRAD mode only). */
+    async refreshNexradTimes() {
+        return this.core.refreshNexradTimes();
+    }
+    /** @param {string | null} siteId - ICAO id, or null to clear the selected site */
+    async setNexradSite(siteId) {
+        return this.core.setNexradSite(siteId);
+    }
+    async setNexradProduct(product) {
+        return this.core.setNexradProduct(product);
+    }
+    /** @param {'level2'|'level3'} dataSource @param {string} product */
+    async setNexradProductMode(dataSource, product) {
+        return this.core.setNexradProductMode(dataSource, product);
+    }
+    /** @param {'level2'|'level3'} source */
+    async setNexradDataSource(source) {
+        return this.core.setNexradDataSource(source);
+    }
+    async setNexradTilt(tilt) {
+        return this.core.setNexradTilt(tilt);
+    }
+    async setNexradTimestamp(timestamp) {
+        return this.core.setNexradTimestamp(timestamp);
+    }
 
     // --- VISUAL RENDERING LOGIC ---
     // These methods were removed from the core and now live exclusively
     // in this web-specific presentation layer.
 
-    // New internal method — accepts an externally-supplied token so the
-    // rebuild can guarantee its own fetch is never discarded.
-    async _updateLayerDataWithToken(state, requestToken) {
+    /** Swaps to a timestep that was already uploaded by rebuild or `_preloadAllTimeSteps`. */
+    _updateLayerDataWithToken(state) {
         if (!this.shaderLayer || !state.variable) {
-            console.warn(`[WLM._updateLayerDataWithToken] token=${requestToken} — skipping, shaderLayer=${!!this.shaderLayer} variable=${state.variable}`);
             return;
         }
 
-        const timeKey = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
-        //console.log(`[WLM._updateLayerDataWithToken] token=${requestToken} timeKey=${timeKey}`);
-
+        const timeKey = state.isMRMS
+            ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
+            : Number(state.forecastHour);
         if (this.shaderLayer.switchToPreloadedTexture(timeKey)) {
             this.currentLoadedTimeKey = timeKey;
-            //console.log(`[WLM._updateLayerDataWithToken] token=${requestToken} — FAST PATH: preloaded texture found for timeKey=${timeKey}, swapped instantly`);
             this.map.triggerRepaint();
             return;
         }
 
-        //console.log(`[WLM._updateLayerDataWithToken] token=${requestToken} — SLOW PATH: no preloaded texture for timeKey=${timeKey}, fetching...`);
-        const fetchStart = performance.now();
-        try {
-            const grid = await this.core._loadGridData(state);
-            const fetchMs = (performance.now() - fetchStart).toFixed(1);
-
-            if (requestToken !== this.latestDataRequestToken) {
-                //console.log(`[WLM._updateLayerDataWithToken] token=${requestToken} — STALE after fetch (latestToken=${this.latestDataRequestToken}), discarding (${fetchMs}ms)`);
-                return;
-            }
-
-            if (grid && grid.data) {
-                const gridModel = state.isMRMS ? 'mrms' : state.model;
-                const { gridDef } = this.core._getGridCornersAndDef(gridModel);
-                //console.log(`[WLM._updateLayerDataWithToken] token=${requestToken} — grid received in ${fetchMs}ms, storing+switching texture for timeKey=${timeKey}`);
-
-                this.shaderLayer.storePreloadedTexture(
-                    timeKey, grid.data, grid.encoding,
-                    gridDef.grid_params.nx, gridDef.grid_params.ny
-                );
-                this.shaderLayer.switchToPreloadedTexture(timeKey);
-                this.currentLoadedTimeKey = timeKey;
-                this.latestDataRequestToken = this.currentRebuildId;
-                this.map.triggerRepaint();
-            } else {
-                console.error(
-                    `[WLM._updateLayerDataWithToken] token=${requestToken} — grid fetch returned null/empty after ${fetchMs}ms for timeKey=${timeKey}.`,
-                    { model: state.model, variable: state.variable, forecastHour: state.forecastHour, isMRMS: state.isMRMS },
-                    '← THIS IS WHY THE MAP IS BLANK'
-                );
-            }
-        } catch (error) {
-            if (requestToken === this.latestDataRequestToken) {
-                console.error(`[WLM._updateLayerDataWithToken] token=${requestToken} — fetch threw for timeKey=${timeKey}:`, error);
-            }
-        }
+        // No GPU cache for this timestep (preload still in flight, or it failed e.g. 502). Never fetch
+        // here — scrubbing must not trigger `_loadGridData`; only rebuild + `_preloadAllTimeSteps` may.
+        // When a background preload finishes, `_preloadAllTimeSteps` applies the frame if it matches
+        // the active time.
     }
 
     async _rebuildLayerAndPreload(state) {
+        if (state.isSatellite) {
+            return;
+        }
+        if (!state.variable) {
+            return;
+        }
+
         const rebuildId = ++this.currentRebuildId;
 
         this.core.cancelAllRequests();
@@ -186,20 +740,19 @@ export class WeatherLayerManager extends EventEmitter {
         }
         this.currentLoadedTimeKey = null;
 
-        if (!state.variable) return;
-
         if (
             !state.isMRMS &&
             state.forecastHour === 0 &&
             state.variable === 'ptypeRefl' &&
             state.model === 'hrrr'
         ) {
-            const availableHours =
-                this.core.modelStatus?.[state.model]?.[state.date]?.[state.run] || [];
+            const availableHours = this.core.getAvailableForecastHours();
             const firstValidHour = availableHours.find(h => h !== 0);
             if (firstValidHour !== undefined) {
                 state = { ...state, forecastHour: firstValidHour };
                 this.core.state.forecastHour = firstValidHour;
+            } else {
+                return;
             }
         }
 
@@ -209,12 +762,39 @@ export class WeatherLayerManager extends EventEmitter {
 
         this.shaderLayer = new GridRenderLayer(this.layerId);
         this.shaderLayer.runKey = runKey;
-        this.map.addLayer(this.shaderLayer, 'AML_-_terrain');
+        const beforeId = this._weatherInsertBeforeId();
+        if (beforeId) {
+            this.map.addLayer(this.shaderLayer, beforeId);
+        } else {
+            this.map.addLayer(this.shaderLayer);
+        }
         this._updateLayerStyle(state);
 
-        const grid = await this.core._loadGridData(state);
+        this._rebuildTargetTimeKey = state.isMRMS
+            ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
+            : Number(state.forecastHour);
+        this._initialGridLoadPending = true;
 
-        if (rebuildId !== this.currentRebuildId) return;
+        let grid;
+        try {
+            grid = await this.core._loadGridData(state);
+        } catch (e) {
+            this._initialGridLoadPending = false;
+            throw e;
+        }
+
+        if (rebuildId !== this.currentRebuildId) {
+            this._initialGridLoadPending = false;
+            return;
+        }
+
+        const coreTimeKey = state.isMRMS
+            ? (this.core.state.mrmsTimestamp == null ? null : Number(this.core.state.mrmsTimestamp))
+            : Number(this.core.state.forecastHour);
+        if (coreTimeKey !== this._rebuildTargetTimeKey) {
+            this._initialGridLoadPending = false;
+            return;
+        }
 
         if (grid && grid.data) {
             const gridModel = state.isMRMS ? 'mrms' : state.model;
@@ -225,32 +805,61 @@ export class WeatherLayerManager extends EventEmitter {
                 gridDef.grid_params.nx, gridDef.grid_params.ny
             );
 
-            this.currentLoadedTimeKey = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
-            this.latestDataRequestToken = this.currentRebuildId;
+            this.currentLoadedTimeKey = state.isMRMS
+                ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
+                : Number(state.forecastHour);
+            this.shaderLayer.registerCurrentDataTextureAsPreloaded(this.currentLoadedTimeKey);
             this.map.triggerRepaint();
         }
 
+        this._initialGridLoadPending = false;
+
         if (rebuildId === this.currentRebuildId) {
             this._preloadAllTimeSteps(state);
         }
     }
     
     _preloadAllTimeSteps(state) {
-        const timeSteps = state.isMRMS ? state.availableTimestamps : state.availableHours;
-        if (!timeSteps || timeSteps.length <= 1) {
-            //console.log(`[WLM._preloadAllTimeSteps] skipping — only ${timeSteps?.length ?? 0} time steps available`);
+        let fromCore = [];
+        try {
+            if (!state.isMRMS && typeof this.core.getAvailableForecastHours === 'function') {
+                fromCore = this.core.getAvailableForecastHours();
+            }
+        } catch (err) {
+            // ignore
+        }
+
+        const fromState = state.isMRMS
+            ? (state.availableTimestamps || [])
+            : (state.availableHours || []);
+
+        let timeSteps;
+        if (state.isMRMS) {
+            timeSteps = fromState.length ? fromState : fromCore;
+        } else {
+            timeSteps = fromCore.length > 0 ? fromCore : fromState;
+        }
+
+        const normalized = (timeSteps || [])
+            .map(t => Number(t))
+            .filter(t => !Number.isNaN(t));
+
+        const currentFrameTime = Number(state.isMRMS ? state.mrmsTimestamp : state.forecastHour);
+        const stepsToPreload = normalized.filter(t => t !== currentFrameTime);
+
+        if (normalized.length === 0) {
+            return;
+        }
+
+        if (stepsToPreload.length === 0) {
             return;
         }
 
-        const currentFrameTime = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
-        const stepsToPreload = timeSteps.filter(t => t !== currentFrameTime);
         const capturedRebuildId = this.currentRebuildId;
-        //console.log(`[WLM._preloadAllTimeSteps] preloading ${stepsToPreload.length} frames (skipping currentFrameTime=${currentFrameTime}), capturedRebuildId=${capturedRebuildId}`);
 
         const gridModel = state.isMRMS ? 'mrms' : state.model;
         const { gridDef } = this.core._getGridCornersAndDef(gridModel);
 
-        let completed = 0, failed = 0;
         stepsToPreload.forEach(time => {
             const stateForTime = {
                 ...state,
@@ -259,29 +868,30 @@ export class WeatherLayerManager extends EventEmitter {
 
             this.core._loadGridData(stateForTime)
                 .then(grid => {
-                    if (capturedRebuildId !== this.currentRebuildId) return;
+                    if (capturedRebuildId !== this.currentRebuildId) {
+                        return;
+                    }
                     if (grid?.data && this.shaderLayer) {
                         this.shaderLayer.storePreloadedTexture(
                             time, grid.data, grid.encoding,
                             gridDef.grid_params.nx, gridDef.grid_params.ny
                         );
-                        completed++;
-                        //console.log(`[WLM._preloadAllTimeSteps] stored texture for time=${time} (${completed}/${stepsToPreload.length} done, ${failed} failed)`);
-                    } else if (!grid?.data) {
-                        failed++;
-                        console.warn(`[WLM._preloadAllTimeSteps] null grid for time=${time} — skipping texture store (${completed}/${stepsToPreload.length} done, ${failed} failed)`);
+                        const s = this.core.state;
+                        const activeTime = s.isMRMS
+                            ? (s.mrmsTimestamp == null ? null : Number(s.mrmsTimestamp))
+                            : Number(s.forecastHour);
+                        if (time === activeTime && this.shaderLayer.switchToPreloadedTexture(time)) {
+                            this.currentLoadedTimeKey = time;
+                            this.map.triggerRepaint();
+                        }
                     }
                 })
-                .catch(e => {
-                    failed++;
-                    console.warn(`[WLM._preloadAllTimeSteps] fetch error for time=${time} (${completed}/${stepsToPreload.length} done, ${failed} failed):`, e);
-                });
+                .catch(() => {});
         });
     }
 
-    async _updateLayerData(state) {
-        const requestToken = ++this.latestDataRequestToken;
-        return this._updateLayerDataWithToken(state, requestToken);
+    _updateLayerData(state) {
+        return this._updateLayerDataWithToken(state);
     }
 
     _updateLayerStyle(state) {
@@ -302,11 +912,9 @@ export class WeatherLayerManager extends EventEmitter {
         let dataRange;
         if (state.variable === 'ptypeRefl' || state.variable === 'ptypeRate') {
             if (state.isMRMS) {
-                //console.log('🔧 Using MRMS ptype data range: 5-380');
                 dataRange = [5, 380];
             } else {
-                //console.log('🔧 Using Model ptype data range: 5-380');
-                dataRange = [5, 380]; // Models also use the full colormap range
+                dataRange = [5, 380];
             }
         } else {
             dataRange = [finalColormap[0], finalColormap[finalColormap.length - 2]];
@@ -328,18 +936,35 @@ export class WeatherLayerManager extends EventEmitter {
      * @private
      */
     async _handleMouseMove(e) {
-        // This function's only job is to get the coordinates and call the core's
-        // powerful utility method to do the actual work.
-        const payload = await this.core.getValueAtLngLat(e.lngLat.lng, e.lngLat.lat);
+        const { lng, lat } = this._mouseLngLatFromEvent(e);
+        const state = this._lastEmittedState;
+        if (state?.isNexrad) {
+            if (this._nexradController) {
+                const payload = this._nexradController.getInspectPayload(lng, lat, state);
+                if (payload) {
+                    this.emit('data:inspect', {
+                        ...payload,
+                        point: e.point,
+                    });
+                } else {
+                    this.emit('data:inspect', null);
+                }
+            } else {
+                this.emit('data:inspect', null);
+            }
+            return;
+        }
+
+        // Model / MRMS: delegate to the core grid sampler.
+        const payload = await this.core.getValueAtLngLat(lng, lat);
 
-        // It then re-emits the final payload with the screen point attached.
         if (payload) {
-             this.emit('data:inspect', {
-                 ...payload,
-                 point: e.point, // Add the screen coordinate for the UI
-             });
+            this.emit('data:inspect', {
+                ...payload,
+                point: e.point,
+            });
         } else {
-             this.emit('data:inspect', null);
+            this.emit('data:inspect', null);
         }
     }
 
@@ -377,8 +1002,6 @@ export class WeatherLayerManager extends EventEmitter {
      * @returns {Promise<void>}
      */
     async refreshData() {
-        //console.log('[WeatherLayerManager] Manual data refresh triggered.');
-        // This just calls the internal logic we already built.
         await this._checkForUpdates();
     }
 
@@ -388,7 +1011,58 @@ export class WeatherLayerManager extends EventEmitter {
      * @private
      */
     async _checkForUpdates() {
-        const { isMRMS, model: currentModel, variable: currentVariable, date, run } = this.core.state;
+        const s = this.core.state;
+        const { isMRMS, isSatellite, isNexrad, model: currentModel, variable: currentVariable, date, run } = s;
+
+        if (isSatellite && s.satelliteKey) {
+            const prevTimeline = this.core._computeSatelliteTimeline();
+            const prevTimes = [...(prevTimeline.unixTimes || [])]
+                .map((t) => Number(t))
+                .filter((t) => !Number.isNaN(t))
+                .sort((a, b) => a - b);
+            const prevMax = prevTimes.length ? prevTimes[prevTimes.length - 1] : null;
+            const curSat = s.satelliteTimestamp == null ? null : Number(s.satelliteTimestamp);
+
+            await this.core.fetchSatelliteListing(true);
+            this.core._emitStateChange();
+
+            const nextTimeline = this.core._computeSatelliteTimeline();
+            const nextTimes = [...(nextTimeline.unixTimes || [])]
+                .map((t) => Number(t))
+                .filter((t) => !Number.isNaN(t))
+                .sort((a, b) => a - b);
+            const newMax = nextTimes.length ? nextTimes[nextTimes.length - 1] : null;
+
+            if (prevMax != null && curSat != null && curSat === prevMax && newMax != null && newMax > prevMax) {
+                await this.core.setSatelliteTimestamp(newMax);
+            } else if (curSat != null && newMax != null && nextTimes.length && !nextTimes.includes(curSat)) {
+                await this.core.setSatelliteTimestamp(newMax);
+            }
+            this.emit('data:updated', { type: 'satellite', satelliteKey: s.satelliteKey });
+            return;
+        }
+
+        if (isNexrad && s.nexradSite) {
+            const nk = this.core._nexradTimesCacheKey();
+            const rawBefore = nk ? this.core.nexradTimesByStation[nk]?.unixTimes : [];
+            const filteredBefore = this.core._getFilteredNexradTimestampsForVariable(rawBefore || []);
+            const prevMax = filteredBefore.length ? filteredBefore[filteredBefore.length - 1] : null;
+            const curNx = s.nexradTimestamp == null ? null : Number(s.nexradTimestamp);
+
+            await this.core.refreshNexradTimes();
+
+            const rawAfter = nk ? this.core.nexradTimesByStation[nk]?.unixTimes : [];
+            const filteredAfter = this.core._getFilteredNexradTimestampsForVariable(rawAfter || []);
+            const newMax = filteredAfter.length ? filteredAfter[filteredAfter.length - 1] : null;
+
+            if (prevMax != null && curNx != null && curNx === prevMax && newMax != null && newMax > prevMax) {
+                await this.core.setNexradTimestamp(newMax);
+            } else if (curNx != null && newMax != null && filteredAfter.length && !filteredAfter.includes(curNx)) {
+                await this.core.setNexradTimestamp(newMax);
+            }
+            this.emit('data:updated', { type: 'nexrad', nexradSite: s.nexradSite });
+            return;
+        }
 
         if (isMRMS) {
             const oldTimestamps = new Set(this.core.mrmsStatus?.[currentVariable] || []);
@@ -410,7 +1084,7 @@ export class WeatherLayerManager extends EventEmitter {
                 newTimestampsToPreload.forEach(timestamp => {
                     const stateForPreload = { ...this.core.state, mrmsTimestamp: timestamp };
                     this.core._loadGridData(stateForPreload)
-                        .catch(e => console.warn(`[Auto-Refresh] Failed to preload MRMS frame for time ${timestamp}`, e));
+                        .catch(() => {});
                 });
 
                 // 5. Clean up the cache for any timestamps that are no longer available.
@@ -425,8 +1099,14 @@ export class WeatherLayerManager extends EventEmitter {
                 this.emit('data:updated', { type: 'mrms', variable: currentVariable, newTimestamps: newTimestampsToPreload });
             }
         } else {
+            const previousStatus = this.core.modelStatus;
             const modelStatus = await this.core.fetchModelStatus(true);
-            this.core._emitStateChange();
+            
+            // Only emit if the status actually changed
+            const statusChanged = JSON.stringify(previousStatus) !== JSON.stringify(modelStatus);
+            if (statusChanged) {
+                this.core._emitStateChange();
+            }
 
             const latestRun = findLatestModelRun(modelStatus, currentModel);
             if (!latestRun) return;
@@ -449,6 +1129,18 @@ export class WeatherLayerManager extends EventEmitter {
         // 1. Unbind the map's mousemove event listener
         this.map.off('mousemove', this._handleMouseMove);
 
+        if (this._nwsOverlay) {
+            try {
+                this._nwsOverlay.destroy();
+            } catch {
+                /* ignore */
+            }
+            this._nwsOverlay = null;
+        }
+
+        this._tearDownSatellite();
+        this._tearDownNexrad();
+
         // 2. Explicitly clean up and remove the visual layer
         if (this.shaderLayer) {
             // First, check if the layer still exists on the map before trying to remove it
@@ -469,7 +1161,5 @@ export class WeatherLayerManager extends EventEmitter {
         
         // 4. Clear any remaining internal state
         this.currentLoadedTimeKey = null;
-        
-        //console.log(`WeatherLayerManager with id "${this.layerId}" has been destroyed.`);
     }
 }