@aguacerowx/mapsgl 0.0.53 → 0.0.54

package/src/NexradWeatherController.js

@@ -1,510 +1,510 @@
-/**
- * Connects AguaceroCore NEXRAD state to MapboxRadarLayer + archive fetch (aguacero-frontend parity).
- * Preloads all timestamps on the active timeline (MRMS/satellite-style) so scrubbing does not trigger loads.
- */
-import { getUnitConversionFunction, getDefaultRadarTilt } from '@aguacerowx/javascript-sdk';
-import { fetchAndParseArchive, objectKeyToUrl, setNexradArchiveApiKey } from './nexrad/radarArchiveCore.bundled.js';
-import { MapboxRadarLayer } from './nexrad/MapboxRadarLayer.bundled.js';
-import { nexradBinGroupIdForKey, variableToNexradGroup } from '@aguacerowx/javascript-sdk';
-import { sampleNexradFrameAtLatLon } from './nexrad/nexradCrossSectionSampleAtLatLon.bundled.js';
-import { prepareRadarFrameForGpuReadout } from './nexrad/radarFrameGpuMatch.bundled.js';
-import { mapboxFrameUploadOptionsForNexradState } from './nexrad/nexradMapboxFrameOpts.bundled.js';
-
-function pickNearestLevel3ObjectKey(unixTime, timeToKeyMap, maxDeltaSec = 600) {
-    const direct = timeToKeyMap[String(unixTime)];
-    if (direct) return direct;
-    const entries = Object.entries(timeToKeyMap || {});
-    if (entries.length === 0) return null;
-    let bestKey = null;
-    let bestDelta = Infinity;
-    for (const [tStr, key] of entries) {
-        const t = Number(tStr);
-        if (!Number.isFinite(t)) continue;
-        const d = Math.abs(t - unixTime);
-        if (d < bestDelta) {
-            bestDelta = d;
-            bestKey = key;
-        }
-    }
-    if (bestKey == null) return null;
-    if (bestDelta > maxDeltaSec && Number.isFinite(maxDeltaSec)) return null;
-    return bestKey;
-}
-
-function isVelocityStyleRadarVar(radarVariable) {
-    return radarVariable === 'VEL' || radarVariable === 'SW' || radarVariable === 'N0G' || radarVariable === 'N0W';
-}
-
-function velocityRangeToMs(rangeMin, rangeMax, displayUnit) {
-    if (rangeMin == null || rangeMax == null || !displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') {
-        return [rangeMin, rangeMax];
-    }
-    const toMs = getUnitConversionFunction(displayUnit, 'm/s', 'nexrad_vel');
-    if (!toMs) return [rangeMin, rangeMax];
-    return [toMs(rangeMin), toMs(rangeMax)];
-}
-
-function colormapToMs(colormap, radarVariable, displayUnit) {
-    if (!colormap || !Array.isArray(colormap) || colormap.length < 2) return colormap;
-    if (!isVelocityStyleRadarVar(radarVariable)) return colormap;
-    if (!displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') return colormap;
-    const toMs = getUnitConversionFunction(
-        displayUnit,
-        'm/s',
-        radarVariable === 'SW' || radarVariable === 'N0W' ? 'nexrad_sw' : 'nexrad_vel',
-    );
-    if (!toMs) return colormap;
-    const out = [...colormap];
-    for (let i = 0; i < out.length; i += 2) {
-        const v = out[i];
-        if (typeof v === 'number' && Number.isFinite(v)) out[i] = toMs(v);
-    }
-    return out;
-}
-
-function radarShaderValueRange(rangeMin, rangeMax, radarVariable, units, nexradDataSource) {
-    const v = (radarVariable || '').toUpperCase();
-    if (isVelocityStyleRadarVar(v)) {
-        const [vmin, vmax] = velocityRangeToMs(rangeMin, rangeMax, units);
-        return [vmin ?? 0, vmax ?? 80];
-    }
-    if (nexradDataSource === 'level3' && (v === 'N0H' || v === 'HHC')) {
-        const lo = rangeMin ?? 0;
-        let hi = rangeMax ?? 11;
-        if (hi > 11) hi = 11;
-        if (hi < lo) hi = lo;
-        return [lo, hi];
-    }
-    if (v === 'KDP') {
-        const lo = rangeMin ?? -2;
-        let hi = rangeMax ?? 8;
-        if (hi < lo) hi = lo;
-        return [lo, hi];
-    }
-    return [rangeMin ?? 0, rangeMax ?? 80];
-}
-
-/** Level-III digital / hybrid hydrometeor classification (aguacero-frontend `nexradLevel3IsHydrometeorClassification`). */
-function nexradLevel3IsHydrometeorClassification(radarVariable) {
-    const v = (radarVariable || '').toUpperCase();
-    return v === 'N0H' || v === 'HHC';
-}
-
-/** NWS class labels for digital HC (indices 0–11). */
-const NEXRAD_HYDROMETEOR_CLASS_LABELS = [
-    'Biological',
-    'Ground clutter',
-    'Ice crystals',
-    'Dry snow',
-    'Wet snow',
-    'Light rain',
-    'Heavy rain',
-    'Big drops',
-    'Graupel',
-    'Hail/rain',
-    'Large hail',
-    'Giant hail',
-];
-
-function nexradHydrometeorLabelForClassIndex(value) {
-    const idx = Math.round(Number(value));
-    if (idx >= 12) return null;
-    if (idx >= 0 && idx < NEXRAD_HYDROMETEOR_CLASS_LABELS.length) {
-        return NEXRAD_HYDROMETEOR_CLASS_LABELS[idx];
-    }
-    return `Class ${idx}`;
-}
-
-function velocityMsToDisplay(valueMs, displayUnit) {
-    if (!displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') {
-        return valueMs;
-    }
-    const fromMs = getUnitConversionFunction('m/s', displayUnit, 'nexrad_vel');
-    return fromMs ? fromMs(valueMs) : valueMs;
-}
-
-/** Standard 4/3-earth beam height (km AGL at antenna) from slant range and elevation — matches frontend `beamHeightKm`. */
-function beamHeightKm(slantRangeKm, elevDeg) {
-    const el = (elevDeg * Math.PI) / 180;
-    const ReKm = (6371000 * 4) / (3 * 1000);
-    const cosEl = Math.max(Math.cos(el), 0.05);
-    const s = slantRangeKm / cosEl;
-    return Math.sqrt(s * s + ReKm * ReKm + 2 * s * ReKm * Math.sin(el)) - ReKm;
-}
-
-function formatNexradInspectNumeric(raw, radarVariable) {
-    const vu = (radarVariable || '').toUpperCase();
-    const vl = radarVariable || '';
-    if (vu.includes('RATE') || vl.toLowerCase().includes('rate')) {
-        return Number(raw.toFixed(3).replace(/\.?0+$/, ''));
-    }
-    if (vu === 'RHO' || vu === 'ZDR' || vl.includes('RhoHV') || vl.includes('Zdr')) {
-        return Number(raw.toFixed(2));
-    }
-    if (Math.abs(raw) < 10) return Number(raw.toFixed(1));
-    return Math.round(raw);
-}
-
-const PRELOAD_CONCURRENCY = 4;
-
-export class NexradWeatherController {
-    constructor(map, core, options = {}) {
-        this.map = map;
-        this.core = core;
-        this.layerId = options.nexradLayerId || 'aguacero-nexrad-layer';
-        this.mapboxLayer = null;
-        /** Includes tilt/timestamp so elevation changes always re-upload (see {@link _syncIdentity}). */
-        this._lastSyncKey = null;
-        this._abort = null;
-        this._interpolateColormap = options.interpolateNexradColormap !== false;
-        this._gateSmoothing = options.nexradGateSmoothing === true;
-        /** Decoded radar frames keyed by fetchKey from _buildFetchParamsForUnix. */
-        this._frameCache = new Map();
-        this._preloadAbort = null;
-        this._preloadTimelineSig = null;
-        /** @type {(() => string | undefined) | null} */
-        this._getInsertBeforeLayerId = options.getInsertBeforeLayerId || null;
-    }
-
-    destroy() {
-        this._abort?.abort();
-        this._abort = null;
-        this._preloadAbort?.abort();
-        this._preloadAbort = null;
-        this._frameCache.clear();
-        this._preloadTimelineSig = null;
-        if (this.mapboxLayer && this.map.getLayer(this.mapboxLayer.id)) {
-            this.map.removeLayer(this.mapboxLayer.id);
-        }
-        this.mapboxLayer = null;
-        this._lastSyncKey = null;
-    }
-
-    _resolveListingContext(state) {
-        const nk = this.core._nexradTimesCacheKey?.();
-        const ent = nk ? this.core.nexradTimesByStation?.[nk] : null;
-        const timeToKeyMap = state.nexradTimeToKeyMap || ent?.timeToKeyMap || {};
-        const motionMap = state.nexradLevel3MotionTimeToKeyMap || ent?.level3MotionTimeToKeyMap || {};
-        return { nk, ent, timeToKeyMap, motionMap };
-    }
-
-    /**
-     * @param {object} state
-     * @param {number} unix
-     * @returns {{ objectKey: string, url: string, fetchKey: string, motionObjectKey: string | null, radarVar: string, radarSource: string, groupId: number } | null}
-     */
-    _buildFetchParamsForUnix(state, unix) {
-        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
-        const radarSource = state.nexradDataSource === 'level3' ? 'level3' : 'level2';
-        const groupId = nexradBinGroupIdForKey(variableToNexradGroup(radarVar));
-        const { timeToKeyMap, motionMap } = this._resolveListingContext(state);
-        const objectKey = timeToKeyMap[String(unix)];
-        if (!objectKey) return null;
-
-        let motionObjectKey = null;
-        if (radarVar === 'VEL' && state.nexradStormRelative) {
-            motionObjectKey = pickNearestLevel3ObjectKey(unix, motionMap);
-        }
-
-        const url = objectKeyToUrl(objectKey, radarSource);
-        const fetchKey = `${url}|${radarVar}|${radarSource}|${motionObjectKey || ''}`;
-        return { objectKey, url, fetchKey, motionObjectKey, radarVar, radarSource, groupId };
-    }
-
-    async _fetchFrame(state, unix, { signal, priority }) {
-        const p = this._buildFetchParamsForUnix(state, unix);
-        if (!p) return null;
-        return fetchAndParseArchive(p.url, p.objectKey, p.radarVar, p.groupId, p.radarSource, {
-            signal,
-            priority,
-            level3MotionObjectKey: p.motionObjectKey,
-        });
-    }
-
-    _preloadTimelineSignature(state) {
-        const nk = this.core._nexradTimesCacheKey?.() || '';
-        const ts = [...(state.availableNexradTimestamps || [])]
-            .map(Number)
-            .filter((t) => Number.isFinite(t))
-            .sort((a, b) => a - b)
-            .join(',');
-        const tilt =
-            state.nexradTilt != null && Number.isFinite(Number(state.nexradTilt))
-                ? Number(state.nexradTilt).toFixed(3)
-                : '';
-        return `${nk}|${ts}|sr:${state.nexradStormRelative ? 1 : 0}|tilt:${tilt}`;
-    }
-
-    /**
-     * Identity for whether the visible radar frame + upload options match (tilt affects L3 mesh keys and listing object paths).
-     * @param {object} state
-     * @param {{ fetchKey: string }} p
-     * @param {number} unix
-     */
-    _syncIdentity(state, p, unix) {
-        const tilt =
-            state.nexradTilt != null && Number.isFinite(Number(state.nexradTilt))
-                ? Number(state.nexradTilt).toFixed(3)
-                : '';
-        return `${p.fetchKey}|tilt:${tilt}|u:${unix}`;
-    }
-
-    /**
-     * Background-load every volume on the slider timeline (like satellite KTX2 preload).
-     * Slider / `nexradTimestamp` changes only swap GPU buffers from cache when possible.
-     * @param {object} state
-     */
-    preloadAllAvailable(state) {
-        if (!state.isNexrad || !state.nexradSite) return;
-
-        const sig = this._preloadTimelineSignature(state);
-        if (sig === this._preloadTimelineSig) return;
-
-        this._preloadTimelineSig = sig;
-        this._preloadAbort?.abort();
-        this._preloadAbort = new AbortController();
-        const signal = this._preloadAbort.signal;
-
-        this._frameCache.clear();
-
-        setNexradArchiveApiKey(this.core.apiKey || '');
-
-        const times = [...(state.availableNexradTimestamps || [])]
-            .map(Number)
-            .filter((t) => Number.isFinite(t));
-        if (!times.length) return;
-
-        const snapshot = { ...state };
-
-        const run = async () => {
-            let cursor = 0;
-            const work = async () => {
-                while (cursor < times.length && !signal.aborted) {
-                    const i = cursor++;
-                    const unix = times[i];
-                    const p = this._buildFetchParamsForUnix(snapshot, unix);
-                    if (!p || signal.aborted) continue;
-                    if (this._frameCache.has(p.fetchKey)) continue;
-                    try {
-                        const frame = await this._fetchFrame(snapshot, unix, {
-                            signal,
-                            priority: 'prefetch',
-                        });
-                        if (frame && !signal.aborted) {
-                            this._frameCache.set(p.fetchKey, frame);
-                        }
-                    } catch {
-                        /* ignore failed preload tiles */
-                    }
-                }
-            };
-            await Promise.all(Array.from({ length: PRELOAD_CONCURRENCY }, () => work()));
-        };
-
-        void run();
-    }
-
-    _ensureLayer() {
-        if (this.mapboxLayer) return;
-        this.mapboxLayer = new MapboxRadarLayer(this.layerId);
-        let beforeId =
-            typeof this._getInsertBeforeLayerId === 'function'
-                ? this._getInsertBeforeLayerId()
-                : undefined;
-        if (!beforeId && this.map.getLayer('AML_-_terrain')) {
-            beforeId = 'AML_-_terrain';
-        }
-        if (beforeId) {
-            this.map.addLayer(this.mapboxLayer, beforeId);
-        } else {
-            this.map.addLayer(this.mapboxLayer);
-        }
-    }
-
-    _uploadFrame(state, frame) {
-        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
-        this.mapboxLayer.setInterpolateColormap(this._interpolateColormap);
-        this.mapboxLayer.setGateSmoothing(this._gateSmoothing);
-
-        const colormapFlat = state.colormap;
-        const colormapForShader = colormapToMs(colormapFlat, radarVar, state.units);
-        const [shaderMin, shaderMax] = radarShaderValueRange(
-            colormapFlat?.[0],
-            colormapFlat?.[colormapFlat.length - 2],
-            radarVar,
-            state.units,
-            state.nexradDataSource,
-        );
-
-        this.mapboxLayer.setColormap(colormapForShader);
-        this.mapboxLayer.setValueRange(shaderMin, shaderMax);
-        this.mapboxLayer.setOpacity(state.opacity ?? 1);
-        this.mapboxLayer.setFrameData(frame, mapboxFrameUploadOptionsForNexradState(state));
-        this.map.triggerRepaint();
-    }
-
-    /**
-     * @param {object} state - core state + emitted colormap (from state:change)
-     */
-    async sync(state) {
-        if (!state.isNexrad || !state.nexradSite || state.nexradTimestamp == null) {
-            this.destroy();
-            return;
-        }
-
-        setNexradArchiveApiKey(this.core.apiKey || '');
-
-        const unix = Number(state.nexradTimestamp);
-        const p = this._buildFetchParamsForUnix(state, unix);
-        if (!p) {
-            return;
-        }
-
-        const syncKey = this._syncIdentity(state, p, unix);
-        if (syncKey === this._lastSyncKey && this.mapboxLayer) {
-            this._applyStyle(state);
-            return;
-        }
-
-        const cached = this._frameCache.get(p.fetchKey);
-        if (cached) {
-            this._ensureLayer();
-            this._uploadFrame(state, cached);
-            this._lastSyncKey = syncKey;
-            return;
-        }
-
-        this._abort?.abort();
-        this._abort = new AbortController();
-
-        let frame;
-        try {
-            frame = await this._fetchFrame(state, unix, {
-                signal: this._abort.signal,
-                priority: 'display',
-            });
-        } catch {
-            return;
-        }
-
-        if (!frame || this._abort.signal.aborted) return;
-
-        this._frameCache.set(p.fetchKey, frame);
-
-        this._ensureLayer();
-        this._uploadFrame(state, frame);
-        this._lastSyncKey = syncKey;
-    }
-
-    _applyStyle(state) {
-        if (!this.mapboxLayer) return;
-        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
-        const colormapFlat = state.colormap;
-        const colormapForShader = colormapToMs(colormapFlat, radarVar, state.units);
-        const [shaderMin, shaderMax] = radarShaderValueRange(
-            colormapFlat?.[0],
-            colormapFlat?.[colormapFlat.length - 2],
-            radarVar,
-            state.units,
-            state.nexradDataSource,
-        );
-        this.mapboxLayer.setColormap(colormapForShader);
-        this.mapboxLayer.setValueRange(shaderMin, shaderMax);
-        this.mapboxLayer.setOpacity(state.opacity ?? 1);
-        this.map.triggerRepaint();
-    }
-
-    /**
-     * Mouse readout at lng/lat — same sampling and formatting as aguacero-frontend `NexradReadoutFrame`
-     * (polar sample + velocity/hydro/range checks). Uses the cached frame for the current timeline key.
-     *
-     * @param {number} lng
-     * @param {number} lat
-     * @param {object} state - Latest `state:change` payload (needs `colormap`, NEXRAD fields).
-     * @returns {object | null}
-     */
-    getInspectPayload(lng, lat, state) {
-        if (!state?.isNexrad || !state.nexradSite || state.nexradTimestamp == null) return null;
-        if (state.visible === false || (state.opacity ?? 1) <= 0) return null;
-
-        const unix = Number(state.nexradTimestamp);
-        const p = this._buildFetchParamsForUnix(state, unix);
-        if (!p) return null;
-
-        const frame = this._frameCache.get(p.fetchKey);
-        if (!frame) return null;
-
-        const colormapFlat = state.colormap;
-        if (!colormapFlat || colormapFlat.length < 2) return null;
-
-        const rangeMin = colormapFlat[0];
-        const rangeMax = colormapFlat[colormapFlat.length - 2];
-
-        const radarVariable = (state.nexradProduct || 'REF').toUpperCase();
-        const radarSource = state.nexradDataSource === 'level3' ? 'level3' : 'level2';
-        const displayUnits =
-            state.units && String(state.units).toLowerCase() !== 'none'
-                ? state.units
-                : isVelocityStyleRadarVar(radarVariable)
-                  ? 'm/s'
-                  : '';
-
-        const gpuFrame = prepareRadarFrameForGpuReadout(frame, mapboxFrameUploadOptionsForNexradState(state));
-        const sample = sampleNexradFrameAtLatLon(gpuFrame, lat, lng, { smoothPolar: this._gateSmoothing });
-        if (!sample) return null;
-
-        const valueMs = sample.value;
-        const isHydro = radarSource === 'level3' && nexradLevel3IsHydrometeorClassification(radarVariable);
-
-        /** @type {number | string} */
-        let valueOut;
-        let unitOut = displayUnits || '';
-
-        if (isVelocityStyleRadarVar(radarVariable)) {
-            valueOut = velocityMsToDisplay(valueMs, displayUnits);
-        } else if (isHydro) {
-            const label = nexradHydrometeorLabelForClassIndex(valueMs);
-            if (label == null) return null;
-            valueOut = label;
-            unitOut = '';
-        } else {
-            valueOut = formatNexradInspectNumeric(valueMs, radarVariable);
-        }
-
-        let inRange;
-        if (isHydro) {
-            const idx = Math.round(Number(valueMs));
-            inRange =
-                (rangeMin == null || idx >= rangeMin) && (rangeMax == null || idx <= rangeMax);
-        } else if (isVelocityStyleRadarVar(radarVariable)) {
-            inRange =
-                (rangeMin == null || valueOut >= rangeMin) && (rangeMax == null || valueOut <= rangeMax);
-        } else {
-            inRange =
-                (rangeMin == null || valueOut >= rangeMin) && (rangeMax == null || valueOut <= rangeMax);
-        }
-
-        if (!inRange) return null;
-
-        const tiltDeg = Number.isFinite(state.nexradTilt) ? state.nexradTilt : getDefaultRadarTilt(state.nexradSite);
-        const bhKm = beamHeightKm(sample.groundRangeKm, tiltDeg);
-        const metric = state.units === 'metric';
-        const beamHeightDisplay = metric ? bhKm : bhKm * 3.280839895013123;
-        const beamUnit = metric ? 'km' : 'kft';
-
-        const fldKey = state.variable;
-        return {
-            lngLat: { lng, lat },
-            variable: {
-                code: fldKey,
-                name: this.core.getVariableDisplayName(fldKey),
-            },
-            value: valueOut,
-            unit: unitOut,
-            beamHeight:
-                Number.isFinite(beamHeightDisplay) && Number.isFinite(bhKm)
-                    ? { value: beamHeightDisplay, unit: beamUnit }
-                    : null,
-        };
-    }
-}
+/**
+ * Connects AguaceroCore NEXRAD state to MapboxRadarLayer + archive fetch (aguacero-frontend parity).
+ * Preloads all timestamps on the active timeline (MRMS/satellite-style) so scrubbing does not trigger loads.
+ */
+import { getUnitConversionFunction, getDefaultRadarTilt } from '@aguacerowx/javascript-sdk';
+import { fetchAndParseArchive, objectKeyToUrl, setNexradArchiveApiKey } from './nexrad/radarArchiveCore.bundled.js';
+import { MapboxRadarLayer } from './nexrad/MapboxRadarLayer.bundled.js';
+import { nexradBinGroupIdForKey, variableToNexradGroup } from '@aguacerowx/javascript-sdk';
+import { sampleNexradFrameAtLatLon } from './nexrad/nexradCrossSectionSampleAtLatLon.bundled.js';
+import { prepareRadarFrameForGpuReadout } from './nexrad/radarFrameGpuMatch.bundled.js';
+import { mapboxFrameUploadOptionsForNexradState } from './nexrad/nexradMapboxFrameOpts.bundled.js';
+
+function pickNearestLevel3ObjectKey(unixTime, timeToKeyMap, maxDeltaSec = 600) {
+    const direct = timeToKeyMap[String(unixTime)];
+    if (direct) return direct;
+    const entries = Object.entries(timeToKeyMap || {});
+    if (entries.length === 0) return null;
+    let bestKey = null;
+    let bestDelta = Infinity;
+    for (const [tStr, key] of entries) {
+        const t = Number(tStr);
+        if (!Number.isFinite(t)) continue;
+        const d = Math.abs(t - unixTime);
+        if (d < bestDelta) {
+            bestDelta = d;
+            bestKey = key;
+        }
+    }
+    if (bestKey == null) return null;
+    if (bestDelta > maxDeltaSec && Number.isFinite(maxDeltaSec)) return null;
+    return bestKey;
+}
+
+function isVelocityStyleRadarVar(radarVariable) {
+    return radarVariable === 'VEL' || radarVariable === 'SW' || radarVariable === 'N0G' || radarVariable === 'N0W';
+}
+
+function velocityRangeToMs(rangeMin, rangeMax, displayUnit) {
+    if (rangeMin == null || rangeMax == null || !displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') {
+        return [rangeMin, rangeMax];
+    }
+    const toMs = getUnitConversionFunction(displayUnit, 'm/s', 'nexrad_vel');
+    if (!toMs) return [rangeMin, rangeMax];
+    return [toMs(rangeMin), toMs(rangeMax)];
+}
+
+function colormapToMs(colormap, radarVariable, displayUnit) {
+    if (!colormap || !Array.isArray(colormap) || colormap.length < 2) return colormap;
+    if (!isVelocityStyleRadarVar(radarVariable)) return colormap;
+    if (!displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') return colormap;
+    const toMs = getUnitConversionFunction(
+        displayUnit,
+        'm/s',
+        radarVariable === 'SW' || radarVariable === 'N0W' ? 'nexrad_sw' : 'nexrad_vel',
+    );
+    if (!toMs) return colormap;
+    const out = [...colormap];
+    for (let i = 0; i < out.length; i += 2) {
+        const v = out[i];
+        if (typeof v === 'number' && Number.isFinite(v)) out[i] = toMs(v);
+    }
+    return out;
+}
+
+function radarShaderValueRange(rangeMin, rangeMax, radarVariable, units, nexradDataSource) {
+    const v = (radarVariable || '').toUpperCase();
+    if (isVelocityStyleRadarVar(v)) {
+        const [vmin, vmax] = velocityRangeToMs(rangeMin, rangeMax, units);
+        return [vmin ?? 0, vmax ?? 80];
+    }
+    if (nexradDataSource === 'level3' && (v === 'N0H' || v === 'HHC')) {
+        const lo = rangeMin ?? 0;
+        let hi = rangeMax ?? 11;
+        if (hi > 11) hi = 11;
+        if (hi < lo) hi = lo;
+        return [lo, hi];
+    }
+    if (v === 'KDP') {
+        const lo = rangeMin ?? -2;
+        let hi = rangeMax ?? 8;
+        if (hi < lo) hi = lo;
+        return [lo, hi];
+    }
+    return [rangeMin ?? 0, rangeMax ?? 80];
+}
+
+/** Level-III digital / hybrid hydrometeor classification (aguacero-frontend `nexradLevel3IsHydrometeorClassification`). */
+function nexradLevel3IsHydrometeorClassification(radarVariable) {
+    const v = (radarVariable || '').toUpperCase();
+    return v === 'N0H' || v === 'HHC';
+}
+
+/** NWS class labels for digital HC (indices 0–11). */
+const NEXRAD_HYDROMETEOR_CLASS_LABELS = [
+    'Biological',
+    'Ground clutter',
+    'Ice crystals',
+    'Dry snow',
+    'Wet snow',
+    'Light rain',
+    'Heavy rain',
+    'Big drops',
+    'Graupel',
+    'Hail/rain',
+    'Large hail',
+    'Giant hail',
+];
+
+function nexradHydrometeorLabelForClassIndex(value) {
+    const idx = Math.round(Number(value));
+    if (idx >= 12) return null;
+    if (idx >= 0 && idx < NEXRAD_HYDROMETEOR_CLASS_LABELS.length) {
+        return NEXRAD_HYDROMETEOR_CLASS_LABELS[idx];
+    }
+    return `Class ${idx}`;
+}
+
+function velocityMsToDisplay(valueMs, displayUnit) {
+    if (!displayUnit || displayUnit.toLowerCase() === 'm/s' || displayUnit.toLowerCase() === 'ms') {
+        return valueMs;
+    }
+    const fromMs = getUnitConversionFunction('m/s', displayUnit, 'nexrad_vel');
+    return fromMs ? fromMs(valueMs) : valueMs;
+}
+
+/** Standard 4/3-earth beam height (km AGL at antenna) from slant range and elevation — matches frontend `beamHeightKm`. */
+function beamHeightKm(slantRangeKm, elevDeg) {
+    const el = (elevDeg * Math.PI) / 180;
+    const ReKm = (6371000 * 4) / (3 * 1000);
+    const cosEl = Math.max(Math.cos(el), 0.05);
+    const s = slantRangeKm / cosEl;
+    return Math.sqrt(s * s + ReKm * ReKm + 2 * s * ReKm * Math.sin(el)) - ReKm;
+}
+
+function formatNexradInspectNumeric(raw, radarVariable) {
+    const vu = (radarVariable || '').toUpperCase();
+    const vl = radarVariable || '';
+    if (vu.includes('RATE') || vl.toLowerCase().includes('rate')) {
+        return Number(raw.toFixed(3).replace(/\.?0+$/, ''));
+    }
+    if (vu === 'RHO' || vu === 'ZDR' || vl.includes('RhoHV') || vl.includes('Zdr')) {
+        return Number(raw.toFixed(2));
+    }
+    if (Math.abs(raw) < 10) return Number(raw.toFixed(1));
+    return Math.round(raw);
+}
+
+const PRELOAD_CONCURRENCY = 4;
+
+export class NexradWeatherController {
+    constructor(map, core, options = {}) {
+        this.map = map;
+        this.core = core;
+        this.layerId = options.nexradLayerId || 'aguacero-nexrad-layer';
+        this.mapboxLayer = null;
+        /** Includes tilt/timestamp so elevation changes always re-upload (see {@link _syncIdentity}). */
+        this._lastSyncKey = null;
+        this._abort = null;
+        this._interpolateColormap = options.interpolateNexradColormap !== false;
+        this._gateSmoothing = options.nexradGateSmoothing === true;
+        /** Decoded radar frames keyed by fetchKey from _buildFetchParamsForUnix. */
+        this._frameCache = new Map();
+        this._preloadAbort = null;
+        this._preloadTimelineSig = null;
+        /** @type {(() => string | undefined) | null} */
+        this._getInsertBeforeLayerId = options.getInsertBeforeLayerId || null;
+    }
+
+    destroy() {
+        this._abort?.abort();
+        this._abort = null;
+        this._preloadAbort?.abort();
+        this._preloadAbort = null;
+        this._frameCache.clear();
+        this._preloadTimelineSig = null;
+        if (this.mapboxLayer && this.map.getLayer(this.mapboxLayer.id)) {
+            this.map.removeLayer(this.mapboxLayer.id);
+        }
+        this.mapboxLayer = null;
+        this._lastSyncKey = null;
+    }
+
+    _resolveListingContext(state) {
+        const nk = this.core._nexradTimesCacheKey?.();
+        const ent = nk ? this.core.nexradTimesByStation?.[nk] : null;
+        const timeToKeyMap = state.nexradTimeToKeyMap || ent?.timeToKeyMap || {};
+        const motionMap = state.nexradLevel3MotionTimeToKeyMap || ent?.level3MotionTimeToKeyMap || {};
+        return { nk, ent, timeToKeyMap, motionMap };
+    }
+
+    /**
+     * @param {object} state
+     * @param {number} unix
+     * @returns {{ objectKey: string, url: string, fetchKey: string, motionObjectKey: string | null, radarVar: string, radarSource: string, groupId: number } | null}
+     */
+    _buildFetchParamsForUnix(state, unix) {
+        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
+        const radarSource = state.nexradDataSource === 'level3' ? 'level3' : 'level2';
+        const groupId = nexradBinGroupIdForKey(variableToNexradGroup(radarVar));
+        const { timeToKeyMap, motionMap } = this._resolveListingContext(state);
+        const objectKey = timeToKeyMap[String(unix)];
+        if (!objectKey) return null;
+
+        let motionObjectKey = null;
+        if (radarVar === 'VEL' && state.nexradStormRelative) {
+            motionObjectKey = pickNearestLevel3ObjectKey(unix, motionMap);
+        }
+
+        const url = objectKeyToUrl(objectKey, radarSource);
+        const fetchKey = `${url}|${radarVar}|${radarSource}|${motionObjectKey || ''}`;
+        return { objectKey, url, fetchKey, motionObjectKey, radarVar, radarSource, groupId };
+    }
+
+    async _fetchFrame(state, unix, { signal, priority }) {
+        const p = this._buildFetchParamsForUnix(state, unix);
+        if (!p) return null;
+        return fetchAndParseArchive(p.url, p.objectKey, p.radarVar, p.groupId, p.radarSource, {
+            signal,
+            priority,
+            level3MotionObjectKey: p.motionObjectKey,
+        });
+    }
+
+    _preloadTimelineSignature(state) {
+        const nk = this.core._nexradTimesCacheKey?.() || '';
+        const ts = [...(state.availableNexradTimestamps || [])]
+            .map(Number)
+            .filter((t) => Number.isFinite(t))
+            .sort((a, b) => a - b)
+            .join(',');
+        const tilt =
+            state.nexradTilt != null && Number.isFinite(Number(state.nexradTilt))
+                ? Number(state.nexradTilt).toFixed(3)
+                : '';
+        return `${nk}|${ts}|sr:${state.nexradStormRelative ? 1 : 0}|tilt:${tilt}`;
+    }
+
+    /**
+     * Identity for whether the visible radar frame + upload options match (tilt affects L3 mesh keys and listing object paths).
+     * @param {object} state
+     * @param {{ fetchKey: string }} p
+     * @param {number} unix
+     */
+    _syncIdentity(state, p, unix) {
+        const tilt =
+            state.nexradTilt != null && Number.isFinite(Number(state.nexradTilt))
+                ? Number(state.nexradTilt).toFixed(3)
+                : '';
+        return `${p.fetchKey}|tilt:${tilt}|u:${unix}`;
+    }
+
+    /**
+     * Background-load every volume on the slider timeline (like satellite KTX2 preload).
+     * Slider / `nexradTimestamp` changes only swap GPU buffers from cache when possible.
+     * @param {object} state
+     */
+    preloadAllAvailable(state) {
+        if (!state.isNexrad || !state.nexradSite) return;
+
+        const sig = this._preloadTimelineSignature(state);
+        if (sig === this._preloadTimelineSig) return;
+
+        this._preloadTimelineSig = sig;
+        this._preloadAbort?.abort();
+        this._preloadAbort = new AbortController();
+        const signal = this._preloadAbort.signal;
+
+        this._frameCache.clear();
+
+        setNexradArchiveApiKey(this.core.apiKey || '');
+
+        const times = [...(state.availableNexradTimestamps || [])]
+            .map(Number)
+            .filter((t) => Number.isFinite(t));
+        if (!times.length) return;
+
+        const snapshot = { ...state };
+
+        const run = async () => {
+            let cursor = 0;
+            const work = async () => {
+                while (cursor < times.length && !signal.aborted) {
+                    const i = cursor++;
+                    const unix = times[i];
+                    const p = this._buildFetchParamsForUnix(snapshot, unix);
+                    if (!p || signal.aborted) continue;
+                    if (this._frameCache.has(p.fetchKey)) continue;
+                    try {
+                        const frame = await this._fetchFrame(snapshot, unix, {
+                            signal,
+                            priority: 'prefetch',
+                        });
+                        if (frame && !signal.aborted) {
+                            this._frameCache.set(p.fetchKey, frame);
+                        }
+                    } catch {
+                        /* ignore failed preload tiles */
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: PRELOAD_CONCURRENCY }, () => work()));
+        };
+
+        void run();
+    }
+
+    _ensureLayer() {
+        if (this.mapboxLayer) return;
+        this.mapboxLayer = new MapboxRadarLayer(this.layerId);
+        let beforeId =
+            typeof this._getInsertBeforeLayerId === 'function'
+                ? this._getInsertBeforeLayerId()
+                : undefined;
+        if (!beforeId && this.map.getLayer('AML_-_terrain')) {
+            beforeId = 'AML_-_terrain';
+        }
+        if (beforeId) {
+            this.map.addLayer(this.mapboxLayer, beforeId);
+        } else {
+            this.map.addLayer(this.mapboxLayer);
+        }
+    }
+
+    _uploadFrame(state, frame) {
+        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
+        this.mapboxLayer.setInterpolateColormap(this._interpolateColormap);
+        this.mapboxLayer.setGateSmoothing(this._gateSmoothing);
+
+        const colormapFlat = state.colormap;
+        const colormapForShader = colormapToMs(colormapFlat, radarVar, state.units);
+        const [shaderMin, shaderMax] = radarShaderValueRange(
+            colormapFlat?.[0],
+            colormapFlat?.[colormapFlat.length - 2],
+            radarVar,
+            state.units,
+            state.nexradDataSource,
+        );
+
+        this.mapboxLayer.setColormap(colormapForShader);
+        this.mapboxLayer.setValueRange(shaderMin, shaderMax);
+        this.mapboxLayer.setOpacity(state.opacity ?? 1);
+        this.mapboxLayer.setFrameData(frame, mapboxFrameUploadOptionsForNexradState(state));
+        this.map.triggerRepaint();
+    }
+
+    /**
+     * @param {object} state - core state + emitted colormap (from state:change)
+     */
+    async sync(state) {
+        if (!state.isNexrad || !state.nexradSite || state.nexradTimestamp == null) {
+            this.destroy();
+            return;
+        }
+
+        setNexradArchiveApiKey(this.core.apiKey || '');
+
+        const unix = Number(state.nexradTimestamp);
+        const p = this._buildFetchParamsForUnix(state, unix);
+        if (!p) {
+            return;
+        }
+
+        const syncKey = this._syncIdentity(state, p, unix);
+        if (syncKey === this._lastSyncKey && this.mapboxLayer) {
+            this._applyStyle(state);
+            return;
+        }
+
+        const cached = this._frameCache.get(p.fetchKey);
+        if (cached) {
+            this._ensureLayer();
+            this._uploadFrame(state, cached);
+            this._lastSyncKey = syncKey;
+            return;
+        }
+
+        this._abort?.abort();
+        this._abort = new AbortController();
+
+        let frame;
+        try {
+            frame = await this._fetchFrame(state, unix, {
+                signal: this._abort.signal,
+                priority: 'display',
+            });
+        } catch {
+            return;
+        }
+
+        if (!frame || this._abort.signal.aborted) return;
+
+        this._frameCache.set(p.fetchKey, frame);
+
+        this._ensureLayer();
+        this._uploadFrame(state, frame);
+        this._lastSyncKey = syncKey;
+    }
+
+    _applyStyle(state) {
+        if (!this.mapboxLayer) return;
+        const radarVar = (state.nexradProduct || 'REF').toUpperCase();
+        const colormapFlat = state.colormap;
+        const colormapForShader = colormapToMs(colormapFlat, radarVar, state.units);
+        const [shaderMin, shaderMax] = radarShaderValueRange(
+            colormapFlat?.[0],
+            colormapFlat?.[colormapFlat.length - 2],
+            radarVar,
+            state.units,
+            state.nexradDataSource,
+        );
+        this.mapboxLayer.setColormap(colormapForShader);
+        this.mapboxLayer.setValueRange(shaderMin, shaderMax);
+        this.mapboxLayer.setOpacity(state.opacity ?? 1);
+        this.map.triggerRepaint();
+    }
+
+    /**
+     * Mouse readout at lng/lat — same sampling and formatting as aguacero-frontend `NexradReadoutFrame`
+     * (polar sample + velocity/hydro/range checks). Uses the cached frame for the current timeline key.
+     *
+     * @param {number} lng
+     * @param {number} lat
+     * @param {object} state - Latest `state:change` payload (needs `colormap`, NEXRAD fields).
+     * @returns {object | null}
+     */
+    getInspectPayload(lng, lat, state) {
+        if (!state?.isNexrad || !state.nexradSite || state.nexradTimestamp == null) return null;
+        if (state.visible === false || (state.opacity ?? 1) <= 0) return null;
+
+        const unix = Number(state.nexradTimestamp);
+        const p = this._buildFetchParamsForUnix(state, unix);
+        if (!p) return null;
+
+        const frame = this._frameCache.get(p.fetchKey);
+        if (!frame) return null;
+
+        const colormapFlat = state.colormap;
+        if (!colormapFlat || colormapFlat.length < 2) return null;
+
+        const rangeMin = colormapFlat[0];
+        const rangeMax = colormapFlat[colormapFlat.length - 2];
+
+        const radarVariable = (state.nexradProduct || 'REF').toUpperCase();
+        const radarSource = state.nexradDataSource === 'level3' ? 'level3' : 'level2';
+        const displayUnits =
+            state.units && String(state.units).toLowerCase() !== 'none'
+                ? state.units
+                : isVelocityStyleRadarVar(radarVariable)
+                  ? 'm/s'
+                  : '';
+
+        const gpuFrame = prepareRadarFrameForGpuReadout(frame, mapboxFrameUploadOptionsForNexradState(state));
+        const sample = sampleNexradFrameAtLatLon(gpuFrame, lat, lng, { smoothPolar: this._gateSmoothing });
+        if (!sample) return null;
+
+        const valueMs = sample.value;
+        const isHydro = radarSource === 'level3' && nexradLevel3IsHydrometeorClassification(radarVariable);
+
+        /** @type {number | string} */
+        let valueOut;
+        let unitOut = displayUnits || '';
+
+        if (isVelocityStyleRadarVar(radarVariable)) {
+            valueOut = velocityMsToDisplay(valueMs, displayUnits);
+        } else if (isHydro) {
+            const label = nexradHydrometeorLabelForClassIndex(valueMs);
+            if (label == null) return null;
+            valueOut = label;
+            unitOut = '';
+        } else {
+            valueOut = formatNexradInspectNumeric(valueMs, radarVariable);
+        }
+
+        let inRange;
+        if (isHydro) {
+            const idx = Math.round(Number(valueMs));
+            inRange =
+                (rangeMin == null || idx >= rangeMin) && (rangeMax == null || idx <= rangeMax);
+        } else if (isVelocityStyleRadarVar(radarVariable)) {
+            inRange =
+                (rangeMin == null || valueOut >= rangeMin) && (rangeMax == null || valueOut <= rangeMax);
+        } else {
+            inRange =
+                (rangeMin == null || valueOut >= rangeMin) && (rangeMax == null || valueOut <= rangeMax);
+        }
+
+        if (!inRange) return null;
+
+        const tiltDeg = Number.isFinite(state.nexradTilt) ? state.nexradTilt : getDefaultRadarTilt(state.nexradSite);
+        const bhKm = beamHeightKm(sample.groundRangeKm, tiltDeg);
+        const metric = state.units === 'metric';
+        const beamHeightDisplay = metric ? bhKm : bhKm * 3.280839895013123;
+        const beamUnit = metric ? 'km' : 'kft';
+
+        const fldKey = state.variable;
+        return {
+            lngLat: { lng, lat },
+            variable: {
+                code: fldKey,
+                name: this.core.getVariableDisplayName(fldKey),
+            },
+            value: valueOut,
+            unit: unitOut,
+            beamHeight:
+                Number.isFinite(beamHeightDisplay) && Number.isFinite(bhKm)
+                    ? { value: beamHeightDisplay, unit: beamUnit }
+                    : null,
+        };
+    }
+}