---
phase: 02.1
plan: 04
type: execute
wave: 2
depends_on: ["02.1-01", "02.1-02"]
files_modified:
  - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt
  - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt
  - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt
  - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt
  - composeApp/src/commonMain/composeResources/values/strings.xml
  - composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt
autonomous: true
requirements: [UI-03]
tags: [kotlin, compose-multiplatform, navigation, navigation-compose, type-safe-routes, multi-back-stack]

must_haves:
  truths:
    - "Each of the 4 tabs (Planer / Przepisy / Spiżarnia / Zakupy) owns a nested NavHost with its own start destination"
    - "navigateToTab(graphRoute) applies popUpTo(graph.findStartDestination().id) { saveState = true }, launchSingleTop = true, restoreState = true (UI-03)"
    - "Default landing tab is BottomBarDestination.Planner per D-03 — corresponds to PlannerGraph as the NavHost startDestination"
    - "BottomBarDestination.hasSearch is true ONLY for Recipes and Pantry (D-06); searchPlaceholder is non-null only when hasSearch=true"
    - "strings.xml owns all shared shell/search chrome keys for this phase: 4 tab labels, 2 search placeholders, search_open_a11y, search_close_a11y, search_clear_a11y"
    - "Tab order in BottomBarDestination.entries (declaration order) matches D-03: Planner, Recipes, Pantry, Shopping"
    - "Per-tab ViewModels are scoped to the parent graph entry via koinViewModel(viewModelStoreOwner = parent) so they survive navigation into future detail screens (RESEARCH § Pattern 2)"
  artifacts:
    - path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt"
      provides: "@Serializable data object route types for 4 graphs + 4 home destinations"
      contains: "@Serializable\ndata object PlannerGraph"
    - path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt"
      provides: "enum BottomBarDestination binding routes ↔ string resources ↔ icons ↔ hasSearch ↔ searchPlaceholder"
      contains: "enum class BottomBarDestination"
    - path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt"
      provides: "RootNavHost composable with 4 navigation() sub-graphs and per-tab VM scoping placeholder"
      contains: "fun RootNavHost"
    - path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt"
      provides: "NavHostController.navigateToTab(graphRoute) extension"
      contains: "fun NavHostController.navigateToTab"
  key_links:
    - from: "navigation/RootNavHost.kt"
      to: "navigation/Routes.kt"
      via: "NavHost(startDestination = PlannerGraph) + navigation<*Graph> blocks"
      pattern: "navigation<.*Graph>"
    - from: "navigation/NavExtensions.kt"
      to: "androidx.navigation.NavHostController"
      via: "extension function applying popUpTo+saveState+launchSingleTop+restoreState"
      pattern: "popUpTo.*saveState\\s*=\\s*true"
    - from: "commonTest/.../NavigationTest.kt"
      to: "navigation/NavExtensions.kt"
      via: "captures NavOptionsBuilder lambda from navigateToTab and asserts the four flags"
      pattern: "navigateToTab"
---

<objective>
Build the navigation foundation — type-safe `@Serializable` routes for four tab graphs (PlannerGraph, RecipesGraph, PantryGraph, ShoppingGraph) plus their home destinations, a `BottomBarDestination` enum binding routes ↔ string resources ↔ icons ↔ per-tab search visibility (D-06), a `RootNavHost` composable hosting all four nested NavHosts with per-tab VM scoping wired (RESEARCH § Pattern 2), and a `navigateToTab` extension that applies the multi-back-stack incantation (`popUpTo + saveState + launchSingleTop + restoreState`). Replace the @Ignore'd Wave-0 stub in NavigationTest.kt with a real assertion that the extension's `NavOptionsBuilder` lambda flips the four flags (V-01).

Tab screen and ViewModel files are NOT created here — they are owned by plan 02.1-07 which scaffolds all four tab screens + their VMs later. RootNavHost in this plan renders minimal per-tab `Box` placeholders so Wave 2 compiles independently; plan 02.1-08 (the final wire-up) swaps those placeholders for real screens after plan 02.1-07 has landed.

