@code-migration/wow-migrator 0.2.3 → 0.2.5

package/skills/android-to-kmp-migrator/references/kmp-mvi-flowredux.md

@@ -0,0 +1,344 @@
+---
+name: kmp-mvi-flowredux
+description: >
+  KMP/CMP MVI architecture using FlowRedux state machines. Use when building or
+  reviewing Kotlin Multiplatform features that need MVI pattern: state machines,
+  sealed State/Action classes, unidirectional data flow, Compose Multiplatform UI
+  wiring, or when the user mentions FlowRedux, MVI, state machine, inState, onEnter,
+  dispatch, or sealed interface State.
+---
+
+# KMP MVI with FlowRedux — architecture skill
+
+Reference: https://freeletics.github.io/FlowRedux/
+
+## Core concepts
+
+MVI (Model-View-Intent) enforces **unidirectional data flow**:
+
+```
+Action (Intent) ──► StateMachine ──► State ──► UI
+       ▲                                        │
+       └────────────────────────────────────────┘
+                      dispatch()
+```
+
+FlowRedux models this as an explicit **state machine** with a Coroutines DSL:
+- `State` — sealed interface; each subtype is a discrete screen state
+- `Action` — sealed interface; every user gesture or external event
+- `FlowReduxStateMachineFactory` — holds the `spec { }` DSL and produces instances
+- `FlowReduxStateMachine` — public API: `state: Flow<State>` + `suspend dispatch(action)`
+
+---
+
+## Architecture layers
+
+```
+:shared/commonMain
+  ├── feature/
+  │   ├── model/
+  │   │   ├── FeatureState.kt        ← sealed interface State + subtypes
+  │   │   └── FeatureAction.kt       ← sealed interface Action + subtypes
+  │   ├── statemachine/
+  │   │   └── FeatureStateMachineFactory.kt  ← FlowReduxStateMachineFactory
+  │   └── domain/
+  │       └── FeatureRepository.kt   ← interface; expect/actual for platform impl
+  └── di/
+      └── FeatureModule.kt           ← Koin module wiring factory + repo
+
+:composeApp/commonMain
+  └── feature/
+      ├── FeatureScreen.kt           ← @Composable, uses produceStateMachine()
+      └── FeatureViewModel.kt        ← optional: ViewModel wrapper for lifecycle
+```
+
+**Rule:** All state machine logic lives in `:shared/commonMain`. The UI layer
+(`:composeApp`) only renders state and dispatches actions — zero business logic.
+
+---
+
+## Coding guidance
+
+### 1. Define State and Action as sealed interfaces
+
+```kotlin
+// shared/commonMain/.../model/ItemListState.kt
+sealed interface ItemListState {
+    data object Loading : ItemListState
+    data class ShowContent(val items: List<Item>) : ItemListState
+    data class Error(val message: String, val countdown: Int) : ItemListState
+}
+
+// shared/commonMain/.../model/ItemListAction.kt
+sealed interface ItemListAction {
+    data object RetryLoading : ItemListAction
+    data class ToggleFavorite(val itemId: Int) : ItemListAction
+}
+```
+
+Rules:
+- `State` subtypes are `data object` (no fields) or `data class` (immutable fields)
+- Never put UI logic inside a `State` — it is plain data
+- `Action` subtypes carry only the payload the handler needs — nothing else
+
+### 2. Write the StateMachineFactory in commonMain
+
+```kotlin
+// shared/commonMain/.../statemachine/ItemListStateMachineFactory.kt
+class ItemListStateMachineFactory(
+    private val repository: ItemRepository
+) : FlowReduxStateMachineFactory<ItemListState, ItemListAction>() {
+
+    init {
+        initializeWith { Loading }
+
+        spec {
+            inState<Loading> {
+                onEnter { state ->
+                    try {
+                        val items = repository.loadItems()
+                        state.override { ShowContent(items) }
+                    } catch (t: Throwable) {
+                        state.override { Error(t.message ?: "Unknown error", countdown = 3) }
+                    }
+                }
+            }
+
+            inState<Error> {
+                on<RetryLoading> { _, state ->
+                    state.override { Loading }
+                }
+
+                collectWhileInState(timerEverySecond()) { _, state ->
+                    val next = state.snapshot.countdown - 1
+                    if (next <= 0) state.override { Loading }
+                    else state.mutate { copy(countdown = next) }
+                }
+            }
+
+            inState<ShowContent> {
+                on<ToggleFavorite>(executionPolicy = ExecutionPolicy.Unordered) { action, state ->
+                    // delegate to child state machine — see composing section
+                    state.mutate { copy(items = items.map { item ->
+                        if (item.id == action.itemId) item.copy(toggling = true) else item
+                    }) }
+                }
+            }
+        }
+    }
+}
+```
+
+Rules:
+- One factory per feature/screen — not one global machine
+- `initializeWith { }` always first in `init`
+- Extract large handlers into `private suspend fun` for readability and unit-testability
+- Never call `state.override` or `state.mutate` after the function returns — these are the only mutation points
+
+### 3. DSL blocks reference
+
+| Block | Triggers when | Typical use |
+|---|---|---|
+| `onEnter { }` | State is entered | Load data, start timers |
+| `on<Action> { }` | Action arrives while in this state | User interactions |
+| `collectWhileInState(flow) { }` | Flow emits while in this state | Countdown, realtime updates |
+| `onActionEffect<Action> { }` | Like `on<>` but does NOT transition state | Logging, analytics side-effects |
+| `condition { }` | Wraps sub-blocks with a predicate | Feature flags, conditional handlers |
+| `untilIdentityChanged { }` | Re-enters block when identity field changes | Pagination, refresh on id change |
+
+### 4. ExecutionPolicy — choose deliberately
+
+```kotlin
+// Default: CancelPrevious — cancel in-flight handler when same action fires again
+on<SearchQueryChanged> { action, state -> ... }
+
+// Unordered — run in parallel, no order guarantee; use for independent async ops
+on<ToggleFavorite>(executionPolicy = ExecutionPolicy.Unordered) { ... }
+
+// Ordered — sequential; use when order matters and you must not cancel
+on<PageLoad>(executionPolicy = ExecutionPolicy.Ordered) { ... }
+
+// Throttled — ignore re-triggers within duration; use for debounce-like behaviour
+on<ButtonClick>(executionPolicy = ExecutionPolicy.Throttled(500.milliseconds)) { ... }
+```
+
+### 5. Compose Multiplatform UI wiring
+
+```kotlin
+// composeApp/commonMain/.../FeatureScreen.kt
+@Composable
+fun ItemListScreen(factory: ItemListStateMachineFactory) {
+    val stateMachine = factory.produceStateMachine()   // FlowRedux compose extension
+    val state by stateMachine.state.collectAsState()   // or use stateMachine.state.value
+
+    when (val s = state) {
+        is Loading     -> LoadingIndicator()
+        is ShowContent -> ContentList(s.items, onToggle = {
+            stateMachine.dispatch(ToggleFavorite(it))  // dispatch is non-suspending in compose ext
+        })
+        is Error       -> ErrorView(s.message, s.countdown, onRetry = {
+            stateMachine.dispatch(RetryLoading)
+        })
+    }
+}
+```
+
+For Android ViewModel lifecycle:
+
+```kotlin
+class ItemListViewModel @Inject constructor(
+    private val factory: ItemListStateMachineFactory
+) : ViewModel() {
+    private val stateMachine = factory.shareIn(viewModelScope)
+    val state: StateFlow<ItemListState> = stateMachine.state
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), Loading)
+
+    fun dispatch(action: ItemListAction) {
+        viewModelScope.launch { stateMachine.dispatch(action) }
+    }
+}
+```
+
+### 6. Composing state machines (hierarchical)
+
+Delegate a sub-problem to a child state machine rather than bloating the parent spec:
+
+```kotlin
+inState<ShowContent> {
+    onActionStartStateMachine(
+        stateMachineFactoryBuilder = { action: ToggleFavorite ->
+            FavoriteStatusStateMachineFactory(
+                itemId = action.itemId,
+                httpClient = httpClient
+            )
+        }
+    ) { favoriteStatus: FavoriteStatus ->
+        // merge child state into parent state
+        mutate { copy(items = items.updateFavoriteStatus(favoriteStatus)) }
+    }
+}
+```
+
+Use `onEnterStartStateMachine()` when you want a child machine to start on state entry
+rather than on an explicit action.
+
+### 7. Effects (side-effects without state transition)
+
+```kotlin
+inState<ShowContent> {
+    onActionEffect<ToggleFavorite> { action, stateSnapshot ->
+        analytics.track("toggle_favorite", mapOf("id" to action.itemId))
+        // cannot mutate state from an effect block
+    }
+}
+```
+
+Use `*Effect` variants whenever you need to react to an action or event but must not
+change state (navigation events, analytics, logging).
+
+---
+
+## Project structure checklist
+
+```
+:shared
+  commonMain
+    └── feature/itemlist/
+        ├── model/
+        │   ├── ItemListState.kt          ✓ sealed interface, data classes, immutable
+        │   └── ItemListAction.kt         ✓ sealed interface
+        ├── statemachine/
+        │   ├── ItemListStateMachineFactory.kt  ✓ extends FlowReduxStateMachineFactory
+        │   └── FavoriteStatusStateMachineFactory.kt  ✓ child machine
+        ├── domain/
+        │   └── ItemRepository.kt         ✓ interface only
+        └── data/
+            └── ItemRepositoryImpl.kt     ✓ actual implementation (or expect/actual)
+
+:composeApp
+  commonMain
+    └── feature/itemlist/
+        ├── ItemListScreen.kt             ✓ @Composable, pure render + dispatch
+        └── ItemListViewModel.kt          ✓ only if AndroidX lifecycle needed
+```
+
+---
+
+## Testing guidance
+
+Prefer **functional integration tests** with Turbine over unit tests per handler.
+
+```kotlin
+// Use runTest + Turbine for the full state machine
+@Test
+fun `loading transitions to ShowContent on success`() = runTest {
+    val factory = ItemListStateMachineFactory(FakeItemRepository(items = sampleItems))
+    val sm = factory.shareIn(backgroundScope)
+
+    sm.state.test {
+        assertEquals(Loading, awaitItem())
+        assertEquals(ShowContent(sampleItems), awaitItem())
+    }
+}
+
+// Override initial state to test mid-flow without replaying all transitions
+@Test
+fun `retry from Error transitions to Loading`() = runTest {
+    val factory = ItemListStateMachineFactory(FakeItemRepository())
+    factory.initializeWith { Error("oops", countdown = 3) }
+    val sm = factory.shareIn(backgroundScope)
+
+    sm.state.test {
+        assertEquals(Error("oops", 3), awaitItem())
+        sm.dispatch(RetryLoading)
+        assertEquals(Loading, awaitItem())
+    }
+}
+```
+
+For **unit testing handlers**, extract them to `private suspend fun` and test with
+`ChangeableState` + `changedState.reduce(snapshot)` directly.
+
+---
+
+## Gradle dependencies
+
+```kotlin
+// shared/build.gradle.kts
+kotlin {
+    sourceSets {
+        commonMain.dependencies {
+            // FlowRedux core (KMP)
+            implementation("com.freeletics.flowredux:flowredux:2.0.1")
+            // Coroutines
+            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
+        }
+    }
+}
+
+// composeApp/build.gradle.kts
+commonMain.dependencies {
+    // FlowRedux Compose extensions (produceStateMachine, dispatch)
+    implementation("com.freeletics.flowredux:compose:2.0.1")
+}
+
+// Testing
+commonTest.dependencies {
+    implementation("app.cash.turbine:turbine:1.1.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
+}
+```
+
+---
+
+## Anti-patterns to avoid
+
+| Anti-pattern | Fix |
+|---|---|
+| Business logic inside `@Composable` | Move to `inState { }` handlers |
+| Mutable state inside `State` data class | All fields must be `val`; use `state.mutate { copy(...) }` |
+| One giant state machine for the whole app | One factory per screen/feature |
+| `state.override` called after a `return` | Override is the last expression in the lambda |
+| Catching all `Throwable` silently | Log or encode the error into an `Error` state subtype |
+| Skipping `ExecutionPolicy` on concurrent actions | Explicitly choose `Unordered` or `Ordered` where needed |
+| Navigation logic inside state | Use `onActionEffect` + a navigation callback; state stays pure data |

