@luciq/react-native 19.4.0 → 19.6.0

package/src/modules/Luciq.ts

@@ -29,6 +29,7 @@ import LuciqUtils, {
 } from '../utils/LuciqUtils';
 import * as NetworkLogger from './NetworkLogger';
 import { captureUnhandledRejections } from '../utils/UnhandledRejectionTracking';
+import { ScreenLoadingManager } from './apm/ScreenLoadingManager';
 import type { ReproConfig } from '../models/ReproConfig';
 import type { FeatureFlag } from '../models/FeatureFlag';
 import { addAppStateListener } from '../utils/AppStatesHandler';
@@ -48,6 +49,13 @@ let isNativeInterceptionFeatureEnabled = false; // Checks the value of "cp_nativ
 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: NavigationContainerRefWithCurrent<ReactNavigation.RootParamList> | null = null;
+let _currentRoute: string | null = null;
+let _activeNavigationSpanId: string | null = null;
+let _stateChangeTimeout: ReturnType<typeof setTimeout> | undefined;
+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.
@@ -116,7 +124,7 @@ export const init = (config: LuciqConfig) => {
   reportCurrentViewForAndroid(firstScreen);
   setTimeout(() => {
     if (_currentScreen === firstScreen) {
-      NativeLuciq.reportScreenChange(firstScreen);
+      NativeLuciq.reportScreenChange(firstScreen, null);
       _currentScreen = null;
     }
   }, 1000);
@@ -158,12 +166,14 @@ export const setWebViewUserInteractionsTrackingEnabled = (isEnabled: boolean) =>
  * Handles app state changes and updates APM network flags if necessary.
  */
 const handleAppStateChange = async (nextAppState: AppStateStatus, config: LuciqConfig) => {
-  // 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;
@@ -756,6 +766,139 @@ export const onReportSubmitHandler = (handler?: (report: Report) => void) => {
   NativeLuciq.setPreSendingHandler(handler);
 };
 
+/**
+ * Helper to clear the state change timeout
+ */
+const _clearStateChangeTimeout = (): void => {
+  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?: any): void => {
+  // 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 = (): void => {
+  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: string | null = _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: NavigationStateV4,
   currentState: NavigationStateV4,
@@ -765,17 +908,33 @@ export const onNavigationStateChange = (
   const prevScreen = LuciqUtils.getActiveRouteName(prevState);
 
   if (prevScreen !== currentScreen) {
+    // Start Screen Loading measurement for v4
+    let screenLoadingSpanId: string | null = 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);
   }
 };
@@ -785,17 +944,28 @@ export const onStateChange = (state?: NavigationStateV5) => {
     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);
@@ -809,13 +979,29 @@ export const onStateChange = (state?: NavigationStateV5) => {
 export const setNavigationListener = (
   navigationRef: NavigationContainerRefWithCurrent<ReactNavigation.RootParamList>,
 ) => {
-  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: string) => {
-  NativeLuciq.reportScreenChange(screenName);
+  NativeLuciq.reportScreenChange(screenName, null);
 };
 
 /**
@@ -879,7 +1065,7 @@ export const componentDidAppearListener = (event: ComponentDidAppearEvent) => {
     return;
   }
   if (_lastScreen !== event.componentName) {
-    NativeLuciq.reportScreenChange(event.componentName);
+    NativeLuciq.reportScreenChange(event.componentName, null);
     _lastScreen = event.componentName;
   }
 };

package/src/modules/apm/ScreenLoadingManager.ts

@@ -0,0 +1,364 @@
+import { NativeAPM } from '../../native/NativeAPM';
+import { Logger } from '../../utils/logger';
+import { fromEpochMicros, nowMicros, toEpochMicros } from '../../utils/LuciqUtils';
+
+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.
+ */
+
+class ScreenLoadingManagerClass {
+  private activeSpans: Map<string, ScreenLoadingSpan> = new Map();
+  private isInitialized: boolean = false;
+  private isEnabled: boolean = false;
+  private isEndScreenLoadingEnabled: boolean = false;
+  private isFrameTrackingInitialized: boolean = false;
+  private activeSpanId: string | null = null;
+  private maxConcurrentSpans: number = 50;
+  private excludedRoutes: Set<string> = new Set();
+
+  async initialize(): Promise<void> {
+    if (this.isInitialized) {
+      return;
+    }
+
+    try {
+      // Check feature flags
+      this.isEnabled = await NativeAPM.isScreenLoadingEnabled();
+      this.isEndScreenLoadingEnabled = await NativeAPM.isEndScreenLoadingEnabled();
+      if (this.isEnabled) {
+        await NativeAPM.initScreenFrameTracking();
+        this.isFrameTrackingInitialized = true;
+        Logger.log('[ScreenLoading] Manager initialized, feature enabled');
+      } else {
+        Logger.log('[ScreenLoading] Feature disabled by flag');
+      }
+      this.isInitialized = true;
+    } catch (error) {
+      Logger.error('[ScreenLoading] Failed to initialize:', error);
+      this.isEnabled = false;
+    }
+  }
+
+  async refreshFlags(): Promise<void> {
+    try {
+      this.isEnabled = await NativeAPM.isScreenLoadingEnabled();
+      this.isEndScreenLoadingEnabled = await NativeAPM.isEndScreenLoadingEnabled();
+
+      if (this.isEnabled && !this.isFrameTrackingInitialized) {
+        await NativeAPM.initScreenFrameTracking();
+        this.isFrameTrackingInitialized = true;
+        Logger.log('[ScreenLoading] Frame tracking initialized after flag refresh');
+      }
+
+      Logger.log(
+        `[ScreenLoading] Flags refreshed - enabled: ${this.isEnabled}, endScreenLoading: ${this.isEndScreenLoadingEnabled}`,
+      );
+    } catch (error) {
+      Logger.error('[ScreenLoading] Failed to refresh flags:', error);
+    }
+  }
+
+  /**
+   * Exclude specific routes from automatic screen loading measurement
+   * @param routes Array of route names to exclude
+   */
+  excludeRoutes(routes: string[]): void {
+    routes.forEach((route) => this.excludedRoutes.add(route));
+    Logger.log('[ScreenLoading] Excluded routes:', Array.from(this.excludedRoutes));
+  }
+
+  /**
+   * 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 {
+    if (!routes || routes.length === 0) {
+      this.excludedRoutes.clear();
+      Logger.log('[ScreenLoading] Cleared all route exclusions');
+    } else {
+      routes.forEach((route) => this.excludedRoutes.delete(route));
+      Logger.log('[ScreenLoading] Removed exclusions for:', routes);
+    }
+  }
+
+  /**
+   * Check if a route is excluded from measurement
+   */
+  isRouteExcluded(routeName: string): boolean {
+    return this.excludedRoutes.has(routeName);
+  }
+
+  /**
+   * 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 = false,
+    startTimestampParam?: number,
+  ): ScreenLoadingSpan | null {
+    if (!this.isEnabled) {
+      return null;
+    }
+
+    // Check if route is excluded (only for automatic tracking)
+    if (!isManual && this.isRouteExcluded(screenName)) {
+      Logger.log(`[ScreenLoading] Route "${screenName}" is excluded from automatic measurement`);
+      return null;
+    }
+
+    // Cleanup if exceeding capacity
+    if (this.activeSpans.size >= this.maxConcurrentSpans) {
+      this.cleanupOldestSpans();
+    }
+
+    const spanId = Date.now().toString();
+    const startTimestamp = startTimestampParam ?? nowMicros();
+
+    const span: ScreenLoadingSpan = {
+      spanId,
+      screenName,
+      startTimestamp,
+      status: 'pending',
+      isManual,
+      attributes: new Map<string, number>(),
+    };
+
+    this.activeSpans.set(spanId, span);
+
+    // Register with native for frame tracking
+    try {
+      NativeAPM.setActiveScreenSpanId(spanId);
+    } catch (error) {
+      Logger.error(`[ScreenLoading] Failed to set active span ID ${spanId}:`, error);
+    }
+    if (!isManual) {
+      this.activeSpanId = spanId;
+    }
+    span.status = 'measuring';
+
+    Logger.log(
+      `[ScreenLoading] Created span ${spanId} for screen "${screenName}" (${isManual ? 'manual' : 'automatic'})`,
+    );
+
+    return span;
+  }
+
+  /**
+   * End a screen loading span
+   * @param spanId The ID of the span to end
+   */
+  async endSpan(spanId: string): Promise<void> {
+    if (!this.isEnabled) {
+      return;
+    }
+
+    const span = this.activeSpans.get(spanId);
+    if (!span || span.status === 'completed') {
+      return;
+    }
+
+    try {
+      // Get frame timestamp from native with retry logic
+      // The native frame callback (CADisplayLink/Choreographer) may not have executed yet
+      // if endSpan is called very quickly after createSpan. Retry up to 3 times with
+      // a delay of ~20ms (slightly more than one frame at 60fps) between attempts.
+      const maxRetries = 3;
+      const retryDelayMs = 20;
+      let frameTimestamp: number | null = null;
+
+      for (let attempt = 0; attempt < maxRetries; attempt++) {
+        frameTimestamp = await NativeAPM.getScreenTimeToDisplay(spanId);
+
+        if (frameTimestamp) {
+          break;
+        }
+
+        // Wait for next frame before retrying (only if not last attempt)
+        if (attempt < maxRetries - 1) {
+          await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+        }
+      }
+
+      if (frameTimestamp) {
+        // Native returns epoch microseconds; convert to monotonic for consistent internal math
+        span.endTimestamp = fromEpochMicros(frameTimestamp);
+        span.ttid = span.endTimestamp - span.startTimestamp;
+
+        span.status = 'completed';
+
+        // Log the measurement
+        this.logScreenLoading(span);
+      } else {
+        span.status = 'error';
+        Logger.warn(`[ScreenLoading] No frame timestamp available for span ${spanId}`);
+      }
+    } catch (error) {
+      span.status = 'error';
+      Logger.error(`[ScreenLoading] Failed to get timestamp for span ${spanId}:`, error);
+    }
+
+    // Cleanup after a delay
+    setTimeout(() => {
+      this.activeSpans.delete(spanId);
+    }, 5000);
+  }
+
+  /**
+   * Log a screen loading span
+   * @param span The span to log
+   */
+  private logScreenLoading(span: ScreenLoadingSpan): void {
+    // Convert Map to plain object for JSON serialization (JSON.stringify cannot serialize Maps)
+    const attributesObject = Object.fromEntries(span.attributes);
+
+    const startEpochUs = Math.round(toEpochMicros(span.startTimestamp));
+    const endEpochUs = span.endTimestamp ? Math.round(toEpochMicros(span.endTimestamp)) : undefined;
+
+    const logData = {
+      span_id: span.spanId,
+      screen_name: span.screenName,
+      start_timestamp_us: startEpochUs,
+      end_timestamp_us: endEpochUs,
+      ttid_us: span.ttid ? Math.round(span.ttid) : undefined,
+      ttid_ms: span.ttid ? Math.round(span.ttid) / 1000 : undefined,
+      is_manual: span.isManual,
+      attributes: attributesObject,
+    };
+
+    Logger.log('[ScreenLoading] Measurement:', JSON.stringify(logData, null, 2));
+
+    // Sync screen loading data to native layer (also pass converted object)
+    try {
+      if (span.isManual) {
+        NativeAPM.syncManualScreenLoading(
+          span.screenName,
+          startEpochUs,
+          Math.round(span.ttid!),
+          attributesObject,
+        );
+      } else {
+        NativeAPM.syncScreenLoading(
+          Number(span.spanId),
+          span.screenName,
+          startEpochUs,
+          Math.round(span.ttid!),
+          attributesObject,
+        );
+      }
+    } catch (error) {
+      Logger.error(`[ScreenLoading] Failed to sync screen loading for span ${span.spanId}:`, error);
+    }
+  }
+
+  /**
+   * End a screen loading span using the current timestamp and active span ID
+   */
+  endScreenLoading(): void {
+    if (!this.isEndScreenLoadingFeatureEnabled()) {
+      Logger.error('[ScreenLoading] End screen loading feature is not enabled');
+      return;
+    }
+    if (!this.activeSpanId) {
+      Logger.warn('[ScreenLoading] No active span to end screen loading');
+      return;
+    }
+    try {
+      const timeStampMicro = Math.round(toEpochMicros(nowMicros()));
+      const uiTraceId = Number(this.activeSpanId);
+      NativeAPM.endScreenLoading(timeStampMicro, uiTraceId);
+      Logger.log(
+        `[ScreenLoading] endScreenLoading() was called at ${timeStampMicro} for ui trace id "${uiTraceId}"`,
+      );
+    } catch (error) {
+      Logger.error('[ScreenLoading] Failed to end screen loading:', error);
+    }
+  }
+
+  /**
+   * 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 {
+    const span = this.activeSpans.get(spanId);
+    if (span) {
+      this.activeSpans.delete(spanId);
+      Logger.log(`[ScreenLoading] Discarded span ${spanId} for screen "${span.screenName}"`);
+    }
+  }
+
+  getActiveSpan(spanId: string): ScreenLoadingSpan | undefined {
+    return this.activeSpans.get(spanId);
+  }
+
+  getAllActiveSpans(): ScreenLoadingSpan[] {
+    return Array.from(this.activeSpans.values());
+  }
+
+  addSpanAttribute(spanId: string, key: string, value: number): void {
+    const span = this.activeSpans.get(spanId);
+    if (span) {
+      span.attributes.set(key, value);
+    }
+  }
+
+  private cleanupOldestSpans(): void {
+    const sortedSpans = Array.from(this.activeSpans.entries()).sort(
+      (a, b) => a[1].startTimestamp - b[1].startTimestamp,
+    );
+
+    const toRemove = Math.max(0, sortedSpans.length - 30);
+    for (let i = 0; i < toRemove; i++) {
+      this.activeSpans.delete(sortedSpans[i][0]);
+    }
+  }
+
+  isFeatureEnabled(): boolean {
+    return this.isEnabled;
+  }
+
+  isEndScreenLoadingFeatureEnabled(): boolean {
+    return this.isEnabled && this.isEndScreenLoadingEnabled;
+  }
+}
+
+export const ScreenLoadingManager = new ScreenLoadingManagerClass();

package/src/native/NativeAPM.ts

@@ -54,6 +54,28 @@ export interface ApmNativeModule extends NativeModule {
   isCustomSpanEnabled(): Promise<boolean>;
 
   isAPMEnabled(): Promise<boolean>;
+
+  // Screen Loading methods
+  initScreenFrameTracking(): Promise<void>;
+  setActiveScreenSpanId(spanId: string): void;
+  getScreenTimeToDisplay(spanId: string): Promise<number | null>;
+  isScreenLoadingEnabled(): Promise<boolean>;
+  isEndScreenLoadingEnabled(): Promise<boolean>;
+  endScreenLoading(timeStampMicro: number, uiTraceId: number): void;
+  setScreenLoadingEnabled(isEnabled: boolean): void;
+  syncScreenLoading(
+    spanId: number,
+    screenName: string,
+    startTimestamp: number,
+    durationUS: number,
+    attributes: Record<string, any>,
+  ): void;
+  syncManualScreenLoading(
+    screenName: string,
+    startTimestamp: number,
+    durationUS: number,
+    attributes: Record<string, any>,
+  ): void;
 }
 
 export const NativeAPM = NativeModules.LCQAPM;

package/src/native/NativeLuciq.ts

@@ -92,7 +92,7 @@ export interface LuciqNativeModule extends NativeModule {
     sessionReplay: ReproStepsMode,
   ): void;
   setTrackUserSteps(isEnabled: boolean): void;
-  reportScreenChange(firstScreen: string): void;
+  reportScreenChange(screenName: string, spanId: string | null): void;
   reportCurrentViewChange(screenName: string): void;
   addPrivateView(nativeTag: number | null): void;
   removePrivateView(nativeTag: number | null): void;