### Set Up App Navigation with Nav3Host (Simple Setup)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

This Composable function demonstrates a simple setup for Nav3 Router within a Jetpack Compose application. It automatically creates the router and uses `Nav3Host` to manage the navigation back stack and display different screens based on the `Screen` definition.

```kotlin
import androidx.compose.runtime.Composable
import androidx.navigation3.compose.Nav3Host
import androidx.navigation3.compose.NavDisplay
import androidx.navigation3.compose.entry
import androidx.navigation3.compose.entryProvider
import androidx.navigation3.compose.rememberNavBackStack

@Composable
fun App() {
    val backStack = rememberNavBackStack(Screen.Home)
    
    Nav3Host(
        backStack = backStack
    ) { backStack, onBack, router ->  // router provided by Nav3Host
        NavDisplay(
            backStack = backStack,
            onBack = onBack,
            entryProvider = entryProvider {
                entry<Screen.Home> {
                    HomeScreen(
                        onNavigateToDetails = { itemId ->
                            router.push(Screen.Details(itemId))
                        }
                    )
                }
                
                entry<Screen.Details> { screen ->
                    DetailsScreen(
                        itemId = screen.itemId,
                        onBack = { router.pop() }
                    )
                }
                
                entry<Screen.Settings> {
                    SettingsScreen()
                }
            }
        )
    }
}
```

--------------------------------

### Integrate Nav3 Router with ViewModels using DI

Source: https://context7.com/arttttt/nav3router/llms.txt

Shows how to inject Nav3 Router into ViewModels for decoupled and testable navigation logic. This example uses Koin for dependency injection and defines screen navigation keys. The App composable demonstrates setting up the Nav3Host with a DI-provided router.

```kotlin
// Screen definitions
@Serializable
sealed interface Screen : NavKey {
    @Serializable data object Home : Screen
    @Serializable data class Details(val id: String) : Screen
    @Serializable data object Settings : Screen
}

// ViewModel with injected router
class HomeViewModel(
    private val router: Router<Screen>,
    private val repository: ItemRepository
) : ViewModel() {

    val items = repository.getItems().stateIn(viewModelScope, SharingStarted.Lazily, emptyList())

    fun onItemClick(itemId: String) {
        router.push(Screen.Details(itemId))
    }

    fun onSettingsClick() {
        router.push(Screen.Settings)
    }
}

// Koin DI setup
val navigationModule = module {
    single { Router<Screen>() }
}

val viewModelModule = module {
    viewModel { HomeViewModel(get(), get()) }
}

// App with DI-provided router
@Composable
fun App() {
    val router: Router<Screen> = koinInject()
    val backStack = rememberNavBackStack(Screen.Home)

    Nav3Host(
        backStack = backStack,
        router = router,  // DI-provided router
    ) {
        backStack, onBack, _ ->
        NavDisplay(
            backStack = backStack,
            onBack = onBack,
            entryProvider = entryProvider {
                entry<Screen.Home> {
                    val viewModel: HomeViewModel = koinViewModel()
                    HomeScreen(viewModel)
                }
                entry<Screen.Details> { screen ->
                    DetailsScreen(screen.id)
                }
                entry<Screen.Settings> {
                    SettingsScreen()
                }
            }
        )
    }
}
```

--------------------------------

### ViewModel Navigation with Nav3 Router

Source: https://github.com/arttttt/nav3router/blob/master/README.md

This example shows how to inject and use the `Router` within a ViewModel to trigger navigation events. It demonstrates methods for navigating to a details screen with an argument and to a settings screen.

```kotlin
import androidx.lifecycle.ViewModel
import io.github.arttttt.nav3router.core.Router

// Assuming Screen is defined as in the previous example

// In your ViewModel
class HomeViewModel(
    private val router: Router<Screen>
) : ViewModel() {
    
    fun openDetails(itemId: String) {
        router.push(Screen.Details(itemId))
    }
    
    fun openSettings() {
        router.push(Screen.Settings)
    }
}
```

--------------------------------

