create-cmp-cli 0.8.0 → 0.9.0

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

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/ComponentStories.kt

@@ -0,0 +1,269 @@
+package __PACKAGE__.inspector
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxScope
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ColumnScope
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Home
+import androidx.compose.material.icons.filled.Person
+import androidx.compose.material3.Icon
+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.components.AppBottomBar
+import __PACKAGE__.presentation.components.AppHeader
+import __PACKAGE__.presentation.components.AppPrimaryButton
+import __PACKAGE__.presentation.components.AppTextButton
+import __PACKAGE__.presentation.components.BaseScreen
+import __PACKAGE__.presentation.components.ContentStateContainer
+import __PACKAGE__.presentation.components.ContentStateDefaults
+import __PACKAGE__.presentation.components.ContentUiState
+import __PACKAGE__.presentation.components.EmptyState
+import __PACKAGE__.presentation.components.ErrorState
+import __PACKAGE__.presentation.components.ListItemCard
+import __PACKAGE__.presentation.components.ListItemSkeleton
+import __PACKAGE__.presentation.components.NavItem
+import __PACKAGE__.presentation.components.ScreenColumn
+import __PACKAGE__.presentation.navigation.AppTab
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+
+/**
+ * Component stories — one preview-registry entry per `@Composable` in
+ * `presentation/components` (the Storybook analog at component granularity).
+ * Each story renders the component in isolation on a plain tokened surface;
+ * a multi-variant component stacks its variants in ONE render. Ids follow
+ * `component.<kebab-case-of-composable-name>` (`AppHeader` →
+ * `component.app-header`), derivable mechanically from the name — the
+ * verify lane's `componentStories` step (qa/lib/component-stories.mjs)
+ * enforces exactly one story per component. The console excludes
+ * `component.*` entries from the Screens grid and shows each render at the
+ * top of that component's Components-page entry instead.
+ *
+ * These are preview-surface code (desktopMain), not production API: sample
+ * args only, tokens for every design value, testTags on every interactive
+ * node — a story meets the same bar the screens do.
+ */
+fun componentStories(): List<ScreenPreview> = listOf(
+    // Structure: the containers a screen roots itself in.
+    story("component.screen-column", "ScreenColumn") {
+        ScreenColumn(screenTag = "story") {
+            Text("ScreenColumn owns the tagged root and the PaddingPage inset.")
+            Text("Children stack vertically; scrollable = true adds scrolling.")
+        }
+    },
+    story("component.base-screen", "BaseScreen") {
+        BaseScreen { _ ->
+            Text(
+                "BaseScreen owns the status/navigation-bar insets; body content is safe with zero ceremony.",
+                modifier = Modifier.padding(__THEME_PREFIX__Tokens.PaddingPage),
+            )
+        }
+    },
+    // Header and navigation.
+    variantsStory("component.app-header", "AppHeader") {
+        AppHeader(title = "Screen title", screenTag = "story")
+        AppHeader(
+            title = "With back and action",
+            screenTag = "story_nav",
+            onBack = {},
+            actions = {
+                AppTextButton(
+                    text = "Action",
+                    onClick = {},
+                    modifier = Modifier.semantics { testTag = "story_header_action" },
+                )
+            },
+        )
+    },
+    story("component.app-bottom-bar", "AppBottomBar") {
+        AppBottomBar(
+            tabs = listOf(
+                AppTab("Home", Icons.Filled.Home) {},
+                AppTab("Profile", Icons.Filled.Person) {},
+            ),
+            selectedIndex = 0,
+            onSelect = {},
+            modifier = Modifier.align(Alignment.BottomCenter),
+        )
+    },
+    variantsStory("component.nav-item", "NavItem") {
+        NavItem(label = "Selected", selected = true, onClick = {}) {
+            Icon(
+                Icons.Filled.Home,
+                contentDescription = "Selected",
+                tint = __THEME_PREFIX__Colors.Primary,
+            )
+        }
+        NavItem(label = "Unselected", selected = false, onClick = {}) {
+            Icon(
+                Icons.Filled.Person,
+                contentDescription = "Unselected",
+                tint = __THEME_PREFIX__Colors.OnSurfaceVariant,
+            )
+        }
+    },
+    // Buttons.
+    variantsStory("component.app-primary-button", "AppPrimaryButton") {
+        AppPrimaryButton(
+            text = "Primary",
+            onClick = {},
+            modifier = Modifier.semantics { testTag = "story_primary" },
+        )
+        AppPrimaryButton(
+            text = "Primary — disabled",
+            onClick = {},
+            enabled = false,
+            modifier = Modifier.semantics { testTag = "story_primary_disabled" },
+        )
+    },
+    variantsStory("component.app-text-button", "AppTextButton") {
+        AppTextButton(
+            text = "Text button",
+            onClick = {},
+            modifier = Modifier.semantics { testTag = "story_text" },
+        )
+        AppTextButton(
+            text = "Text button — disabled",
+            onClick = {},
+            enabled = false,
+            modifier = Modifier.semantics { testTag = "story_text_disabled" },
+        )
+    },
+    // The four-state contract: all four arms of the container, stacked.
+    variantsStory("component.content-state-container", "ContentStateContainer") {
+        ContentStateContainer<List<String>>(
+            state = ContentUiState.Loading,
+            screenTag = "story_loading",
+            modifier = Modifier.height(180.dp),
+        ) { }
+        ContentStateContainer<List<String>>(
+            state = ContentUiState.Empty,
+            screenTag = "story_empty",
+            modifier = Modifier.height(180.dp),
+        ) { }
+        ContentStateContainer<List<String>>(
+            state = ContentUiState.Error("Something went wrong."),
+            screenTag = "story_error",
+            onRetry = {},
+            modifier = Modifier.height(180.dp),
+        ) { }
+        ContentStateContainer(
+            state = ContentUiState.Content(listOf("First item", "Second item")),
+            screenTag = "story_content",
+            modifier = Modifier.height(180.dp),
+        ) { data ->
+            Column(verticalArrangement = Arrangement.spacedBy(__THEME_PREFIX__Tokens.GapCard)) {
+                data.forEachIndexed { i, title ->
+                    ListItemCard(
+                        title = title,
+                        onClick = {},
+                        modifier = Modifier.semantics { testTag = "story_state_item_$i" },
+                    )
+                }
+            }
+        }
+    },
+    variantsStory("component.empty-state", "EmptyState") {
+        EmptyState(
+            screenTag = "story",
+            modifier = Modifier.height(220.dp),
+            body = "Items you add will show up here.",
+            action = {
+                AppTextButton(
+                    text = "Add an item",
+                    onClick = {},
+                    modifier = Modifier.semantics { testTag = "story_empty_action" },
+                )
+            },
+        )
+    },
+    variantsStory("component.error-state", "ErrorState") {
+        ErrorState(
+            message = "Something went wrong.",
+            screenTag = "story",
+            onRetry = {},
+            modifier = Modifier.height(220.dp),
+        )
+    },
+    // List vocabulary.
+    variantsStory("component.list-item-card", "ListItemCard") {
+        ListItemCard(
+            title = "Title only",
+            onClick = {},
+            modifier = Modifier.semantics { testTag = "story_item_1" },
+        )
+        ListItemCard(
+            title = "With subtitle",
+            subtitle = "Secondary line",
+            onClick = {},
+            modifier = Modifier.semantics { testTag = "story_item_2" },
+        )
+        ListItemCard(
+            title = "With a leading slot",
+            subtitle = "Leading content precedes the text column",
+            onClick = {},
+            modifier = Modifier.semantics { testTag = "story_item_3" },
+            leading = { Icon(Icons.Filled.Person, contentDescription = null) },
+        )
+    },
+    story("component.list-skeleton", "ContentStateDefaults.ListSkeleton") {
+        Box(Modifier.fillMaxSize().padding(__THEME_PREFIX__Tokens.PaddingPage)) {
+            ContentStateDefaults.ListSkeleton(screenTag = "story")
+        }
+    },
+    variantsStory("component.list-item-skeleton", "ListItemSkeleton") {
+        ListItemSkeleton()
+    },
+    story("component.spinner", "ContentStateDefaults.Spinner") {
+        ContentStateDefaults.Spinner(screenTag = "story")
+    },
+)
+
+/**
+ * `component.<kebab-name>` entry hosting [content] on the plain story surface.
+ * The id is passed as a full literal (never concatenated) so the lane's parity
+ * gate (qa/lib/component-stories.mjs) and a plain grep both find it.
+ */
+private fun story(
+    id: String,
+    title: String,
+    content: @Composable BoxScope.() -> Unit,
+): ScreenPreview = ScreenPreview(id, "$title — component story") {
+    StoryHost(content)
+}
+
+/** Stacked-variants flavor: the story surface with a padded, token-gapped column. */
+private fun variantsStory(
+    id: String,
+    title: String,
+    content: @Composable ColumnScope.() -> Unit,
+): ScreenPreview = story(id, title) {
+    Column(
+        modifier = Modifier.fillMaxSize().padding(__THEME_PREFIX__Tokens.PaddingPage),
+        verticalArrangement = Arrangement.spacedBy(__THEME_PREFIX__Tokens.GapCard),
+        content = content,
+    )
+}
+
+/**
+ * The plain tokened surface every story renders on: theme background, nothing
+ * else — the component is the only subject. Internal (not private) so the
+ * generated registry can host the PlaceholderScreen story on custom-tab
+ * scaffolds (PlaceholderScreen ships only when a configured tab has no
+ * feature yet, so its story rides PreviewRegistry.kt, not this file).
+ */
+@Composable
+internal fun StoryHost(content: @Composable BoxScope.() -> Unit) {
+    Box(Modifier.fillMaxSize().background(__THEME_PREFIX__Colors.Background)) { content() }
+}

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewRegistry.kt

