create-cmp-cli 0.9.0 → 0.10.0

package/README.md

@@ -64,6 +64,22 @@ accessibility, on-device E2E — and writes a receipt bound to a content hash of
 verified. The Stop hook and CI both check that receipt. You cannot hand-forge it, and a stale one
 doesn't pass.
 
+## Watch and drive your app live — from a browser
+
+Every debug build carries a live device view. With the app running on a device or emulator
+(`adb forward tcp:9500 tcp:9500`, or just `connect_live` from the plugin), open:
+
+```
+http://127.0.0.1:9500/inspect/remote
+```
+
+A self-contained page mirrors the running app (~700ms refresh) and **click-to-tap drives the
+real thing** — clicks scale to device pixels and dispatch as taps. This is the "two audiences,
+one app" split at its purest: the human watches and drives real pixels in a browser while the
+agent asserts on the semantics tree (`navigate_and_inspect`, `prove_change`, `db_query`). Use
+it to watch an e2e run, demo a feature, or poke at the app without touching the device. No
+install, no CORS, debug builds only — release builds contain none of this code.
+
 ## Quick start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Create production mobile apps (Android + iOS, one Kotlin codebase) with AI — the delivery harness for Compose Multiplatform, the current generation of cross-platform (Google-backed KMP, iOS stable since May 2025). A deterministic, non-interactive generator that scaffolds a green-building app 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": {

package/src/lib/tabs.mjs

@@ -166,6 +166,12 @@ export function renderSmokeYaml(infos) {
 # AppShell.kt's navItemTag (lowercase, non-[a-z0-9] runs collapsed to "_", trimmed);
 # keep these ids in sync with it if the configured tabs change.
 #
+# SETTLE RULE for the behaviour steps you add: any assertion that follows an interaction
+# triggering an async state change (search input, a toggle that persists, a load) must use
+# extendedWaitUntil — the ViewModel round-trip passes through a brief Loading arm, and a
+# lane-loaded emulator stretches that window past a bare assert's patience (a real false
+# red from the field). Bare assertVisible is for static post-navigation elements only.
+#
 # Run:  maestro test qa/e2e/smoke.yaml      (device/emulator attached)
 # The verify lane's e2eSmoke step runs this automatically when maestro + a device are present.
 appId: __PACKAGE__

package/template/CLAUDE.md

@@ -101,22 +101,33 @@ human decision. The ordered walk is a **definition order**, not just an approval
 each artifact is the vocabulary the next is written in, so on a fresh app each step is a
 conversation that ends in an approval — the genesis walk, six conversations:
 
+The order encodes two disciplines: **behavior is spec-first** (the exemplar's clauses are
+confirmed before the slice is built) and **visuals are UI-first** (the design system and
+component vocabulary are distilled from the real screens, so they lock after the exemplar —
+a provisional palette carries the build until then).
+
 0. **Intent** — `specs/intent.md`, the root brief everything else traces to (purpose,
    audience, platforms, brand feel, reference apps, first screens, **glossary**). Filled by
    the `cmp-new` interview; the seed's placeholder prose is marked unfilled. Its
    `## Glossary` section is lifted verbatim into `docs/ARCHITECTURE.md` §8 — write it there
    in the exact form you want published.
-1. **Design system** — `presentation/theme/Theme.kt`, `presentation/theme/Tokens.kt`.
-2. **Architecture + structure** — `specs/app-base.spec.md` **and**
+1. **Architecture + structure** — `specs/app-base.spec.md` **and**
    [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) (`cmp:generated` sections stripped
    before hashing, so a mechanical regeneration never invalidates the approval — only an
    authored-prose edit does).
-3. **Components** — every `presentation/components/*.kt` (a dynamic, sorted glob). Once
+2. **Exemplar spec** — `specs/<exemplar>.spec.md`. Confirmed BEFORE the slice is built:
+   propose the clauses, get the human's yes, then implement to satisfy them (the same
+   discipline `add-feature` already enforces post-genesis).
+3. **Exemplar feature** — the **configured** exemplar's file set the `add-feature`
+   stamper clones from (see "Configurable exemplar"), built to the confirmed spec.
+4. **Design system** — `presentation/theme/Theme.kt`, `presentation/theme/Tokens.kt`.
+   Locked on the REAL exemplar: candidates render on real screens, never stubs. If the
+   lock changes the exemplar's look, reopen → re-approve it — that loop is the design,
+   not a failure.
+5. **Components** — every `presentation/components/*.kt` (a dynamic, sorted glob),
+   distilled from the screens per the inclusion rubric (`docs/ARCHITECTURE.md` §7). Once
    approved, the registry is law: adding or changing a common component invalidates the
    approval until a human re-approves.
