@sentry/react 10.25.0 → 10.27.0

package/build/esm/reactrouter-compat-utils/instrumentation.js

@@ -4,7 +4,7 @@ import * as React from 'react';
 import { DEBUG_BUILD } from '../debug-build.js';
 import { hoistNonReactStatics } from '../hoist-non-react-statics.js';
 import { checkRouteForAsyncHandler } from './lazy-routes.js';
-import { resolveRouteNameAndSource, initializeRouterUtils } from './utils.js';
+import { resolveRouteNameAndSource, transactionNameHasWildcard, initializeRouterUtils } from './utils.js';
 
 /* eslint-disable max-lines */
 // Inspired from Donnie McNeal's solution:
@@ -16,14 +16,112 @@ let _useLocation;
 let _useNavigationType;
 let _createRoutesFromChildren;
 let _matchRoutes;
+
 let _enableAsyncRouteHandlers = false;
+let _lazyRouteTimeout = 3000;
 
 const CLIENTS_WITH_INSTRUMENT_NAVIGATION = new WeakSet();
 
+// Prevents duplicate spans when router.subscribe fires multiple times
+const activeNavigationSpans = new WeakMap
+
+();
+
+// Exported for testing only
+const allRoutes = new Set();
+
+// Tracks lazy route loads to wait before finalizing span names
+const pendingLazyRouteLoads = new WeakMap();
+
 /**
- * Adds resolved routes as children to the parent route.
- * Prevents duplicate routes by checking if they already exist.
+ * Schedules a callback using requestAnimationFrame when available (browser),
+ * or falls back to setTimeout for SSR environments (Node.js, createMemoryRouter tests).
  */
+function scheduleCallback(callback) {
+  if (WINDOW?.requestAnimationFrame) {
+    return WINDOW.requestAnimationFrame(callback);
+  }
+  return setTimeout(callback, 0) ;
+}
+
+/**
+ * Cancels a scheduled callback, handling both RAF (browser) and timeout (SSR) IDs.
+ */
+function cancelScheduledCallback(id) {
+  if (WINDOW?.cancelAnimationFrame) {
+    WINDOW.cancelAnimationFrame(id);
+  } else {
+    clearTimeout(id);
+  }
+}
+
+/**
+ * Computes location key for duplicate detection. Normalizes undefined/null to empty strings.
+ * Exported for testing.
+ */
+function computeLocationKey(location) {
+  return `${location.pathname}${location.search || ''}${location.hash || ''}`;
+}
+
+/**
+ * Checks if a route name is parameterized (contains route parameters like :id or wildcards like *)
+ * vs a raw URL path.
+ */
+function isParameterizedRoute(routeName) {
+  return routeName.includes(':') || routeName.includes('*');
+}
+
+/**
+ * Determines if a navigation should be skipped as a duplicate, and if an existing span should be updated.
+ * Exported for testing.
+ *
+ * @returns An object with:
+ *   - skip: boolean - Whether to skip creating a new span
+ *   - shouldUpdate: boolean - Whether to update the existing span name (wildcard upgrade)
+ */
+function shouldSkipNavigation(
+  trackedNav
+
+,
+  locationKey,
+  proposedName,
+  spanHasEnded,
+) {
+  if (!trackedNav) {
+    return { skip: false, shouldUpdate: false };
+  }
+
+  // Check if this is a duplicate navigation (same location)
+  // 1. If it's a placeholder, it's always a duplicate (we're waiting for the real one)
+  // 2. If it's a real span, it's a duplicate only if it hasn't ended yet
+  const isDuplicate = trackedNav.locationKey === locationKey && (trackedNav.isPlaceholder || !spanHasEnded);
+
+  if (isDuplicate) {
+    // Check if we should update the span name with a better route
+    // Allow updates if:
+    // 1. Current has wildcard and new doesn't (wildcard → parameterized upgrade)
+    // 2. Current is raw path and new is parameterized (raw → parameterized upgrade)
+    // 3. New name is different and more specific (longer, indicating nested routes resolved)
+    const currentHasWildcard = !!trackedNav.routeName && transactionNameHasWildcard(trackedNav.routeName);
+    const proposedHasWildcard = transactionNameHasWildcard(proposedName);
+    const currentIsParameterized = !!trackedNav.routeName && isParameterizedRoute(trackedNav.routeName);
+    const proposedIsParameterized = isParameterizedRoute(proposedName);
+
+    const isWildcardUpgrade = currentHasWildcard && !proposedHasWildcard;
+    const isRawToParameterized = !currentIsParameterized && proposedIsParameterized;
+    const isMoreSpecific =
+      proposedName !== trackedNav.routeName &&
+      proposedName.length > (trackedNav.routeName?.length || 0) &&
+      !proposedHasWildcard;
+
+    const shouldUpdate = !!(trackedNav.routeName && (isWildcardUpgrade || isRawToParameterized || isMoreSpecific));
+
+    return { skip: true, shouldUpdate };
+  }
+
+  return { skip: false, shouldUpdate: false };
+}
+
 function addResolvedRoutesToParent(resolvedRoutes, parentRoute) {
   const existingChildren = parentRoute.children || [];
 
@@ -42,9 +140,23 @@ function addResolvedRoutesToParent(resolvedRoutes, parentRoute) {
   }
 }
 
