@aguacerowx/react-native 0.0.52 → 0.0.53

package/lib/module/satelliteRnDebug.js

@@ -0,0 +1,248 @@
+/**
+ * Satellite-specific RN diagnostics (Metro + native events → Metro when `debug` is on).
+ *
+ * Filter Metro: `[AguaceroRN][satellite]`
+ * Filter logcat: `AguaceroRN`, `AguaceroSatelliteView`, `AguaceroSatellite`, `AguaceroSatKtx`
+ */
+import { NativeEventEmitter, NativeModules, Platform, UIManager } from 'react-native';
+import { aguaceroDebug, aguaceroDebugWarn, getAguaceroAuthDiagnosticSnapshot, isAguaceroRnDebugEnabled, redactApiKeyFromUrl } from './aguaceroRnDebug';
+export const SATELLITE_DIAGNOSTIC_EVENT = 'AguaceroSatelliteDiagnostic';
+const LOG = '[AguaceroRN][satellite]';
+
+/** @type {import('react-native').EmitterSubscription | null} */
+let diagSubscription = null;
+const BASIS_FORMAT_NAMES = {
+  1: 'ETC2_RGBA (preferred Android)',
+  10: 'ASTC_LDR_4x4 (black tiles if GPU cannot sample ASTC)',
+  13: 'RGBA32 (universal fallback)'
+};
+
+/**
+ * @param {number | undefined} ordinal
+ */
+export function basisFormatLabel(ordinal) {
+  if (ordinal == null || Number.isNaN(Number(ordinal))) return 'unknown';
+  return BASIS_FORMAT_NAMES[Number(ordinal)] ?? `ordinal_${ordinal}`;
+}
+
+/**
+ * Actionable hints when imagery is black but JS sync looks healthy.
+ * @param {Record<string, unknown>} ctx
+ */
+export function interpretSatelliteBlackScreenHints(ctx) {
+  const hints = [];
+  const frameCount = Number(ctx.frameCount ?? 0);
+  const nativeCached = Number(ctx.nativeCachedFrames ?? ctx.cachedFrameCount ?? NaN);
+  const targetUnix = ctx.targetUnix;
+  const activeUnix = ctx.activeUnix;
+  const visible = ctx.visible;
+  const opacity = ctx.opacity;
+  const basisFormat = ctx.basisFormatOrdinal ?? ctx.transcodeFormatOrdinal;
+  if (frameCount === 0) {
+    hints.push('JS built zero frame URLs — check satellite listing, channel (geocolor), and sector.');
+  }
+  if (visible === false) {
+    hints.push('Layer visible=false — imagery is hidden by state/UI.');
+  }
+  if (typeof opacity === 'number' && opacity <= 0) {
+    hints.push('Layer opacity=0 — increase opacity in WeatherLayerManager state.');
+  }
+  if (targetUnix != null && nativeCached === 0 && !Number.isNaN(nativeCached)) {
+    hints.push('targetUnix is set but native GPU cache is empty — KTX fetch/decode/upload failed; check native diagnostic events or logcat (AguaceroSatelliteView).');
+  }
+  if (activeUnix == null && targetUnix != null) {
+    hints.push('targetUnix set but no active frame on GPU yet — wait for decode or prior frame failed upload (ASTC on unsupported GPU is common).');
+  }
+  if (Number(basisFormat) === 10) {
+    hints.push('Transcoded to ASTC — if the map footprint is black, rebuild SDK with ETC2-first transcode or check AguaceroSatellite for GPU upload GL errors.');
+  }
+  if (ctx.bundleIdPresent === false) {
+    hints.push('bundleId missing — install react-native-device-info; some keys require x-app-identifier (usually 403, not black tiles).');
+  }
+  if (ctx.mapLayerAdded === false) {
+    hints.push('Mapbox custom satellite layer not attached — ensure WeatherLayerManager is a child of MapManager.');
+  }
+  if (ctx.satelliteNativeMissing === true) {
+    hints.push('SatelliteLayer native view manager not registered — rebuild app / link @aguacerowx/react-native android.');
+  }
+  if (hints.length === 0) {
+    hints.push('JS pipeline looks healthy — inspect native events below (fetch bytes, transcode format, GPU upload). Filter logcat: AguaceroSatelliteView AguaceroSatellite AguaceroSatKtx');
+  }
+  return hints;
+}
+
+/**
+ * One-shot integration audit (call when WeatherLayerManager mounts with debug).
+ * @param {{ core?: import('@aguacerowx/javascript-sdk').AguaceroCore; satelliteLayerRef?: React.RefObject<unknown> }} opts
+ */
+export function auditSatelliteIntegration(opts = {}) {
+  if (!isAguaceroRnDebugEnabled()) return;
+  const {
+    core,
+    satelliteLayerRef
+  } = opts;
+  let satCmdKeys = [];
+  let gridCmdKeys = [];
+  let satManagerError = null;
+  try {
+    satCmdKeys = Object.keys(UIManager.getViewManagerConfig?.('SatelliteLayer')?.Commands ?? {});
+  } catch (e) {
+    satManagerError = String(e?.message ?? e);
+    satCmdKeys = [];
+  }
+  try {
+    gridCmdKeys = Object.keys(UIManager.getViewManagerConfig?.('GridRenderLayer')?.Commands ?? {});
+  } catch {
+    gridCmdKeys = [];
+  }
+  let deviceInfoOk = false;
+  let deviceInfoBundleId = null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, global-require
+    const DeviceInfo = require('react-native-device-info');
+    deviceInfoOk = true;
+    try {
+      deviceInfoBundleId = DeviceInfo.getBundleId?.() ?? null;
+    } catch {
+      deviceInfoBundleId = null;
+    }
+  } catch {
+    deviceInfoOk = false;
+  }
+  const snapshot = {
+    platform: Platform.OS,
+    satelliteNativeCommands: satCmdKeys,
+    satelliteNativeMissing: satCmdKeys.length === 0,
+    satelliteManagerError: satManagerError,
+    gridNativeCommands: gridCmdKeys,
+    satelliteRefAttached: Boolean(satelliteLayerRef?.current),
+    satelliteRefMethods: satelliteLayerRef?.current ? Object.keys(satelliteLayerRef.current) : [],
+    reactNativeDeviceInfo: deviceInfoOk ? {
+      installed: true,
+      bundleId: deviceInfoBundleId
+    } : {
+      installed: false,
+      hint: 'npm install react-native-device-info — required for core.bundleId / x-app-identifier'
+    },
+    mapboxNote: 'Requires @rnmapbox/maps v11; WeatherLayerManager must be nested inside MapManager',
+    nativeLibraries: ['aguacero_satellite_ktx (KTX2 Basis transcoder JNI)'],
+    auth: core ? getAguaceroAuthDiagnosticSnapshot(core) : undefined
+  };
+  aguaceroDebug('integration.audit', snapshot);
+  if (satCmdKeys.length === 0) {
+    aguaceroDebugWarn('integration.satelliteNativeMissing', {
+      hint: 'SatelliteLayer ViewManager has no commands — satellite will never render on Android.'
+    });
+  }
+  if (core && !core.bundleId && Platform.OS !== 'web') {
+    aguaceroDebugWarn('integration.bundleIdMissing', {
+      hint: 'core.bundleId is null — CDN may still work; some API keys require react-native-device-info.',
+      deviceInfoInstalled: deviceInfoOk
+    });
+  }
+  return snapshot;
+}
+
+/**
+ * @param {object} params
+ */
+export function logSatelliteSyncReport(params) {
+  if (!isAguaceroRnDebugEnabled()) return;
+  const {
+    state,
+    core,
+    frames,
+    targetUnix,
+    runKey,
+    timelineKeyCount,
+    runKeyChanged,
+    timelineChanged,
+    stylePayload
+  } = params;
+  const first = frames?.[0];
+  const last = frames?.length ? frames[frames.length - 1] : null;
+  const report = {
+    runKey,
+    runKeyChanged,
+    timelineChanged,
+    timelineKeyCount,
+    builtFrameCount: frames?.length ?? 0,
+    targetUnix,
+    satelliteTimestamp: state?.satelliteTimestamp ?? null,
+    style: stylePayload,
+    instrument: state?.satelliteInstrumentId,
+    sector: state?.satelliteSectorLabel,
+    channel: state?.satelliteChannel,
+    availableSatelliteTimestamps: state?.availableSatelliteTimestamps?.length ?? 0,
+    sampleShaderFileName: first?.shaderFileName ?? null,
+    sampleFrameUrl: first?.url ? redactApiKeyFromUrl(first.url) : null,
+    firstUnix: first?.unix ?? null,
+    lastUnix: last?.unix ?? null,
+    auth: core ? getAguaceroAuthDiagnosticSnapshot(core) : undefined,
+    blackScreenHints: interpretSatelliteBlackScreenHints({
+      frameCount: frames?.length ?? 0,
+      targetUnix,
+      visible: stylePayload?.visible,
+      opacity: stylePayload?.opacity,
+      bundleIdPresent: Boolean(core?.bundleId)
+    })
+  };
+  aguaceroDebug('sync.report', report);
+}
+
+/**
+ * Subscribe to native → JS diagnostic events (Android). Returns unsubscribe.
+ * @returns {() => void}
+ */
+export function installSatelliteDiagnosticListener() {
+  if (!isAguaceroRnDebugEnabled()) return () => {};
+  if (Platform.OS !== 'android') {
+    aguaceroDebug('nativeEvents.skipped', {
+      reason: 'only Android emits AguaceroSatelliteDiagnostic today'
+    });
+    return () => {};
+  }
+  if (diagSubscription) {
+    diagSubscription.remove();
+    diagSubscription = null;
+  }
+  const emitter = new NativeEventEmitter();
+  diagSubscription = emitter.addListener(SATELLITE_DIAGNOSTIC_EVENT, payload => {
+    if (!payload || typeof payload !== 'object') return;
+    const phase = payload.phase ?? 'unknown';
+    const detail = {
+      ...payload
+    };
+    delete detail.phase;
+    if (detail.basisFormatOrdinal != null) {
+      detail.basisFormat = basisFormatLabel(detail.basisFormatOrdinal);
+    }
+    if (detail.transcodeFormatOrdinal != null) {
+      detail.transcodeFormat = basisFormatLabel(detail.transcodeFormatOrdinal);
+    }
+    if (phase.includes('fail') || phase.includes('error') || phase === 'render.noDraw' || phase === 'render.poll' && (detail.cachedFrameCount === 0 || detail.activeUnix == null)) {
+      detail.blackScreenHints = interpretSatelliteBlackScreenHints(detail);
+      aguaceroDebugWarn(`native.${phase}`, detail);
+    } else {
+      aguaceroDebug(`native.${phase}`, detail);
+    }
+  });
+  aguaceroDebug('nativeEvents.installed', {
+    event: SATELLITE_DIAGNOSTIC_EVENT,
+    hint: 'Native fetch/decode/GPU logs will appear here when debug=true on WeatherLayerManager'
+  });
+  return () => {
+    diagSubscription?.remove();
+    diagSubscription = null;
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} nativePayload
+ */
+export function logSatelliteNativeDiagnostic(nativePayload) {
+  if (!isAguaceroRnDebugEnabled() || !nativePayload) return;
+  const phase = nativePayload.phase ?? 'event';
+  aguaceroDebug(`native.${phase}`, nativePayload);
+}
+//# sourceMappingURL=satelliteRnDebug.js.map

package/lib/module/satelliteRnDebug.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["NativeEventEmitter","NativeModules","Platform","UIManager","aguaceroDebug","aguaceroDebugWarn","getAguaceroAuthDiagnosticSnapshot","isAguaceroRnDebugEnabled","redactApiKeyFromUrl","SATELLITE_DIAGNOSTIC_EVENT","LOG","diagSubscription","BASIS_FORMAT_NAMES","basisFormatLabel","ordinal","Number","isNaN","interpretSatelliteBlackScreenHints","ctx","hints","frameCount","nativeCached","nativeCachedFrames","cachedFrameCount","NaN","targetUnix","activeUnix","visible","opacity","basisFormat","basisFormatOrdinal","transcodeFormatOrdinal","push","bundleIdPresent","mapLayerAdded","satelliteNativeMissing","length","auditSatelliteIntegration","opts","core","satelliteLayerRef","satCmdKeys","gridCmdKeys","satManagerError","Object","keys","getViewManagerConfig","Commands","e","String","message","deviceInfoOk","deviceInfoBundleId","DeviceInfo","require","getBundleId","snapshot","platform","OS","satelliteNativeCommands","satelliteManagerError","gridNativeCommands","satelliteRefAttached","Boolean","current","satelliteRefMethods","reactNativeDeviceInfo","installed","bundleId","hint","mapboxNote","nativeLibraries","auth","undefined","deviceInfoInstalled","logSatelliteSyncReport","params","state","frames","runKey","timelineKeyCount","runKeyChanged","timelineChanged","stylePayload","first","last","report","builtFrameCount","satelliteTimestamp","style","instrument","satelliteInstrumentId","sector","satelliteSectorLabel","channel","satelliteChannel","availableSatelliteTimestamps","sampleShaderFileName","shaderFileName","sampleFrameUrl","url","firstUnix","unix","lastUnix","blackScreenHints","installSatelliteDiagnosticListener","reason","remove","emitter","addListener","payload","phase","detail","transcodeFormat","includes","event","logSatelliteNativeDiagnostic","nativePayload"],"sourceRoot":"..\\..\\src","sources":["satelliteRnDebug.js"],"mappings":"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","ignoreList":[]}

