feat(navigation): keep tabs alive across a tab switch

A tab press cleared the whole backstack, so every tab was rebuilt from nothing on
every press. Nav3 gives each entry its own ViewModelStore and saveable state, and
both die with the entry, so returning to the wallet meant a cold ViewModel behind
its loading spinner — which is what made the scanner-to-wallet switch after a
claim read as a reload rather than a tab change.

Tab homes now stay on the stack and the target moves to the top. Its entry is the
one already there, so the tab comes back with its ViewModels, rememberSaveable
state and list scroll position intact. Everything that is not a tab home is still
dropped: the screens pushed on the outgoing tab and any sheet over them, which
clearing always discarded and which would otherwise sit under the tab being
opened.

Back walks the visited tabs before it leaves the app, rather than leaving from
whichever tab is showing. That is the cost of the retention — an entry has to be
on the stack to survive — and it is not avoidable by refusing to pop: NavDisplay
enables predictive back on stack depth alone, so a swallowed pop would show a
seek preview and snap back.

Two readers assumed the old shape. The nav bar's selection walked the stack from
the bottom, which is now the tab visited first rather than the tab showing, and
the scanner ran its camera only when it was the only entry on the stack, which
never held again. Both now ask what is on top. MainRoot compares its launch graph
from the active tab up, so the retained tabs beneath it don't read as a mismatch
and reset the user to the launch route.

Deeplinks are unaffected — they still arrive through navigateAll, which clears. A
link is an entry point into the app rather than a move between tabs.

Author: bmc08gt

apps/flipcash/app/src/main/kotlin/com/flipcash/app/internal/ui/AppNavigationBar.kt

@@ -24,7 +24,7 @@ import com.flipcash.app.core.LocalUserManager
 import dev.chrisbanes.haze.HazeState
 import com.flipcash.app.core.navigation.NavBarButton
 import com.flipcash.app.core.navigation.asNavBarTab
-import com.flipcash.app.core.navigation.destinationRoute
+import com.flipcash.app.core.navigation.switchTab
 import com.flipcash.app.core.ui.NavigationBar
 import com.flipcash.app.core.ui.rememberNavigationBarState
 import com.flipcash.app.session.LocalSessionController
