Lifecycle, ViewModel and Navigation in Compose Multiplatform

// sharedUI/src/commonMain/kotlin/com/example/trailmate/ui/TrackingEffect.kt
package com.example.trailmate.ui

import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleEventEffect
import androidx.lifecycle.compose.LifecycleResumeEffect
import com.example.trailmate.location.LocationProvider

@Composable
fun TrackingEffect(locationProvider: LocationProvider) {
    // Runs once per ON_START, whatever the platform
    LifecycleEventEffect(Lifecycle.Event.ON_START) {
        locationProvider.refreshPermissionState()
    }

    // Start when RESUMED, stop when PAUSED (phone call, window blur, app switch)
    LifecycleResumeEffect(locationProvider) {
        locationProvider.startUpdates()
        onPauseOrDispose { locationProvider.stopUpdates() }
    }
}

// sharedUI/src/commonMain/kotlin/com/example/trailmate/ui/TrailListRoute.kt
package com.example.trailmate.ui

import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewmodel.compose.viewModel
import com.example.trailmate.di.appContainer
import com.example.trailmate.presentation.TrailListViewModel

@Composable
fun TrailListRoute(onTrailClick: (String) -> Unit) {
    // Initializer lambda: no reflection required, works on iOS, desktop and web
    val viewModel: TrailListViewModel = viewModel { TrailListViewModel(appContainer.trailRepository) }
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    TrailListScreen(uiState = uiState, onTrailClick = onTrailClick)
}

// sharedUI/src/commonMain/kotlin/com/example/trailmate/ui/TrailDetailRoute.kt
package com.example.trailmate.ui

import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import com.example.trailmate.presentation.TrailDetailViewModel
import org.koin.compose.viewmodel.koinViewModel
import org.koin.core.parameter.parametersOf

@Composable
fun TrailDetailRoute(trailId: String, onBack: () -> Unit) {
    // The id is passed to the viewModel { params -> ... } definition in trailMateModule
    val viewModel: TrailDetailViewModel = koinViewModel(parameters = { parametersOf(trailId) })
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    TrailDetailScreen(uiState = uiState, onBack = onBack)
}

// sharedLogic/build.gradle.kts (excerpt) -- native UI path (SwiftUI keeps the screens)
kotlin {
    listOf(iosArm64(), iosSimulatorArm64()).forEach { target ->
        target.binaries.framework {
            baseName = "SharedLogic"
            export(libs.androidx.lifecycle.viewmodel)   // ViewModel must be visible to Swift
        }
    }
    sourceSets {
        commonMain.dependencies {
            api(libs.androidx.lifecycle.viewmodel)       // not the -compose artifact
        }
    }
}

<!-- iosApp/iosApp/Info.plist (excerpt) -->
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>trailmate</string>
        </array>
    </dict>
</array>

// sharedUI/src/commonMain/kotlin/com/example/trailmate/navigation/TrailMateNavHost.kt (excerpt)
composable<TrailDetail>(
    deepLinks = listOf(
        // Generated: trailmate://trail/{id}
        navDeepLink<TrailDetail>(basePath = "trailmate://trail"),
        // Hand-written, for an https link (an App Link on Android, a universal link on iOS)
        navDeepLink { uriPattern = "https://trailmate.example.com/trails/{id}" },
    ),
) { entry ->
    val route: TrailDetail = entry.toRoute()
    TrailDetailRoute(trailId = route.id, onBack = { navController.popBackStack() })
}

// sharedUI/src/commonMain/kotlin/com/example/trailmate/navigation/DeepLinkBus.kt
package com.example.trailmate.navigation

import androidx.navigation.NavController
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.SharedFlow

object DeepLinkBus {
    // replay = 1 keeps a link received before the UI was composed (cold start)
    private val _links = MutableSharedFlow<String>(replay = 1, extraBufferCapacity = 1)
    val links: SharedFlow<String> = _links

    fun onUri(uri: String) { _links.tryEmit(uri) }
}

// Used from App(): LaunchedEffect(navController) { DeepLinkBus.links.collect { navController.navigate(...) } }

// iosApp/iosApp/iOSApp.swift
import SwiftUI
import SharedUI

@main
struct iOSApp: App {
    var body: some Scene {
        WindowGroup {
            ComposeHost()
                .ignoresSafeArea()
                .onOpenURL { url in
                    // Forward to the shared singleton; the NavHost reacts
                    DeepLinkBus.shared.onUri(uri: url.absoluteString)
                }
        }
    }
}

// sharedUI/src/commonMain/kotlin/com/example/trailmate/navigation/Nav3Keys.kt
package com.example.trailmate.navigation

import androidx.navigation3.runtime.NavKey
import androidx.savedstate.serialization.SavedStateConfiguration
import kotlinx.serialization.Serializable
import kotlinx.serialization.modules.SerializersModule
import kotlinx.serialization.modules.polymorphic
import kotlinx.serialization.modules.subclass

@Serializable
sealed interface TrailKey : NavKey

@Serializable data object TrailListKey : TrailKey
@Serializable data class TrailDetailKey(val id: String) : TrailKey
@Serializable data object SettingsKey : TrailKey

// Required on iOS and web: tells the saved-state machinery how to (de)serialize NavKey
val trailMateSavedState = SavedStateConfiguration {
    serializersModule = SerializersModule {
        polymorphic(NavKey::class) {
            subclass(TrailListKey::class, TrailListKey.serializer())
            subclass(TrailDetailKey::class, TrailDetailKey.serializer())
            subclass(SettingsKey::class, SettingsKey.serializer())
        }
    }
}

// sharedUI/src/commonMain/kotlin/com/example/trailmate/navigation/TrailMateNav3.kt
package com.example.trailmate.navigation

import androidx.compose.runtime.Composable
import androidx.lifecycle.viewmodel.navigation3.rememberViewModelStoreNavEntryDecorator
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
import androidx.navigation3.ui.NavDisplay
import com.example.trailmate.ui.SettingsRoute
import com.example.trailmate.ui.TrailDetailRoute
import com.example.trailmate.ui.TrailListRoute

@Composable
fun TrailMateNav3() {
    // The overload with SavedStateConfiguration is the multiplatform-safe one
    val backStack = rememberNavBackStack(trailMateSavedState, TrailListKey)

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryDecorators = listOf(
            rememberSaveableStateHolderNavEntryDecorator(),  // rememberSaveable per entry
            rememberViewModelStoreNavEntryDecorator(),       // ViewModel per entry
        ),
        entryProvider = entryProvider {
            entry<TrailListKey> {
                TrailListRoute(
                    onTrailClick = { id -> backStack.add(TrailDetailKey(id)) },
                    onSettings = { backStack.add(SettingsKey) },
                )
            }
            entry<TrailDetailKey> { key ->
                TrailDetailRoute(trailId = key.id, onBack = { backStack.removeLastOrNull() })
            }
            entry<SettingsKey> { SettingsRoute(onBack = { backStack.removeLastOrNull() }) }
        },
    )
}