package/lib/typescript/WeatherLayerManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WeatherLayerManager.d.ts","sourceRoot":"","sources":["../../src/WeatherLayerManager.js"],"names":[],"mappings":"AAyQA,sCAutDG"}
+{"version":3,"file":"WeatherLayerManager.d.ts","sourceRoot":"","sources":["../../src/WeatherLayerManager.js"],"names":[],"mappings":"AA0QA,sCA0uDG"}

package/lib/typescript/aguaceroRnDebug.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aguaceroRnDebug.d.ts","sourceRoot":"","sources":["../../src/aguaceroRnDebug.js"],"names":[],"mappings":"AAuCA;;GAEG;AACH,mDAFW,OAAO,QAIjB;AAED;;GAEG;AACH,gDAFW;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,QAwB/B;AAED;;;GAGG;AACH,4CAFa,OAAO,CAqBnB;AAUD;;;GAGG;AACH,uCAHW,MAAM,GAAG,IAAI,GAAG,SAAS,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBnC;AAED;;;GAGG;AACH,qCAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;GAGG;AACH,uCAHW,MAAM,GACJ,MAAM,CAKlB;AAED;;;GAGG;AACH,0CAHW,MAAM,GACJ,OAAO,CAMnB;AAED;;;GAGG;AACH,mCAHW,MAAM,UACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,QAS7C;AAED;;;;GAIG;AACH,uCAHW,MAAM,UACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,QAS7C;AAED;;;GAGG;AACH,wDAHW,GAAiD,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,UACvL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBjC;AAED;;;;GAIG;AACH,4DAJW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,eAErB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBnC;AA4BD;;GAEG;AACH,iDAiEC"}
+{"version":3,"file":"aguaceroRnDebug.d.ts","sourceRoot":"","sources":["../../src/aguaceroRnDebug.js"],"names":[],"mappings":"AAwCA;;GAEG;AACH,mDAFW,OAAO,QAIjB;AAED;;GAEG;AACH,gDAFW;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,QAwB/B;AAED;;;GAGG;AACH,4CAFa,OAAO,CAqBnB;AAUD;;;GAGG;AACH,uCAHW,MAAM,GAAG,IAAI,GAAG,SAAS,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBnC;AAED;;;GAGG;AACH,qCAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;GAGG;AACH,uCAHW,MAAM,GACJ,MAAM,CAKlB;AAED;;;GAGG;AACH,0CAHW,MAAM,GACJ,OAAO,CAMnB;AAED;;;GAGG;AACH,mCAHW,MAAM,UACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,QAS7C;AAED;;;;GAIG;AACH,uCAHW,MAAM,UACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,QAS7C;AAED;;;GAGG;AACH,wDAHW,GAAiD,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,UACvL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBjC;AAED;;;;GAIG;AACH,4DAJW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,eAErB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBnC;AA4BD;;GAEG;AACH,iDAiEC"}