### Custom Navigator Implementation in Kotlin

Source: https://context7.com/arttttt/nav3router/llms.txt

Extends Nav3Navigator to add custom command types or modify navigation behavior. This example introduces a 'SwapScreens' command to replace the last two screens in the snapshot with a new one. It requires the androidx.navigation3.runtime and com.arttttt.nav3router libraries.

```kotlin
import androidx.navigation3.runtime.NavBackStack
import androidx.navigation3.runtime.NavKey
import com.arttttt.nav3router.Command
import com.arttttt.nav3router.Nav3Navigator
import com.arttttt.nav3router.Push

// Custom command
data class SwapScreens<T : Any>(val screen: T) : Command<T>

// Custom navigator with extended behavior
class CustomNavigator(
    navBackStack: NavBackStack<NavKey>,
    onBack: () -> Unit,
) : Nav3Navigator(navBackStack, onBack) {

    override fun applyCommand(
        snapshot: MutableList<NavKey>,
        command: Command<NavKey>,
        onBackRequested: () -> Unit,
    ) {
        when (command) {
            is SwapScreens<NavKey> -> {
                // Custom: remove last two screens and add new one
                if (snapshot.size >= 2) {
                    snapshot.removeAt(snapshot.lastIndex)
                    snapshot.removeAt(snapshot.lastIndex)
                }
                snapshot.add(command.screen)
            }
            else -> super.applyCommand(snapshot, command, onBackRequested)
        }
    }
}

// Usage with custom navigator
@Composable
fun AppWithCustomNavigator() {
    val router = rememberRouter<Screen>()
    val backStack = rememberNavBackStack(Screen.Home)

    val customNavigator = remember(backStack) {
        CustomNavigator(
            navBackStack = backStack,
            onBack = { /* handle system back */ }
        )
    }

    Nav3Host(
        backStack = backStack,
        router = router,
        navigator = customNavigator,
    ) { backStack, onBack, router ->
        // Navigation content
    }
}
```

--------------------------------

### Setup Nav3Host Composable for Navigation

Source: https://context7.com/arttttt/nav3router/llms.txt

Integrate Nav3 Router with Jetpack Compose using the Nav3Host composable. It connects the router to the navigator and manages lifecycle for proper navigation handling.

```kotlin
import androidx.compose.runtime.Composable
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay
import com.arttttt.nav3router.Nav3Host
import com.arttttt.nav3router.rememberRouter

@Composable
fun App() {
    val router = rememberRouter<Screen>()
    val backStack = rememberNavBackStack(Screen.Home)

    Nav3Host(
        backStack = backStack,
        router = router,
    ) { backStack, onBack, router ->
        NavDisplay(
            backStack = backStack,
            onBack = onBack,
            entryProvider = entryProvider {
                entry<Screen.Home> {
                    HomeScreen(
                        onNavigateToDetails = { itemId ->
                            router.push(Screen.Details(itemId))
                        },
                        onNavigateToSettings = {
                            router.push(Screen.Settings)
                        }
                    )
                }

                entry<Screen.Details> { screen ->
                    DetailsScreen(
                        itemId = screen.itemId,
                        onBack = { router.pop() }
                    )
                }

                entry<Screen.Settings> {
                    SettingsScreen(
                        onBack = { router.pop() }
                    )
                }
            }
        )
    }
}
```

--------------------------------

### Router API: Clear Stack (Kotlin)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

Shows how to remove all screens except the root screen using the `clearStack` method. This is typically used for a 'Home' button action to return the user to the application's starting point.

```kotlin
router.clearStack()
```

--------------------------------

### Install Nav3 Router Dependency

Source: https://context7.com/arttttt/nav3router/llms.txt

Add the Nav3 Router library to your Kotlin Multiplatform shared module or Android-only project. This dependency enables the navigation functionalities across different platforms.

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.arttttt.nav3router:nav3router:1.0.3")
        }
    }
}

