---
name: setup-navigation
description: Set up Compose Multiplatform Navigation 3 in the KMP project. Use when the user wants to add navigation, routing, or screen transitions.
allowed-tools: Bash, Read, Edit, Write, Grep, Glob
user-invocable: true
---

Set up Navigation 3 for the DocuBox Compose Multiplatform project.

This project uses Compose Multiplatform 1.10.0 which supports Navigation 3.

## Steps

1. Read `gradle/libs.versions.toml` and add the navigation dependencies:

   Under `[versions]`:
   ```
   navigation3-ui = "1.0.0-alpha05"
   lifecycle-viewmodel-navigation3 = "2.10.0-alpha05"
   ```

   Under `[libraries]`:
   ```
   navigation3-ui = { module = "org.jetbrains.androidx.navigation3:navigation3-ui", version.ref = "navigation3-ui" }
   lifecycle-viewmodel-navigation3 = { module = "org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-navigation3", version.ref = "lifecycle-viewmodel-navigation3" }
   ```

   **Important**: Before adding, search the web for the latest stable version of these libraries. Use latest stable — no alpha/beta unless no stable exists yet (Navigation 3 is currently alpha-only, so alpha is acceptable here).

2. Read `composeApp/build.gradle.kts` and add to `commonMain.dependencies`:
   ```kotlin
   implementation(libs.navigation3.ui)
   implementation(libs.lifecycle.viewmodel.navigation3)
   ```

   Also ensure `kotlinx-serialization` plugin is applied (needed for type-safe routes):
   - Add serialization plugin in `[plugins]` of version catalog if missing
   - Apply it in `composeApp/build.gradle.kts`
   - Add `kotlinx-serialization-core` to commonMain dependencies

3. Create the navigation setup at `composeApp/src/commonMain/kotlin/io/ak1/docubox/navigation/`:

   **NavRoutes.kt** — Define routes as serializable data objects/classes:
   ```kotlin
   @Serializable
   data object HomeRoute : NavKey

   @Serializable
   data class DetailRoute(val id: String) : NavKey
   ```

   **NavConfig.kt** — SavedStateConfiguration with polymorphic serialization (required for iOS/non-JVM):
   ```kotlin
   val navConfig = SavedStateConfiguration {
       serializersModule = SerializersModule {
           polymorphic(NavKey::class) {
               subclass(HomeRoute::class)
               subclass(DetailRoute::class)
           }
       }
   }
   ```

   **AppNavigation.kt** — Main navigation composable using `rememberNavBackStack` and `NavDisplay`

4. Update `App.kt` to use the new navigation composable as root.

5. Verify the build compiles on both platforms:
   ```
   ./gradlew :composeApp:assembleDebug
   ./gradlew :composeApp:iosSimulatorArm64MainKotlinNativeCompile
   ```

## Key rules
- All route classes must implement `NavKey` and be `@Serializable`
- Register every route in the `SavedStateConfiguration` polymorphic block (required for iOS)
- Use `rememberNavBackStack` for back stack management — manipulate it directly to navigate
- Do not use the old `navigation-compose` (org.jetbrains.androidx.navigation:navigation-compose) — Navigation 3 is the current approach for Compose Multiplatform 1.10.0+