create-cmp-cli 0.5.0 → 0.6.0

package/README.md

@@ -101,7 +101,7 @@ Everything except `create` works on **any** KMP project, not just ones this tool
 Hit a KMP build error? [Common CMP/KMP build errors and fixes](docs/errors/README.md) — kotlin↔KSP
 mismatch, the KSP2/iOS catch-22, `SDK location not found`, `No space left on device`, version drift.
 
-## The Claude Code plugin (8 skills)
+## The Claude Code plugin (9 skills)
 
 ```text
 /plugin marketplace add kvdm-co-pilot/create-cmp
@@ -115,13 +115,14 @@ Same engine as the CLI, conversational front door. Each skill is a guided flow,
 | `cmp-new` | "Make me an app." Interviews you in chat, scaffolds via the engine, generates your bottom-nav tab screens from the exemplar pattern, proves the build green. |
 | `cmp-doctor` | "Why won't my KMP project build?" Runs the doctor, explains the findings, applies consented fixes. |
 | `cmp-upgrade` | "Bump my dependencies safely." Diff → apply → verify, with the lockstep guardrails. |
+| `cmp-preview` | "Show me my screens." Live gallery of every screen at a local URL — real DI/theme/data, no device, no emulator, no manual Gradle. Edit → save → the page re-renders itself; changed screens get flagged; a11y violations show per screen. |
 | `cmp-inspect` | "What did the UI actually render?" Reads a **running** app as structured JSON — hierarchy, geometry, resolved design tokens, navigation state. Never screenshots. Can assert tokens, find drift against your design system, audit accessibility, diff before/after. |
 | `cmp-dev-client` | "Let me iterate fast." Runs your shared UI in a phone-sized desktop window with hot reload — save a file, see it change. No emulator needed. Firebase stays off on desktop (offline fakes). |
 | `cmp-firebase-connect` | "Wire up my real Firebase." Drives the Firebase CLI: create/reuse a project, register the app, drop the real `google-services.json` over the placeholder, prove it with a green build. Every cloud action asks first. |
 | `cmp-test` | "Write tests for my app." *Observes* the running app's semantics tree — what's actually on screen, what's tappable, where navigation goes — and derives the regression suite from that. Tests come from rendered reality, not guesses. |
 | `cmp-qa-prep` | "Get my test environment up." Emulator + app install + E2E smoke run, with the gotchas handled. |
 
-Plus the **`cmp-inspector` MCP server** (14 tools) — the machine-readable window into a running
+Plus the **`cmp-inspector` MCP server** (18 tools) — the machine-readable window into a running
 Compose UI that `cmp-inspect`, `cmp-test`, and the verified dev loop are built on. One tree
 contract, three sources: render a screen headlessly, connect to the live app, or read a device
 via UIAutomator.
@@ -182,13 +183,21 @@ stamper (`qa/scaffold-feature.mjs`):
 Any plain Claude Code session — no create-cmp plugin installed — finds these and extends the app
 correctly by construction.
 
-### 6. The live inspector — AI-readable UI
-Every debug build serves `127.0.0.1:9500` (loopback-only, structurally absent from release): the
-UI tree as JSON, the design-token catalog, a screenshot route, a tap route, and a live device
-view for humans (`/inspect/remote` — watch the real device in a browser, click to tap). Agents
-read structure; humans see pixels.
+### 6. The inspector — AI-readable UI, previews without a device
+Two loops, one contract. **Live (tier 1):** every debug build serves `127.0.0.1:9500`
+(loopback-only, structurally absent from release): the UI tree as JSON, the design-token catalog,
+a screenshot route, a tap route, and a live device view for humans (`/inspect/remote` — watch the
+real device in a browser, click to tap). **Headless previews (tier 0):** every app ships
+`inspector/PreviewRegistry.kt` (the `@Preview` analog — shell, every tab, detail) and a
+`:composeApp:renderScreens` task that renders each screen with real DI/theme/data to
+`screen.png` + its contract `tree.json` — no device, no emulator; `node qa/preview-gallery.mjs`
+turns the output into one self-contained `index.html` (pixels + wireframe + a11y per screen).
+Agents read structure; humans see pixels.
 
 ### 7. The daily-driver extras
+- **Live preview loop** — every real screen rendered headlessly on save (resident hot-reload
+  daemon, ~1s warm renders); a self-updating gallery for the human, changed-screen attribution
+  and compile-error surfacing for the agent. The agent sees what it builds.
 - **Desktop dev-client** — shared UI in a phone-sized JVM window, Compose Hot Reload attached.
 - **CI workflow** — Android job on every push; iOS job ready to un-comment.
 - **`CLAUDE.md`** — the AI delivery contract itself, stating everything above as rules any AI
@@ -201,8 +210,15 @@ read structure; humans see pixels.
 **New app → green.** `cmp-new` (or `npx create-cmp-cli`) → interview → stamp → green build proven
 → tab screens generated. Then `cmp-firebase-connect` to wire your real backend.
 
-**The daily UI loop.** `./gradlew :composeApp:hotRunDesktop --auto` → edit Compose → save → see
-it. No emulator, no Firebase, sub-second feedback.
+**The daily UI loop.** Say "preview my app" (the cmp-preview skill / `preview` MCP tool) → a
+live local gallery of EVERY real screen that re-renders on save — no device, no emulator, no
+manual Gradle. The agent runs the same loop to check its own work while it builds: edit →
+`preview_status { waitForRender: true }` → which screens changed (or the compile error, or the
+failed hot swap) → `preview_diff { screen }` for a proven verdict — feedback in seconds instead
+of a 25–40s build or an emulator round-trip. One interactive window instead of stills:
+`./gradlew :composeApp:hotRunDesktop --auto`. Command-line fallback (no plugin needed — the
+scaffolded app carries the whole loop):
+`./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs`.
 
 **The verified dev loop (the flagship).** For any UI change: snapshot the live tree → make the
 edit → reload → `prove_change` compares before/after structure, token drift, and a11y, and returns

package/llms.txt

@@ -14,7 +14,22 @@ Other flags: `--bundle-id`, `--region`, `--theme-prefix`, `--ios/--no-ios`, `--f
 
 Official alias packages (same tool, same flags, same maintainer): `npm create compose-multiplatform@latest my-app` and `npm create kmp@latest my-app` both delegate to create-cmp-cli.
 