dependencies {
    implementation("io.github.arttttt.nav3router:nav3router:1.0.3")
}
```

--------------------------------

### Define Navigation Screens with Serializable Interface

Source: https://github.com/arttttt/nav3router/blob/master/README.md

This Kotlin code defines a sealed interface `Screen` that implements `NavKey` for type-safe navigation. It includes examples of different screen types: a simple `Home` screen, a `Details` screen with a parameter, and a `Settings` screen.

```kotlin
import androidx.navigation3.runtime.NavKey
import kotlinx.serialization.Serializable

@Serializable
sealed interface Screen : NavKey {
    @Serializable
    data object Home : Screen
    
    @Serializable
    data class Details(val itemId: String) : Screen
    
    @Serializable
    data object Settings : Screen
}
```

--------------------------------

### Set Up App Navigation with Nav3Host (DI Integration)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

This Composable function illustrates integrating Nav3 Router with a dependency injection framework (like Koin) in a Jetpack Compose app. It shows how to retrieve the `Router` instance from the DI container and pass it to `Nav3Host` for managing navigation.

```kotlin
import androidx.compose.runtime.Composable
import androidx.navigation3.compose.Nav3Host
import androidx.navigation3.compose.NavDisplay
import androidx.navigation3.compose.entry
import androidx.navigation3.compose.entryProvider
import androidx.navigation3.compose.rememberNavBackStack
import io.github.arttttt.nav3router.core.Router
import org.koin.compose.koinInject

@Composable
fun App() {
    // Get router from your DI container (Koin, Hilt, etc.)
    val router: Router<Screen> = koinInject()
    val backStack = rememberNavBackStack(Screen.Home)
    
    Nav3Host(
        backStack = backStack,
        router = router  // Pass your DI-provided router
    ) { backStack, onBack, _ ->
        NavDisplay(
            backStack = backStack,
            onBack = onBack,
            entryProvider = /* ... */
        )
    }
}
```

--------------------------------

### Router API: Push Screens (Kotlin)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

Demonstrates how to push single or multiple screens onto the navigation stack using the `push` method. This is used for navigating to new views.

```kotlin
router.push(Screen.Details("item-123"))

router.push(
    Screen.Details("item-1"),
    Screen.Details("item-2"),
    Screen.Settings
)
```

--------------------------------

### Implement Nested Navigation with Nav3 Router

Source: https://context7.com/arttttt/nav3router/llms.txt

Demonstrates how to create nested navigation containers using Nav3 Router. Child navigators can have their own independent back stacks, and back presses from child containers will propagate to parent containers when the child stack is empty. This requires importing necessary Nav3 Router and UI components.

```kotlin
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay
import com.arttttt.nav3router.Nav3Host
import com.arttttt.nav3router.rememberRouter

@Composable
fun NestedNavigationScreen() {
    // Nested router - independent from parent
    val nestedRouter = rememberRouter<Screen>()
    val nestedBackStack = rememberNavBackStack(Screen.Home)

    Column(modifier = Modifier.fillMaxSize()) {
        Text("Nested Navigation Container")

        // Nested Nav3Host - back presses propagate to parent when empty
        Nav3Host(
            backStack = nestedBackStack,
            router = nestedRouter,
        ) { backStack, onBack, router ->
            NavDisplay(
                modifier = Modifier.weight(1f),
                backStack = backStack,
                onBack = onBack,
                entryProvider = entryProvider {
                    entry<Screen.Home> {
                        Button(onClick = { router.push(Screen.Details("nested-item")) }) {
                            Text("Open Nested Details")
                        }
                    }

                    entry<Screen.Details> { screen ->
                        Column {
                            Text("Nested Details: ${screen.itemId}")
                            Button(onClick = { router.pop() }) {
                                Text("Back")
                            }
                        }
                    }
                }
            )
        }

        // Control buttons
        Row {
            Button(onClick = { nestedRouter.push(Screen.Settings) }) {
                Text("Push")
            }
            Button(onClick = { nestedRouter.pop() }) {
                Text("Pop")
            }
            Button(onClick = { nestedRouter.clearStack() }) {
                Text("Clear")
            }
        }
    }
}
```

--------------------------------

### Push Screens onto Navigation Stack

Source: https://context7.com/arttttt/nav3router/llms.txt

Use the `router.push()` function to navigate to new screens. It supports pushing single screens or a chain of screens for complex navigation flows. This can be used directly or from ViewModels.

```kotlin
// Push a single screen
router.push(Screen.Details("item-123"))

