create-cmp-cli 0.8.0 → 0.10.0

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,300 @@
+package __PACKAGE__.inspector
+
+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.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.filled.Home
+import androidx.compose.material.icons.filled.Person
+import androidx.compose.material3.Icon
+import androidx.compose.material3.Surface
+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.AppIconButton
+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" },
+        )
+    },
+    variantsStory("component.app-icon-button", "AppIconButton") {
+        AppIconButton(
+            icon = Icons.AutoMirrored.Filled.ArrowBack,
+            contentDescription = "Back",
+            onClick = {},
+            modifier = Modifier.semantics { testTag = "story_icon_button" },
+        )
+        AppIconButton(
+            icon = Icons.AutoMirrored.Filled.ArrowBack,
+            contentDescription = "Back — disabled",
+            onClick = {},
+            enabled = false,
+            modifier = Modifier.semantics { testTag = "story_icon_button_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).
+ *
+ * A `Surface`, not a bare `Box`: real screens root in [BaseScreen]'s `Scaffold`, which
+ * provides `LocalContentColor` to everything below it. A Box only PAINTS a background —
+ * it supplies no content color — so any component that correctly inherits one (an
+ * [AppIconButton] tint, a bare `Text`) fell back to `LocalContentColor`'s black default
+ * and rendered black-on-near-black. The story read as an empty rectangle while the
+ * component was in fact drawing perfectly. Stories must sit in the same content-color
+ * context as the screens they document, or they document a lie.
+ */
+@Composable
+internal fun StoryHost(content: @Composable BoxScope.() -> Unit) {
+    Surface(
+        modifier = Modifier.fillMaxSize(),
+        color = __THEME_PREFIX__Colors.Background,
+        contentColor = __THEME_PREFIX__Colors.OnSurface,
+    ) {
+        Box(Modifier.fillMaxSize()) { content() }
+    }
+}

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

@@ -69,6 +69,11 @@ fun main(args: Array<String>) {
             put("ok", JsonPrimitive(true))
             put("pid", JsonPrimitive(ProcessHandle.current().pid()))
             put("port", JsonPrimitive(port))
+            // WHICH project this daemon serves. The port is machine-global, so a
+            // preview service that finds a healthy daemon here has no other way to
+            // tell "my project's daemon" from "another checkout's daemon on the
+            // same port" — and adopting the wrong one renders another app's screens.
+            put("previewsDir", JsonPrimitive(outRoot.absolutePath))
             put("reloadCount", JsonPrimitive(reloadCount.get()))
             put("reloadErrors", JsonPrimitive(reloadErrors.get()))
             put("reloadHooked", JsonPrimitive(reloadHooked))

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

@@ -25,12 +25,16 @@ import __PACKAGE__.di.appModules
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Theme
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__TypeRamp
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
 import kotlinx.serialization.json.JsonPrimitive
 import kotlinx.serialization.json.buildJsonArray
 import kotlinx.serialization.json.buildJsonObject
+import org.jetbrains.skia.Bitmap
 import org.jetbrains.skia.EncodedImageFormat
+import org.jetbrains.skia.Image
 import org.koin.core.context.startKoin
 import org.koin.dsl.module
 import java.io.File
@@ -189,7 +193,8 @@ internal fun renderPng(entry: ScreenPreview, outFile: File, scale: Float) {
             }
             iterations++
         }
-        val data = image.encodeToData(EncodedImageFormat.PNG)
+        val framed = if (isComponentStory(entry.id)) cropToContent(image, scale) else image
+        val data = framed.encodeToData(EncodedImageFormat.PNG)
             ?: error("Skia failed to encode ${entry.id} as PNG")
         outFile.writeBytes(data.bytes)
     } finally {
@@ -197,6 +202,74 @@ internal fun renderPng(entry: ScreenPreview, outFile: File, scale: Float) {
     }
 }
 
+/**
+ * Component stories are the ONLY previews cropped. A screen's frame is part of
+ * what is being reviewed (insets, bottom bar, where content sits on the page),
+ * so screens keep the full phone viewport. A component story is the opposite:
+ * a 48 dp button rendered on an 891 dp canvas is 3% component and 97% empty
+ * background, which is what made the Components gallery read as broken.
+ */
+private fun isComponentStory(id: String) = id.startsWith("component.")
+
+/**
+ * Tightest rectangle whose pixels differ from the frame's own background,
+ * plus one page-padding gutter. Measured from the PIXELS, not the semantics
+ * tree — decoration with no semantics (a ring, a shimmer, a divider) is part
+ * of the component and must not be cropped off.
+ *
+ * The background reference is the top-left pixel: [StoryHost] paints the whole
+ * canvas in the Background token before drawing, so that corner is background
+ * by construction. Two honest fallbacks, never a wrong crop:
+ *   - nothing differs (a story whose content IS the background color) -> the
+ *     full frame, uncropped;
+ *   - a degenerate box (under 8 px on a side) -> the full frame too.
+ * Cropping is lossless: the kept pixels are the rendered pixels, untouched.
+ */
+private fun cropToContent(image: Image, scale: Float): Image {
+    val bitmap = Bitmap.makeFromImage(image)
+    val info = bitmap.imageInfo
+    val w = info.width
+    val h = info.height
+    val bpp = info.bytesPerPixel
+    if (w <= 0 || h <= 0 || bpp <= 0) return image
+    // One bulk read, then scan in memory — getColor(x, y) per pixel would be
+    // ~1.5M native calls per story.
+    val rowBytes = w * bpp
+    val pixels = bitmap.readPixels(info, rowBytes, 0, 0) ?: return image
+    fun samePixelAsOrigin(offset: Int): Boolean {
+        for (b in 0 until bpp) if (pixels[offset + b] != pixels[b]) return false
+        return true
+    }
+    var minX = w
+    var minY = h
+    var maxX = -1
+    var maxY = -1
+    for (y in 0 until h) {
+        val row = y * rowBytes
+        for (x in 0 until w) {
+            if (!samePixelAsOrigin(row + x * bpp)) {
+                if (x < minX) minX = x
+                if (y < minY) minY = y
+                if (x > maxX) maxX = x
+                if (y > maxY) maxY = y
+            }
+        }
+    }
+    if (maxX < 0 || maxY < 0) return image
+    val gutter = (__THEME_PREFIX__Tokens.PaddingPage.value * scale).toInt().coerceAtLeast(1)
+    val left = (minX - gutter).coerceAtLeast(0)
+    val top = (minY - gutter).coerceAtLeast(0)
+    val right = (maxX + 1 + gutter).coerceAtMost(w)
+    val bottom = (maxY + 1 + gutter).coerceAtMost(h)
+    val cw = right - left
+    val ch = bottom - top
+    if (cw < 8 || ch < 8) return image
+    val croppedInfo = info.withWidthHeight(cw, ch)
+    val croppedRowBytes = cw * bpp
+    val cropped = bitmap.readPixels(croppedInfo, croppedRowBytes, left, top) ?: return image
+    return Image.makeRaster(croppedInfo, cropped, croppedRowBytes)
+}
+
 /** The declared design-system catalog — generated FROM the theme objects, so it can't drift. */
 internal fun designSystemCatalog(): String {
     val pretty = Json { prettyPrint = true }
@@ -237,6 +310,23 @@ internal fun designSystemCatalog(): String {
             put("RadiusModal", dp(__THEME_PREFIX__Tokens.RadiusModal))
             put("RadiusInput", dp(__THEME_PREFIX__Tokens.RadiusInput))
         })
+        // The type ramp, published from the SAME data the Typography factory
+        // builds its styles from (presentation/theme/Typography.kt) — the
+        // console's Design language page renders the ramp from this block, so a
+        // ramp that ships and a ramp that is documented cannot diverge. Font
+        // family is deliberately absent: it resolves through @Composable Font()
+        // and is not derivable here, and a guessed name would be a fabrication.
+        put("typography", buildJsonArray {
+            __THEME_PREFIX__TypeRamp.forEach { spec ->
+                add(buildJsonObject {
+                    put("name", JsonPrimitive(spec.name))
+                    put("weight", JsonPrimitive(spec.weight))
+                    put("size", JsonPrimitive("${spec.sizeSp}sp"))
+                    put("lineHeight", JsonPrimitive("${spec.lineHeightSp}sp"))
+                    put("tracking", spec.tracking?.let { JsonPrimitive("${it}sp") } ?: JsonNull)
+                })
+            }
+        })
     }
     return pretty.encodeToString(JsonElement.serializer(), doc)
 }

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