@@ -39,8 +39,9 @@ import kotlinx.coroutines.flow.map
 
 /**
  * The hoisted navigation bar — root chrome, not owned by any screen. It renders over whichever
- * top-level route is a tab home and switches tabs by **swapping the current screen** (single
- * backstack, like a tab bar — hence [CodeNavigator.replaceAll], not a sheet).
+ * top-level route is a tab home and switches tabs by moving the target's home to the top of the
+ * backstack (see [switchTab]), keeping the tabs already visited alive rather than rebuilding each
+ * one on every press.
  *
  * Only visible when the current route maps to a tab.
  *
@@ -60,9 +61,12 @@ internal fun AppNavigationBar(
     // the expansion doesn't recompose the bar.
     cardExpansion: CardExpansionController? = null,
 ) {
-    // Selection follows the base of the backstack (the tab "home"), so it stays correct while a
-    // sheet/modal sits on top and is right on launch. The top route only gates visibility.
-    val selectedTab = navigator.backStack.firstNotNullOfOrNull { (it as? AppRoute)?.asNavBarTab() }
+    // Selection follows the topmost tab home, so it stays correct while a sheet/modal or a pushed
+    // detail sits over it and is right on launch. Read from the top down rather than the bottom up
+    // because the tabs below the active one are the retained ones (see [switchTab]) — the base of
+    // the stack is the tab visited first, not the tab showing. The top route only gates visibility.
+    val selectedTab = navigator.backStack.asReversed()
+        .firstNotNullOfOrNull { (it as? AppRoute)?.asNavBarTab() }
     val topTab = (navigator.currentRouteKey as? AppRoute)?.asNavBarTab()
 
     // A BottomBar modal (e.g. Add Money) renders in the nav content, above this bar; hide the bar so
@@ -126,10 +130,7 @@ internal fun AppNavigationBar(
                         .padding(horizontal = CodeTheme.dimens.grid.x8)
                         .padding(bottom = CodeTheme.dimens.grid.x3),
                     state = state,
-                    onButtonClick = { button ->
-                        // Tab bar semantics: swap the current screen (single backstack).
-                        navigator.replaceAll(button.destinationRoute())
-                    },
+                    onButtonClick = { button -> navigator.switchTab(button) },
                     hazeState = hazeState,
                     avatar = avatar,
                 )

apps/flipcash/app/src/main/kotlin/com/flipcash/app/internal/ui/navigation/MainRoot.kt

@@ -27,6 +27,7 @@ import com.flipcash.app.core.AppRoute
 import com.flipcash.app.core.DisplayNameSource
 import com.flipcash.app.core.userprofile.UpdateProfileStep
 import com.flipcash.app.core.navigation.DeeplinkAction
+import com.flipcash.app.core.navigation.asNavBarTab
 import com.flipcash.app.core.navigation.homeRoute
 import com.flipcash.app.core.extensions.navigateAll
 import com.flipcash.app.core.extensions.resolveBackStack
@@ -123,7 +124,7 @@ internal fun MainRoot(
                 }
 
                 if (launch != null) {
-                    val current = navigator.backStack.toList()
+                    val current = navigator.backStack.toList().fromActiveTab()
                     val target = launch.resolvedBackStack()
 
                     // Skip if the current stack already matches or extends the target.
@@ -169,6 +170,19 @@ internal data class LaunchNavGraph(
         resolveBackStack(baseRoutes, deeplinkRoutes)
 }
 
+/**
+ * The backstack from the active tab up, dropping the tab homes retained beneath it.
+ *
+ * A tab switch keeps the tabs already visited on the stack (see `switchTab`), so the base of the
+ * stack is the tab visited first, not the one showing. The launch graph only ever describes the
+ * active tab and what sits over it, so comparing against the whole stack would read the retained
+ * tabs as a mismatch and reset the user to the launch route on any auth/flags re-emission.
+ */
+private fun List<NavKey>.fromActiveTab(): List<NavKey> {
+    val active = indexOfLast { (it as? AppRoute)?.asNavBarTab() != null }
+    return if (active > 0) drop(active) else this
+}
+
 /**
  * Returns true if [this] list starts with [prefix] (element-wise structural equality).
  * An exact match also returns true (prefix == full list).

apps/flipcash/core/src/main/kotlin/com/flipcash/app/core/navigation/TabSwitch.kt

@@ -0,0 +1,57 @@
+package com.flipcash.app.core.navigation
+
+import androidx.compose.runtime.snapshots.Snapshot
+import androidx.navigation3.runtime.NavKey
+import com.flipcash.app.core.AppRoute
+import com.getcode.navigation.core.CodeNavigator
+
+/**
+ * Switch to [tab]'s home, keeping the tab homes already visited.
+ *
+ * A tab press used to clear the whole backstack, so every tab was rebuilt from nothing on every
+ * press: Nav3 gives each entry its own `ViewModelStore` and saveable state, and both die with the
+ * entry. Returning to the wallet meant a cold ViewModel behind its loading spinner, which is what
+ * made the scanner-to-wallet switch after a claim read as a reload rather than a tab change.
+ *
+ * So the tab homes stay on the stack and the target moves to the top. Its entry — and with it its
+ * ViewModels, `rememberSaveable` state and list scroll position — is the one already there, so the
+ * tab comes back as the user left it.
+ *
+ * Back now walks the visited tabs before it leaves the app, rather than leaving from whichever tab
+ * is showing. That is the cost of the retention: an entry has to be on the stack to survive, and a
+ * stack the user can see is a stack they can go back through.
+ *
+ * Deeplinks are unaffected — they still arrive through `navigateAll`, which clears. A link is an
+ * entry point into the app rather than a move between tabs, and it should not inherit whatever the
+ * previous session left behind it.
+ */
+fun CodeNavigator.switchTab(tab: NavBarButton) {
+    val current = backStack.toList()
+    val next = current.afterSwitchingTo(tab)
+    if (next == current) return
+
+    Snapshot.withMutableSnapshot {
+        backStack.clear()
+        backStack.addAll(next)
+    }
+}
+
+/**
+ * The stack [switchTab] leaves behind, in the order back will walk it.
+ *
+ * Everything that is not a tab home is dropped: the screens pushed on the outgoing tab, and any
+ * sheet over them. Clearing the stack always discarded those, and carrying them across would leave
+ * another tab's detail screen sitting under the one being opened.
+ *
+ * A pure function over the keys, because that is the part worth asserting on — [switchTab] applies
+ * it to a live [androidx.navigation3.runtime.NavBackStack] inside a snapshot, so the whole swap
+ * lands in one frame and no entry is seen to leave and come back.
+ */
+fun List<NavKey>.afterSwitchingTo(tab: NavBarButton): List<NavKey> {
+    val destination = tab.destinationRoute()
+    val retained = filter { key ->
+        val home = (key as? AppRoute)?.asNavBarTab()
+        home != null && home != tab
+    }
+    return retained + destination
+}

