@aguacerowx/react-native 0.0.46 → 0.0.49

package/lib/module/nexrad/nexradAndroidController.js

@@ -0,0 +1,1013 @@
+/**
+ * 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
+    };
+  }
+}
+//# sourceMappingURL=nexradAndroidController.js.map