@luciq/react-native 19.4.0-47504-SNAPSHOT → 19.6.0

package/dist/modules/Luciq.js

@@ -1,11 +1,12 @@
 import { AppState, findNodeHandle, Platform } from 'react-native';
 import Report from '../models/Report';
 import { emitter, NativeEvents, NativeLuciq } from '../native/NativeLuciq';
-import { registerFeatureFlagsListener, initFeatureFlagsCache } from '../utils/FeatureFlags';
+import { registerFeatureFlagsListener } from '../utils/FeatureFlags';
 import { LogLevel, NetworkInterceptionMode, ReproStepsMode, StringKey, } from '../utils/Enums';
 import LuciqUtils, { checkNetworkRequestHandlers, resetNativeObfuscationListener, setApmNetworkFlagsIfChanged, stringifyIfNotString, } from '../utils/LuciqUtils';
 import * as NetworkLogger from './NetworkLogger';
 import { captureUnhandledRejections } from '../utils/UnhandledRejectionTracking';
+import { ScreenLoadingManager } from './apm/ScreenLoadingManager';
 import { addAppStateListener } from '../utils/AppStatesHandler';
 import { NativeNetworkLogger } from '../native/NativeNetworkLogger';
 import LuciqConstants from '../utils/LuciqConstants';
@@ -19,6 +20,12 @@ let _currentAppState = AppState.currentState;
 let isNativeInterceptionFeatureEnabled = false; // Checks the value of "cp_native_interception_enabled" backend flag.
 let hasAPMNetworkPlugin = false; // Android only: checks if the APM plugin is installed.
 let shouldEnableNativeInterception = false; // For Android: used to disable APM logging inside reportNetworkLog() -> NativeAPM.networkLogAndroid(), For iOS: used to control native interception (true == enabled , false == disabled)
