create-cmp-cli 0.5.0 → 0.6.1

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

@@ -0,0 +1,219 @@
+package __PACKAGE__.inspector
+
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import com.sun.net.httpserver.HttpExchange
+import com.sun.net.httpserver.HttpServer
+import java.io.File
+import java.net.InetAddress
+import java.net.InetSocketAddress
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Executors
+import java.util.concurrent.atomic.AtomicLong
+import kotlin.system.exitProcess
+import kotlin.system.measureTimeMillis
+
+/**
+ * Resident preview daemon — phase 2 of the create-cmp preview loop (`@Preview` parity).
+ *
+ * A long-lived headless JVM that renders [previewRegistry] screens ON DEMAND over a
+ * loopback HTTP protocol, so the per-change cost drops from a full Gradle JavaExec cycle
+ * to a warm in-process render. Designed to run under **Compose Hot Reload**:
+ *
+ *   ./gradlew :composeApp:hotRunDesktop --mainClass=__PACKAGE__.inspector.PreviewDaemonKt --auto
+ *
+ * With `--auto`, saving a source file recompiles incrementally and hot-swaps classes into
+ * THIS running JVM; every `/render` composes fresh scenes (and re-reads the registry), so
+ * the next render reflects the new code — typically 1–3s after save instead of a 20–40s
+ * task cycle. Also runnable without hot reload via the plain `runPreviewDaemon` task
+ * (resident, but a restart is needed to pick up recompiled classes).
+ *
+ * Routes (loopback only, mirroring the on-device inspector server's posture):
+ *   GET /health                 → { ok, pid, screens, port, reloadCount, reloadHooked }
+ *   GET /screens                → the registry (ids + titles)
+ *   GET /render?screen=<id|all>[&afterReload=<n>]
+ *       → renders to the previews dir; → { rendered, ms, out, reloadCount, reloadHooked }.
+ *       With afterReload, the render WAITS (≤10s) until reloadCount exceeds <n>: classes
+ *       appearing on disk precede the in-JVM swap, so a caller that just saw a source
+ *       change uses this to avoid composing pre-swap code (a stale render).
+ *   GET /shutdown               → 200, then exits
+ *
+ * Program args (never --args-through-Gradle for the renderScreens task, but ComposeHotRun
+ * passes them fine; all optional): `--port <n>` (default 9601), `--out <dir>` (default
+ * build/previews — resolved against the task's working dir, composeApp/), `--pngScale <n>`.
+ */
+fun main(args: Array<String>) {
+    val port = argValue(args, "--port")?.toIntOrNull() ?: 9601
+    val outRoot = File(argValue(args, "--out") ?: "build/previews")
+    val pngScale = argValue(args, "--pngScale")?.toFloatOrNull()?.takeIf { it > 0f } ?: 2f
+
+    val reloadCount = AtomicLong(0)
+    val reloadErrors = AtomicLong(0)
+    val reloadHooked = hookReloadListener { succeeded ->
+        if (succeeded) reloadCount.incrementAndGet() else reloadErrors.incrementAndGet()
+    }
+
+    initPreviewKoin()
+    outRoot.mkdirs()
+    File(outRoot, "design-system.json").writeText(designSystemCatalog())
+
+    val renderLock = Any()
+    val server = HttpServer.create(InetSocketAddress(InetAddress.getLoopbackAddress(), port), 0)
+    server.executor = Executors.newFixedThreadPool(3)
+
+    server.createContext("/health") { exchange ->
+        respondJson(exchange, 200, buildJsonObject {
+            put("ok", JsonPrimitive(true))
+            put("pid", JsonPrimitive(ProcessHandle.current().pid()))
+            put("port", JsonPrimitive(port))
+            put("reloadCount", JsonPrimitive(reloadCount.get()))
+            put("reloadErrors", JsonPrimitive(reloadErrors.get()))
+            put("reloadHooked", JsonPrimitive(reloadHooked))
+            put("screens", buildJsonArray {
+                previewRegistry().forEach { add(JsonPrimitive(it.id)) }
+            })
+        })
+    }
+
+    server.createContext("/screens") { exchange ->
+        respondJson(exchange, 200, buildJsonObject {
+            put("screens", buildJsonArray {
+                previewRegistry().forEach {
+                    add(buildJsonObject {
+                        put("id", JsonPrimitive(it.id))
+                        put("title", JsonPrimitive(it.title))
+                    })
+                }
+            })
+        })
+    }
+
+    server.createContext("/render") { exchange ->
+        // Swap-aware rendering: classes on disk precede the in-JVM swap, so a caller
+        // that just observed a source change passes afterReload=<last seen count> and
+        // we wait (bounded) for the swap to actually land before composing.
+        val afterReload = queryParam(exchange, "afterReload")?.toLongOrNull()
+        if (afterReload != null && reloadHooked) {
+            val deadline = System.currentTimeMillis() + 10_000
+            while (reloadCount.get() <= afterReload && System.currentTimeMillis() < deadline) {
+                Thread.sleep(100)
+            }
+        }
+        // Re-read the registry PER REQUEST: after a hot swap, this picks up the
+        // redefined screen composables (fresh scenes are composed from current classes).
+        val all = previewRegistry()
+        val filter = queryParam(exchange, "screen") ?: "all"
+        val selected = if (filter == "all") all else all.filter { it.id == filter }
+        if (selected.isEmpty()) {
+            respondJson(exchange, 404, buildJsonObject {
+                put("error", JsonPrimitive(
+                    "Unknown screen '$filter'. Available: ${all.joinToString(", ") { it.id }} (or 'all')."
+                ))
+            })
+            return@createContext
+        }
+        try {
+            val rendered = mutableListOf<String>()
+            val ms = measureTimeMillis {
+                synchronized(renderLock) {
+                    for (entry in selected) {
+                        val dir = File(outRoot, entry.id).apply { mkdirs() }
+                        renderTree(entry, File(dir, "tree.json"))
+                        renderPng(entry, File(dir, "screen.png"), pngScale)
+                        rendered += entry.id
+                    }
+                    // The manifest always lists the FULL registry so single-screen renders
+                    // keep the gallery complete.
+                    File(outRoot, "manifest.json").writeText(manifestJson(all, pngScale))
+                }
+            }
+            respondJson(exchange, 200, buildJsonObject {
+                put("rendered", buildJsonArray { rendered.forEach { add(JsonPrimitive(it)) } })
+                put("ms", JsonPrimitive(ms))
+                put("out", JsonPrimitive(outRoot.absolutePath))
+                put("reloadCount", JsonPrimitive(reloadCount.get()))
+                put("reloadErrors", JsonPrimitive(reloadErrors.get()))
+                put("reloadHooked", JsonPrimitive(reloadHooked))
+            })
+        } catch (t: Throwable) {
+            respondJson(exchange, 500, buildJsonObject {
+                put("error", JsonPrimitive(t.message ?: t.toString()))
+            })
+        }
+    }
+
+    server.createContext("/shutdown") { exchange ->
+        respondJson(exchange, 200, buildJsonObject { put("ok", JsonPrimitive(true)) })
+        Thread {
+            Thread.sleep(100)
+            exitProcess(0)
+        }.start()
+    }
+
+    server.start()
+    System.err.println(
+        "preview daemon listening on http://127.0.0.1:$port " +
+            "(previews -> ${outRoot.absolutePath}, pngScale $pngScale)"
+    )
+    CountDownLatch(1).await() // resident until /shutdown or SIGTERM
+}
+
+/**
+ * Register a Compose Hot Reload after-reload callback via REFLECTION against the
+ * AGENT (`org.jetbrains.compose.reload.agent.ReloadHooksKt`) — the agent jar is what
+ * `hotRunDesktop` loads via -javaagent, so it IS visible to app code, unlike the
+ * runtime-api facade (verified: ClassNotFoundException). No compile-time dependency,
+ * so the inspector feature stays independent of the dev-client feature; plain
+ * `runPreviewDaemon` JVMs return false and just report reloadHooked=false.
+ *
+ * The callback receives Either<Reload, Throwable>: success bumps the reload count,
+ * failure (a swap the agent could not apply) is reported separately so callers can
+ * surface "your edit did not land" instead of rendering pre-swap code forever.
+ */
+private fun hookReloadListener(onReload: (succeeded: Boolean) -> Unit): Boolean = try {
+    val hooks = Class.forName("org.jetbrains.compose.reload.agent.ReloadHooksKt")
+    val isSuccess = runCatching {
+        Class.forName("org.jetbrains.compose.reload.core.TryKt")
+            .getMethod("isSuccess", Class.forName("org.jetbrains.compose.reload.core.Either"))
+    }.getOrNull()
+    val callback: Function2<Any?, Any?, Unit> = { _, either ->
+        val ok = runCatching { isSuccess?.invoke(null, either) as? Boolean }.getOrNull() ?: true
+        onReload(ok)
+    }
+    hooks.getMethod("invokeAfterHotReload", Function2::class.java).invoke(null, callback)
+    true
+} catch (t: Throwable) {
+    System.err.println(
+        "preview daemon: reload hook unavailable (${t.javaClass.simpleName}) — " +
+            "swap-aware renders disabled, callers fall back to time-based settling"
+    )
+    false
+}
+
+private fun argValue(args: Array<String>, flag: String): String? {
+    val i = args.indexOf(flag)
+    return if (i >= 0 && i + 1 < args.size) args[i + 1] else null
+}
+
+private fun queryParam(exchange: HttpExchange, key: String): String? =
+    exchange.requestURI.query
+        ?.split("&")
+        ?.mapNotNull { part ->
+            val eq = part.indexOf('=')
+            if (eq > 0) part.substring(0, eq) to part.substring(eq + 1) else null
+        }
+        ?.firstOrNull { it.first == key }
+        ?.second
+        ?.takeIf { it.isNotBlank() }
+
+private val daemonJson = Json { prettyPrint = true }
+
+private fun respondJson(exchange: HttpExchange, status: Int, body: JsonElement) {
+    val bytes = daemonJson.encodeToString(JsonElement.serializer(), body).toByteArray()
+    exchange.responseHeaders.set("Content-Type", "application/json")
+    exchange.sendResponseHeaders(status, bytes.size.toLong())
+    exchange.responseBody.use { it.write(bytes) }
+}

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

