refactor: KMP best practices — androidx ViewModel, .update{}, navigateTo + docs

CLAUDE.md

@@ -24,14 +24,14 @@ Kotlin lint is detekt (`config/detekt/detekt.yml`, with `detekt-formatting` + `d
 
 **Business logic is shared; UI is native per platform.** This is the core rule — internalize it before making changes.
 
-- `shared/src/commonMain/kotlin/com/github/jvsena42/eco/` holds all cross-platform code:
+- `shared/src/commonMain/kotlin/com/github/jvsena42/echo/` holds all cross-platform code:
   - `domain/model/` — pure Kotlin data classes (`Deck`, `Card`, `ImportDraft`, `SrsState`, `AppError`, etc.). No framework imports.
   - `data/repository/` — repository interfaces (all 8 in `Repositories.kt`: Identity, Deck, Card, Import, Media, Tag, Discovery, Srs), implementations under `data/repository/impl/`. **Repositories own the business logic** — parsing, triage, publishing, SRS grading, follow/unfollow, sign-in/out all live as methods on the relevant repo rather than in a separate use-case layer. **All 8 are implemented** (`IdentityRepositoryImpl`, `DeckRepositoryImpl`, `CardRepositoryImpl`, `ImportRepositoryImpl` — the paste parser, spec §6 rules + §9 edge cases —, `MediaRepositoryImpl`, `SrsRepositoryImpl`, `DiscoveryRepositoryImpl`, `TagRepositoryImpl`), plus `SessionRevalidatorImpl`. `TagRepositoryImpl` writes pubky-app-specs tag records to the homeserver and reads trending from the Nexus indexer (`data/nexus/NexusClient`, see Architecture.md §7.6). The impls are Pubky-only: they write/read through `PubkyClient` and hold an in-memory per-session cache. No SQLDelight yet — the app is not offline-first, Pubky is the single source of truth.
   - `data/pubky/` — `PubkyClient` interface + DTOs (`ManifestDto`, `CardDto`, `MediaRefDto` in `DeckDtos.kt`, `ProfileDto`) and path helpers (`PubkyPaths`, `Hashing`) that map between domain models and the on-homeserver JSON layout defined in `docs/Architecture.md §8.0`. `SessionProvider`/`MutableSessionProvider` is the tiny read-only abstraction repos use to author writes without depending on `IdentityRepository`. `SessionRevalidator` + `SessionRetry` + `SessionPayloadParser` handle expired-session retry.
   - `data/pubky/PubkyClient.kt` — the single interface that wraps `pubky-core-ffi-fork`. All Pubky calls must route through this. It is a **thin** 1:1 mirror of the FFI surface (keys, mnemonics, recovery, auth, records, DHT). Do not add deck/card concepts here — those belong in repositories. The `actual` impl is `AndroidPubkyClient` (androidMain); the iOS impl (`IosPubkyClient.swift`) is still a stub awaiting framework binding.
   - `data/storage/` — `SecureSessionStore` interface for persisting the signed-in `Session`, backed by the platform keystore via Liftric KVault (`AndroidSecureSessionStore` wraps EncryptedSharedPreferences; `IosSecureSessionStore` wraps Keychain). This resolves the secret-storage open question — see "Non-obvious rules" below.
   - `di/SharedModule.kt` — Koin graph binding repos, ViewModels, and `SessionProvider`; platforms override `PubkyClient` + `SecureSessionStore` via `PlatformModule.{android,ios}.kt`.
-  - `presentation/` — KMP ViewModels, one per screen (`StateFlow<UiState>` + `SharedFlow<UiEffect>`). **Implemented** across `onboarding/` (`OnboardingViewModel` + UiState/Effect), `home/` (`HomeViewModel`), `decks/` (`DecksLibraryViewModel`, `DeckDetailViewModel`, `DeckEditorViewModel`, `EditCardViewModel`), `import/` (`PasteImportViewModel`, `PublishDeckViewModel`), and `profile/` (`ProfileViewModel`). Coroutines + Koin are wired (no longer blocked).
+  - `presentation/` — KMP ViewModels, one per screen, each extending the multiplatform `androidx.lifecycle.ViewModel` (`viewModelScope`) and exposing `StateFlow<UiState>` + `SharedFlow<UiEffect>` (see "Coding conventions" below). **Implemented** across `onboarding/` (`OnboardingViewModel` + UiState/Effect), `home/` (`HomeViewModel`), `decks/` (`DecksLibraryViewModel`, `DeckDetailViewModel`, `DeckEditorViewModel`, `EditCardViewModel`), `import/` (`PasteImportViewModel`, `PublishDeckViewModel`), and `profile/` (`ProfileViewModel`). Coroutines + Koin are wired (no longer blocked).
 - `shared/src/{android,ios}Main/` — `expect`/`actual` platform glue only (Pubky FFI, TTS, haptics, file I/O). Nothing else lives here.
 - `composeApp/src/androidMain/` — Android app. Compose screens in `ui/`, Koin in `di/`, `MainActivity` as entry point. Uses Jetpack Navigation Compose.
 - `iosApp/iosApp/` — iOS app. SwiftUI screens in `Views/`, `NavigationStack` in `Navigation/`, Koin bootstrap in `DI/`. Compose Multiplatform UI is **not** used for iOS screens.
@@ -55,6 +55,58 @@ Kotlin lint is detekt (`config/detekt/detekt.yml`, with `detekt-formatting` + `d
 
 Root package is `com.github.jvsena42.echo`. Android namespace is `com.github.jvsena42.echo` (app) and `com.github.jvsena42.echo.shared` (library).
 
+## Coding conventions
+
+Prescriptive rules, adapted from the sibling Bitkit apps' `AGENTS.md` to Echo's
+shared-logic / native-UI split. These are the canonical conventions — `docs/Architecture.md`
+points here rather than restating them.
+
+### Shared (Kotlin · `shared/commonMain`)
+
+- **ViewModels extend `androidx.lifecycle.ViewModel`** (the multiplatform JetBrains build) and
+  launch work in `viewModelScope`. Do **not** hand-roll a `CoroutineScope`/`SupervisorJob` or an
+  `onDispose()` — `viewModelScope` cancels in `onCleared()`. Never use `GlobalScope`; never
+  `runBlocking` in suspend code.
+- **State:** expose `val state: StateFlow<UiState> = _state.asStateFlow()`. **ALWAYS mutate with
+  `_state.update { … }`; NEVER `_state.value = …`** (atomic read-modify-write). Reading
+  `_state.value` is fine.
+- **Effects:** one-shot effects (navigation, haptics, toasts, clipboard) go through a
+  `MutableSharedFlow(extraBufferCapacity = 4)` exposed as `SharedFlow`, separate from state.
+- **UiState shape:** `sealed interface` for screens with distinct modes (Loading/Empty/Content/Error);
+  a single `data class` with nullable fields otherwise. Keep `UiState`/`Effect`/small helper data
+  classes in the same file, after the ViewModel. (Annotate with `@Immutable` only in the *Android*
+  layer — shared `commonMain` has no Compose dependency.)
+- **Errors:** prefer `runCatching { … }.onSuccess { }.onFailure { }` / `Result` over try/catch; map
+  domain `AppError` into the UI state. Prefer `requireNotNull(x) { "…" }` over `!!`.
+- **DI:** bind ViewModels with Koin's `viewModel { }` DSL (`org.koin.core.module.dsl.viewModel`) in
+  `SharedModule.kt`; repositories stay `single { }`.
+- **Imports:** always import; never inline fully-qualified names (Kotlin and Swift).
+
+### Android (Compose · `composeApp`)
+
+- **Stateful/stateless split:** a `…Route` composable resolves the VM via `koinViewModel()` (NOT
+  `koinInject`), collects state with `collectAsStateWithLifecycle()`, and consumes effects in a
+  `LaunchedEffect`; it delegates to a stateless `…Screen(state, callbacks)`. Pass `viewModel::method`
+  references down — never the ViewModel itself.
+- **No manual VM disposal.** With `koinViewModel()` + `viewModelScope`, drop the old
+  `DisposableEffect { onDispose { viewModel.onDispose() } }` blocks.
+- **`modifier: Modifier = Modifier`** is the first optional parameter and is passed **last** at call sites.
+- **Navigation goes through `NavController.navigateTo()`** (`ui/nav/NavExt.kt`), which dedups the
+  current destination — never raw `navController.navigate(...)`.
+- **Immutable collections (recommended, not yet adopted):** prefer `ImmutableList`/`persistentListOf()`
+  for `UiState` list fields and Compose params, and annotate `UiState`/token data classes `@Immutable`.
+  `kotlinx.collections.immutable` is not yet a dependency — treat this as the target when touching state.
+- No hardcoded user-facing strings — use string resources.
+
+### iOS (SwiftUI · `iosApp`)
+
+- **Consume the shared KMP ViewModels.** Do **not** introduce iOS-side `@Observable` business-logic
+  objects (unlike bitkit-ios) — Echo shares its VMs. Bridge `StateFlow`/`SharedFlow` → SwiftUI per the
+  Architecture §9.2 decision; call the VM's generated `clear()` on disappear (there is no `onDispose()`).
+- Reuse the project's text/components instead of raw `Text().font().foregroundColor()` chains; use
+  `.task` (not `.onAppear`) for async tied to a view's lifetime; mutate state on `@MainActor`; use
+  self-documenting names (`isLoadingDecks`, not `loading`); comment only non-obvious "why".
+
 ## Where to read before starting work
 
 - `docs/Architecture.md` — always. §4 (shared layering), §6 (Paste-to-Import state flow), §7 (Pubky open question), §12 (open questions blocking feature work).

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/components/ImagePickerSheet.kt

@@ -37,7 +37,6 @@ import androidx.compose.material3.OutlinedTextFieldDefaults
 import androidx.compose.material3.Text
 import androidx.compose.material3.rememberModalBottomSheetState
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
@@ -65,6 +64,7 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 
 /**
  * Reusable bottom sheet for choosing an image — web search (Unsplash) + a 3-column grid, plus a
@@ -81,9 +81,8 @@ fun ImagePickerSheet(
     onSelected: (ImageSelection) -> Unit,
 ) {
     val colors = EchoTheme.colors
-    val viewModel = koinInject<ImageSheetViewModel>()
+    val viewModel = koinViewModel<ImageSheetViewModel>()
     val mediaProcessor = koinInject<MediaProcessor>()
-    DisposableEffect(viewModel) { onDispose { viewModel.onDispose() } }
 
     val state by viewModel.state.collectAsStateWithLifecycle()
     val sheetState = rememberModalBottomSheetState(skipPartiallyExpanded = true)

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/decks/DeckDetailScreen.kt

@@ -31,7 +31,6 @@ import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberUpdatedState
@@ -61,7 +60,7 @@ import com.github.jvsena42.echo.ui.components.StatsBar
 import com.github.jvsena42.echo.ui.components.TagChip
 import com.github.jvsena42.echo.ui.theme.EchoTheme
 import kotlinx.coroutines.flow.collectLatest
-import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 import org.koin.core.parameter.parametersOf
 
 @Composable
@@ -72,10 +71,7 @@ fun DeckDetailRoute(
     onEditDeck: (String) -> Unit = {},
     onStudy: (String) -> Unit = {},
 ) {
-    val viewModel = koinInject<DeckDetailViewModel> { parametersOf(deckId, authorPubky) }
-    DisposableEffect(viewModel) {
-        onDispose { viewModel.onDispose() }
-    }
+    val viewModel = koinViewModel<DeckDetailViewModel> { parametersOf(deckId, authorPubky) }
 
     val currentBack by rememberUpdatedState(onBack)
     val currentEditDeck by rememberUpdatedState(onEditDeck)

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/decks/DeckEditorScreen.kt

@@ -42,7 +42,6 @@ import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.material3.TopAppBarDefaults
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberUpdatedState
@@ -65,7 +64,7 @@ import com.github.jvsena42.echo.presentation.decks.EditableCardModel
 import com.github.jvsena42.echo.ui.components.TagChip
 import com.github.jvsena42.echo.ui.theme.EchoTheme
 import kotlinx.coroutines.flow.collectLatest
-import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 import org.koin.core.parameter.parametersOf
 
 @Composable
@@ -75,10 +74,7 @@ fun DeckEditorRoute(
     onEditCard: (deckId: String, cardId: String) -> Unit = { _, _ -> },
     onSaved: (deckId: String) -> Unit = {},
 ) {
-    val viewModel = koinInject<DeckEditorViewModel> { parametersOf(deckId) }
-    DisposableEffect(viewModel) {
-        onDispose { viewModel.onDispose() }
-    }
+    val viewModel = koinViewModel<DeckEditorViewModel> { parametersOf(deckId) }
 
     val currentBack by rememberUpdatedState(onBack)
     val currentEditCard by rememberUpdatedState(onEditCard)

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/decks/DecksScreen.kt

@@ -27,7 +27,6 @@ import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.material3.pulltorefresh.PullToRefreshBox
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberUpdatedState
@@ -53,18 +52,15 @@ import com.github.jvsena42.echo.ui.components.EchoLoadingScreen
 import com.github.jvsena42.echo.ui.components.EchoPrimaryButton
 import com.github.jvsena42.echo.ui.theme.EchoTheme
 import kotlinx.coroutines.flow.collectLatest
-import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 
 @Composable
 fun DecksRoute(
     onDeckClick: (String) -> Unit = {},
     onImportClick: () -> Unit = {},
     onCreateDeckClick: () -> Unit = {},
 ) {
-    val viewModel = koinInject<DecksLibraryViewModel>()
-    DisposableEffect(viewModel) {
-        onDispose { viewModel.onDispose() }
-    }
+    val viewModel = koinViewModel<DecksLibraryViewModel>()
 
     val currentDeckClick by rememberUpdatedState(onDeckClick)
     val currentImportClick by rememberUpdatedState(onImportClick)

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/decks/EditCardScreen.kt

@@ -36,7 +36,6 @@ import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.material3.TopAppBarDefaults
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
@@ -64,6 +63,7 @@ import com.github.jvsena42.echo.ui.components.TagChip
 import com.github.jvsena42.echo.ui.theme.EchoTheme
 import kotlinx.coroutines.flow.collectLatest
 import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 import org.koin.core.parameter.parametersOf
 
 @Composable
@@ -72,11 +72,8 @@ fun EditCardRoute(
     cardId: String,
     onBack: () -> Unit = {},
 ) {
-    val viewModel = koinInject<EditCardViewModel> { parametersOf(deckId, cardId) }
+    val viewModel = koinViewModel<EditCardViewModel> { parametersOf(deckId, cardId) }
     val speaker = koinInject<Speaker>()
-    DisposableEffect(viewModel) {
-        onDispose { viewModel.onDispose() }
-    }
 
     val currentBack by rememberUpdatedState(onBack)
 

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/discover/DiscoverScreen.kt

@@ -32,7 +32,6 @@ import androidx.compose.material3.TextButton
 import androidx.compose.material3.pulltorefresh.PullToRefreshBox
 import androidx.compose.material3.rememberModalBottomSheetState
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
@@ -63,15 +62,14 @@ import com.github.jvsena42.echo.ui.components.EchoLoadingScreen
 import com.github.jvsena42.echo.ui.components.TagChip
 import com.github.jvsena42.echo.ui.theme.EchoTheme
 import kotlinx.coroutines.flow.collectLatest
-import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 
 @Composable
 fun DiscoverRoute(
     onOpenProfile: (String) -> Unit = {},
     onOpenDeck: (deckId: String, author: String?) -> Unit = { _, _ -> },
 ) {
-    val viewModel = koinInject<DiscoverViewModel>()
-    DisposableEffect(viewModel) { onDispose { viewModel.onDispose() } }
+    val viewModel = koinViewModel<DiscoverViewModel>()
 
     val currentOpenProfile by rememberUpdatedState(onOpenProfile)
     val currentOpenDeck by rememberUpdatedState(onOpenDeck)

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/home/HomeScreen.kt

@@ -16,7 +16,6 @@ import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.Text
 import androidx.compose.material3.pulltorefresh.PullToRefreshBox
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberUpdatedState
@@ -36,7 +35,7 @@ import com.github.jvsena42.echo.presentation.home.HomeViewModel
 import com.github.jvsena42.echo.ui.components.EchoLoadingScreen
 import com.github.jvsena42.echo.ui.theme.EchoTheme
 import kotlinx.coroutines.flow.collectLatest
-import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 
 @Composable
 fun HomeRoute(
@@ -46,10 +45,7 @@ fun HomeRoute(
     onOpenDeck: (String) -> Unit = {},
     onSignedOut: () -> Unit = {},
 ) {
-    val viewModel = koinInject<HomeViewModel>()
-    DisposableEffect(viewModel) {
-        onDispose { viewModel.onDispose() }
-    }
+    val viewModel = koinViewModel<HomeViewModel>()
 
     val currentCreate by rememberUpdatedState(onCreateDeck)
     val currentBrowse by rememberUpdatedState(onBrowseExamples)

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/importflow/PasteScreen.kt

@@ -35,7 +35,6 @@ import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.material3.TopAppBarDefaults
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.rememberUpdatedState
@@ -60,15 +59,14 @@ import com.github.jvsena42.echo.presentation.importflow.PreviewCard
 import com.github.jvsena42.echo.ui.components.EchoPrimaryButton
 import com.github.jvsena42.echo.ui.theme.EchoTheme
 import kotlinx.coroutines.flow.collectLatest
-import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 
 @Composable
 fun PasteRoute(
     onCancel: () -> Unit = {},
     onNext: () -> Unit = {},
 ) {
-    val viewModel = koinInject<PasteImportViewModel>()
-    DisposableEffect(viewModel) { onDispose { viewModel.onDispose() } }
+    val viewModel = koinViewModel<PasteImportViewModel>()
 
     val currentCancel by rememberUpdatedState(onCancel)
     val currentNext by rememberUpdatedState(onNext)

composeApp/src/androidMain/kotlin/com/github/jvsena42/echo/ui/importflow/PublishDeckScreen.kt

@@ -39,7 +39,6 @@ import androidx.compose.material3.SwitchDefaults
 import androidx.compose.material3.Text
 import androidx.compose.material3.rememberModalBottomSheetState
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
@@ -72,15 +71,14 @@ import com.github.jvsena42.echo.ui.components.ImageSelection
 import com.github.jvsena42.echo.ui.components.TagChip
 import com.github.jvsena42.echo.ui.theme.EchoTheme
 import kotlinx.coroutines.flow.collectLatest
-import org.koin.compose.koinInject
+import org.koin.compose.viewmodel.koinViewModel
 
 @Composable
 fun PublishDeckRoute(
     onBack: () -> Unit = {},
     onPublished: (deckId: String) -> Unit = {},
 ) {
-    val viewModel = koinInject<PublishDeckViewModel>()
-    DisposableEffect(viewModel) { onDispose { viewModel.onDispose() } }
+    val viewModel = koinViewModel<PublishDeckViewModel>()
 
     val currentBack by rememberUpdatedState(onBack)
     val currentPublished by rememberUpdatedState(onPublished)