// Push multiple screens at once (creates navigation chain)
router.push(
    Screen.Home,
    Screen.Details("item-1"),
    Screen.Profile(userId = 42)
)

// Push from ViewModel with dependency injection
class HomeViewModel(
    private val router: Router<Screen>
) : ViewModel() {

    fun openProductDetails(productId: String) {
        router.push(Screen.Details(productId))
    }

    fun openDeepLink(userId: Int, itemId: String) {
        // Build deep navigation stack
        router.push(
            Screen.Profile(userId),
            Screen.Details(itemId)
        )
    }
}
```

--------------------------------

### Define Type-Safe Navigation Screens

Source: https://context7.com/arttttt/nav3router/llms.txt

Create sealed interfaces implementing NavKey for type-safe screen definitions using Kotlin serialization. This allows for robust handling of navigation arguments and states.

```kotlin
import androidx.navigation3.runtime.NavKey
import kotlinx.serialization.Serializable

@Serializable
sealed interface Screen : NavKey {

    @Serializable
    data object Home : Screen

    @Serializable
    data class Details(val itemId: String) : Screen

    @Serializable
    data object Settings : Screen

    @Serializable
    data class Profile(val userId: Int) : Screen

    @Serializable
    data object BottomSheet : Screen

    @Serializable
    data object Dialog : Screen
}
```

--------------------------------

### Router API: Pop to Specific Screen (Kotlin)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

Demonstrates navigating back to a specific screen and removing all screens above it using the `popTo` method. This is useful for returning to a known state in the navigation history.

```kotlin
router.popTo(Screen.Home)
```

--------------------------------

### Navigate Back to Specific Screen with Router.popTo()

Source: https://context7.com/arttttt/nav3router/llms.txt

Navigates backward in the navigation stack to a specified screen, removing all screens that were pushed after the target screen. If the target screen is not found in the stack, all screens except the root screen are removed.

```kotlin
// Navigate back to home, removing all intermediate screens
router.popTo(Screen.Home)

// Deep navigation example
class NavigationHelper(
    private val router: Router<Screen>
) {

    fun navigateToHome() {
        // Pop all screens until Home is reached
        router.popTo(Screen.Home)
    }

    fun navigateToProfile(userId: Int) {
        // Pop to specific profile screen
        router.popTo(Screen.Profile(userId))
    }
}
```

--------------------------------

### rememberRouter()

Source: https://context7.com/arttttt/nav3router/llms.txt

Creates and remembers a Router instance within a Composable context. The router will be recreated if any of the provided keys change, allowing for router configurations that are dependent on state. It can also accept a custom factory lambda to create the router.

```APIDOC
## rememberRouter()

### Description
Creates and remembers a Router instance in a Composable context. The router will be recreated if any of the provided keys change, allowing for state-dependent router configurations.

### Method
`rememberRouter<T : Screen>(vararg keys: Any, factory: () -> Router<T> = { Router() })`

### Parameters
- **keys** (Any) - Optional - A list of keys that, if changed, will cause the router to be recreated.
- **factory** (() -> Router<T>) - Optional - A lambda function that provides a custom Router instance. Defaults to a standard `Router()`.

### Request Example
```kotlin
import com.arttttt.nav3router.rememberRouter

@Composable
fun App() {
    // Basic usage - router persists across recompositions
    val router = rememberRouter<Screen>()

    // With custom factory
    val customRouter = rememberRouter<Screen> {
        MyCustomRouter()
    }

    // Recreate router when user changes
    val userId by remember { mutableStateOf<String?>(null) }
    val userScopedRouter = rememberRouter<Screen>(userId) {
        Router()
    }

    // Use in Nav3Host
    Nav3Host(
        backStack = rememberNavBackStack(Screen.Home),
        router = router,
    ) { backStack, onBack, router ->
        // Navigation content
    }
}
```