-4. **Exemplar feature** — the **configured** exemplar's 11-file set the `add-feature`
-   stamper clones from (see "Configurable exemplar").
-5. **Exemplar spec** — `specs/<exemplar>.spec.md`.
 6. **Per-feature spec** — `specs/<feature>.spec.md`, one governed artifact per feature,
    added as features land.
 
@@ -220,6 +231,13 @@ and tells you what your edit changed.
 `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.
 
+**Live tier — the human's live device view (standing step).** Whenever `connect_live`
+succeeds, OFFER the `remoteUrl` it returns (`http://127.0.0.1:9500/inspect/remote`) to the
+human — every time, not as a maybe. It is a self-contained browser page that mirrors the
+running app (~700ms refresh) with click-to-tap driving the real device: they watch and drive
+the actual app while you assert on the tree (`navigate_and_inspect` / `prove_change` /
+`db_query`). It is also the right way for a human to *watch* an e2e run.
+
 Screens come from `inspector/PreviewRegistry.kt` (desktopMain). The `add-feature` and
 `add-screen` stampers auto-register stamped screens at the `// cmp:anchor preview-registry`
 marker; when you add a screen by hand, register it there — a forced-state variant is just

package/template/README.md

@@ -29,6 +29,15 @@ follow the contract in [`CLAUDE.md`](./CLAUDE.md).
 node qa/verify.mjs
 ```
 
+<!-- >>> cmp:feature inspector -->
+**Watch and drive the app live from a browser:** with a debug build running on a
+device/emulator, run `adb forward tcp:9500 tcp:9500` and open
+`http://127.0.0.1:9500/inspect/remote` — a self-contained page that mirrors the running app
+(~700ms refresh) with **click-to-tap driving the real device**. The human's window into the
+same app the agent inspects structurally; also the way to watch an e2e run. Debug builds
+only — release builds contain no inspector code.
+<!-- <<< cmp:feature inspector -->
+
 <!-- >>> cmp:feature ios -->
 **iOS:** `cd iosApp && xcodegen generate && pod install`, then open
 `iosApp.xcworkspace` in Xcode and run. (First time: `brew install xcodegen`.)

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/InspectorCatalog.kt

@@ -5,9 +5,12 @@ import androidx.compose.ui.graphics.toArgb
 import androidx.compose.ui.unit.Dp
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
 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 kotlinx.serialization.json.put
 
@@ -57,6 +60,22 @@ object InspectorCatalog {
                 put("RadiusModal", __THEME_PREFIX__Tokens.RadiusModal.token())
                 put("RadiusInput", __THEME_PREFIX__Tokens.RadiusInput.token())
             })
+            // The type ramp, from the same ramp data the Typography factory builds
+            // its styles from — so the LIVE tier answers with the same block the
+            // headless preview catalog writes, and the console renders one ramp
+            // whichever tier it read.
+            put("typography", buildJsonArray {
+                __THEME_PREFIX__TypeRamp.forEach { spec ->
+                    add(buildJsonObject {
+                        put("name", spec.name)
+                        put("weight", spec.weight)
+                        put("size", "${spec.sizeSp}sp")
+                        put("lineHeight", "${spec.lineHeightSp}sp")
+                        val tracking = spec.tracking
+                        if (tracking == null) put("tracking", JsonNull) else put("tracking", "${tracking}sp")
+                    })
+                }
+            })
         }
         return prettyJson.encodeToString(JsonElement.serializer(), doc)
     }

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/InspectorHttpServer.kt