-create-cmp is also invokable as a Claude Code plugin (`/plugin marketplace add kvdm-co-pilot/create-cmp`, then `/plugin install create-cmp`) with eight skills and the `cmp-inspector` MCP server. Generated projects self-verify without the plugin installed: `node qa/verify.mjs` runs 8 gates (spec coverage, build, unit tests, conformance, golden trees, token drift, a11y, on-device E2E) and writes a content-hash-bound evidence receipt; a Stop hook and CI both refuse "done" without a fresh PASS receipt.
+create-cmp is also invokable as a Claude Code plugin (`/plugin marketplace add kvdm-co-pilot/create-cmp`, then `/plugin install create-cmp`) with nine skills and the `cmp-inspector` MCP server (18 tools). Generated projects self-verify without the plugin installed: `node qa/verify.mjs` runs 8 gates (spec coverage, build, unit tests, conformance, golden trees, token drift, a11y, on-device E2E) and writes a content-hash-bound evidence receipt; a Stop hook and CI both refuse "done" without a fresh PASS receipt.
+
+## The UI feedback loop (for agents building UI)
+
+Every generated app carries a device-free preview loop — no emulator, no manual Gradle. An
+agent editing ANY screen should use it to see and verify its own work: with the plugin,
+`preview { projectDir }` starts a resident service (live self-updating gallery URL for the
+human), then after each edit `preview_status { waitForRender: true }` blocks until the
+outcome — `changedLastRender` names the screens the edit touched (empty = it reached no
+screen), `lastErrorSource: "compile"` means it didn't build — and `preview_diff { screen }`
+returns a proven verdict (`proven-clean` / `changed-with-regressions` / `no-change`).
+Warm renders take ~1s per screen (resident hot-reload daemon). Without the plugin:
+`./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs`. Screens are registered
+in `inspector/PreviewRegistry.kt`; the generated `CLAUDE.md`/`AGENTS.md` document the loop
+in-repo ("UI feedback loop" section). Pixels flow to the human, structure (tree JSON) flows
+to the agent — never read PNG bytes into model context.
 
 ## Docs
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.5.0",
-  "description": "The AI delivery harness for Kotlin/Compose Multiplatform — a deterministic, non-interactive project generator that scaffolds a green-building app (Android + iOS) in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Installs the `create-cmp` command.",
+  "version": "0.6.0",
+  "description": "The AI delivery harness for Kotlin/Compose Multiplatform — a deterministic, non-interactive project generator that scaffolds a green-building app (Android + iOS) in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Every app carries a device-free UI preview loop (real screens rendered headlessly on save; changed-screen attribution and compile-error surfacing for coding agents, a live gallery for humans) plus agent-first docs (CLAUDE.md + AGENTS.md). Installs the `create-cmp` command.",
   "type": "module",
   "bin": {
     "create-cmp": "bin/create-cmp.mjs",
@@ -41,7 +41,12 @@
     "android",
     "ios",
     "verify",
-    "e2e"
+    "e2e",
+    "preview",
+    "storybook",
+    "agent feedback loop",
+    "agents.md",
+    "claude"
   ],
   "license": "MIT",
   "author": "Karel van der Merwe",