### Response
- **router** (Router<T>) - The remembered Router instance.
```

--------------------------------

### Router API: Drop Stack (Kotlin)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

Demonstrates making the current screen the only one in the stack and then triggering a system back action using the `dropStack` method. This effectively exits the current flow or view.

```kotlin
router.dropStack()
```

--------------------------------

### Router API: Pop Screen (Kotlin)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

Shows how to remove the top screen from the navigation stack using the `pop` method. If it's the last screen, it triggers the system back behavior.

```kotlin
router.pop()
```

--------------------------------

### Router API: Replace Current Screen (Kotlin)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

Illustrates replacing the currently displayed screen with a new one using the `replaceCurrent` method. This is useful for updating the current view without affecting the rest of the stack.

```kotlin
router.replaceCurrent(Screen.Home)
```

--------------------------------

### Router Navigation API

Source: https://github.com/arttttt/nav3router/blob/master/README.md

This section details the various methods available in the Router API for managing screen navigation.

```APIDOC
## Router API

### Description

Provides methods to manipulate the navigation stack of the application.

### Methods

#### `push(vararg screens)`

*   **Description**: Pushes one or more screens onto the navigation stack.
*   **Method**: POST (Conceptual - actual implementation might vary)
*   **Endpoint**: `/router/push` (Conceptual)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: `screens` (Array of Screen objects) - Required - The screens to push onto the stack.

#### `pop()`

*   **Description**: Removes the top screen from the navigation stack. If it's the last screen, it triggers the system back action.
*   **Method**: DELETE (Conceptual)
*   **Endpoint**: `/router/pop` (Conceptual)
*   **Parameters**: None

#### `replaceCurrent(screen)`

*   **Description**: Replaces the current top screen on the navigation stack with a new screen.
*   **Method**: PUT (Conceptual)
*   **Endpoint**: `/router/replaceCurrent` (Conceptual)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: `screen` (Screen object) - Required - The new screen to replace the current one.

#### `replaceStack(vararg screens)`

*   **Description**: Replaces the entire navigation stack with a new set of screens.
*   **Method**: PUT (Conceptual)
*   **Endpoint**: `/router/replaceStack` (Conceptual)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: `screens` (Array of Screen objects) - Required - The new screens to form the navigation stack.

#### `popTo(screen)`

*   **Description**: Navigates back to a specific screen, removing all screens that were pushed after it.
*   **Method**: DELETE (Conceptual)
*   **Endpoint**: `/router/popTo` (Conceptual)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: `screen` (Screen object) - Required - The target screen to navigate back to.

#### `clearStack()`

*   **Description**: Removes all screens from the navigation stack except for the root screen.
*   **Method**: DELETE (Conceptual)
*   **Endpoint**: `/router/clearStack` (Conceptual)
*   **Parameters**: None

#### `dropStack()`

*   **Description**: Keeps only the current screen on the stack and then triggers the system back action.
*   **Method**: DELETE (Conceptual)
*   **Endpoint**: `/router/dropStack` (Conceptual)
*   **Parameters**: None

### Usage Examples (Kotlin)

```kotlin
// Push single screen
router.push(Screen.Details("item-123"))

// Push multiple screens at once
router.push(
    Screen.Details("item-1"),
    Screen.Details("item-2"),
    Screen.Settings
)

// Replace current screen
router.replaceCurrent(Screen.Home)

// Navigate back
router.pop()

// Navigate back to specific screen
router.popTo(Screen.Home)

// Replace entire stack (useful for login/logout flows)
router.replaceStack(Screen.Login)

// Clear to root (useful for "Home" button)
router.clearStack()

// Make current screen the only one and exit
router.dropStack()
```
```

--------------------------------

### Router API: Replace Stack (Kotlin)

Source: https://github.com/arttttt/nav3router/blob/master/README.md

Illustrates replacing the entire navigation stack with a new set of screens using the `replaceStack` method. This is commonly used for login and logout flows to reset the navigation context.

```kotlin
router.replaceStack(Screen.Login)
```

--------------------------------

### Remember Router Instance with rememberRouter()

Source: https://context7.com/arttttt/nav3router/llms.txt

Creates and remembers a Router instance within a Jetpack Compose Composable function. The router will be recreated if any of the provided keys change, enabling state-dependent router configurations. This function is essential for managing navigation state in Compose applications.

```kotlin
import com.arttttt.nav3router.rememberRouter

