@luciq/react-native 19.4.0 → 19.6.0

package/dist/modules/apm/ScreenLoadingManager.js

@@ -0,0 +1,296 @@
+import { NativeAPM } from '../../native/NativeAPM';
+import { Logger } from '../../utils/logger';
+import { fromEpochMicros, nowMicros, toEpochMicros } from '../../utils/LuciqUtils';
+/**
+ * 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 {
+    activeSpans = new Map();
+    isInitialized = false;
+    isEnabled = false;
+    isEndScreenLoadingEnabled = false;
+    isFrameTrackingInitialized = false;
+    activeSpanId = null;
+    maxConcurrentSpans = 50;
+    excludedRoutes = new Set();
+    async initialize() {
+        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() {
+        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) {
+        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) {
+        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) {
+        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, isManual = false, startTimestampParam) {
+        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 = {
+            spanId,
+            screenName,
+            startTimestamp,
+            status: 'pending',
+            isManual,
+            attributes: new Map(),
+        };
+        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) {
+        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 = 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
+     */
+    logScreenLoading(span) {
+        // 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() {
+        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) {
+        const span = this.activeSpans.get(spanId);
+        if (span) {
+            this.activeSpans.delete(spanId);
+            Logger.log(`[ScreenLoading] Discarded span ${spanId} for screen "${span.screenName}"`);
+        }
+    }
+    getActiveSpan(spanId) {
+        return this.activeSpans.get(spanId);
+    }
+    getAllActiveSpans() {
+        return Array.from(this.activeSpans.values());
+    }
+    addSpanAttribute(spanId, key, value) {
+        const span = this.activeSpans.get(spanId);
+        if (span) {
+            span.attributes.set(key, value);
+        }
+    }
+    cleanupOldestSpans() {
+        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() {
+        return this.isEnabled;
+    }
+    isEndScreenLoadingFeatureEnabled() {
+        return this.isEnabled && this.isEndScreenLoadingEnabled;
+    }
+}
+export const ScreenLoadingManager = new ScreenLoadingManagerClass();

package/dist/native/NativeAPM.d.ts

