reis-mobile 0.3.6 → 0.4.0

package/skills/android-navigation-3/references/android/guide/navigation/navigation-3/recipes/scenes-twopane.md

@@ -0,0 +1,244 @@
+# Two-Pane Scene Recipe
+
+This example shows how to create a two pane layout using the Scenes API.
+
+A `TwoPaneSceneStrategy` will return a `TwoPaneScene` if:
+
+- the window width is over 600dp
+- the last two nav entries on the back stack have indicated that they support being displayed in a `TwoPaneScene` in their metadata.
+
+See `TwoPaneScene.kt` for more implementation details.
+[![](https://developer.android.com/static/images/picto-icons/code.svg) Explore View the full recipe on GitHub.](https://github.com/android/nav3-recipes/tree/main/app/src/main/java/com/example/nav3recipes/scenes/twopane)
+
+```
+package com.example.nav3recipes.scenes.twopane
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.adaptive.currentWindowAdaptiveInfoV2
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavMetadataKey
+import androidx.navigation3.runtime.contains
+import androidx.navigation3.runtime.metadata
+import androidx.navigation3.scene.Scene
+import androidx.navigation3.scene.SceneStrategy
+import androidx.navigation3.scene.SceneStrategyScope
+import androidx.window.core.layout.WindowSizeClass
+import androidx.window.core.layout.WindowSizeClass.Companion.WIDTH_DP_MEDIUM_LOWER_BOUND
+
+// --- TwoPaneScene ---
+/**
+ * A custom [Scene] that displays two [NavEntry]s side-by-side in a 50/50 split.
+ */
+data class TwoPaneScene<T : Any>(
+    override val key: Any,
+    override val previousEntries: List<NavEntry<T>>,
+    val firstEntry: NavEntry<T>,
+    val secondEntry: NavEntry<T>
+) : Scene<T> {
+    override val entries: List<NavEntry<T>> = listOf(firstEntry, secondEntry)
+    override val content: @Composable (() -> Unit) = {
+        Row(modifier = Modifier.fillMaxSize()) {
+            Column(modifier = Modifier.weight(0.5f)) {
+                firstEntry.Content()
+            }
+            Column(modifier = Modifier.weight(0.5f)) {
+                secondEntry.Content()
+            }
+        }
+    }
+
+    companion object {
+        /**
+         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
+         * in a two-pane layout.
+         */
+        fun twoPane() = metadata {
+            put(TwoPaneKey, true)
+        }
+    }
+
+    object TwoPaneKey : NavMetadataKey<Boolean>
+}
+
+@Composable
+fun <T : Any> rememberTwoPaneSceneStrategy(): TwoPaneSceneStrategy<T> {
+    val windowSizeClass = currentWindowAdaptiveInfoV2().windowSizeClass
+
+    return remember(windowSizeClass) {
+        TwoPaneSceneStrategy(windowSizeClass)
+    }
+}
+
+
+// --- TwoPaneSceneStrategy ---
+/**
+ * A [SceneStrategy] that activates a [TwoPaneScene] if the window is wide enough
+ * and the top two back stack entries declare support for two-pane display.
+ */
+class TwoPaneSceneStrategy<T : Any>(val windowSizeClass: WindowSizeClass) : SceneStrategy<T> {
+
+    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? {
+
+        // Condition 1: Only return a Scene if the window is sufficiently wide to render two panes.
+        // We use isWidthAtLeastBreakpoint with WIDTH_DP_MEDIUM_LOWER_BOUND (600dp).
+        if (!windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND)) {
+            return null
+        }
+
+        val lastTwoEntries = entries.takeLast(2)
+
+        // Condition 2: Only return a Scene if there are two entries, and both have declared
+        // they can be displayed in a two pane scene.
+        return if (lastTwoEntries.size == 2
+            && lastTwoEntries.all { it.metadata.contains(TwoPaneScene.TwoPaneKey) }
+        ) {
+            val firstEntry = lastTwoEntries.first()
+            val secondEntry = lastTwoEntries.last()
+
+            // The scene key must uniquely represent the state of the scene.
+            // A Pair of the first and second entry keys ensures uniqueness.
+            val sceneKey = Pair(firstEntry.contentKey, secondEntry.contentKey)
+
+            TwoPaneScene(
+                key = sceneKey,
+                // Where we go back to is a UX decision. In this case, we only remove the top
+                // entry from the back stack, despite displaying two entries in this scene.
+                // This is because in this app we only ever add one entry to the
+                // back stack at a time. It would therefore be confusing to the user to add one
+                // when navigating forward, but remove two when navigating back.
+                previousEntries = entries.dropLast(1),
+                firstEntry = firstEntry,
+                secondEntry = secondEntry
+            )
+
+        } else {
+            null
+        }
+    }
+
+
+}
+```
+
+```
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.nav3recipes.scenes.twopane
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.animation.SharedTransitionLayout
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Column
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavBackStack
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentBase
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.content.ContentRed
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import com.example.nav3recipes.ui.theme.colors
+import kotlinx.serialization.Serializable
+
+@Serializable
+private object Home : NavKey
+
+@Serializable
+private data class Product(val id: Int) : NavKey
+
+@Serializable
+private data object Profile : NavKey
+
+class TwoPaneActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+
+        setContent {
+            val backStack = rememberNavBackStack(Home)
+            val twoPaneStrategy = rememberTwoPaneSceneStrategy<NavKey>()
+
+            SharedTransitionLayout {
+                NavDisplay(
+                    backStack = backStack,
+                    onBack = { backStack.removeLastOrNull() },
+                    sceneStrategies = listOf(twoPaneStrategy),
+                    sharedTransitionScope = this,
+                    entryProvider = entryProvider {
+                        entry<Home>(
+                            metadata = TwoPaneScene.twoPane()
+                        ) {
+                            ContentRed("Welcome to Nav3") {
+                                Button(onClick = { backStack.addProductRoute(1) }) {
+                                    Text("View the first product")
+                                }
+                            }
+                        }
+                        entry<Product>(
+                            metadata = TwoPaneScene.twoPane()
+                        ) { product ->
+                            ContentBase(
+                                "Product ${product.id} ",
+                                Modifier.background(colors[product.id % colors.size])
+                            ) {
+                                Column(horizontalAlignment = Alignment.CenterHorizontally) {
+                                    Button(onClick = dropUnlessResumed {
+                                        backStack.addProductRoute(product.id + 1)
+                                    }) {
+                                        Text("View the next product")
+                                    }
+                                    Button(onClick = dropUnlessResumed {
+                                        backStack.add(Profile)
+                                    }) {
+                                        Text("View profile")
+                                    }
+                                }
+                            }
+                        }
+                        entry<Profile> {
+                            ContentGreen("Profile (single pane only)")
+                        }
+                    }
+                )
+            }
+        }
+    }
+}
+
+private fun NavBackStack<NavKey>.addProductRoute(productId: Int) {
+    val productRoute =
+        Product(productId)
+    // Avoid adding the same product route to the back stack twice.
+    if (!contains(productRoute)) {
+        add(productRoute)
+    }
+}
+```

package/skills/android-navigation-3/references/android/guide/navigation/type-safe-destinations.md

@@ -0,0 +1,129 @@
+This guide outlines the process of replacing string-based routes with
+serializable Kotlin types to achieve compile-time safety and eliminate runtime
+crashes caused by typos or incorrect argument types.
+
+## Prerequisites
+
+Before starting the migration, verify that your project meets the following
+requirements:
+
+1. **Navigation version**: Update to Jetpack Navigation 2.8.0 or higher
+2. **Kotlin serialization plugin**:
+3. Add the plugin to `libs.versions.toml`:
+
+    [libraries]
+    kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerializationJson" }
+
+    [plugins]
+    kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+
+- Add the dependencies to your top-level `build.gradle.kts` and module-level `build.gradle.kts`.
+
+## Step 1: Define Your Destinations
+
+Replace your constant route strings with `@Serializable` objects and classes.
+
+- **For screens without arguments** : Use a `data object`
+- **For screens with arguments** : Use a `data class`
+
+**Before (string based):**
+
+    const val ROUTE_HOME = "home"
+    const val ROUTE_PROFILE = "profile/{userId}"
+
+**After (type safe):**
+
+    import kotlinx.serialization.Serializable
+
+    @Serializable
+    object Home
+
+    @Serializable
+    data class Profile(val userId: String)
+
+## Step 2: Update the NavHost Configuration
+
+Update your `NavHost` to use the new generic types in the `composable` and
+`dialog` function.
+
+**Before:**
+
+    NavHost(navController, startDestination = "home") {
+        composable("home") { HomeScreen(...) }
+        composable("profile/{userId}") { backStackEntry ->
+            val userId = backStackEntry.arguments?.getString("userId")
+            ProfileScreen(userId)
+        }
+    }
+
+**After:**
+
+    NavHost(navController, startDestination = Home) {
+        composable<Home> {
+            HomeScreen(...)
+        }
+        composable<Profile> { backStackEntry ->
+            // The library automatically handles argument extraction
+            val profile: Profile = backStackEntry.toRoute()
+            ProfileScreen(profile.userId)
+        }
+    }
+
+## Step 3: Implement Type-Safe Navigation Calls
+
+Replace string-interpolated navigation calls with class instances.
+
+**Before:**
+
+    navController.navigate("profile/user123")
+
+**After:**
+
+    navController.navigate(Profile(userId = "user123"))
+
+## Step 4: Accessing Arguments in ViewModels
+
+If you use a `ViewModel`, you can now extract the route object directly from the
+`SavedStateHandle`.
+
+**Implementation:**
+
+    class ProfileViewModel(
+        savedStateHandle: SavedStateHandle
+    ) : ViewModel() {
+        // Automatically parses arguments into the Profile class
+        private val profile = savedStateHandle.toRoute<Profile>()
+        val userId = profile.userId
+    }
+
+## Step 5: (Advanced) Handling Custom Types
+
+If you need to pass complex data classes (not just primitives), you must define
+a custom `NavType`.
+
+1. **Create the Custom Type** : \`\`\`kotlin val SearchFilterType = object : NavType(isNullableAllowed = false) { override fun get(bundle: Bundle, key: String): SearchFilter? = Json.decodeFromString(bundle.getString(key) ?: return null)
+
+    override fun parseValue(value: String): SearchFilter =
+        Json.decodeFromString(Uri.decode(value))
+
+    override fun put(bundle: Bundle, key: String, value: SearchFilter) {
+        bundle.putString(key, Json.encodeToString(value))
+    }
+
+}
+
+
+
+    2. **Register it in the Graph**:
+    ```kotlin
+    composable<Search>(
+        typeMap = mapOf(typeOf<SearchFilter>() to SearchFilterType)
+    ) { ... }
+
+## Best practices and tips
+
+- **Sealed Hierarchies**: For large apps, group your routes using a sealed interface or class to keep the navigation structure organized
+- **Object Instances** : For routes without parameters, always use `object` instead of `class` to avoid unnecessary allocations
+- **Nullable Types** : The new API supports nullable types (for example, `data
+  class Search(val query: String?)`) and provides default values automatically
+- **Testing** : Use `navController.currentBackStackEntry?.hasRoute<T>()` to check the current destination in a type-safe manner during UI tests

package/skills/android-navigation-event/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: android-navigation-event
+description: Intercept back gestures and run Predictive Back animations using the
+  NavigationEvent (androidx.navigationevent) library in Compose Android. Handles Activity
+  setup, parent-child dispatcher scoping in `ViewPagers` or tabs, Compose `NavigationBackHandler`,
+  and migration from legacy `BackHandler` on SDK 36+.
+license: Apache-2.0
+source: https://github.com/android/skills
+routing: manual
+stacks: [android]
+metadata:
+  author: Google LLC
+  last-updated: '2026-09-01'
+  keywords:
+  - Android
+  - Navigation Event
+  - Jetpack Compose
+  - Back Navigation
+  - Dispatcher
+  - Guidelines
+  - Troubleshooting
+  - ComponentActivity
+  - Dialog
+  - ViewPager
+---
+
+## Common guidelines
+
+- **For architecture concepts** : To understand the foundational architecture, continuous gesture event lifecycles, or class definitions of the Navigation Event library, read [Navigation Event overview](references/android/guide/navigation/navigation-event/index.md).
+- **For Android target** : If compile SDK is lower than 36, set it to `36` or higher in `build.gradle.kts`.
+- **For Compose Android target**: The project must use Jetpack Compose for Compose-specific APIs. This skill is scoped exclusively to Compose Android (Android Views and non-Compose implementations are excluded).
+- **For activity dispatchers** : `ComponentActivity` automatically implements `NavigationEventDispatcherOwner` out-of-the-box. You must use the built-in `navigationEventDispatcher` without creating anonymous delegate owners or overriding member properties.
+- **For dialog scoping** : Floating windows (Compose `Dialog`, `ModalBottomSheet`, `ComponentDialog`) automatically provide a `NavigationEventDispatcherOwner`. You don't need manual `CompositionLocalProvider` propagation for dialogs.
+- **For parent-child dispatcher hierarchies** : When scoping navigation handling to `ViewPagers`, tabbed interfaces, or nested navigation containers in Compose, use `rememberNavigationEventDispatcherOwner()` to create a child owner linked to the parent. Disabling the owner (`enabled = false`) automatically cascades to disable all child handlers.
+- **For Compose handlers** : A one-to-one relationship between `NavigationEventState` and handlers is strictly enforced. Never bind the same `NavigationEventState` to multiple active `NavigationBackHandler` instances (`IllegalArgumentException`).
+
+## Step 1: Plan
+
+To complete this step, you **MUST** ensure the following:
+
+1. **Identify the target platform** : Verify the app is targeting Compose Android. If `compileSdk` is lower than 36, set it to `36` or higher in `build.gradle.kts`.
+2. **Navigation check**: Check if Navigation 3 is in use. If it is in use, use Navigation 3's built-in back navigation support rather than manually implementing low-level dispatchers from this skill.
+3. **Hierarchy check** : Identify host Activities, `ViewPagers`, tabbed interfaces, or nested navigation hosts that require back gesture interception or parent-child dispatcher linking.
+4. **Migration check** : Check if the project is migrating from back handling (`OnBackPressedCallback`, `BackHandler`, `onBackPresser`) to `NavigationEvent` and `NavigationBackHandler`.
+5. **Input interception** : Detect where the app is intercepting navigation events from gestures or hardware button presses requiring translation to `NavigationEvent`.
+
+## Step 2: Set up dependencies
+
+To complete this step, you **MUST** ensure the following:
+
+- For setting up compile SDKs, declaring catalog versions, and adding dependencies, follow [setup guide](references/android/guide/navigation/navigation-event/setup.md).
+
+## Step 3: Configure dispatcher and inputs
+
+To complete this step, you **MUST** ensure the following:
+
+- To configure your dispatcher, leverage automatic `ComponentActivity` or `ComponentDialog` owner resolution.
+- Link parent-child dispatchers in Compose following [dispatcher guide](references/android/guide/navigation/navigation-event/dispatcher.md).
+
+## Step 4: Handle back navigation and UI transitions
+
+To complete this step, you **MUST** ensure the following:
+
+- To create navigation event handlers, integrate back gesture interception in Compose, animate UI components during swipes, and migrate from legacy back handlers, follow [handle back guide](references/android/guide/navigation/navigation-event/handle-back.md).
+
+## Step 5: Clean up resources
+
+> [!WARNING]
+> **Warning:** Compose APIs perform teardown automatically. When using Compose APIs such as `NavigationBackHandler` and `rememberNavigationEventDispatcherOwner()`, handler removal and dispatcher disposal occur automatically when the composable leaves the composition.
+
+You **MUST** perform explicit manual cleanup only when managing custom
+dispatchers or non-Compose handlers:
+
+- Call `remove()` on active handlers during teardown.
+- Call `isEnabled = false` to temporarily disable navigation subtrees.
+- Call `dispose()` on dispatcher instances when hosting components are destroyed. Disposing a parent dispatcher automatically cascades to all child dispatchers.
+
+## Core troubleshooting guidelines
+
+### 1. Activity dispatcher setup (StackOverflowError recursion)
+
+`ComponentActivity` implements `NavigationEventDispatcherOwner` automatically
+out-of-the-box. Don't override `navigationEventDispatcher` or wrap it in an
+anonymous delegate owner.
+
+#### RIGHT
+
+**Why this is RIGHT** : Compose apps use `ComponentActivity` as the host.
+`LocalNavigationEventDispatcherOwner.current` automatically resolves the
+Activity's built-in dispatcher.
+
+
+```kotlin
+// RIGHT
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            MyApplicationContent()
+        }
+    }
+}
+```
+
+<br />
+
+#### WRONG
+
+**Why this is WRONG** : Implementing `NavigationEventDispatcherOwner` directly on
+`MainActivity` and overriding `navigationEventDispatcher` with a new instance
+shadows the library's extension property, causing a recursive infinite loop
+crash on launch (`StackOverflowError`). Creating redundant anonymous delegate
+owners (`object : NavigationEventDispatcherOwner`) is unnecessary.
+
+
+```kotlin
+// WRONG
+class MainActivity : ComponentActivity(), NavigationEventDispatcherOwner {
+    override val navigationEventDispatcher = NavigationEventDispatcher() // Shadow loop crash
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            MyApplicationContent()
+        }
+    }
+}
+```
+
+<br />
+
+### 2. Floating window and dialog scoping (automatic ComponentDialog owner)
+
+Floating windows (Compose `Dialog`, `ModalBottomSheet`, and any window backed by
+`ComponentDialog`) automatically provide a `NavigationEventDispatcherOwner`.
+Don't manually re-provide `LocalNavigationEventDispatcherOwner` using
+`CompositionLocalProvider` inside dialogs.
+
+#### RIGHT
+
+**Why this is RIGHT** : `ComponentDialog` handles navigation dispatchers
+automatically. Compose `Dialog` components resolve their dispatcher owner
+out-of-the-box without manual propagation.
+
+
+```kotlin
+// RIGHT
+@Composable
+fun MyDialog(onDismiss: () -> Unit) {
+    Dialog(onDismissRequest = onDismiss) {
+        val navigationState = rememberNavigationEventState(currentInfo = NavigationEventInfo.None)
+        NavigationBackHandler(
+            state = navigationState,
+            onBackCompleted = onDismiss
+        )
+    }
+}
+```
+
+<br />
+
+#### WRONG
+
+**Why this is WRONG** : Wrapping dialog content in a manual
+`CompositionLocalProvider` creates redundant boilerplate and obscures the
+automatic dispatcher resolution provided by `ComponentDialog`.
+
+
+```kotlin
+// WRONG
+@Composable
+fun MyDialog(onDismiss: () -> Unit) {
+    val dispatcherOwner = LocalNavigationEventDispatcherOwner.current!!
+    Dialog(onDismissRequest = onDismiss) {
+        // Redundant: ComponentDialog provides NavigationEventDispatcherOwner automatically
+        CompositionLocalProvider( LocalNavigationEventDispatcherOwner provides dispatcherOwner) {
+            val navigationState = rememberNavigationEventState(currentInfo = NavigationEventInfo.None)
+            NavigationBackHandler(
+                state = navigationState,
+                onBackCompleted = onDismiss
+            )
+        }
+    }
+}
+```
+
+<br />
+
+### 3. Parent-child dispatcher hierarchy (`ViewPagers` and nested navigation)
+
+When managing nested UI hierarchies such as `ViewPagers`, tabbed
+interfaces, or custom navigation containers in Compose, use
+`rememberNavigationEventDispatcherOwner()` to create a child owner linked to the
+composition hierarchy. Setting `enabled = false` on the child owner
+automatically disables its dispatcher and all registered child handlers.
+
+#### RIGHT
+
+**Why this is RIGHT** : Using `rememberNavigationEventDispatcherOwner(enabled =
+isSelected)` creates a scoped child dispatcher linked to the parent from
+`LocalNavigationEventDispatcherOwner.current`. Providing it using
+`CompositionLocalProvider` ensures non-visible tabs or pages automatically stop
+intercepting back gestures without leaking handlers.
+
+
+```kotlin
+// RIGHT: Scoping child navigation in a ViewPager or Tab interface
+@Composable
+fun TabPage(isSelected: Boolean) {
+    val childOwner = rememberNavigationEventDispatcherOwner(enabled = isSelected)
+    CompositionLocalProvider(LocalNavigationEventDispatcherOwner provides childOwner) {
+        val navigationState = rememberNavigationEventState(currentInfo = NavigationEventInfo.None)
+        NavigationBackHandler(
+            state = navigationState,
+            onBackCompleted = { /* Handle page back navigation */ }
+        )
+        // Page content
+    }
+}
+```
+
+<br />
+
+#### WRONG
+
+**Why this is WRONG** : Creating unlinked standalone dispatchers, instantiating
+raw dispatchers without remembering them across recompositions, or attempting to
+use non-existent methods like `.addChild()` breaks hierarchy routing and leaves
+child handlers active even when the page is inactive.
+
+
+```kotlin
+// WRONG
+@Composable
+fun TabPage(isSelected: Boolean) {
+    val parentDispatcher = LocalNavigationEventDispatcherOwner.current?.navigationEventDispatcher
+    val childDispatcher = NavigationEventDispatcher() // Unlinked and not remembered across recompositions
+    // WRONG: Method does not exist
+    parentDispatcher?.addChild(childDispatcher)
+}
+```
+
+<br />
+
+### 4. Compose multi-handler registration (IllegalArgumentException)
+
+You must not bind the same `NavigationEventState` to multiple active
+`NavigationBackHandler` instances, as this throws an `IllegalArgumentException`
+at runtime. To handle conditional workflows (such as checking for unsaved
+changes versus navigating back immediately), you must register a single unified
+handler and branch logic inside `onBackCompleted`.
+
+#### RIGHT
+
+**Why this is RIGHT** : Using a single `NavigationBackHandler` with internal
+branching logic inside `onBackCompleted` maintains a strict 1:1 mapping between
+`NavigationEventState` and the handler, preventing state collisions.
+
+
+```kotlin
+// RIGHT
+val navigationState = rememberNavigationEventState(currentInfo = NavigationEventInfo.None)
+NavigationBackHandler(
+    state = navigationState,
+    isBackEnabled = true,
+    onBackCompleted = {
+        if (hasUnsavedChanges) {
+            showDiscardDialog()
+        } else {
+            onNavigateUp()
+        }
+    }
+)
+```
+
+<br />
+
+#### WRONG
+
+**Why this is WRONG** : Attaching multiple `NavigationBackHandler` composables to
+the same `navigationState` instance attempts to bind duplicate handlers to a
+single state object, which throws an `IllegalArgumentException` at runtime.
+
+
+```kotlin
+// WRONG
+val navigationState = rememberNavigationEventState(currentInfo = NavigationEventInfo.None)
+NavigationBackHandler(
+    state = navigationState,
+    isBackEnabled = hasUnsavedChanges,
+    onBackCompleted = { /* Discard changes */ }
+)
+NavigationBackHandler(
+    state = navigationState,
+    isBackEnabled = !hasUnsavedChanges,
+    onBackCompleted = { /* Navigate up */ }
+)
+```
+
+<br />
+
+## Checklist
+
+**For Compose Android targets:**
+
+- \[ \] Is compile SDK set to `36` or higher? (If compile SDK is lower than 36, set it to `36` or higher in `build.gradle.kts`).
+- \[ \] Is `android:enableOnBackInvokedCallback` NOT explicitly set to `"false"` in `AndroidManifest.xml`? (On API 36+, it defaults to `"true"`; on API 33--35, ensure it is set to `"true"`).
+- \[ \] Does the Activity rely on the built-in `ComponentActivity` dispatcher owner without redundant anonymous delegate wrapping?
+- \[ \] Do dialogs or sheets rely on automatic `ComponentDialog` dispatcher resolution without redundant `CompositionLocalProvider` wrapping?
+- \[ \] Are parent-child dispatcher relationships in Compose scoped using `rememberNavigationEventDispatcherOwner()` when managing nested hierarchies?
+- \[ \] Is conditional back logic handled within a single unified `NavigationBackHandler` to avoid duplicate registration (`IllegalArgumentException`)?
+- \[ \] Are legacy `BackHandler` usages migrated to `NavigationBackHandler` with predictive progress support?
+- \[ \] Does the project build and pass tests successfully?