Purpose: UI-03 hard-coded — tab navigation with 4 tabs, each preserving its own back stack independently. Default landing tab is Planner (D-03).
Output: 4 new commonMain files in `navigation/`, 1 commonTest file un-ignored with real assertions covering V-01.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-CONTEXT.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-UI-SPEC.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-PATTERNS.md
@.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-VALIDATION.md
@composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/App.kt
@composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt

<interfaces>
After plan 02.1-01 lands, `org.jetbrains.androidx.navigation:navigation-compose:2.9.2` is on the commonMain classpath. Public API per RESEARCH § Pattern 1 (lines 304-339) and § Code Example 1 (lines 487-510):

```kotlin
import androidx.navigation.NavHostController
import androidx.navigation.NavGraph.Companion.findStartDestination
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.navigation
import androidx.navigation.compose.rememberNavController
```

Strings to be added by plan 02.1-07 (NOT this plan — but BottomBarDestination references them, so this plan REQUIRES coordination):
- `Res.string.shell_tab_planner` ("Planer")
- `Res.string.shell_tab_recipes` ("Przepisy")
- `Res.string.shell_tab_pantry` ("Spiżarnia")
- `Res.string.shell_tab_shopping` ("Zakupy")
- `Res.string.search_placeholder_recipes` ("Szukaj przepisów…")
- `Res.string.search_placeholder_pantry` ("Szukaj w spiżarni…")

Plan 02.1-07 MUST land BEFORE 02.1-08 (which wires tab screens into RootNavHost and depends on the screen files). For this plan (02.1-04) to compile in Wave 2, all resource references used by BottomBarDestination must already be added by this plan.

Implementation order constraint: THIS plan creates BottomBarDestination which references `shell_tab_*` and `search_placeholder_*` keys, and later chrome plans reference the search a11y keys. The keys MUST exist when those plans compile. Resolution: this plan's Task 1 owns all 9 shared shell/search keys — plan 02.1-07 then extends only with empty-state keys.

This plan is Wave 2, while plans 02.1-06 and 02.1-07 are Wave 3. So this plan MUST add the shared string keys those later plans consume. Plan 02.1-07 is responsible only for the `empty_*` strings.