@@ -0,0 +1,265 @@
+package __PACKAGE__.inspector
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.remember
+import androidx.compose.ui.ImageComposeScene
+import androidx.compose.ui.graphics.toArgb
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.onRoot
+import androidx.compose.ui.test.runDesktopComposeUiTest
+import androidx.compose.ui.unit.Density
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.LifecycleRegistry
+import androidx.lifecycle.ViewModelStore
+import androidx.lifecycle.ViewModelStoreOwner
+import androidx.lifecycle.compose.LocalLifecycleOwner
+import androidx.lifecycle.viewmodel.compose.LocalViewModelStoreOwner
+import __PACKAGE__.core.connectivity.NetworkMonitor
+// >>> cmp:feature room
+import __PACKAGE__.data.local.AppDatabase
+import __PACKAGE__.data.local.buildDatabase
+// <<< cmp:feature room
+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 kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import org.jetbrains.skia.EncodedImageFormat
+import org.koin.core.context.startKoin
+import org.koin.dsl.module
+import java.io.File
+import kotlin.system.exitProcess
+
+// Phone-shaped viewport, density 1 — px == dp in the dumped tree (matches the dev-client
+// window and keeps the inspector's a11y/touch-target math exact).
+internal const val WIDTH = 411
+internal const val HEIGHT = 891
+
+/**
+ * Headless preview harness — the project-wired tier-0 loop of the create-cmp inspector.
+ *
+ * Renders REAL screens from [previewRegistry] with no device, emulator, or window:
+ * for each screen it writes the inspector-contract semantics tree (`tree.json`, via
+ * `runDesktopComposeUiTest`) and a pixel preview (`screen.png`, via [ImageComposeScene])
+ * from the same composition sources at the same viewport, plus the declared design-system
+ * catalog (`design-system.json`) and a `manifest.json` for gallery tooling
+ * (qa/preview-gallery.mjs turns the output into a single self-contained index.html).
+ *
+ * Real DI, real theme, real data: Koin starts with the same modules as the app, and
+ * screens resolve their ViewModels through `koinViewModel()` exactly as in production.
+ *
+ * Invoked by the `:composeApp:renderScreens` Gradle task; parameters arrive as SYSTEM
+ * PROPERTIES (never `--args`, which Gradle's CLI parsing mangles):
+ *   -Pscreen=<id|all>   which registry entry to render        (default all)
+ *   -PpreviewOut=<dir>  output root                           (default build/previews)
+ *   -PpngScale=<n>      PNG density multiplier for sharpness  (default 2; tree stays density 1)
+ */
+fun main() {
+    val screenFilter = System.getProperty("screen")?.takeIf { it.isNotBlank() } ?: "all"
+    val outRoot = File(System.getProperty("out")?.takeIf { it.isNotBlank() } ?: "build/previews")
+    val pngScale = System.getProperty("pngScale")?.toFloatOrNull()?.takeIf { it > 0f } ?: 2f
+
+    initPreviewKoin()
+
+    val all = previewRegistry()
+    val selected = if (screenFilter == "all") all else all.filter { it.id == screenFilter }
+    if (selected.isEmpty()) {
+        System.err.println(
+            "Unknown screen '$screenFilter'. Available: ${all.joinToString(", ") { it.id }} (or 'all').",
+        )
+        exitProcess(2)
+    }
+
+    outRoot.mkdirs()
+    File(outRoot, "design-system.json").writeText(designSystemCatalog())
+
+    for (entry in selected) {
+        val dir = File(outRoot, entry.id).apply { mkdirs() }
+        renderTree(entry, File(dir, "tree.json"))
+        renderPng(entry, File(dir, "screen.png"), pngScale)
+        System.err.println("rendered ${entry.id} -> ${dir.absolutePath}")
+    }
+
+    File(outRoot, "manifest.json").writeText(manifestJson(selected, pngScale))
+    System.err.println("previews -> ${outRoot.absolutePath}")
+    // AWT/EDT and Koin threads are non-daemon; exit explicitly once outputs are on disk.
+    exitProcess(0)
+}
+
+/**
+ * Preview-harness DI — intentionally independent of the dev-client feature (which owns
+ * DesktopModule): the same platform bindings, started once for the render run.
+ */
+internal fun initPreviewKoin() {
+    startKoin {
+        modules(
+            module {
+                // >>> cmp:feature room
+                single<AppDatabase> { buildDatabase() }
+                // <<< cmp:feature room
+                single { NetworkMonitor(null) }
+            },
+            *appModules.toTypedArray(),
+        )
+    }
+}
+
+/**
+ * Provides what a bare offscreen composition lacks so production screens compose
+ * unmodified: a RESUMED [LifecycleOwner] (for `collectAsStateWithLifecycle`) and a fresh
+ * [ViewModelStoreOwner] per composition (so `koinViewModel()` resolves — and each render
+ * gets fresh ViewModels), then the app theme.
+ */
+@Composable
+internal fun PreviewRoot(content: @Composable () -> Unit) {
+    val owner = remember { PreviewOwner() }
+    CompositionLocalProvider(
+        LocalLifecycleOwner provides owner,
+        LocalViewModelStoreOwner provides owner,
+    ) {
+        __THEME_PREFIX__Theme(content)
+    }
+}
+
+internal class PreviewOwner : LifecycleOwner, ViewModelStoreOwner {
+    private val registry = LifecycleRegistry.createUnsafe(this).apply {
+        currentState = Lifecycle.State.RESUMED
+    }
+    override val lifecycle: Lifecycle get() = registry
+    override val viewModelStore = ViewModelStore()
+}
+
+/**
+ * Semantics tree at the phone viewport, density 1. ADAPTIVE settle: async data arrives in
+ * real time, so keep sampling until two consecutive dumps are identical (bounded) — static
+ * screens finish in ~300ms instead of paying the full window.
+ */
+@OptIn(ExperimentalTestApi::class)
+internal fun renderTree(entry: ScreenPreview, outFile: File) {
+    var json = ""
+    runDesktopComposeUiTest(width = WIDTH, height = HEIGHT) {
+        setContent { PreviewRoot { entry.content() } }
+        waitForIdle()
+        var prev: String? = null
+        var stable = 0
+        var iterations = 0
+        while (iterations < 8 && stable < 2) {
+            Thread.sleep(150)
+            waitForIdle()
+            val dump = PreviewSemanticsJson.dumpTree(onRoot(useUnmergedTree = true).fetchSemanticsNode())
+            if (dump == prev) stable++ else { stable = 0; prev = dump }
+            iterations++
+        }
+        json = prev ?: PreviewSemanticsJson.dumpTree(onRoot(useUnmergedTree = true).fetchSemanticsNode())
+    }
+    outFile.writeText(json)
+}
+
+/**
+ * Pixel twin of the tree: same content, same dp viewport, density [scale] for sharpness.
+ * Frames are re-rendered while invalidations arrive so async data reaches the pixels too.
+ */
+internal fun renderPng(entry: ScreenPreview, outFile: File, scale: Float) {
+    val scene = ImageComposeScene(
+        width = (WIDTH * scale).toInt(),
+        height = (HEIGHT * scale).toInt(),
+        density = Density(scale),
+    ) {
+        PreviewRoot { entry.content() }
+    }
+    try {
+        var elapsedNanos = 0L
+        var image = scene.render(elapsedNanos)
+        var quiet = 0
+        var iterations = 0
+        while (iterations < 12 && quiet < 2) {
+            Thread.sleep(100)
+            elapsedNanos += 100_000_000L
+            if (scene.hasInvalidations()) {
+                image = scene.render(elapsedNanos)
+                quiet = 0
+            } else {
+                quiet++
+            }
+            iterations++
+        }
+        val data = image.encodeToData(EncodedImageFormat.PNG)
+            ?: error("Skia failed to encode ${entry.id} as PNG")
+        outFile.writeBytes(data.bytes)
+    } finally {
+        scene.close()
+    }
+}
+
+/** The declared design-system catalog — generated FROM the theme objects, so it can't drift. */
+internal fun designSystemCatalog(): String {
+    val pretty = Json { prettyPrint = true }
+    fun hex(color: androidx.compose.ui.graphics.Color): JsonElement =
+        JsonPrimitive("#%06X".format(color.toArgb() and 0xFFFFFF))
+    fun dp(value: androidx.compose.ui.unit.Dp): JsonElement =
+        JsonPrimitive("${value.value.toInt()}dp")
+
+    val doc = buildJsonObject {
+        put("colors", buildJsonObject {
+            put("Primary", hex(__THEME_PREFIX__Colors.Primary))
+            put("OnPrimary", hex(__THEME_PREFIX__Colors.OnPrimary))
+            put("Accent", hex(__THEME_PREFIX__Colors.Accent))
+            put("OnAccent", hex(__THEME_PREFIX__Colors.OnAccent))
+            put("Secondary", hex(__THEME_PREFIX__Colors.Secondary))
+            put("Error", hex(__THEME_PREFIX__Colors.Error))
+            put("Success", hex(__THEME_PREFIX__Colors.Success))
+            put("Warning", hex(__THEME_PREFIX__Colors.Warning))
+            put("Info", hex(__THEME_PREFIX__Colors.Info))
+            put("Background", hex(__THEME_PREFIX__Colors.Background))
+            put("Surface", hex(__THEME_PREFIX__Colors.Surface))
+            put("SurfaceVariant", hex(__THEME_PREFIX__Colors.SurfaceVariant))
+            put("OnSurface", hex(__THEME_PREFIX__Colors.OnSurface))
+            put("OnSurfaceVariant", hex(__THEME_PREFIX__Colors.OnSurfaceVariant))
+            put("Outline", hex(__THEME_PREFIX__Colors.Outline))
+            put("OutlineVariant", hex(__THEME_PREFIX__Colors.OutlineVariant))
+            put("Divider", hex(__THEME_PREFIX__Colors.Divider))
+        })
+        put("dimens", buildJsonObject {
+            put("ElevationCard", dp(__THEME_PREFIX__Tokens.ElevationCard))
+            put("ElevationModal", dp(__THEME_PREFIX__Tokens.ElevationModal))
+            put("PaddingPage", dp(__THEME_PREFIX__Tokens.PaddingPage))
+            put("PaddingCard", dp(__THEME_PREFIX__Tokens.PaddingCard))
+            put("GapCard", dp(__THEME_PREFIX__Tokens.GapCard))
+            put("BottomNavHeight", dp(__THEME_PREFIX__Tokens.BottomNavHeight))
+            put("RadiusCard", dp(__THEME_PREFIX__Tokens.RadiusCard))
+            put("RadiusPill", dp(__THEME_PREFIX__Tokens.RadiusPill))
+            put("RadiusModal", dp(__THEME_PREFIX__Tokens.RadiusModal))
+            put("RadiusInput", dp(__THEME_PREFIX__Tokens.RadiusInput))
+        })
+    }
+    return pretty.encodeToString(JsonElement.serializer(), doc)
+}
+
+internal fun manifestJson(entries: List<ScreenPreview>, pngScale: Float): String {
+    val pretty = Json { prettyPrint = true }
+    val doc = buildJsonObject {
+        put("viewport", buildJsonObject {
+            put("width", JsonPrimitive(WIDTH))
+            put("height", JsonPrimitive(HEIGHT))
+            put("treeDensity", JsonPrimitive(1))
+            put("pngScale", JsonPrimitive(pngScale))
+        })
+        put("screens", buildJsonArray {
+            entries.forEach { entry ->
+                add(buildJsonObject {
+                    put("id", JsonPrimitive(entry.id))
+                    put("title", JsonPrimitive(entry.title))
+                    put("tree", JsonPrimitive("${entry.id}/tree.json"))
+                    put("png", JsonPrimitive("${entry.id}/screen.png"))
+                })
+            }
+        })
+    }
+    return pretty.encodeToString(JsonElement.serializer(), doc)
+}

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