-// Keeping as a global variable for cross-usage in multiple functions
-// only exported for testing purposes
-const allRoutes = new Set();
+/** Registers a pending lazy route load promise for a span. */
+function trackLazyRouteLoad(span, promise) {
+  let promises = pendingLazyRouteLoads.get(span);
+  if (!promises) {
+    promises = new Set();
+    pendingLazyRouteLoads.set(span, promises);
+  }
+  promises.add(promise);
+
+  // Clean up when promise resolves/rejects
+  promise.finally(() => {
+    const currentPromises = pendingLazyRouteLoads.get(span);
+    if (currentPromises) {
+      currentPromises.delete(promise);
+    }
+  });
+}
 
 /**
  * Processes resolved routes by adding them to allRoutes and checking for nested async handlers.
@@ -110,13 +222,14 @@ function updateNavigationSpan(
   forceUpdate = false,
   matchRoutes,
 ) {
-  // Check if this span has already been named to avoid multiple updates
-  // But allow updates if this is a forced update (e.g., when lazy routes are loaded)
-  const hasBeenNamed =
-    !forceUpdate && (activeRootSpan )?.__sentry_navigation_name_set__;
+  const spanJson = spanToJSON(activeRootSpan);
+  const currentName = spanJson.description;
+
+  const hasBeenNamed = (activeRootSpan )?.__sentry_navigation_name_set__;
+  const currentNameHasWildcard = currentName && transactionNameHasWildcard(currentName);
+  const shouldUpdate = !hasBeenNamed || forceUpdate || currentNameHasWildcard;
 
-  if (!hasBeenNamed) {
-    // Get fresh branches for the current location with all loaded routes
+  if (shouldUpdate && !spanJson.timestamp) {
     const currentBranches = matchRoutes(allRoutes, location);
     const [name, source] = resolveRouteNameAndSource(
       location,
@@ -126,22 +239,105 @@ function updateNavigationSpan(
       '',
     );
 
-    // Only update if we have a valid name and the span hasn't finished
-    const spanJson = spanToJSON(activeRootSpan);
-    if (name && !spanJson.timestamp) {
+    const currentSource = spanJson.data?.[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE];
+    const isImprovement =
+      name &&
+      (!currentName || // No current name - always set
+        (!hasBeenNamed && (currentSource !== 'route' || source === 'route')) || // Not finalized - allow unless downgrading route→url
+        (currentSource !== 'route' && source === 'route') || // URL → route upgrade
+        (currentSource === 'route' && source === 'route' && currentNameHasWildcard)); // Route → better route (only if current has wildcard)
+    if (isImprovement) {
       activeRootSpan.updateName(name);
       activeRootSpan.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, source);
 
-      // Mark this span as having its name set to prevent future updates
-      addNonEnumerableProperty(
-        activeRootSpan ,
-        '__sentry_navigation_name_set__',
-        true,
-      );
+      // Only mark as finalized for non-wildcard route names (allows URL→route upgrades).
+      if (!transactionNameHasWildcard(name) && source === 'route') {
+        addNonEnumerableProperty(
+          activeRootSpan ,
+          '__sentry_navigation_name_set__',
+          true,
+        );
+      }
     }
   }
 }
 
+function setupRouterSubscription(
+  router,
+  routes,
+  version,
+  basename,
+  activeRootSpan,
+) {
+  let isInitialPageloadComplete = false;
+  let hasSeenPageloadSpan = !!activeRootSpan && spanToJSON(activeRootSpan).op === 'pageload';
+  let hasSeenPopAfterPageload = false;
+  let scheduledNavigationHandler = null;
+  let lastHandledPathname = null;
+
+  router.subscribe((state) => {
+    if (!isInitialPageloadComplete) {
+      const currentRootSpan = getActiveRootSpan();
+      const isCurrentlyInPageload = currentRootSpan && spanToJSON(currentRootSpan).op === 'pageload';
+
+      if (isCurrentlyInPageload) {
+        hasSeenPageloadSpan = true;
+      } else if (hasSeenPageloadSpan) {
+        if (state.historyAction === 'POP' && !hasSeenPopAfterPageload) {
+          hasSeenPopAfterPageload = true;
+        } else {
+          isInitialPageloadComplete = true;
+        }
+      }
+    }
+
+    const shouldHandleNavigation =
+      state.historyAction === 'PUSH' || (state.historyAction === 'POP' && isInitialPageloadComplete);
+
+    if (shouldHandleNavigation) {
+      // Include search and hash to allow query/hash-only navigations
+      // Use computeLocationKey() to ensure undefined/null values are normalized to empty strings
+      const currentLocationKey = computeLocationKey(state.location);
+      const navigationHandler = () => {
+        // Prevent multiple calls for the same location within the same navigation cycle
+        if (lastHandledPathname === currentLocationKey) {
+          return;
+        }
+        lastHandledPathname = currentLocationKey;
+        scheduledNavigationHandler = null;
+        handleNavigation({
+          location: state.location,
+          routes,
+          navigationType: state.historyAction,
+          version,
+          basename,
+          allRoutes: Array.from(allRoutes),
+        });
+      };
+
+      if (state.navigation.state !== 'idle') {
+        // Navigation in progress - reset if location changed
+        if (lastHandledPathname !== currentLocationKey) {
+          lastHandledPathname = null;
+        }
+        // Cancel any previously scheduled handler to avoid duplicates
+        if (scheduledNavigationHandler !== null) {
+          cancelScheduledCallback(scheduledNavigationHandler);
+        }
+        scheduledNavigationHandler = scheduleCallback(navigationHandler);
+      } else {
+        // Navigation completed - cancel scheduled handler if any, then call immediately
+        if (scheduledNavigationHandler !== null) {
+          cancelScheduledCallback(scheduledNavigationHandler);
+          scheduledNavigationHandler = null;
+        }
+        navigationHandler();
+        // Don't reset - next navigation cycle resets to prevent duplicates within same cycle.
+      }
+    }
+  });
+}
+
 /**
  * Creates a wrapCreateBrowserRouter function that can be used with all React Router v6 compatible versions.
  */
