@luciq/react-native 19.4.0 → 19.6.0

package/dist/components/LuciqCaptureScreenLoading.js

@@ -0,0 +1,154 @@
+import React, { useState, useRef, useEffect, useLayoutEffect, useContext } from 'react';
+import { View } from 'react-native';
+import { ScreenLoadingManager } from '../modules/apm/ScreenLoadingManager';
+import { Logger } from '../utils/logger';
+import { nowMicros, toEpochMicros } from '../utils/LuciqUtils';
+// Context to handle nested components
+const ScreenLoadingContext = React.createContext(false);
+export function LuciqCaptureScreenLoading(props) {
+    const { screenName, record, onMeasured, onLayout, children, ...viewProps } = props;
+    const isNested = useContext(ScreenLoadingContext);
+    // Refs for timestamps (these don't need to trigger re-renders)
+    const constructorTimestampRef = useRef(nowMicros()); // microseconds
+    const renderStartTimestampRef = useRef(undefined);
+    const renderEndTimestampRef = useRef(undefined);
+    const mountTimestampRef = useRef(undefined);
+    // Guards to ensure single execution
+    const initializedRef = useRef(false);
+    const hasFirstRenderCompletedRef = useRef(false);
+    const attributesRecordedRef = useRef(false);
+    const initialSpanIdRef = useRef(null);
+    // Capture render start timestamp ONLY on first render
+    if (!hasFirstRenderCompletedRef.current) {
+        renderStartTimestampRef.current = nowMicros();
+    }
+    // Initialize span - runs once like constructor (lazy initialization)
+    if (!initializedRef.current) {
+        initializedRef.current = true;
+        // Initialize span if conditions are met
+        try {
+            if (record !== false && ScreenLoadingManager.isFeatureEnabled()) {
+                const span = ScreenLoadingManager.createSpan(screenName, true, constructorTimestampRef.current);
+                if (span) {
+                    initialSpanIdRef.current = span.spanId;
+                    Logger.log(`[LuciqScreenLoading] Span ${span.spanId} created in constructor`);
+                }
+            }
+        }
+        catch (error) {
+            Logger.error('[LuciqScreenLoading] Failed to create span:', error);
+        }
+    }
+    const [spanId, setSpanId] = useState(initialSpanIdRef.current);
+    const [isMeasured, setIsMeasured] = useState(false);
+    // Ref to avoid stale closure in useLayoutEffect
+    const onMeasuredRef = useRef(onMeasured);
+    useEffect(() => {
+        onMeasuredRef.current = onMeasured;
+    }, [onMeasured]);
+    // Refs to track latest values for cleanup (componentWillUnmount)
+    const spanIdRef = useRef(spanId);
+    const isMeasuredRef = useRef(isMeasured);
+    // Keep refs in sync with state
+    useEffect(() => {
+        spanIdRef.current = spanId;
+    }, [spanId]);
+    useEffect(() => {
+        isMeasuredRef.current = isMeasured;
+    }, [isMeasured]);
+    // Handle nested component detection
+    useEffect(() => {
+        // Check if we're nested and should ignore this component
+        if (isNested && initialSpanIdRef.current) {
+            Logger.log(`[LuciqScreenLoading] Nested component detected, ignoring span ${initialSpanIdRef.current}`);
+            // Cancel the span
+            setSpanId(null);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []); // Empty deps = componentDidMount
+    // Record lifecycle timestamps after first render completes (synchronous)
+    // useLayoutEffect fires synchronously after DOM mutations but before browser paint
+    useLayoutEffect(() => {
+        // Skip if no span, already recorded, or nested
+        if (!spanId || attributesRecordedRef.current || isNested) {
+            return;
+        }
+        // endSpan is async (native frame timestamp fetch), fire-and-forget from useLayoutEffect
+        ScreenLoadingManager.endSpan(spanId)
+            .then(() => {
+            const completedSpan = ScreenLoadingManager.getActiveSpan(spanId);
+            if (completedSpan?.ttid && onMeasuredRef.current) {
+                onMeasuredRef.current(completedSpan.ttid / 1000);
+            }
+        })
+            .catch((error) => {
+            Logger.warn('[LuciqScreenLoading] Failed to end span:', error);
+        });
+        attributesRecordedRef.current = true;
+        mountTimestampRef.current = nowMicros();
+        try {
+            // Record all timestamps
+            ScreenLoadingManager.addSpanAttribute(spanId, 'cnst_mus_st', toEpochMicros(constructorTimestampRef.current));
+            if (renderStartTimestampRef.current) {
+                ScreenLoadingManager.addSpanAttribute(spanId, 'rnd_mus_st', toEpochMicros(renderStartTimestampRef.current));
+            }
+            ScreenLoadingManager.addSpanAttribute(spanId, 'mnt_mus_st', toEpochMicros(mountTimestampRef.current));
+            // Record all durations
+            if (renderStartTimestampRef.current) {
+                // Constructor duration: time from component init to first render start
+                const constructorDuration = renderStartTimestampRef.current - constructorTimestampRef.current;
+                ScreenLoadingManager.addSpanAttribute(spanId, 'cnst_mus', constructorDuration);
+            }
+            if (renderEndTimestampRef.current && renderStartTimestampRef.current) {
+                // Render duration: time spent creating JSX
+                const renderDuration = renderEndTimestampRef.current - renderStartTimestampRef.current;
+                ScreenLoadingManager.addSpanAttribute(spanId, 'rnd_mus', renderDuration);
+            }
+            if (mountTimestampRef.current && renderEndTimestampRef.current) {
+                // Mount duration: time from render complete to effect execution
+                const mountDuration = mountTimestampRef.current - renderEndTimestampRef.current;
+                ScreenLoadingManager.addSpanAttribute(spanId, 'mnt_mus', mountDuration);
+            }
+            Logger.log(`[LuciqScreenLoading] Lifecycle measurements for span ${spanId}:`, {
+                constructor_us: renderStartTimestampRef.current
+                    ? renderStartTimestampRef.current - constructorTimestampRef.current
+                    : undefined,
+                render_us: renderEndTimestampRef.current && renderStartTimestampRef.current
+                    ? renderEndTimestampRef.current - renderStartTimestampRef.current
+                    : undefined,
+                mount_us: mountTimestampRef.current && renderEndTimestampRef.current
+                    ? mountTimestampRef.current - renderEndTimestampRef.current
+                    : undefined,
+            });
+        }
+        catch (error) {
+            Logger.error(`[LuciqScreenLoading] Failed to record attributes for span ${spanId}:`, error);
+        }
+        // End the span — mark as measured synchronously to guard against unmount race
+        setIsMeasured(true);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [spanId]); // Run when spanId is set
+    // componentWillUnmount equivalent
+    useEffect(() => {
+        return () => {
+            // Cleanup on unmount if not measured
+            if (spanIdRef.current && !isMeasuredRef.current) {
+                ScreenLoadingManager.endSpan(spanIdRef.current).catch((error) => {
+                    Logger.warn('[LuciqScreenLoading] Failed to end span on unmount:', error);
+                });
+            }
+        };
+    }, []); // Empty deps = only runs cleanup on unmount
+    // Create the JSX result
+    const result = (<ScreenLoadingContext.Provider value={spanId !== null}>
+      <View {...viewProps} onLayout={onLayout}>
+        {children}
+      </View>
+    </ScreenLoadingContext.Provider>);
+    // Capture render end timestamp ONLY on first render (after JSX creation)
+    if (!hasFirstRenderCompletedRef.current) {
+        renderEndTimestampRef.current = nowMicros();
+        hasFirstRenderCompletedRef.current = true;
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -18,4 +18,6 @@ import type { SessionMetadata } from './models/SessionMetadata';
 export * from './utils/Enums';
 export { Report, CustomSpan, APM, BugReporting, CrashReporting, FeatureRequests, NetworkLogger, SessionReplay, Replies, Surveys, ProactiveReportingConfigOptions, createProactiveReportingConfig, };
 export type { LuciqConfig, Survey, NetworkData, NetworkDataObfuscationHandler, SessionMetadata, ThemeConfig, };
+export { LuciqCaptureScreenLoading } from './components/LuciqCaptureScreenLoading';
+export type { LuciqScreenLoadingProps } from './components/LuciqCaptureScreenLoading';
 export default Luciq;

package/dist/index.js

@@ -13,4 +13,6 @@ import * as Surveys from './modules/Surveys';
 import * as SessionReplay from './modules/SessionReplay';
 export * from './utils/Enums';
 export { Report, CustomSpan, APM, BugReporting, CrashReporting, FeatureRequests, NetworkLogger, SessionReplay, Replies, Surveys, createProactiveReportingConfig, };
+// Screen Loading Component
+export { LuciqCaptureScreenLoading } from './components/LuciqCaptureScreenLoading';
 export default Luciq;

package/dist/modules/APM.d.ts

@@ -138,3 +138,22 @@ export declare const startCustomSpan: (name: string) => Promise<CustomSpan | nul
  * ```
  */
 export declare const addCompletedCustomSpan: (name: string, startDate: Date, endDate: Date) => Promise<void>;
+/**
+ * Enables or disables Screen Loading feature
+ * @param isEnabled
+ */
+export declare const setScreenLoadingEnabled: (isEnabled: boolean) => void;
+/**
+ * Extends the currently running screen loading trace with a new end timestamp.
+ */
+export declare const endScreenLoading: () => void;
+/**
+ * Exclude specific routes from automatic screen loading measurement
+ * @param routes Array of route names to exclude
+ */
+export declare function excludeScreenLoadingRoutes(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)
+ */
+export declare function includeScreenLoadingRoutes(routes?: string[]): void;

package/dist/modules/APM.js

@@ -2,6 +2,12 @@ import { Platform } from 'react-native';
 import { NativeAPM } from '../native/NativeAPM';
 import { NativeLuciq } from '../native/NativeLuciq';
 import { startCustomSpan as startCustomSpanInternal, addCompletedCustomSpan as addCompletedCustomSpanInternal, } from '../utils/CustomSpansManager';
+import { ScreenLoadingManager } from './apm/ScreenLoadingManager';
+import { Logger } from '../utils/logger';
+// Initialize Screen Loading on module load
+ScreenLoadingManager.initialize().catch((error) => {
+    Logger.error('[APM] Failed to initialize Screen Loading:', error);
+});
 /**
  * Enables or disables APM
  * @param isEnabled
@@ -171,3 +177,35 @@ export const startCustomSpan = async (name) => {
 export const addCompletedCustomSpan = async (name, startDate, endDate) => {
     return addCompletedCustomSpanInternal(name, startDate, endDate);
 };
+/**
+ * Enables or disables Screen Loading feature
+ * @param isEnabled
+ */
+export const setScreenLoadingEnabled = (isEnabled) => {
+    try {
+        NativeAPM.setScreenLoadingEnabled(isEnabled);
+    }
+    catch (error) {
+        Logger.error('[APM] Failed to set screen loading enabled:', error);
+    }
+};
+/**
+ * Extends the currently running screen loading trace with a new end timestamp.
+ */
+export const endScreenLoading = () => {
+    ScreenLoadingManager.endScreenLoading();
+};
+/**
+ * Exclude specific routes from automatic screen loading measurement
+ * @param routes Array of route names to exclude
+ */
+export function excludeScreenLoadingRoutes(routes) {
+    ScreenLoadingManager.excludeRoutes(routes);
+}
+/**
+ * Include previously excluded routes back into screen loading measurement
+ * @param routes Array of route names to include (or empty to clear all exclusions)
+ */
+export function includeScreenLoadingRoutes(routes) {
+    ScreenLoadingManager.includeRoutes(routes);
+}

package/dist/modules/Luciq.d.ts

@@ -286,7 +286,7 @@ export declare const onStateChange: (state?: NavigationStateV5) => void;
  *  @param navigationRef a refrence of a navigation container
  *
  */
-export declare const setNavigationListener: (navigationRef: NavigationContainerRefWithCurrent<ReactNavigation.RootParamList>) => () => void;
+export declare const setNavigationListener: (navigationRef: NavigationContainerRefWithCurrent<ReactNavigation.RootParamList>) => void;
 export declare const reportScreenChange: (screenName: string) => void;
 /**
  * Add feature flags to the next report.

package/dist/modules/Luciq.js

@@ -6,6 +6,7 @@ import { LogLevel, NetworkInterceptionMode, ReproStepsMode, StringKey, } from '.
 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.
@@ -78,7 +85,7 @@ export const init = (config) => {
     reportCurrentViewForAndroid(firstScreen);
     setTimeout(() => {
         if (_currentScreen === firstScreen) {
-            NativeLuciq.reportScreenChange(firstScreen);
+            NativeLuciq.reportScreenChange(firstScreen, null);
             _currentScreen = null;
         }
     }, 1000);
@@ -115,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;
 };
@@ -646,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);
     }
 };
@@ -668,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);
@@ -688,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.
@@ -749,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/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 {};