@Composable
fun App() {
    // Basic usage - router persists across recompositions
    val router = rememberRouter<Screen>()

    // With custom factory
    val customRouter = rememberRouter<Screen> {
        MyCustomRouter()
    }

    // Recreate router when user changes
    val userId by remember { mutableStateOf<String?>(null) }
    val userScopedRouter = rememberRouter<Screen>(userId) {
        Router()
    }

    // Use in Nav3Host
    Nav3Host(
        backStack = rememberNavBackStack(Screen.Home),
        router = router,
    ) { backStack, onBack, router ->
        // Navigation content
    }
}
```

--------------------------------

### Router.popTo()

Source: https://context7.com/arttttt/nav3router/llms.txt

Navigates back to a specific screen within the navigation stack, removing all screens that were pushed after it. If the specified target screen is not found in the stack, all screens except the root screen will be removed.

```APIDOC
## Router.popTo()

### Description
Navigates back to a specific screen in the stack, removing all screens above it. If the target screen is not found, all screens except the root are removed.

### Method
`popTo`

### Parameters
- **screen** (Screen) - Required - The target screen to navigate back to.

### Request Example
```kotlin
// Navigate back to home, removing all intermediate screens
router.popTo(Screen.Home)
```

### Response
This method does not return a value.
```

--------------------------------

### Replace Current Screen with Router.replaceCurrent()

Source: https://context7.com/arttttt/nav3router/llms.txt

Replaces the current top screen with a new screen without adding it to the navigation stack. This is useful for flows where the user should not be able to navigate back to the previous screen, such as completing a login or onboarding process.

```kotlin
// Replace current screen (user cannot navigate back to login)
router.replaceCurrent(Screen.Home)

// Login flow example
class AuthViewModel(
    private val router: Router<Screen>,
    private val authRepository: AuthRepository
) : ViewModel() {

    fun onLoginSuccess() {
        // Replace login screen with home - back won't return to login
        router.replaceCurrent(Screen.Home)
    }

    fun onOnboardingComplete() {
        // Replace onboarding with main app
        router.replaceCurrent(Screen.Home)
    }
}
```

--------------------------------

### Add Nav3 Router Dependency to KMP Project

Source: https://github.com/arttttt/nav3router/blob/master/README.md

This snippet shows how to add the Nav3 Router library as a dependency to the commonMain source set of a Kotlin Multiplatform project using Gradle Kotlin DSL.

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.arttttt.nav3router:nav3router:1.0.0") // Check latest version
        }
    }
}
```

--------------------------------

### Router.replaceStack()

Source: https://context7.com/arttttt/nav3router/llms.txt

Replaces the entire navigation stack with a new set of screens. This operation resets the navigation to the root, replaces the root screen with the first provided screen, and then pushes any additional screens. It's ideal for significant navigation flow changes, such as when an authentication state changes.

```APIDOC
## Router.replaceStack()

### Description
Replaces the entire navigation stack with new screens. This operation resets to root, replaces the root screen with the first provided screen, then pushes additional screens. Useful for major navigation flow changes like authentication state changes.

### Method
`replaceStack`

### Parameters
- **screens** (Array<Screen>) - Required - The new screens to form the navigation stack.

### Request Example
```kotlin
// Replace entire stack with single screen
router.replaceStack(Screen.Home)

// Replace stack with multiple screens
router.replaceStack(
    Screen.Home,
    Screen.Settings
)
```

### Response
This method does not return a value.
```

