@aguacerowx/react-native 0.0.42 → 0.0.44

package/lib/commonjs/android/src/main/java/com/aguacerowx/reactnative/NexradRadarLayerView.java

@@ -0,0 +1,515 @@
+package com.aguacerowx.reactnative;
+
+import android.app.Activity;
+import android.os.Handler;
+import android.os.Looper;
+import android.util.Base64;
+import android.util.Log;
+import android.view.View;
+import android.view.ViewGroup;
+import android.widget.FrameLayout;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import java.util.Locale;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.WritableMap;
+import com.facebook.react.modules.core.DeviceEventManagerModule;
+import com.facebook.react.uimanager.ThemedReactContext;
+import com.mapbox.maps.LayerPosition;
+import com.mapbox.maps.MapView;
+import com.mapbox.maps.MapboxMap;
+import com.mapbox.maps.Style;
+
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+/**
+ * Hosts {@link NexradRadarLayer} on the app {@link MapView} (Android-only NEXRAD path).
+ */
+public class NexradRadarLayerView extends FrameLayout {
+
+    /**
+     * Stable Mapbox style layer id (must match JS {@code AGUACERO_NEXRAD_MAP_LAYER_ID}) so NWS alerts
+     * fill/line stacking matches mapsgl / {@link WeatherLayerManager} on web.
+     */
+    public static final String NEXRAD_LAYER_ID = "aguacero-nexrad-custom-layer";
+
+    private final NexradRadarLayer radarLayer;
+    private final String layerId;
+    private static final String TAG = "AguaceroNexradView";
+    private MapView mapView;
+    private boolean isLayerAdded = false;
+    private String belowLayerID = null;
+    /** One-shot: after first add, re-check z-order once the weather grid layer may have appeared. */
+    private boolean nexradReparentScheduled = false;
+
+    /**
+     * JSON + Base64 decode is megabytes per frame — must not run on the RN UI thread (mirrors mapsgl
+     * doing heavy prep off the repaint hot path).
+     */
+    private final ExecutorService nexradDecodeExecutor =
+            Executors.newSingleThreadExecutor(
+                    r -> {
+                        Thread t = new Thread(r, "aguacero-nexrad-decode");
+                        t.setPriority(Thread.NORM_PRIORITY - 1);
+                        return t;
+                    });
+
+    /**
+     * Bumped only by {@link #clearNexrad()} so in-flight decodes are dropped after an explicit clear.
+     * Do not increment on every upload: uploads are queued on a single-thread executor while the RN bridge
+     * can enqueue many frames quickly—incrementing per upload makes every {@code post()} appear stale
+     * ({@code gen != current}) and nothing ever draws.
+     */
+    private final AtomicInteger decodeGeneration = new AtomicInteger(0);
+
+    /** Monotonic id for perf logs (independent of {@link #decodeGeneration}). */
+    private final AtomicInteger decodeSeq = new AtomicInteger(0);
+
+    /**
+     * Apply decoded frames on the process main looper. {@link View#post} from a background thread can
+     * enqueue on the view run-queue while {@code mAttachInfo} is null (common during RN layout), and those
+     * runnables may never execute — so {@link #requestFullFrameUpload} never runs ({@code hasFrame=false}).
+     */
+    private final Handler mainHandler = new Handler(Looper.getMainLooper());
+
+    public NexradRadarLayerView(@NonNull ThemedReactContext context) {
+        super(context);
+        final ThemedReactContext reactContext = context;
+        this.radarLayer =
+                new NexradRadarLayer(
+                        context.getApplicationContext(),
+                        (cacheKey) -> {
+                            if (cacheKey == null || cacheKey.isEmpty()) {
+                                return;
+                            }
+                            reactContext.runOnUiQueueThread(
+                                    () -> {
+                                        try {
+                                            WritableMap m = Arguments.createMap();
+                                            m.putString("nativeGpuCacheKey", cacheKey);
+                                            reactContext
+                                                    .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
+                                                    .emit("AguaceroNexradGpuFrameReady", m);
+                                        } catch (Throwable t) {
+                                            Log.w(TAG, "[NEXRAD] emit AguaceroNexradGpuFrameReady failed", t);
+                                        }
+                                    });
+                        });
+        this.layerId = NEXRAD_LAYER_ID;
+    }
+
+    public void setBelowID(String belowID) {
+        this.belowLayerID = belowID;
+    }
+
+    @Override
+    protected void onLayout(boolean changed, int left, int top, int right, int bottom) {
+        super.onLayout(changed, left, top, right, bottom);
+        findMapViewAndAddLayer();
+    }
+
+    private void findMapViewAndAddLayer() {
+        // Custom layers are dropped on full style reloads — re-add when our id is missing.
+        if (mapView != null) {
+            Style existing = mapView.getMapboxMap().getStyle();
+            if (existing != null && existing.isStyleLoaded() && existing.styleLayerExists(layerId)) {
+                isLayerAdded = true;
+                return;
+            }
+        }
+
+        Activity activity = ((ThemedReactContext) getContext()).getCurrentActivity();
+        if (activity == null) {
+            Log.w(TAG, "[NEXRAD] findMapView: getCurrentActivity() is null");
+            return;
+        }
+        View rootView = activity.findViewById(android.R.id.content);
+        if (rootView == null) {
+            Log.w(TAG, "[NEXRAD] findMapView: content root is null");
+            return;
+        }
+        MapView foundMap = findMapViewRecursive(rootView);
+        if (foundMap == null) {
+            Log.w(TAG, "[NEXRAD] findMapView: no MapView under activity content (recursive search)");
+            return;
+        }
+        this.mapView = foundMap;
+        final MapboxMap mapboxMap = mapView.getMapboxMap();
+        Style.OnStyleLoaded styleLoadedCallback = style -> {
+            if (!style.styleLayerExists(layerId)) {
+                LayerPosition position = null;
+                String anchor = null;
+                // Place radar above the weather grid (both share the same terrain anchor otherwise
+                // Mapbox can stack the grid on top and hide NEXRAD entirely).
+                if (style.styleLayerExists(AguaceroStyleLayerIds.WEATHER_GRID_CUSTOM_LAYER)) {
+                    position = new LayerPosition(AguaceroStyleLayerIds.WEATHER_GRID_CUSTOM_LAYER, null, null);
+                    anchor = "above:" + AguaceroStyleLayerIds.WEATHER_GRID_CUSTOM_LAYER;
+                } else if (this.belowLayerID != null && style.styleLayerExists(this.belowLayerID)) {
+                    position = new LayerPosition(null, this.belowLayerID, null);
+                    anchor = "below:" + this.belowLayerID;
+                }
+                style.addStyleCustomLayer(layerId, radarLayer, position);
+                isLayerAdded = true;
+                if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                    Log.i(TAG, "[NEXRAD] custom layer registered id=" + layerId + " position=" + anchor);
+                }
+                triggerRepaint();
+                if (anchor == null || anchor.startsWith("below:")) {
+                    scheduleReparentAboveGridOnce();
+                }
+            }
+        };
+        Style currentStyle = mapboxMap.getStyle();
+        if (currentStyle != null && currentStyle.isStyleLoaded()) {
+            styleLoadedCallback.onStyleLoaded(currentStyle);
+        } else {
+            mapboxMap.getStyle(styleLoadedCallback);
+        }
+    }
+
+    private void scheduleReparentAboveGridOnce() {
+        if (nexradReparentScheduled || mapView == null) return;
+        nexradReparentScheduled = true;
+        mapView.postDelayed(() -> {
+            nexradReparentScheduled = false;
+            reparentNexradAboveGridIfNeeded();
+        }, 350);
+    }
+
+    /**
+     * If the weather grid registered after NEXRAD, the radar layer can sit under the grid and show nothing.
+     * Re-insert once above {@link AguaceroStyleLayerIds#WEATHER_GRID_CUSTOM_LAYER} when both exist.
+     */
+    private void reparentNexradAboveGridIfNeeded() {
+        try {
+            if (mapView == null) return;
+            MapboxMap m = mapView.getMapboxMap();
+            Style s = m.getStyle();
+            if (s == null || !s.isStyleLoaded()) return;
+            if (!s.styleLayerExists(layerId)) return;
+            if (!s.styleLayerExists(AguaceroStyleLayerIds.WEATHER_GRID_CUSTOM_LAYER)) return;
+            s.removeStyleLayer(layerId);
+            isLayerAdded = false;
+            LayerPosition pos = new LayerPosition(AguaceroStyleLayerIds.WEATHER_GRID_CUSTOM_LAYER, null, null);
+            s.addStyleCustomLayer(layerId, radarLayer, pos);
+            isLayerAdded = true;
+            if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                Log.i(TAG, "[NEXRAD] reparented above " + AguaceroStyleLayerIds.WEATHER_GRID_CUSTOM_LAYER);
+            }
+            triggerRepaint();
+        } catch (Throwable t) {
+            Log.w(TAG, "[NEXRAD] reparent above grid skipped", t);
+        }
+    }
+
+    private MapView findMapViewRecursive(View view) {
+        if (view instanceof MapView) return (MapView) view;
+        if (view instanceof ViewGroup) {
+            ViewGroup viewGroup = (ViewGroup) view;
+            for (int i = 0; i < viewGroup.getChildCount(); i++) {
+                MapView found = findMapViewRecursive(viewGroup.getChildAt(i));
+                if (found != null) return found;
+            }
+        }
+        return null;
+    }
+
+    private void triggerRepaint() {
+        if (mapView != null) mapView.post(mapView.getMapboxMap()::triggerRepaint);
+    }
+
+    private static double nanoToMs(long startNanos) {
+        return (System.nanoTime() - startNanos) / 1_000_000.0;
+    }
+
+    private static byte[] decodeRleGateData(byte[] compressed, int expectedSize) {
+        byte[] out = new byte[expectedSize];
+        int outIdx = 0;
+        int inIdx = 0;
+        while (inIdx + 3 < compressed.length && outIdx < expectedSize) {
+            int count = (compressed[inIdx] & 0xFF) | ((compressed[inIdx + 1] & 0xFF) << 8);
+            byte val0 = compressed[inIdx + 2];
+            byte val1 = compressed[inIdx + 3];
+            inIdx += 4;
+            for (int i = 0; i < count && outIdx + 1 < expectedSize; i++) {
+                out[outIdx++] = val0;
+                out[outIdx++] = val1;
+            }
+        }
+        return out;
+    }
+
+    public void uploadFrameFromJson(String json) {
+        // Snapshot while enqueueing (RN bridge thread). If clearNexrad() bumps the generation after this,
+        // the worker must not apply — even if it starts running later (matches clear semantics).
+        final int genSnapshot = decodeGeneration.get();
+        final int jsonChars = json != null ? json.length() : 0;
+        final long tEnqueue = System.nanoTime();
+        final String jsonSnapshot = json;
+        nexradDecodeExecutor.execute(
+                () -> {
+                    final int seq = decodeSeq.incrementAndGet();
+                    final double queueToWorkerMs = nanoToMs(tEnqueue);
+                    final long tWorker = System.nanoTime();
+                    try {
+                        long mark = System.nanoTime();
+                        JSONObject o = new JSONObject(jsonSnapshot);
+                        final double jsonParseMs = nanoToMs(mark);
+
+                        mark = System.nanoTime();
+                        byte[] gateRaw = Base64.decode(o.getString("gateB64"), Base64.DEFAULT);
+                        final double gateB64DecodeMs = nanoToMs(mark);
+
+                        mark = System.nanoTime();
+                        int nGates = o.getInt("nGates");
+                        int nRays = o.getInt("nRays");
+                        final byte[] gateBytes =
+                                o.optBoolean("gateIsRle", false)
+                                        ? decodeRleGateData(gateRaw, nGates * nRays * 2)
+                                        : gateRaw;
+                        double stationLat = o.getDouble("stationLat");
+                        double stationLon = o.getDouble("stationLon");
+                        float firstGateKm = (float) o.getDouble("firstGateKm");
+                        float gateWidthKm = (float) o.getDouble("gateWidthKm");
+                        final double scalarFieldsMs = nanoToMs(mark);
+
+                        mark = System.nanoTime();
+                        JSONArray rayArr = o.getJSONArray("rayBoundaries");
+                        float[] ray = new float[rayArr.length()];
+                        for (int i = 0; i < ray.length; i++) {
+                            ray[i] = (float) rayArr.getDouble(i);
+                        }
+                        final double rayArrayMs = nanoToMs(mark);
+                        
+                        mark = System.nanoTime();
+                        JSONObject uploadOpts = o.optJSONObject("uploadOpts");
+                        String geometryLayoutKey = uploadOpts != null ? uploadOpts.optString("geometryLayoutKey", "") : "";
+                        RadarFrameGpuMatch.Result gpuMatchResult = RadarFrameGpuMatch.prepareRadarFrameForGpuReadout(
+                                nRays, nGates, gateBytes, ray, geometryLayoutKey);
+                        final byte[] finalGateBytes = gpuMatchResult.gateData;
+                        final float[] finalRay = gpuMatchResult.rayBoundariesDeg;
+                        final double gpuMatchMs = nanoToMs(mark);
+
+                        mark = System.nanoTime();
+                        byte[] lut = Base64.decode(o.getString("lutB64"), Base64.DEFAULT);
+                        final double lutB64DecodeMs = nanoToMs(mark);
+
+                        mark = System.nanoTime();
+                        float valueScale = (float) o.getDouble("valueScale");
+                        float valueOffset = (float) o.getDouble("valueOffset");
+                        float lutMin = (float) o.getDouble("lutMin");
+                        float lutMax = (float) o.getDouble("lutMax");
+                        float discrete = (float) o.getDouble("discreteIntegerLut");
+                        float opacity = (float) o.getDouble("opacity");
+                        float gateSmooth = (float) o.getDouble("gateSmoothPolar");
+                        int interpolateLut = o.optInt("interpolateLut", 1);
+                        final String nativeGpuCacheKeyRaw = o.optString("nativeGpuCacheKey", "");
+                        final @Nullable String nativeGpuCacheKeyForUpload =
+                                nativeGpuCacheKeyRaw.isEmpty() ? null : nativeGpuCacheKeyRaw;
+                        final double styleScalarsMs = nanoToMs(mark);
+
+                        mark = System.nanoTime();
+                        String geomKey = NexradRadarLayer.buildGeometryCacheKey(
+                                nRays, nGates, stationLat, stationLon, firstGateKm, gateWidthKm, finalRay);
+                        final RadarRayGeometryBuilder.Result finalGeomResult;
+                        if (!radarLayer.isGeometryCommitted(geomKey)) {
+                            finalGeomResult = RadarRayGeometryBuilder.build(
+                                    nRays, nGates, stationLat, stationLon, firstGateKm, gateWidthKm, finalRay);
+                        } else {
+                            finalGeomResult = null;
+                        }
+                        final double geomBuildMs = nanoToMs(mark);
+
+                        final double decodeThreadTotalMs = nanoToMs(tWorker);
+                        final long tDecodeDone = System.nanoTime();
+
+                        if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                            Log.i(
+                                    TAG,
+                                    String.format(
+                                            Locale.US,
+                                            "[NEXRAD][PERF] decodeWorker seq=%d genSnapshot=%d jsonChars=%d queueToWorkerMs=%.2f "
+                                                    + "jsonParseMs=%.2f gateB64DecodeMs=%.2f scalarFieldsMs=%.2f rayArrayMs=%.2f "
+                                                    + "gpuMatchMs=%.2f lutB64DecodeMs=%.2f styleScalarsMs=%.2f geomBuildMs=%.2f decodeThreadTotalMs=%.2f "
+                                                    + "gateBytes=%d nGates=%d nRays=%d lutBytes=%d",
+                                            seq,
+                                            genSnapshot,
+                                            jsonChars,
+                                            queueToWorkerMs,
+                                            jsonParseMs,
+                                            gateB64DecodeMs,
+                                            scalarFieldsMs,
+                                            rayArrayMs,
+                                            gpuMatchMs,
+                                            lutB64DecodeMs,
+                                            styleScalarsMs,
+                                            geomBuildMs,
+                                            decodeThreadTotalMs,
+                                            finalGateBytes.length,
+                                            nGates,
+                                            nRays,
+                                            lut.length));
+                        }
+
+                        mainHandler.post(
+                                () -> {
+                                    final double mainQueueMs = nanoToMs(tDecodeDone);
+                                    if (genSnapshot != decodeGeneration.get()) {
+                                        if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                                            Log.i(
+                                                    TAG,
+                                                    String.format(
+                                                            Locale.US,
+                                                            "[NEXRAD][PERF] uiApplyDroppedStale seq=%d genSnapshot=%d currentGen=%d mainQueueMs=%.2f",
+                                                            seq,
+                                                            genSnapshot,
+                                                            decodeGeneration.get(),
+                                                            mainQueueMs));
+                                        }
+                                        return;
+                                    }
+                                    try {
+                                        final long tUi = System.nanoTime();
+                                        if (!isLayerAdded) {
+                                            findMapViewAndAddLayer();
+                                        }
+                                        radarLayer.requestFullFrameUpload(
+                                                finalGateBytes,
+                                                nGates,
+                                                nRays,
+                                                stationLat,
+                                                stationLon,
+                                                firstGateKm,
+                                                gateWidthKm,
+                                                finalRay,
+                                                lut,
+                                                valueScale,
+                                                valueOffset,
+                                                lutMin,
+                                                lutMax,
+                                                discrete,
+                                                opacity,
+                                                gateSmooth,
+                                                interpolateLut,
+                                                nativeGpuCacheKeyForUpload,
+                                                finalGeomResult);
+                                        triggerRepaint();
+                                        final double uiApplyMs = nanoToMs(tUi);
+                                        if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                                            Log.i(
+                                                    TAG,
+                                                    String.format(
+                                                            Locale.US,
+                                                            "[NEXRAD][PERF] uiApplyOk seq=%d genSnapshot=%d mainQueueMs=%.2f uiApplyMs=%.2f "
+                                                                    + "gateBytes=%d nGates=%d nRays=%d isLayerAdded=%s "
+                                                                    + "(GPU upload happens on next GL render — see AguaceroNexrad)",
+                                                            seq,
+                                                            genSnapshot,
+                                                            mainQueueMs,
+                                                            uiApplyMs,
+                                                            gateBytes.length,
+                                                            nGates,
+                                                            nRays,
+                                                            Boolean.toString(isLayerAdded)));
+                                        }
+                                    } catch (Exception e) {
+                                        Log.e(TAG, "uploadFrame apply failed", e);
+                                    }
+                                });
+                    } catch (Exception e) {
+                        Log.e(TAG, "uploadFrameFromJson decode failed", e);
+                    }
+                });
+    }
+
+    public void activateNexradCachedFrame(@Nullable String nativeGpuCacheKey) {
+        final long t0 = System.nanoTime();
+        if (nativeGpuCacheKey == null || nativeGpuCacheKey.isEmpty()) {
+            Log.w(TAG, "[NEXRAD][PERF] activateNexradCachedFrame skipped empty key");
+            return;
+        }
+        radarLayer.requestActivateCachedFrame(nativeGpuCacheKey);
+        triggerRepaint();
+        if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+            Log.i(
+                    TAG,
+                    String.format(
+                            Locale.US,
+                            "[NEXRAD][PERF] activateNexradCachedFrame enqueued rnUiMs=%.3f keyLen=%d",
+                            nanoToMs(t0),
+                            nativeGpuCacheKey.length()));
+        }
+    }
+
+    public void uploadStyleOnlyFromJson(String json) {
+        final long t0 = System.nanoTime();
+        final int jsonChars = json != null ? json.length() : 0;
+        try {
+            long mark = System.nanoTime();
+            if (!isLayerAdded) findMapViewAndAddLayer();
+            final double ensureLayerMs = nanoToMs(mark);
+
+            mark = System.nanoTime();
+            JSONObject o = new JSONObject(json);
+            final double jsonParseMs = nanoToMs(mark);
+
+            mark = System.nanoTime();
+            byte[] lut = Base64.decode(o.getString("lutB64"), Base64.DEFAULT);
+            final double lutB64DecodeMs = nanoToMs(mark);
+
+            mark = System.nanoTime();
+            float valueScale = (float) o.getDouble("valueScale");
+            float valueOffset = (float) o.getDouble("valueOffset");
+            float lutMin = (float) o.getDouble("lutMin");
+            float lutMax = (float) o.getDouble("lutMax");
+            float discrete = (float) o.getDouble("discreteIntegerLut");
+            float opacity = (float) o.getDouble("opacity");
+            float gateSmooth = (float) o.getDouble("gateSmoothPolar");
+            int interpolateLut = o.optInt("interpolateLut", 1);
+            final double scalarReadMs = nanoToMs(mark);
+
+            mark = System.nanoTime();
+            radarLayer.requestStyleOnlyUpload(
+                    lut, valueScale, valueOffset, lutMin, lutMax, discrete, opacity, gateSmooth, interpolateLut);
+            final double requestUploadMs = nanoToMs(mark);
+
+            mark = System.nanoTime();
+            triggerRepaint();
+            final double triggerRepaintMs = nanoToMs(mark);
+
+            final double totalMs = nanoToMs(t0);
+            if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                Log.i(
+                        TAG,
+                        String.format(
+                                Locale.US,
+                                "[NEXRAD][PERF] styleOnlyOnUiThread jsonChars=%d totalMs=%.2f ensureLayerMs=%.2f jsonParseMs=%.2f "
+                                        + "lutB64DecodeMs=%.2f scalarReadMs=%.2f requestUploadMs=%.2f triggerRepaintMs=%.2f lutBytes=%d",
+                                jsonChars,
+                                totalMs,
+                                ensureLayerMs,
+                                jsonParseMs,
+                                lutB64DecodeMs,
+                                scalarReadMs,
+                                requestUploadMs,
+                                triggerRepaintMs,
+                                lut.length));
+            }
+        } catch (Exception e) {
+            Log.e(TAG, "uploadStyleOnlyFromJson failed", e);
+        }
+    }
+
+    public void clearNexrad() {
+        decodeGeneration.incrementAndGet();
+        radarLayer.clearFrame();
+        triggerRepaint();
+    }
+}

