feat(android): Add sentry-android-navigation3 module (#5000)

Implements Sentry integration for Android Navigation 3 library.

This new module provides automatic breadcrumb capture and performance
tracing for navigation events in Compose applications using Navigation 3's
back stack-based architecture.

Key features:
- Observes back stack state changes using Compose snapshotFlow
- Captures breadcrumbs with from/to routes and back stack state
- Creates idle transactions for navigation events
- Each composable maintains independent transaction state for proper
  multi-pane/split-screen support
- Supports custom keyToRoute extraction for any back stack key type
- Multiplatform-friendly (Android + Desktop JVM targets)
- Respects global SentryOptions for tracing and screen tracking

Usage:
```kotlin
val backStack = rememberNavBackStack<NavKey>(HomeScreen)

// In your composable
SentryNavigation3Traced(
  backStack = backStack.toList()
)

// Or with custom configuration
SentryNavigation3Traced(
  backStack = backStack.toList(),
  enableNavigationBreadcrumbs = true,
  enableNavigationTracing = true,
  keyToRoute = { it.route }
)
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: markushi

sentry-android-navigation3/api/android/sentry-android-navigation3.api

@@ -7,7 +7,6 @@ public final class io/sentry/android/navigation3/BuildConfig {
 }
 
 public final class io/sentry/android/navigation3/SentryNavigation3IntegrationKt {
-	public static final fun withSentryObservableEffect (Landroidx/compose/runtime/snapshots/SnapshotStateList;ZZLkotlin/jvm/functions/Function1;Lio/sentry/IScopes;Landroidx/compose/runtime/Composer;II)Landroidx/compose/runtime/snapshots/SnapshotStateList;
-	public static final fun withSentryObservableEffect (Landroidx/compose/runtime/snapshots/SnapshotStateList;ZZLkotlin/jvm/functions/Function1;Lio/sentry/IScopes;Lkotlin/jvm/functions/Function2;Landroidx/compose/runtime/Composer;II)V
+	public static final fun SentryNavigation3Traced (Ljava/util/List;ZZLkotlin/jvm/functions/Function1;Lio/sentry/IScopes;Landroidx/compose/runtime/Composer;II)V
 }
 

sentry-android-navigation3/src/androidMain/kotlin/io/sentry/android/navigation3/SentryNavigation3Integration.kt

@@ -1,15 +1,11 @@
 package io.sentry.android.navigation3
 
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.DisposableEffect
-import androidx.compose.runtime.NonRestartableComposable
-import androidx.compose.runtime.compositionLocalOf
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberUpdatedState
 import androidx.compose.runtime.snapshotFlow
-import androidx.compose.runtime.snapshots.SnapshotStateList
 import io.sentry.Breadcrumb
 import io.sentry.Hint
 import io.sentry.IScopes
@@ -31,29 +27,24 @@ import kotlinx.coroutines.flow.onEach
 private const val TRACE_ORIGIN = "auto.navigation.navigation3"
 private const val NAVIGATION_OP = "navigation"
 
-/**
- * CompositionLocal that holds the active navigation transaction for the current navigation scope.
- * This allows multiple navigation instances to maintain separate transaction states.
- */
-internal val LocalNavigationTransaction = compositionLocalOf<NavigationTransactionHolder?> { null }
-
 /** Holder for the active navigation transaction in a composition scope. */
 internal class NavigationTransactionHolder {
   internal var activeTransaction: ITransaction? = null
 }
 
 /**
- * A [DisposableEffect] that observes a [SnapshotStateList] back stack and captures a [Breadcrumb]
- * and starts an [ITransaction] for each navigation event, sending them to Sentry.
+ * A Composable that observes a back stack [List] and captures a [Breadcrumb] and starts an
+ * [ITransaction] for each navigation event, sending them to Sentry.
  *
  * This integration is designed for Android Navigation 3 which uses a back stack-based approach with
  * Compose state observation instead of traditional listeners.
  *
- * This function creates a composition-local scope for transaction management, allowing multiple
- * navigation instances (e.g., in split-screen or multi-pane layouts) to maintain independent
- * transaction states.
+ * Each invocation of this composable maintains independent transaction state, allowing multiple
+ * navigation instances (e.g., in split-screen or multi-pane layouts) to coexist without
+ * interference.
  *
  * @param T The type of keys in the back stack
+ * @param backStack The current back stack to observe for navigation changes
  * @param enableNavigationBreadcrumbs Whether the integration should capture breadcrumbs for
  *   navigation events.
  * @param enableNavigationTracing Whether the integration should start a new idle [ITransaction]
@@ -62,30 +53,28 @@ internal class NavigationTransactionHolder {
  *   [Any.toString].
  * @param scopes The [IScopes] instance to use for capturing events. Defaults to the singleton
  *   instance.
- * @param content The composable content to display with this navigation scope.
  */
 @Composable
-@NonRestartableComposable
-public fun <T> SnapshotStateList<T>.withSentryObservableEffect(
+public fun <T> SentryNavigation3Traced(
+  backStack: List<T>,
   enableNavigationBreadcrumbs: Boolean = true,
   enableNavigationTracing: Boolean = true,
   keyToRoute: (T) -> String? = { it.toString() },
   scopes: IScopes = ScopesAdapter.getInstance(),
-  content: @Composable () -> Unit,
 ) {
+  val backStackSnapshot by rememberUpdatedState(backStack)
   val enableBreadcrumbsSnapshot by rememberUpdatedState(enableNavigationBreadcrumbs)
   val enableTracingSnapshot by rememberUpdatedState(enableNavigationTracing)
   val keyToRouteSnapshot by rememberUpdatedState(keyToRoute)
   val scopesSnapshot by rememberUpdatedState(scopes)
 
   val transactionHolder = remember { NavigationTransactionHolder() }
 
-  DisposableEffect(this) {
+  DisposableEffect(Unit) {
     addIntegrationToSdkVersion("Navigation3")
 
     val observer =
       SentryBackStackObserver(
-        backStack = this@withSentryObservableEffect,
         enableNavigationBreadcrumbs = enableBreadcrumbsSnapshot,
         enableNavigationTracing = enableTracingSnapshot,
         keyToRoute = keyToRouteSnapshot,
@@ -97,82 +86,32 @@ public fun <T> SnapshotStateList<T>.withSentryObservableEffect(
       kotlinx.coroutines.CoroutineScope(
         kotlinx.coroutines.Dispatchers.Main + kotlinx.coroutines.SupervisorJob()
       )
-    val job = observer.observe(scope)
-
-    onDispose { job.cancel() }
-  }
-
-  CompositionLocalProvider(LocalNavigationTransaction provides transactionHolder) { content() }
-}
-
-/**
- * A [DisposableEffect] that observes a [SnapshotStateList] back stack and captures a [Breadcrumb]
- * and starts an [ITransaction] for each navigation event, sending them to Sentry.
- *
- * This variant does not require a content block and is used when the back stack observation should
- * apply to the entire composition.
- *
- * @param T The type of keys in the back stack
- * @param enableNavigationBreadcrumbs Whether the integration should capture breadcrumbs for
- *   navigation events.
- * @param enableNavigationTracing Whether the integration should start a new idle [ITransaction]
- *   with [SentryOptions.idleTimeout] for navigation events.
- * @param keyToRoute A function to extract a route name from a back stack key. Defaults to
- *   [Any.toString].
- * @param scopes The [IScopes] instance to use for capturing events. Defaults to the singleton
- *   instance.
- * @return The same [SnapshotStateList] for chaining.
- */
-@Composable
-@NonRestartableComposable
-public fun <T> SnapshotStateList<T>.withSentryObservableEffect(
-  enableNavigationBreadcrumbs: Boolean = true,
-  enableNavigationTracing: Boolean = true,
-  keyToRoute: (T) -> String? = { it.toString() },
-  scopes: IScopes = ScopesAdapter.getInstance(),
-): SnapshotStateList<T> {
-  val enableBreadcrumbsSnapshot by rememberUpdatedState(enableNavigationBreadcrumbs)
-  val enableTracingSnapshot by rememberUpdatedState(enableNavigationTracing)
-  val keyToRouteSnapshot by rememberUpdatedState(keyToRoute)
-  val scopesSnapshot by rememberUpdatedState(scopes)
-
-  val transactionHolder = remember { NavigationTransactionHolder() }
-
-  DisposableEffect(this) {
-    addIntegrationToSdkVersion("Navigation3")
-
-    val observer =
-      SentryBackStackObserver(
-        backStack = this@withSentryObservableEffect,
-        enableNavigationBreadcrumbs = enableBreadcrumbsSnapshot,
-        enableNavigationTracing = enableTracingSnapshot,
-        keyToRoute = keyToRouteSnapshot,
-        scopes = scopesSnapshot,
-        transactionHolder = transactionHolder,
-      )
-
-    val scope =
-      kotlinx.coroutines.CoroutineScope(
-        kotlinx.coroutines.Dispatchers.Main + kotlinx.coroutines.SupervisorJob()
-      )
-    val job = observer.observe(scope)
+    val job =
+      snapshotFlow { backStackSnapshot }
+        .drop(1) // Skip initial state
+        .onEach { currentStack ->
+          val currentKey = currentStack.lastOrNull()
+          val previousKey = observer.previousKey
+          if (currentKey != null && currentKey != previousKey) {
+            observer.handleNavigation(currentKey, currentStack)
+            observer.previousKey = currentKey
+          }
+        }
+        .launchIn(scope)
 
     onDispose { job.cancel() }
   }
-
-  return this
 }
 
 /** Internal observer that monitors back stack changes and creates Sentry events. */
 internal class SentryBackStackObserver<T>(
-  private val backStack: SnapshotStateList<T>,
   private val enableNavigationBreadcrumbs: Boolean,
   private val enableNavigationTracing: Boolean,
   private val keyToRoute: (T) -> String?,
   private val scopes: IScopes,
   private val transactionHolder: NavigationTransactionHolder,
 ) {
-  private var previousKey: T? = null
+  internal var previousKey: T? = null
 
   private val isPerformanceEnabled: Boolean
     get() = scopes.options.isTracingEnabled && enableNavigationTracing
@@ -182,18 +121,6 @@ internal class SentryBackStackObserver<T>(
       .addPackage("maven:io.sentry:sentry-android-navigation3", BuildConfig.VERSION_NAME)
   }
 
-  fun observe(scope: kotlinx.coroutines.CoroutineScope) =
-    snapshotFlow { backStack.toList() }
-      .drop(1) // Skip initial state
-      .onEach { currentStack ->
-        val currentKey = currentStack.lastOrNull()
-        if (currentKey != null && currentKey != previousKey) {
-          handleNavigation(currentKey, currentStack)
-          previousKey = currentKey
-        }
-      }
-      .launchIn(scope)
-
   internal fun handleNavigation(currentKey: T, currentStack: List<T>) {
     val currentRoute = keyToRoute(currentKey)
     if (currentRoute != null) {

sentry-android-navigation3/src/androidUnitTest/kotlin/io/sentry/android/navigation3/SentryNavigation3IntegrationTest.kt

@@ -54,7 +54,6 @@ class SentryNavigation3IntegrationTest {
   fun `adds breadcrumb on navigation`() {
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = true,
         enableNavigationTracing = false,
         keyToRoute = { it },
@@ -81,7 +80,6 @@ class SentryNavigation3IntegrationTest {
   fun `adds breadcrumb with from and to routes`() {
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = true,
         enableNavigationTracing = false,
         keyToRoute = { it },
@@ -109,7 +107,6 @@ class SentryNavigation3IntegrationTest {
   fun `captures back stack keys in breadcrumb`() {
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = true,
         enableNavigationTracing = false,
         keyToRoute = { it },
@@ -137,7 +134,6 @@ class SentryNavigation3IntegrationTest {
   fun `does not add breadcrumb when disabled`() {
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = false,
         keyToRoute = { it },
@@ -161,7 +157,6 @@ class SentryNavigation3IntegrationTest {
 
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = true,
         keyToRoute = { it },
@@ -191,7 +186,6 @@ class SentryNavigation3IntegrationTest {
 
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = true,
         keyToRoute = { it },
@@ -215,7 +209,6 @@ class SentryNavigation3IntegrationTest {
 
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = true,
         keyToRoute = { it },
@@ -244,7 +237,6 @@ class SentryNavigation3IntegrationTest {
 
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = true,
         keyToRoute = { it },
@@ -272,7 +264,6 @@ class SentryNavigation3IntegrationTest {
 
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = true,
         keyToRoute = { it },
@@ -300,7 +291,6 @@ class SentryNavigation3IntegrationTest {
 
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = false,
         keyToRoute = { it },
@@ -321,7 +311,6 @@ class SentryNavigation3IntegrationTest {
 
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = false,
         keyToRoute = { it },
@@ -342,7 +331,6 @@ class SentryNavigation3IntegrationTest {
     val customBackStack = mutableStateListOf<NavKey>()
     val observer =
       SentryBackStackObserver(
-        backStack = customBackStack,
         enableNavigationBreadcrumbs = true,
         enableNavigationTracing = false,
         keyToRoute = { it.route },
@@ -364,7 +352,6 @@ class SentryNavigation3IntegrationTest {
   fun `handles null route from keyToRoute`() {
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = true,
         enableNavigationTracing = true,
         keyToRoute = { null },
@@ -393,7 +380,6 @@ class SentryNavigation3IntegrationTest {
 
     val observer =
       SentryBackStackObserver(
-        backStack = backStack,
         enableNavigationBreadcrumbs = false,
         enableNavigationTracing = true,
         keyToRoute = { it },