package/lib/typescript/index.d.ts

@@ -2,6 +2,7 @@ export { MapManager } from "./MapManager";
 export { WeatherLayerManager } from "./WeatherLayerManager";
 export { default as GridRenderLayer } from "./GridRenderLayerNativeComponent";
 export { configureAguaceroRnDebug, setAguaceroRnDebugEnabled, isAguaceroRnDebugEnabled, getAguaceroAuthDiagnosticSnapshot, aguaceroDebug, aguaceroDebugWarn } from "./aguaceroRnDebug";
+export { SATELLITE_DIAGNOSTIC_EVENT, auditSatelliteIntegration, installSatelliteDiagnosticListener, logSatelliteSyncReport, interpretSatelliteBlackScreenHints, basisFormatLabel } from "./satelliteRnDebug";
 export { resolveGridRequestSiteOrigin, RN_DEFAULT_GRID_REQUEST_SITE_ORIGIN } from "./gridCdnAuth";
 export { AGUACERO_NEXRAD_MAP_LAYER_ID, AGUACERO_SATELLITE_MAP_LAYER_ID } from "./nws/nwsAndroidConstants";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/satellite/satelliteAndroidController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"satelliteAndroidController.d.ts","sourceRoot":"","sources":["../../../src/satellite/satelliteAndroidController.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,oDAHW;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,EAAE,cACvD,MAAM,GAAG,IAAI;UADL,MAAM;SAAO,MAAM;oBAAkB,MAAM;IAiB7D;AAED;;;GAGG;AACH,yEAFW,MAAM;;;;;SA4BhB;AAED;IACI;;;OAGG;IACH,0CAFW,KAAK,CAAC,SAAS,CAAC;QAAE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;QAAC,2BAA2B,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC,EAcvM;IAXG,UAAgB;IAChB;wBAJyC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;yBAAmB,MAAM,IAAI;sCAAgC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;+BAAyB,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;OAIvJ;IAC1C,oBAAuB;IACvB,iCAAiC;IACjC,eADW,MAAM,GAAG,SAAS,CACC;IAC9B,iCAAiC;IACjC,oBADW,MAAM,GAAG,SAAS,CACM;IACnC,wCAAwC;IACxC,iBADW,MAAM,GAAG,IAAI,GAAG,SAAS,CACJ;IAChC,iCAAiC;IACjC,gBADW,MAAM,GAAG,SAAS,CACE;IAGnC,gBAQC;IAED;;OAEG;IACH,uBAsJC;CACJ"}