--------------------------------

### Replace Navigation Stack with Router.replaceStack()

Source: https://context7.com/arttttt/nav3router/llms.txt

Replaces the entire navigation stack with new screens. This operation effectively resets the navigation to the root, then replaces the root screen with the first provided screen and pushes any subsequent screens. It's ideal for significant navigation flow changes, like when an authentication state changes.

```kotlin
// Replace entire stack with single screen
router.replaceStack(Screen.Home)

// Replace stack with multiple screens
router.replaceStack(
    Screen.Home,
    Screen.Settings
)

// Auth state change example
class SessionManager(
    private val router: Router<Screen>
) {

    fun onLogout() {
        // Clear entire stack, show login
        router.replaceStack(Screen.Login)
    }

    fun onSessionRestored(userId: Int) {
        // Set up authenticated navigation stack
        router.replaceStack(
            Screen.Home,
            Screen.Profile(userId)
        )
    }
}
```

--------------------------------

### Router.clearStack()

Source: https://context7.com/arttttt/nav3router/llms.txt

Clears all screens from the navigation stack except for the root screen. This effectively resets the navigation stack to its initial state, which is commonly used for 'back to home' functionality or to clear out complex navigation flows.

```APIDOC
## Router.clearStack()

### Description
Clears all screens except the root screen, resetting the navigation stack to its initial state. Useful for 'back to home' functionality or clearing complex navigation flows.

### Method
`clearStack`

### Parameters
None

### Request Example
```kotlin
// Clear to root screen
router.clearStack()
```

### Response
This method does not return a value.
```

--------------------------------

### Router.replaceCurrent()

Source: https://context7.com/arttttt/nav3router/llms.txt

Replaces the current top screen with a new screen without adding it to the navigation stack. This is useful for flows where the user should not be able to navigate back to the previous screen, such as after login or completing onboarding.

```APIDOC
## Router.replaceCurrent()

### Description
Replaces the current top screen with a new screen without adding to the stack. Useful for login flow completion, error recovery, or screen transitions where back navigation should skip the replaced screen.

### Method
`replaceCurrent`

### Parameters
- **screen** (Screen) - Required - The new screen to replace the current one with.

### Request Example
```kotlin
// Replace current screen (user cannot navigate back to login)
router.replaceCurrent(Screen.Home)
```

### Response
This method does not return a value.
```

--------------------------------

### Router.dropStack()

Source: https://context7.com/arttttt/nav3router/llms.txt

Removes all screens from the navigation stack except for the current top screen, making that screen the new root. It then triggers the system's back navigation. This is useful when you want to close a nested navigation graph or exit the application from the current screen.

```APIDOC
## Router.dropStack()

### Description
Removes all screens except the current top screen, making it the new root, then triggers system back navigation. Use when you want to close a nested navigation graph or exit the application from the current screen.

### Method
`dropStack`

### Parameters
None

### Request Example
```kotlin
// Make current screen root and trigger back
router.dropStack()
```

### Response
This method does not return a value.
```

--------------------------------

### Add Nav3 Router Dependency to Android Project

Source: https://github.com/arttttt/nav3router/blob/master/README.md

This snippet demonstrates how to include the Nav3 Router library as a dependency in an Android-only project using Gradle Kotlin DSL.

```kotlin
dependencies {
    implementation("io.github.arttttt.nav3router:nav3router:1.0.0")
}
```

--------------------------------

### Drop Navigation Stack with Router.dropStack()

Source: https://context7.com/arttttt/nav3router/llms.txt

Removes all screens from the navigation stack except for the current top screen, which then becomes the new root. This action also triggers the system's back navigation. It's useful for closing nested navigation graphs or exiting the application from the current screen.

```kotlin
// Make current screen root and trigger back
router.dropStack()

// Exit flow example
class CheckoutViewModel(
    private val router: Router<Screen>
) : ViewModel() {

    fun onPurchaseComplete() {
        // Keep confirmation screen as root and exit
        router.dropStack()
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.