@@ -0,0 +1,61 @@
+package __PACKAGE__.inspector
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import __PACKAGE__.presentation.components.BaseScreen
+import __PACKAGE__.presentation.home.DetailScreen
+import __PACKAGE__.presentation.home.HomeScreen
+import __PACKAGE__.presentation.navigation.AppShell
+import __PACKAGE__.presentation.navigation.appTabs
+import __PACKAGE__.presentation.profile.ProfileScreen
+
+/**
+ * One previewable screen: a stable [id] (the `-Pscreen=` selector and output directory
+ * name), a human [title] for the gallery, and the composable [content] exactly as the
+ * app hosts it.
+ *
+ * The `@Preview` analog for the create-cmp inspector: the registry makes "render screen
+ * X" a closed, enumerable operation. The scaffolder regenerates the tab entries from the
+ * configured `tabs`; when you add a screen by hand, add it here — the renderScreens
+ * harness, the gallery, and golden baselines pick it up by id.
+ *
+ * State variants (the Storybook "story" analog): a screen in a specific UI state is just
+ * another entry with a derived id — e.g. `ScreenPreview("home@empty", "Home — empty")`
+ * hosting the screen with that state forced (a state-first overload of the screen, or
+ * 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.
+ */
+data class ScreenPreview(
+    val id: String,
+    val title: String,
+    val content: @Composable () -> Unit,
+)
+
+/** Every registered screen, in gallery order. Ids must be unique and filesystem-safe. */
+fun previewRegistry(): List<ScreenPreview> = listOf(
+    ScreenPreview("shell", "App shell — bottom nav (first tab selected)") {
+        AppShell(
+            tabs = appTabs(
+                home = { HomeScreen(onItemClick = {}) },
+                profile = { ProfileScreen() },
+            ),
+        )
+    },
+    ScreenPreview("home", "Home tab") { TabHost { HomeScreen(onItemClick = {}) } },
+    ScreenPreview("profile", "Profile tab") { TabHost { ProfileScreen() } },
+    ScreenPreview("detail", "Detail (nav destination)") { DetailScreen(itemId = "1", onBack = {}) },
+)
+
+/**
+ * Hosts a single tab's content the way [AppShell] does — inside [BaseScreen] — minus the
+ * bottom bar, so a tab previews with the same insets/background it gets in the shell.
+ */
+@Composable
+private fun TabHost(content: @Composable () -> Unit) {
+    BaseScreen {
+        Box(Modifier.fillMaxSize()) { content() }
+    }
+}

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

