@aguacerowx/mapsgl 0.0.45 → 0.0.47

package/src/WeatherLayerManager.js

@@ -1,1528 +1,1541 @@
-// index.js - The main entry point for the @aguacerowx/web 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';
-
-const DEBUG_NS = '[WeatherLayerManager:debug]';
-
-/**
- * Redact secrets for console output.
- * @param {object} options
- */
-function _debugSanitizeOptions(options) {
-    if (!options || typeof options !== 'object') return options;
-    const o = { ...options };
-    if (typeof o.apiKey === 'string' && o.apiKey.length > 0) {
-        o.apiKey = `${o.apiKey.slice(0, 4)}…(${o.apiKey.length} chars)`;
-    }
-    return o;
-}
-
-/**
- * Compact summary of timestamp / hour arrays (MRMS timeline debugging).
- * @param {unknown[]} arr
- */
-function _debugSummarizeNumericSeries(arr) {
-    if (!Array.isArray(arr) || arr.length === 0) {
-        return { length: 0, min: null, max: null, spanSec: null, head: [], tail: undefined };
-    }
-    const nums = arr.map((x) => Number(x)).filter((n) => !Number.isNaN(n));
-    if (nums.length === 0) {
-        return { length: 0, min: null, max: null, spanSec: null, head: [], tail: undefined };
-    }
-    const sorted = [...nums].sort((a, b) => a - b);
-    const min = sorted[0];
-    const max = sorted[sorted.length - 1];
-    const head = sorted.slice(0, Math.min(8, sorted.length));
-    const tail = sorted.length > 16 ? sorted.slice(-8) : [];
-    return {
-        length: sorted.length,
-        min,
-        max,
-        spanSec: max != null && min != null ? max - min : null,
-        head,
-        tail: tail.length ? tail : undefined,
-    };
-}
-
-function findLatestModelRun(modelsData, modelName) {
-    const model = modelsData?.[modelName];
-    if (!model) return null;
-    const availableDates = Object.keys(model).sort((a, b) => b.localeCompare(a));
-    for (const date of availableDates) {
-        const runs = model[date];
-        if (!runs) continue;
-        const availableRuns = Object.keys(runs).sort((a, b) => b.localeCompare(a));
-        if (availableRuns.length > 0) return { date: date, run: availableRuns[0] };
-    }
-    return null;
-}
-
-/**
- * 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`).
- * @param {boolean} [options.debug] - When `true`, logs detailed diagnostics to the console (prefix `[WeatherLayerManager:debug]`). Off by default.
- */
-export class WeatherLayerManager extends EventEmitter {
-    constructor(map, options = {}) {
-        super();
-        if (!map) throw new Error('A Mapbox GL map instance is required.');
-        this.map = map;
-        /** @private When true, emit verbose `[WeatherLayerManager:debug]` logs. */
-        this._debug = options.debug === true;
-        /** @private Monotonic counter for correlating state:change logs. */
-        this._debugStateSeq = 0;
-        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.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);
-
-        if (this._debug) {
-            const layerOpts = options.layerOptions || {};
-            console.log(DEBUG_NS, 'constructor', {
-                layerId: this.layerId,
-                nexradLayerId: this._nexradLayerId,
-                mapLoaded: typeof this.map?.loaded === 'function' ? this.map.loaded() : undefined,
-                styleLoaded: this.map?.isStyleLoaded?.() ?? undefined,
-                weatherBeforeLayerId: this._weatherBeforeLayerId,
-                options: _debugSanitizeOptions(options),
-                layerOptions: layerOpts,
-                coreStateSnapshot: {
-                    isMRMS: this.core.state?.isMRMS,
-                    isSatellite: this.core.state?.isSatellite,
-                    isNexrad: this.core.state?.isNexrad,
-                    model: this.core.state?.model,
-                    variable: this.core.state?.variable,
-                    mrmsDurationValue: this.core.state?.mrmsDurationValue,
-                    mrmsTimestamp: this.core.state?.mrmsTimestamp,
-                    satelliteDurationValue: this.core.state?.satelliteDurationValue,
-                },
-            });
-        }
-
-        // 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);
-            
-            // Re-emit the state:change event for the end-user
-            this.emit('state:change', newState);
-        });
-
-        // Re-emit the data inspection event for the end-user
-        this.core.on('data:inspect', (payload) => this.emit('data:inspect', payload));
-        
-        // 3. BIND the map's mousemove event to call the core's utility method
-        this._handleMouseMove = this._handleMouseMove.bind(this);
-        this.map.on('mousemove', this._handleMouseMove);
-    }
-
-    /**
-     * Structured debug log (no-op unless `options.debug === true` on construction).
-     * @param {string} scope
-     * @param {object} [data]
-     */
-    _debugLog(scope, data) {
-        if (!this._debug) return;
-        if (data !== undefined) {
-            console.log(DEBUG_NS, scope, data);
-        } else {
-            console.log(DEBUG_NS, scope);
-        }
-    }
-
-    /**
-     * 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.
-     * @param {object} state - The new state object from AguaceroCore.
-     * @private
-     */
-    _handleStateChange(state) {
-        const seq = this._debug ? ++this._debugStateSeq : 0;
-        /** 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 (this._debug) {
-                const tsSummary = state.isMRMS
-                    ? _debugSummarizeNumericSeries(state.availableTimestamps || [])
-                    : null;
-                this._debugLog('state:change', {
-                    seq,
-                    mode: state.isSatellite
-                        ? 'satellite'
-                        : state.isNexrad
-                          ? 'nexrad'
-                          : state.isMRMS
-                            ? 'mrms'
-                            : 'model',
-                    model: state.model,
-                    variable: state.variable,
-                    runKey: `${state.model}-${state.date}-${state.run}-${state.variable}`,
-                    timeKey: state.isMRMS
-                        ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
-                        : Number(state.forecastHour),
-                    mrmsDurationValue: state.mrmsDurationValue,
-                    availableTimestampsSummary: tsSummary,
-                    availableHoursLen: Array.isArray(state.availableHours) ? state.availableHours.length : 0,
-                    shaderLayerRunKey: this.shaderLayer?.runKey ?? null,
-                    currentLoadedTimeKey: this.currentLoadedTimeKey,
-                    rebuildId: this.currentRebuildId,
-                    initialGridLoadPending: this._initialGridLoadPending,
-                });
-            }
-
-            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._debug && state.isMRMS) {
-                this._debugLog('grid path (mrms/model)', {
-                    seq,
-                    prevMrmsDurationValue: prevMrmsDur,
-                    mrmsDurationChanged,
-                    willRebuild: !this.shaderLayer || this.shaderLayer.runKey !== runKey,
-                    willUpdateData:
-                        this.shaderLayer &&
-                        this.shaderLayer.runKey === runKey &&
-                        this.currentLoadedTimeKey !== timeKey,
-                    shaderRunKey: this.shaderLayer?.runKey,
-                    targetRunKey: runKey,
-                });
-            }
-
-            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);
-                } else if (this._debug) {
-                    this._debugLog('skip _updateLayerData (duplicate before first paint)', {
-                        seq,
-                        timeKey,
-                        _rebuildTargetTimeKey: this._rebuildTargetTimeKey,
-                    });
-                }
-            }
-
-            if (this.shaderLayer) {
-                this.shaderLayer.updateStyle({ opacity: state.opacity });
-                this.shaderLayer.setSmoothing(!state.shaderSmoothingEnabled);
-                this.map.triggerRepaint();
-            }
-
-            if (state.isMRMS && this.shaderLayer && mrmsDurationChanged) {
-                if (this._debug) {
-                    this._debugLog('_preloadAllTimeSteps (mrms duration changed)', {
-                        seq,
-                        from: prevMrmsDur,
-                        to: state.mrmsDurationValue,
-                    });
-                }
-                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) {
-            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();
-        }
-    }
-
-    // --- DELEGATION METHODS ---
-    // The public API of the WeatherLayerManager now simply "delegates" calls
-    // to the core engine. This keeps the API consistent for your users.
-
-    async initialize(options) {
-        const t0 =
-            typeof performance !== 'undefined' && typeof performance.now === 'function'
-                ? performance.now()
-                : Date.now();
-        this._debugLog('initialize:start', {
-            autoRefreshEnabled: this.autoRefreshEnabled,
-            autoRefreshIntervalSeconds: this.autoRefreshIntervalSeconds,
-            passedOptions: options && typeof options === 'object' ? { ...options } : options,
-            coreStateBefore: {
-                isMRMS: this.core.state?.isMRMS,
-                variable: this.core.state?.variable,
-                mrmsTimestamp: this.core.state?.mrmsTimestamp,
-                mrmsDurationValue: this.core.state?.mrmsDurationValue,
-            },
-            mrmsStatusVariableLen: this.core.state?.variable
-                ? (this.core.mrmsStatus?.[this.core.state.variable]?.length ?? 'n/a')
-                : 'n/a',
-        });
-        if (this.autoRefreshEnabled) {
-            this.setAutoRefresh(true, this.autoRefreshIntervalSeconds);
-        }
-        try {
-            const result = await this.core.initialize({ ...options, autoRefresh: false });
-            const t1 =
-                typeof performance !== 'undefined' && typeof performance.now === 'function'
-                    ? performance.now()
-                    : Date.now();
-            this._debugLog('initialize:done', {
-                elapsedMs: Math.round(t1 - t0),
-                coreStateAfter: {
-                    isMRMS: this.core.state?.isMRMS,
-                    variable: this.core.state?.variable,
-                    model: this.core.state?.model,
-                    date: this.core.state?.date,
-                    run: this.core.state?.run,
-                    forecastHour: this.core.state?.forecastHour,
-                    mrmsTimestamp: this.core.state?.mrmsTimestamp,
-                    mrmsDurationValue: this.core.state?.mrmsDurationValue,
-                },
-                availableTimestampsSummary: _debugSummarizeNumericSeries(
-                    this._lastEmittedState?.availableTimestamps || [],
-                ),
-                availableHoursLen: Array.isArray(this._lastEmittedState?.availableHours)
-                    ? this._lastEmittedState.availableHours.length
-                    : 0,
-                modelStatusLoaded: this.core.modelStatus != null,
-                mrmsStatusKeys:
-                    this.core.mrmsStatus && typeof this.core.mrmsStatus === 'object'
-                        ? Object.keys(this.core.mrmsStatus).length
-                        : 0,
-                mrmsStatusVariableLen: this.core.state?.variable
-                    ? (this.core.mrmsStatus?.[this.core.state.variable]?.length ?? 0)
-                    : 0,
-            });
-            return result;
-        } catch (err) {
-            this._debugLog('initialize:error', {
-                message: err?.message || String(err),
-                stack: err?.stack,
-            });
-            throw err;
-        }
-    }
-    async setState(newState) { return this.core.setState(newState); }
-    play() { this.core.play(); }
-    pause() { this.core.pause(); }
-    togglePlay() { this.core.togglePlay(); }
-    step(direction) { this.core.step(direction); }
-    setPlaybackSpeed(speed) { this.core.setPlaybackSpeed(speed); }
-    async setOpacity(opacity) { return this.core.setOpacity(opacity); }
-    async setUnits(units) { return this.core.setUnits(units); }
-    async switchMode(options) { return this.core.switchMode(options); }
-    getAvailableVariables(model) { return this.core.getAvailableVariables(model); }
-    getVariableDisplayName(code) { return this.core.getVariableDisplayName(code); }
-    async setRun(runString) { return this.core.setRun(runString); }
-    setShaderSmoothing(enabled) { 
-        return this.core.setShaderSmoothing(enabled); 
-    }
-    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.
-
-    /** Swaps to a timestep that was already uploaded by rebuild or `_preloadAllTimeSteps`. */
-    _updateLayerDataWithToken(state) {
-        if (!this.shaderLayer || !state.variable) {
-            return;
-        }
-
-        const timeKey = state.isMRMS
-            ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
-            : Number(state.forecastHour);
-        if (this.shaderLayer.switchToPreloadedTexture(timeKey)) {
-            this.currentLoadedTimeKey = timeKey;
-            this.map.triggerRepaint();
-            return;
-        }
-
-        // 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.
-    }
-
-    /**
-     * MRMS timestamps or model forecast hours for the active timeline (ordering preserved from source lists).
-     * @returns {number[]}
-     */
-    _collectNormalizedTimelineSteps(state) {
-        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;
-        let mrmsTimelineSource = '';
-        if (state.isMRMS) {
-            if (fromState.length) {
-                timeSteps = fromState;
-                mrmsTimelineSource = 'state.availableTimestamps';
-            } else if (
-                state.variable &&
-                typeof this.core._getFilteredMrmsTimestampsForVariable === 'function'
-            ) {
-                /**
-                 * Same list {@link AguaceroCore} puts on `state:change` as `availableTimestamps`.
-                 * When that array is missing or empty on this snapshot (ordering / first paint),
-                 * derive from core so rebuild preload is not stuck with only `currentFrameTime`.
-                 */
-                try {
-                    timeSteps = this.core._getFilteredMrmsTimestampsForVariable(state.variable);
-                    mrmsTimelineSource = 'core._getFilteredMrmsTimestampsForVariable';
-                } catch {
-                    timeSteps = fromCore;
-                    mrmsTimelineSource = 'core forecast hours fallback (error)';
-                }
-            } else {
-                timeSteps = fromCore;
-                mrmsTimelineSource = 'empty';
-            }
-        } else {
-            timeSteps = fromCore.length > 0 ? fromCore : fromState;
-        }
-
-        const out = (timeSteps || [])
-            .map(t => Number(t))
-            .filter(t => !Number.isNaN(t));
-        if (this._debug && state.isMRMS) {
-            this._debugLog('_collectNormalizedTimelineSteps', {
-                variable: state.variable,
-                mrmsDurationValue: state.mrmsDurationValue,
-                fromStateLen: fromState.length,
-                fromCoreLen: fromCore.length,
-                chosenSource: mrmsTimelineSource || (state.isMRMS ? 'n/a' : 'model'),
-                normalizedLen: out.length,
-                summary: _debugSummarizeNumericSeries(out),
-            });
-        }
-        return out;
-    }
-
-    /**
-     * @param {object} state
-     * @param {number[]} times
-     * @param {{ rebuildId: number, mode: 'rebuild' | 'append' }} options
-     */
-    _runParallelGridFrameLoads(state, times, options) {
-        const { rebuildId, mode } = options;
-        if (!times.length || !this.shaderLayer) {
-            if (mode === 'rebuild') {
-                this._initialGridLoadPending = false;
-            }
-            this._debugLog('_runParallelGridFrameLoads:skip', {
-                reason: !times.length ? 'no times' : 'no shaderLayer',
-                mode,
-                rebuildId,
-                timesLen: times.length,
-            });
-            return;
-        }
-
-        // Number(null) === 0, which is falsy and causes _loadGridData to return null immediately
-        // (the core guards with `if (!mrmsTimestamp) return null`). Treat null as NaN so that
-        // primaryTimeForRebuild falls through to times[0] — the first real MRMS timestamp.
-        const _rawFrameTime = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
-        const currentFrameTime = _rawFrameTime == null ? NaN : Number(_rawFrameTime);
-        /** When the active timestep is unset/NaN, paint the first timeline step (legacy single-fetch behavior). */
-        let primaryTimeForRebuild = Number.NaN;
-        if (mode === 'rebuild') {
-            primaryTimeForRebuild = Number.isFinite(currentFrameTime)
-                ? currentFrameTime
-                : times[0];
-        }
-        const tsKey = state.isMRMS ? 'mrmsTimestamp' : 'forecastHour';
-        const gridModel = state.isMRMS ? 'mrms' : state.model;
-        const { gridDef } = this.core._getGridCornersAndDef(gridModel);
-
-        this._debugLog('_runParallelGridFrameLoads', {
-            mode,
-            rebuildId,
-            gridModel,
-            timesLen: times.length,
-            timesSummary: _debugSummarizeNumericSeries(times),
-            currentFrameTime,
-            primaryTimeForRebuild:
-                mode === 'rebuild'
-                    ? Number.isFinite(currentFrameTime)
-                        ? currentFrameTime
-                        : times[0]
-                    : undefined,
-            tsKey,
-            gridNxNy: gridDef?.grid_params
-                ? { nx: gridDef.grid_params.nx, ny: gridDef.grid_params.ny }
-                : null,
-        });
-
-        times.forEach((time) => {
-            const stateForTime = { ...state, [tsKey]: time };
-            this.core._loadGridData(stateForTime)
-                .then((grid) => {
-                    if (rebuildId !== this.currentRebuildId || !this.shaderLayer) {
-                        return;
-                    }
-
-                    const isPrimaryFrame =
-                        mode === 'rebuild' &&
-                        Number.isFinite(primaryTimeForRebuild) &&
-                        time === primaryTimeForRebuild;
-
-                    if (isPrimaryFrame) {
-                        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._debugLog('_loadGridData:skip primary (core time drifted vs rebuild target)', {
-                                time,
-                                coreTimeKey,
-                                _rebuildTargetTimeKey: this._rebuildTargetTimeKey,
-                                rebuildId,
-                            });
-                            return;
-                        }
-                        if (!grid?.data) {
-                            this._debugLog('_loadGridData:primary frame missing grid.data', {
-                                time,
-                                rebuildId,
-                                mode,
-                            });
-                            this._initialGridLoadPending = false;
-                            return;
-                        }
-                        this.shaderLayer.updateDataTexture(
-                            grid.data,
-                            grid.encoding,
-                            gridDef.grid_params.nx,
-                            gridDef.grid_params.ny,
-                        );
-                        this.currentLoadedTimeKey = time;
-                        this.shaderLayer.registerCurrentDataTextureAsPreloaded(time);
-                        this._initialGridLoadPending = false;
-                        this.map.triggerRepaint();
-                        return;
-                    }
-
-                    if (grid?.data) {
-                        this.shaderLayer.storePreloadedTexture(
-                            time,
-                            grid.data,
-                            grid.encoding,
-                            gridDef.grid_params.nx,
-                            gridDef.grid_params.ny,
-                        );
-                        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();
-                        }
-                    } else if (this._debug && mode === 'append') {
-                        this._debugLog('_loadGridData:empty grid (append)', { time, mode, rebuildId });
-                    }
-                })
-                .catch((err) => {
-                    this._debugLog('_loadGridData:error', {
-                        time,
-                        mode,
-                        rebuildId,
-                        message: err?.message || String(err),
-                    });
-                    if (
-                        mode === 'rebuild' &&
-                        Number.isFinite(primaryTimeForRebuild) &&
-                        time === primaryTimeForRebuild
-                    ) {
-                        this._initialGridLoadPending = false;
-                    }
-                });
-        });
-    }
-
-    _rebuildLayerAndPreload(state) {
-        if (state.isSatellite) {
-            return;
-        }
-        if (!state.variable) {
-            return;
-        }
-
-        const rebuildId = ++this.currentRebuildId;
-
-        this.core.cancelAllRequests();
-
-        if (this.shaderLayer) {
-            this.map.removeLayer(this.shaderLayer.id);
-            this.shaderLayer = null;
-        }
-        this.currentLoadedTimeKey = null;
-
-        if (
-            !state.isMRMS &&
-            state.forecastHour === 0 &&
-            state.variable === 'ptypeRefl' &&
-            state.model === 'hrrr'
-        ) {
-            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;
-            }
-        }
-
-        if (rebuildId !== this.currentRebuildId) return;
-
-        const runKey = `${state.model}-${state.date}-${state.run}-${state.variable}`;
-
-        this.shaderLayer = new GridRenderLayer(this.layerId);
-        this.shaderLayer.runKey = runKey;
-        const beforeId = this._weatherInsertBeforeId();
-        if (beforeId) {
-            this.map.addLayer(this.shaderLayer, beforeId);
-        } else {
-            this.map.addLayer(this.shaderLayer);
-        }
-        this._updateLayerStyle(state);
-
-        this._rebuildTargetTimeKey = state.isMRMS
-            ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
-            : Number(state.forecastHour);
-        this._initialGridLoadPending = true;
-
-        const normalized = this._collectNormalizedTimelineSteps(state);
-        // Same null-guard as in _runParallelGridFrameLoads: Number(null) === 0, which is a finite
-        // value that would inject Unix epoch into timesToLoad and mis-identify the primary frame.
-        const _rawCft = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
-        const currentFrameTime = _rawCft == null ? NaN : Number(_rawCft);
-        const timesSet = new Set(normalized);
-        if (!Number.isNaN(currentFrameTime)) {
-            timesSet.add(currentFrameTime);
-        }
-        let timesToLoad = [...timesSet];
-        if (timesToLoad.length === 0 && !Number.isNaN(currentFrameTime)) {
-            timesToLoad = [currentFrameTime];
-        }
-        this._debugLog('_rebuildLayerAndPreload:timeline', {
-            rebuildId,
-            isMRMS: state.isMRMS,
-            variable: state.variable,
-            normalizedLen: normalized.length,
-            normalizedSummary: _debugSummarizeNumericSeries(normalized),
-            currentFrameTime,
-            timesToLoadLen: timesToLoad.length,
-            timesToLoadSummary: _debugSummarizeNumericSeries(timesToLoad),
-            insertBeforeId: beforeId ?? '(stack top)',
-        });
-        if (timesToLoad.length === 0) {
-            this._initialGridLoadPending = false;
-            this._debugLog('_rebuildLayerAndPreload:no times to load — check availableTimestamps / duration window', {
-                rebuildId,
-                availableTimestampsLen: Array.isArray(state.availableTimestamps)
-                    ? state.availableTimestamps.length
-                    : 0,
-                mrmsDurationValue: state.mrmsDurationValue,
-            });
-            return;
-        }
-
-        if (rebuildId === this.currentRebuildId) {
-            this._runParallelGridFrameLoads(state, timesToLoad, { rebuildId, mode: 'rebuild' });
-        }
-    }
-
-    _preloadAllTimeSteps(state) {
-        const normalized = this._collectNormalizedTimelineSteps(state);
-        const _rawPft = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
-        const currentFrameTime = _rawPft == null ? NaN : Number(_rawPft);
-        const stepsToPreload = normalized.filter(t => t !== currentFrameTime);
-
-        this._debugLog('_preloadAllTimeSteps', {
-            normalizedLen: normalized.length,
-            currentFrameTime,
-            stepsToPreloadLen: stepsToPreload.length,
-            stepsSummary: _debugSummarizeNumericSeries(stepsToPreload),
-        });
-
-        if (normalized.length === 0) {
-            return;
-        }
-
-        if (stepsToPreload.length === 0) {
-            this._debugLog('_preloadAllTimeSteps:skip (nothing to preload besides current)', {
-                currentFrameTime,
-            });
-            return;
-        }
-
-        const capturedRebuildId = this.currentRebuildId;
-        this._runParallelGridFrameLoads(state, stepsToPreload, { rebuildId: capturedRebuildId, mode: 'append' });
-    }
-
-    _updateLayerData(state) {
-        return this._updateLayerDataWithToken(state);
-    }
-
-    _updateLayerStyle(state) {
-        if (!this.shaderLayer || !state.variable) return;
-
-        const gridModel = state.isMRMS ? 'mrms' : state.model;
-        const geometry = this.core._getGridCornersAndDef(gridModel);
-        if (!geometry) {
-            return;
-        }
-
-        const { corners, gridDef } = geometry;
-        const { colormap, baseUnit } = this.core._getColormapForVariable(state.variable);
-        const toUnit = this.core._getTargetUnit(baseUnit, state.units);
-
-        const finalColormap = this.core._convertColormapUnits(colormap, baseUnit, toUnit);
-        
-        let dataRange;
-        if (state.variable === 'ptypeRefl' || state.variable === 'ptypeRate') {
-            if (state.isMRMS) {
-                dataRange = [5, 380];
-            } else {
-                dataRange = [5, 380];
-            }
-        } else {
-            dataRange = [finalColormap[0], finalColormap[finalColormap.length - 2]];
-        }
-        
-        const dataNativeUnit = (DICTIONARIES.fld[state.variable] || {}).defaultUnit || 'none';
-
-        this.shaderLayer.updateGeometry(corners, gridDef);
-        this.shaderLayer.updateColormapTexture(finalColormap);
-        this.shaderLayer.updateStyle({ opacity: state.opacity, dataRange });
-        this.shaderLayer.setUnitConversion(dataNativeUnit, state.units);
-        this.shaderLayer.setVariable(state.variable);
-        this.shaderLayer.setIsMRMS(state.isMRMS); // NEW
-    }
-    
-    /**
-     * Handles the map's mousemove event by delegating calculations to the core.
-     * @param {object} e - The Mapbox GL mouse event object.
-     * @private
-     */
-    async _handleMouseMove(e) {
-        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);
-
-        if (payload) {
-            this.emit('data:inspect', {
-                ...payload,
-                point: e.point,
-            });
-        } else {
-            this.emit('data:inspect', null);
-        }
-    }
-
-    /**
-     * Enables or disables automatic checking for new weather data for both models and MRMS.
-     * When enabled, it periodically checks for and displays the latest available data.
-     * @param {boolean} enabled - Whether to enable or disable auto-refresh.
-     * @param {number} [intervalSeconds] - The interval in seconds to check for new data. Defaults to the value from constructor options or 30.
-     */
-    setAutoRefresh(enabled, intervalSeconds) {
-        // Stop any existing refresh interval
-        if (this.autoRefreshIntervalId) {
-            clearInterval(this.autoRefreshIntervalId);
-            this.autoRefreshIntervalId = null;
-        }
-
-        // Store the new state
-        this.autoRefreshEnabled = enabled;
-        if (typeof intervalSeconds === 'number' && intervalSeconds > 0) {
-            this.autoRefreshIntervalSeconds = intervalSeconds;
-        }
-
-        if (this.autoRefreshEnabled) {
-            const intervalMilliseconds = this.autoRefreshIntervalSeconds * 1000;
-            // Run the check immediately once, then start the interval
-            this._checkForUpdates(); 
-            this.autoRefreshIntervalId = setInterval(() => this._checkForUpdates(), intervalMilliseconds);
-        }
-    }
-
-    /**
-     * Manually triggers a check for new weather data.
-     * This performs the same action as a single auto-refresh cycle, updating the
-     * timeline and preloading new data in the background without changing the user's view.
-     * @returns {Promise<void>}
-     */
-    async refreshData() {
-        await this._checkForUpdates();
-    }
-
-    /**
-     * Checks for new data, updates the timeline, and proactively preloads the data for
-     * any new time steps in the background.
-     * @private
-     */
-    async _checkForUpdates() {
-        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] || []);
-
-            // 1. Fetch the absolute latest status
-            const mrmsStatus = await this.core.fetchMRMSStatus(true);
-            const newTimestamps = mrmsStatus?.[currentVariable] || [];
-            if (newTimestamps.length === 0) return;
-
-            // 2. Identify exactly which timestamps are new
-            const newTimestampsToPreload = newTimestamps.filter(ts => !oldTimestamps.has(ts));
-
-            if (newTimestampsToPreload.length > 0) {
-                // 3. Update the core's internal status and emit the change to update the UI (slider)
-                this.core.mrmsStatus = mrmsStatus; 
-                this.core._emitStateChange();
-
-                // 4. Proactively fetch the data for each new timestamp in the background.
-                newTimestampsToPreload.forEach(timestamp => {
-                    const stateForPreload = { ...this.core.state, mrmsTimestamp: timestamp };
-                    this.core._loadGridData(stateForPreload)
-                        .catch(() => {});
-                });
-
-                // 5. Clean up the cache for any timestamps that are no longer available.
-                const newTimestampsSet = new Set(newTimestamps);
-                oldTimestamps.forEach(oldTs => {
-                    if (!newTimestampsSet.has(oldTs)) {
-                        const cacheKey = `mrms-${oldTs}-${currentVariable}-0`;
-                        this.core.dataCache.delete(cacheKey);
-                    }
-                });
-
-                this.emit('data:updated', { type: 'mrms', variable: currentVariable, newTimestamps: newTimestampsToPreload });
-            }
-        } else {
-            const previousStatus = this.core.modelStatus;
-            const modelStatus = await this.core.fetchModelStatus(true);
-            
-            // 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;
-
-            const currentRunKey = `${date}:${run}`;
-            const latestRunKey = `${latestRun.date}:${latestRun.run}`;
-
-            if (latestRunKey > currentRunKey) {
-                this.emit('data:updated', { type: 'model', model: currentModel, newRun: latestRunKey });
-            }
-        }
-    }
-
-    /**
-     * Cleans up all resources.
-     */
-    destroy() {
-        this._debugLog('destroy');
-        this.setAutoRefresh(false);
-        
-        // 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
-            if (this.map.getLayer(this.shaderLayer.id)) {
-                this.map.removeLayer(this.shaderLayer.id);
-            }
-            
-            // Manually call the layer's own cleanup method as a safeguard.
-            // This guarantees the release of WebGL resources (textures, buffers).
-            this.shaderLayer.onRemove();
-            
-            // Nullify the reference to the custom layer object
-            this.shaderLayer = null;
-        }
-
-        // 3. Tell the core engine to destroy its own resources (cache, workers, etc.)
-        this.core.destroy();
-        
-        // 4. Clear any remaining internal state
-        this.currentLoadedTimeKey = null;
-    }
+// index.js - The main entry point for the @aguacerowx/web 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';
+
+import { DEFAULT_BASIS_BASE_URL } from './defaultBasisBaseUrl.js';
+
+const DEBUG_NS = '[WeatherLayerManager:debug]';
+
+/**
+ * Redact secrets for console output.
+ * @param {object} options
+ */
+function _debugSanitizeOptions(options) {
+    if (!options || typeof options !== 'object') return options;
+    const o = { ...options };
+    if (typeof o.apiKey === 'string' && o.apiKey.length > 0) {
+        o.apiKey = `${o.apiKey.slice(0, 4)}…(${o.apiKey.length} chars)`;
+    }
+    return o;
+}
+
+/**
+ * Compact summary of timestamp / hour arrays (MRMS timeline debugging).
+ * @param {unknown[]} arr
+ */
+function _debugSummarizeNumericSeries(arr) {
+    if (!Array.isArray(arr) || arr.length === 0) {
+        return { length: 0, min: null, max: null, spanSec: null, head: [], tail: undefined };
+    }
+    const nums = arr.map((x) => Number(x)).filter((n) => !Number.isNaN(n));
+    if (nums.length === 0) {
+        return { length: 0, min: null, max: null, spanSec: null, head: [], tail: undefined };
+    }
+    const sorted = [...nums].sort((a, b) => a - b);
+    const min = sorted[0];
+    const max = sorted[sorted.length - 1];
+    const head = sorted.slice(0, Math.min(8, sorted.length));
+    const tail = sorted.length > 16 ? sorted.slice(-8) : [];
+    return {
+        length: sorted.length,
+        min,
+        max,
+        spanSec: max != null && min != null ? max - min : null,
+        head,
+        tail: tail.length ? tail : undefined,
+    };
+}
+
+function findLatestModelRun(modelsData, modelName) {
+    const model = modelsData?.[modelName];
+    if (!model) return null;
+    const availableDates = Object.keys(model).sort((a, b) => b.localeCompare(a));
+    for (const date of availableDates) {
+        const runs = model[date];
+        if (!runs) continue;
+        const availableRuns = Object.keys(runs).sort((a, b) => b.localeCompare(a));
+        if (availableRuns.length > 0) return { date: date, run: availableRuns[0] };
+    }
+    return null;
+}
+
+/**
+ * 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`).
+ * @param {boolean} [options.debug] - When `true`, logs detailed diagnostics to the console (prefix `[WeatherLayerManager:debug]`). Off by default.
+ * @param {string} [options.basisBaseUrl] - URL prefix for satellite KTX2 Basis transcoder assets (`basis_transcoder.js`, `basis_transcoder.wasm`). Defaults to jsDelivr for the published package version; override (e.g. `/basis/`) for strict CSP or offline.
+ */
+export class WeatherLayerManager extends EventEmitter {
+    constructor(map, options = {}) {
+        super();
+        if (!map) throw new Error('A Mapbox GL map instance is required.');
+        this.map = map;
+        /** @private When true, emit verbose `[WeatherLayerManager:debug]` logs. */
+        this._debug = options.debug === true;
+        /** @private Monotonic counter for correlating state:change logs. */
+        this._debugStateSeq = 0;
+        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.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 ?? DEFAULT_BASIS_BASE_URL;
+        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);
+
+        if (this._debug) {
+            const layerOpts = options.layerOptions || {};
+            console.log(DEBUG_NS, 'constructor', {
+                layerId: this.layerId,
+                nexradLayerId: this._nexradLayerId,
+                mapLoaded: typeof this.map?.loaded === 'function' ? this.map.loaded() : undefined,
+                styleLoaded: this.map?.isStyleLoaded?.() ?? undefined,
+                weatherBeforeLayerId: this._weatherBeforeLayerId,
+                options: _debugSanitizeOptions(options),
+                layerOptions: layerOpts,
+                coreStateSnapshot: {
+                    isMRMS: this.core.state?.isMRMS,
+                    isSatellite: this.core.state?.isSatellite,
+                    isNexrad: this.core.state?.isNexrad,
+                    model: this.core.state?.model,
+                    variable: this.core.state?.variable,
+                    mrmsDurationValue: this.core.state?.mrmsDurationValue,
+                    mrmsTimestamp: this.core.state?.mrmsTimestamp,
+                    satelliteDurationValue: this.core.state?.satelliteDurationValue,
+                },
+            });
+        }
+
+        // 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);
+            
+            // Re-emit the state:change event for the end-user
+            this.emit('state:change', newState);
+        });
+
+        // Re-emit the data inspection event for the end-user
+        this.core.on('data:inspect', (payload) => this.emit('data:inspect', payload));
+        
+        // 3. BIND the map's mousemove event to call the core's utility method
+        this._handleMouseMove = this._handleMouseMove.bind(this);
+        this.map.on('mousemove', this._handleMouseMove);
+    }
+
+    /**
+     * Structured debug log (no-op unless `options.debug === true` on construction).
+     * @param {string} scope
+     * @param {object} [data]
+     */
+    _debugLog(scope, data) {
+        if (!this._debug) return;
+        if (data !== undefined) {
+            console.log(DEBUG_NS, scope, data);
+        } else {
+            console.log(DEBUG_NS, scope);
+        }
+    }
+
+    /**
+     * 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.
+     * @param {object} state - The new state object from AguaceroCore.
+     * @private
+     */
+    _handleStateChange(state) {
+        const seq = this._debug ? ++this._debugStateSeq : 0;
+        /** 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 (this._debug) {
+                const tsSummary = state.isMRMS
+                    ? _debugSummarizeNumericSeries(state.availableTimestamps || [])
+                    : null;
+                this._debugLog('state:change', {
+                    seq,
+                    mode: state.isSatellite
+                        ? 'satellite'
+                        : state.isNexrad
+                          ? 'nexrad'
+                          : state.isMRMS
+                            ? 'mrms'
+                            : 'model',
+                    model: state.model,
+                    variable: state.variable,
+                    runKey: `${state.model}-${state.date}-${state.run}-${state.variable}`,
+                    timeKey: state.isMRMS
+                        ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
+                        : Number(state.forecastHour),
+                    mrmsTimestamp: state.mrmsTimestamp,
+                    mrmsDurationValue: state.mrmsDurationValue,
+                    availableTimestampsSummary: tsSummary,
+                    availableHoursLen: Array.isArray(state.availableHours) ? state.availableHours.length : 0,
+                    shaderLayerRunKey: this.shaderLayer?.runKey ?? null,
+                    currentLoadedTimeKey: this.currentLoadedTimeKey,
+                    rebuildId: this.currentRebuildId,
+                    initialGridLoadPending: this._initialGridLoadPending,
+                });
+            }
+
+            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._debug && state.isMRMS) {
+                this._debugLog('grid path (mrms/model)', {
+                    seq,
+                    prevMrmsDurationValue: prevMrmsDur,
+                    mrmsDurationChanged,
+                    willRebuild: !this.shaderLayer || this.shaderLayer.runKey !== runKey,
+                    willUpdateData:
+                        this.shaderLayer &&
+                        this.shaderLayer.runKey === runKey &&
+                        this.currentLoadedTimeKey !== timeKey,
+                    shaderRunKey: this.shaderLayer?.runKey,
+                    targetRunKey: runKey,
+                });
+            }
+
+            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);
+                } else if (this._debug) {
+                    this._debugLog('skip _updateLayerData (duplicate before first paint)', {
+                        seq,
+                        timeKey,
+                        _rebuildTargetTimeKey: this._rebuildTargetTimeKey,
+                    });
+                }
+            }
+
+            if (this.shaderLayer) {
+                this.shaderLayer.updateStyle({ opacity: state.opacity });
+                this.shaderLayer.setSmoothing(!state.shaderSmoothingEnabled);
+                this.map.triggerRepaint();
+            }
+
+            if (state.isMRMS && this.shaderLayer && mrmsDurationChanged) {
+                if (this._debug) {
+                    this._debugLog('_preloadAllTimeSteps (mrms duration changed)', {
+                        seq,
+                        from: prevMrmsDur,
+                        to: state.mrmsDurationValue,
+                    });
+                }
+                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) {
+            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();
+        }
+    }
+
+    // --- DELEGATION METHODS ---
+    // The public API of the WeatherLayerManager now simply "delegates" calls
+    // to the core engine. This keeps the API consistent for your users.
+
+    async initialize(options) {
+        const t0 =
+            typeof performance !== 'undefined' && typeof performance.now === 'function'
+                ? performance.now()
+                : Date.now();
+        this._debugLog('initialize:start', {
+            autoRefreshEnabled: this.autoRefreshEnabled,
+            autoRefreshIntervalSeconds: this.autoRefreshIntervalSeconds,
+            passedOptions: options && typeof options === 'object' ? { ...options } : options,
+            coreStateBefore: {
+                isMRMS: this.core.state?.isMRMS,
+                variable: this.core.state?.variable,
+                mrmsTimestamp: this.core.state?.mrmsTimestamp,
+                mrmsDurationValue: this.core.state?.mrmsDurationValue,
+            },
+            mrmsStatusVariableLen: this.core.state?.variable
+                ? (this.core.mrmsStatus?.[this.core.state.variable]?.length ?? 'n/a')
+                : 'n/a',
+        });
+        if (this.autoRefreshEnabled) {
+            this.setAutoRefresh(true, this.autoRefreshIntervalSeconds);
+        }
+        try {
+            const result = await this.core.initialize({ ...options, autoRefresh: false });
+            const t1 =
+                typeof performance !== 'undefined' && typeof performance.now === 'function'
+                    ? performance.now()
+                    : Date.now();
+            this._debugLog('initialize:done', {
+                elapsedMs: Math.round(t1 - t0),
+                coreStateAfter: {
+                    isMRMS: this.core.state?.isMRMS,
+                    variable: this.core.state?.variable,
+                    model: this.core.state?.model,
+                    date: this.core.state?.date,
+                    run: this.core.state?.run,
+                    forecastHour: this.core.state?.forecastHour,
+                    mrmsTimestamp: this.core.state?.mrmsTimestamp,
+                    mrmsDurationValue: this.core.state?.mrmsDurationValue,
+                },
+                availableTimestampsSummary: _debugSummarizeNumericSeries(
+                    this._lastEmittedState?.availableTimestamps || [],
+                ),
+                availableHoursLen: Array.isArray(this._lastEmittedState?.availableHours)
+                    ? this._lastEmittedState.availableHours.length
+                    : 0,
+                modelStatusLoaded: this.core.modelStatus != null,
+                mrmsStatusKeys:
+                    this.core.mrmsStatus && typeof this.core.mrmsStatus === 'object'
+                        ? Object.keys(this.core.mrmsStatus).length
+                        : 0,
+                mrmsStatusVariableLen: this.core.state?.variable
+                    ? (this.core.mrmsStatus?.[this.core.state.variable]?.length ?? 0)
+                    : 0,
+            });
+            return result;
+        } catch (err) {
+            this._debugLog('initialize:error', {
+                message: err?.message || String(err),
+                stack: err?.stack,
+            });
+            throw err;
+        }
+    }
+    async setState(newState) { return this.core.setState(newState); }
+    play() { this.core.play(); }
+    pause() { this.core.pause(); }
+    togglePlay() { this.core.togglePlay(); }
+    step(direction) { this.core.step(direction); }
+    setPlaybackSpeed(speed) { this.core.setPlaybackSpeed(speed); }
+    async setOpacity(opacity) { return this.core.setOpacity(opacity); }
+    async setUnits(units) { return this.core.setUnits(units); }
+    async switchMode(options) { return this.core.switchMode(options); }
+    getAvailableVariables(model) { return this.core.getAvailableVariables(model); }
+    getVariableDisplayName(code) { return this.core.getVariableDisplayName(code); }
+    async setRun(runString) { return this.core.setRun(runString); }
+    setShaderSmoothing(enabled) { 
+        return this.core.setShaderSmoothing(enabled); 
+    }
+    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.
+
+    /** Swaps to a timestep that was already uploaded by rebuild or `_preloadAllTimeSteps`. */
+    _updateLayerDataWithToken(state) {
+        if (!this.shaderLayer || !state.variable) {
+            return;
+        }
+
+        const timeKey = state.isMRMS
+            ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
+            : Number(state.forecastHour);
+        if (this.shaderLayer.switchToPreloadedTexture(timeKey)) {
+            this.currentLoadedTimeKey = timeKey;
+            this.map.triggerRepaint();
+            return;
+        }
+
+        // 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.
+    }
+
+    /**
+     * MRMS timestamps or model forecast hours for the active timeline (ordering preserved from source lists).
+     * @returns {number[]}
+     */
+    _collectNormalizedTimelineSteps(state) {
+        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;
+        let mrmsTimelineSource = '';
+        if (state.isMRMS) {
+            if (fromState.length) {
+                timeSteps = fromState;
+                mrmsTimelineSource = 'state.availableTimestamps';
+            } else if (
+                state.variable &&
+                typeof this.core._getFilteredMrmsTimestampsForVariable === 'function'
+            ) {
+                /**
+                 * Same list {@link AguaceroCore} puts on `state:change` as `availableTimestamps`.
+                 * When that array is missing or empty on this snapshot (ordering / first paint),
+                 * derive from core so rebuild preload is not stuck with only `currentFrameTime`.
+                 */
+                try {
+                    timeSteps = this.core._getFilteredMrmsTimestampsForVariable(state.variable);
+                    mrmsTimelineSource = 'core._getFilteredMrmsTimestampsForVariable';
+                } catch {
+                    timeSteps = fromCore;
+                    mrmsTimelineSource = 'core forecast hours fallback (error)';
+                }
+            } else {
+                timeSteps = fromCore;
+                mrmsTimelineSource = 'empty';
+            }
+        } else {
+            timeSteps = fromCore.length > 0 ? fromCore : fromState;
+        }
+
+        const out = (timeSteps || [])
+            .map(t => Number(t))
+            .filter(t => !Number.isNaN(t));
+        if (this._debug && state.isMRMS) {
+            this._debugLog('_collectNormalizedTimelineSteps', {
+                variable: state.variable,
+                mrmsDurationValue: state.mrmsDurationValue,
+                fromStateLen: fromState.length,
+                fromCoreLen: fromCore.length,
+                chosenSource: mrmsTimelineSource || (state.isMRMS ? 'n/a' : 'model'),
+                normalizedLen: out.length,
+                summary: _debugSummarizeNumericSeries(out),
+            });
+        }
+        return out;
+    }
+
+    /**
+     * @param {object} state
+     * @param {number[]} times
+     * @param {{ rebuildId: number, mode: 'rebuild' | 'append' }} options
+     */
+    _runParallelGridFrameLoads(state, times, options) {
+        const { rebuildId, mode } = options;
+        if (!times.length || !this.shaderLayer) {
+            if (mode === 'rebuild') {
+                this._initialGridLoadPending = false;
+            }
+            this._debugLog('_runParallelGridFrameLoads:skip', {
+                reason: !times.length ? 'no times' : 'no shaderLayer',
+                mode,
+                rebuildId,
+                timesLen: times.length,
+            });
+            return;
+        }
+
+        // Number(null) === 0, which is falsy and causes _loadGridData to return null immediately
+        // (the core guards with `if (!mrmsTimestamp) return null`). Treat null as NaN so that
+        // primaryTimeForRebuild falls through to times[0] — the first real MRMS timestamp.
+        const _rawFrameTime = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
+        const currentFrameTime = _rawFrameTime == null ? NaN : Number(_rawFrameTime);
+        /** When the active timestep is unset/NaN, paint the first timeline step (legacy single-fetch behavior). */
+        let primaryTimeForRebuild = Number.NaN;
+        if (mode === 'rebuild') {
+            primaryTimeForRebuild = Number.isFinite(currentFrameTime)
+                ? currentFrameTime
+                : times[0];
+        }
+        const tsKey = state.isMRMS ? 'mrmsTimestamp' : 'forecastHour';
+        const gridModel = state.isMRMS ? 'mrms' : state.model;
+        const { gridDef } = this.core._getGridCornersAndDef(gridModel);
+
+        this._debugLog('_runParallelGridFrameLoads', {
+            mode,
+            rebuildId,
+            gridModel,
+            timesLen: times.length,
+            timesSummary: _debugSummarizeNumericSeries(times),
+            currentFrameTime,
+            primaryTimeForRebuild:
+                mode === 'rebuild'
+                    ? Number.isFinite(currentFrameTime)
+                        ? currentFrameTime
+                        : times[0]
+                    : undefined,
+            tsKey,
+            gridNxNy: gridDef?.grid_params
+                ? { nx: gridDef.grid_params.nx, ny: gridDef.grid_params.ny }
+                : null,
+        });
+
+        times.forEach((time) => {
+            const stateForTime = { ...state, [tsKey]: time };
+            this.core._loadGridData(stateForTime)
+                .then((grid) => {
+                    if (rebuildId !== this.currentRebuildId || !this.shaderLayer) {
+                        return;
+                    }
+
+                    const isPrimaryFrame =
+                        mode === 'rebuild' &&
+                        Number.isFinite(primaryTimeForRebuild) &&
+                        time === primaryTimeForRebuild;
+
+                    if (isPrimaryFrame) {
+                        // Drift guard: when the rebuild started with an explicit target timestamp
+                        // (mrmsTimestamp / forecastHour was non-null at rebuild time) and the user
+                        // navigated to a different time while loading, skip applying the now-stale
+                        // primary frame. When _rebuildTargetTimeKey is null it means there was no
+                        // explicit timestamp at rebuild time (e.g. first MRMS load where
+                        // mrmsTimestamp starts as null); in that case we must always apply the
+                        // primary frame — skipping it leaves currentLoadedTimeKey null forever.
+                        if (this._rebuildTargetTimeKey !== null) {
+                            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._debugLog('_loadGridData:skip primary (core time drifted vs rebuild target)', {
+                                    time,
+                                    coreTimeKey,
+                                    _rebuildTargetTimeKey: this._rebuildTargetTimeKey,
+                                    rebuildId,
+                                });
+                                return;
+                            }
+                        }
+                        if (!grid?.data) {
+                            this._debugLog('_loadGridData:primary frame missing grid.data', {
+                                time,
+                                rebuildId,
+                                mode,
+                            });
+                            this._initialGridLoadPending = false;
+                            return;
+                        }
+                        this.shaderLayer.updateDataTexture(
+                            grid.data,
+                            grid.encoding,
+                            gridDef.grid_params.nx,
+                            gridDef.grid_params.ny,
+                        );
+                        this.currentLoadedTimeKey = time;
+                        this.shaderLayer.registerCurrentDataTextureAsPreloaded(time);
+                        this._initialGridLoadPending = false;
+                        this.map.triggerRepaint();
+                        return;
+                    }
+
+                    if (grid?.data) {
+                        this.shaderLayer.storePreloadedTexture(
+                            time,
+                            grid.data,
+                            grid.encoding,
+                            gridDef.grid_params.nx,
+                            gridDef.grid_params.ny,
+                        );
+                        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();
+                        }
+                    } else if (this._debug && mode === 'append') {
+                        this._debugLog('_loadGridData:empty grid (append)', { time, mode, rebuildId });
+                    }
+                })
+                .catch((err) => {
+                    this._debugLog('_loadGridData:error', {
+                        time,
+                        mode,
+                        rebuildId,
+                        message: err?.message || String(err),
+                    });
+                    if (
+                        mode === 'rebuild' &&
+                        Number.isFinite(primaryTimeForRebuild) &&
+                        time === primaryTimeForRebuild
+                    ) {
+                        this._initialGridLoadPending = false;
+                    }
+                });
+        });
+    }
+
+    _rebuildLayerAndPreload(state) {
+        if (state.isSatellite) {
+            return;
+        }
+        if (!state.variable) {
+            return;
+        }
+
+        const rebuildId = ++this.currentRebuildId;
+
+        this.core.cancelAllRequests();
+
+        if (this.shaderLayer) {
+            this.map.removeLayer(this.shaderLayer.id);
+            this.shaderLayer = null;
+        }
+        this.currentLoadedTimeKey = null;
+
+        if (
+            !state.isMRMS &&
+            state.forecastHour === 0 &&
+            state.variable === 'ptypeRefl' &&
+            state.model === 'hrrr'
+        ) {
+            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;
+            }
+        }
+
+        if (rebuildId !== this.currentRebuildId) return;
+
+        const runKey = `${state.model}-${state.date}-${state.run}-${state.variable}`;
+
+        this.shaderLayer = new GridRenderLayer(this.layerId);
+        this.shaderLayer.runKey = runKey;
+        const beforeId = this._weatherInsertBeforeId();
+        if (beforeId) {
+            this.map.addLayer(this.shaderLayer, beforeId);
+        } else {
+            this.map.addLayer(this.shaderLayer);
+        }
+        this._updateLayerStyle(state);
+
+        this._rebuildTargetTimeKey = state.isMRMS
+            ? (state.mrmsTimestamp == null ? null : Number(state.mrmsTimestamp))
+            : Number(state.forecastHour);
+        this._initialGridLoadPending = true;
+
+        const normalized = this._collectNormalizedTimelineSteps(state);
+        // Same null-guard as in _runParallelGridFrameLoads: Number(null) === 0, which is a finite
+        // value that would inject Unix epoch into timesToLoad and mis-identify the primary frame.
+        const _rawCft = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
+        const currentFrameTime = _rawCft == null ? NaN : Number(_rawCft);
+        const timesSet = new Set(normalized);
+        if (!Number.isNaN(currentFrameTime)) {
+            timesSet.add(currentFrameTime);
+        }
+        let timesToLoad = [...timesSet];
+        if (timesToLoad.length === 0 && !Number.isNaN(currentFrameTime)) {
+            timesToLoad = [currentFrameTime];
+        }
+        this._debugLog('_rebuildLayerAndPreload:timeline', {
+            rebuildId,
+            isMRMS: state.isMRMS,
+            variable: state.variable,
+            normalizedLen: normalized.length,
+            normalizedSummary: _debugSummarizeNumericSeries(normalized),
+            currentFrameTime,
+            timesToLoadLen: timesToLoad.length,
+            timesToLoadSummary: _debugSummarizeNumericSeries(timesToLoad),
+            insertBeforeId: beforeId ?? '(stack top)',
+        });
+        if (timesToLoad.length === 0) {
+            this._initialGridLoadPending = false;
+            this._debugLog('_rebuildLayerAndPreload:no times to load — check availableTimestamps / duration window', {
+                rebuildId,
+                availableTimestampsLen: Array.isArray(state.availableTimestamps)
+                    ? state.availableTimestamps.length
+                    : 0,
+                mrmsDurationValue: state.mrmsDurationValue,
+            });
+            return;
+        }
+
+        if (rebuildId === this.currentRebuildId) {
+            this._runParallelGridFrameLoads(state, timesToLoad, { rebuildId, mode: 'rebuild' });
+        }
+    }
+
+    _preloadAllTimeSteps(state) {
+        const normalized = this._collectNormalizedTimelineSteps(state);
+        const _rawPft = state.isMRMS ? state.mrmsTimestamp : state.forecastHour;
+        const currentFrameTime = _rawPft == null ? NaN : Number(_rawPft);
+        const stepsToPreload = normalized.filter(t => t !== currentFrameTime);
+
+        this._debugLog('_preloadAllTimeSteps', {
+            normalizedLen: normalized.length,
+            currentFrameTime,
+            stepsToPreloadLen: stepsToPreload.length,
+            stepsSummary: _debugSummarizeNumericSeries(stepsToPreload),
+        });
+
+        if (normalized.length === 0) {
+            return;
+        }
+
+        if (stepsToPreload.length === 0) {
+            this._debugLog('_preloadAllTimeSteps:skip (nothing to preload besides current)', {
+                currentFrameTime,
+            });
+            return;
+        }
+
+        const capturedRebuildId = this.currentRebuildId;
+        this._runParallelGridFrameLoads(state, stepsToPreload, { rebuildId: capturedRebuildId, mode: 'append' });
+    }
+
+    _updateLayerData(state) {
+        return this._updateLayerDataWithToken(state);
+    }
+
+    _updateLayerStyle(state) {
+        if (!this.shaderLayer || !state.variable) return;
+
+        const gridModel = state.isMRMS ? 'mrms' : state.model;
+        const geometry = this.core._getGridCornersAndDef(gridModel);
+        if (!geometry) {
+            return;
+        }
+
+        const { corners, gridDef } = geometry;
+        const { colormap, baseUnit } = this.core._getColormapForVariable(state.variable);
+        const toUnit = this.core._getTargetUnit(baseUnit, state.units);
+
+        const finalColormap = this.core._convertColormapUnits(colormap, baseUnit, toUnit);
+        
+        let dataRange;
+        if (state.variable === 'ptypeRefl' || state.variable === 'ptypeRate') {
+            if (state.isMRMS) {
+                dataRange = [5, 380];
+            } else {
+                dataRange = [5, 380];
+            }
+        } else {
+            dataRange = [finalColormap[0], finalColormap[finalColormap.length - 2]];
+        }
+        
+        const dataNativeUnit = (DICTIONARIES.fld[state.variable] || {}).defaultUnit || 'none';
+
+        this.shaderLayer.updateGeometry(corners, gridDef);
+        this.shaderLayer.updateColormapTexture(finalColormap);
+        this.shaderLayer.updateStyle({ opacity: state.opacity, dataRange });
+        this.shaderLayer.setUnitConversion(dataNativeUnit, state.units);
+        this.shaderLayer.setVariable(state.variable);
+        this.shaderLayer.setIsMRMS(state.isMRMS); // NEW
+    }
+    
+    /**
+     * Handles the map's mousemove event by delegating calculations to the core.
+     * @param {object} e - The Mapbox GL mouse event object.
+     * @private
+     */
+    async _handleMouseMove(e) {
+        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);
+
+        if (payload) {
+            this.emit('data:inspect', {
+                ...payload,
+                point: e.point,
+            });
+        } else {
+            this.emit('data:inspect', null);
+        }
+    }
+
+    /**
+     * Enables or disables automatic checking for new weather data for both models and MRMS.
+     * When enabled, it periodically checks for and displays the latest available data.
+     * @param {boolean} enabled - Whether to enable or disable auto-refresh.
+     * @param {number} [intervalSeconds] - The interval in seconds to check for new data. Defaults to the value from constructor options or 30.
+     */
+    setAutoRefresh(enabled, intervalSeconds) {
+        // Stop any existing refresh interval
+        if (this.autoRefreshIntervalId) {
+            clearInterval(this.autoRefreshIntervalId);
+            this.autoRefreshIntervalId = null;
+        }
+
+        // Store the new state
+        this.autoRefreshEnabled = enabled;
+        if (typeof intervalSeconds === 'number' && intervalSeconds > 0) {
+            this.autoRefreshIntervalSeconds = intervalSeconds;
+        }
+
+        if (this.autoRefreshEnabled) {
+            const intervalMilliseconds = this.autoRefreshIntervalSeconds * 1000;
+            // Run the check immediately once, then start the interval
+            this._checkForUpdates(); 
+            this.autoRefreshIntervalId = setInterval(() => this._checkForUpdates(), intervalMilliseconds);
+        }
+    }
+
+    /**
+     * Manually triggers a check for new weather data.
+     * This performs the same action as a single auto-refresh cycle, updating the
+     * timeline and preloading new data in the background without changing the user's view.
+     * @returns {Promise<void>}
+     */
+    async refreshData() {
+        await this._checkForUpdates();
+    }
+
+    /**
+     * Checks for new data, updates the timeline, and proactively preloads the data for
+     * any new time steps in the background.
+     * @private
+     */
+    async _checkForUpdates() {
+        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] || []);
+
+            // 1. Fetch the absolute latest status
+            const mrmsStatus = await this.core.fetchMRMSStatus(true);
+            const newTimestamps = mrmsStatus?.[currentVariable] || [];
+            if (newTimestamps.length === 0) return;
+
+            // 2. Identify exactly which timestamps are new
+            const newTimestampsToPreload = newTimestamps.filter(ts => !oldTimestamps.has(ts));
+
+            if (newTimestampsToPreload.length > 0) {
+                // 3. Update the core's internal status and emit the change to update the UI (slider)
+                this.core.mrmsStatus = mrmsStatus; 
+                this.core._emitStateChange();
+
+                // 4. Proactively fetch the data for each new timestamp in the background.
+                newTimestampsToPreload.forEach(timestamp => {
+                    const stateForPreload = { ...this.core.state, mrmsTimestamp: timestamp };
+                    this.core._loadGridData(stateForPreload)
+                        .catch(() => {});
+                });
+
+                // 5. Clean up the cache for any timestamps that are no longer available.
+                const newTimestampsSet = new Set(newTimestamps);
+                oldTimestamps.forEach(oldTs => {
+                    if (!newTimestampsSet.has(oldTs)) {
+                        const cacheKey = `mrms-${oldTs}-${currentVariable}-0`;
+                        this.core.dataCache.delete(cacheKey);
+                    }
+                });
+
+                this.emit('data:updated', { type: 'mrms', variable: currentVariable, newTimestamps: newTimestampsToPreload });
+            }
+        } else {
+            const previousStatus = this.core.modelStatus;
+            const modelStatus = await this.core.fetchModelStatus(true);
+            
+            // 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;
+
+            const currentRunKey = `${date}:${run}`;
+            const latestRunKey = `${latestRun.date}:${latestRun.run}`;
+
+            if (latestRunKey > currentRunKey) {
+                this.emit('data:updated', { type: 'model', model: currentModel, newRun: latestRunKey });
+            }
+        }
+    }
+
+    /**
+     * Cleans up all resources.
+     */
+    destroy() {
+        this._debugLog('destroy');
+        this.setAutoRefresh(false);
+        
+        // 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
+            if (this.map.getLayer(this.shaderLayer.id)) {
+                this.map.removeLayer(this.shaderLayer.id);
+            }
+            
+            // Manually call the layer's own cleanup method as a safeguard.
+            // This guarantees the release of WebGL resources (textures, buffers).
+            this.shaderLayer.onRemove();
+            
+            // Nullify the reference to the custom layer object
+            this.shaderLayer = null;
+        }
+
+        // 3. Tell the core engine to destroy its own resources (cache, workers, etc.)
+        this.core.destroy();
+        
+        // 4. Clear any remaining internal state
+        this.currentLoadedTimeKey = null;
+    }
 }