package/src/lib/tabs.mjs

@@ -317,6 +317,109 @@ fun PlaceholderScreen(title: String, titleTag: String) {
 `;
 }
 
+/** Preview content lambda for one tab in the registry's appTabs(...) call — no-op navigation. */
+function previewTabArg(tab) {
+  if (tab.slug === "home") {
+    return `                ${tab.param} = { HomeScreen(onItemClick = {}) },`;
+  }
+  if (tab.slug === "profile") {
+    return `                ${tab.param} = { ProfileScreen() },`;
+  }
+  return `                ${tab.param} = { PlaceholderScreen(title = "${kotlinString(tab.label)}", titleTag = "${tab.slug}_title") },`;
+}
+
+/** Per-tab ScreenPreview entry (single tab hosted in TabHost, as AppShell hosts it). */
+function previewEntry(tab) {
+  if (tab.slug === "home") {
+    return `    ScreenPreview("home", "${kotlinString(tab.label)} tab") { TabHost { HomeScreen(onItemClick = {}) } },`;
+  }
+  if (tab.slug === "profile") {
+    return `    ScreenPreview("profile", "${kotlinString(tab.label)} tab") { TabHost { ProfileScreen() } },`;
+  }
+  return `    ScreenPreview("${tab.slug}", "${kotlinString(tab.label)} tab") { TabHost { PlaceholderScreen(title = "${kotlinString(tab.label)}", titleTag = "${tab.slug}_title") } },`;
+}
+
+/**
+ * Render inspector/PreviewRegistry.kt (template-token form) — the `@Preview` analog the
+ * renderScreens harness enumerates: one shell entry wiring appTabs(...) like AppNavHost,
+ * one entry per tab, plus the shipped Detail destination. For the default tabs this
+ * reproduces the static template file byte-for-byte.
+ * @param {ReturnType<typeof tabInfos>} infos
+ */
+export function renderPreviewRegistryKt(infos) {
+  const imports = [
+    "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",
+  ];
+  if (infos.some((t) => t.slug !== "home" && t.slug !== "profile")) {
+    imports.push("import __PACKAGE__.presentation.components.PlaceholderScreen");
+  }
+  imports.push("import __PACKAGE__.presentation.home.DetailScreen");
+  if (infos.some((t) => t.slug === "home")) {
+    imports.push("import __PACKAGE__.presentation.home.HomeScreen");
+  }
+  imports.push("import __PACKAGE__.presentation.navigation.AppShell");
+  imports.push("import __PACKAGE__.presentation.navigation.appTabs");
+  if (infos.some((t) => t.slug === "profile")) {
+    imports.push("import __PACKAGE__.presentation.profile.ProfileScreen");
+  }
+
+  return `package __PACKAGE__.inspector
+
+${imports.join("\n")}
+
+/**
+ * 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(
+${infos.map(previewTabArg).join("\n")}
+            ),
+        )
+    },
+${infos.map(previewEntry).join("\n")}
+    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() }
+    }
+}
+`;
+}
+
 // --- pipeline entry --------------------------------------------------------------
 
 const APPTAB_REL =
@@ -325,6 +428,8 @@ const NAVHOST_REL =
   "composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppNavHost.kt";
 const PLACEHOLDER_REL =
   "composeApp/src/commonMain/kotlin/com/example/app/presentation/components/PlaceholderScreen.kt";
+const PREVIEW_REGISTRY_REL =
+  "composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewRegistry.kt";
 const SMOKE_REL = "qa/e2e/smoke.yaml";
 
 /**
@@ -362,6 +467,14 @@ export function rewriteTabSurfaces(projectDir, tabs, log = () => {}) {
     }
   }
 
+  // Present only when the inspector feature is on (the harness's desktopMain dir);
+  // absent → skipped, same contract as the other feature-stripped surfaces.
+  const previewRegistryPath = path.join(projectDir, PREVIEW_REGISTRY_REL);
+  if (fs.existsSync(previewRegistryPath)) {
+    fs.writeFileSync(previewRegistryPath, renderPreviewRegistryKt(infos));
+    log(`  tabs → ${PREVIEW_REGISTRY_REL}`);
+  }
+
   const smokePath = path.join(projectDir, SMOKE_REL);
   if (fs.existsSync(smokePath)) {
     fs.writeFileSync(smokePath, renderSmokeYaml(infos));

package/template/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent instructions
+
+This repository is agent-first. The full working contract — the definition of done
+(`node qa/verify.mjs` must PASS), the architecture gates, the testing pyramid, and the
+device-free **UI feedback loop** (render every real screen headlessly and see exactly
+what your edit changed) — lives in [CLAUDE.md](./CLAUDE.md).
+
+Read CLAUDE.md before making changes. It applies to every coding agent, not only Claude.

package/template/CLAUDE.md

@@ -52,6 +52,38 @@ invariants the conformance gates enforce.
 Commit it with your change — git history is the audit ledger. Binary artifacts under
 `qa-artifacts/` are hashed into the receipt; never commit them.
 
+## UI feedback loop — see what you build, without a device
+
+<!-- >>> cmp:feature inspector -->
+While building or changing ANY screen, use the preview loop instead of an emulator: it
+renders this app's REAL screens (real DI, real theme, seeded data) headlessly in seconds
+and tells you exactly what your edit changed.
+
+**With the create-cmp plugin (cmp-inspector MCP tools):**
+
+1. `preview { projectDir }` — once per session. Returns a live gallery URL (give it to
+   the human; it re-renders itself on every save) plus per-screen structural summaries
+   for you. Sources are watched; you never run Gradle by hand.
+2. After each edit: `preview_status { waitForRender: true }` — blocks until the
+   render/compile outcome. `changedLastRender` names the screens your edit touched
+   (empty = the edit reached no screen); `lastErrorSource: "compile"` means the edit
+   didn't even build (the compiler's `e:` lines are in `lastError`).
+3. `preview_diff { screen }` — one call proves the change: verdict `proven-clean` /
+   `changed-with-regressions` / `no-change`. No snapshot bookkeeping needed.
+
+**Without the plugin:** `./gradlew :composeApp:renderScreens` renders every screen to
+`composeApp/build/previews/<id>/{screen.png, tree.json}` (`-Pscreen=<id>` for one);
+`node qa/preview-gallery.mjs` builds a self-contained gallery page from the output.
+
+Screens come from `inspector/PreviewRegistry.kt` (desktopMain). **When you add a screen,
+register it there** — a forced-state variant is just another entry (`"home@empty"`).
+Assert on the `tree.json` structure; never read PNG bytes (pixels are for humans).
+<!-- <<< cmp:feature inspector -->
+<!-- >>> cmp:feature dev-client -->
+For one interactive window instead of stills of every screen:
+`./gradlew :composeApp:hotRunDesktop --auto` (Compose Hot Reload dev-client).
+<!-- <<< cmp:feature dev-client -->
+
 ## Docs
 
 [`README.md`](./README.md) (front page) · [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)

package/template/README.md

@@ -17,6 +17,11 @@ follow the contract in [`CLAUDE.md`](./CLAUDE.md).
 ./gradlew :composeApp:hotRunDesktop --auto
 <!-- <<< cmp:feature dev-client -->
 
+<!-- >>> cmp:feature inspector -->
+# Preview EVERY screen headlessly — no device, no emulator (agents: CLAUDE.md "UI feedback loop")
+./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs
+<!-- <<< cmp:feature inspector -->
+
 # Unit tests (fast inner loop)
 ./gradlew :composeApp:desktopTest
 

package/template/composeApp/build.gradle.kts

@@ -136,6 +136,13 @@ kotlin {
                 implementation(compose.desktop.currentOs)
                 implementation(libs.kotlinx.coroutines.swing)
                 implementation(libs.ktor.client.cio)
+                // >>> cmp:feature inspector
+                // Headless semantics API (runDesktopComposeUiTest / onRoot) for the preview
+                // harness (inspector/PreviewHarness.kt) — renders real screens with no window.
+                // Desktop is a dev-only target, so shipping the test artifact here is deliberate.
+                @OptIn(org.jetbrains.compose.ExperimentalComposeLibrary::class)
+                implementation(compose.uiTest)
+                // <<< cmp:feature inspector
             }
         }
 
@@ -275,6 +282,52 @@ compose.desktop {
 }
 // <<< cmp:feature dev-client
 
+// >>> cmp:feature inspector
+// Headless screen previews — the project-wired tier-0 loop of the create-cmp inspector.
+// Renders every screen in inspector/PreviewRegistry.kt (real DI, real theme, real data)
+// to build/previews/<id>/{screen.png, tree.json} with NO device, emulator, or window,
+// then qa/preview-gallery.mjs turns the output into one self-contained index.html:
+//
+//   ./gradlew :composeApp:renderScreens                      # all screens
+//   ./gradlew :composeApp:renderScreens -Pscreen=home        # one screen
+//   node qa/preview-gallery.mjs                              # build the gallery
+//
+// Parameters travel as -P properties -> system properties, NEVER via --args (Gradle's CLI
+// parsing splits space-separated --args values into task names).
+tasks.register<JavaExec>("renderScreens") {
+    group = "verification"
+    description = "Render registered screens headlessly to PNG + inspector-contract tree JSON."
+    val desktopCompilation = kotlin.targets.getByName("desktop").compilations.getByName("main")
+    classpath(desktopCompilation.output.allOutputs, desktopCompilation.runtimeDependencyFiles)
+    mainClass.set("__PACKAGE__.inspector.PreviewHarnessKt")
+    systemProperty("java.awt.headless", "true")
+    systemProperty("screen", providers.gradleProperty("screen").getOrElse("all"))
+    systemProperty(
+        "out",
+        providers.gradleProperty("previewOut")
+            .getOrElse(layout.buildDirectory.dir("previews").get().asFile.absolutePath),
+    )
+    systemProperty("pngScale", providers.gradleProperty("pngScale").getOrElse("2"))
+}
+
+// Resident preview daemon (phase 2): a long-lived headless JVM serving /render on
+// 127.0.0.1:9601 so warm re-renders skip the task cycle. Preferred launch is under
+// Compose Hot Reload (saves hot-swap into the running daemon; needs the dev-client
+// feature's Compose Hot Reload plugin):
+//
+//   ./gradlew :composeApp:hotRunDesktop --mainClass=__PACKAGE__.inspector.PreviewDaemonKt --auto
+//
+// This plain variant runs on any JDK with no hot swap (restart to pick up new code):
+tasks.register<JavaExec>("runPreviewDaemon") {
+    group = "verification"
+    description = "Run the resident preview daemon (loopback HTTP /render, no hot reload)."
+    val desktopCompilation = kotlin.targets.getByName("desktop").compilations.getByName("main")
+    classpath(desktopCompilation.output.allOutputs, desktopCompilation.runtimeDependencyFiles)
+    mainClass.set("__PACKAGE__.inspector.PreviewDaemonKt")
+    systemProperty("java.awt.headless", "true")
+}
+// <<< cmp:feature inspector
+
 // Evidence integrity: golden-tree baselines (qa/golden) and the UPDATE_GOLDEN capture flag are
 // REAL inputs of the JVM test tier, but Gradle can't see either on its own — baselines are read
 // at runtime, not compiled, and env vars aren't tracked. Undeclared, the build cache will happily

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