@@ -0,0 +1,83 @@
+package __PACKAGE__.inspector
+
+import androidx.compose.ui.semantics.SemanticsActions
+import androidx.compose.ui.semantics.SemanticsNode
+import androidx.compose.ui.semantics.SemanticsProperties
+import androidx.compose.ui.semantics.getOrNull
+import __PACKAGE__.presentation.theme.DesignTokenKey
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import kotlin.math.roundToInt
+
+/**
+ * Walks a Compose [SemanticsNode] tree and serialises it to JSON matching the create-cmp
+ * inspector contract (schemaVersion 1, source "headless-jvm"). Every node carries pixel,
+ * root-relative `bounds` and a (possibly empty) `children` array; testTag / text /
+ * contentDescription / designToken are nullable; `role` / `clickable` / `disabled` are the
+ * additive interaction fields.
+ *
+ * This dumper reads THIS project's [DesignTokenKey], so the resolved design tokens the
+ * component kit self-reports (Modifier.designToken) appear in the dump — which is what
+ * makes the tree design-system-aware, not just geometry.
+ */
+object PreviewSemanticsJson {
+
+    private val prettyJson = Json { prettyPrint = true }
+
+    fun dumpTree(root: SemanticsNode): String {
+        val doc = buildJsonObject {
+            put("schemaVersion", JsonPrimitive(1))
+            put("source", JsonPrimitive("headless-jvm"))
+            put("root", nodeToJson(root))
+        }
+        return prettyJson.encodeToString(JsonElement.serializer(), doc)
+    }
+
+    private fun nodeToJson(node: SemanticsNode): JsonObject = buildJsonObject {
+        put("testTag", node.config.getOrNull(SemanticsProperties.TestTag).toJson())
+        put(
+            "text",
+            node.config.getOrNull(SemanticsProperties.Text)
+                ?.joinToString(" ") { it.text }?.takeIf { it.isNotEmpty() }.toJson(),
+        )
+        put(
+            "contentDescription",
+            node.config.getOrNull(SemanticsProperties.ContentDescription)
+                ?.joinToString(" ")?.takeIf { it.isNotEmpty() }.toJson(),
+        )
+        put("role", node.config.getOrNull(SemanticsProperties.Role)?.toString().toJson())
+        put("clickable", JsonPrimitive(node.config.contains(SemanticsActions.OnClick)))
+        put("disabled", JsonPrimitive(node.config.contains(SemanticsProperties.Disabled)))
+        put("bounds", node.boundsJson())
+        put("designToken", node.designTokenJson())
+        put("children", buildJsonArray { node.children.forEach { add(nodeToJson(it)) } })
+    }
+
+    private fun SemanticsNode.boundsJson(): JsonObject {
+        val rect = boundsInRoot
+        return buildJsonObject {
+            put("x", JsonPrimitive(rect.left.roundToInt()))
+            put("y", JsonPrimitive(rect.top.roundToInt()))
+            put("width", JsonPrimitive(rect.width.roundToInt()))
+            put("height", JsonPrimitive(rect.height.roundToInt()))
+        }
+    }
+
+    private fun SemanticsNode.designTokenJson(): JsonElement {
+        val info = config.getOrNull(DesignTokenKey) ?: return JsonNull
+        return buildJsonObject {
+            put("tokens", buildJsonArray { info.tokens.forEach { add(JsonPrimitive(it)) } })
+            put("resolved", buildJsonObject {
+                info.resolved.forEach { (k, v) -> put(k, JsonPrimitive(v)) }
+            })
+        }
+    }
+
+    private fun String?.toJson(): JsonElement =
+        if (this == null) JsonNull else JsonPrimitive(this)
+}