package/lib/commonjs/android/src/main/java/com/aguacerowx/reactnative/NexradRadarManager.java

@@ -0,0 +1,113 @@
+package com.aguacerowx.reactnative;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import java.util.Locale;
+
+import com.facebook.react.bridge.ReadableArray;
+import com.facebook.react.uimanager.SimpleViewManager;
+import com.facebook.react.uimanager.ThemedReactContext;
+import com.facebook.react.uimanager.annotations.ReactProp;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import android.util.Log;
+
+public class NexradRadarManager extends SimpleViewManager<NexradRadarLayerView> {
+
+    private static final String REACT_CLASS = "NexradRadarLayer";
+    private static final int CMD_UPLOAD_FRAME = 1;
+    private static final int CMD_UPLOAD_STYLE = 2;
+    private static final int CMD_CLEAR = 3;
+    private static final int CMD_ACTIVATE_CACHED_FRAME = 4;
+
+    @NonNull
+    @Override
+    public String getName() {
+        return REACT_CLASS;
+    }
+
+    @NonNull
+    @Override
+    protected NexradRadarLayerView createViewInstance(@NonNull ThemedReactContext reactContext) {
+        return new NexradRadarLayerView(reactContext);
+    }
+
+    @ReactProp(name = "belowID")
+    public void setBelowID(NexradRadarLayerView view, @Nullable String belowID) {
+        view.setBelowID(belowID);
+    }
+
+    @Override
+    public Map<String, Integer> getCommandsMap() {
+        Map<String, Integer> m = new HashMap<>();
+        m.put("uploadNexradFrame", CMD_UPLOAD_FRAME);
+        m.put("uploadNexradStyleOnly", CMD_UPLOAD_STYLE);
+        m.put("clearNexrad", CMD_CLEAR);
+        m.put("activateNexradCachedFrame", CMD_ACTIVATE_CACHED_FRAME);
+        return m;
+    }
+
+    @Override
+    public void receiveCommand(@NonNull NexradRadarLayerView view, int commandId, @Nullable ReadableArray args) {
+        final long t0 = System.nanoTime();
+        if (commandId == CMD_CLEAR) {
+            view.clearNexrad();
+            if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                Log.i(
+                        REACT_CLASS,
+                        String.format(
+                                Locale.US,
+                                "[NEXRAD][PERF] receiveCommand clearNexrad rnBridgeMs=%.3f",
+                                (System.nanoTime() - t0) / 1_000_000.0));
+            }
+            return;
+        }
+        if (args == null || args.size() < 1) return;
+        final String payload = args.getString(0);
+        final int jsonChars = payload != null ? payload.length() : 0;
+        switch (commandId) {
+            case CMD_ACTIVATE_CACHED_FRAME:
+                view.activateNexradCachedFrame(payload);
+                if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                    Log.i(
+                            REACT_CLASS,
+                            String.format(
+                                    Locale.US,
+                                    "[NEXRAD][PERF] receiveCommand activateNexradCachedFrame keyLen=%d rnBridgeMs=%.3f",
+                                    jsonChars,
+                                    (System.nanoTime() - t0) / 1_000_000.0));
+                }
+                return;
+            case CMD_UPLOAD_FRAME:
+                view.uploadFrameFromJson(payload);
+                if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                    Log.i(
+                            REACT_CLASS,
+                            String.format(
+                                    Locale.US,
+                                    "[NEXRAD][PERF] receiveCommand uploadNexradFrame jsonChars=%d rnBridgeScheduleMs=%.3f (decode runs async)",
+                                    jsonChars,
+                                    (System.nanoTime() - t0) / 1_000_000.0));
+                }
+                break;
+            case CMD_UPLOAD_STYLE:
+                view.uploadStyleOnlyFromJson(payload);
+                if (AguaceroDebugLog.NEXRAD_NATIVE_VERBOSE) {
+                    Log.i(
+                            REACT_CLASS,
+                            String.format(
+                                    Locale.US,
+                                    "[NEXRAD][PERF] receiveCommand uploadNexradStyleOnly jsonChars=%d rnBridgeMs=%.3f",
+                                    jsonChars,
+                                    (System.nanoTime() - t0) / 1_000_000.0));
+                }
+                break;
+            default:
+                Log.w(REACT_CLASS, "receiveCommand: unknown commandId=" + commandId);
+                break;
+        }
+    }
+}