create-cmp-cli 0.7.1 → 0.9.0

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

@@ -1,5 +1,6 @@
 package __PACKAGE__.inspector
 
+import android.content.Context
 import android.graphics.Bitmap
 import android.graphics.Canvas
 import android.os.Handler
@@ -14,6 +15,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 +45,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 +78,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 +130,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 +147,12 @@ 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())
+            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 ->
@@ -183,6 +207,49 @@ 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

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/NavInspector.kt

@@ -0,0 +1,31 @@
+package __PACKAGE__.inspector
+
+import __PACKAGE__.presentation.navigation.NavInspectionHook
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Debug-only sink for [NavInspectionHook]: [install] registers a listener that stores the
+ * latest route/back-stack snapshot the common `AppNavHost` reports, so `GET /inspect/nav` can
+ * read it synchronously from the HTTP thread without touching Compose state directly.
+ *
+ * Best-effort by design: until the first navigation event fires (cold start, before
+ * `AppNavHost` has composed at least once), [current] reports an empty snapshot rather than
+ * blocking or erroring — mirrors the tree/screenshot routes' "not ready yet, retry" posture,
+ * just without the 503 (an empty nav snapshot is a valid, if uninteresting, answer).
+ */
+object NavInspector {
+
+    data class Snapshot(val currentRoute: String?, val backStack: List<String>)
+
+    private val EMPTY = Snapshot(currentRoute = null, backStack = emptyList())
+    private val state = AtomicReference(EMPTY)
+
+    /** Must run before the first Activity's setContent — same timing rule as [ComposeRootRegistry]. */
+    fun install() {
+        NavInspectionHook.listener = { current, backStack ->
+            state.set(Snapshot(current, backStack))
+        }
+    }
+
+    fun current(): Snapshot = state.get()
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/data/AppResultCatching.kt

@@ -0,0 +1,32 @@
+package __PACKAGE__.data
+
+import __PACKAGE__.domain.model.DomainError
+import __PACKAGE__.domain.result.AppResult
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * The data layer's ONLY exception-catching mechanism (`specs/app-base.spec.md` ARCH-08).
+ * Repository implementations wrap their I/O in this instead of writing `try`/`catch` —
+ * it is the single translation point where infrastructure exceptions become typed
+ * [DomainError] values, and it enforces the one non-negotiable rule of coroutine error
+ * handling:
+ *
+ * **`CancellationException` is ALWAYS rethrown, never mapped.** Swallowing it breaks
+ * structured concurrency — a cancelled screen would render an error state instead of
+ * simply stopping. The conformance gate scans for exactly this guard.
+ *
+ * [mapError] classifies everything else into your [DomainError] vocabulary; the default
+ * files anything unclassified under [DomainError.Unexpected] with the cause preserved
+ * for logging (never for display).
+ */
+suspend fun <T> suspendRunCatching(
+    mapError: (Throwable) -> DomainError = { DomainError.Unexpected(it) },
+    block: suspend () -> T,
+): AppResult<T> =
+    try {
+        AppResult.Success(block())
+    } catch (e: CancellationException) {
+        throw e // never mapped: cancellation is not a failure state
+    } catch (e: Throwable) {
+        AppResult.Failure(mapError(e))
+    }

package/template/composeApp/src/commonMain/kotlin/com/example/app/data/remote/ItemRepositoryImpl.kt

@@ -1,7 +1,9 @@
 package __PACKAGE__.data.remote
 
+import __PACKAGE__.data.suspendRunCatching
 import __PACKAGE__.domain.model.Item
 import __PACKAGE__.domain.repository.ItemRepository
+import __PACKAGE__.domain.result.AppResult
 import kotlinx.coroutines.delay
 
 // Example data source for the `home` feature. This is intentionally dependency-light
@@ -9,10 +11,15 @@ import kotlinx.coroutines.delay
 //
 // Real apps swap this for a Firestore/Ktor source and add a Room cache (see data/local).
 // The Clean Architecture seam is the ItemRepository interface in the domain layer.
+//
+// The repository is the ONLY exception-translation point: I/O runs inside
+// suspendRunCatching (data/AppResultCatching.kt), which maps infrastructure exceptions
+// to typed DomainError values and ALWAYS rethrows CancellationException. Pass a mapError
+// lambda to classify your real source's exceptions (IOException -> Network, etc).
 class ItemRepositoryImpl : ItemRepository {
-    override suspend fun getItems(): List<Item> {
+    override suspend fun getItems(): AppResult<List<Item>> = suspendRunCatching {
         delay(300) // simulate I/O
-        return listOf(
+        listOf(
             Item("1", "Welcome to __APP_NAME__", "Your Compose Multiplatform app is wired end-to-end."),
             Item("2", "Clean Architecture", "presentation → domain → data, with Koin DI."),
             Item("3", "Edge-to-edge, pre-solved", "BaseScreen owns the window insets for you."),

package/template/composeApp/src/commonMain/kotlin/com/example/app/domain/model/DomainError.kt

@@ -0,0 +1,21 @@
+package __PACKAGE__.domain.model
+
+/**
+ * The typed failure vocabulary of the domain layer — every failure a repository can report
+ * is one of these KINDS. No user-facing message strings live here: mapping a kind to copy
+ * is the presentation layer's job (see the exemplar ViewModel's `toUserMessage()`), so the
+ * domain stays translatable and UI-copy changes never touch this layer.
+ *
+ * Extend with the kinds YOUR sources can actually produce (e.g. `Unauthorized`, `Conflict`)
+ * — the data layer's `suspendRunCatching` mapper is the single place they are assigned.
+ */
+sealed interface DomainError {
+    /** The source was unreachable — connectivity, DNS, timeouts. */
+    data object Network : DomainError
+
+    /** The requested entity does not exist at the source. */
+    data object NotFound : DomainError
+
+    /** Anything not yet classified. Carries the cause for logging — never for display. */
+    data class Unexpected(val cause: Throwable? = null) : DomainError
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/domain/repository/ItemRepository.kt

@@ -1,8 +1,11 @@
 package __PACKAGE__.domain.repository
 
 import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.result.AppResult
 
 // Domain-facing contract. Presentation depends on THIS, never on a concrete data source.
+// One-shot operations return AppResult — they never throw (ARCH-06): failures cross the
+// boundary as typed DomainError values, translated inside the data implementation.
 interface ItemRepository {
-    suspend fun getItems(): List<Item>
+    suspend fun getItems(): AppResult<List<Item>>
 }

package/template/composeApp/src/commonMain/kotlin/com/example/app/domain/result/AppResult.kt

@@ -0,0 +1,23 @@
+package __PACKAGE__.domain.result
+
+import __PACKAGE__.domain.model.DomainError
+
+/**
+ * The typed result that crosses the data → domain → presentation boundary. One-shot
+ * repository operations return `AppResult<T>`, never throw (`specs/app-base.spec.md`
+ * ARCH-06) — so a ViewModel exhaustively `when`s over Success/Failure instead of
+ * catching exceptions (ARCH-07).
+ *
+ * Deliberately our own type rather than `kotlin.Result`: the stdlib Result carries an
+ * untyped Throwable, which would put raw exceptions right back on the boundary this
+ * type exists to keep them off. A [Failure] carries a typed [DomainError] kind instead
+ * (the same call Now in Android makes with its own Result).
+ *
+ * Cancellation is NOT a result: `CancellationException` propagates (structured
+ * concurrency), enforced at the single translation point — `suspendRunCatching` in
+ * `data/AppResultCatching.kt` (ARCH-08).
+ */
+sealed interface AppResult<out T> {
+    data class Success<out T>(val value: T) : AppResult<T>
+    data class Failure(val error: DomainError) : AppResult<Nothing>
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/domain/usecase/GetItemsUseCase.kt

@@ -2,11 +2,14 @@ package __PACKAGE__.domain.usecase
 
 import __PACKAGE__.domain.model.Item
 import __PACKAGE__.domain.repository.ItemRepository
+import __PACKAGE__.domain.result.AppResult
 
 // A use case is a single business action. ViewModels depend on use cases, not repositories
 // directly, so business rules stay testable and out of the presentation layer.
+// The typed result passes through untouched — a use case may combine or transform results,
+// but it never unwraps them into exceptions.
 class GetItemsUseCase(
     private val repository: ItemRepository,
 ) {
-    suspend operator fun invoke(): List<Item> = repository.getItems()
+    suspend operator fun invoke(): AppResult<List<Item>> = repository.getItems()
 }

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

@@ -0,0 +1,138 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.defaultMinSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.navigationBarsPadding
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Icon
+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.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.sp
+import __PACKAGE__.presentation.navigation.AppTab
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+import __PACKAGE__.presentation.theme.designToken
+
+/**
+ * The bottom tab bar: one item per tab, icon over label. Owns the 48 dp touch targets,
+ * the deterministic `nav_<slug>` testTags, token-bound colors, the navigation-bar inset
+ * padding, and the `BottomNavHeight` inspector self-report. Selection state stays with
+ * the caller; `AppShell` wires it.
+ *
+ * @param tabs Tabs in display order; each label also derives its item's `nav_*` testTag.
+ * @param selectedIndex Index of the selected tab in [tabs].
+ * @param onSelect Called with the index of the tapped tab.
+ */
+@Composable
+fun AppBottomBar(
+    tabs: List<AppTab>,
+    selectedIndex: Int,
+    onSelect: (Int) -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Column(modifier.fillMaxWidth()) {
+        Box(
+            Modifier
+                .fillMaxWidth()
+                .height(1.dp)
+                .background(__THEME_PREFIX__Colors.OutlineVariant)
+        )
+        Row(
+            modifier = Modifier
+                .fillMaxWidth()
+                .background(__THEME_PREFIX__Colors.Surface)
+                // Lift tabs above the gesture pill / 3-button nav (maps to iOS safe area).
+                .navigationBarsPadding()
+                .height(__THEME_PREFIX__Tokens.BottomNavHeight)
+                // Inspector: the bottom-nav container self-reports its height token.
+                .designToken(
+                    tokens = listOf("BottomNavHeight"),
+                    resolved = mapOf("height" to "${__THEME_PREFIX__Tokens.BottomNavHeight.value.toInt()}dp"),
+                )
+                .semantics { testTag = "app_bottom_nav" }
+                .padding(bottom = 8.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.SpaceEvenly,
+        ) {
+            tabs.forEachIndexed { index, tab ->
+                NavItem(
+                    label = tab.label,
+                    selected = selectedIndex == index,
+                    onClick = { onSelect(index) },
+                ) {
+                    Icon(
+                        imageVector = tab.icon,
+                        contentDescription = tab.label,
+                        tint = if (selectedIndex == index) __THEME_PREFIX__Colors.Primary
+                               else __THEME_PREFIX__Colors.OnSurfaceVariant.copy(alpha = 0.55f),
+                        modifier = Modifier.size(24.dp),
+                    )
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Deterministic automation tag for a nav item: `nav_` + the label lowercased with every
+ * non-[a-z0-9] run collapsed to `_` and trimmed (e.g. "My Stuff!" → `nav_my_stuff`).
+ * Must mirror `navSlug` in create-cmp's engine (src/lib/tabs.mjs), which generates
+ * `qa/e2e/smoke.yaml`'s id selectors from the configured tabs — keep the two in sync.
+ */
+private fun navItemTag(label: String): String =
+    "nav_" + label.lowercase().replace(Regex("[^a-z0-9]+"), "_").trim('_')
+
+/**
+ * A single tab item: icon over label, a 48 dp minimum touch target, tagged from its
+ * label via [navItemTag]. Internal (not private) so the component story
+ * (`component.nav-item`) can render it in isolation; absent from the public API surface.
+ *
+ * @param selected True renders the item in the selected treatment (primary color, bold label).
+ * @param icon Icon slot, rendered above the label.
+ */
+@Composable
+internal fun NavItem(
+    label: String,
+    selected: Boolean,
+    onClick: () -> Unit,
+    icon: @Composable () -> Unit,
+) {
+    Column(
+        modifier = Modifier
+            .clip(RoundedCornerShape(8.dp))
+            .clickable(onClick = onClick)
+            // a11y: guarantee the 48dp minimum touch target regardless of label width
+            // (the inspector's audit_a11y flags anything smaller).
+            .defaultMinSize(minWidth = 48.dp, minHeight = 48.dp)
+            // Durable selection handle (tests/E2E select by testTag, never display text).
+            .semantics { testTag = navItemTag(label) }
+            .padding(horizontal = 8.dp, vertical = 4.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center,
+    ) {
+        icon()
+        Text(
+            text = label,
+            fontSize = 10.sp,
+            fontWeight = if (selected) FontWeight.Bold else FontWeight.SemiBold,
+            color = if (selected) __THEME_PREFIX__Colors.Primary else __THEME_PREFIX__Colors.OnSurfaceVariant,
+            modifier = Modifier.padding(top = 4.dp),
+        )
+    }
+}

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

@@ -0,0 +1,56 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.sizeIn
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+
+/**
+ * The filled call-to-action button: M3 `Button` with a 48 dp minimum touch target
+ * applied. Stock M3 buttons sit below that floor by default; wrapping them here clears
+ * WCAG 2.2 SC 2.5.8 and the harness's `audit_a11y` bar once, for every call site.
+ */
+@Composable
+fun AppPrimaryButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+) {
+    Button(
+        onClick = onClick,
+        enabled = enabled,
+        modifier = modifier.sizeIn(minWidth = AppButtonDefaults.MinTouchTarget, minHeight = AppButtonDefaults.MinTouchTarget),
+    ) {
+        Text(text)
+    }
+}
+
+/**
+ * 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.
+ */
+@Composable
+fun AppTextButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+) {
+    TextButton(
+        onClick = onClick,
+        enabled = enabled,
+        modifier = modifier.sizeIn(minWidth = AppButtonDefaults.MinTouchTarget, minHeight = AppButtonDefaults.MinTouchTarget),
+    ) {
+        Text(text)
+    }
+}
+
+/** Shared button constants, following the `ComponentDefaults` naming convention. */
+object AppButtonDefaults {
+    val MinTouchTarget = 48.dp
+}

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

@@ -0,0 +1,54 @@
+package __PACKAGE__.presentation.components
+
+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.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.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.unit.dp
+
+/**
+ * The screen header: a headline row with an optional back affordance and a trailing
+ * actions slot, tagged `<screenTag>_title` and `<screenTag>_back`. Deliberately not an
+ * M3 `TopAppBar` — no scroll behaviors, no center-aligned variants, no window-inset
+ * handling (`BaseScreen` owns insets, SHELL-03). A collapsing toolbar would be a
+ * registry addition, not a default.
+ *
+ * @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.
+ * @param actions Trailing slot at the row's end, for per-screen controls.
+ */
+@Composable
+fun AppHeader(
+    title: String,
+    screenTag: String,
+    modifier: Modifier = Modifier,
+    onBack: (() -> Unit)? = null,
+    actions: @Composable RowScope.() -> Unit = {},
+) {
+    Row(
+        modifier = modifier.fillMaxWidth().padding(bottom = 12.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        if (onBack != null) {
+            AppTextButton(
+                text = "← Back",
+                onClick = onBack,
+                modifier = Modifier.semantics { testTag = "${screenTag}_back" },
+            )
+        }
+        Text(
+            text = title,
+            style = MaterialTheme.typography.headlineMedium,
+            modifier = Modifier.weight(1f).semantics { testTag = "${screenTag}_title" },
+        )
+        actions()
+    }
+}

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

@@ -15,15 +15,23 @@ import androidx.compose.ui.graphics.Color
 import __PACKAGE__.presentation.theme.designToken
 
 /**
- * The insets moat, pre-solved. Every screen wraps its content in [BaseScreen] instead of
- * re-deriving edge-to-edge padding. The Activity is edge-to-edge (transparent system bars);
- * this Scaffold owns the status-bar / navigation-bar insets in shared code, which also maps
- * to iOS safe areas under Compose Multiplatform.
+ * The edge-to-edge scaffold that owns system-bar insets in shared code. The Activity
+ * draws behind transparent system bars; this component applies status-bar and
+ * navigation-bar padding once (mapping to iOS safe areas under Compose Multiplatform),
+ * consumes what it applies to prevent doubled padding, and self-reports the applied
+ * inset facts to the inspector. Screens wrap their content in it instead of re-deriving
+ * insets.
  *
- * - [topBar] / [bottomBar] draw edge-to-edge (e.g. a nav bar that bleeds behind the gesture
- *   pill) and are responsible for their own inset padding.
- * - The content lambda receives padding already accounting for any bars; by default the body
- *   gets status + navigation bar padding so plain screens are safe with zero ceremony.
+ * @param containerColor Background color; `Color.Unspecified` resolves to the theme background.
+ * @param applyStatusBarPadding False lets the body draw under the status bar, for
+ *   full-bleed content that handles the top inset itself.
+ * @param applyNavBarPadding False lets the body draw under the navigation bar — set it
+ *   when a bottom bar owns that inset instead.
+ * @param topBar Draws edge-to-edge and is responsible for its own inset padding.
+ * @param bottomBar Draws edge-to-edge and is responsible for its own inset padding
+ *   (e.g. a nav bar that bleeds behind the gesture pill).
+ * @param content Screen body. Its padding is already applied by the wrapper; the
+ *   `PaddingValues` are passed through for callers that need the raw values.
  */
 @Composable
 fun BaseScreen(