@aguacerowx/react-native 0.0.42 → 0.0.44

package/src/nexrad/nexradAndroidController.js

@@ -0,0 +1,1076 @@
+/**
+ * AguaceroCore NEXRAD → Android native custom layer (parity with mapsgl {@link NexradWeatherController}).
+ */
+import { getUnitConversionFunction, getDefaultRadarTilt, nexradBinGroupIdForKey, variableToNexradGroup } from '@aguacerowx/javascript-sdk';
+import { fromByteArray } from 'base64-js';
+import {
+    fetchAndParseArchive,
+    objectKeyToUrl,
+    setNexradArchiveApiKey,
+    setNexradArchiveBundleId,
+    setNexradSitesJsonUrl,
+    setNexradSitesFetchAuth,
+} from './radarArchiveCore.bundled.js';
+import { prepareRadarFrameForGpuReadout } from './radarFrameGpuMatch.bundled.js';
+import { mapboxFrameUploadOptionsForNexradState } from './nexradMapboxFrameOpts.bundled.js';
+import { sampleNexradFrameAtLatLon } from './nexradCrossSectionSampleAtLatLon.bundled.js';
+import { buildNexradLutRgba } from './nexradLutBuild.js';
+import { nexradDiag, nexradDiagBootSnapshot, nexradDiagGateTextureSummary, nexradPerfSpan } from './nexradDiag.js';
+
+nexradDiagBootSnapshot({
+    archiveExports: {
+        setNexradArchiveApiKey: typeof setNexradArchiveApiKey,
+        setNexradArchiveBundleId: typeof setNexradArchiveBundleId,
+        objectKeyToUrl: typeof objectKeyToUrl,
+        fetchAndParseArchive: typeof fetchAndParseArchive,
+    },
+});
+
+/** @returns {boolean} */
+function ensureRadarArchiveBindings(label) {
+    const ok =
+        typeof setNexradArchiveApiKey === 'function' &&
+        typeof setNexradArchiveBundleId === 'function' &&
+        typeof objectKeyToUrl === 'function' &&
+        typeof fetchAndParseArchive === 'function';
+    if (!ok) {
+        nexradDiag('archive.bindings.missing', {
+            where: label,
+            setNexradArchiveApiKey: typeof setNexradArchiveApiKey,
+            setNexradArchiveBundleId: typeof setNexradArchiveBundleId,
+            objectKeyToUrl: typeof objectKeyToUrl,
+            fetchAndParseArchive: typeof fetchAndParseArchive,
+        });
+    }
+    return ok;
+}
+
+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];
+}
+
+function nexradLevel3IsHydrometeorClassification(radarVariable) {
+    const v = (radarVariable || '').toUpperCase();
+    return v === 'N0H' || v === 'HHC';
+}
+
+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;
+}
+
+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);
+}
+
+/** Keep low so Level-2 decode stays off the critical path for touches/animations (was 4). */
+const PRELOAD_CONCURRENCY = 1;
+
+function yieldToJsEventLoop() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/** Match mapsgl {@link MapboxRadarLayer} geometry LRU — reuse serialized native payloads when scrubbing. */
+const NATIVE_UPLOAD_JSON_LRU_MAX = 12;
+
+function rleCompressGateData(gateData) {
+    const len = gateData.length;
+    const out = new Uint8Array(len * 2);
+    let outIdx = 0;
+    let i = 0;
+    while (i < len) {
+        let val0 = gateData[i];
+        let val1 = gateData[i + 1];
+        let count = 1;
+        let maxCount = (len - i) >> 1;
+        if (maxCount > 65535) maxCount = 65535;
+
+        let j = i + 2;
+        while (count < maxCount && gateData[j] === val0 && gateData[j + 1] === val1) {
+            count++;
+            j += 2;
+        }
+
+        out[outIdx++] = count & 0xFF;
+        out[outIdx++] = (count >> 8) & 0xFF;
+        out[outIdx++] = val0;
+        out[outIdx++] = val1;
+
+        i = j;
+    }
+    return out.subarray(0, outIdx);
+}
+
+export class NexradAndroidController {
+/**
+ * @param {*} core - AguaceroCore instance
+ * @param {React.MutableRefObject<{ uploadNexradFrame?: (s: string) => void; uploadNexradStyleOnly?: (s: string) => void; clearNexrad?: () => void; activateNexradCachedFrame?: (k: string) => void } | null>} layerRef
+     * @param {object} [options]
+     */
+    constructor(core, layerRef, options = {}) {
+        this.core = core;
+        this._layerRef = layerRef;
+        this._lastSyncKey = null;
+        this._abort = null;
+        this._interpolateColormap = options.interpolateNexradColormap !== false;
+        this._gateSmoothing = options.nexradGateSmoothing === true;
+        this._frameCache = new Map();
+        /** WeakMap: decoded frame → Map(uploadOptsKey → prepared frame). Avoids O(n²) canonical re-bin every map move. */
+        this._gpuReadoutPrep = new WeakMap();
+        this._preloadAbort = null;
+        this._preloadTimelineSig = null;
+        this._nativeFrameUploaded = false;
+        /** @type {{ valueScale: number; valueOffset: number } | null} */
+        this._lastUploadMeta = null;
+        /** @type {Map<string, { json: string; valueScale: number; valueOffset: number }>} */
+        this._nativeUploadJsonLru = new Map();
+        /** @type {Set<string>} Sync keys with gate texture registered in Android GL cache (AguaceroNexradGpuFrameReady). */
+        this._nativeGpuReadyKeys = new Set();
+        /** @type {Map<string, { valueScale: number; valueOffset: number }>} */
+        this._uploadMetaBySyncKey = new Map();
+        /** @type {{ remove: () => void } | null} */
+        this._gpuReadyEventSub = null;
+        try {
+            const { DeviceEventEmitter } = require('react-native');
+            if (DeviceEventEmitter && typeof DeviceEventEmitter.addListener === 'function') {
+                this._gpuReadyEventSub = DeviceEventEmitter.addListener('AguaceroNexradGpuFrameReady', (e) => {
+                    const k = e && e.nativeGpuCacheKey;
+                    if (typeof k === 'string' && k.length > 0) {
+                        this._nativeGpuReadyKeys.add(k);
+                        this._trimNativeGpuReadyKeys(32);
+                        nexradDiag('gpuReady.event', { keyTail: k.slice(-80), setSize: this._nativeGpuReadyKeys.size });
+                    }
+                });
+            }
+        } catch (err) {
+            nexradDiag('gpuReady.subscribeFailed', { message: err?.message || String(err) });
+        }
+        const base = typeof core?.baseGridUrl === 'string' ? core.baseGridUrl.replace(/\/$/, '') : '';
+        if (base && typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+            setNexradSitesJsonUrl(`${base}/data/nexrad.json`);
+            setNexradSitesFetchAuth(core.apiKey || '', core.bundleId || '');
+        }
+        nexradDiag('controller.construct', {
+            hasCore: !!core,
+            apiKeyLen: (core?.apiKey || '').length,
+            bundleIdLen: (core?.bundleId || '').length,
+            interpolateColormap: this._interpolateColormap,
+            gateSmoothing: this._gateSmoothing,
+            rnSitesUrl: base ? `${base}/data/nexrad.json` : '(unset)',
+        });
+    }
+
+    _trimNativeGpuReadyKeys(max) {
+        while (this._nativeGpuReadyKeys.size > max) {
+            const first = this._nativeGpuReadyKeys.values().next().value;
+            if (first === undefined) break;
+            this._nativeGpuReadyKeys.delete(first);
+        }
+    }
+
+    _rememberUploadMetaForSyncKey(syncKey, valueScale, valueOffset) {
+        this._uploadMetaBySyncKey.set(syncKey, { valueScale, valueOffset });
+        while (this._uploadMetaBySyncKey.size > 40) {
+            const k = this._uploadMetaBySyncKey.keys().next().value;
+            if (k === undefined) break;
+            this._uploadMetaBySyncKey.delete(k);
+        }
+    }
+
+    updateStyleOptions(options) {
+        if (options.interpolateNexradColormap != null) {
+            this._interpolateColormap = options.interpolateNexradColormap !== false;
+        }
+        if (options.nexradGateSmoothing != null) {
+            this._gateSmoothing = options.nexradGateSmoothing === true;
+        }
+    }
+
+    destroy() {
+        nexradDiag('controller.destroy');
+        try {
+            this._gpuReadyEventSub?.remove();
+        } catch (_) {
+            /* ignore */
+        }
+        this._gpuReadyEventSub = null;
+        this._nativeGpuReadyKeys.clear();
+        this._uploadMetaBySyncKey.clear();
+        this._abort?.abort();
+        this._abort = null;
+        this._preloadAbort?.abort();
+        this._preloadAbort = null;
+        this._frameCache.clear();
+        this._gpuReadoutPrep = new WeakMap();
+        this._preloadTimelineSig = null;
+        this._lastSyncKey = null;
+        this._nativeFrameUploaded = false;
+        this._lastUploadMeta = null;
+        this._nativeUploadJsonLru.clear();
+        this._layerRef?.current?.clearNexrad?.();
+    }
+
+    _getPreparedReadoutFrame(frame, uploadOpts) {
+        let byOpts = this._gpuReadoutPrep.get(frame);
+        if (!byOpts) {
+            byOpts = new Map();
+            this._gpuReadoutPrep.set(frame, byOpts);
+        }
+        const optKey =
+            uploadOpts && typeof uploadOpts === 'object'
+                ? JSON.stringify(uploadOpts)
+                : String(uploadOpts);
+        let prepared = byOpts.get(optKey);
+        if (!prepared) {
+            prepared = prepareRadarFrameForGpuReadout(frame, uploadOpts);
+            byOpts.set(optKey, prepared);
+        }
+        return prepared;
+    }
+
+    _native() {
+        return this._layerRef?.current;
+    }
+
+    _lutPack(state) {
+        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,
+        );
+        const { bytes, discreteIntegerLut } = buildNexradLutRgba(
+            colormapForShader,
+            shaderMin,
+            shaderMax,
+            this._interpolateColormap,
+        );
+        return {
+            lutB64: fromByteArray(bytes),
+            lutMin: shaderMin,
+            lutMax: shaderMax,
+            discreteIntegerLut,
+        };
+    }
+
+    /**
+     * LRU for full native JSON payloads (parity with mapsgl gate-texture reuse — avoids base64 + stringify on repeat scrubs).
+     * @param {string} syncKey
+     * @returns {{ json: string; valueScale: number; valueOffset: number } | null}
+     */
+    _nativeUploadJsonLruTouch(syncKey) {
+        const ent = this._nativeUploadJsonLru.get(syncKey);
+        if (!ent) return null;
+        this._nativeUploadJsonLru.delete(syncKey);
+        this._nativeUploadJsonLru.set(syncKey, ent);
+        return ent;
+    }
+
+    /** @param {string} syncKey @param {{ json: string; valueScale: number; valueOffset: number }} entry */
+    _nativeUploadJsonLruPut(syncKey, entry) {
+        if (this._nativeUploadJsonLru.has(syncKey)) this._nativeUploadJsonLru.delete(syncKey);
+        this._nativeUploadJsonLru.set(syncKey, entry);
+        while (this._nativeUploadJsonLru.size > NATIVE_UPLOAD_JSON_LRU_MAX) {
+            const oldest = this._nativeUploadJsonLru.keys().next().value;
+            if (oldest === undefined) break;
+            this._nativeUploadJsonLru.delete(oldest);
+        }
+    }
+
+    /**
+     * Full-frame JSON includes LUT + opacity + shader toggles; keep LRU key aligned so scrubbing
+     * cannot resurrect an outdated style after the user changes only presentation options.
+     */
+    _nativeUploadLruKey(state, syncKey) {
+        return `${syncKey}|o:${state.opacity ?? 1}|g:${this._gateSmoothing ? 1 : 0}|i:${this._interpolateColormap ? 1 : 0}`;
+    }
+
+    /**
+     * @param {*} state
+     * @param {*} frame - decoded archive frame
+     * @param {{ fetchKey: string }} p - from {@link _buildFetchParamsForUnix}
+     * @param {number} unix
+     */
+    _uploadFrameToNative(state, frame, p, unix) {
+        const uploadTotal = nexradPerfSpan(
+            `uploadFrame.total site=${state.nexradSite} unix=${unix} var=${p?.radarVar ?? state.nexradProduct}`,
+        );
+        const n = this._native();
+        if (!n?.uploadNexradFrame) {
+            nexradDiag('native.uploadSkipped', {
+                reason: !n ? 'noLayerRef' : 'noUploadNexradFrameMethod',
+                site: state.nexradSite,
+            });
+            uploadTotal.end({ outcome: 'skippedNoNative' });
+            return;
+        }
+
+        const syncKey = this._syncIdentity(state, p, unix);
+        const lruKey = this._nativeUploadLruKey(state, syncKey);
+        const lruHit = this._nativeUploadJsonLruTouch(lruKey);
+        if (lruHit) {
+            this._lastUploadMeta = { valueScale: lruHit.valueScale, valueOffset: lruHit.valueOffset };
+            this._rememberUploadMetaForSyncKey(syncKey, lruHit.valueScale, lruHit.valueOffset);
+            if (n.activateNexradCachedFrame && this._nativeGpuReadyKeys.has(syncKey)) {
+                nexradDiag('native.uploadFrame.gpuActivateOnly', {
+                    site: state.nexradSite,
+                    syncKeyTail: syncKey.slice(-80),
+                    jsonCharsSkipped: lruHit.json.length,
+                });
+                const tAct = nexradPerfSpan('uploadFrame.nativeGpuActivateOnly');
+                n.activateNexradCachedFrame(syncKey);
+                tAct.end({ keyLen: syncKey.length });
+                const tStyle = nexradPerfSpan('uploadFrame.styleAfterGpuActivate');
+                this.applyStyleFromState(state);
+                tStyle.end({});
+                this._nativeFrameUploaded = true;
+                uploadTotal.end({ outcome: 'gpuActivateOnly', jsonCharsSkipped: lruHit.json.length });
+                return;
+            }
+            nexradDiag('native.uploadFrame.jsonLruHit', {
+                site: state.nexradSite,
+                jsonChars: lruHit.json.length,
+            });
+            const bridge = nexradPerfSpan('uploadFrame.nativeJsonLru.bridgeDispatch');
+            n.uploadNexradFrame(lruHit.json);
+            bridge.end({ jsonChars: lruHit.json.length, path: 'jsonLruHit' });
+            this._nativeFrameUploaded = true;
+            uploadTotal.end({ outcome: 'jsonLruHit', jsonChars: lruHit.json.length });
+            return;
+        }
+
+        const tOpts = nexradPerfSpan('uploadFrame.mapboxFrameUploadOptions');
+        const uploadOpts = mapboxFrameUploadOptionsForNexradState(state);
+        tOpts.end({});
+
+        // Skip JS sorting for Android native upload
+        // We pass the raw frame and let Android do the sorting/canonicalization
+        const rawFrame = frame;
+
+        this._lastUploadMeta = {
+            valueScale: rawFrame.valueScale,
+            valueOffset: rawFrame.valueOffset,
+        };
+
+        const tLut = nexradPerfSpan('uploadFrame.lutPack_buildNexradLutRgba');
+        const style = this._lutPack(state);
+        tLut.end({
+            lutB64Chars: style.lutB64?.length ?? 0,
+            discreteIntegerLut: style.discreteIntegerLut,
+            lutMin: style.lutMin,
+            lutMax: style.lutMax,
+        });
+
+        const tRay = nexradPerfSpan('uploadFrame.rayBoundariesToJsArray');
+        const rayBoundaries = rawFrame.rayBoundariesDeg?.slice ? Array.from(rawFrame.rayBoundariesDeg) : [...(rawFrame.rayBoundariesDeg || [])];
+        tRay.end({ len: rayBoundaries.length });
+
+        const tB64 = nexradPerfSpan('uploadFrame.gateData_toBase64');
+        const rleGateData = rleCompressGateData(rawFrame.gateData);
+        const gateB64 = fromByteArray(rleGateData);
+        tB64.end({ gateB64Chars: gateB64.length, rleBytes: rleGateData.length, rawBytes: rawFrame.gateData.length });
+
+        const payload = {
+            gateB64,
+            gateIsRle: true,
+            nGates: rawFrame.nGates,
+            nRays: rawFrame.nRays,
+            stationLat: rawFrame.stationLat,
+            stationLon: rawFrame.stationLon,
+            firstGateKm: rawFrame.firstGateKm,
+            gateWidthKm: rawFrame.gateWidthKm,
+            rayBoundaries,
+            lutB64: style.lutB64,
+            valueScale: rawFrame.valueScale,
+            valueOffset: rawFrame.valueOffset,
+            lutMin: style.lutMin,
+            lutMax: style.lutMax,
+            discreteIntegerLut: style.discreteIntegerLut,
+            opacity: state.opacity ?? 1,
+            gateSmoothPolar: this._gateSmoothing ? 1 : 0,
+            interpolateLut: this._interpolateColormap ? 1 : 0,
+            nativeGpuCacheKey: syncKey,
+            uploadOpts: uploadOpts,
+        };
+
+        const tJson = nexradPerfSpan('uploadFrame.JSON_stringify_payload');
+        const json = JSON.stringify(payload);
+        tJson.end({
+            jsonChars: json.length,
+            rayBoundaryLen: rayBoundaries.length,
+        });
+
+        const tLruPut = nexradPerfSpan('uploadFrame.nativeUploadJsonLruPut');
+        this._nativeUploadJsonLruPut(lruKey, {
+            json,
+            valueScale: rawFrame.valueScale,
+            valueOffset: rawFrame.valueOffset,
+        });
+        tLruPut.end({ lruKeyTail: lruKey.slice(-96), lruSize: this._nativeUploadJsonLru.size });
+
+        const gateSummary = nexradDiagGateTextureSummary(
+            rawFrame.gateData,
+            rawFrame.nGates,
+            rawFrame.nRays,
+            rawFrame.valueScale,
+            rawFrame.valueOffset,
+            style.lutMin,
+            style.lutMax,
+        );
+        nexradDiag('native.uploadFrame.dispatch', {
+            site: state.nexradSite,
+            nGates: rawFrame.nGates,
+            nRays: rawFrame.nRays,
+            jsonChars: json.length,
+            uploadOpts: uploadOpts ?? null,
+            rayBoundaryLen: rayBoundaries.length,
+            firstGateKm: rawFrame.firstGateKm,
+            gateWidthKm: rawFrame.gateWidthKm,
+            gateSummary,
+        });
+
+        const tBridge = nexradPerfSpan('uploadFrame.nativeBridge_uploadNexradFrame');
+        n.uploadNexradFrame(json);
+        tBridge.end({ jsonChars: json.length, path: 'fullRebuild' });
+
+        this._rememberUploadMetaForSyncKey(syncKey, rawFrame.valueScale, rawFrame.valueOffset);
+        this._nativeFrameUploaded = true;
+        uploadTotal.end({
+            outcome: 'fullPipeline',
+            jsonChars: json.length,
+            nGates: rawFrame.nGates,
+            nRays: rawFrame.nRays,
+        });
+    }
+
+    applyStyleFromState(state) {
+        const perf = nexradPerfSpan(
+            `applyStyleFromState site=${state.nexradSite} product=${state.nexradProduct} tilt=${state.nexradTilt}`,
+        );
+        const n = this._native();
+        if (!this._nativeFrameUploaded || !this._lastUploadMeta || !n?.uploadNexradStyleOnly) {
+            perf.end({
+                outcome: 'skipped',
+                nativeFrameUploaded: this._nativeFrameUploaded,
+                hasUploadMeta: !!this._lastUploadMeta,
+                hasStyleMethod: !!n?.uploadNexradStyleOnly,
+            });
+            return;
+        }
+
+        const tLut = nexradPerfSpan('applyStyleFromState.lutPack');
+        const style = this._lutPack(state);
+        tLut.end({ lutB64Chars: style.lutB64?.length ?? 0 });
+
+        const payload = {
+            lutB64: style.lutB64,
+            valueScale: this._lastUploadMeta.valueScale,
+            valueOffset: this._lastUploadMeta.valueOffset,
+            lutMin: style.lutMin,
+            lutMax: style.lutMax,
+            discreteIntegerLut: style.discreteIntegerLut,
+            opacity: state.opacity ?? 1,
+            gateSmoothPolar: this._gateSmoothing ? 1 : 0,
+            interpolateLut: this._interpolateColormap ? 1 : 0,
+        };
+
+        const tJson = nexradPerfSpan('applyStyleFromState.JSON_stringify');
+        const json = JSON.stringify(payload);
+        tJson.end({ jsonChars: json.length });
+
+        const tBridge = nexradPerfSpan('applyStyleFromState.nativeBridge');
+        n.uploadNexradStyleOnly(json);
+        tBridge.end({ jsonChars: json.length });
+
+        perf.end({ outcome: 'dispatched' });
+    }
+
+    _resolveListingContext(state) {
+        const nk = this.core._nexradTimesCacheKey?.();
+        const ent = nk ? this.core.nexradTimesByStation?.[nk] : null;
+        // Merge so we still resolve object keys if the last state event omitted maps but the core cache is populated.
+        const timeToKeyMap = { ...(ent?.timeToKeyMap || {}), ...(state.nexradTimeToKeyMap || {}) };
+        const motionMap = {
+            ...(ent?.level3MotionTimeToKeyMap || {}),
+            ...(state.nexradLevel3MotionTimeToKeyMap || {}),
+        };
+        return { nk, ent, timeToKeyMap, motionMap };
+    }
+
+    _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) {
+            nexradDiag('fetchParams.noObjectKeyForUnix', {
+                unix,
+                radarVar,
+                radarSource,
+                timeToKeyMapSize: Object.keys(timeToKeyMap || {}).length,
+                sampleUnixKeys: Object.keys(timeToKeyMap || {}).slice(0, 12),
+            });
+            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 fetchPerf = nexradPerfSpan(
+            `fetchAndParseArchive priority=${priority} site=${state.nexradSite} unix=${unix} product=${state.nexradProduct}`,
+        );
+        const p = this._buildFetchParamsForUnix(state, unix);
+        if (!p) {
+            fetchPerf.end({ ok: false, reason: 'noFetchParams' });
+            return null;
+        }
+        try {
+            const frame = await fetchAndParseArchive(p.url, p.objectKey, p.radarVar, p.groupId, p.radarSource, {
+                signal,
+                priority,
+                level3MotionObjectKey: p.motionObjectKey,
+            });
+            fetchPerf.end({
+                ok: !!frame,
+                radarVar: p.radarVar,
+                radarSource: p.radarSource,
+                objectKeyTail: (p.objectKey || '').slice(-48),
+                motionKeyTail: (p.motionObjectKey || '').slice(-48),
+            });
+            return frame;
+        } catch (err) {
+            fetchPerf.end({
+                ok: false,
+                error: err?.message || String(err),
+                radarVar: p.radarVar,
+                radarSource: p.radarSource,
+            });
+            throw err;
+        }
+    }
+
+    _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}`;
+    }
+
+    _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}`;
+    }
+
+    preloadAllAvailable(state) {
+        if (!state.isNexrad || !state.nexradSite) return;
+
+        if (!ensureRadarArchiveBindings('preloadAllAvailable')) 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;
+
+        // Keep the volume currently on screen in the JS cache so getInspectPayload (mapsgl parity readouts)
+        // still works while we clear and rebuild the prefetch LRU — otherwise readouts stay null until
+        // this unix is fetched again (often last in the timeline).
+        const curUnix =
+            state.nexradTimestamp != null && Number.isFinite(Number(state.nexradTimestamp))
+                ? Number(state.nexradTimestamp)
+                : NaN;
+        const curP = Number.isFinite(curUnix) ? this._buildFetchParamsForUnix(state, curUnix) : null;
+        let preservedFetchKey = null;
+        let preservedFrame = null;
+        if (curP && this._frameCache.has(curP.fetchKey)) {
+            preservedFetchKey = curP.fetchKey;
+            preservedFrame = this._frameCache.get(curP.fetchKey);
+        }
+
+        this._frameCache.clear();
+        if (preservedFetchKey && preservedFrame) {
+            this._frameCache.set(preservedFetchKey, preservedFrame);
+        }
+        this._nativeUploadJsonLru.clear();
+        this._nativeGpuReadyKeys.clear();
+        this._uploadMetaBySyncKey.clear();
+
+        setNexradArchiveApiKey(this.core.apiKey || '');
+        setNexradArchiveBundleId(this.core.bundleId || '');
+        setNexradSitesFetchAuth(this.core.apiKey || '', this.core.bundleId || '');
+
+        const times = [...(state.availableNexradTimestamps || [])]
+            .map(Number)
+            .filter((t) => Number.isFinite(t));
+        if (!times.length) {
+            nexradDiag('preload.skipNoTimestamps', { site: state.nexradSite });
+            return;
+        }
+
+        nexradDiag('preload.start', {
+            site: state.nexradSite,
+            timesCount: times.length,
+            firstUnix: times[0],
+            lastUnix: times[times.length - 1],
+        });
+
+        const snapshot = { ...state };
+        const preloadBatch = nexradPerfSpan(`preload.batch site=${state.nexradSite} times=${times.length}`);
+        let preloadCompleted = 0;
+        let preloadFailed = 0;
+        let preloadSkippedCached = 0;
+
+        const run = async () => {
+            let cursor = 0;
+            const work = async () => {
+                while (cursor < times.length && !signal.aborted) {
+                    const i = cursor++;
+                    const unix = times[i];
+                    const slot = nexradPerfSpan(`preload.slot idx=${i + 1}/${times.length} unix=${unix}`);
+                    const p = this._buildFetchParamsForUnix(snapshot, unix);
+                    if (!p || signal.aborted) {
+                        slot.end({ outcome: 'noParamsOrAborted' });
+                    } else if (this._frameCache.has(p.fetchKey)) {
+                        preloadSkippedCached++;
+                        slot.end({ outcome: 'alreadyCached', fetchKeyTail: p.fetchKey.slice(-64) });
+                    } else {
+                        try {
+                            const frame = await this._fetchFrame(snapshot, unix, {
+                                signal,
+                                priority: 'prefetch',
+                            });
+                            if (frame && !signal.aborted) {
+                                this._frameCache.set(p.fetchKey, frame);
+                                preloadCompleted++;
+                                slot.end({
+                                    outcome: 'cachedFrame',
+                                    fetchKeyTail: p.fetchKey.slice(-64),
+                                    cacheSizeAfter: this._frameCache.size,
+                                });
+                            } else {
+                                slot.end({ outcome: 'noFrame', aborted: signal.aborted });
+                            }
+                        } catch (err) {
+                            preloadFailed++;
+                            nexradDiag('preload.fetchFailed', {
+                                unix,
+                                message: err?.message || String(err),
+                            });
+                            slot.end({ outcome: 'error', message: err?.message || String(err) });
+                        }
+                    }
+                    await yieldToJsEventLoop();
+                }
+            };
+            await Promise.all(Array.from({ length: PRELOAD_CONCURRENCY }, () => work()));
+            preloadBatch.end({
+                outcome: signal.aborted ? 'aborted' : 'complete',
+                completed: preloadCompleted,
+                failed: preloadFailed,
+                skippedCached: preloadSkippedCached,
+                finalCacheSize: this._frameCache.size,
+            });
+        };
+
+        void run();
+    }
+
+    async sync(state) {
+        const unixEarly = state.nexradTimestamp != null ? Number(state.nexradTimestamp) : NaN;
+        const syncTotal = nexradPerfSpan(
+            `sync.total site=${state.nexradSite} unix=${unixEarly} product=${state.nexradProduct} source=${state.nexradDataSource} tilt=${state.nexradTilt}`,
+        );
+
+        if (!state.isNexrad || !state.nexradSite || state.nexradTimestamp == null) {
+            nexradDiag('sync.skipped', {
+                isNexrad: state.isNexrad,
+                site: state.nexradSite,
+                nexradTimestamp: state.nexradTimestamp,
+            });
+            this.destroy();
+            syncTotal.end({ outcome: 'skippedNotNexradOrMissing' });
+            return;
+        }
+
+        if (!ensureRadarArchiveBindings('sync')) {
+            syncTotal.end({ outcome: 'skippedMissingArchiveBindings' });
+            return;
+        }
+
+        const tAuth = nexradPerfSpan('sync.setArchiveAuth');
+        setNexradArchiveApiKey(this.core.apiKey || '');
+        setNexradArchiveBundleId(this.core.bundleId || '');
+        setNexradSitesFetchAuth(this.core.apiKey || '', this.core.bundleId || '');
+        tAuth.end({});
+
+        const unix = Number(state.nexradTimestamp);
+        nexradDiag('sync.enter', {
+            site: state.nexradSite,
+            unix,
+            product: state.nexradProduct,
+            source: state.nexradDataSource,
+            apiKeyLen: (this.core.apiKey || '').length,
+        });
+
+        const tParams = nexradPerfSpan('sync.buildFetchParams');
+        const p = this._buildFetchParamsForUnix(state, unix);
+        tParams.end({ ok: !!p });
+        if (!p) {
+            const ctx = this._resolveListingContext(state);
+            nexradDiag('sync.abortedNoFetchParams', {
+                site: state.nexradSite,
+                unix,
+                cacheKey: ctx.nk,
+                timeToKeyMapSize: Object.keys(ctx.timeToKeyMap || {}).length,
+                sampleTimeKeys: Object.keys(ctx.timeToKeyMap || {}).slice(0, 8),
+            });
+            syncTotal.end({ outcome: 'noFetchParams' });
+            return;
+        }
+
+        const tIdentity = nexradPerfSpan('sync.syncIdentity');
+        const syncKey = this._syncIdentity(state, p, unix);
+        tIdentity.end({ syncKeyTail: syncKey.slice(-96), lastSyncKeyMatch: syncKey === this._lastSyncKey });
+
+        const jsCachedForShortCircuit = this._frameCache.get(p.fetchKey);
+        if (syncKey === this._lastSyncKey && this._nativeFrameUploaded && jsCachedForShortCircuit) {
+            nexradDiag('sync.styleOnlyShortCircuit', { site: state.nexradSite });
+            const tStyle = nexradPerfSpan('sync.shortCircuit_styleOnly');
+            this.applyStyleFromState(state);
+            tStyle.end({});
+            syncTotal.end({ outcome: 'styleOnlyShortCircuit' });
+            return;
+        }
+
+        const tCacheLookup = nexradPerfSpan('sync.memoryCacheLookup');
+        const cached = this._frameCache.get(p.fetchKey);
+        tCacheLookup.end({ hit: !!cached, cacheSize: this._frameCache.size, fetchKeyTail: p.fetchKey.slice(-80) });
+
+        const tGpuTry = nexradPerfSpan('sync.tryGpuCacheActivate');
+        if (cached && this._nativeGpuReadyKeys.has(syncKey)) {
+            const n = this._native();
+            if (n?.activateNexradCachedFrame) {
+                nexradDiag('sync.gpuCacheActivate.enter', {
+                    site: state.nexradSite,
+                    unix,
+                    syncKeyTail: syncKey.slice(-80),
+                    gpuReadySetSize: this._nativeGpuReadyKeys.size,
+                });
+                const tAct = nexradPerfSpan('sync.dispatchActivateCachedFrame');
+                n.activateNexradCachedFrame(syncKey);
+                tAct.end({ keyLen: syncKey.length });
+                const tStyle = nexradPerfSpan('sync.applyStyleAfterGpuActivate');
+                this.applyStyleFromState(state);
+                tStyle.end({});
+                const meta = this._uploadMetaBySyncKey.get(syncKey);
+                if (meta) {
+                    this._lastUploadMeta = { valueScale: meta.valueScale, valueOffset: meta.valueOffset };
+                }
+                this._lastSyncKey = syncKey;
+                this._nativeFrameUploaded = true;
+                tGpuTry.end({ outcome: 'gpuCacheActivate', gpuReadySetSize: this._nativeGpuReadyKeys.size });
+                syncTotal.end({ outcome: 'gpuCacheActivate' });
+                return;
+            }
+        }
+        tGpuTry.end({
+            outcome: 'noGpuActivate',
+            hasJsCachedFrame: !!cached,
+            gpuReadyForSyncKey: this._nativeGpuReadyKeys.has(syncKey),
+            hasActivateMethod: !!this._native()?.activateNexradCachedFrame,
+        });
+
+        if (cached) {
+            nexradDiag('sync.uploadFromCache', { fetchKeyTail: p.fetchKey.slice(-80) });
+            const tUpload = nexradPerfSpan('sync.uploadFromMemoryCache_toNative');
+            this._uploadFrameToNative(state, cached, p, unix);
+            tUpload.end({});
+            this._lastSyncKey = syncKey;
+            syncTotal.end({ outcome: 'memoryCacheHit' });
+            return;
+        }
+
+        this._abort?.abort();
+        this._abort = new AbortController();
+
+        nexradDiag('fetch.start', { objectKey: p.objectKey, radarVar: p.radarVar, radarSource: p.radarSource });
+
+        let frame;
+        try {
+            frame = await this._fetchFrame(state, unix, {
+                signal: this._abort.signal,
+                priority: 'display',
+            });
+        } catch (err) {
+            nexradDiag('fetch.error', { message: err?.message || String(err) });
+            syncTotal.end({ outcome: 'fetchThrew', message: err?.message || String(err) });
+            return;
+        }
+
+        if (!frame || this._abort.signal.aborted) {
+            nexradDiag('fetch.noFrame', { aborted: this._abort.signal.aborted, hadFrame: !!frame });
+            syncTotal.end({
+                outcome: 'fetchNoFrame',
+                aborted: this._abort.signal.aborted,
+                hadFrame: !!frame,
+            });
+            return;
+        }
+
+        const tPut = nexradPerfSpan('sync.frameCacheSet');
+        this._frameCache.set(p.fetchKey, frame);
+        tPut.end({ cacheSizeAfter: this._frameCache.size });
+
+        nexradDiag('fetch.ok', { fetchKeyTail: p.fetchKey.slice(-80) });
+        const tUploadFetched = nexradPerfSpan('sync.uploadFetchedFrame_toNative');
+        this._uploadFrameToNative(state, frame, p, unix);
+        tUploadFetched.end({});
+        this._lastSyncKey = syncKey;
+        syncTotal.end({ outcome: 'fetchedAndUploaded' });
+    }
+
+    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 uploadOptsForReadout = mapboxFrameUploadOptionsForNexradState(state);
+        const gpuFrame = this._getPreparedReadoutFrame(frame, uploadOptsForReadout);
+        const sample = sampleNexradFrameAtLatLon(gpuFrame, lat, lng, { smoothPolar: this._gateSmoothing });
+        if (!sample) {
+            return null;
+        }
+
+        const valueMs = sample.value;
+        const isHydro = radarSource === 'level3' && nexradLevel3IsHydrometeorClassification(radarVariable);
+
+        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);
+            const bu = state.colormapBaseUnit;
+            if (bu != null && String(bu).length > 0 && String(bu).toLowerCase() !== 'none') {
+                unitOut = bu;
+            }
+        }
+
+        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 {
+            // Do not apply the colormap *lower* stop as a hard readout floor: weak echoes below the first
+            // legend tick can still be drawn (LUT / GL), and users expect a number there.
+            inRange = 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,
+        };
+    }
+}