@@ -1,13 +1,20 @@
 package __PACKAGE__.inspector
 
+import android.app.Activity
 import android.content.Context
+import android.content.ContextWrapper
 import android.graphics.Bitmap
 import android.graphics.Canvas
+import android.graphics.Rect
+import android.os.Build
 import android.os.Handler
 import android.os.Looper
 import android.os.SystemClock
 import android.util.Log
 import android.view.MotionEvent
+import android.view.PixelCopy
+import android.view.View
+import android.view.Window
 import androidx.core.view.drawToBitmap
 import java.io.BufferedReader
 import java.io.ByteArrayOutputStream
@@ -149,6 +156,11 @@ object InspectorHttpServer {
                 tapResponse(readBody(reader, contentLength)).let { (s, b) -> writeJson(client, s, b) }
             method == "GET" && path == "/inspect/nav" ->
                 writeJson(client, 200, navJson())
+            // The JUMP half of the nav seam (the read half is /inspect/nav above): coverage
+            // by route, not by synthesized taps. GET (not POST) deliberately — it is
+            // idempotent-ish debug tooling meant to be curl-able, like everything else here.
+            method == "GET" && path == "/inspect/navigate" ->
+                navigateResponse(query).let { (s, b) -> writeJson(client, s, b) }
             method == "GET" && path == "/inspect/crashes" ->
                 writeJson(client, 200, crashesJson())
             method == "GET" && path == "/inspect/db" ->
@@ -177,8 +189,35 @@ object InspectorHttpServer {
         return String(buf, 0, read)
     }
 
-    private fun healthJson(appId: String): String =
-        """{"status":"ok","schemaVersion":1,"source":"live-android","appId":${JsonPrimitive(appId)},"buildType":"debug"}"""
+    private fun healthJson(appId: String): String {
+        // Process start as epoch millis: elapsedRealtime anchors the boot clock to the wall
+        // clock. This is the DETERMINISM primitive — an external relaunch (force-stop +
+        // launch) is VERIFIED by this value moving forward, so a walk can prove it started
+        // from a fresh process instead of trusting that a retained ViewModel isn't lurking.
+        val startedAtMs = System.currentTimeMillis() - android.os.SystemClock.elapsedRealtime() +
+            android.os.Process.getStartElapsedRealtime()
+        return """{"status":"ok","schemaVersion":1,"source":"live-android","appId":${JsonPrimitive(appId)},"buildType":"debug",""" +
+            """"processStartedAtMs":$startedAtMs,"processUptimeMs":${android.os.SystemClock.elapsedRealtime() - android.os.Process.getStartElapsedRealtime()}}"""
+    }
+
+    private fun navigateResponse(query: String): Pair<Int, String> {
+        val route = query.split('&')
+            .firstOrNull { it.startsWith("route=") }
+            ?.substringAfter('=')
+            ?.let { java.net.URLDecoder.decode(it, "UTF-8") }
+            ?.takeIf { it.isNotBlank() }
+            ?: return 400 to errorJson("missing route parameter — /inspect/navigate?route=<route>")
+        val error = NavInspector.navigate(route)
+        return if (error == null) {
+            200 to """{"ok":true,"route":${JsonPrimitive(route)}}"""
+        } else if (error.startsWith("nav host not composed")) {
+            503 to errorJson(error)
+        } else if (error.startsWith("unknown route")) {
+            404 to errorJson(error)
+        } else {
+            500 to errorJson(error)
+        }
+    }
 
     private fun treeResponse(): Pair<Int, String> {
         val root = ComposeRootRegistry.current()
@@ -251,9 +290,18 @@ object InspectorHttpServer {
         }
 
     /**
-     * PNG of the current Compose root. The Bitmap is rendered on the MAIN thread (views are
-     * not thread-safe); PNG compression — tens of ms for a full screen — happens back on the
-     * server thread so the UI never pays for it.
+     * PNG of the current Compose root. Pixels are read with [PixelCopy] (API 26+) from the
+     * COMPOSITED window surface — the same source `adb screencap` reads — so a capture can
+     * never replay a stale Compose layer recording. The software fallback (`View.draw` into a
+     * bitmap canvas) replays recorded display lists, and a nav-transition `graphicsLayer`
+     * whose recording predates the current frame replays the PREVIOUS screen: byte-identical
+     * "screenshots" of two different screens, detectable only by hash-compare. PixelCopy is
+     * therefore the primary path; the draw fallback remains for pre-26, windowless roots, and
+     * dialog/popup roots (their content lives in a different window than the Activity's).
+     *
+     * The capture runs on the MAIN thread (views are not thread-safe; PixelCopy's listener is
+     * delivered there too); PNG compression — tens of ms for a full screen — happens back on
+     * the server thread so the UI never pays for it.
      */
     private fun screenshotResponse(client: Socket) {
         val root = ComposeRootRegistry.current()
@@ -267,22 +315,35 @@ object InspectorHttpServer {
         val bitmapRef = AtomicReference<Bitmap?>()
         val errorRef = AtomicReference<String?>()
         val latch = CountDownLatch(1)
-        Handler(Looper.getMainLooper()).post {
+        val main = Handler(Looper.getMainLooper())
+        main.post {
             try {
                 val view = root.view
-                bitmapRef.set(
-                    try {
-                        // androidx.core.view.drawToBitmap (core-ktx — already an androidMain dep).
-                        view.drawToBitmap()
-                    } catch (t: Throwable) {
-                        // Not laid out yet / hardware path refused — plain Canvas draw fallback.
-                        Bitmap.createBitmap(
-                            view.width.coerceAtLeast(1),
-                            view.height.coerceAtLeast(1),
-                            Bitmap.Config.ARGB_8888,
-                        ).also { view.draw(Canvas(it)) }
-                    }
-                )
+                // PixelCopy only when this root actually lives in the Activity's window —
+                // a dialog/popup root has its own window, and copying the Activity's would
+                // capture the screen BENEATH it. Those fall back to the software draw.
+                val window = windowOf(view)?.takeIf { it.decorView === view.rootView }
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && window != null) {
+                    val loc = IntArray(2).also(view::getLocationInWindow)
+                    val bmp = Bitmap.createBitmap(
+                        view.width.coerceAtLeast(1),
+                        view.height.coerceAtLeast(1),
+                        Bitmap.Config.ARGB_8888,
+                    )
+                    val src = Rect(loc[0], loc[1], loc[0] + bmp.width, loc[1] + bmp.height)
+                    PixelCopy.request(window, src, bmp, { result ->
+                        try {
+                            // No composited frame to copy (mid-transition, surface torn down):
+                            // fall back rather than fail — a fallback frame beats no frame.
+                            bitmapRef.set(if (result == PixelCopy.SUCCESS) bmp else softwareDraw(view))
+                        } catch (t: Throwable) {
+                            errorRef.set("failed to render screenshot: ${t.message}")
+                        }
+                        latch.countDown()
+                    }, main)
+                    return@post // countDown happens in the PixelCopy listener above
+                }
+                bitmapRef.set(softwareDraw(view))
             } catch (t: Throwable) {
                 errorRef.set("failed to render screenshot: ${t.message}")
             }
@@ -309,6 +370,34 @@ object InspectorHttpServer {
         writeResponse(client, 200, bytes, PNG_TYPE)
     }
 
+    /** The view's host [Window], unwrapped through the ContextWrapper chain. MAIN thread. */
+    private fun windowOf(view: View): Window? {
+        var ctx = view.context
+        while (ctx is ContextWrapper) {
+            if (ctx is Activity) return ctx.window
+            ctx = ctx.baseContext
+        }
+        return null
+    }
+
+    /**
+     * Software-canvas capture — re-issues the view's draw. Correct for laid-out static content,
+     * but can replay a stale `graphicsLayer` recording mid-transition (see [screenshotResponse]);
+     * used only where PixelCopy can't be (pre-API-26, windowless, or dialog roots). MAIN thread.
+     */
+    private fun softwareDraw(view: View): Bitmap =
+        try {
+            // androidx.core.view.drawToBitmap (core-ktx — already an androidMain dep).
+            view.drawToBitmap()
+        } catch (t: Throwable) {
+            // Not laid out yet / hardware path refused — plain Canvas draw fallback.
+            Bitmap.createBitmap(
+                view.width.coerceAtLeast(1),
+                view.height.coerceAtLeast(1),
+                Bitmap.Config.ARGB_8888,
+            ).also { view.draw(Canvas(it)) }
+        }
+
     /**
      * Dispatch a synthetic tap (ACTION_DOWN, then ACTION_UP ~50ms later) to the topmost
      * Compose root, on the MAIN thread. Coordinates are root-relative px — exactly the

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/LiveSemanticsJson.kt

@@ -26,6 +26,9 @@ import kotlin.math.roundToInt
  *  - `role`      string|null — [SemanticsProperties.Role] (e.g. "Button").
  *  - `clickable` boolean     — presence of [SemanticsActions.OnClick].
  *  - `disabled`  boolean     — presence of [SemanticsProperties.Disabled].
+ *  - `size`      {width,height} — the FULL composed (unclipped) size; `bounds` is the visible
+ *                slice after ancestor clipping (a scroll fold truncates it). The a11y audit
+ *                judges touch targets on `size` so fold-clipped rows never false-flag.
  */
 object LiveSemanticsJson {
 
@@ -49,6 +52,7 @@ object LiveSemanticsJson {
         put("clickable", JsonPrimitive(node.isClickable()))
         put("disabled", JsonPrimitive(node.isDisabled()))
         put("bounds", node.boundsJson())
+        put("size", node.sizeJson())
         put("designToken", node.designTokenJson())
         put("children", buildJsonArray {
             node.children.forEach { add(nodeToJson(it)) }
@@ -87,6 +91,12 @@ object LiveSemanticsJson {
         }
     }
 
+    /** Full composed (unclipped) size — see the class doc's `size` contract note. */
+    private fun SemanticsNode.sizeJson(): JsonObject = buildJsonObject {
+        put("width", JsonPrimitive(size.width))
+        put("height", JsonPrimitive(size.height))
+    }
+
     private fun SemanticsNode.designTokenJson(): JsonElement {
         val info = config.getOrNull(DesignTokenKey) ?: return JsonNull
         return buildJsonObject {

package/template/composeApp/src/androidDebug/kotlin/com/example/app/inspector/NavInspector.kt

@@ -28,4 +28,35 @@ object NavInspector {
     }
 
     fun current(): Snapshot = state.get()
+
+    /**
+     * The jump half (`GET /inspect/navigate?route=…`): request navigation to [route] on the
+     * main thread and wait (bounded) for the outcome. Coverage tool, not a behaviour proof —
+     * see [NavInspectionHook.navigator]. Outcomes are honest, never fabricated:
+     *  - `null` on success (the NavController accepted the route);
+     *  - a message when no navigator is registered (nav host not composed yet — retry), when
+     *    the route is unknown (NavController's own IllegalArgumentException, surfaced
+     *    verbatim), or when the main thread didn't get to it in time.
+     */
+    fun navigate(route: String, timeoutMs: Long = 5_000): String? {
+        val error = java.util.concurrent.atomic.AtomicReference<String?>(null)
+        val latch = java.util.concurrent.CountDownLatch(1)
+        android.os.Handler(android.os.Looper.getMainLooper()).post {
+            val nav = NavInspectionHook.navigator
+            if (nav == null) {
+                error.set("nav host not composed yet — no navigator registered. Retry shortly.")
+            } else {
+                try {
+                    nav(route)
+                } catch (e: IllegalArgumentException) {
+                    error.set("unknown route ${'"'}$route${'"'} — ${e.message}")
+                }
+            }
+            latch.countDown()
+        }
+        if (!latch.await(timeoutMs, java.util.concurrent.TimeUnit.MILLISECONDS)) {
+            return "main thread did not service the navigation within ${timeoutMs}ms"
+        }
+        return error.get()
+    }
 }

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/brand/BrandMark.kt

@@ -0,0 +1,75 @@
+package __PACKAGE__.presentation.brand
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
+
+// The app's brand mark — a guided placeholder, not final art. Brand is its own governed
+// category (presentation/brand/, distinct from the components registry): identity, not
+// design-system vocabulary. This starter renders a theme-tinted badge with the app's
+// initial plus a wordmark, so "we need a logo" has a home from day one. Replace the badge
+// with a DRAWN mark (Canvas paths — see how a real one is built: a shape punched out of
+// the badge, scaled from a unit box) when the identity lands; keep the testTags.
+
+private const val APP_NAME = "__APP_NAME__"
+
+/** The badge alone — compact header, avatar seats, launcher-adjacent surfaces. */
+@Composable
+fun BrandMark(
+    modifier: Modifier = Modifier,
+    size: Dp = 32.dp,
+) {
+    Box(
+        modifier = modifier
+            .size(size)
+            .clip(RoundedCornerShape(size * 0.28f))
+            .background(__THEME_PREFIX__Colors.Primary)
+            .semantics { testTag = "brand_mark"; contentDescription = APP_NAME },
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(
+            text = APP_NAME.trim().take(1).uppercase(),
+            style = MaterialTheme.typography.titleLarge,
+            fontWeight = FontWeight.Bold,
+            color = __THEME_PREFIX__Colors.OnPrimary,
+        )
+    }
+}
+
+/** Badge + wordmark, for headers and about/launch surfaces. */
+@Composable
+fun BrandWordmark(
+    modifier: Modifier = Modifier,
+    markSize: Dp = 28.dp,
+) {
+    Row(
+        modifier = modifier.semantics { testTag = "brand_wordmark" },
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        BrandMark(size = markSize)
+        Spacer(Modifier.width(10.dp))
+        Text(
+            text = APP_NAME,
+            style = MaterialTheme.typography.titleLarge,
+            fontWeight = FontWeight.Bold,
+            color = MaterialTheme.colorScheme.onSurface,
+        )
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppButton.kt

@@ -30,9 +30,9 @@ fun AppPrimaryButton(
 }
 
 /**
- * The low-emphasis text button, with the same 48 dp floor as [AppPrimaryButton]. These
- * two are the registry's only buttons — a new variant (icon, loading, destructive, FAB)
- * is a registry addition a human approves, not a local tweak.
+ * The low-emphasis text button, with the same 48 dp floor as [AppPrimaryButton]. The
+ * registry's buttons are these two plus [AppIconButton] — a new variant (loading,
+ * destructive, FAB) is a registry addition a human approves, not a local tweak.
  */
 @Composable
 fun AppTextButton(

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppHeader.kt

@@ -4,6 +4,8 @@ import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.RowScope
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
@@ -20,6 +22,11 @@ import androidx.compose.ui.unit.dp
  * handling (`BaseScreen` owns insets, SHELL-03). A collapsing toolbar would be a
  * registry addition, not a default.
  *
+ * The back affordance is a Material icon button with the auto-mirrored arrow
+ * (RTL-correct), via [AppIconButton] so the 48 dp touch-target floor holds by
+ * construction — never a text link. It renders only when [onBack] is non-null, so a tab
+ * root never shows a back control.
+ *
  * @param title Headline text, rendered in `headlineMedium`.
  * @param screenTag Feature slug; derives the `<screenTag>_title` and `<screenTag>_back` tags.
  * @param onBack Non-null renders a 48 dp back affordance left of the title.
@@ -38,9 +45,11 @@ fun AppHeader(
         verticalAlignment = Alignment.CenterVertically,
     ) {
         if (onBack != null) {
-            AppTextButton(
-                text = "← Back",
+            AppIconButton(
+                icon = Icons.AutoMirrored.Filled.ArrowBack,
+                contentDescription = "Back",
                 onClick = onBack,
+                tint = MaterialTheme.colorScheme.onSurface,
                 modifier = Modifier.semantics { testTag = "${screenTag}_back" },
             )
         }

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppIconButton.kt

@@ -0,0 +1,48 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.size
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.LocalContentColor
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.vector.ImageVector
+
+/**
+ * The registry's icon button: M3 `IconButton` held to the 48 dp touch-target floor.
+ *
+ * Stock M3 `IconButton` defaults to a 40x40 dp target — below WCAG 2.2 SC 2.5.8 and this
+ * harness's own `audit_a11y` bar — so every raw use is a violation waiting to be measured
+ * (and historically why a text link masqueraded as a back button). This wrapper clears the
+ * floor once, by construction, the same way [AppPrimaryButton] does for filled buttons.
+ *
+ * A [contentDescription] is REQUIRED, not defaulted: an icon-only control with no label is
+ * invisible to screen readers (`missing-label` in the same audit). Pass what the control
+ * does ("Back", "Add entry"), never what the icon looks like.
+ *
+ * @param icon The vector to render (e.g. `Icons.AutoMirrored.Filled.ArrowBack`).
+ * @param contentDescription What the control does, for screen readers.
+ * @param tint Icon tint; defaults to the current content color.
+ */
+@Composable
+fun AppIconButton(
+    icon: ImageVector,
+    contentDescription: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+    tint: Color = Color.Unspecified,
+) {
+    IconButton(
+        onClick = onClick,
+        enabled = enabled,
+        modifier = modifier.size(AppButtonDefaults.MinTouchTarget),
+    ) {
+        Icon(
+            imageVector = icon,
+            contentDescription = contentDescription,
+            tint = if (tint == Color.Unspecified) LocalContentColor.current else tint,
+        )
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppNavHost.kt

@@ -21,11 +21,20 @@ fun AppNavHost() {
     // androidDebug inspector registered a listener (see NavInspectionHook.kt). Best-effort:
     // `currentBackStack` is a live snapshot, not a durable history.
     LaunchedEffect(navController) {
-        navController.currentBackStack.collect { stack ->
-            NavInspectionHook.listener?.invoke(
-                navController.currentDestination?.route,
-                stack.mapNotNull { it.destination.route },
-            )
+        // The jump half of the same seam: lets the debug inspector navigate by route
+        // (its navigate endpoint) so walkthrough coverage enumerates the graph instead of
+        // synthesizing taps. Registered/cleared with the controller's composition lifetime;
+        // NavController rejects unknown routes itself (IllegalArgumentException).
+        NavInspectionHook.navigator = { route -> navController.navigate(route) }
+        try {
+            navController.currentBackStack.collect { stack ->
+                NavInspectionHook.listener?.invoke(
+                    navController.currentDestination?.route,
+                    stack.mapNotNull { it.destination.route },
+                )
+            }
+        } finally {
+            NavInspectionHook.navigator = null
         }
     }
 

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/NavInspectionHook.kt

@@ -18,4 +18,14 @@ object NavInspectionHook {
      * durable history).
      */
     var listener: ((currentRoute: String?, backStack: List<String>) -> Unit)? = null
+
+    /**
+     * The JUMP half of the seam: [AppNavHost] registers a function that navigates the real
+     * `NavController` to a route. Debug-only callers (the debug inspector's navigate endpoint) use it
+     * so a walkthrough can enumerate the nav graph mechanically — coverage by route-jump —
+     * instead of synthesizing taps with guessed settle times. Taps remain the tool for
+     * BEHAVIOUR proofs (a toggle, a search); this is for COVERAGE. `null` outside debug
+     * inspection, and must only ever be invoked on the main thread (NavController requirement).
+     */
+    var navigator: ((route: String) -> Unit)? = null
 }