create-cmp-cli 0.8.0 → 0.9.0

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/Shimmer.kt

@@ -0,0 +1,90 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.RepeatMode
+import androidx.compose.animation.core.animateFloat
+import androidx.compose.animation.core.infiniteRepeatable
+import androidx.compose.animation.core.rememberInfiniteTransition
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.composed
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.unit.dp
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+
+/**
+ * A left-to-right shimmer sweep: an infinite transition driving a linear-gradient brush.
+ * Hand-rolled with zero dependencies — Accompanist's `placeholder` artifact is
+ * deprecated and Android-only, so no library option exists for this project's
+ * commonMain. Apply to any box that stands in for loading content.
+ */
+fun Modifier.shimmer(): Modifier = composed {
+    val transition = rememberInfiniteTransition(label = "shimmer")
+    val translateX by transition.animateFloat(
+        initialValue = -1000f,
+        targetValue = 1000f,
+        animationSpec = infiniteRepeatable(
+            animation = tween(durationMillis = 1200, easing = LinearEasing),
+            repeatMode = RepeatMode.Restart,
+        ),
+        label = "shimmerTranslate",
+    )
+    background(
+        Brush.linearGradient(
+            colors = listOf(
+                MaterialTheme.colorScheme.surfaceVariant,
+                MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.4f),
+                MaterialTheme.colorScheme.surfaceVariant,
+            ),
+            start = Offset(translateX, 0f),
+            end = Offset(translateX + 400f, 400f),
+        ),
+    )
+}
+
+/**
+ * A skeleton row matching [ListItemCard]'s geometry — same shape, elevation, and padding
+ * tokens — so the loaded list replaces it without a layout jump. Decorative and
+ * semantics-silent by design: the loading container (`ContentStateDefaults.ListSkeleton`)
+ * carries the `<screenTag>_loading` tag and the "Loading" `contentDescription`, so
+ * assistive tech announces one loading state, not a stack of anonymous bars.
+ */
+@Composable
+fun ListItemSkeleton(modifier: Modifier = Modifier) {
+    Surface(
+        color = MaterialTheme.colorScheme.surface,
+        shape = MaterialTheme.shapes.medium,
+        tonalElevation = __THEME_PREFIX__Tokens.ElevationCard,
+        modifier = modifier.fillMaxWidth(),
+    ) {
+        Column(Modifier.padding(__THEME_PREFIX__Tokens.PaddingCard)) {
+            Box(
+                Modifier
+                    .fillMaxWidth(0.6f)
+                    .height(16.dp)
+                    .clip(MaterialTheme.shapes.small)
+                    .shimmer(),
+            )
+            Box(
+                Modifier
+                    .padding(top = 8.dp)
+                    .fillMaxWidth(0.4f)
+                    .height(12.dp)
+                    .clip(MaterialTheme.shapes.small)
+                    .shimmer(),
+            )
+        }
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/TestTagAutomation.kt

@@ -4,15 +4,15 @@ import androidx.compose.ui.Modifier
 
 /**
  * Exposes every `Modifier.testTag` in the subtree to the platform's UI-automation layer,
- * so Appium/uiautomator id-selectors (and the cmp-test-generated suites) find them on a
- * stock build with no extra flags.
+ * so id-based E2E selectors (Maestro, Appium, XCUITest) find them on a stock build with
+ * no extra flags. Apply once at the root — `AppShell` does — and it covers the whole
+ * subtree.
  *
- * - Android actual: `semantics { testTagsAsResourceId = true }` → tags surface as
- *   `resource-id` in the uiautomator/Appium tree.
- * - iOS actual: same semantics flag → tags surface as `accessibilityIdentifier` (XCUITest).
- * - Desktop actual: no-op — the skiko `ui` artifact has no `testTagsAsResourceId`
- *   (there is no resource-id concept on desktop; tests use the Compose test APIs directly).
- *
- * Apply once at the root (AppShell does); it covers the whole subtree.
+ * Per-platform actuals:
+ * - Android: `semantics { testTagsAsResourceId = true }` — tags surface as `resource-id`
+ *   in the uiautomator tree.
+ * - iOS: the same semantics flag — tags surface as `accessibilityIdentifier` (XCUITest).
+ * - Desktop: no-op — no resource-id concept exists there; desktop tests use the Compose
+ *   test APIs directly.
  */
 expect fun Modifier.exposeTestTagsForAutomation(): Modifier

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

@@ -1,18 +1,11 @@
 package __PACKAGE__.presentation.home
 
-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.material3.TextButton
 import androidx.compose.runtime.Composable
-import androidx.compose.ui.Modifier
-import androidx.compose.ui.semantics.semantics
-import androidx.compose.ui.semantics.testTag
+import __PACKAGE__.presentation.components.AppHeader
 import __PACKAGE__.presentation.components.BaseScreen
-import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
-import __PACKAGE__.presentation.theme.designToken
+import __PACKAGE__.presentation.components.ScreenColumn
 
 @Composable
 fun DetailScreen(
@@ -20,25 +13,10 @@ fun DetailScreen(
     onBack: () -> Unit,
 ) {
     BaseScreen {
-        Column(
-            Modifier
-                .fillMaxSize()
-                .designToken(
-                    tokens = listOf("PaddingPage"),
-                    resolved = mapOf("padding" to "16dp"),
-                )
-                .padding(__THEME_PREFIX__Tokens.PaddingPage),
-        ) {
-            TextButton(onClick = onBack, modifier = Modifier.semantics { testTag = "detail_back" }) {
-                Text("← Back")
-            }
+        ScreenColumn(screenTag = "detail") {
+            AppHeader(title = "Detail", screenTag = "detail", onBack = onBack)
             Text(
-                "Detail",
-                style = MaterialTheme.typography.headlineMedium,
-                modifier = Modifier.semantics { testTag = "detail_title" },
-            )
-            Text(
-                "Item id: $itemId",
+                text = "Item id: $itemId",
                 style = MaterialTheme.typography.bodyLarge,
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
             )

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

@@ -1,28 +1,19 @@
 package __PACKAGE__.presentation.home
 
-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.fillMaxSize
-import androidx.compose.foundation.layout.fillMaxWidth
-import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.foundation.lazy.items
-import androidx.compose.material3.CircularProgressIndicator
-import androidx.compose.material3.MaterialTheme
-import androidx.compose.material3.Surface
-import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
-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 androidx.lifecycle.compose.collectAsStateWithLifecycle
+import __PACKAGE__.presentation.components.AppHeader
+import __PACKAGE__.presentation.components.ContentStateContainer
+import __PACKAGE__.presentation.components.ListItemCard
+import __PACKAGE__.presentation.components.ScreenColumn
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
-import __PACKAGE__.presentation.theme.designToken
 import org.koin.compose.viewmodel.koinViewModel
 
 @Composable
@@ -32,64 +23,17 @@ fun HomeScreen(
 ) {
     val state by viewModel.state.collectAsStateWithLifecycle()
 
-    Column(
-        Modifier
-            .fillMaxSize()
-            .designToken(
-                tokens = listOf("PaddingPage"),
-                resolved = mapOf("padding" to "16dp"),
-            )
-            .padding(__THEME_PREFIX__Tokens.PaddingPage),
-    ) {
-        Text(
-            text = "Home",
-            style = MaterialTheme.typography.headlineMedium,
-            modifier = Modifier.semantics { testTag = "home_title" }.padding(bottom = 12.dp),
-        )
-
-        val errorMessage = state.errorMessage
-        if (state.isLoading) {
-            Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
-                CircularProgressIndicator()
-            }
-        } else if (errorMessage != null) {
-            Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
-                Text(
-                    text = errorMessage,
-                    style = MaterialTheme.typography.bodyLarge,
-                    color = MaterialTheme.colorScheme.error,
-                    modifier = Modifier.semantics { testTag = "home_error" },
-                )
-            }
-        } else {
+    ScreenColumn(screenTag = "home") {
+        AppHeader(title = "Home", screenTag = "home")
+        ContentStateContainer(state = state, screenTag = "home", onRetry = viewModel::load) { items ->
             LazyColumn(verticalArrangement = Arrangement.spacedBy(__THEME_PREFIX__Tokens.GapCard)) {
-                items(state.items, key = { it.id }) { item ->
-                    Surface(
-                        color = MaterialTheme.colorScheme.surface,
-                        shape = MaterialTheme.shapes.medium,
-                        tonalElevation = __THEME_PREFIX__Tokens.ElevationCard,
-                        modifier = Modifier
-                            .fillMaxWidth()
-                            .designToken(
-                                tokens = listOf("RadiusCard", "ElevationCard", "PaddingCard"),
-                                resolved = mapOf(
-                                    "radius" to "16dp",
-                                    "elevation" to "2dp",
-                                    "padding" to "16dp",
-                                    "color" to "#FFFFFFFF",
-                                ),
-                            )
-                            .clickable { onItemClick(item.id) },
-                    ) {
-                        Column(Modifier.padding(__THEME_PREFIX__Tokens.PaddingCard)) {
-                            Text(item.title, style = MaterialTheme.typography.titleMedium)
-                            Text(
-                                item.subtitle,
-                                style = MaterialTheme.typography.bodyMedium,
-                                color = MaterialTheme.colorScheme.onSurfaceVariant,
-                            )
-                        }
-                    }
+                items(items, key = { it.id }) { item ->
+                    ListItemCard(
+                        title = item.title,
+                        subtitle = item.subtitle,
+                        onClick = { onItemClick(item.id) },
+                        modifier = Modifier.semantics { testTag = "home_item_${item.id}" },
+                    )
                 }
             }
         }

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") }
+        }
+    }
+}