+// Screen Loading tracking variables
+let _navigationRef = null;
+let _currentRoute = null;
+let _activeNavigationSpanId = null;
+let _stateChangeTimeout;
+const STATE_CHANGE_TIMEOUT_MS = 2000; // Safety timeout if state never changes
 /**
  * Enables or disables Luciq functionality.
  * @param isEnabled A boolean to enable/disable Luciq.
@@ -50,7 +57,6 @@ function reportCurrentViewForAndroid(screenName) {
  * @param config SDK configurations. See {@link LuciqConfig} for more info.
  */
 export const init = (config) => {
-    initFeatureFlagsCache();
     if (Platform.OS === 'android') {
         // Add android feature flags listener for android
         registerFeatureFlagsListener();
@@ -79,7 +85,7 @@ export const init = (config) => {
     reportCurrentViewForAndroid(firstScreen);
     setTimeout(() => {
         if (_currentScreen === firstScreen) {
-            NativeLuciq.reportScreenChange(firstScreen);
+            NativeLuciq.reportScreenChange(firstScreen, null);
             _currentScreen = null;
         }
     }, 1000);
@@ -116,12 +122,14 @@ export const setWebViewUserInteractionsTrackingEnabled = (isEnabled) => {
  * Handles app state changes and updates APM network flags if necessary.
  */
 const handleAppStateChange = async (nextAppState, config) => {
-    // Checks if  the app has come to the foreground
+    // Checks if the app has come to the foreground
     if (['inactive', 'background'].includes(_currentAppState) && nextAppState === 'active') {
         const isUpdated = await fetchApmNetworkFlags();
         if (isUpdated) {
             refreshAPMNetworkConfigs(config);
         }
+        // Refresh screen loading flags from native
+        await ScreenLoadingManager.refreshFlags();
     }
     _currentAppState = nextAppState;
 };
@@ -647,21 +655,150 @@ export const onReportSubmitHandler = (handler) => {
     });
     NativeLuciq.setPreSendingHandler(handler);
 };
+/**
+ * Helper to clear the state change timeout
+ */
+const _clearStateChangeTimeout = () => {
+    if (_stateChangeTimeout) {
+        clearTimeout(_stateChangeTimeout);
+        _stateChangeTimeout = undefined;
+    }
+};
+/**
+ * Handles React Navigation's __unsafe_action__ event
+ * This fires WHEN a navigation action is dispatched (the start of navigation)
+ */
+const _onNavigationAction = (event) => {
+    // Check for noop actions that shouldn't create spans
+    if (event?.data?.noop) {
+        Logger.log('[ScreenLoading] Navigation action is a noop, not starting span');
+        return;
+    }
+    // Skip non-navigation actions (like SET_PARAMS, OPEN_DRAWER, etc.)
+    const actionType = event?.data?.action?.type;
+    if (actionType &&
+        ['SET_PARAMS', 'OPEN_DRAWER', 'CLOSE_DRAWER', 'TOGGLE_DRAWER'].includes(actionType)) {
+        Logger.log(`[ScreenLoading] Skipping non-navigation action: ${actionType}`);
+        return;
+    }
+    // If there's an existing active span, it means navigation was interrupted
+    // Discard the previous span as it never completed
+    if (_activeNavigationSpanId) {
+        Logger.log('[ScreenLoading] Discarding incomplete previous navigation span');
+        // Mark the span as cancelled/error since state change never occurred
+        const span = ScreenLoadingManager.getActiveSpan(_activeNavigationSpanId);
+        if (span) {
+            ScreenLoadingManager.endSpan(_activeNavigationSpanId);
+        }
+        _activeNavigationSpanId = null;
+        _clearStateChangeTimeout();
+    }
+    // Create a new span for this navigation action
+    // We don't know the destination screen yet, so use a placeholder name
+    if (ScreenLoadingManager.isFeatureEnabled()) {
+        const span = ScreenLoadingManager.createSpan('NavigationPending', false);
+        if (span) {
+            _activeNavigationSpanId = span.spanId;
+            Logger.log(`[ScreenLoading] Started span ${span.spanId} on navigation dispatch`);
+            // Set a safety timeout to discard the span if state never changes
+            // This prevents memory leaks from incomplete navigations
+            _stateChangeTimeout = setTimeout(() => {
+                if (_activeNavigationSpanId === span.spanId) {
+                    Logger.warn(`[ScreenLoading] Navigation span ${span.spanId} timed out - state never changed`);
+                    ScreenLoadingManager.endSpan(span.spanId);
+                    _activeNavigationSpanId = null;
+                }
+            }, STATE_CHANGE_TIMEOUT_MS);
+        }
+    }
+};
+/**
+ * Handles React Navigation's state event
+ * This fires AFTER the navigation state has changed (the screen is mounted)
+ */
+const _onNavigationStateChange = () => {
+    if (!_navigationRef?.current) {
+        return;
+    }
+    const previousRouteName = _currentRoute;
+    const currentRoute = _navigationRef.current.getCurrentRoute();
+    const currentRouteName = currentRoute?.name || null;
+    // If no route or same route, ignore
+    if (!currentRouteName || previousRouteName === currentRouteName) {
+        // Still need to clean up the span if one was created
+        if (_activeNavigationSpanId) {
+            Logger.log('[ScreenLoading] Navigation resulted in same route, discarding span');
+            ScreenLoadingManager.endSpan(_activeNavigationSpanId);
+            _activeNavigationSpanId = null;
+            _clearStateChangeTimeout();
+        }
+        return;
+    }
+    // Capture the span ID BEFORE clearing it so we can pass it to reportScreenChange
+    let spanIdForReport = _activeNavigationSpanId;
+    // Complete the active navigation span if one exists
+    if (_activeNavigationSpanId) {
+        // Now that we know the actual route name, check if it's excluded
+        if (ScreenLoadingManager.isRouteExcluded(currentRouteName)) {
+            Logger.log(`[ScreenLoading] Route "${currentRouteName}" is excluded, discarding span`);
+            ScreenLoadingManager.discardSpan(_activeNavigationSpanId);
+            spanIdForReport = null;
+            _activeNavigationSpanId = null;
+            _clearStateChangeTimeout();
+        }
+        else {
+            const span = ScreenLoadingManager.getActiveSpan(_activeNavigationSpanId);
+            if (span) {
+                // Update the span name from placeholder to actual screen name
+                span.screenName = currentRouteName;
+                // End the span - the native frame tracker will provide the actual render timestamp
+                ScreenLoadingManager.endSpan(_activeNavigationSpanId)
+                    .then(() => {
+                    Logger.log(`[ScreenLoading] Completed span for navigation to ${currentRouteName}`);
+                })
+                    .catch((error) => {
+                    Logger.warn('[ScreenLoading] Failed to end navigation span:', error);
+                });
+            }
+            // Clear the active span and timeout
+            _activeNavigationSpanId = null;
+            _clearStateChangeTimeout();
+        }
+    }
+    // Update the current route for the rest of Luciq's tracking
+    _currentRoute = currentRouteName;
+    // Report to native
+    NativeLuciq.reportScreenChange(currentRouteName, spanIdForReport);
+};
 export const onNavigationStateChange = (prevState, currentState, _action) => {
     const currentScreen = LuciqUtils.getActiveRouteName(currentState);
     const prevScreen = LuciqUtils.getActiveRouteName(prevState);
     if (prevScreen !== currentScreen) {
+        // Start Screen Loading measurement for v4
+        let screenLoadingSpanId = null;
+        if (ScreenLoadingManager.isFeatureEnabled()) {
+            const span = ScreenLoadingManager.createSpan(currentScreen || 'Unknown', false);
+            if (span) {
+                screenLoadingSpanId = span.spanId;
+            }
+        }
         reportCurrentViewForAndroid(currentScreen);
         if (_currentScreen != null && _currentScreen !== firstScreen) {
-            NativeLuciq.reportScreenChange(_currentScreen);
+            NativeLuciq.reportScreenChange(_currentScreen, screenLoadingSpanId);
             _currentScreen = null;
         }
         _currentScreen = currentScreen;
         setTimeout(() => {
             if (currentScreen && _currentScreen === currentScreen) {
-                NativeLuciq.reportScreenChange(currentScreen);
+                NativeLuciq.reportScreenChange(currentScreen, screenLoadingSpanId);
                 _currentScreen = null;
             }
+            // End Screen Loading measurement for v4
+            if (screenLoadingSpanId) {
+                ScreenLoadingManager.endSpan(screenLoadingSpanId).catch((error) => {
+                    Logger.warn('[ScreenLoading] Failed to end span:', error);
+                });
+            }
         }, 1000);
     }
 };
@@ -669,16 +806,25 @@ export const onStateChange = (state) => {
     if (!state) {
         return;
     }
+    // Delegate to the new state change handler for Screen Loading
+    // This handles reportScreenChange when setNavigationListener was called
+    _onNavigationStateChange();
+    // When setNavigationListener is used, _onNavigationStateChange already handles
+    // reportScreenChange properly - skip legacy logic to avoid duplicate calls
+    if (_navigationRef?.current) {
+        return;
+    }
+    // Fallback: Legacy screen tracking for users who only use onStateChange without setNavigationListener
     const currentScreen = LuciqUtils.getFullRoute(state);
     reportCurrentViewForAndroid(currentScreen);
     if (_currentScreen !== null && _currentScreen !== firstScreen) {
-        NativeLuciq.reportScreenChange(_currentScreen);
+        NativeLuciq.reportScreenChange(_currentScreen, null);
         _currentScreen = null;
     }
     _currentScreen = currentScreen;
     setTimeout(() => {
         if (_currentScreen === currentScreen) {
-            NativeLuciq.reportScreenChange(currentScreen);
+            NativeLuciq.reportScreenChange(currentScreen, null);
             _currentScreen = null;
         }
     }, 1000);
@@ -689,12 +835,23 @@ export const onStateChange = (state) => {
  *
  */
 export const setNavigationListener = (navigationRef) => {
-    return navigationRef.addListener('state', () => {
-        onStateChange(navigationRef.getRootState());
-    });
+    // Store the navigationRef for Screen Loading tracking
+    _navigationRef = navigationRef;
+    if (!navigationRef?.current) {
+        Logger.warn('[Luciq] Navigation ref not available, cannot set listeners');
+        return;
+    }
+    // Register the __unsafe_action__ listener for span creation
+    // This listener fires on navigation dispatch (start of navigation)
+    navigationRef.current.addListener('__unsafe_action__', _onNavigationAction);
+    // NOTE: We do NOT register a 'state' listener here because the user is expected
+    // to pass Luciq.onStateChange to NavigationContainer's onStateChange prop.
+    // Registering both would cause duplicate reportScreenChange calls.
+    Logger.log('[Luciq] Registered Screen Loading listener (__unsafe_action__)');
+    // return stateListener;
 };
 export const reportScreenChange = (screenName) => {
-    NativeLuciq.reportScreenChange(screenName);
+    NativeLuciq.reportScreenChange(screenName, null);
 };
 /**
  * Add feature flags to the next report.
@@ -750,7 +907,7 @@ export const componentDidAppearListener = (event) => {
         return;
     }
     if (_lastScreen !== event.componentName) {
-        NativeLuciq.reportScreenChange(event.componentName);
+        NativeLuciq.reportScreenChange(event.componentName, null);
         _lastScreen = event.componentName;
     }
 };

package/dist/modules/NetworkLogger.d.ts

@@ -3,6 +3,11 @@ import { NetworkData, ProgressCallback } from '../utils/XhrNetworkInterceptor';
 import { NetworkListenerType } from '../native/NativeNetworkLogger';
 export type { NetworkData };
 export type NetworkDataObfuscationHandler = (data: NetworkData) => Promise<NetworkData>;
+/**
+ * Sets whether network logs should be sent with bug reports.
+ * It is enabled by default.
+ * @param isEnabled
+ */
 export declare const setEnabled: (isEnabled: boolean) => void;
 /**
  * @internal

package/dist/modules/NetworkLogger.js

@@ -20,25 +20,21 @@ function getPortFromUrl(url) {
  * It is enabled by default.
  * @param isEnabled
  */
-const NET_TAG = 'LCQ-RN-NET:';
 export const setEnabled = (isEnabled) => {
     if (isEnabled) {
         xhr.enableInterception();
         xhr.setOnDoneCallback(async (network) => {
-            Logger.debug(NET_TAG, `[NetworkLogger] onDoneCallback received: ${network.method} ${network.url}, status=${network.responseCode}`);
             // eslint-disable-next-line no-new-func
             const predicate = Function('network', 'return ' + _requestFilterExpression);
             if (!predicate(network)) {
                 const MAX_NETWORK_BODY_SIZE_IN_BYTES = await NativeLuciq.getNetworkBodyMaxSize();
                 try {
                     if (_networkDataObfuscationHandler) {
-                        Logger.debug(NET_TAG, `[NetworkLogger] Running obfuscation handler for ${network.url}`);
                         network = await _networkDataObfuscationHandler(network);
                     }
                     if (__DEV__) {
                         const urlPort = getPortFromUrl(network.url);
                         if (urlPort === LuciqRNConfig.metroDevServerPort) {
-                            Logger.debug(NET_TAG, `[NetworkLogger] Skipping Metro dev server request: ${network.url}`);
                             return;
                         }
                     }
@@ -58,16 +54,12 @@ export const setEnabled = (isEnabled) => {
                         network.responseBody = `Body is omitted because content type ${network.contentType} isn't supported`;
                         Logger.warn(`LCQ-RN: The response body for the network request with URL ${network.url} has been omitted because the content type ${network.contentType} isn't supported.`);
                     }
-                    Logger.debug(NET_TAG, `[NetworkLogger] Reporting network log to native: ${network.method} ${network.url}`);
                     reportNetworkLog(network);
                 }
                 catch (e) {
-                    Logger.error(NET_TAG, `[NetworkLogger] Error processing network log for ${network.url}:`, e);
+                    Logger.error(e);
                 }
             }
-            else {
-                Logger.debug(NET_TAG, `[NetworkLogger] Request filtered out by predicate: ${network.method} ${network.url}, expression="${_requestFilterExpression}"`);
-            }
         });
     }
     else {

package/dist/modules/apm/ScreenLoadingManager.d.ts

@@ -0,0 +1,99 @@
+export interface ScreenLoadingSpan {
+    spanId: string;
+    screenName: string;
+    startTimestamp: number;
+    endTimestamp?: number;
+    ttid?: number;
+    status: 'pending' | 'measuring' | 'completed' | 'error';
+    isManual: boolean;
+    attributes: Map<string, number>;
+}
+/**
+ * Automatic Screen Loading Measurement
+ *
+ * Start point: `__unsafe_action__` navigation event (below).
+ *   - Fires when a navigation action is dispatched, before the target screen mounts.
+ *   - `ScreenLoadingManager.createSpan()` records `nowMicros()` as the span start.
+ *
+ * End point: `_onNavigationStateChange()` (called from `onStateChange`).
+ *   - Fires after navigation state has settled and the new screen is mounted.
+ *   - `ScreenLoadingManager.endSpan()` fetches the native frame timestamp from
+ *     CADisplayLink (iOS) / Choreographer (Android) to mark actual render completion.
+ *   - The TTID is: native frame timestamp − span start.
+ *
+ *
+ * Manual Screen Loading Measurement
+ *
+ * Start point: Component instantiation (lazy init block before first render).
+ *   - `nowMicros()` is captured as `constructorTimestampRef` and passed to
+ *     `ScreenLoadingManager.createSpan()` as the span's start timestamp.
+ *
+ * End point: `useLayoutEffect` (fires synchronously after React commits DOM
+ *   mutations, before the browser paints).
+ *   - `ScreenLoadingManager.endSpan()` fetches the native frame timestamp
+ *     from CADisplayLink (iOS) / Choreographer (Android) to mark the actual
+ *     render completion. The TTID is: native frame timestamp − span start.
+ *
+ * Both approaches share the same `endSpan()` path so TTID values are comparable.
+ */
+declare class ScreenLoadingManagerClass {
+    private activeSpans;
+    private isInitialized;
+    private isEnabled;
+    private isEndScreenLoadingEnabled;
+    private isFrameTrackingInitialized;
+    private activeSpanId;
+    private maxConcurrentSpans;
+    private excludedRoutes;
+    initialize(): Promise<void>;
+    refreshFlags(): Promise<void>;
+    /**
+     * Exclude specific routes from automatic screen loading measurement
+     * @param routes Array of route names to exclude
+     */
+    excludeRoutes(routes: string[]): void;
+    /**
+     * Include previously excluded routes back into screen loading measurement
+     * @param routes Array of route names to include (or empty to clear all exclusions)
+     */
+    includeRoutes(routes?: string[]): void;
+    /**
+     * Check if a route is excluded from measurement
+     */
+    isRouteExcluded(routeName: string): boolean;
+    /**
+     * Create a new screen loading span
+     * @param screenName Name of the screen
+     * @param isManual Whether the span is manual (not automatically created)
+     * @param startTimestampParam Optional start timestamp in microseconds (defaults to nowMicros())
+     * @returns The created span or null if the feature is not enabled
+     */
+    createSpan(screenName: string, isManual?: boolean, startTimestampParam?: number): ScreenLoadingSpan | null;
+    /**
+     * End a screen loading span
+     * @param spanId The ID of the span to end
+     */
+    endSpan(spanId: string): Promise<void>;
+    /**
+     * Log a screen loading span
+     * @param span The span to log
+     */
+    private logScreenLoading;
+    /**
+     * End a screen loading span using the current timestamp and active span ID
+     */
+    endScreenLoading(): void;
+    /**
+     * Discard a span without logging or syncing it to native.
+     * Used when a span should be silently dropped (e.g., excluded route resolved after creation).
+     */
+    discardSpan(spanId: string): void;
+    getActiveSpan(spanId: string): ScreenLoadingSpan | undefined;
+    getAllActiveSpans(): ScreenLoadingSpan[];
+    addSpanAttribute(spanId: string, key: string, value: number): void;
+    private cleanupOldestSpans;
+    isFeatureEnabled(): boolean;
+    isEndScreenLoadingFeatureEnabled(): boolean;
+}
+export declare const ScreenLoadingManager: ScreenLoadingManagerClass;
+export {};