@@ -163,30 +359,17 @@ function createV6CompatibleWrapCreateBrowserRouter
   return function (routes, opts) {
     addRoutesToAllRoutes(routes);
 
-    // Check for async handlers that might contain sub-route declarations (only if enabled)
     if (_enableAsyncRouteHandlers) {
       for (const route of routes) {
         checkRouteForAsyncHandler(route, processResolvedRoutes);
       }
     }
 
-    // Wrap patchRoutesOnNavigation to detect when lazy routes are loaded
     const wrappedOpts = wrapPatchRoutesOnNavigation(opts);
-
     const router = createRouterFunction(routes, wrappedOpts);
     const basename = opts?.basename;
-
     const activeRootSpan = getActiveRootSpan();
 
-    // Track whether we've completed the initial pageload to properly distinguish
-    // between POPs that occur during pageload vs. legitimate back/forward navigation.
-    let isInitialPageloadComplete = false;
-    let hasSeenPageloadSpan = !!activeRootSpan && spanToJSON(activeRootSpan).op === 'pageload';
-    let hasSeenPopAfterPageload = false;
-
-    // The initial load ends when `createBrowserRouter` is called.
-    // This is the earliest convenient time to update the transaction name.
-    // Callbacks to `router.subscribe` are not called for the initial load.
     if (router.state.historyAction === 'POP' && activeRootSpan) {
       updatePageloadTransaction({
         activeRootSpan,
@@ -197,50 +380,7 @@ function createV6CompatibleWrapCreateBrowserRouter
       });
     }
 
-    router.subscribe((state) => {
-      // Track pageload completion to distinguish POPs during pageload from legitimate back/forward navigation
-      if (!isInitialPageloadComplete) {
-        const currentRootSpan = getActiveRootSpan();
-        const isCurrentlyInPageload = currentRootSpan && spanToJSON(currentRootSpan).op === 'pageload';
-
-        if (isCurrentlyInPageload) {
-          hasSeenPageloadSpan = true;
-        } else if (hasSeenPageloadSpan) {
-          // Pageload span was active but is now gone - pageload has completed
-          if (state.historyAction === 'POP' && !hasSeenPopAfterPageload) {
-            // Pageload ended: ignore the first POP after pageload
-            hasSeenPopAfterPageload = true;
-          } else {
-            // Pageload ended: either non-POP action or subsequent POP
-            isInitialPageloadComplete = true;
-          }
-        }
-        // If we haven't seen a pageload span yet, keep waiting (don't mark as complete)
-      }
-
-      const shouldHandleNavigation =
-        state.historyAction === 'PUSH' || (state.historyAction === 'POP' && isInitialPageloadComplete);
-
-      if (shouldHandleNavigation) {
-        const navigationHandler = () => {
-          handleNavigation({
-            location: state.location,
-            routes,
-            navigationType: state.historyAction,
-            version,
-            basename,
-            allRoutes: Array.from(allRoutes),
-          });
-        };
-
-        // Wait for the next render if loading an unsettled route
-        if (state.navigation.state !== 'idle') {
-          requestAnimationFrame(navigationHandler);
-        } else {
-          navigationHandler();
-        }
-      }
-    });
+    setupRouterSubscription(router, routes, version, basename, activeRootSpan);
 
     return router;
   };
