create-cmp-cli 0.8.0 → 0.10.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,27 @@ 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) {
+        // The jump half of the same seam: lets the debug inspector navigate by route
+        // (its navigate endpoint) so walkthrough coverage enumerates the graph instead of
+        // synthesizing taps. Registered/cleared with the controller's composition lifetime;
+        // NavController rejects unknown routes itself (IllegalArgumentException).
+        NavInspectionHook.navigator = { route -> navController.navigate(route) }
+        try {
+            navController.currentBackStack.collect { stack ->
+                NavInspectionHook.listener?.invoke(
+                    navController.currentDestination?.route,
+                    stack.mapNotNull { it.destination.route },
+                )
+            }
+        } finally {
+            NavInspectionHook.navigator = null
+        }
+    }
+
     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,31 @@
+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
+
+    /**
+     * The JUMP half of the seam: [AppNavHost] registers a function that navigates the real
+     * `NavController` to a route. Debug-only callers (the debug inspector's navigate endpoint) use it
+     * so a walkthrough can enumerate the nav graph mechanically — coverage by route-jump —
+     * instead of synthesizing taps with guessed settle times. Taps remain the tool for
+     * BEHAVIOUR proofs (a toggle, a search); this is for COVERAGE. `null` outside debug
+     * inspection, and must only ever be invoked on the main thread (NavController requirement).
+     */
+    var navigator: ((route: 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/commonMain/kotlin/com/example/app/presentation/theme/Typography.kt

@@ -5,6 +5,7 @@ import androidx.compose.runtime.Composable
 import androidx.compose.ui.text.TextStyle
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.TextUnit
 import androidx.compose.ui.unit.sp
 import org.jetbrains.compose.resources.Font
 import __PACKAGE__.generated.resources.DMSans_Bold
@@ -22,15 +23,78 @@ val DmSansFontFamily: FontFamily
         Font(Res.font.DMSans_Bold,     weight = FontWeight.Bold),
     )
 
+/**
+ * One rung of the ramp, as plain data. The ramp has to be readable WITHOUT a
+ * composition — the preview harness publishes it into `design-system.json`, and
+ * the studio console's Design language page renders the type ramp from that
+ * catalog. Holding the numbers here (rather than only inside the [Typography]
+ * factory below, which needs `@Composable` for the font family) is what keeps
+ * the published ramp and the rendered ramp the same numbers by construction.
+ *
+ * [tracking] is nullable on purpose: `null` means "leave letter spacing
+ * unspecified", which is NOT the same as `0.sp` — Compose resolves those
+ * differently, and flattening one into the other would silently retrack the
+ * mid-ramp styles.
+ */
+data class __THEME_PREFIX__TypeStyle(
+    val name: String,
+    val weight: Int,
+    val sizeSp: Int,
+    val lineHeightSp: Int,
+    val tracking: Float? = null,
+)
+
+/**
+ * A full ramp, not a minimal one. `display*` are the hero numerics (counts,
+ * totals, dashboard figures) — heavy and optically tightened; `headline`/`title`
+ * structure the screens; `label*` carries small ALL-CAPS eyebrows and metric
+ * units. Tight negative tracking on the big sizes is what makes a data-forward
+ * screen read as a considered product rather than a form — a thin ramp is the
+ * single cheapest tell of a scaffold.
+ */
+val __THEME_PREFIX__TypeRamp: List<__THEME_PREFIX__TypeStyle> = listOf(
+    __THEME_PREFIX__TypeStyle("displayLarge",   weight = 700, sizeSp = 56, lineHeightSp = 58, tracking = -1.5f),
+    __THEME_PREFIX__TypeStyle("displayMedium",  weight = 700, sizeSp = 44, lineHeightSp = 46, tracking = -1.0f),
+    __THEME_PREFIX__TypeStyle("displaySmall",   weight = 700, sizeSp = 32, lineHeightSp = 36, tracking = -0.5f),
+    __THEME_PREFIX__TypeStyle("headlineLarge",  weight = 700, sizeSp = 28, lineHeightSp = 32, tracking = -0.5f),
+    __THEME_PREFIX__TypeStyle("headlineMedium", weight = 600, sizeSp = 22, lineHeightSp = 28, tracking = -0.3f),
+    __THEME_PREFIX__TypeStyle("titleLarge",     weight = 600, sizeSp = 18, lineHeightSp = 24),
+    __THEME_PREFIX__TypeStyle("titleMedium",    weight = 600, sizeSp = 16, lineHeightSp = 22),
+    __THEME_PREFIX__TypeStyle("bodyLarge",      weight = 400, sizeSp = 16, lineHeightSp = 24),
+    __THEME_PREFIX__TypeStyle("bodyMedium",     weight = 400, sizeSp = 14, lineHeightSp = 20),
+    __THEME_PREFIX__TypeStyle("labelLarge",     weight = 600, sizeSp = 14, lineHeightSp = 18),
+    __THEME_PREFIX__TypeStyle("labelMedium",    weight = 500, sizeSp = 12, lineHeightSp = 16, tracking = 0.5f),
+    __THEME_PREFIX__TypeStyle("labelSmall",     weight = 600, sizeSp = 11, lineHeightSp = 14, tracking = 0.8f),
+)
+
+private fun ramp(name: String): __THEME_PREFIX__TypeStyle =
+    __THEME_PREFIX__TypeRamp.first { it.name == name }
+
 @Composable
 fun remember__THEME_PREFIX__Typography(): Typography {
     val dmSans = DmSansFontFamily
+    fun style(name: String): TextStyle {
+        val spec = ramp(name)
+        return TextStyle(
+            fontFamily = dmSans,
+            fontWeight = FontWeight(spec.weight),
+            fontSize = spec.sizeSp.sp,
+            lineHeight = spec.lineHeightSp.sp,
+            letterSpacing = spec.tracking?.sp ?: TextUnit.Unspecified,
+        )
+    }
     return Typography(
-        displayLarge   = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.Bold,     fontSize = 32.sp),
-        headlineMedium = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.SemiBold, fontSize = 24.sp),
-        titleMedium    = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.SemiBold, fontSize = 18.sp),
-        bodyLarge      = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.Normal,   fontSize = 16.sp),
-        bodyMedium     = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.Normal,   fontSize = 14.sp),
-        labelSmall     = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.Medium,   fontSize = 12.sp),
+        displayLarge   = style("displayLarge"),
+        displayMedium  = style("displayMedium"),
+        displaySmall   = style("displaySmall"),
+        headlineLarge  = style("headlineLarge"),
+        headlineMedium = style("headlineMedium"),
+        titleLarge     = style("titleLarge"),
+        titleMedium    = style("titleMedium"),
+        bodyLarge      = style("bodyLarge"),
+        bodyMedium     = style("bodyMedium"),
+        labelLarge     = style("labelLarge"),
+        labelMedium    = style("labelMedium"),
+        labelSmall     = style("labelSmall"),
     )
 }

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())
     }
 }