+{"version":3,"file":"satelliteAndroidController.d.ts","sourceRoot":"","sources":["../../../src/satellite/satelliteAndroidController.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,oDAHW;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,EAAE,cACvD,MAAM,GAAG,IAAI;UADL,MAAM;SAAO,MAAM;oBAAkB,MAAM;IAiB7D;AAED;;;GAGG;AACH,yEAFW,MAAM;;;;;SA4BhB;AAED;IACI;;;OAGG;IACH,0CAFW,KAAK,CAAC,SAAS,CAAC;QAAE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;QAAC,2BAA2B,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,oBAAoB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC,EAcvM;IAXG,UAAgB;IAChB;wBAJyC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;yBAAmB,MAAM,IAAI;sCAAgC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;+BAAyB,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;OAIvJ;IAC1C,oBAAuB;IACvB,iCAAiC;IACjC,eADW,MAAM,GAAG,SAAS,CACC;IAC9B,iCAAiC;IACjC,oBADW,MAAM,GAAG,SAAS,CACM;IACnC,wCAAwC;IACxC,iBADW,MAAM,GAAG,IAAI,GAAG,SAAS,CACJ;IAChC,iCAAiC;IACjC,gBADW,MAAM,GAAG,SAAS,CACE;IAGnC,gBAQC;IAED;;OAEG;IACH,uBAiKC;CACJ"}

package/lib/typescript/satelliteRnDebug.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @param {number | undefined} ordinal
+ */
+export function basisFormatLabel(ordinal: number | undefined): any;
+/**
+ * Actionable hints when imagery is black but JS sync looks healthy.
+ * @param {Record<string, unknown>} ctx
+ */
+export function interpretSatelliteBlackScreenHints(ctx: Record<string, unknown>): string[];
+/**
+ * One-shot integration audit (call when WeatherLayerManager mounts with debug).
+ * @param {{ core?: import('@aguacerowx/javascript-sdk').AguaceroCore; satelliteLayerRef?: React.RefObject<unknown> }} opts
+ */
+export function auditSatelliteIntegration(opts?: {
+    core?: any;
+    satelliteLayerRef?: React.RefObject<unknown>;
+}): {
+    platform: "ios" | "android" | "windows" | "macos" | "web";
+    satelliteNativeCommands: any[];
+    satelliteNativeMissing: boolean;
+    satelliteManagerError: string | null;
+    gridNativeCommands: any[];
+    satelliteRefAttached: boolean;
+    satelliteRefMethods: string[];
+    reactNativeDeviceInfo: {
+        installed: boolean;
+        bundleId: string | null;
+        hint?: undefined;
+    } | {
+        installed: boolean;
+        hint: string;
+        bundleId?: undefined;
+    };
+    mapboxNote: string;
+    nativeLibraries: string[];
+    auth: {
+        platform: "ios" | "android" | "windows" | "macos" | "web";
+        isReactNative: boolean;
+        baseGridUrl: any;
+        apiKey: Record<string, unknown>;
+        bundleId: {
+            present: boolean;
+            value: string;
+            length: number;
+            hint?: undefined;
+        } | {
+            present: boolean;
+            hint: string;
+            value?: undefined;
+            length?: undefined;
+        };
+        gridRequestSiteOrigin: {
+            present: boolean;
+            value: string;
+            length: number;
+            hint?: undefined;
+        } | {
+            present: boolean;
+            hint: string;
+            value?: undefined;
+            length?: undefined;
+        };
+        willSendAppIdentifier: boolean;
+        willSendOriginHeaders: boolean;
+    } | undefined;
+} | undefined;
+/**
+ * @param {object} params
+ */
+export function logSatelliteSyncReport(params: object): void;
+/**
+ * Subscribe to native → JS diagnostic events (Android). Returns unsubscribe.
+ * @returns {() => void}
+ */
+export function installSatelliteDiagnosticListener(): () => void;
+/**
+ * @param {Record<string, unknown>} nativePayload
+ */
+export function logSatelliteNativeDiagnostic(nativePayload: Record<string, unknown>): void;
+export const SATELLITE_DIAGNOSTIC_EVENT: "AguaceroSatelliteDiagnostic";
+//# sourceMappingURL=satelliteRnDebug.d.ts.map

package/lib/typescript/satelliteRnDebug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"satelliteRnDebug.d.ts","sourceRoot":"","sources":["../../src/satelliteRnDebug.js"],"names":[],"mappings":"AAsBA;;GAEG;AACH,0CAFW,MAAM,GAAG,SAAS,OAK5B;AAED;;;GAGG;AACH,wDAFW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAqDjC;AAED;;;GAGG;AACH,iDAFW;IAAE,IAAI,CAAC,EAAE,GAAiD,CAAC;IAAC,iBAAiB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqEpH;AAED;;GAEG;AACH,+CAFW,MAAM,QA+ChB;AAED;;;GAGG;AACH,sDAFa,MAAM,IAAI,CA+CtB;AAED;;GAEG;AACH,4DAFW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAMjC;AAnQD,yCAA0C,6BAA6B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aguacerowx/react-native",
-  "version": "0.0.52",
+  "version": "0.0.53",
   "description": "Native weather rendering for React Native",
   "license": "ISC",
   "author": "Michael Barletta",
@@ -46,7 +46,7 @@
     "react-native-device-info": ">=10.0.0"
   },
   "dependencies": {
-    "@aguacerowx/javascript-sdk": "^0.0.29",
+    "@aguacerowx/javascript-sdk": "^0.0.30",
     "base64-js": "^1.5.1"
   },
   "react-native-builder-bob": {

package/src/WeatherLayerManager.js

@@ -29,6 +29,7 @@ import {
 } from './aguaceroRnDebug';
 import { installAguaceroCoreDebugHooks, logProcessFrameAuthMismatch } from './aguaceroCoreDebugHooks';
 import { resolveGridRequestSiteOrigin } from './gridCdnAuth';
+import { auditSatelliteIntegration, installSatelliteDiagnosticListener } from './satelliteRnDebug';
 
 const NEXRAD_NATIVE = Platform.OS === 'android' || Platform.OS === 'ios';
 const SATELLITE_NATIVE = Platform.OS === 'android' || Platform.OS === 'ios';
@@ -271,6 +272,12 @@ export const WeatherLayerManager = forwardRef((props, ref) => {
         customColormaps,
         initialMode,
         initialVariable,
+        /** GOES instrument when {@link initialMode} is `"satellite"` (default `GOES19-EAST`). */
+        initialSatelliteId,
+        /** Sector token or label when {@link initialMode} is `"satellite"` (default `conus` → GOES-EAST CONUS). */
+        initialSatelliteSector,
+        /** Product/band when {@link initialMode} is `"satellite"` (e.g. `geocolor`, `C13`). Falls back to {@link initialVariable}. */
+        initialSatelliteProduct,
         autoRefresh,
         autoRefreshInterval,
         initialModel,
@@ -289,6 +296,12 @@ export const WeatherLayerManager = forwardRef((props, ref) => {
     useEffect(() => {
         configureAguaceroRnDebug({ enabled: Boolean(debug) });
     }, [debug]);
+
+    useEffect(() => {
+        if (!debug) return undefined;
+        auditSatelliteIntegration({ core, satelliteLayerRef });
+        return installSatelliteDiagnosticListener();
+    }, [debug, core]);
     const context = useContext(AguaceroContext);
 
     // Create the core here instead of getting it from context
@@ -302,6 +315,13 @@ export const WeatherLayerManager = forwardRef((props, ref) => {
                     mode: initialMode,
                     variable: initialVariable,
                     model: initialModel,
+                    ...(initialMode === 'satellite'
+                        ? {
+                              satelliteId: initialSatelliteId,
+                              sector: initialSatelliteSector,
+                              satelliteProduct: initialSatelliteProduct ?? initialVariable,
+                          }
+                        : {}),
                 },
                 autoRefresh: false, // <-- add this
             }),

package/src/aguaceroRnDebug.js

@@ -16,6 +16,7 @@
  *    or: `globalThis.__AGUACERO_DEBUG__ = true` in your entry file.
  *
  * Logs use the prefix `[AguaceroRN][debug]` (Metro, Xcode, Logcat).
+ * Satellite imagery: also filter `[AguaceroRN][satellite]` and native `AguaceroSatelliteDiagnostic` events.
  * API keys are never printed in full — only length, fingerprint, and whitespace hints.
  */
 

package/src/index.js

@@ -8,6 +8,14 @@ export {
     aguaceroDebug,
     aguaceroDebugWarn,
 } from './aguaceroRnDebug';
+export {
+    SATELLITE_DIAGNOSTIC_EVENT,
+    auditSatelliteIntegration,
+    installSatelliteDiagnosticListener,
+    logSatelliteSyncReport,
+    interpretSatelliteBlackScreenHints,
+    basisFormatLabel,
+} from './satelliteRnDebug';
 export {
     resolveGridRequestSiteOrigin,
     RN_DEFAULT_GRID_REQUEST_SITE_ORIGIN,

package/src/satellite/satelliteAndroidController.js

@@ -5,6 +5,7 @@
 import { resolveSatelliteS3FileName } from '@aguacerowx/javascript-sdk';
 import { satBridgeWarn } from '../satelliteBridgeDiag';
 import { aguaceroDebug, getAguaceroAuthDiagnosticSnapshot, isAguaceroRnDebugEnabled, redactApiKeyFromUrl } from '../aguaceroRnDebug';
+import { logSatelliteSyncReport } from '../satelliteRnDebug';
 
 /**
  * Target frame first, then remaining frames by increasing temporal distance to {@code targetUnix}.
@@ -149,11 +150,18 @@ export class SatelliteAndroidController {
                 timelineKeyCount: keys.length,
                 hasApiKey: Boolean(mergedState.apiKey),
                 satelliteChannel: mergedState.satelliteChannel,
+                gridRequestSiteOrigin:
+                    mergedState.gridRequestSiteOrigin ?? this.core.gridRequestSiteOrigin ?? null,
+                bundleId: this.core.bundleId ?? null,
                 mapKeys:
                     mergedState.satelliteTimeToFileMap &&
                     typeof mergedState.satelliteTimeToFileMap === 'object'
                         ? Object.keys(mergedState.satelliteTimeToFileMap).length
                         : 0,
+                hint:
+                    keys.length === 0
+                        ? 'Timeline empty — wait for core.initialize / listing, or check satelliteId/sector/product.'
+                        : 'Timeline has keys but no resolvable frame URLs — check satelliteChannel vs listing (e.g. geocolor needs MULTI on CONUS).',
             });
         }
 
@@ -182,15 +190,18 @@ export class SatelliteAndroidController {
         const timelineChanged = timelineSig !== this._cachedTimelineSig;
 
         if (runKeyChanged || timelineChanged) {
-            if (isAguaceroRnDebugEnabled()) {
-                aguaceroDebug('satellite.sync.payload', {
-                    auth: getAguaceroAuthDiagnosticSnapshot(this.core),
-                    frameCount: frames.length,
-                    sampleFrameUrl: frames[0] ? redactApiKeyFromUrl(frames[0].url) : null,
-                    gridRequestSiteOrigin: mergedState.gridRequestSiteOrigin ?? this.core.gridRequestSiteOrigin ?? null,
-                });
-            }
             const sortedFrames = sortFramesByTargetProximity(frames, targetUnix);
+            logSatelliteSyncReport({
+                state: mergedState,
+                core: this.core,
+                frames: sortedFrames,
+                targetUnix,
+                runKey: satRunKey,
+                timelineKeyCount: keys.length,
+                runKeyChanged,
+                timelineChanged,
+                stylePayload,
+            });
             const payload = {
                 runKey: satRunKey,
                 // Must match query params on each frame URL (same merge as buildSatelliteFetchParts) and mapsgl fetch headers.
@@ -203,6 +214,7 @@ export class SatelliteAndroidController {
                 visible: stylePayload.visible,
                 opacity: stylePayload.opacity,
                 fillSmoothing: stylePayload.fillSmoothing,
+                debug: isAguaceroRnDebugEnabled(),
                 frames: sortedFrames,
             };
             if (targetUnix != null && Number.isFinite(targetUnix)) {