create-cmp-cli 0.8.0 → 0.10.0

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

@@ -0,0 +1,99 @@
+package __PACKAGE__.inspector
+
+import android.content.Context
+import android.util.Log
+import java.io.File
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+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
+
+/**
+ * Debug-only crash capture: [install] sets a process-wide
+ * [Thread.UncaughtExceptionHandler] that persists crash JSON to
+ * `filesDir/inspector/crashes/` (bounded to the last [MAX_CRASHES]) so a crash survives the
+ * process death that follows it — an in-memory ring buffer would not.
+ *
+ * MUST NEVER SWALLOW THE CRASH: after persisting, it always hands off to whatever handler was
+ * installed before it (chained, not replaced) so system crash dialogs, `System.exit`, and any
+ * other crash-reporting tool still behave exactly as if this class did not exist.
+ */
+object CrashRecorder {
+
+    private const val TAG = "CmpInspector"
+    private const val MAX_CRASHES = 20
+
+    fun install(context: Context) {
+        val crashDir = File(context.filesDir, "inspector/crashes").apply { mkdirs() }
+        val previous = Thread.getDefaultUncaughtExceptionHandler()
+        Thread.setDefaultUncaughtExceptionHandler { thread, throwable ->
+            try {
+                persist(crashDir, throwable)
+            } catch (t: Throwable) {
+                // Persisting the crash record must never itself crash the crash handler.
+                Log.w(TAG, "failed to persist crash record", t)
+            } finally {
+                if (previous != null) {
+                    previous.uncaughtException(thread, throwable)
+                } else {
+                    // No previous handler installed: fall back to the JVM's own default so the
+                    // process still dies the normal way instead of hanging.
+                    Runtime.getRuntime().exit(10)
+                }
+            }
+        }
+    }
+
+    private fun persist(crashDir: File, throwable: Throwable) {
+        val doc = buildJsonObject {
+            put("timestamp", JsonPrimitive(isoNow()))
+            put("exception", JsonPrimitive(throwable::class.qualifiedName ?: throwable.javaClass.name))
+            put("message", throwable.message?.let { JsonPrimitive(it) } ?: JsonNull)
+            put("frames", buildJsonArray {
+                throwable.stackTrace.forEach { el ->
+                    add(buildJsonObject {
+                        put("className", JsonPrimitive(el.className))
+                        put("methodName", JsonPrimitive(el.methodName))
+                        put("fileName", el.fileName?.let { JsonPrimitive(it) } ?: JsonNull)
+                        put("lineNumber", JsonPrimitive(el.lineNumber))
+                    })
+                }
+            })
+        }
+        File(crashDir, "crash-${System.currentTimeMillis()}.json")
+            .writeText(Json.encodeToString(JsonElement.serializer(), doc))
+        prune(crashDir)
+    }
+
+    /** Keep only the most recent [MAX_CRASHES] crash files (current boot + previous ones). */
+    private fun prune(crashDir: File) {
+        val files = crashDir.listFiles { f -> f.isFile && f.name.endsWith(".json") } ?: return
+        if (files.size <= MAX_CRASHES) return
+        files.sortedBy { it.lastModified() }
+            .take(files.size - MAX_CRASHES)
+            .forEach { it.delete() }
+    }
+
+    /**
+     * Every persisted crash's raw JSON text, newest first — spans the current boot AND any
+     * previous ones ([install] never clears the directory, only [prune] bounds it).
+     */
+    fun readAll(context: Context): List<String> {
+        val crashDir = File(context.filesDir, "inspector/crashes")
+        val files = crashDir.listFiles { f -> f.isFile && f.name.endsWith(".json") } ?: return emptyList()
+        return files.sortedByDescending { it.lastModified() }
+            .mapNotNull { runCatching { it.readText() }.getOrNull() }
+    }
+
+    private fun isoNow(): String {
+        val fmt = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US)
+        fmt.timeZone = TimeZone.getTimeZone("UTC")
+        return fmt.format(Date())
+    }
+}

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