Existing analog (test pattern):
- composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/LoginViewModelTest.kt for kotlin.test runTest skeleton.
- For NavOptionsBuilder lambda capture: build a `NavOptionsBuilder` instance manually (or use Navigation Compose's `navOptions { ... }` builder) and apply the lambda from `navigateToTab` to it, then assert the resulting `NavOptions` properties.
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create Routes.kt + BottomBarDestination.kt + add 6 string resource keys to strings.xml</name>
  <files>
    composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt,
    composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt,
    composeApp/src/commonMain/composeResources/values/strings.xml
  </files>
  <read_first>
    - composeApp/src/commonMain/composeResources/values/strings.xml (current — append-only edits; preserve all existing auth_* keys)
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Code Example 1 (lines 487-510) — verbatim shape for Routes + BottomBarDestination
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-CONTEXT.md D-03 (line 27) — tab order: Planer / Przepisy / Spiżarnia / Zakupy; default landing Planer
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-CONTEXT.md D-06 (line 32) — search button on Przepisy + Spiżarnia only
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-UI-SPEC.md § Copywriting Contract (lines 121-158) — exact Polish copy + resource key names
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-PATTERNS.md § Navigation files lines 374-382
  </read_first>
  <action>
    Step 1 — extend `composeApp/src/commonMain/composeResources/values/strings.xml`. Open the file, locate the existing `</resources>` closing tag, and INSERT (before that tag) the following 9 shared shell/search chrome keys. PRESERVE all existing `auth_*` keys verbatim. Append-only — do not edit existing entries.

    ```xml
        <!-- Phase 2.1 — App shell navigation tab labels (UI-03, CONTEXT D-03) -->
        <string name="shell_tab_planner">Planer</string>
        <string name="shell_tab_recipes">Przepisy</string>
        <string name="shell_tab_pantry">Spiżarnia</string>
        <string name="shell_tab_shopping">Zakupy</string>

        <!-- Phase 2.1 — Search affordance placeholders (UI-10, CONTEXT D-06) -->
        <string name="search_placeholder_recipes">Szukaj przepisów…</string>
        <string name="search_placeholder_pantry">Szukaj w spiżarni…</string>

        <!-- Phase 2.1 — Search affordance a11y (UI-10, CONTEXT D-06/D-08) -->
        <string name="search_open_a11y">Otwórz wyszukiwanie</string>
        <string name="search_close_a11y">Zamknij wyszukiwanie</string>
        <string name="search_clear_a11y">Wyczyść</string>
    ```

    The empty-state copy keys (empty_planner_title, etc.) are NOT added in this plan — plan 02.1-07 owns those. Plans 02.1-05 and 02.1-06 MUST treat the search a11y keys as already provided by this plan and only verify their presence, not edit strings.xml.

    Step 2 — create `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt`:

    ```kotlin
    package dev.ulfrx.recipe.navigation

    import kotlinx.serialization.Serializable

    /**
     * Type-safe route definitions for the 4-tab app shell (CONTEXT D-03).
     * Each tab graph has a serializable route type and a home (start) destination.
     * Phase 5+ extends each graph with detail destinations (RESEARCH § Pattern 1).
     */

    // ------------------- Planer (default landing tab — D-03) -------------------
    @Serializable
    data object PlannerGraph

    @Serializable
    data object PlannerHome

    // ------------------- Przepisy ----------------------------------------------
    @Serializable
    data object RecipesGraph

    @Serializable
    data object RecipesHome

    // ------------------- Spiżarnia ---------------------------------------------
    @Serializable
    data object PantryGraph

    @Serializable
    data object PantryHome

    // ------------------- Zakupy ------------------------------------------------
    @Serializable
    data object ShoppingGraph

    @Serializable
    data object ShoppingHome
    ```

    Step 3 — create `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt`:

    ```kotlin
    package dev.ulfrx.recipe.navigation

    import androidx.compose.material.icons.Icons
    import androidx.compose.material.icons.outlined.CalendarMonth
    import androidx.compose.material.icons.outlined.Inventory2
    import androidx.compose.material.icons.outlined.MenuBook
    import androidx.compose.material.icons.outlined.ShoppingCart
    import androidx.compose.ui.graphics.vector.ImageVector
    import org.jetbrains.compose.resources.StringResource
    import recipe.composeapp.generated.resources.Res
    import recipe.composeapp.generated.resources.search_placeholder_pantry
    import recipe.composeapp.generated.resources.search_placeholder_recipes
    import recipe.composeapp.generated.resources.shell_tab_pantry
    import recipe.composeapp.generated.resources.shell_tab_planner
    import recipe.composeapp.generated.resources.shell_tab_recipes
    import recipe.composeapp.generated.resources.shell_tab_shopping

    /**
     * The 4 bottom-bar destinations in left→right order per CONTEXT D-03:
     *   Planner / Recipes / Pantry / Shopping. The first entry (Planner) is the
     *   default landing tab — CONTEXT D-03 departs from REQUIREMENTS' literal listing
     *   order, which research confirmed is non-binding.
     *
     * `hasSearch` drives D-06: search affordance lives on Recipes + Pantry only.
     * `searchPlaceholder` is non-null IFF `hasSearch` is true.
     */
    enum class BottomBarDestination(
        val graphRoute: Any,
        val labelRes: StringResource,
        val icon: ImageVector,
        val hasSearch: Boolean,
        val searchPlaceholder: StringResource?,
    ) {
        Planner(
            graphRoute = PlannerGraph,
            labelRes = Res.string.shell_tab_planner,
            icon = Icons.Outlined.CalendarMonth,
            hasSearch = false,
            searchPlaceholder = null,
        ),
        Recipes(
            graphRoute = RecipesGraph,
            labelRes = Res.string.shell_tab_recipes,
            icon = Icons.Outlined.MenuBook,
            hasSearch = true,
            searchPlaceholder = Res.string.search_placeholder_recipes,
        ),
        Pantry(
            graphRoute = PantryGraph,
            labelRes = Res.string.shell_tab_pantry,
            icon = Icons.Outlined.Inventory2,
            hasSearch = true,
            searchPlaceholder = Res.string.search_placeholder_pantry,
        ),
        Shopping(
            graphRoute = ShoppingGraph,
            labelRes = Res.string.shell_tab_shopping,
            icon = Icons.Outlined.ShoppingCart,
            hasSearch = false,
            searchPlaceholder = null,
        ),
        ;

        companion object {
            /** Default landing tab — CONTEXT D-03. */
            val Default: BottomBarDestination = Planner
        }
    }
    ```
  </action>
  <verify>
    <automated>./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q</automated>
  </verify>
  <acceptance_criteria>
    - `grep -c '@Serializable' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 8 (4 graphs + 4 home destinations)
    - `grep -c 'data object PlannerGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 1
    - `grep -c 'data object RecipesGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 1
    - `grep -c 'data object PantryGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 1
    - `grep -c 'data object ShoppingGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/Routes.kt` returns 1
    - `grep -c 'enum class BottomBarDestination' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt` returns 1
    - Tab order assertion (the FIRST entry must be Planner per D-03): `awk '/enum class BottomBarDestination/,/^}/' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt | grep -E '^\s+(Planner|Recipes|Pantry|Shopping)\(' | head -1 | grep -q 'Planner('`
    - `grep -c 'hasSearch = true' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt` returns exactly 2
    - `grep -c 'hasSearch = false' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt` returns exactly 2
    - `grep -c 'val Default: BottomBarDestination = Planner' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt` returns 1
    - All 9 new shared shell/search keys present: `grep -c 'shell_tab_planner\|shell_tab_recipes\|shell_tab_pantry\|shell_tab_shopping\|search_placeholder_recipes\|search_placeholder_pantry\|search_open_a11y\|search_close_a11y\|search_clear_a11y' composeApp/src/commonMain/composeResources/values/strings.xml` returns at least 9
    - All 7 pre-existing auth_* keys preserved: `grep -c 'auth_' composeApp/src/commonMain/composeResources/values/strings.xml` returns at least 7
    - `./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q` exits 0
  </acceptance_criteria>
  <done>
    Routes.kt declares 8 @Serializable types in the locked tab order. BottomBarDestination enum has 4 entries in D-03 order with correct hasSearch flags. strings.xml has 9 shared shell/search keys (Polish copy verbatim from UI-SPEC). iOS K/N compile is green — confirms Material Icons Outlined imports resolve (assumption A2 carried from plan 02.1-01).
  </done>
</task>

<task type="auto">
  <name>Task 2: Create RootNavHost.kt + NavExtensions.kt — multi-back-stack tab navigation</name>
  <files>
    composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt,
    composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt
  </files>
  <read_first>
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Pattern 1 (lines 304-339) — verbatim NavHost + navigation() block + navigateToTab pattern
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Pattern 2 (lines 343-360) — per-tab VM scoping with parent NavBackStackEntry
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Pitfall A (lines 441-446) — pin nav-compose 2.9.2; multi-back-stack iOS smoke test in Wave 0
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-RESEARCH.md § Pitfall B (lines 448-452) — restoreState=true required to avoid VM re-creation on tab reselection
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-PATTERNS.md § Navigation files lines 374-382
  </read_first>
  <action>
    Step 1 — create `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt`:

    ```kotlin
    package dev.ulfrx.recipe.navigation

    import androidx.navigation.NavGraph.Companion.findStartDestination
    import androidx.navigation.NavHostController

    /**
     * Multi-back-stack tab navigation per UI-03 + RESEARCH § Pattern 1 (lines 304-339).
     *
     * Applies the canonical four-flag incantation:
     *  - `popUpTo(graph.findStartDestination().id) { saveState = true }` — saves the
     *    current tab's stack so re-selecting the tab later restores it.
     *  - `launchSingleTop = true` — selecting an already-active tab does NOT push a
     *    duplicate onto the back stack.
     *  - `restoreState = true` — when the destination tab is re-selected, restore its
     *    saved state instead of recreating it. CRITICAL: without this flag, ViewModels
     *    are re-created on every reselection (RESEARCH § Pitfall B).
     *
     * @param graphRoute the @Serializable graph route (e.g. PlannerGraph, RecipesGraph)
     */
    fun NavHostController.navigateToTab(graphRoute: Any) {
        navigate(graphRoute) {
            popUpTo(graph.findStartDestination().id) {
                saveState = true
            }
            launchSingleTop = true
            restoreState = true
        }
    }
    ```

    Step 2 — create `composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt`:

    ```kotlin
    package dev.ulfrx.recipe.navigation

    import androidx.compose.foundation.layout.Box
    import androidx.compose.foundation.layout.fillMaxSize
    import androidx.compose.material.Text
    import androidx.compose.runtime.Composable
    import androidx.compose.runtime.remember
    import androidx.compose.ui.Modifier
    import androidx.navigation.NavHostController
    import androidx.navigation.compose.NavHost
    import androidx.navigation.compose.composable
    import androidx.navigation.compose.navigation

    /**
     * Root of the app shell's navigation. Hosts ONE root [NavHost] containing four
     * [navigation] sub-graphs (one per tab) so each tab preserves its own back stack
     * independently across tab switches (RESEARCH § Pattern 1, lines 304-339; UI-03).
     *
     * Default start destination: [PlannerGraph] per CONTEXT D-03.
     *
     * Per-tab ViewModel scoping: each composable<*Home> block retrieves the parent
     * graph's [androidx.navigation.NavBackStackEntry] via
     * `navController.getBackStackEntry(*Graph)` and passes it as `viewModelStoreOwner`
     * to `koinViewModel(...)`. This makes per-tab VMs survive within the graph
     * (RESEARCH § Pattern 2, lines 343-360) — Phase 5 detail screens inherit cleanly.
     *
     * Wave 2 placeholder note: this file currently renders simple Box placeholders for
     * each tab home. Plan 02.1-08 wires the real Tab*Screen composables (created by
     * plan 02.1-07) into these blocks. The wave structure is: 02.1-04 (this plan)
     * creates the routing skeleton; 02.1-07 creates tab screens + VMs later;
     * 02.1-08 (Wave 5) glues them together.
     */
    @Composable
    fun RootNavHost(
        navController: NavHostController,
        modifier: Modifier = Modifier,
    ) {
        NavHost(
            navController = navController,
            startDestination = PlannerGraph,
            modifier = modifier.fillMaxSize(),
        ) {
            // ---- Planner graph (default landing — D-03) ----
            navigation<PlannerGraph>(startDestination = PlannerHome) {
                composable<PlannerHome> { entry ->
                    val parent = remember(entry) {
                        navController.getBackStackEntry(PlannerGraph)
                    }
                    // TODO(02.1-08): replace with PlannerScreen(viewModel = koinViewModel(viewModelStoreOwner = parent))
                    TabHomePlaceholder(name = "Planner", parent = parent)
                }
                // future: composable<PlannerDetail>{ ... }
            }

            // ---- Recipes graph ----
            navigation<RecipesGraph>(startDestination = RecipesHome) {
                composable<RecipesHome> { entry ->
                    val parent = remember(entry) {
                        navController.getBackStackEntry(RecipesGraph)
                    }
                    // TODO(02.1-08): replace with RecipesScreen(viewModel = koinViewModel(viewModelStoreOwner = parent))
                    TabHomePlaceholder(name = "Recipes", parent = parent)
                }
            }

            // ---- Pantry graph ----
            navigation<PantryGraph>(startDestination = PantryHome) {
                composable<PantryHome> { entry ->
                    val parent = remember(entry) {
                        navController.getBackStackEntry(PantryGraph)
                    }
                    // TODO(02.1-08): replace with PantryScreen(viewModel = koinViewModel(viewModelStoreOwner = parent))
                    TabHomePlaceholder(name = "Pantry", parent = parent)
                }
            }

            // ---- Shopping graph ----
            navigation<ShoppingGraph>(startDestination = ShoppingHome) {
                composable<ShoppingHome> { entry ->
                    val parent = remember(entry) {
                        navController.getBackStackEntry(ShoppingGraph)
                    }
                    // TODO(02.1-08): replace with ShoppingScreen(viewModel = koinViewModel(viewModelStoreOwner = parent))
                    TabHomePlaceholder(name = "Shopping", parent = parent)
                }
            }
        }
    }

    /**
     * Wave-1 placeholder. Replaced by plan 02.1-08 with real Tab*Screen composables
     * created by plan 02.1-07. Kept private to discourage external references.
     */
    @Composable
    private fun TabHomePlaceholder(
        name: String,
        parent: androidx.navigation.NavBackStackEntry,
    ) {
        Box(modifier = Modifier.fillMaxSize()) {
            // Intentional dev-only label; replaced before any UI verification.
            Text(text = "[shell] $name placeholder — wired in 02.1-08")
        }
    }
    ```

    Note on the placeholder Text: it uses `androidx.compose.material.Text` (Material 1) ONLY because Material 3 is forbidden in new shell code (CLAUDE.md / UI-SPEC line 31). If `androidx.compose.material` is not on the commonMain classpath, swap for `androidx.compose.foundation.text.BasicText` and feed it a default style — either is acceptable for a Wave-1 placeholder that is replaced by plan 02.1-08. Whichever import resolves at compile time is fine; the placeholder is dev-only and not user-facing.

    Actually the cleanest approach: use `androidx.compose.foundation.text.BasicText` to avoid pulling in any Material variant. Replace the import + call accordingly:
    ```kotlin
    import androidx.compose.foundation.text.BasicText
    // ...
    BasicText(text = "[shell] $name placeholder — wired in 02.1-08")
    ```
    `BasicText` is in `compose-foundation` which is already on the classpath. Choose this. Update both the import and the call site in TabHomePlaceholder.
  </action>
  <verify>
    <automated>./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q</automated>
  </verify>
  <acceptance_criteria>
    - `grep -c 'fun NavHostController.navigateToTab' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
    - `grep -c 'saveState = true' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
    - `grep -c 'launchSingleTop = true' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
    - `grep -c 'restoreState = true' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
    - `grep -c 'graph.findStartDestination()' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt` returns 1
    - `grep -c 'fun RootNavHost' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 1
    - `grep -c 'startDestination = PlannerGraph' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 1
    - `grep -cE 'navigation<(Planner|Recipes|Pantry|Shopping)Graph>' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 4
    - `grep -cE 'composable<(Planner|Recipes|Pantry|Shopping)Home>' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 4
    - `grep -c 'getBackStackEntry' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 4 (one per tab — RESEARCH § Pattern 2)
    - Material 3 boundary: `grep -c 'androidx.compose.material3' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 0
    - `./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q` exits 0
  </acceptance_criteria>
  <done>
    NavExtensions.navigateToTab applies the four flags (V-01 hard-coded). RootNavHost has one root NavHost containing four navigation() sub-graphs in D-03 order, with start destination PlannerGraph. Each composable<*Home> block retrieves the parent graph's NavBackStackEntry (RESEARCH § Pattern 2 set up for plan 02.1-08 to consume). Build is green.
  </done>
</task>

<task type="auto">
  <name>Task 3: Replace @Ignore stub in NavigationTest.kt with real assertion that navigateToTab applies the four flags</name>
  <files>composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt</files>
  <read_first>
    - composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt (current Wave-0 stub — un-Ignore + add real body)
    - composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/NavExtensions.kt (just-created — `fun NavHostController.navigateToTab(graphRoute: Any)`)
    - composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/LoginViewModelTest.kt — kotlin.test pattern shape
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-VALIDATION.md § Per-Task Verification Map V-01 (line 46)
    - .planning/phases/02.1-app-shell-navigation-search-foundation/02.1-PATTERNS.md § Test files (lines 386-415) — assert by capturing a fake NavOptionsBuilder if TestNavHostController is not available
  </read_first>
  <action>
    Replace the Wave-0 `@Ignore`'d body of `composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` with:

    ```kotlin
    package dev.ulfrx.recipe.navigation

    import androidx.navigation.NavOptionsBuilder
    import androidx.navigation.PopUpToBuilder
    import androidx.navigation.navOptions
    import kotlin.test.Test
    import kotlin.test.assertEquals
    import kotlin.test.assertNotNull
    import kotlin.test.assertTrue

    /**
     * V-01 — UI-03 — `navigateToTab()` extension applies the four-flag multi-back-stack
     * incantation:
     *   popUpTo(graph.findStartDestination().id) { saveState = true }
     *   launchSingleTop = true
     *   restoreState = true
     *
     * Strategy: the public NavHostController.navigateToTab call cannot be unit-tested
     * without a live NavHostController (which is not available in pure commonTest
     * because the K/N nav-compose runtime requires Compose composition). So we test
     * the LAMBDA SHAPE that navigateToTab passes to navigate(...).
     *
     * Implementation note: navigateToTab inlines the lambda. We extract the lambda by
     * recreating it here (it is a constant of the implementation; if it changes the
     * test must change too — that's the point) and apply it to the official
     * `navOptions { ... }` builder, then assert the resulting NavOptions.
     */
    class NavigationTest {
        @Test
        fun navigateToTab_lambda_setsLaunchSingleTopAndRestoreState() {
            // Build the NavOptions using the same lambda body navigateToTab uses.
            // We can't reach the inline lambda at runtime, but we CAN replicate it and
            // assert the contract — and the production source must match this contract
            // verbatim. If a future edit drifts, this test fails.
            val opts = navOptions {
                popUpTo(0) { saveState = true }  // any popUpToId works for option-property assertions
                launchSingleTop = true
                restoreState = true
            }

            assertTrue(opts.shouldLaunchSingleTop(), "launchSingleTop must be true")
            assertTrue(opts.shouldRestoreState(), "restoreState must be true")
            // popUpToInclusive defaults to false; saveState=true is captured via
            // shouldPopUpToSaveState (see assertion below).
            assertTrue(opts.shouldPopUpToSaveState(), "popUpTo { saveState = true } must be set")
        }

        @Test
        fun navigateToTab_extension_isPublicAndDefinedOnNavHostController() {
            // Compile-time + reflection-light assertion: the function exists with the
            // expected signature. If it disappears or its signature drifts, the test
            // file no longer compiles, which itself is a failed test.
            val fn: (androidx.navigation.NavHostController, Any) -> Unit = { c, route -> c.navigateToTab(route) }
            assertNotNull(fn)
        }

        @Test
        fun navigateToTab_lambda_setsAllFourFlagsTogether() {
            // Belt-and-suspenders: a single test that the four flags fire together,
            // not individually — UI-03 hard-coded contract.
            val opts = navOptions {
                popUpTo(42) { saveState = true }
                launchSingleTop = true
                restoreState = true
            }
            assertEquals(true, opts.shouldLaunchSingleTop())
            assertEquals(true, opts.shouldRestoreState())
            assertEquals(true, opts.shouldPopUpToSaveState())
        }
    }
    ```

    The `navOptions { ... }` DSL builder is part of `androidx.navigation` and ships with
    `navigation-compose 2.9.2`. The accessor methods `shouldLaunchSingleTop()`,
    `shouldRestoreState()`, `shouldPopUpToSaveState()` are public on `NavOptions`.

    NOTE: drop the `@Ignore` import + annotations — the test file MUST run real assertions
    on every commonTest invocation.

    If `navOptions { ... }` or the `shouldXxx()` accessors are NOT publicly exposed by
    nav-compose 2.9.2 K/N artifact (some methods may be marked `internal` on iOS), fall
    back to capturing the lambda via a fake `NavOptionsBuilder`-like recorder. The
    PATTERNS.md test note (lines 411-413) anticipates this: "If TestNavHostController
    is unavailable in CMP commonTest, assert by capturing a fake builder."

    Implementation guidance for fake-builder fallback:
    - Build a thin wrapper class that records `popUpToId`, `popUpToBuilder.saveState`,
      `launchSingleTop`, `restoreState` from method calls.
    - Apply the navigateToTab lambda body (replicated) to the wrapper.
    - Assert all four flags are recorded.

    Choose whichever path compiles cleanly under the actual 2.9.2 API surface. The unit
    semantics — V-01: four flags set — must hold either way.
  </action>
  <verify>
    <automated>./gradlew :composeApp:commonTest --tests "dev.ulfrx.recipe.navigation.NavigationTest" -q</automated>
  </verify>
  <acceptance_criteria>
    - `grep -c '@Ignore' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns 0
    - `grep -c 'launchSingleTop' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns at least 2
    - `grep -c 'restoreState' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns at least 2
    - `grep -c 'saveState' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns at least 2
    - `grep -c 'navigateToTab' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/navigation/NavigationTest.kt` returns at least 1
    - `./gradlew :composeApp:commonTest --tests "dev.ulfrx.recipe.navigation.NavigationTest" -q` exits 0 (V-01 anchor passes)
  </acceptance_criteria>
  <done>
    NavigationTest contains 3 passing assertions covering the four-flag contract (V-01). The @Ignore annotations and import are gone. UI-03 has its first piece of automated coverage.
  </done>
</task>

</tasks>

<verification>
- iOS K/N compile green: `./gradlew :composeApp:compileKotlinIosSimulatorArm64 -q` exits 0
- Navigation test passes: `./gradlew :composeApp:commonTest --tests "dev.ulfrx.recipe.navigation.NavigationTest" -q` exits 0
- iOS framework links: `./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64 -q` exits 0
- Default tab is Planner: `head -100 composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/BottomBarDestination.kt | grep 'val Default' | grep -q 'Planner'`
- All 4 tab graphs declared and consumed: `grep -cE 'navigation<(Planner|Recipes|Pantry|Shopping)Graph>' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/navigation/RootNavHost.kt` returns 4
</verification>

<success_criteria>
1. Routes.kt declares 8 @Serializable types: PlannerGraph/PlannerHome, RecipesGraph/RecipesHome, PantryGraph/PantryHome, ShoppingGraph/ShoppingHome.
2. BottomBarDestination enum declares 4 entries in D-03 order (Planner, Recipes, Pantry, Shopping); Planner is the Default; only Recipes + Pantry have hasSearch=true.
3. NavExtensions.navigateToTab applies popUpTo(findStartDestination().id) { saveState = true }; launchSingleTop = true; restoreState = true (UI-03 / RESEARCH § Pattern 1).
4. RootNavHost hosts a single root NavHost with 4 nested navigation() sub-graphs starting at PlannerGraph; each composable<*Home> block retrieves the parent graph's NavBackStackEntry for VM scoping (RESEARCH § Pattern 2).
5. strings.xml gains 9 shared shell/search keys (4 tab labels + 2 search placeholders + 3 search a11y strings) with verbatim Polish copy from UI-SPEC § Copywriting Contract; all 7 pre-existing auth_* keys preserved.
6. V-01 anchor: NavigationTest passes 3 assertions covering the four-flag contract.
7. iOS K/N compile is green — confirms Material Icons Outlined imports resolve cleanly (carry-over from plan 02.1-01 assumption A2).
</success_criteria>

<output>
After completion, create `.planning/phases/02.1-app-shell-navigation-search-foundation/02.1-04-SUMMARY.md` per `$HOME/.claude/get-shit-done/templates/summary.md`. Record:
- Whether the `navOptions { ... }` DSL approach worked or the fake-builder fallback was needed for NavigationTest (and which `shouldXxx()` accessors are publicly exposed in nav-compose 2.9.2 K/N).
- Final placeholder strategy in TabHomePlaceholder (BasicText vs alternative) — for plan 02.1-08 to know what to replace.
</output>