@@ -272,14 +412,12 @@ function createV6CompatibleWrapCreateMemoryRouter
   ) {
     addRoutesToAllRoutes(routes);
 
-    // Check for async handlers that might contain sub-route declarations (only if enabled)
     if (_enableAsyncRouteHandlers) {
       for (const route of routes) {
         checkRouteForAsyncHandler(route, processResolvedRoutes);
       }
     }
 
-    // Wrap patchRoutesOnNavigation to detect when lazy routes are loaded
     const wrappedOpts = wrapPatchRoutesOnNavigation(opts, true);
 
     const router = createRouterFunction(routes, wrappedOpts);
@@ -317,58 +455,7 @@ function createV6CompatibleWrapCreateMemoryRouter
       });
     }
 
-    // Track whether we've completed the initial pageload to properly distinguish
-    // between POPs that occur during pageload vs. legitimate back/forward navigation.
-    let isInitialPageloadComplete = false;
-    let hasSeenPageloadSpan = !!memoryActiveRootSpan && spanToJSON(memoryActiveRootSpan).op === 'pageload';
-    let hasSeenPopAfterPageload = false;
-
-    router.subscribe((state) => {
-      // Track pageload completion to distinguish POPs during pageload from legitimate back/forward navigation
-      if (!isInitialPageloadComplete) {
-        const currentRootSpan = getActiveRootSpan();
-        const isCurrentlyInPageload = currentRootSpan && spanToJSON(currentRootSpan).op === 'pageload';
-
-        if (isCurrentlyInPageload) {
-          hasSeenPageloadSpan = true;
-        } else if (hasSeenPageloadSpan) {
-          // Pageload span was active but is now gone - pageload has completed
-          if (state.historyAction === 'POP' && !hasSeenPopAfterPageload) {
-            // Pageload ended: ignore the first POP after pageload
-            hasSeenPopAfterPageload = true;
-          } else {
-            // Pageload ended: either non-POP action or subsequent POP
-            isInitialPageloadComplete = true;
-          }
-        }
-        // If we haven't seen a pageload span yet, keep waiting (don't mark as complete)
-      }
-
-      const location = state.location;
-
-      const shouldHandleNavigation =
-        state.historyAction === 'PUSH' || (state.historyAction === 'POP' && isInitialPageloadComplete);
-
-      if (shouldHandleNavigation) {
-        const navigationHandler = () => {
-          handleNavigation({
-            location,
-            routes,
-            navigationType: state.historyAction,
-            version,
-            basename,
-            allRoutes: Array.from(allRoutes),
-          });
-        };
-
-        // Wait for the next render if loading an unsettled route
-        if (state.navigation.state !== 'idle') {
-          requestAnimationFrame(navigationHandler);
-        } else {
-          navigationHandler();
-        }
-      }
-    });
+    setupRouterSubscription(router, routes, version, basename, memoryActiveRootSpan);
 
     return router;
   };