package/skills/android-to-kmp-migrator/references/kmp-mvvm.md

@@ -0,0 +1,328 @@
+---
+name: kmp-mvvm
+description: >
+  KMP/CMP MVVM architecture with shared ViewModels. Use when building or reviewing
+  Kotlin Multiplatform features that follow the MVVM pattern: ViewModel + StateFlow,
+  UI state classes, state hoisting, collectAsStateWithLifecycle, Koin viewModel
+  injection, or bridging shared ViewModels to SwiftUI on iOS. Triggers on MVVM,
+  ViewModel, StateFlow, uiState, viewModelScope, KMP-ObservableViewModel, SKIE.
+---
+
+# KMP MVVM with shared ViewModels — architecture skill
+
+References:
+- https://kotlinlang.org/docs/multiplatform/compose-viewmodel.html
+- https://touchlab.co/kmp-view-models
+
+## Core concepts
+
+MVVM separates concerns into three groups:
+
+```
+        observe (StateFlow)              user events (fun calls)
+View ◄───────────────────────── ViewModel ◄──────────────────── View
+ │                                  │
+ │                                  ▼
+ │                          Model (UseCase / Repository)
+ └─ renders UiState                 │
+                                    ▼
+                            data / network / cache
+```
+
+- **Model** — domain + data layer (UseCases, Repositories) in `commonMain`
+- **ViewModel** — holds and exposes immutable `UiState` as `StateFlow`, handles events
+- **View** — Compose Multiplatform (shared) or native (SwiftUI/Compose), renders state only
+
+MVVM vs MVI: MVVM exposes a single immutable `UiState` and *public methods* for events,
+rather than dispatching `Action` objects through a reducer. Use MVVM when the team is
+Android/Compose-native and the per-screen state is simple; reach for MVI/FlowRedux when
+state transitions are complex enough to warrant an explicit state machine.
+
+---
+
+## Architecture layers
+
+```
+:shared/commonMain
+  ├── feature/order/
+  │   ├── presentation/
+  │   │   ├── OrderUiState.kt        ← single immutable data class (the "Model" the View sees)
+  │   │   └── OrderViewModel.kt      ← extends ViewModel, exposes StateFlow<OrderUiState>
+  │   ├── domain/
+  │   │   ├── OrderRepository.kt     ← interface
+  │   │   └── PlaceOrderUseCase.kt   ← business logic, no Android deps
+  │   └── data/
+  │       └── OrderRepositoryImpl.kt ← actual impl (Ktor/SQLDelight)
+  └── di/
+      └── OrderModule.kt             ← Koin module: viewModelOf(::OrderViewModel)
+
+:composeApp/commonMain
+  └── feature/order/
+      └── OrderScreen.kt             ← @Composable, koinViewModel() + collectAsStateWithLifecycle()
+
+iosApp (Swift)                        ← observes ViewModel via KMP-ObservableViewModel
+```
+
+**Rule:** ViewModel, UiState, and all logic live in `:shared/commonMain`. The View only
+collects state and calls ViewModel methods.
+
+---
+
+## Choosing the ViewModel base class
+
+There are three viable approaches. Pick one per project and stay consistent.
+
+| Approach | commonMain dependency | iOS story | When to use |
+|---|---|---|---|
+| **AndroidX `lifecycle-viewmodel` (multiplatform)** | `androidx.lifecycle:lifecycle-viewmodel:2.8+` | Manual lifecycle on iOS; brings `viewModelScope` baggage | CMP-first apps where iOS UI is also Compose |
+| **KMP-ObservableViewModel** (rickclephas) | `com.rickclephas.kmp:kmp-observableviewmodel-core` | First-class: SwiftUI observes directly, handles store-owner boilerplate | **Recommended** when iOS uses SwiftUI; this is the official Kotlin-docs recommendation |
+| **Pure Kotlin ViewModel** (your own `interface`/base) | none | Explicit Swift observer wrapper you write | Maximum control, zero androidx in commonMain |
+
+The official Kotlin documentation recommends **KMP-ObservableViewModel** for SwiftUI
+because there is no built-in `ViewModelStoreOwner` on iOS — the library ties the
+ViewModel lifecycle to the SwiftUI view automatically.
+
+---
+
+## Coding guidance
+
+### 1. Model UiState as a single immutable data class
+
+```kotlin
+// shared/commonMain/.../presentation/OrderUiState.kt
+data class OrderUiState(
+    val quantity: Int = 1,
+    val items: List<OrderItem> = emptyList(),
+    val isLoading: Boolean = false,
+    val errorMessage: String? = null,
+)
+```
+
+Rules:
+- One `UiState` per screen — never expose multiple loose `StateFlow`s for one screen
+- All fields `val`, with sensible defaults
+- Represent loading/error as fields (`isLoading`, `errorMessage`), or use a sealed
+  `UiState` if states are mutually exclusive enough to warrant it
+- Keep it free of framework types (no `Composable`, no `Color`, no `Painter`)
+
+### 2. ViewModel exposes StateFlow, never MutableStateFlow
+
+```kotlin
+// shared/commonMain/.../presentation/OrderViewModel.kt
+import com.rickclephas.kmp.observableviewmodel.ViewModel
+import com.rickclephas.kmp.observableviewmodel.MutableStateFlow
+import com.rickclephas.kmp.observableviewmodel.stateIn
+import com.rickclephas.kmp.nativecoroutines.NativeCoroutinesState
+
+class OrderViewModel(
+    private val placeOrder: PlaceOrderUseCase,
+    private val repository: OrderRepository,
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow(viewModelScope, OrderUiState())
+
+    @NativeCoroutinesState                       // exposes the flow cleanly to Swift
+    val uiState: StateFlow<OrderUiState> = _uiState.asStateFlow()
+
+    init { loadItems() }
+
+    fun setQuantity(n: Int) {
+        _uiState.update { it.copy(quantity = n) }
+    }
+
+    fun submit() {
+        viewModelScope.coroutineScope.launch {
+            _uiState.update { it.copy(isLoading = true, errorMessage = null) }
+            runCatching { placeOrder(_uiState.value.quantity) }
+                .onSuccess { _uiState.update { s -> s.copy(isLoading = false) } }
+                .onFailure { t -> _uiState.update { s -> s.copy(isLoading = false, errorMessage = t.message) } }
+        }
+    }
+
+    private fun loadItems() { /* launch in viewModelScope, update _uiState */ }
+}
+```
+
+Rules:
+- `_uiState` is private `MutableStateFlow`; expose read-only `StateFlow` via `asStateFlow()`
+- Always update via `update { copy(...) }` — atomic, avoids race conditions
+- Launch coroutines in `viewModelScope` so they cancel when the ViewModel clears
+- Annotate the public flow with `@NativeCoroutinesState` for clean Swift interop
+- Never expose `suspend` functions to the View; the View calls plain `fun`, the VM launches
+
+### 3. Compose Multiplatform View — state hoisting + lifecycle-aware collection
+
+```kotlin
+// composeApp/commonMain/.../OrderScreen.kt
+@Composable
+fun OrderScreen(viewModel: OrderViewModel = koinViewModel()) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+
+    OrderContent(
+        state = uiState,
+        onQuantityChange = viewModel::setQuantity,
+        onSubmit = viewModel::submit,
+    )
+}
+
+// Stateless, hoisted — fully previewable and testable
+@Composable
+private fun OrderContent(
+    state: OrderUiState,
+    onQuantityChange: (Int) -> Unit,
+    onSubmit: () -> Unit,
+) {
+    Column {
+        if (state.isLoading) LinearProgressIndicator()
+        QuantityStepper(state.quantity, onQuantityChange)
+        state.errorMessage?.let { Text(it, color = MaterialTheme.colorScheme.error) }
+        Button(onClick = onSubmit, enabled = !state.isLoading) { Text("Place order") }
+    }
+}
+```
+
+Rules:
+- Split into a stateful screen (`koinViewModel()` + collect) and a stateless content
+  composable that takes `state` + lambdas — this is **state hoisting**
+- Use `collectAsStateWithLifecycle()` (not bare `collectAsState()`) so collection pauses
+  when the UI is not visible
+- Pass method references (`viewModel::setQuantity`), not the whole ViewModel, into content
+- The stateless content composable has zero ViewModel dependency → trivially previewable
+
+### 4. Dependency injection with Koin
+
+```kotlin
+// shared/commonMain/.../di/OrderModule.kt
+val orderModule = module {
+    singleOf(::OrderRepositoryImpl) bind OrderRepository::class
+    factoryOf(::PlaceOrderUseCase)
+    viewModelOf(::OrderViewModel)        // koin-compose-viewmodel
+}
+```
+
+Compose retrieves it with `koinViewModel()` (from `koin-compose-viewmodel`), which
+scopes the ViewModel to the navigation entry / composition correctly on all platforms.
+
+### 5. iOS bridge (SwiftUI)
+
+With KMP-ObservableViewModel + `@NativeCoroutinesState`, SwiftUI observes directly:
+
+```swift
+struct OrderView: View {
+    @StateViewModel var viewModel = OrderViewModel(placeOrder: ..., repository: ...)
+
+    var body: some View {
+        VStack {
+            if viewModel.uiState.isLoading { ProgressView() }
+            Stepper("Qty: \(viewModel.uiState.quantity)",
+                    value: Binding(get: { Int(viewModel.uiState.quantity) },
+                                   set: { viewModel.setQuantity(n: Int32($0)) }))
+            Button("Place order") { viewModel.submit() }
+        }
+    }
+}
+```
+
+If you instead use AndroidX ViewModel + SKIE, SKIE maps `StateFlow` to a Swift
+`AsyncSequence`/`@Observable` and you bridge it with an observer wrapper.
+
+---
+
+## Project structure checklist
+
+```
+:shared
+  commonMain
+    └── feature/order/
+        ├── presentation/
+        │   ├── OrderUiState.kt          ✓ single immutable data class
+        │   └── OrderViewModel.kt        ✓ private Mutable, public StateFlow
+        ├── domain/
+        │   ├── OrderRepository.kt       ✓ interface
+        │   └── PlaceOrderUseCase.kt     ✓ pure logic, no androidx
+        ├── data/
+        │   └── OrderRepositoryImpl.kt   ✓ Ktor / SQLDelight
+        └── di/OrderModule.kt            ✓ viewModelOf(::OrderViewModel)
+
+:composeApp
+  commonMain
+    └── feature/order/OrderScreen.kt     ✓ stateful screen + stateless content
+
+iosApp                                   ✓ @StateViewModel, observes uiState
+```
+
+---
+
+## Testing guidance
+
+The ViewModel is a plain class — test it with `runTest` + Turbine, injecting fakes.
+
+```kotlin
+@Test
+fun `submit sets loading then clears on success`() = runTest {
+    val vm = OrderViewModel(
+        placeOrder = FakePlaceOrderUseCase(succeeds = true),
+        repository = FakeOrderRepository(),
+    )
+    vm.uiState.test {
+        assertEquals(OrderUiState(), awaitItem())           // initial
+        vm.setQuantity(3)
+        assertEquals(3, awaitItem().quantity)
+        vm.submit()
+        assertTrue(awaitItem().isLoading)                   // loading on
+        assertFalse(awaitItem().isLoading)                  // cleared after success
+    }
+}
+```
+
+The stateless content composable is tested separately with Compose UI tests / screenshot
+tests — it takes a `UiState` directly, so no ViewModel is needed.
+
+---
+
+## Gradle dependencies
+
+```kotlin
+// shared/build.gradle.kts
+kotlin {
+    sourceSets {
+        commonMain.dependencies {
+            // Recommended iOS-friendly ViewModel (official Kotlin docs)
+            implementation("com.rickclephas.kmp:kmp-observableviewmodel-core:1.0.0-BETA-13")
+            // OR the AndroidX multiplatform ViewModel
+            // implementation("org.jetbrains.androidx.lifecycle:lifecycle-viewmodel:2.8.4")
+
+            implementation("io.insert-koin:koin-core:4.0.0")
+            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
+        }
+        commonTest.dependencies {
+            implementation("app.cash.turbine:turbine:1.1.0")
+            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
+        }
+    }
+}
+
+// composeApp/build.gradle.kts
+commonMain.dependencies {
+    implementation("io.insert-koin:koin-compose-viewmodel:4.0.0")  // koinViewModel()
+    implementation("org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose:2.8.4")
+}
+```
+
+For SwiftUI interop, add the KMP-ObservableViewModel Swift package, or KMP-NativeCoroutines / SKIE.
+
+---
+
+## Anti-patterns to avoid
+
+| Anti-pattern | Fix |
+|---|---|
+| Exposing `MutableStateFlow` publicly | Expose read-only `StateFlow` via `asStateFlow()` |
+| Multiple loose `StateFlow`s for one screen | Combine into one `UiState` data class |
+| Business logic inside the `@Composable` | Move to the ViewModel; the View only renders + calls methods |
+| Passing the whole ViewModel into child composables | Hoist state: pass `UiState` + lambdas |
+| `collectAsState()` instead of `collectAsStateWithLifecycle()` | Use the lifecycle-aware variant to pause off-screen collection |
+| `suspend` functions exposed to the View | Keep them internal; the VM launches in `viewModelScope` |
+| Framework types (`Color`, `Painter`) inside `UiState` | Keep `UiState` platform-agnostic data only |
+| AndroidX ViewModel in commonMain when targeting SwiftUI | Prefer KMP-ObservableViewModel or a pure-Kotlin base |
+| Mutating state with `.value = .value.copy()` under concurrency | Use `update { copy(...) }` for atomic updates |