package/template/manifest.json

@@ -94,9 +94,11 @@
       "enabledByDefault": true,
       "paths": [
         "composeApp/src/androidDebug/kotlin/com/example/app/inspector",
-        "composeApp/src/androidRelease/kotlin/com/example/app/inspector"
+        "composeApp/src/androidRelease/kotlin/com/example/app/inspector",
+        "composeApp/src/desktopMain/kotlin/com/example/app/inspector",
+        "qa/preview-gallery.mjs"
       ],
-      "notes": "Live on-device inspector: debug-only loopback HTTP server on 127.0.0.1:9500 (GET /inspect/health|tree|design-system) serving the semantics tree + design-token catalog to the cmp-inspector MCP via `adb forward tcp:9500 tcp:9500`. The androidRelease dir holds only the no-op startInspector() twin — release builds contain no inspector code structurally. When off: delete both inspector dirs AND strip the `inspector` marker blocks in AppApplication.kt (import + startInspector() call) and composeApp/src/androidDebug/AndroidManifest.xml (INTERNET permission). Zero dependencies (java.net.ServerSocket + kotlinx-serialization from commonMain); no build-file markers needed."
+      "notes": "Two loops in one feature. (1) Live on-device inspector: debug-only loopback HTTP server on 127.0.0.1:9500 (GET /inspect/health|tree|design-system) serving the semantics tree + design-token catalog to the cmp-inspector MCP via `adb forward tcp:9500 tcp:9500`. The androidRelease dir holds only the no-op startInspector() twin — release builds contain no inspector code structurally. (2) Headless preview harness (tier 0): the desktopMain inspector dir (PreviewRegistry/PreviewHarness/PreviewSemanticsJson) + the :composeApp:renderScreens task render every registered screen to PNG + contract tree JSON with no device; qa/preview-gallery.mjs builds a self-contained index.html from the output (vendored pure-logic render libs live in qa/lib and stay when the feature is off — they are inert without the harness). The harness starts its OWN Koin (independent of the dev-client feature's DesktopModule) and its PreviewRegistry tab entries are regenerated from the configured `tabs` by the scaffolder (pipeline step b.3). When off: delete all three inspector dirs + qa/preview-gallery.mjs, strip the `inspector` marker blocks in AppApplication.kt (import + startInspector() call), composeApp/src/androidDebug/AndroidManifest.xml (INTERNET permission), and composeApp/build.gradle.kts (desktopMain compose.uiTest dep + the renderScreens task). On-device server: zero dependencies (java.net.ServerSocket + kotlinx-serialization from commonMain)."
     },
     "dev-client": {
       "enabledByDefault": true,