@aguacerowx/react-native 0.0.52 → 0.0.53

package/src/satelliteRnDebug.js

@@ -0,0 +1,269 @@
+/**
+ * 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);
+}