@@ -4,12 +4,19 @@ import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Modifier
+import __PACKAGE__.domain.model.DomainError
+import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.repository.ItemRepository
+import __PACKAGE__.domain.result.AppResult
+import __PACKAGE__.domain.usecase.GetItemsUseCase
 import __PACKAGE__.presentation.components.BaseScreen
 import __PACKAGE__.presentation.home.DetailScreen
 import __PACKAGE__.presentation.home.HomeScreen
+import __PACKAGE__.presentation.home.HomeViewModel
 import __PACKAGE__.presentation.navigation.AppShell
 import __PACKAGE__.presentation.navigation.appTabs
 import __PACKAGE__.presentation.profile.ProfileScreen
+import kotlinx.coroutines.awaitCancellation
 
 /**
  * One previewable screen: a stable [id] (the `-Pscreen=` selector and output directory
@@ -29,6 +36,11 @@ import __PACKAGE__.presentation.profile.ProfileScreen
  * preview-only fakes behind its usual parameters). Every entry renders the same way
  * (gallery card, `-Pscreen=` selector, golden baseline), so loading/empty/error states
  * sit side by side with the default seeded state.
+ *
+ * Component stories (`component.<kebab-name>` ids, ComponentStories.kt) are appended
+ * below — one isolated render per `presentation/components` composable. The console
+ * keeps them out of the Screens grid and shows each at the top of its Components-page
+ * entry; the verify lane's `componentStories` step enforces one story per component.
  */
 data class ScreenPreview(
     val id: String,
@@ -49,8 +61,21 @@ fun previewRegistry(): List<ScreenPreview> = listOf(
     ScreenPreview("home", "Home tab") { TabHost { HomeScreen(onItemClick = {}) } },
     ScreenPreview("profile", "Profile tab") { TabHost { ProfileScreen() } },
     ScreenPreview("detail", "Detail (nav destination)") { DetailScreen(itemId = "1", onBack = {}) },
+    // State variants (§6.5, component-system-deep-dive.md): the same ContentUiState arms
+    // ContentStateContainer dispatches on, forced via a preview-only repository — the
+    // console's genesis workbench and the golden baselines get loading/empty/error as
+    // first-class screens beside the default seeded "home" entry.
+    ScreenPreview("home@loading", "Home — loading") {
+        TabHost { HomeScreen(onItemClick = {}, viewModel = previewHomeViewModel { awaitCancellation() }) }
+    },
+    ScreenPreview("home@empty", "Home — empty") {
+        TabHost { HomeScreen(onItemClick = {}, viewModel = previewHomeViewModel { AppResult.Success(emptyList()) }) }
+    },
+    ScreenPreview("home@error", "Home — error") {
+        TabHost { HomeScreen(onItemClick = {}, viewModel = previewHomeViewModel { AppResult.Failure(DomainError.Network) }) }
+    },
     // cmp:anchor preview-registry
-)
+) + componentStories()
 
 /**
  * Hosts a single tab's content the way [AppShell] does — inside [BaseScreen] — minus the
@@ -62,3 +87,14 @@ private fun TabHost(content: @Composable () -> Unit) {
         Box(Modifier.fillMaxSize()) { content() }
     }
 }
+
+/**
+ * Forces one `ContentUiState` arm on a real [HomeViewModel] for the state-variant previews
+ * above. `desktopMain` cannot depend on `commonTest`'s `FakeItemRepository` (test sources
+ * never leak into main), so this is a minimal, self-contained equivalent — the real
+ * ViewModel and screen render unmodified, only the repository result is forced.
+ */
+private fun previewHomeViewModel(result: suspend () -> AppResult<List<Item>>): HomeViewModel =
+    HomeViewModel(GetItemsUseCase(object : ItemRepository {
+        override suspend fun getItems(): AppResult<List<Item>> = result()
+    }))