@aguacerowx/react-native 0.0.46 → 0.0.49

package/src/nws/NwsAlertsOverlay.native.js

@@ -0,0 +1,463 @@
+/**
+ * NWS watches/warnings for React Native (iOS + Android) — parity with {@link NwsWatchesWarningsOverlay}
+ * (archived / slider time via {@link NwsWatchesWarningsOverlay#syncWithMode}, same customization options).
+ *
+ * Uses the javascript-sdk NWS overlay engine with a stub Mapbox GL object; GeoJSON + layers render via @rnmapbox/maps.
+ */
+
+import './eventSourceRnPolyfill.js';
+
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import Mapbox from '@rnmapbox/maps';
+/** Subpath imports avoid Metro/barrel init ordering where the package root can yield undefined named exports during RN startup. */
+import { NwsWatchesWarningsOverlay, NWS_DEFAULT_LINE_BEFORE_LAYER_ID } from '@aguacerowx/javascript-sdk/nws/NwsWatchesWarningsOverlay.js';
+import { buildNwsLineDasharrayLiteralExpression } from '@aguacerowx/javascript-sdk/nws/nwsSdkConstants.js';
+import { buildAlertClickPayload, normalizeFeatureCollectionForMapboxGl } from '@aguacerowx/javascript-sdk/nws/nwsAlertsSupport.js';
+import { computeNwsAlertsFetchHoursFromAguaceroState } from '@aguacerowx/javascript-sdk/nws/nwsAlertsFetchSpec.js';
+import { mapRegistry } from '../MapRegistry';
+import { AGUACERO_NEXRAD_MAP_LAYER_ID, AGUACERO_SATELLITE_MAP_LAYER_ID } from './nwsAndroidConstants.js';
+
+const SOURCE_ID = 'aguacero-nws-alerts-source';
+const FILL_ID = 'aguacero-nws-alerts-fill';
+const LINE_CASING_ID = 'aguacero-nws-alerts-line-casing';
+const LINE_CORE_ID = 'aguacero-nws-alerts-line-core';
+
+class AndroidNwsOverlay extends NwsWatchesWarningsOverlay {
+    /**
+     * @param {object} map
+     * @param {object} options
+     * @param {(paint: object) => void} onPaint
+     */
+    constructor(map, options, onPaint) {
+        super(map, options);
+        this._onPaint = onPaint;
+    }
+
+    /**
+     * @rnmapbox/maps does not support data-driven `line-dasharray` (match on `event_name`).
+     * Keep web parity for colors; dash style follows {@link NwsWatchesWarningsOverlay} default `lineDash` only on RN.
+     */
+    _buildPaint() {
+        const p = super._buildPaint();
+        const mode = this._nwsAlertSettings?.lineDash ?? 'solid';
+        return {
+            ...p,
+            lineDashExpr: buildNwsLineDasharrayLiteralExpression(mode),
+            fillOpacityExpr: Array.isArray(p.fillOpacityExpr) && p.fillOpacityExpr.length > 2 ? p.fillOpacityExpr[2] : p.fillOpacityExpr,
+            lineOpacityExpr: Array.isArray(p.lineOpacityExpr) && p.lineOpacityExpr.length > 2 ? p.lineOpacityExpr[2] : p.lineOpacityExpr,
+        };
+    }
+
+    /**
+     * RN renders ShapeSource + layers declaratively (same ids). Only sync GeoJSON + paint; skip imperative addLayer.
+     */
+    _ensureLayers() {
+        const m = this.map;
+        if (!m?.addSource) return;
+
+        const paint = this._buildPaint();
+        if (this._onPaint) this._onPaint(paint);
+
+        const sourceData = normalizeFeatureCollectionForMapboxGl(this._workingFc);
+        if (!m.getSource(this._sourceId)) {
+            m.addSource(this._sourceId, {
+                type: 'geojson',
+                data: sourceData,
+            });
+        } else {
+            m.getSource(this._sourceId).setData(sourceData);
+        }
+    }
+
+    _refreshPaint() {
+        if (this._onPaint) this._onPaint(this._buildPaint());
+    }
+
+    _applyLayerOrder() {}
+
+    _syncClickHandler() {}
+}
+
+/**
+ * @param {object} handlers
+ * @param {() => import('@rnmapbox/maps').default | null} handlers.getMapboxMapView
+ * @param {(shape: object) => void} handlers.onShape
+ * @param {() => void} [handlers.onLayersCleared]
+ */
+function createFeatureStateBatcher(handlers) {
+    /** @type {Map<string, object>} */
+    const pendingStates = new Map();
+    let rafId = null;
+
+    function flush() {
+        rafId = null;
+        if (handlers.onFeatureStates) {
+            const activeIds = [];
+            for (const [fid, state] of pendingStates) {
+                if (state && state.active !== false) {
+                    activeIds.push(fid);
+                }
+            }
+            handlers.onFeatureStates(activeIds);
+        }
+    }
+
+    return {
+        push(fid, state, sid) {
+            pendingStates.set(fid, state);
+            if (rafId == null) {
+                rafId = requestAnimationFrame(flush);
+            }
+        },
+        clear() {
+            pendingStates.clear();
+            if (rafId != null) {
+                cancelAnimationFrame(rafId);
+                rafId = null;
+            }
+            if (handlers.onFeatureStates) {
+                handlers.onFeatureStates(null);
+            }
+        },
+    };
+}
+
+function createAndroidNwsStubMap(handlers) {
+    let sourceAdded = false;
+    /** Declarative RN layers use the same ids — treat as present after first {@link AndroidNwsOverlay#_ensureLayers}. */
+    let declarativeLayersReady = false;
+    const featureStateBatcher = createFeatureStateBatcher(handlers);
+
+    return {
+        isStyleLoaded: () => true,
+        once(ev, fn) {
+            if (ev === 'style.load') {
+                queueMicrotask(() => fn({ target: {} }));
+            }
+        },
+        __markDeclarativeLayersReady() {
+            declarativeLayersReady = true;
+        },
+        addSource(id, spec) {
+            if (id === SOURCE_ID) {
+                sourceAdded = true;
+                if (spec?.data) handlers.onShape(spec.data);
+            }
+        },
+        getSource(id) {
+            if (!sourceAdded || id !== SOURCE_ID) return null;
+            return {
+                setData: (geojson) => handlers.onShape(geojson),
+            };
+        },
+        addLayer() {},
+        removeLayer(id) {
+            if ([FILL_ID, LINE_CASING_ID, LINE_CORE_ID].includes(id)) {
+                declarativeLayersReady = false;
+                featureStateBatcher.clear();
+                handlers.onLayersCleared?.();
+            }
+        },
+        removeSource(id) {
+            if (id === SOURCE_ID) {
+                sourceAdded = false;
+                declarativeLayersReady = false;
+                featureStateBatcher.clear();
+                handlers.onLayersCleared?.();
+            }
+        },
+        getLayer(id) {
+            if (!declarativeLayersReady) return null;
+            return [FILL_ID, LINE_CASING_ID, LINE_CORE_ID].includes(id) ? { id } : null;
+        },
+        getStyle() {
+            return { layers: [] };
+        },
+        moveLayer() {},
+        setPaintProperty() {},
+        on() {},
+        off() {},
+        fire() {},
+        setFeatureState(target, state) {
+            const sid = target?.source;
+            const fid = target?.id;
+            if (sid !== SOURCE_ID || fid == null) return;
+            try {
+                featureStateBatcher.push(fid, state, sid);
+            } catch {
+                /* ignore */
+            }
+        },
+    };
+}
+
+/**
+ * @param {object} state - {@link AguaceroCore} state
+ * @param {object} wopt - watches/warnings options (same shape as mapsgl {@link WeatherLayerManager#configureWatchesWarnings})
+ * @returns {{ weatherLayerId: string | null, fillBelowId: string | null, lineBelowId: string }}
+ */
+export function resolveNwsAndroidLayerAnchors(state, wopt) {
+    const manualFill = Object.prototype.hasOwnProperty.call(wopt, 'fillBeforeLayerId')
+        ? wopt.fillBeforeLayerId ?? null
+        : null;
+
+    let weatherLayerId = null;
+    if (state?.isNexrad) {
+        weatherLayerId = AGUACERO_NEXRAD_MAP_LAYER_ID;
+    } else if (state?.isSatellite) {
+        weatherLayerId = AGUACERO_SATELLITE_MAP_LAYER_ID;
+    } else if (state?.isMRMS && state?.variable) {
+        weatherLayerId = 'aguacero-weather-grid-custom';
+    }
+
+    const fillBelowId =
+        manualFill != null && String(manualFill) !== ''
+            ? String(manualFill)
+            : weatherLayerId || NWS_DEFAULT_LINE_BEFORE_LAYER_ID;
+
+    const lineBelowId = wopt.lineBeforeLayerId || NWS_DEFAULT_LINE_BEFORE_LAYER_ID;
+
+    return { weatherLayerId, fillBelowId, lineBelowId };
+}
+
+/**
+ * @param {object} props
+ * @param {import('@aguacerowx/javascript-sdk').AguaceroCore} props.core
+ * @param {object} props.watchesWarnings - merged options ({ enabled, alertsBaseUrl, nwsAlertSettings, ... })
+ * @param {(payload: object) => void} [props.onNwsAlertClick]
+ */
+export default function NwsAlertsOverlay({ core, watchesWarnings, onNwsAlertClick }) {
+    const [aguaceroState, setAguaceroState] = useState(() => core?.state);
+
+    useEffect(() => {
+        if (!core) return undefined;
+        const h = (s) => setAguaceroState(s);
+        core.on('state:change', h);
+        return () => core.off('state:change', h);
+    }, [core]);
+
+    const [shape, setShape] = useState({ type: 'FeatureCollection', features: [] });
+    const [paint, setPaint] = useState(null);
+    const [activeIds, setActiveIds] = useState(null);
+
+    const overlayRef = useRef(null);
+    const stubRef = useRef(null);
+    const watchesRef = useRef(watchesWarnings);
+    const optsKeyRef = useRef('');
+
+    watchesRef.current = watchesWarnings;
+
+    const getMapboxMapView = useCallback(() => mapRegistry.getMap(), []);
+
+    const anchors = useMemo(
+        () => resolveNwsAndroidLayerAnchors(aguaceroState, watchesWarnings || {}),
+        [aguaceroState, watchesWarnings],
+    );
+
+    useEffect(() => {
+        const onPaint = (p) => setPaint(p);
+
+        const stub = createAndroidNwsStubMap({
+            getMapboxMapView,
+            onShape: (g) => setShape(g),
+            onFeatureStates: (ids) => setActiveIds(ids),
+            onLayersCleared: () => {
+                setPaint(null);
+                setActiveIds(null);
+            },
+        });
+        stubRef.current = stub;
+
+        const w0 = watchesRef.current || {};
+        const overlay = new AndroidNwsOverlay(stub, w0, onPaint);
+        overlayRef.current = overlay;
+
+        return () => {
+            overlay.destroy();
+            overlayRef.current = null;
+            stubRef.current = null;
+        };
+    }, [getMapboxMapView]);
+
+    useEffect(() => {
+        const ov = overlayRef.current;
+        if (!ov) return;
+
+        const wopt = watchesWarnings || {};
+        const nwsAlertSettingsForOpts = {
+            ...(wopt.nwsAlertSettings ?? {}),
+            ...(wopt.activeOnlyRealtime !== undefined ? { activeOnlyRealtime: wopt.activeOnlyRealtime } : {}),
+        };
+
+        const weatherLayerId = anchors.weatherLayerId;
+        const fillBeforeLayerId = Object.prototype.hasOwnProperty.call(wopt, 'fillBeforeLayerId')
+            ? wopt.fillBeforeLayerId ?? null
+            : null;
+
+        const nwsOptsKey = JSON.stringify({
+            weatherLayerId,
+            fillBeforeLayerId,
+            lineBeforeLayerId: wopt.lineBeforeLayerId,
+            alertsBaseUrl: wopt.alertsBaseUrl,
+            alertInteractionEnabled: wopt.alertInteractionEnabled,
+            deltaDebounceMs: wopt.deltaDebounceMs,
+            fillOpacity: wopt.fillOpacity,
+            lineOpacity: wopt.lineOpacity,
+            lineWidth: wopt.lineWidth,
+            nwsAlertSettings: nwsAlertSettingsForOpts,
+        });
+
+        if (optsKeyRef.current !== nwsOptsKey) {
+            optsKeyRef.current = nwsOptsKey;
+            ov.updateOptions({
+                alertsBaseUrl: wopt.alertsBaseUrl,
+                alertInteractionEnabled: wopt.alertInteractionEnabled,
+                deltaDebounceMs: wopt.deltaDebounceMs,
+                fillOpacity: wopt.fillOpacity,
+                lineOpacity: wopt.lineOpacity,
+                lineWidth: wopt.lineWidth,
+                weatherLayerId,
+                fillBeforeLayerId,
+                lineBeforeLayerId: wopt.lineBeforeLayerId,
+                nwsAlertSettings: nwsAlertSettingsForOpts,
+            });
+        }
+    }, [watchesWarnings, anchors.weatherLayerId]);
+
+    useEffect(() => {
+        const ov = overlayRef.current;
+        if (!ov || !aguaceroState) return;
+
+        const wopt = watchesWarnings || {};
+        const masterEnabled = wopt.enabled === true;
+        const enabled = masterEnabled;
+
+        let timelineUnix = null;
+        let timelineTimes = null;
+        const st = aguaceroState;
+        if (st.isSatellite) {
+            timelineUnix = st.satelliteTimestamp == null ? null : Number(st.satelliteTimestamp);
+            timelineTimes = st.availableSatelliteTimestamps;
+        } else if (st.isNexrad) {
+            timelineUnix = st.nexradTimestamp == null ? null : Number(st.nexradTimestamp);
+            timelineTimes = st.availableNexradTimestamps;
+        } else if (st.isMRMS) {
+            timelineUnix = st.mrmsTimestamp == null ? null : Number(st.mrmsTimestamp);
+            timelineTimes = st.availableTimestamps;
+        }
+
+        const hasObservationTimeline = !!(st.isSatellite || st.isNexrad || st.isMRMS);
+        const alertsFetchHours = computeNwsAlertsFetchHoursFromAguaceroState(st);
+
+        ov.syncWithMode({
+            enabled,
+            timelineUnix,
+            timelineTimes,
+            hasObservationTimeline,
+            alertsFetchHours,
+        });
+    }, [aguaceroState, watchesWarnings]);
+
+    useLayoutEffect(() => {
+        const stub = stubRef.current;
+        const ov = overlayRef.current;
+        if (!stub || !ov || !paint) return;
+        stub.__markDeclarativeLayersReady();
+        try {
+            ov._applyTimeFilters();
+        } catch {
+            /* ignore */
+        }
+    }, [paint, shape, aguaceroState?.nexradTimestamp, aguaceroState?.mrmsTimestamp, aguaceroState?.satelliteTimestamp]);
+
+    useEffect(() => {
+        if (!onNwsAlertClick) return undefined;
+
+        const handler = async (payload) => {
+            const wopt = watchesRef.current || {};
+            if (!wopt.enabled || wopt.alertInteractionEnabled === false) return;
+
+            const mapView = mapRegistry.getMap();
+            if (!mapView?.queryRenderedFeaturesAtPoint) return;
+
+            let screenPoint = null;
+            if (payload?.properties?.screenPointX != null && payload?.properties?.screenPointY != null) {
+                screenPoint = [payload.properties.screenPointX, payload.properties.screenPointY];
+            } else if (payload?.point != null && Array.isArray(payload.point)) {
+                screenPoint = payload.point;
+            }
+            if (!screenPoint) return;
+
+            let feats = await mapView.queryRenderedFeaturesAtPoint(screenPoint, undefined, [
+                FILL_ID,
+                LINE_CASING_ID,
+                LINE_CORE_ID,
+            ]);
+            if (!feats?.length && payload?.coordinates) {
+                const coord = payload.coordinates;
+                const pt = await mapView.getPointInView(coord);
+                if (pt) feats = await mapView.queryRenderedFeaturesAtPoint(pt, undefined, [FILL_ID, LINE_CASING_ID, LINE_CORE_ID]);
+            }
+            const hit = feats?.find((f) =>
+                [FILL_ID, LINE_CASING_ID, LINE_CORE_ID].includes(f?.layer?.id),
+            );
+            if (!hit?.properties) return;
+            try {
+                const built = buildAlertClickPayload(hit);
+                onNwsAlertClick({ ...built, feature: hit });
+            } catch {
+                /* ignore */
+            }
+        };
+
+        mapRegistry.addPressListener(handler);
+        return () => mapRegistry.removePressListener(handler);
+    }, [onNwsAlertClick]);
+
+    if (!paint) {
+        return null;
+    }
+
+    const p = paint;
+    const lineLayout = p.lineLayout ?? {};
+    const lineCap = lineLayout['line-cap'] ?? 'round';
+    const lineJoin = lineLayout['line-join'] ?? 'round';
+    const lineSortKey = lineLayout['line-sort-key'] ?? ['coalesce', ['get', '_nws_render_priority'], 0];
+    const fillSortKey = ['coalesce', ['get', '_nws_render_priority'], 0];
+
+    const fillStyle = {
+        fillColor: p.fillColorExpr,
+        fillOpacity: p.fillOpacityExpr,
+        fillSortKey,
+    };
+    const casingStyle = {
+        lineColor: p.dualLine.casingColor,
+        lineWidth: p.dualLine.casingWidth,
+        lineOpacity: p.lineOpacityExpr,
+        lineDasharray: p.lineDashExpr,
+        lineCap,
+        lineJoin,
+        lineSortKey,
+    };
+    const coreStyle = {
+        lineColor: p.dualLine.coreColor,
+        lineWidth: p.dualLine.coreWidth,
+        lineOpacity: p.lineOpacityExpr,
+        lineDasharray: p.lineDashExpr,
+        lineCap,
+        lineJoin,
+        lineSortKey,
+    };
+
+    const activeFilter = activeIds
+        ? (activeIds.length > 0 ? ['in', ['id'], ['literal', activeIds]] : ['==', ['id'], -1])
+        : ['==', ['id'], -1];
+
+    return (
+        <Mapbox.ShapeSource id={SOURCE_ID} shape={shape}>
+            <Mapbox.FillLayer id={FILL_ID} belowLayerID={anchors.fillBelowId} style={fillStyle} filter={activeFilter} />
+            <Mapbox.LineLayer id={LINE_CASING_ID} belowLayerID={anchors.lineBelowId} style={casingStyle} filter={activeFilter} />
+            <Mapbox.LineLayer id={LINE_CORE_ID} belowLayerID={anchors.lineBelowId} style={coreStyle} filter={activeFilter} />
+        </Mapbox.ShapeSource>
+    );
+}