apps/flipcash/core/src/test/kotlin/com/flipcash/app/core/navigation/TabSwitchTest.kt

@@ -0,0 +1,82 @@
+package com.flipcash.app.core.navigation
+
+import androidx.navigation3.runtime.NavKey
+import com.flipcash.app.core.AppRoute
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertSame
+
+/**
+ * A tab press used to clear the backstack, which took each tab's ViewModels and saved state with it.
+ * These assert the shape of the stack it leaves instead — the retained entries are the whole point,
+ * since an entry that stays on the stack is an entry Nav3 does not tear down.
+ */
+class TabSwitchTest {
+
+    private val scanner = AppRoute.Main.Scanner
+    private val wallet = AppRoute.Sheets.Wallet
+    private val menu = AppRoute.Sheets.Menu
+
+    @Test
+    fun `the tab already visited stays on the stack, under the one being opened`() {
+        val stack = listOf<NavKey>(wallet)
+
+        assertEquals(listOf(wallet, scanner), stack.afterSwitchingTo(NavBarButton.Scanner))
+    }
+
+    @Test
+    fun `switching back reuses the entry that is already there`() {
+        val stack = listOf<NavKey>(wallet).afterSwitchingTo(NavBarButton.Scanner)
+
+        val back = stack.afterSwitchingTo(NavBarButton.Wallet)
+
+        assertEquals(listOf(scanner, wallet), back)
+        // Same key instance, so it keeps the same contentKey and Nav3 hands the entry — its
+        // ViewModelStore, its saveable state — straight back rather than building a new one.
+        assertSame(wallet, back.last())
+    }
+
+    @Test
+    fun `a tab is never on the stack twice, however often it is pressed`() {
+        var stack = listOf<NavKey>(wallet)
+        repeat(3) {
+            stack = stack.afterSwitchingTo(NavBarButton.Scanner).afterSwitchingTo(NavBarButton.Wallet)
+        }
+
+        assertEquals(listOf(scanner, wallet), stack)
+    }
+
+    @Test
+    fun `screens pushed on the outgoing tab are dropped, not carried across`() {
+        val stack = listOf<NavKey>(wallet, AppRoute.Main.Sheet(AppRoute.Sheets.ActivityHistory))
+
+        // The wallet's home is kept — that is the entry being retained — but its open sheet is not,
+        // or it would sit underneath the scanner and be what back returned to.
+        assertEquals(listOf(wallet, scanner), stack.afterSwitchingTo(NavBarButton.Scanner))
+    }
+
+    @Test
+    fun `pressing the tab you are already on pops back to its home`() {
+        val stack = listOf<NavKey>(wallet, AppRoute.Main.Sheet(AppRoute.Sheets.ActivityHistory))
+
+        assertEquals(listOf(wallet), stack.afterSwitchingTo(NavBarButton.Wallet))
+    }
+
+    @Test
+    fun `pressing the tab you are on with nothing over it changes nothing`() {
+        val stack = listOf<NavKey>(scanner, wallet)
+
+        assertEquals(stack, stack.afterSwitchingTo(NavBarButton.Wallet))
+    }
+
+    @Test
+    fun `back walks the tabs in the order they were visited`() {
+        var stack = listOf<NavKey>(wallet)
+        stack = stack.afterSwitchingTo(NavBarButton.TipCard)
+        stack = stack.afterSwitchingTo(NavBarButton.Scanner)
+
+        // Back from the scanner returns to the You tab, then the wallet, then leaves the app —
+        // the deliberate cost of keeping the entries alive.
+        assertEquals(listOf(wallet, menu, scanner), stack)
+    }
+}

apps/flipcash/features/scanner/src/main/kotlin/com/flipcash/app/scanner/internal/Scanner.kt

@@ -157,8 +157,13 @@ internal fun Scanner() {
         }
     }
 
-    LaunchedEffect(navigator.backStack.size) {
-        previewing = navigator.backStack.size <= 1
+    // The camera runs while nothing covers the scanner. This used to ask whether the scanner was the
+    // only entry on the stack, which stopped meaning the same thing once a tab switch began keeping
+    // the tabs already visited underneath it (see `switchTab`): the scanner tab is reached with those
+    // beneath it, so the stack is never depth-1 and the preview never came up. Depth was only ever a
+    // proxy for "nothing is on top"; ask that instead.
+    LaunchedEffect(navigator.currentRouteKey) {
+        previewing = navigator.currentRouteKey == AppRoute.Main.Scanner
     }
 
     LaunchedEffect(billState.bill) {