@@ -17,6 +17,15 @@ export interface ApmNativeModule extends NativeModule {
     syncCustomSpan(name: string, startTimestamp: number, endTimestamp: number): Promise<void>;
     isCustomSpanEnabled(): Promise<boolean>;
     isAPMEnabled(): Promise<boolean>;
+    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 declare const NativeAPM: ApmNativeModule;
 export declare const emitter: NativeEventEmitter;

package/dist/native/NativeLuciq.d.ts

@@ -28,7 +28,7 @@ export interface LuciqNativeModule extends NativeModule {
     setNetworkLogBodyEnabled(isEnabled: boolean): void;
     setReproStepsConfig(bugMode: ReproStepsMode, crashMode: ReproStepsMode, 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;

package/dist/utils/LuciqUtils.d.ts

@@ -75,6 +75,30 @@ export declare function resetNativeObfuscationListener(): void;
  * This method is for internal use only.
  */
 export declare function updateNetworkLogSnapshot(networkSnapshot: NetworkData): void;
+/**
+ * @internal
+ * This method is for internal use only.
+ *
+ * Parses a string value to an integer, returning null if the value is null or cannot be parsed.
+ * @param value The string value to parse
+ * @returns The parsed integer or null
+ */
+export declare function getIntValue(value: string | null): number | null;
+/**
+ * Returns a high-resolution monotonic timestamp in microseconds.
+ * Use this for all internal duration measurements.
+ */
+export declare function nowMicros(): number;
+/**
+ * Converts an internal monotonic microsecond timestamp to epoch microseconds.
+ * Use this only when reporting to the native layer or external systems.
+ */
+export declare function toEpochMicros(monotonicUs: number): number;
+/**
+ * Converts an epoch microsecond timestamp to internal monotonic microseconds.
+ * Use this when receiving timestamps from the native layer that are epoch-based.
+ */
+export declare function fromEpochMicros(epochUs: number): number;
 declare const _default: {
     parseErrorStack: (error: ExtendedError) => StackFrame[];
     captureJsErrors: () => void;
@@ -82,6 +106,7 @@ declare const _default: {
     getFullRoute: typeof getFullRoute;
     getStackTrace: (e: ExtendedError) => StackFrame[];
     stringifyIfNotString: (input: unknown) => string;
+    getIntValue: typeof getIntValue;
     sendCrashReport: typeof sendCrashReport;
     reportNetworkLog: (network: NetworkData) => void;
     generateTracePartialId: () => {

package/dist/utils/LuciqUtils.js

@@ -304,6 +304,49 @@ export function resetNativeObfuscationListener() {
 export function updateNetworkLogSnapshot(networkSnapshot) {
     NativeNetworkLogger.updateNetworkLogSnapshot(networkSnapshot.url, networkSnapshot.id, networkSnapshot.requestBody, networkSnapshot.responseBody, networkSnapshot.responseCode ?? 200, networkSnapshot.requestHeaders, networkSnapshot.responseHeaders);
 }
+/**
+ * @internal
+ * This method is for internal use only.
+ *
+ * Parses a string value to an integer, returning null if the value is null or cannot be parsed.
+ * @param value The string value to parse
+ * @returns The parsed integer or null
+ */
+export function getIntValue(value) {
+    if (value === null) {
+        return null;
+    }
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? null : parsed;
+}
+// One-time anchor captured at module load to convert performance.now() to epoch time.
+// performance.now() gives high-resolution monotonic time (sub-ms precision) but relative
+// to app start. We pair it with Date.now() once, then derive epoch from the offset.
+const perfAnchorMs = performance.now();
+const epochAnchorUs = Date.now() * 1000;
+/**
+ * Returns a high-resolution monotonic timestamp in microseconds.
+ * Use this for all internal duration measurements.
+ */
+export function nowMicros() {
+    return performance.now() * 1000;
+}
+/**
+ * Converts an internal monotonic microsecond timestamp to epoch microseconds.
+ * Use this only when reporting to the native layer or external systems.
+ */
+export function toEpochMicros(monotonicUs) {
+    const offsetUs = monotonicUs - perfAnchorMs * 1000;
+    return epochAnchorUs + offsetUs;
+}
+/**
+ * Converts an epoch microsecond timestamp to internal monotonic microseconds.
+ * Use this when receiving timestamps from the native layer that are epoch-based.
+ */
+export function fromEpochMicros(epochUs) {
+    const offsetUs = epochUs - epochAnchorUs;
+    return perfAnchorMs * 1000 + offsetUs;
+}
 export default {
     parseErrorStack,
     captureJsErrors,
@@ -311,6 +354,7 @@ export default {
     getFullRoute,
     getStackTrace,
     stringifyIfNotString,
+    getIntValue,
     sendCrashReport,
     reportNetworkLog,
     generateTracePartialId,

package/dist/utils/RouteMatcher.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Matches route path definitions (potentially containing parameters and wildcards)
+ * against actual navigation paths.
+ *
+ * Supports `:param` segments for named parameters and `**` for wildcard matching.
+ */
+declare class RouteMatcher {
+    private static _instance;
+    static get instance(): RouteMatcher;
+    /** @internal visible for testing */
+    static setInstance(instance: RouteMatcher): void;
+    /**
+     * Checks whether the given `routePath` definition matches the given `actualPath`.
+     *
+     * The `routePath` definition can contain parameters in the form of `:param`,
+     * or `**` for a wildcard parameter.
+     *
+     * Returns `true` if the `actualPath` matches the `routePath`, otherwise `false`.
+     *
+     * @example
+     * ```ts
+     * RouteMatcher.instance.match('/users', '/users'); // true
+     * RouteMatcher.instance.match('/user/:id', '/user/123'); // true
+     * RouteMatcher.instance.match('/user/**', '/user/123/profile'); // true
+     * ```
+     */
+    match(routePath: string | null, actualPath: string | null): boolean;
+    private segmentPath;
+}
+export default RouteMatcher;

package/dist/utils/RouteMatcher.js

@@ -0,0 +1,67 @@
+// TODO: This class is currently unused but will be used later for route matching.
+/**
+ * Matches route path definitions (potentially containing parameters and wildcards)
+ * against actual navigation paths.
+ *
+ * Supports `:param` segments for named parameters and `**` for wildcard matching.
+ */
+class RouteMatcher {
+    static _instance = new RouteMatcher();
+    static get instance() {
+        return RouteMatcher._instance;
+    }
+    /** @internal visible for testing */
+    static setInstance(instance) {
+        RouteMatcher._instance = instance;
+    }
+    /**
+     * Checks whether the given `routePath` definition matches the given `actualPath`.
+     *
+     * The `routePath` definition can contain parameters in the form of `:param`,
+     * or `**` for a wildcard parameter.
+     *
+     * Returns `true` if the `actualPath` matches the `routePath`, otherwise `false`.
+     *
+     * @example
+     * ```ts
+     * RouteMatcher.instance.match('/users', '/users'); // true
+     * RouteMatcher.instance.match('/user/:id', '/user/123'); // true
+     * RouteMatcher.instance.match('/user/**', '/user/123/profile'); // true
+     * ```
+     */
+    match(routePath, actualPath) {
+        if (routePath == null || actualPath == null) {
+            return routePath === actualPath;
+        }
+        const routePathSegments = this.segmentPath(routePath);
+        const actualPathSegments = this.segmentPath(actualPath);
+        const hasWildcard = routePathSegments.includes('**');
+        if (routePathSegments.length !== actualPathSegments.length && !hasWildcard) {
+            return false;
+        }
+        for (let i = 0; i < routePathSegments.length; i++) {
+            const routeSegment = routePathSegments[i];
+            const isWildcard = routeSegment === '**';
+            const isParameter = routeSegment.startsWith(':');
+            const noMoreActualSegments = i >= actualPathSegments.length;
+            if (noMoreActualSegments) {
+                return isWildcard;
+            }
+            if (isParameter) {
+                continue;
+            }
+            if (isWildcard) {
+                return true;
+            }
+            if (routeSegment !== actualPathSegments[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    segmentPath(path) {
+        const pathWithoutQuery = path.split('?')[0];
+        return pathWithoutQuery.split('/').filter((segment) => segment.length > 0);
+    }
+}
+export default RouteMatcher;

package/ios/RNLuciq/LuciqAPMBridge.m

@@ -8,6 +8,7 @@
 #import <LuciqSDK/LCQTypes.h>
 #import <React/RCTUIManager.h>
 #import "Util/LCQAPM+PrivateAPIs.h"
+#import "LuciqScreenLoadingFrameTracker.h"
 
 @implementation LuciqAPMBridge
 
@@ -145,7 +146,88 @@ RCT_EXPORT_METHOD(isAPMEnabled:(RCTPromiseResolveBlock)resolve
     }
 }
 
+// Screen Loading methods
+RCT_EXPORT_METHOD(initScreenFrameTracking:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [[LuciqScreenLoadingFrameTracker sharedInstance] initializeFrameTracking];
+        resolve(nil);
+    });
+}
+
+RCT_EXPORT_METHOD(setActiveScreenSpanId:(NSString *)spanId)
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [[LuciqScreenLoadingFrameTracker sharedInstance] startTrackingForSpanId:spanId];
+    });
+}
+
+RCT_EXPORT_METHOD(getScreenTimeToDisplay:(NSString *)spanId
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        NSNumber *timestamp = [[LuciqScreenLoadingFrameTracker sharedInstance] getFrameTimestampForSpanId:spanId];
+        resolve(timestamp);
+    });
+}
+
+RCT_EXPORT_METHOD(isScreenLoadingEnabled:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject){
 
+    BOOL isScreenLoadingEnabled = LCQAPM.screenLoadingEnabled;
+    resolve(@(isScreenLoadingEnabled));
+}
+
+RCT_EXPORT_METHOD(isEndScreenLoadingEnabled:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject){
+
+    BOOL isEndScreenLoadingEnabled = LCQAPM.endScreenLoadingEnabled;
+    resolve(@(isEndScreenLoadingEnabled));
+}
+
+// uiTraceId is unused on iOS but required to keep the React Native Bridge call
+// signature consistent with Android, which uses it.
+RCT_EXPORT_METHOD(endScreenLoading:(double)timeStampMicro
+                  uiTraceId:(double)uiTraceId){
+    [LCQAPM endScreenLoadingCPWithEndTimestampMUS:timeStampMicro];
+}
+
+RCT_EXPORT_METHOD(setScreenLoadingEnabled:(BOOL)isEnabled){
+    LCQAPM.screenLoadingEnabled = isEnabled;
+}
+
+- (NSMutableDictionary<NSString *, NSNumber *> *)buildStagesMapFromAttributes:(NSDictionary *)stages {
+    NSMutableDictionary<NSString *, NSNumber *> *stagesMap = [NSMutableDictionary dictionary];
+    NSArray<NSString *> *keys = @[@"cnst_mus_st" , @"cnst_mus",@"rnd_mus_st", @"rnd_mus", @"mnt_mus_st" ,@"mnt_mus", @"lyt_mus_st" , @"lyt_mus"];
+    for (NSString *key in keys) {
+        if (stages[key])
+            stagesMap[key] = @([stages[key] longLongValue]);
+    }
+    return stagesMap;
+}
+
+// Syncs screen loading data to native layer for reporting
+RCT_EXPORT_METHOD(syncScreenLoading:(double)spanId
+                  screenName:(NSString *)screenName
+                  startTimestamp:(double)startTimestamp
+                  ttid_us:(double)ttid_us
+                  attributes:(NSDictionary *)stages){
+
+    NSMutableDictionary<NSString *, NSNumber *> *stagesMap = [self buildStagesMapFromAttributes:stages];
+    [LCQAPM reportScreenLoadingCPWithStartTimestampMUS:startTimestamp durationMUS:ttid_us stages:stagesMap];
+}
+
+// Syncs manual screen loading measurements to native layer for reporting (no span ID)
+RCT_EXPORT_METHOD(syncManualScreenLoading:(NSString *)screenName
+                  startTimestamp:(double)startTimestamp
+                  ttid_mus:(double)ttid_mus
+                  attributes:(NSDictionary *)stages){
+
+    NSMutableDictionary<NSString *, NSNumber *> *stagesMap = [self buildStagesMapFromAttributes:stages];
+    [LCQAPM reportScreenLoadingCPUITraceWithName:screenName screenLoadingStartMUS:startTimestamp screenLoadingDurationMUS:ttid_mus stages:stagesMap];
+}
 
 @synthesize description;
 

package/ios/RNLuciq/LuciqReactBridge.m

@@ -453,7 +453,7 @@ RCT_EXPORT_METHOD(show) {
     [[NSRunLoop mainRunLoop] performSelector:@selector(show) target:[Luciq class] argument:nil order:0 modes:@[NSDefaultRunLoopMode]];
 }
 
-RCT_EXPORT_METHOD(reportScreenChange:(NSString *)screenName) {
+RCT_EXPORT_METHOD(reportScreenChange:(NSString *)screenName spanId:(NSString * _Nullable)spanId) {
     SEL setPrivateApiSEL = NSSelectorFromString(@"logViewDidAppearEvent:");
     if ([[Luciq class] respondsToSelector:setPrivateApiSEL]) {
         NSInvocation *inv = [NSInvocation invocationWithMethodSignature:[[Luciq class] methodSignatureForSelector:setPrivateApiSEL]];

package/ios/RNLuciq/LuciqScreenLoadingFrameTracker.h

@@ -0,0 +1,11 @@
+#import <Foundation/Foundation.h>
+
+@interface LuciqScreenLoadingFrameTracker : NSObject
+
++ (instancetype)sharedInstance;
+- (void)startTrackingForSpanId:(NSString *)spanId;
+- (NSNumber *)getFrameTimestampForSpanId:(NSString *)spanId;
+- (void)initializeFrameTracking;
+- (void)cleanup;
+
+@end