@@ -0,0 +1,144 @@
+package __PACKAGE__.inspector
+
+// >>> cmp:feature room
+import __PACKAGE__.data.local.AppDatabase
+import androidx.room.useReaderConnection
+import kotlinx.coroutines.runBlocking
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import org.koin.core.context.GlobalContext
+// <<< cmp:feature room
+
+/**
+ * `GET /inspect/db` (schema: tables via `sqlite_master`) and `GET /inspect/db?table=<name>&limit=<n>`
+ * (rows). Read-only, off the main thread. 404 when this project's local-database feature is off
+ * (there is nothing to query) — see the `room`-gated implementation below for the real path.
+ */
+object DbInspector {
+
+    // >>> cmp:feature room
+    // Reads go through the project's Room database (a Koin single). Injection-safe by
+    // construction: a requested `table` is only ever used in a query after it is proven to be
+    // a real name returned by `sqlite_master` in THIS call — the raw wire value never reaches
+    // SQL beyond that validated identifier.
+    //
+    // This project's Room config uses the KMP driver architecture (BundledSQLiteDriver, see
+    // data/local/DatabaseBuilder.kt), not the legacy Android-only SupportSQLiteDatabase — so
+    // reads go through Room 2.8's public `useReaderConnection { transactor -> ... }` whose
+    // receiver is a pooled connection exposing `usePrepared(sql) { stmt -> ... }` (the
+    // statement is created and closed by Room; binds are 1-based, column reads 0-based).
+    private const val DEFAULT_ROW_LIMIT = 50
+    private const val MAX_ROW_LIMIT = 500
+    private val VALID_IDENTIFIER = Regex("^[A-Za-z_][A-Za-z0-9_]*$")
+    private val prettyJson = Json { prettyPrint = true }
+
+    private fun appDatabaseOrNull(): AppDatabase? =
+        try {
+            // GlobalContext.getOrNull() IS the Koin instance (or null before startKoin).
+            GlobalContext.getOrNull()?.getOrNull<AppDatabase>()
+        } catch (t: Throwable) {
+            null
+        }
+
+    fun schema(): Pair<Int, String> {
+        val db = appDatabaseOrNull()
+            ?: return 503 to errorJson("database not available yet (Room not initialised — is Koin started?).")
+        return try {
+            val tables = runBlocking {
+                db.useReaderConnection { connection ->
+                    connection.usePrepared(
+                        "SELECT name, sql FROM sqlite_master WHERE type = 'table' " +
+                            "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'room_%' ORDER BY name"
+                    ) { stmt ->
+                        val out = mutableListOf<Pair<String, String?>>()
+                        while (stmt.step()) {
+                            out += stmt.getText(0) to (if (stmt.isNull(1)) null else stmt.getText(1))
+                        }
+                        out
+                    }
+                }
+            }
+            200 to prettyJson.encodeToString(JsonElement.serializer(), buildJsonObject {
+                put("tables", buildJsonArray {
+                    tables.forEach { (name, sql) ->
+                        add(buildJsonObject {
+                            put("name", JsonPrimitive(name))
+                            put("sql", sql?.let { JsonPrimitive(it) } ?: JsonNull)
+                        })
+                    }
+                })
+            })
+        } catch (t: Throwable) {
+            500 to errorJson("failed to read schema: ${t.message}")
+        }
+    }
+
+    /** Row page for one table: columns + stringified values, capped. */
+    private class TableRows(val columns: List<String>, val rows: List<JsonElement>)
+
+    fun rows(table: String, limitParam: String?): Pair<Int, String> {
+        if (!VALID_IDENTIFIER.matches(table)) {
+            return 400 to errorJson("invalid table name '$table' — expected a plain SQL identifier.")
+        }
+        val db = appDatabaseOrNull()
+            ?: return 503 to errorJson("database not available yet (Room not initialised — is Koin started?).")
+        val limit = (limitParam?.toIntOrNull() ?: DEFAULT_ROW_LIMIT).coerceIn(1, MAX_ROW_LIMIT)
+        return try {
+            val result: TableRows? = runBlocking {
+                db.useReaderConnection { connection ->
+                    // STRICT validation: `table` is only used in the row query below once THIS
+                    // check proves it is a real sqlite_master identifier — never the raw wire value.
+                    val exists = connection.usePrepared(
+                        "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?"
+                    ) { stmt ->
+                        stmt.bindText(1, table)
+                        stmt.step()
+                    }
+                    if (!exists) return@useReaderConnection null
+
+                    connection.usePrepared("SELECT * FROM \"$table\" LIMIT ?") { stmt ->
+                        stmt.bindLong(1, limit.toLong())
+                        val colCount = stmt.getColumnCount()
+                        val columns = (0 until colCount).map { stmt.getColumnName(it) }
+                        val rows = mutableListOf<JsonElement>()
+                        while (stmt.step()) {
+                            rows += buildJsonObject {
+                                for (i in 0 until colCount) {
+                                    put(columns[i], if (stmt.isNull(i)) JsonNull else JsonPrimitive(stmt.getText(i)))
+                                }
+                            }
+                        }
+                        TableRows(columns, rows)
+                    }
+                }
+            }
+            if (result == null) {
+                return 404 to errorJson("unknown table '$table' — not present in sqlite_master.")
+            }
+            200 to prettyJson.encodeToString(JsonElement.serializer(), buildJsonObject {
+                put("table", JsonPrimitive(table))
+                put("columns", buildJsonArray { result.columns.forEach { add(JsonPrimitive(it)) } })
+                put("rows", buildJsonArray { result.rows.forEach { add(it) } })
+                put("rowCount", JsonPrimitive(result.rows.size))
+            })
+        } catch (t: Throwable) {
+            500 to errorJson("failed to read table '$table': ${t.message}")
+        }
+    }
+
+    private fun errorJson(message: String): String =
+        """{"error":${JsonPrimitive(message)}}"""
+    // <<< cmp:feature room
+    // >>> cmp:feature !room
+    private const val DISABLED_MESSAGE =
+        "the 'room' feature is disabled in this project — /inspect/db is unavailable."
+
+    fun schema(): Pair<Int, String> = 404 to """{"error":"$DISABLED_MESSAGE"}"""
+
+    fun rows(table: String, limitParam: String?): Pair<Int, String> = schema()
+    // <<< cmp:feature !room
+}

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,12 +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
@@ -14,6 +22,7 @@ import java.io.InputStreamReader
 import java.net.InetAddress
 import java.net.ServerSocket
 import java.net.Socket
