cmp-preview

cmp-preview — live previews of real screens, zero commands

Your job: give the human a live gallery URL of their app's real screens and keep it current while they (or you) edit code — and use the structural side of the same render to verify changes. Nobody runs Gradle by hand; the MCP service owns the loop.

Before anything: confirm the capability (fail loud)

The cmp-inspector MCP tools are a capability, not a given. Before your first call, confirm they resolve (ToolSearch for "cmp-inspector"). If no tools match, STOP — do not fall back to manual Gradle, screenshots, or raw adb silently. Diagnose in order and REPORT to the human:

1. Plugin enabled? Check enabledPlugins in ~/.claude/settings.json (or the project's .claude/settings.json).
2. Session older than the plugin's enablement? MCP servers attach at session START — a session born without the plugin never gains its tools, and no amount of in-session retrying will surface them. The fix is restarting the session.
3. Plugin copy stale or server broken? Run cmp-doctor's inspector-MCP check group.

Only after reporting may the documented degraded path (./gradlew :composeApp:renderScreens

• node qa/preview-gallery.mjs) be used — and the report must name what is lost: on-save re-render, changed-screen attribution, and the preview_diff change proof.

The one-call flow

1. preview { projectDir } (cmp-inspector MCP) — starts (or reuses) the resident service. It:
   • renders every inspector/PreviewRegistry.kt entry headlessly via the app's generated :composeApp:renderScreens task (real Koin DI, real theme, real data);
   • serves the live gallery at the returned url (default http://127.0.0.1:9600/);
   • watches composeApp/src/** — every save re-renders (debounced, serialized) and the page reloads itself via SSE, with changed screens flagged CHANGED. 1b. Phase 2 runs automatically (hot, default true): the service boots a resident preview daemon under Compose Hot Reload (hotRunDesktop --mainClass=<pkg>.inspector.PreviewDaemonKt --auto, JBR auto-provisioned). Saving a file recompiles incrementally and hot-swaps classes INTO the running JVM; renders go through the daemon's loopback /render — measured on a real app: ~900ms for one screen, ~7s for all seven, ~10s save→gallery-shows-the-change (vs 25–40s per change on the task path). If the daemon can't boot (no dev-client feature/hot-reload plugin, no JBR) the service transparently stays on the Gradle path — same gallery, slower loop.
2. Hand the human the url (open it for them if you can, e.g. open <url> on macOS, or the host's browser surface). That's their whole workflow: edit → save → watch the gallery update. First render includes a Gradle compile (tens of seconds); warm saves re-render in a few seconds.
3. You work structurally — after every edit, ONE call: preview_status { waitForRender: true }. It blocks until the render (or the recompile) finishes and returns changedLastRender (empty = your edit reached no screen), lastError/lastErrorSource ("compile" = your edit didn't even build — the daemon surfaces hot-recompile failures, you are NOT flying blind), and screens: [{ id, nodes, tokenized, tagged, a11yPass, a11yViolations, lastChangedVersion, tree, png }]. No HTTP polling, no sleeps. Assert deeper on the tree paths with inspect_tree (pass testTag for one subtree) — never read PNGs.
4. preview_stop {} when the session is done (the Gradle daemon stays warm — good).