@@ -393,6 +480,7 @@ function createReactRouterV6CompatibleTracingIntegration(
     enableAsyncRouteHandlers = false,
     instrumentPageLoad = true,
     instrumentNavigation = true,
+    lazyRouteTimeout,
   } = options;
 
   return {
@@ -400,6 +488,36 @@ function createReactRouterV6CompatibleTracingIntegration(
     setup(client) {
       integration.setup(client);
 
+      const finalTimeout = options.finalTimeout ?? 30000;
+      const defaultMaxWait = (options.idleTimeout ?? 1000) * 3;
+      const configuredMaxWait = lazyRouteTimeout ?? defaultMaxWait;
+
+      // Cap Infinity at finalTimeout to prevent indefinite hangs
+      if (configuredMaxWait === Infinity) {
+        _lazyRouteTimeout = finalTimeout;
+        DEBUG_BUILD &&
+          debug.log(
+            '[React Router] lazyRouteTimeout set to Infinity, capping at finalTimeout:',
+            finalTimeout,
+            'ms to prevent indefinite hangs',
+          );
+      } else if (Number.isNaN(configuredMaxWait)) {
+        DEBUG_BUILD &&
+          debug.warn('[React Router] lazyRouteTimeout must be a number, falling back to default:', defaultMaxWait);
+        _lazyRouteTimeout = defaultMaxWait;
+      } else if (configuredMaxWait < 0) {
+        DEBUG_BUILD &&
+          debug.warn(
+            '[React Router] lazyRouteTimeout must be non-negative or Infinity, got:',
+            configuredMaxWait,
+            'falling back to:',
+            defaultMaxWait,
+          );
+        _lazyRouteTimeout = defaultMaxWait;
+      } else {
+        _lazyRouteTimeout = configuredMaxWait;
+      }
+
       _useEffect = useEffect;
       _useLocation = useLocation;
       _useNavigationType = useNavigationType;
@@ -472,6 +590,9 @@ function createV6CompatibleWrapUseRoutes(origUseRoutes, version) {
         });
         isMountRenderPass.current = false;
       } else {
+        // Note: Component-based routes don't support lazy route tracking via lazyRouteTimeout
+        // because React.lazy() loads happen at the component level, not the router level.
+        // Use createBrowserRouter with patchRoutesOnNavigation for lazy route tracking.
         handleNavigation({
           location: normalizedLocation,
           routes,
@@ -506,7 +627,8 @@ function wrapPatchRoutesOnNavigation(
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
       const targetPath = (args )?.path;
 
-      // For browser router, wrap the patch function to update span during patching
+      const activeRootSpan = getActiveRootSpan();
+
       if (!isMemoryRouter) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
         const originalPatch = (args )?.patch;
@@ -514,13 +636,13 @@ function wrapPatchRoutesOnNavigation(
           // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
           (args ).patch = (routeId, children) => {
             addRoutesToAllRoutes(children);
-            const activeRootSpan = getActiveRootSpan();
-            if (activeRootSpan && (spanToJSON(activeRootSpan) ).op === 'navigation') {
+            const currentActiveRootSpan = getActiveRootSpan();
+            if (currentActiveRootSpan && (spanToJSON(currentActiveRootSpan) ).op === 'navigation') {
               updateNavigationSpan(
-                activeRootSpan,
+                currentActiveRootSpan,
                 { pathname: targetPath, search: '', hash: '', state: null, key: 'default' },
                 Array.from(allRoutes),
-                true, // forceUpdate = true since we're loading lazy routes
+                true,
                 _matchRoutes,
               );
             }
@@ -529,50 +651,48 @@ function wrapPatchRoutesOnNavigation(
         }
       }
 
-      const result = await originalPatchRoutes(args);
-
-      // Update navigation span after routes are patched
-      const activeRootSpan = getActiveRootSpan();
-      if (activeRootSpan && (spanToJSON(activeRootSpan) ).op === 'navigation') {
-        // Determine pathname based on router type
-        let pathname;
-        if (isMemoryRouter) {
-          // For memory routers, only use targetPath
-          pathname = targetPath;
-        } else {
-          // For browser routers, use targetPath or fall back to window.location
-          pathname = targetPath || WINDOW.location?.pathname;
+      const lazyLoadPromise = (async () => {
+        const result = await originalPatchRoutes(args);
+
+        const currentActiveRootSpan = getActiveRootSpan();
+        if (currentActiveRootSpan && (spanToJSON(currentActiveRootSpan) ).op === 'navigation') {
+          const pathname = isMemoryRouter ? targetPath : targetPath || WINDOW.location?.pathname;
+
+          if (pathname) {
+            updateNavigationSpan(
+              currentActiveRootSpan,
+              { pathname, search: '', hash: '', state: null, key: 'default' },
+              Array.from(allRoutes),
+              false,
+              _matchRoutes,
+            );
+          }
         }
 
-        if (pathname) {
-          updateNavigationSpan(
-            activeRootSpan,
-            { pathname, search: '', hash: '', state: null, key: 'default' },
-            Array.from(allRoutes),
-            false, // forceUpdate = false since this is after lazy routes are loaded
-            _matchRoutes,
-          );
-        }
+        return result;
+      })();
+
+      if (activeRootSpan) {
+        trackLazyRouteLoad(activeRootSpan, lazyLoadPromise);
       }
 
-      return result;
+      return lazyLoadPromise;
     },
   };
 }
 
+// eslint-disable-next-line complexity
 function handleNavigation(opts
 
 ) {
   const { location, routes, navigationType, version, matches, basename, allRoutes } = opts;
-  const branches = Array.isArray(matches) ? matches : _matchRoutes(routes, location, basename);
+  const branches = Array.isArray(matches) ? matches : _matchRoutes(allRoutes || routes, location, basename);
 
   const client = getClient();
   if (!client || !CLIENTS_WITH_INSTRUMENT_NAVIGATION.has(client)) {
     return;
   }
 
-  // Avoid starting a navigation span on initial load when a pageload root span is active.
-  // This commonly happens when lazy routes resolve during the first render and React Router emits a POP.
   const activeRootSpan = getActiveRootSpan();
   if (activeRootSpan && spanToJSON(activeRootSpan).op === 'pageload' && navigationType === 'POP') {
     return;
@@ -581,31 +701,90 @@ function handleNavigation(opts
   if ((navigationType === 'PUSH' || navigationType === 'POP') && branches) {
     const [name, source] = resolveRouteNameAndSource(
       location,
-      routes,
+      allRoutes || routes,
       allRoutes || routes,
       branches ,
       basename,
     );
 
-    const activeSpan = getActiveSpan();
-    const spanJson = activeSpan && spanToJSON(activeSpan);
-    const isAlreadyInNavigationSpan = spanJson?.op === 'navigation';
+    const locationKey = computeLocationKey(location);
+    const trackedNav = activeNavigationSpans.get(client);
+
+    // Determine if this navigation should be skipped as a duplicate
+    const trackedSpanHasEnded =
+      trackedNav && !trackedNav.isPlaceholder ? !!spanToJSON(trackedNav.span).timestamp : false;
+    const { skip, shouldUpdate } = shouldSkipNavigation(trackedNav, locationKey, name, trackedSpanHasEnded);
+
+    if (skip) {
+      if (shouldUpdate && trackedNav) {
+        const oldName = trackedNav.routeName;
+
+        if (trackedNav.isPlaceholder) {
+          // Update placeholder's route name - the real span will be created with this name
+          trackedNav.routeName = name;
+          DEBUG_BUILD &&
+            debug.log(
+              `[Tracing] Updated placeholder navigation name from "${oldName}" to "${name}" (will apply to real span)`,
+            );
+        } else {
+          // Update existing real span from wildcard to parameterized route name
+          trackedNav.span.updateName(name);
+          trackedNav.span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, source );
+          addNonEnumerableProperty(
+            trackedNav.span ,
+            '__sentry_navigation_name_set__',
+            true,
+          );
+          trackedNav.routeName = name;
+          DEBUG_BUILD && debug.log(`[Tracing] Updated navigation span name from "${oldName}" to "${name}"`);
+        }
+      } else {
+        DEBUG_BUILD && debug.log(`[Tracing] Skipping duplicate navigation for location: ${locationKey}`);
+      }
+      return;
+    }
 
-    // Cross usage can result in multiple navigation spans being created without this check
-    if (!isAlreadyInNavigationSpan) {
-      const navigationSpan = startBrowserTracingNavigationSpan(client, {
-        name,
+    // Create new navigation span (first navigation or legitimate new navigation)
+    // Reserve the spot in the map first to prevent race conditions
+    // Mark as placeholder to prevent concurrent handleNavigation calls from creating duplicates
+    const placeholderSpan = { end: () => {} } ;
+    const placeholderEntry = {
+      span: placeholderSpan,
+      routeName: name,
+      pathname: location.pathname,
+      locationKey,
+      isPlaceholder: true ,
+    };
+    activeNavigationSpans.set(client, placeholderEntry);
+
+    let navigationSpan;
+    try {
+      navigationSpan = startBrowserTracingNavigationSpan(client, {
+        name: placeholderEntry.routeName, // Use placeholder's routeName in case it was updated
         attributes: {
           [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
           [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
           [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: `auto.navigation.react.reactrouter_v${version}`,
         },
       });
+    } catch (e) {
+      // If span creation fails, remove the placeholder so we don't block future navigations
+      activeNavigationSpans.delete(client);
+      throw e;
+    }
 
-      // Patch navigation span to handle early cancellation (e.g., document.hidden)
-      if (navigationSpan) {
-        patchNavigationSpanEnd(navigationSpan, location, routes, basename, allRoutes);
-      }
+    if (navigationSpan) {
+      // Update the map with the real span (isPlaceholder omitted, defaults to false)
+      activeNavigationSpans.set(client, {
+        span: navigationSpan,
+        routeName: placeholderEntry.routeName, // Use the (potentially updated) placeholder routeName
+        pathname: location.pathname,
+        locationKey,
+      });
+      patchSpanEnd(navigationSpan, location, routes, basename, allRoutes, 'navigation');
+    } else {
+      // If no span was created, remove the placeholder
+      activeNavigationSpans.delete(client);
     }
   }
 }
@@ -654,7 +833,13 @@ function updatePageloadTransaction({
     : (_matchRoutes(allRoutes || routes, location, basename) );
 
   if (branches) {
-    const [name, source] = resolveRouteNameAndSource(location, routes, allRoutes || routes, branches, basename);
+    const [name, source] = resolveRouteNameAndSource(
+      location,
+      allRoutes || routes,
+      allRoutes || routes,
+      branches,
+      basename,
+    );
 
     getCurrentScope().setTransactionName(name || '/');
 
@@ -663,11 +848,93 @@ function updatePageloadTransaction({
       activeRootSpan.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, source);
 
       // Patch span.end() to ensure we update the name one last time before the span is sent
-      patchPageloadSpanEnd(activeRootSpan, location, routes, basename, allRoutes);
+      patchSpanEnd(activeRootSpan, location, routes, basename, allRoutes, 'pageload');
     }
   }
 }
 
+/**
+ * Determines if a span name should be updated during wildcard route resolution.
+ *
+ * Update conditions (in priority order):
+ * 1. No current name + allowNoCurrentName: true → always update (pageload spans)
+ * 2. Current name has wildcard + new is route without wildcard → upgrade (e.g., "/users/*" → "/users/:id")
+ * 3. Current source is not 'route' + new source is 'route' → upgrade (e.g., URL → parameterized route)
+ *
+ * @param currentName - The current span name (may be undefined)
+ * @param currentSource - The current span source ('route', 'url', or undefined)
+ * @param newName - The proposed new span name
+ * @param newSource - The proposed new span source
+ * @param allowNoCurrentName - If true, allow updates when there's no current name (for pageload spans)
+ * @returns true if the span name should be updated
+ */
+function shouldUpdateWildcardSpanName(
+  currentName,
+  currentSource,
+  newName,
+  newSource,
+  allowNoCurrentName = false,
+) {
+  if (!newName) {
+    return false;
+  }
+
+  if (!currentName && allowNoCurrentName) {
+    return true;
+  }
+
+  const hasWildcard = currentName && transactionNameHasWildcard(currentName);
+
+  if (hasWildcard && newSource === 'route' && !transactionNameHasWildcard(newName)) {
+    return true;
+  }
+
+  if (currentSource !== 'route' && newSource === 'route') {
+    return true;
+  }
+
+  return false;
+}
+
+function tryUpdateSpanNameBeforeEnd(
+  span,
+  spanJson,
+  currentName,
+  location,
+  routes,
+  basename,
+  spanType,
+  allRoutes,
+) {
+  try {
+    const currentSource = spanJson.data?.[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE];
+
+    if (currentSource === 'route' && currentName && !transactionNameHasWildcard(currentName)) {
+      return;
+    }
+
+    const currentAllRoutes = Array.from(allRoutes);
+    const routesToUse = currentAllRoutes.length > 0 ? currentAllRoutes : routes;
+    const branches = _matchRoutes(routesToUse, location, basename) ;
+
+    if (!branches) {
+      return;
+    }
+
+    const [name, source] = resolveRouteNameAndSource(location, routesToUse, routesToUse, branches, basename);
+
+    const isImprovement = shouldUpdateWildcardSpanName(currentName, currentSource, name, source, true);
+    const spanNotEnded = spanType === 'pageload' || !spanJson.timestamp;
+
+    if (isImprovement && spanNotEnded) {
+      span.updateName(name);
+      span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, source);
+    }
+  } catch (error) {
+    DEBUG_BUILD && debug.warn(`Error updating span details before ending: ${error}`);
+  }
+}
+
 /**
  * Patches the span.end() method to update the transaction name one last time before the span is sent.
  * This handles cases where the span is cancelled early (e.g., document.hidden) before lazy routes have finished loading.
@@ -687,71 +954,93 @@ function patchSpanEnd(
     return;
   }
 
+  // Use the passed route context, or fall back to global Set
+  const allRoutesSet = _allRoutes ? new Set(_allRoutes) : allRoutes;
+
   const originalEnd = span.end.bind(span);
+  let endCalled = false;
 
   span.end = function patchedEnd(...args) {
-    try {
-      // Only update if the span source is not already 'route' (i.e., it hasn't been parameterized yet)
-      const spanJson = spanToJSON(span);
-      const currentSource = spanJson.data?.[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE];
-      if (currentSource !== 'route') {
-        // Last chance to update the transaction name with the latest route info
-        // Use the live global allRoutes Set to include any lazy routes loaded after patching
-        const currentAllRoutes = Array.from(allRoutes);
-        const branches = _matchRoutes(
-          currentAllRoutes.length > 0 ? currentAllRoutes : routes,
-          location,
-          basename,
-        ) ;
+    if (endCalled) {
+      return;
+    }
+    endCalled = true;
+
+    // Capture timestamp immediately to avoid delay from async operations
+    // If no timestamp was provided, capture the current time now
+    const endTimestamp = args.length > 0 ? args[0] : Date.now() / 1000;
+
+    const spanJson = spanToJSON(span);
+    const currentName = spanJson.description;
+    const currentSource = spanJson.data?.[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE];
+
+    // Helper to clean up activeNavigationSpans after span ends
+    const cleanupNavigationSpan = () => {
+      const client = getClient();
+      if (client && spanType === 'navigation') {
+        const trackedNav = activeNavigationSpans.get(client);
+        if (trackedNav && trackedNav.span === span) {
+          activeNavigationSpans.delete(client);
+        }
+      }
+    };
+
+    const pendingPromises = pendingLazyRouteLoads.get(span);
+    // Wait for lazy routes if:
+    // 1. There are pending promises AND
+    // 2. Current name exists AND
+    // 3. Either the name has a wildcard OR the source is not 'route' (URL-based names)
+    const shouldWaitForLazyRoutes =
+      pendingPromises &&
+      pendingPromises.size > 0 &&
+      currentName &&
+      (transactionNameHasWildcard(currentName) || currentSource !== 'route');
+
+    if (shouldWaitForLazyRoutes) {
+      if (_lazyRouteTimeout === 0) {
+        tryUpdateSpanNameBeforeEnd(span, spanJson, currentName, location, routes, basename, spanType, allRoutesSet);
+        cleanupNavigationSpan();
+        originalEnd(endTimestamp);
+        return;
+      }
 
-        if (branches) {
-          const [name, source] = resolveRouteNameAndSource(
+      const allSettled = Promise.allSettled(pendingPromises).then(() => {});
+      const waitPromise =
+        _lazyRouteTimeout === Infinity
+          ? allSettled
+          : Promise.race([allSettled, new Promise(r => setTimeout(r, _lazyRouteTimeout))]);
+
+      waitPromise
+        .then(() => {
+          const updatedSpanJson = spanToJSON(span);
+          tryUpdateSpanNameBeforeEnd(
+            span,
+            updatedSpanJson,
+            updatedSpanJson.description,
             location,
             routes,
-            currentAllRoutes.length > 0 ? currentAllRoutes : routes,
-            branches,
             basename,
+            spanType,
+            allRoutesSet,
           );
-
-          // Only update if we have a valid name
-          if (name && (spanType === 'pageload' || !spanJson.timestamp)) {
-            span.updateName(name);
-            span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, source);
-          }
-        }
-      }
-    } catch (error) {
-      // Silently catch errors to ensure span.end() is always called
-      DEBUG_BUILD && debug.warn(`Error updating span details before ending: ${error}`);
+          cleanupNavigationSpan();
+          originalEnd(endTimestamp);
+        })
+        .catch(() => {
+          cleanupNavigationSpan();
+          originalEnd(endTimestamp);
+        });
+      return;
     }
 
-    return originalEnd(...args);
+    tryUpdateSpanNameBeforeEnd(span, spanJson, currentName, location, routes, basename, spanType, allRoutesSet);
+    cleanupNavigationSpan();
+    originalEnd(endTimestamp);
   };
 
-  // Mark this span as having its end() method patched to prevent duplicate patching
   addNonEnumerableProperty(span , patchedPropertyName, true);
 }
 
-function patchPageloadSpanEnd(
-  span,
-  location,
-  routes,
-  basename,
-  _allRoutes,
-) {
-  patchSpanEnd(span, location, routes, basename, _allRoutes, 'pageload');
-}
-
-function patchNavigationSpanEnd(
-  span,
-  location,
-  routes,
-  basename,
-  _allRoutes,
-) {
-  patchSpanEnd(span, location, routes, basename, _allRoutes, 'navigation');
-}
-
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function createV6CompatibleWithSentryReactRouterRouting(
   Routes,
@@ -787,11 +1076,13 @@ function createV6CompatibleWithSentryReactRouterRouting(
           });
           isMountRenderPass.current = false;
         } else {
+          // Note: Component-based routes don't support lazy route tracking via lazyRouteTimeout
+          // because React.lazy() loads happen at the component level, not the router level.
+          // Use createBrowserRouter with patchRoutesOnNavigation for lazy route tracking.
           handleNavigation({ location, routes, navigationType, version, allRoutes: Array.from(allRoutes) });
         }
       },
-      // `props.children` is purposely not included in the dependency array, because we do not want to re-run this effect
-      // when the children change. We only want to start transactions when the location or navigation type change.
+      // Re-run only on location/navigation changes, not children changes
       [location, navigationType],
     );
 
@@ -821,5 +1112,5 @@ function getActiveRootSpan() {
   return op === 'navigation' || op === 'pageload' ? rootSpan : undefined;
 }
 
-export { addResolvedRoutesToParent, addRoutesToAllRoutes, allRoutes, createReactRouterV6CompatibleTracingIntegration, createV6CompatibleWithSentryReactRouterRouting, createV6CompatibleWrapCreateBrowserRouter, createV6CompatibleWrapCreateMemoryRouter, createV6CompatibleWrapUseRoutes, handleNavigation, processResolvedRoutes, updateNavigationSpan };
+export { addResolvedRoutesToParent, addRoutesToAllRoutes, allRoutes, computeLocationKey, createReactRouterV6CompatibleTracingIntegration, createV6CompatibleWithSentryReactRouterRouting, createV6CompatibleWrapCreateBrowserRouter, createV6CompatibleWrapCreateMemoryRouter, createV6CompatibleWrapUseRoutes, handleNavigation, processResolvedRoutes, shouldSkipNavigation, updateNavigationSpan };
 //# sourceMappingURL=instrumentation.js.map