+import java.net.URLDecoder
 import java.nio.charset.StandardCharsets
 import java.util.concurrent.CountDownLatch
 import java.util.concurrent.TimeUnit
@@ -43,6 +52,15 @@ import kotlin.math.roundToInt
  *                                  pair to the root view → {"tapped":true,"x":…,"y":…}.
  *   GET  /inspect/remote         → the self-contained remote-control HTML page (same-origin,
  *                                  zero CORS): live screenshot + click-to-tap in a browser.
+ *   GET  /inspect/nav            → { currentRoute, backStack } — best-effort, reported by the
+ *                                  common `NavInspectionHook` seam; empty snapshot before the
+ *                                  first navigation event (see [NavInspector]).
+ *   GET  /inspect/crashes        → { crashes: [...] } — persisted crash JSON (current boot +
+ *                                  previous ones), newest first (see [CrashRecorder]).
+ *   GET  /inspect/db             → schema: { tables:[{name,sql}] } via `sqlite_master`.
+ *   GET  /inspect/db?table=<n>&limit=<n> → rows for one table (read-only, bounded; see
+ *                                  [DbInspector]). 404 (or empty schema) when the project's
+ *                                  `room` feature is off.
  *
  * Single-threaded accept loop on a daemon thread = one client at a time = bounded by design.
  * Failure to bind logs a warning and gives up — the inspector must never crash or block