package/src/satellite/satelliteAndroidController.js

@@ -3,6 +3,7 @@
  * {@link WeatherLayerManager} satellite paths — preload timeline + scrub via {@code targetUnix}).
  */
 import { resolveSatelliteS3FileName } from '@aguacerowx/javascript-sdk';
+import { satBridgeWarn } from '../satelliteBridgeDiag';
 
 /**
  * Target frame first, then remaining frames by increasing temporal distance to {@code targetUnix}.
@@ -68,6 +69,8 @@ export class SatelliteAndroidController {
         this._destroyed = false;
         /** @type {string | undefined} */
         this._cachedRunKey = undefined;
+        /** @type {string | undefined} */
+        this._cachedTimelineSig = undefined;
         /** @type {number | null | undefined} */
         this._lastTargetUnix = undefined;
         /** @type {string | undefined} */
@@ -77,6 +80,7 @@ export class SatelliteAndroidController {
     destroy() {
         this._destroyed = true;
         this._cachedRunKey = undefined;
+        this._cachedTimelineSig = undefined;
         this._lastTargetUnix = undefined;
         this._lastStyleJson = undefined;
         const native = this.satelliteLayerRef?.current;
@@ -87,13 +91,38 @@ export class SatelliteAndroidController {
      * @param {import('@aguacerowx/javascript-sdk').AguaceroCoreState} state
      */
     sync(state) {
-        if (this._destroyed || !state?.isSatellite) return;
+        satBridgeWarn('SatelliteAndroidController.sync enter', {
+            destroyed: this._destroyed,
+            isSatellite: Boolean(state?.isSatellite),
+            instrumentId: state?.satelliteInstrumentId ?? null,
+            sector: state?.satelliteSectorLabel ?? null,
+            channel: state?.satelliteChannel ?? null,
+            tlMapSize:
+                state?.satelliteTimeToFileMap && typeof state.satelliteTimeToFileMap === 'object'
+                    ? Object.keys(state.satelliteTimeToFileMap).length
+                    : 0,
+        });
+
+        if (this._destroyed || !state?.isSatellite) {
+            satBridgeWarn('SatelliteAndroidController.sync early-exit', {
+                destroyed: this._destroyed,
+                isSatellite: state?.isSatellite,
+            });
+            return;
+        }
 
         const native = this.satelliteLayerRef?.current;
-        if (!native?.syncSatellite) return;
+        if (!native?.syncSatellite) {
+            satBridgeWarn('SatelliteAndroidController.sync abort: no native.syncSatellite', {
+                refExists: Boolean(this.satelliteLayerRef?.current),
+                keys: this.satelliteLayerRef?.current ? Object.keys(this.satelliteLayerRef.current) : [],
+            });
+            return;
+        }
 
         const keys = Object.keys(state.satelliteTimeToFileMap || {}).sort((a, b) => Number(a) - Number(b));
-        const satRunKey = `${state.satelliteInstrumentId}|${state.satelliteSectorLabel}|${state.satelliteChannel}|${state.variable || ''}|tl:${keys.join(',')}`;
+        const satRunKey = `${state.satelliteInstrumentId}|${state.satelliteSectorLabel}|${state.satelliteChannel}|${state.variable || ''}`;
+        const timelineSig = keys.join(',');
 
         const mergedState = {
             ...state,
@@ -113,11 +142,34 @@ export class SatelliteAndroidController {
             });
         }
 
-        const targetUnix =
+        if (frames.length === 0) {
+            console.warn('[AguaceroWX][satellite][satelliteSyncNoFrames]', {
+                satRunKey,
+                timelineKeyCount: keys.length,
+                hasApiKey: Boolean(mergedState.apiKey),
+                satelliteChannel: mergedState.satelliteChannel,
+                mapKeys:
+                    mergedState.satelliteTimeToFileMap &&
+                    typeof mergedState.satelliteTimeToFileMap === 'object'
+                        ? Object.keys(mergedState.satelliteTimeToFileMap).length
+                        : 0,
+            });
+        }
+
+        let targetUnix =
             state.satelliteTimestamp == null || state.satelliteTimestamp === undefined
                 ? null
                 : Number(state.satelliteTimestamp);
 
+        // Core often omits satelliteTimestamp on the first satellite emit; without targetUnix the native
+        // layer never promotes uploads to activeUnix until a later activateSatelliteCachedUnix — blank map.
+        if (targetUnix == null || !Number.isFinite(targetUnix)) {
+            const nk = keys.map((k) => Number(k)).filter((n) => Number.isFinite(n));
+            if (nk.length > 0) {
+                targetUnix = Math.max(...nk);
+            }
+        }
+
         const stylePayload = {
             visible: state.visible !== false,
             opacity: state.opacity ?? 1,
@@ -126,14 +178,18 @@ export class SatelliteAndroidController {
         const styleJson = JSON.stringify(stylePayload);
 
         const runKeyChanged = satRunKey !== this._cachedRunKey;
+        const timelineChanged = timelineSig !== this._cachedTimelineSig;
 
-        if (runKeyChanged) {
+        if (runKeyChanged || timelineChanged) {
             const sortedFrames = sortFramesByTargetProximity(frames, targetUnix);
             const payload = {
                 runKey: satRunKey,
                 // Must match query params on each frame URL (same merge as buildSatelliteFetchParts) and mapsgl fetch headers.
                 apiKey: mergedState.apiKey || '',
                 userId: 'sdk-user',
+                // RN has no browser default Origin; native satellite fetch must mirror WeatherFrameProcessor / AguaceroCore grid headers.
+                gridRequestSiteOrigin:
+                    typeof this.core.gridRequestSiteOrigin === 'string' ? this.core.gridRequestSiteOrigin : '',
                 bundleId: this.core.bundleId || '',
                 visible: stylePayload.visible,
                 opacity: stylePayload.opacity,
@@ -144,8 +200,17 @@ export class SatelliteAndroidController {
                 payload.targetUnix = targetUnix;
             }
 
-            native.syncSatellite(JSON.stringify(payload));
+            const payloadJson = JSON.stringify(payload);
+            native.syncSatellite(payloadJson);
+            satBridgeWarn('SatelliteAndroidController.sync full payload sent', {
+                runKey: satRunKey,
+                timelineChanged,
+                frameCount: sortedFrames.length,
+                targetUnix: payload.targetUnix ?? null,
+                jsonChars: payloadJson.length,
+            });
             this._cachedRunKey = satRunKey;
+            this._cachedTimelineSig = timelineSig;
             this._lastTargetUnix = targetUnix != null && Number.isFinite(targetUnix) ? targetUnix : null;
             this._lastStyleJson = styleJson;
             return;
@@ -157,12 +222,14 @@ export class SatelliteAndroidController {
         if (finiteTarget !== this._lastTargetUnix) {
             if (finiteTarget != null && native.activateSatelliteCachedUnix) {
                 native.activateSatelliteCachedUnix(finiteTarget);
+                satBridgeWarn('SatelliteAndroidController.activateSatelliteCachedUnix', { unix: finiteTarget });
             }
             this._lastTargetUnix = finiteTarget;
         }
 
         if (styleJson !== this._lastStyleJson && native.updateSatelliteStyle) {
             native.updateSatelliteStyle(styleJson);
+            satBridgeWarn('SatelliteAndroidController.updateSatelliteStyle', { jsonChars: styleJson.length });
             this._lastStyleJson = styleJson;
         }
     }

package/src/satelliteBridgeDiag.js

@@ -0,0 +1,15 @@
+/**
+ * Always-on warnings for satellite bridge debugging (Metro + many device log sinks).
+ * Filter Xcode / Metro: `sat-bridge` or `AguaceroWX`.
+ */
+export function satBridgeWarn(tag, detail) {
+    try {
+        if (detail !== undefined) {
+            console.warn(`[AguaceroWX][sat-bridge] ${tag}`, detail);
+        } else {
+            console.warn(`[AguaceroWX][sat-bridge] ${tag}`);
+        }
+    } catch {
+        /* ignore */
+    }
+}