create-cmp-cli 0.8.0 → 0.10.0

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

@@ -0,0 +1,62 @@
+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()
+
+    /**
+     * 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/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/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/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]. 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(
+    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,63 @@
+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.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
+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.
+ *
+ * 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.
+ * @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) {
+            AppIconButton(
+                icon = Icons.AutoMirrored.Filled.ArrowBack,
+                contentDescription = "Back",
+                onClick = onBack,
+                tint = MaterialTheme.colorScheme.onSurface,
+                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/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/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(