@@ -67,9 +85,14 @@ object InspectorHttpServer {
 
     @Volatile private var started = false
 
-    fun start(appId: String) {
+    // Set once in [start]; read from the HTTP thread only (crashes/db routes). applicationContext
+    // is safe to hold — it never leaks an Activity.
+    @Volatile private var appContext: Context? = null
+
+    fun start(appId: String, context: Context) {
         if (started) return
         started = true
+        appContext = context.applicationContext
         val thread = Thread({ serve(appId) }, "cmp-inspector-http")
         thread.isDaemon = true
         thread.start()
@@ -114,7 +137,9 @@ object InspectorHttpServer {
         }
         val parts = requestLine.split(" ")
         val method = parts.getOrNull(0) ?: ""
-        val path = (parts.getOrNull(1) ?: "").substringBefore('?')
+        val rawTarget = parts.getOrNull(1) ?: ""
+        val path = rawTarget.substringBefore('?')
+        val query = rawTarget.substringAfter('?', "")
 
         when {
             method == "GET" && path == "/inspect/health" ->
@@ -129,6 +154,17 @@ object InspectorHttpServer {
                 writeResponse(client, 200, RemoteControlPage.html(appId).toByteArray(StandardCharsets.UTF_8), HTML_TYPE)
             method == "POST" && path == "/inspect/tap" ->
                 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" ->
+                dbResponse(query).let { (s, b) -> writeJson(client, s, b) }
             method != "GET" && method != "POST" ->
                 writeJson(client, 405, errorJson("method not allowed"))
             else ->
@@ -153,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()
@@ -183,10 +246,62 @@ object InspectorHttpServer {
         }
     }
 
+    /** { currentRoute, backStack } from [NavInspector] — best-effort, never blocks. */
+    private fun navJson(): String {
+        val snapshot = NavInspector.current()
+        val currentRouteJson = snapshot.currentRoute?.let { JsonPrimitive(it).toString() } ?: "null"
+        val backStackJson = snapshot.backStack.joinToString(",") { JsonPrimitive(it).toString() }
+        return """{"currentRoute":$currentRouteJson,"backStack":[$backStackJson]}"""
+    }
+
+    /** { crashes:[...] } — each element is a persisted crash JSON document, verbatim. */
+    private fun crashesJson(): String {
+        val ctx = appContext ?: return """{"crashes":[]}"""
+        val crashes = CrashRecorder.readAll(ctx)
+        return """{"crashes":[${crashes.joinToString(",")}]}"""
+    }
+
+    /** GET /inspect/db dispatch: no `table` → schema, else → rows for that table. */
+    private fun dbResponse(query: String): Pair<Int, String> {
+        val params = parseQuery(query)
+        val table = params["table"]
+        return if (table == null) DbInspector.schema() else DbInspector.rows(table, params["limit"])
+    }
+
+    /** Minimal `a=b&c=d` query-string parser (URL-decoded values). Last value wins on repeats. */
+    private fun parseQuery(query: String): Map<String, String> {
+        if (query.isEmpty()) return emptyMap()
+        val out = mutableMapOf<String, String>()
+        for (pair in query.split("&")) {
+            if (pair.isEmpty()) continue
+            val eq = pair.indexOf('=')
+            val key = if (eq >= 0) pair.substring(0, eq) else pair
+            val value = if (eq >= 0) pair.substring(eq + 1) else ""
+            out[urlDecode(key)] = urlDecode(value)
+        }
+        return out
+    }
+
+    private fun urlDecode(s: String): String =
+        try {
+            URLDecoder.decode(s, "UTF-8")
+        } catch (t: Throwable) {
+            s
+        }
+
     /**
-     * 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()
@@ -200,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}")
             }
@@ -242,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/InspectorInit.kt

@@ -3,14 +3,18 @@ package __PACKAGE__.inspector
 import android.app.Application
 
 /**
- * DEBUG variant: install the Compose root registry (must happen BEFORE any Activity so the
- * `onViewCreatedCallback` hook catches every root), then start the loopback-only inspection
- * server on 127.0.0.1:9500. Reach it from the host via `adb forward tcp:9500 tcp:9500`.
+ * DEBUG variant: install the Compose root registry and the nav-inspection listener (both must
+ * happen BEFORE any Activity — the registry so `onViewCreatedCallback` catches every root, the
+ * nav listener so the first `AppNavHost` composition is observed), chain in the crash recorder,
+ * then start the loopback-only inspection server on 127.0.0.1:9500. Reach it from the host via
+ * `adb forward tcp:9500 tcp:9500`.
  *
  * The release source set carries a same-signature no-op twin — the compiler picks the variant
  * body, so release builds contain no inspector code at all (structural absence, not a flag).
  */
 fun Application.startInspector() {
     ComposeRootRegistry.install()
-    InspectorHttpServer.start(appId = packageName)
+    NavInspector.install()
+    CrashRecorder.install(this)
+    InspectorHttpServer.start(appId = packageName, context = this)
 }

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 {