@aguacerowx/react-native 0.0.50 → 0.0.52

package/src/nexrad/nexradAndroidController.js

@@ -1,1068 +1,1078 @@
-/**
- * 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,
-    setNexradArchiveSiteOrigin,
-    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 { Platform } from 'react-native';
-import { 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';
-    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). */
-/** iOS Metal uploads benefit from overlapping fetches; keep Android at 1 for steadier radio/CPU. */
-const PRELOAD_CONCURRENCY = Platform.OS === 'ios' ? 2 : 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(96);
-                    }
-                });
-            }
-        } catch (err) {
-            /* ignore */
-        }
-        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 || '');
-        }
-        setNexradArchiveSiteOrigin(core.gridRequestSiteOrigin || '');
-    }
-
-    _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() {
-        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}`;
-    }
-
-    /**
-     * After JS decoded a frame into `_frameCache`, optionally push it through the native bridge.
-     * During timeline preload we **only** upload the **currently displayed** unix to Metal; other
-     * volumes stay in the JS cache until {@link sync} needs them (avoids 40+ full decodes on load).
-     */
-    _primeNativeGpuUploadIfNeeded(snapshot, unix, p, frame, abortSignal) {
-        if (!frame || !p || (abortSignal && abortSignal.aborted)) return;
-        try {
-            const displayUx =
-                snapshot.nexradTimestamp != null && Number.isFinite(Number(snapshot.nexradTimestamp))
-                    ? Number(snapshot.nexradTimestamp)
-                    : NaN;
-            if (Number.isFinite(displayUx) && Number(unix) !== displayUx) {
-                return;
-            }
-            const syncKey = this._syncIdentity(snapshot, p, unix);
-            if (this._nativeGpuReadyKeys.has(syncKey)) {
-                return;
-            }
-            if (!this._native()?.uploadNexradFrame) {
-                return;
-            }
-            this._uploadFrameToNative(snapshot, frame, p, unix);
-        } catch (err) {
-            /* ignore */
-        }
-    }
-
-    /**
-     * @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) {
-            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)) {
-                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;
-            }
-            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,
-        );
-
-        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) {
-            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 times = [...(state.availableNexradTimestamps || [])]
-            .map(Number)
-            .filter((t) => Number.isFinite(t));
-        if (!times.length) {
-            // Important: do not touch `_preloadTimelineSig` or the frame cache here — callers
-            // sometimes pass `core.state` before `availableNexradTimestamps` is committed; an
-            // empty list must not poison the signature or wipe the LRU (see WeatherLayerManager
-            // preload kick merging subscription snapshot).
-            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;
-
-        // Keep frames that are still in the new timeline (or the currently displayed one)
-        // to avoid re-fetching them when expanding the duration window.
-        const validFetchKeys = new Set();
-        for (const unix of times) {
-            const p = this._buildFetchParamsForUnix(state, unix);
-            if (p) validFetchKeys.add(p.fetchKey);
-        }
-        
-        const curP = Number.isFinite(curUnix) ? this._buildFetchParamsForUnix(state, curUnix) : null;
-        if (curP) validFetchKeys.add(curP.fetchKey);
-
-        for (const key of this._frameCache.keys()) {
-            if (!validFetchKeys.has(key)) {
-                this._frameCache.delete(key);
-            }
-        }
-        // Do NOT clear `_nativeGpuReadyKeys` / JSON LRU / upload meta here: that forced a full
-        // ~1MB JSON parse + native decode on every timeline scrub after prefetch. GPU cache keys
-        // stay valid while Metal still holds the slot; `sync` falls back to full upload if needed.
-        // (Controller `destroy()` still clears everything on site/mode teardown.)
-
-        setNexradArchiveApiKey(this.core.apiKey || '');
-        setNexradArchiveBundleId(this.core.bundleId || '');
-        setNexradArchiveSiteOrigin(this.core.gridRequestSiteOrigin || '');
-        setNexradSitesFetchAuth(this.core.apiKey || '', this.core.bundleId || '');
-
-
-        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 () => {
-            // Prime the visible unix first so the active frame hits GPU before background slots.
-            const curUx =
-                snapshot.nexradTimestamp != null && Number.isFinite(Number(snapshot.nexradTimestamp))
-                    ? Number(snapshot.nexradTimestamp)
-                    : NaN;
-            if (Number.isFinite(curUx)) {
-                const p0 = this._buildFetchParamsForUnix(snapshot, curUx);
-                if (p0) {
-                    const fr0 = this._frameCache.get(p0.fetchKey);
-                    if (fr0) {
-                        this._primeNativeGpuUploadIfNeeded(snapshot, curUx, p0, fr0, signal);
-                        await yieldToJsEventLoop();
-                    }
-                }
-            }
-
-            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++;
-                        const cachedFrame = this._frameCache.get(p.fetchKey);
-                        this._primeNativeGpuUploadIfNeeded(snapshot, unix, p, cachedFrame, signal);
-                        await yieldToJsEventLoop();
-                        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++;
-                                this._primeNativeGpuUploadIfNeeded(snapshot, unix, p, frame, signal);
-                                await yieldToJsEventLoop();
-                                slot.end({
-                                    outcome: 'cachedFrame',
-                                    fetchKeyTail: p.fetchKey.slice(-64),
-                                    cacheSizeAfter: this._frameCache.size,
-                                });
-                            } else {
-                                slot.end({ outcome: 'noFrame', aborted: signal.aborted });
-                            }
-                        } catch (err) {
-                            preloadFailed++;
-                            slot.end({ outcome: 'error', message: err?.message || String(err) });
-                        }
-                    }
-                    await yieldToJsEventLoop();
-                }
-            };
-            await Promise.all(Array.from({ length: PRELOAD_CONCURRENCY }, () => work()));
-
-            // Catch-up: any unix still missing a GPU slot (e.g. layer mounted mid-preload) gets one upload pass.
-            if (!signal.aborted) {
-                for (let i = 0; i < times.length && !signal.aborted; i++) {
-                    const unix = times[i];
-                    const p = this._buildFetchParamsForUnix(snapshot, unix);
-                    if (!p) continue;
-                    const frame = this._frameCache.get(p.fetchKey);
-                    if (!frame) continue;
-                    const syncKey = this._syncIdentity(snapshot, p, unix);
-                    if (this._nativeGpuReadyKeys.has(syncKey)) continue;
-                    this._primeNativeGpuUploadIfNeeded(snapshot, unix, p, frame, signal);
-                    await yieldToJsEventLoop();
-                }
-            }
-
-            preloadBatch.end({
-                outcome: signal.aborted ? 'aborted' : 'complete',
-                completed: preloadCompleted,
-                failed: preloadFailed,
-                skippedCached: preloadSkippedCached,
-                finalCacheSize: this._frameCache.size,
-                gpuReadyCount: this._nativeGpuReadyKeys.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) {
-            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 || '');
-        setNexradArchiveSiteOrigin(this.core.gridRequestSiteOrigin || '');
-        setNexradSitesFetchAuth(this.core.apiKey || '', this.core.bundleId || '');
-        tAuth.end({});
-
-        const unix = Number(state.nexradTimestamp);
-
-        const tParams = nexradPerfSpan('sync.buildFetchParams');
-        const p = this._buildFetchParamsForUnix(state, unix);
-        tParams.end({ ok: !!p });
-        if (!p) {
-            const ctx = this._resolveListingContext(state);
-            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) {
-            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) {
-                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) {
-            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();
-
-
-        let frame;
-        try {
-            frame = await this._fetchFrame(state, unix, {
-                signal: this._abort.signal,
-                priority: 'display',
-            });
-        } catch (err) {
-            syncTotal.end({ outcome: 'fetchThrew', message: err?.message || String(err) });
-            return;
-        }
-
-        if (!frame || this._abort.signal.aborted) {
-            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 });
-
-        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,
-        };
-    }
-}
+/**
+ * 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,
+    setNexradArchiveSiteOrigin,
+    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 { Platform } from 'react-native';
+import { nexradDiagBootSnapshot, nexradDiagGateTextureSummary, nexradPerfSpan } from './nexradDiag.js';
+import { aguaceroDebug, getAguaceroAuthDiagnosticSnapshot, isAguaceroRnDebugEnabled } from '../aguaceroRnDebug';
+
+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';
+    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). */
+/** iOS Metal uploads benefit from overlapping fetches; keep Android at 1 for steadier radio/CPU. */
+const PRELOAD_CONCURRENCY = Platform.OS === 'ios' ? 2 : 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(96);
+                    }
+                });
+            }
+        } catch (err) {
+            /* ignore */
+        }
+        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 || '');
+        }
+        setNexradArchiveSiteOrigin(core.gridRequestSiteOrigin || 'https://localhost');
+        if (isAguaceroRnDebugEnabled()) {
+            aguaceroDebug('nexrad.authConfigured', getAguaceroAuthDiagnosticSnapshot(core, { phase: 'NexradAndroidController.constructor' }));
+        }
+    }
+
+    _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() {
+        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}`;
+    }
+
+    /**
+     * After JS decoded a frame into `_frameCache`, optionally push it through the native bridge.
+     * During timeline preload we **only** upload the **currently displayed** unix to Metal; other
+     * volumes stay in the JS cache until {@link sync} needs them (avoids 40+ full decodes on load).
+     */
+    _primeNativeGpuUploadIfNeeded(snapshot, unix, p, frame, abortSignal) {
+        if (!frame || !p || (abortSignal && abortSignal.aborted)) return;
+        try {
+            const displayUx =
+                snapshot.nexradTimestamp != null && Number.isFinite(Number(snapshot.nexradTimestamp))
+                    ? Number(snapshot.nexradTimestamp)
+                    : NaN;
+            if (Number.isFinite(displayUx) && Number(unix) !== displayUx) {
+                return;
+            }
+            const syncKey = this._syncIdentity(snapshot, p, unix);
+            if (this._nativeGpuReadyKeys.has(syncKey)) {
+                return;
+            }
+            if (!this._native()?.uploadNexradFrame) {
+                return;
+            }
+            this._uploadFrameToNative(snapshot, frame, p, unix);
+        } catch (err) {
+            /* ignore */
+        }
+    }
+
+    /**
+     * @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) {
+            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)) {
+                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;
+            }
+            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,
+        );
+
+        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) {
+            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 times = [...(state.availableNexradTimestamps || [])]
+            .map(Number)
+            .filter((t) => Number.isFinite(t));
+        if (!times.length) {
+            // Important: do not touch `_preloadTimelineSig` or the frame cache here — callers
+            // sometimes pass `core.state` before `availableNexradTimestamps` is committed; an
+            // empty list must not poison the signature or wipe the LRU (see WeatherLayerManager
+            // preload kick merging subscription snapshot).
+            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;
+
+        // Keep frames that are still in the new timeline (or the currently displayed one)
+        // to avoid re-fetching them when expanding the duration window.
+        const validFetchKeys = new Set();
+        for (const unix of times) {
+            const p = this._buildFetchParamsForUnix(state, unix);
+            if (p) validFetchKeys.add(p.fetchKey);
+        }
+        
+        const curP = Number.isFinite(curUnix) ? this._buildFetchParamsForUnix(state, curUnix) : null;
+        if (curP) validFetchKeys.add(curP.fetchKey);
+
+        for (const key of this._frameCache.keys()) {
+            if (!validFetchKeys.has(key)) {
+                this._frameCache.delete(key);
+            }
+        }
+        // Do NOT clear `_nativeGpuReadyKeys` / JSON LRU / upload meta here: that forced a full
+        // ~1MB JSON parse + native decode on every timeline scrub after prefetch. GPU cache keys
+        // stay valid while Metal still holds the slot; `sync` falls back to full upload if needed.
+        // (Controller `destroy()` still clears everything on site/mode teardown.)
+
+        setNexradArchiveApiKey(this.core.apiKey || '');
+        setNexradArchiveBundleId(this.core.bundleId || '');
+        setNexradArchiveSiteOrigin(this.core.gridRequestSiteOrigin || 'https://localhost');
+        setNexradSitesFetchAuth(this.core.apiKey || '', this.core.bundleId || '');
+        if (isAguaceroRnDebugEnabled()) {
+            aguaceroDebug('nexrad.authConfigured', getAguaceroAuthDiagnosticSnapshot(this.core, {
+                phase: 'NexradAndroidController.preload',
+                site: state.nexradSite,
+                product: state.nexradProduct,
+            }));
+        }
+
+        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 () => {
+            // Prime the visible unix first so the active frame hits GPU before background slots.
+            const curUx =
+                snapshot.nexradTimestamp != null && Number.isFinite(Number(snapshot.nexradTimestamp))
+                    ? Number(snapshot.nexradTimestamp)
+                    : NaN;
+            if (Number.isFinite(curUx)) {
+                const p0 = this._buildFetchParamsForUnix(snapshot, curUx);
+                if (p0) {
+                    const fr0 = this._frameCache.get(p0.fetchKey);
+                    if (fr0) {
+                        this._primeNativeGpuUploadIfNeeded(snapshot, curUx, p0, fr0, signal);
+                        await yieldToJsEventLoop();
+                    }
+                }
+            }
+
+            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++;
+                        const cachedFrame = this._frameCache.get(p.fetchKey);
+                        this._primeNativeGpuUploadIfNeeded(snapshot, unix, p, cachedFrame, signal);
+                        await yieldToJsEventLoop();
+                        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++;
+                                this._primeNativeGpuUploadIfNeeded(snapshot, unix, p, frame, signal);
+                                await yieldToJsEventLoop();
+                                slot.end({
+                                    outcome: 'cachedFrame',
+                                    fetchKeyTail: p.fetchKey.slice(-64),
+                                    cacheSizeAfter: this._frameCache.size,
+                                });
+                            } else {
+                                slot.end({ outcome: 'noFrame', aborted: signal.aborted });
+                            }
+                        } catch (err) {
+                            preloadFailed++;
+                            slot.end({ outcome: 'error', message: err?.message || String(err) });
+                        }
+                    }
+                    await yieldToJsEventLoop();
+                }
+            };
+            await Promise.all(Array.from({ length: PRELOAD_CONCURRENCY }, () => work()));
+
+            // Catch-up: any unix still missing a GPU slot (e.g. layer mounted mid-preload) gets one upload pass.
+            if (!signal.aborted) {
+                for (let i = 0; i < times.length && !signal.aborted; i++) {
+                    const unix = times[i];
+                    const p = this._buildFetchParamsForUnix(snapshot, unix);
+                    if (!p) continue;
+                    const frame = this._frameCache.get(p.fetchKey);
+                    if (!frame) continue;
+                    const syncKey = this._syncIdentity(snapshot, p, unix);
+                    if (this._nativeGpuReadyKeys.has(syncKey)) continue;
+                    this._primeNativeGpuUploadIfNeeded(snapshot, unix, p, frame, signal);
+                    await yieldToJsEventLoop();
+                }
+            }
+
+            preloadBatch.end({
+                outcome: signal.aborted ? 'aborted' : 'complete',
+                completed: preloadCompleted,
+                failed: preloadFailed,
+                skippedCached: preloadSkippedCached,
+                finalCacheSize: this._frameCache.size,
+                gpuReadyCount: this._nativeGpuReadyKeys.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) {
+            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 || '');
+        setNexradArchiveSiteOrigin(this.core.gridRequestSiteOrigin || 'https://localhost');
+        setNexradSitesFetchAuth(this.core.apiKey || '', this.core.bundleId || '');
+        tAuth.end({});
+
+        const unix = Number(state.nexradTimestamp);
+
+        const tParams = nexradPerfSpan('sync.buildFetchParams');
+        const p = this._buildFetchParamsForUnix(state, unix);
+        tParams.end({ ok: !!p });
+        if (!p) {
+            const ctx = this._resolveListingContext(state);
+            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) {
+            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) {
+                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) {
+            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();
+
+
+        let frame;
+        try {
+            frame = await this._fetchFrame(state, unix, {
+                signal: this._abort.signal,
+                priority: 'display',
+            });
+        } catch (err) {
+            syncTotal.end({ outcome: 'fetchThrew', message: err?.message || String(err) });
+            return;
+        }
+
+        if (!frame || this._abort.signal.aborted) {
+            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 });
+
+        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,
+        };
+    }
+}