create-cmp-cli 0.7.1 → 0.9.0

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/home/HomeViewModel.kt

@@ -2,25 +2,35 @@ package __PACKAGE__.presentation.home
 
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
+import __PACKAGE__.domain.model.DomainError
 import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.result.AppResult
 import __PACKAGE__.domain.usecase.GetItemsUseCase
+import __PACKAGE__.presentation.components.ContentUiState
+import __PACKAGE__.presentation.components.toContentState
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.launch
 
-data class HomeUiState(
-    val isLoading: Boolean = true,
-    val items: List<Item> = emptyList(),
-    val errorMessage: String? = null,
-)
-
+/**
+ * No `try`/`catch` here — ever (ARCH-07). Failures arrive as typed [AppResult.Failure]
+ * values from the use case; the ViewModel folds over the result and maps [DomainError]
+ * KINDS to user-facing copy. A `CancellationException` thrown while suspended simply
+ * cancels this coroutine (structured concurrency) — it never becomes an error state.
+ *
+ * The state machine is the shared [ContentUiState] (`presentation/components`) — the
+ * generalization of this feature's pre-generalization per-feature sealed state (which
+ * EH-1 landed): same four arms (Loading/Content/Empty/Error), same fold, made generic once
+ * so `ContentStateContainer` can own the non-content arms' rendering instead of every
+ * screen hand-folding its own copy.
+ */
 class HomeViewModel(
     private val getItems: GetItemsUseCase,
 ) : ViewModel() {
 
-    private val _state = MutableStateFlow(HomeUiState())
-    val state: StateFlow<HomeUiState> = _state.asStateFlow()
+    private val _state = MutableStateFlow<ContentUiState<List<Item>>>(ContentUiState.Loading)
+    val state: StateFlow<ContentUiState<List<Item>>> = _state.asStateFlow()
 
     init {
         load()
@@ -28,12 +38,22 @@ class HomeViewModel(
 
     fun load() {
         viewModelScope.launch {
-            _state.value = HomeUiState(isLoading = true)
-            _state.value = try {
-                HomeUiState(isLoading = false, items = getItems())
-            } catch (e: Exception) {
-                HomeUiState(isLoading = false, errorMessage = e.message ?: "Something went wrong")
+            _state.value = ContentUiState.Loading
+            _state.value = when (val result = getItems()) {
+                is AppResult.Success -> result.value.toContentState()
+                is AppResult.Failure -> ContentUiState.Error(result.error.toUserMessage())
             }
         }
     }
 }
+
+/**
+ * Presentation owns user-facing copy: error KINDS become strings here, next to the screen
+ * that shows them. A raw `Throwable.message` never reaches the UI — the domain carries no
+ * display text at all.
+ */
+internal fun DomainError.toUserMessage(): String = when (this) {
+    DomainError.Network -> "Can't reach the server. Check your connection and try again."
+    DomainError.NotFound -> "That content isn't available."
+    is DomainError.Unexpected -> "Something went wrong. Please try again."
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppNavHost.kt

@@ -1,6 +1,7 @@
 package __PACKAGE__.presentation.navigation
 
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.navigation.NavType
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
@@ -16,6 +17,18 @@ import __PACKAGE__.presentation.profile.ProfileScreen
 fun AppNavHost() {
     val navController = rememberNavController()
 
+    // Report every back-stack change to the common inspection seam — a no-op unless the
+    // androidDebug inspector registered a listener (see NavInspectionHook.kt). Best-effort:
+    // `currentBackStack` is a live snapshot, not a durable history.
+    LaunchedEffect(navController) {
+        navController.currentBackStack.collect { stack ->
+            NavInspectionHook.listener?.invoke(
+                navController.currentDestination?.route,
+                stack.mapNotNull { it.destination.route },
+            )
+        }
+    }
+
     NavHost(navController = navController, startDestination = Screen.Shell.route) {
         composable(Screen.Shell.route) {
             val tabs = appTabs(

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppShell.kt

@@ -1,44 +1,26 @@
 package __PACKAGE__.presentation.navigation
 
-import androidx.compose.foundation.background
-import androidx.compose.foundation.clickable
-import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
-import androidx.compose.foundation.layout.Column
-import androidx.compose.foundation.layout.Row
-import androidx.compose.foundation.layout.defaultMinSize
 import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.fillMaxWidth
-import androidx.compose.foundation.layout.height
-import androidx.compose.foundation.layout.navigationBarsPadding
-import androidx.compose.foundation.layout.padding
-import androidx.compose.foundation.layout.size
-import androidx.compose.foundation.shape.RoundedCornerShape
-import androidx.compose.material3.Icon
-import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.saveable.rememberSaveable
 import androidx.compose.runtime.setValue
-import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
-import androidx.compose.ui.draw.clip
-import androidx.compose.ui.semantics.semantics
-import androidx.compose.ui.semantics.testTag
-import androidx.compose.ui.text.font.FontWeight
-import androidx.compose.ui.unit.dp
-import androidx.compose.ui.unit.sp
+import __PACKAGE__.presentation.components.AppBottomBar
 import __PACKAGE__.presentation.components.BaseScreen
 import __PACKAGE__.presentation.components.exposeTestTagsForAutomation
-import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
-import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
-import __PACKAGE__.presentation.theme.designToken
 
 /**
  * Generic bottom-nav shell. Parameterized by a [tabs] list — NOT role-hardcoded.
  * Hosts the selected tab's content inside a [BaseScreen] so each tab gets correct insets;
  * the bottom bar reserves the navigation-bar inset exactly once.
+ *
+ * The bar itself is [__PACKAGE__.presentation.components.AppBottomBar] — promoted out of
+ * this file into the governed component registry (§4.3 of the component-vocabulary
+ * proposal): it was already a mature component, just invisible to the registry as a
+ * `private` composable here.
  */
 @Composable
 fun AppShell(tabs: List<AppTab>) {
@@ -52,7 +34,7 @@ fun AppShell(tabs: List<AppTab>) {
         // The bottom bar owns the navigation-bar inset; the body must not also pad it.
         applyNavBarPadding = false,
         bottomBar = {
-            AppBottomNav(
+            AppBottomBar(
                 tabs = tabs,
                 selectedIndex = selected,
                 onSelect = { selected = it },
@@ -64,87 +46,3 @@ fun AppShell(tabs: List<AppTab>) {
         }
     }
 }
-
-@Composable
-private fun AppBottomNav(
-    tabs: List<AppTab>,
-    selectedIndex: Int,
-    onSelect: (Int) -> Unit,
-) {
-    Column(Modifier.fillMaxWidth()) {
-        Box(
-            Modifier
-                .fillMaxWidth()
-                .height(1.dp)
-                .background(__THEME_PREFIX__Colors.OutlineVariant)
-        )
-        Row(
-            modifier = Modifier
-                .fillMaxWidth()
-                .background(__THEME_PREFIX__Colors.Surface)
-                // Lift tabs above the gesture pill / 3-button nav (maps to iOS safe area).
-                .navigationBarsPadding()
-                .height(__THEME_PREFIX__Tokens.BottomNavHeight)
-                // Inspector: the bottom-nav container self-reports its height token.
-                .designToken(
-                    tokens = listOf("BottomNavHeight"),
-                    resolved = mapOf("height" to "72dp"),
-                )
-                .semantics { testTag = "app_bottom_nav" }
-                .padding(bottom = 8.dp),
-            verticalAlignment = Alignment.CenterVertically,
-            horizontalArrangement = Arrangement.SpaceEvenly,
-        ) {
-            tabs.forEachIndexed { index, tab ->
-                NavItem(
-                    label = tab.label,
-                    selected = selectedIndex == index,
-                    onClick = { onSelect(index) },
-                ) {
-                    Icon(
-                        imageVector = tab.icon,
-                        contentDescription = tab.label,
-                        tint = if (selectedIndex == index) __THEME_PREFIX__Colors.Primary
-                               else __THEME_PREFIX__Colors.OnSurfaceVariant.copy(alpha = 0.55f),
-                        modifier = Modifier.size(24.dp),
-                    )
-                }
-            }
-        }
-    }
-}
-
-/** Deterministic automation tag for a nav item: `nav_` + the label lowercased with every non-[a-z0-9] run collapsed to `_` and trimmed (e.g. "My Stuff!" → `nav_my_stuff`). Must mirror `navSlug` in create-cmp's engine (src/lib/tabs.mjs), which generates `qa/e2e/smoke.yaml`'s id selectors from the configured tabs — keep the two in sync. */
-private fun navItemTag(label: String): String =
-    "nav_" + label.lowercase().replace(Regex("[^a-z0-9]+"), "_").trim('_')
-
-@Composable
-private fun NavItem(
-    label: String,
-    selected: Boolean,
-    onClick: () -> Unit,
-    icon: @Composable () -> Unit,
-) {
-    Column(
-        modifier = Modifier
-            .clip(RoundedCornerShape(8.dp))
-            .clickable(onClick = onClick)
-            // a11y: guarantee the 48dp minimum touch target regardless of label width
-            // (the inspector's audit_a11y flags anything smaller).
-            .defaultMinSize(minWidth = 48.dp, minHeight = 48.dp)
-            // Durable selection handle (tests/E2E select by testTag, never display text).
-            .semantics { testTag = navItemTag(label) }
-            .padding(horizontal = 8.dp, vertical = 4.dp),
-        horizontalAlignment = Alignment.CenterHorizontally,
-        verticalArrangement = Arrangement.Center,
-    ) {
-        icon()
-        Text(
-            text = label,
-            fontSize = 10.sp,
-            fontWeight = if (selected) FontWeight.Bold else FontWeight.SemiBold,
-            color = if (selected) __THEME_PREFIX__Colors.Primary else __THEME_PREFIX__Colors.OnSurfaceVariant,
-            modifier = Modifier.padding(top = 4.dp),
-        )
-    }
-}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/NavInspectionHook.kt

@@ -0,0 +1,21 @@
+package __PACKAGE__.presentation.navigation
+
+/**
+ * A tiny common seam [AppNavHost] reports every navigation change to. [listener] is `null` by
+ * default — a structural no-op — and is registered only by the optional debug-only on-device
+ * inspector, when that feature is included in the project. Release builds never register a
+ * listener, so invoking a `null` one stays free.
+ *
+ * This indirection is the whole point: `AppNavHost` lives in commonMain and must never
+ * reference a debug-only class directly (a debug-only source set may not even exist in every
+ * build of this project) — it only ever talks to this common object.
+ */
+object NavInspectionHook {
+    /**
+     * Invoked on every back-stack change with `currentRoute` (nullable — no destination
+     * resolved yet) and `backStack` (root-to-top, best-effort: derived from
+     * `NavController.currentBackStack`, which is itself a live/soon-to-be-live snapshot, not a
+     * durable history).
+     */
+    var listener: ((currentRoute: String?, backStack: List<String>) -> Unit)? = null
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/profile/ProfileScreen.kt

@@ -1,39 +1,16 @@
 package __PACKAGE__.presentation.profile
 
-import androidx.compose.foundation.layout.Arrangement
-import androidx.compose.foundation.layout.Column
-import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.padding
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
-import androidx.compose.ui.Alignment
-import androidx.compose.ui.Modifier
-import androidx.compose.ui.semantics.semantics
-import androidx.compose.ui.semantics.testTag
-import androidx.compose.ui.unit.dp
-import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
-import __PACKAGE__.presentation.theme.designToken
+import __PACKAGE__.presentation.components.AppHeader
+import __PACKAGE__.presentation.components.ScreenColumn
 
 // Feature stub. Copy the `home` feature's data→domain→presentation→DI wiring to flesh this out.
 @Composable
 fun ProfileScreen() {
-    Column(
-        modifier = Modifier
-            .fillMaxSize()
-            .designToken(
-                tokens = listOf("PaddingPage"),
-                resolved = mapOf("padding" to "16dp"),
-            )
-            .padding(__THEME_PREFIX__Tokens.PaddingPage),
-        verticalArrangement = Arrangement.spacedBy(8.dp),
-        horizontalAlignment = Alignment.Start,
-    ) {
-        Text(
-            text = "Profile",
-            style = MaterialTheme.typography.headlineMedium,
-            modifier = Modifier.semantics { testTag = "profile_title" },
-        )
+    ScreenColumn(screenTag = "profile") {
+        AppHeader(title = "Profile", screenTag = "profile")
         Text(
             text = "This is a stub screen. Wire it up like the Home feature.",
             style = MaterialTheme.typography.bodyMedium,

package/template/composeApp/src/commonTest/kotlin/com/example/app/data/AppResultCatchingTest.kt

@@ -0,0 +1,52 @@
+package __PACKAGE__.data
+
+import __PACKAGE__.domain.model.DomainError
+import __PACKAGE__.domain.result.AppResult
+import kotlin.coroutines.cancellation.CancellationException
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlin.test.assertIs
+import kotlinx.coroutines.test.runTest
+
+/**
+ * The exception-translation helper's contract (`specs/app-base.spec.md` ARCH-08):
+ * success wraps, failures map to typed kinds, and cancellation ALWAYS propagates.
+ */
+class AppResultCatchingTest {
+
+    @Test
+    fun `wraps the block's value in Success`() = runTest {
+        val result = suspendRunCatching { 42 }
+
+        assertEquals(AppResult.Success(42), result)
+    }
+
+    @Test
+    fun `maps a thrown exception through mapError to a typed Failure`() = runTest {
+        val boom = IllegalStateException("io broke")
+
+        val result = suspendRunCatching(mapError = { DomainError.Network }) { throw boom }
+
+        assertEquals(AppResult.Failure(DomainError.Network), result)
+    }
+
+    @Test
+    fun `files unclassified exceptions under Unexpected with the cause preserved`() = runTest {
+        val boom = IllegalStateException("io broke")
+
+        val result = suspendRunCatching { throw boom }
+
+        val failure = assertIs<AppResult.Failure>(result)
+        val error = assertIs<DomainError.Unexpected>(failure.error)
+        assertEquals(boom, error.cause)
+    }
+
+    // SPEC: ARCH-08
+    @Test
+    fun `rethrows CancellationException instead of mapping it`() = runTest {
+        assertFailsWith<CancellationException> {
+            suspendRunCatching { throw CancellationException("scope cancelled") }
+        }
+    }
+}

package/template/composeApp/src/commonTest/kotlin/com/example/app/data/remote/ItemRepositoryImplTest.kt

@@ -1,26 +1,51 @@
 package __PACKAGE__.data.remote
 
+import __PACKAGE__.domain.result.AppResult
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertNull
 import kotlin.test.assertTrue
+import kotlin.test.fail
+import kotlinx.coroutines.launch
 import kotlinx.coroutines.test.runTest
 
 /**
  * The exemplar data-layer test. [ItemRepositoryImpl] is the template's dependency-light
  * example source; when you swap it for a real Firestore/Ktor + Room implementation, keep
- * this shape: test the repository through its DOMAIN contract, under `runTest` virtual
- * time (the simulated I/O delay costs nothing here — delays are skipped, not slept).
+ * this shape: test the repository through its DOMAIN contract (AppResult in, never an
+ * exception out), under `runTest` virtual time (the simulated I/O delay costs nothing
+ * here — delays are skipped, not slept).
  */
 class ItemRepositoryImplTest {
 
     private val repository = ItemRepositoryImpl()
 
     @Test
-    fun `returns the seeded example items`() = runTest {
-        val items = repository.getItems()
+    fun `returns the seeded example items as Success`() = runTest {
+        val items = when (val result = repository.getItems()) {
+            is AppResult.Success -> result.value
+            is AppResult.Failure -> fail("example source should succeed, got $result")
+        }
 
         assertTrue(items.isNotEmpty(), "example source should seed items")
         assertEquals(items.size, items.map { it.id }.toSet().size, "item ids must be unique")
         assertTrue(items.all { it.title.isNotBlank() }, "every item needs a title")
     }
+
+    // SPEC: ARCH-08
+    @Test
+    fun `cancellation propagates - a cancelled load never completes as a Failure`() = runTest {
+        // A REAL cancellation: getItems() is suspended in its simulated I/O when the caller's
+        // job is cancelled. suspendRunCatching must rethrow the CancellationException — if it
+        // mapped it, `result` would hold a Failure and this test would fail.
+        var result: Any? = null
+        val job = launch { result = repository.getItems() }
+        testScheduler.runCurrent() // enter getItems() up to the suspension point
+
+        job.cancel()
+        job.join()
+
+        assertTrue(job.isCancelled, "the load job should end cancelled, not completed")
+        assertNull(result, "a cancelled load must produce NO result — especially not a Failure")
+    }
 }

package/template/composeApp/src/commonTest/kotlin/com/example/app/domain/usecase/GetItemsUseCaseTest.kt

@@ -1,15 +1,17 @@
 package __PACKAGE__.domain.usecase
 
+import __PACKAGE__.domain.model.DomainError
 import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.result.AppResult
 import __PACKAGE__.testing.fakes.FakeItemRepository
 import kotlin.test.Test
 import kotlin.test.assertEquals
-import kotlin.test.assertFailsWith
 import kotlinx.coroutines.test.runTest
 
 /**
  * The exemplar use-case test. Use cases are pure business actions with no framework
  * dependencies, so their tests are the simplest in the pyramid: fake in, behavior out.
+ * Results stay typed end-to-end — nothing here throws or catches.
  */
 class GetItemsUseCaseTest {
 
@@ -17,21 +19,21 @@ class GetItemsUseCaseTest {
     private val getItems = GetItemsUseCase(repository)
 
     @Test
-    fun `returns the repository's items`() = runTest {
+    fun `returns the repository's items as Success`() = runTest {
         val expected = listOf(
             Item(id = "1", title = "First", subtitle = "a"),
             Item(id = "2", title = "Second", subtitle = "b"),
         )
         repository.items = expected
 
-        assertEquals(expected, getItems())
+        assertEquals(AppResult.Success(expected), getItems())
         assertEquals(1, repository.getItemsCallCount)
     }
 
     @Test
-    fun `propagates repository failures to the caller`() = runTest {
-        repository.shouldFail = true
+    fun `passes a typed failure through untouched`() = runTest {
+        repository.failure = DomainError.Network
 
-        assertFailsWith<IllegalStateException> { getItems() }
+        assertEquals(AppResult.Failure(DomainError.Network), getItems())
     }
 }

package/template/composeApp/src/commonTest/kotlin/com/example/app/presentation/home/HomeViewModelTest.kt

@@ -1,16 +1,16 @@
 package __PACKAGE__.presentation.home
 
 import app.cash.turbine.test
+import __PACKAGE__.domain.model.DomainError
 import __PACKAGE__.domain.model.Item
 import __PACKAGE__.domain.usecase.GetItemsUseCase
+import __PACKAGE__.presentation.components.ContentUiState
 import __PACKAGE__.testing.fakes.FakeItemRepository
 import kotlin.test.AfterTest
 import kotlin.test.BeforeTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
-import kotlin.test.assertNotNull
-import kotlin.test.assertNull
-import kotlin.test.assertTrue
+import kotlin.test.assertIs
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.test.StandardTestDispatcher
@@ -25,6 +25,10 @@ import kotlinx.coroutines.test.setMain
  *    so coroutines run under the test scheduler's virtual time.
  *  - Turbine (`state.test { … }`) for StateFlow assertions.
  *  - Hand-written fakes from `testing/fakes` — never mocks.
+ *  - Sealed-state assertions: each emission IS one state (`assertEquals` on the state,
+ *    `assertIs` on the branch) — no boolean-flag poking. The state type is the shared
+ *    [ContentUiState] (the generalization of this feature's pre-generalization per-feature
+ *    sealed state).
  */
 @OptIn(ExperimentalCoroutinesApi::class)
 class HomeViewModelTest {
@@ -47,58 +51,66 @@ class HomeViewModelTest {
     // SPEC: HOME-01
     @Test
     fun `starts in loading state`() = runTest(dispatcher) {
+        repository.items = listOf(Item(id = "1", title = "First", subtitle = "sub"))
+
         viewModel().state.test {
-            assertTrue(awaitItem().isLoading, "initial state should be loading")
+            assertEquals(ContentUiState.Loading, awaitItem(), "initial state should be Loading")
         }
     }
 
+    // SPEC: HOME-02
     @Test
-    fun `emits items when repository succeeds`() = runTest(dispatcher) {
-        repository.items = listOf(Item(id = "1", title = "First", subtitle = "sub"))
+    fun `emits Content when the repository returns items`() = runTest(dispatcher) {
+        val items = listOf(Item(id = "1", title = "First", subtitle = "sub"))
+        repository.items = items
 
         viewModel().state.test {
-            assertTrue(awaitItem().isLoading)
+            assertEquals(ContentUiState.Loading, awaitItem())
+            assertEquals(ContentUiState.Content(items), awaitItem())
+        }
+    }
+
+    // SPEC: HOME-07
+    @Test
+    fun `emits Empty when the repository succeeds with no items`() = runTest(dispatcher) {
+        repository.items = emptyList()
 
-            val loaded = awaitItem()
-            assertEquals(false, loaded.isLoading)
-            assertEquals(listOf("First"), loaded.items.map { it.title })
-            assertNull(loaded.errorMessage)
+        viewModel().state.test {
+            assertEquals(ContentUiState.Loading, awaitItem())
+            assertEquals(ContentUiState.Empty, awaitItem())
         }
     }
 
+    // SPEC: HOME-03
     @Test
-    fun `emits error message when repository fails`() = runTest(dispatcher) {
-        repository.shouldFail = true
-        repository.failureMessage = "network down"
+    fun `maps a typed failure to presentation copy - never a raw exception message`() = runTest(dispatcher) {
+        repository.failure = DomainError.Network
 
         viewModel().state.test {
-            assertTrue(awaitItem().isLoading)
+            assertEquals(ContentUiState.Loading, awaitItem())
 
-            val failed = awaitItem()
-            assertEquals(false, failed.isLoading)
-            assertTrue(failed.items.isEmpty())
-            assertEquals("network down", failed.errorMessage)
+            val failed = assertIs<ContentUiState.Error>(awaitItem())
+            assertEquals(DomainError.Network.toUserMessage(), failed.message)
         }
     }
 
     // SPEC: HOME-04
     @Test
     fun `reload after failure clears the error and loads items`() = runTest(dispatcher) {
-        repository.shouldFail = true
+        repository.failure = DomainError.Network
         val viewModel = viewModel()
 
         viewModel.state.test {
-            assertTrue(awaitItem().isLoading)
-            assertNotNull(awaitItem().errorMessage, "first load should fail")
+            assertEquals(ContentUiState.Loading, awaitItem())
+            assertIs<ContentUiState.Error>(awaitItem(), "first load should fail")
 
-            repository.shouldFail = false
+            repository.failure = null
             repository.items = listOf(Item(id = "1", title = "Recovered", subtitle = "sub"))
             viewModel.load()
 
-            assertTrue(awaitItem().isLoading, "reload should show loading again")
-            val recovered = awaitItem()
-            assertNull(recovered.errorMessage)
-            assertEquals(listOf("Recovered"), recovered.items.map { it.title })
+            assertEquals(ContentUiState.Loading, awaitItem(), "reload should show loading again")
+            val recovered = assertIs<ContentUiState.Content<List<Item>>>(awaitItem())
+            assertEquals(listOf("Recovered"), recovered.data.map { it.title })
         }
     }
 }

package/template/composeApp/src/commonTest/kotlin/com/example/app/testing/fakes/FakeItemRepository.kt

@@ -1,29 +1,33 @@
 package __PACKAGE__.testing.fakes
 
+import __PACKAGE__.domain.model.DomainError
 import __PACKAGE__.domain.model.Item
 import __PACKAGE__.domain.repository.ItemRepository
+import __PACKAGE__.domain.result.AppResult
 
 /**
  * Hand-written fake — the template's testing convention (no mocking frameworks: they are
  * JVM-only in KMP, and interface-driven fakes keep the architecture honest).
  *
  * The pattern every fake follows:
- *  - configurable behavior (`items`, `shouldFail`) so a test arranges its scenario,
+ *  - configurable behavior (`items`, `failure`) so a test arranges its scenario,
  *  - recorded interactions (`getItemsCallCount`) so a test can assert usage,
  *  - implements the DOMAIN interface, never a concrete data source.
+ *
+ * Failures are arranged as typed [DomainError] KINDS, mirroring the real contract — the
+ * fake returns [AppResult.Failure]; it never throws (repositories don't, per ARCH-06).
  */
 class FakeItemRepository : ItemRepository {
 
     var items: List<Item> = emptyList()
-    var shouldFail: Boolean = false
-    var failureMessage: String = "fake failure"
+    var failure: DomainError? = null
 
     var getItemsCallCount: Int = 0
         private set
 
-    override suspend fun getItems(): List<Item> {
+    override suspend fun getItems(): AppResult<List<Item>> {
         getItemsCallCount++
-        if (shouldFail) throw IllegalStateException(failureMessage)
-        return items
+        failure?.let { return AppResult.Failure(it) }
+        return AppResult.Success(items)
     }
 }