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

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/FeatureFlags.d.ts

@@ -1,3 +1,9 @@
+export declare function initFeatureFlagsCache(): Promise<void>;
+export declare function getCachedW3cFlags(): {
+    isW3cExternalTraceIDEnabled: boolean;
+    isW3cExternalGeneratedHeaderEnabled: boolean;
+    isW3cCaughtHeaderEnabled: boolean;
+};
 export declare const FeatureFlags: {
     isW3ExternalTraceID: () => Promise<boolean>;
     isW3ExternalGeneratedHeader: () => Promise<boolean>;

package/dist/utils/FeatureFlags.js

@@ -1,5 +1,34 @@
 import { NativeLuciq } from '../native/NativeLuciq';
 import { _registerFeatureFlagsChangeListener } from '../modules/Luciq';
+import { Logger } from './logger';
+const TAG = 'LCQ-RN-NET:';
+let cachedW3cFlags = {
+    isW3cExternalTraceIDEnabled: false,
+    isW3cExternalGeneratedHeaderEnabled: false,
+    isW3cCaughtHeaderEnabled: false,
+};
+export async function initFeatureFlagsCache() {
+    Logger.debug(TAG, '[FeatureFlags] Initializing W3C feature flags cache from native bridge...');
+    try {
+        const [traceID, generatedHeader, caughtHeader] = await Promise.all([
+            NativeLuciq.isW3ExternalTraceIDEnabled(),
+            NativeLuciq.isW3ExternalGeneratedHeaderEnabled(),
+            NativeLuciq.isW3CaughtHeaderEnabled(),
+        ]);
+        cachedW3cFlags = {
+            isW3cExternalTraceIDEnabled: traceID,
+            isW3cExternalGeneratedHeaderEnabled: generatedHeader,
+            isW3cCaughtHeaderEnabled: caughtHeader,
+        };
+        Logger.debug(TAG, `[FeatureFlags] Cache initialized: traceID=${traceID}, generatedHeader=${generatedHeader}, caughtHeader=${caughtHeader}`);
+    }
+    catch (e) {
+        Logger.debug(TAG, '[FeatureFlags] Failed to initialize cache, using defaults (all false):', e);
+    }
+}
+export function getCachedW3cFlags() {
+    return cachedW3cFlags;
+}
 export const FeatureFlags = {
     isW3ExternalTraceID: () => NativeLuciq.isW3ExternalTraceIDEnabled(),
     isW3ExternalGeneratedHeader: () => NativeLuciq.isW3ExternalGeneratedHeaderEnabled(),
@@ -8,6 +37,12 @@ export const FeatureFlags = {
 };
 export const registerFeatureFlagsListener = () => {
     _registerFeatureFlagsChangeListener((res) => {
+        Logger.debug(TAG, `[FeatureFlags] Flags updated from native listener: traceID=${res.isW3ExternalTraceIDEnabled}, generatedHeader=${res.isW3ExternalGeneratedHeaderEnabled}, caughtHeader=${res.isW3CaughtHeaderEnabled}, bodyLimit=${res.networkBodyLimit}`);
+        cachedW3cFlags = {
+            isW3cExternalTraceIDEnabled: res.isW3ExternalTraceIDEnabled,
+            isW3cExternalGeneratedHeaderEnabled: res.isW3ExternalGeneratedHeaderEnabled,
+            isW3cCaughtHeaderEnabled: res.isW3CaughtHeaderEnabled,
+        };
         FeatureFlags.isW3ExternalTraceID = async () => {
             return res.isW3ExternalTraceIDEnabled;
         };

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

@@ -3,6 +3,7 @@ import parseErrorStackLib from 'react-native/Libraries/Core/Devtools/parseErrorS
 import { NativeCrashReporting } from '../native/NativeCrashReporting';
 import { NativeLuciq } from '../native/NativeLuciq';
 import { NativeAPM } from '../native/NativeAPM';
+import { Logger } from './logger';
 import * as NetworkLogger from '../modules/NetworkLogger';
 import { NativeNetworkLogger, NativeNetworkLoggerEvent, NetworkListenerType, NetworkLoggerEmitter, } from '../native/NativeNetworkLogger';
 let apmFlags = {
@@ -181,10 +182,12 @@ export const reportNetworkLog = (network) => {
     if (Platform.OS === 'android') {
         const requestHeaders = JSON.stringify(network.requestHeaders);
         const responseHeaders = JSON.stringify(network.responseHeaders);
+        Logger.debug('LCQ-RN-NET:', `[reportNetworkLog] Sending to NativeLuciq.networkLogAndroid: ${network.method} ${network.url}, status=${network.responseCode}, duration=${network.duration}ms, error=${network.errorDomain || 'none'}`);
         NativeLuciq.networkLogAndroid(network.url, network.requestBody, network.responseBody, network.method, network.responseCode, requestHeaders, responseHeaders, network.duration);
         if (!apmFlags.isNativeInterceptionFeatureEnabled ||
             !apmFlags.hasAPMNetworkPlugin ||
             !apmFlags.shouldEnableNativeInterception) {
+            Logger.debug('LCQ-RN-NET:', `[reportNetworkLog] Also sending to NativeAPM.networkLogAndroid (native interception disabled): ${network.method} ${network.url}`);
             NativeAPM.networkLogAndroid(network.startTime, network.duration, requestHeaders, network.requestBody, network.requestBodySize, network.method, network.url, network.requestContentType, responseHeaders, network.responseBody, network.responseBodySize, network.responseCode, network.contentType, network.errorDomain, {
                 isW3cHeaderFound: network.isW3cHeaderFound,
                 partialId: network.partialId,
@@ -193,6 +196,9 @@ export const reportNetworkLog = (network) => {
                 w3cCaughtHeader: network.w3cCaughtHeader,
             }, network.gqlQueryName, network.serverErrorMessage);
         }
+        else {
+            Logger.debug('LCQ-RN-NET:', `[reportNetworkLog] Skipping NativeAPM.networkLogAndroid (native interception enabled): nativeFeature=${apmFlags.isNativeInterceptionFeatureEnabled}, hasPlugin=${apmFlags.hasAPMNetworkPlugin}, shouldEnable=${apmFlags.shouldEnableNativeInterception}`);
+        }
     }
     else {
         NativeLuciq.networkLogIOS(network.url, network.method, network.requestBody, network.requestBodySize, network.responseBody, network.responseBodySize, network.responseCode, network.requestHeaders, network.responseHeaders, network.contentType, network.errorDomain, network.errorCode, network.startTime, network.duration, network.gqlQueryName, network.serverErrorMessage, {
@@ -304,6 +310,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 +360,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;