create-cmp-cli 0.5.0 → 0.6.0

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewHarness.kt

@@ -0,0 +1,265 @@
+package __PACKAGE__.inspector
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.remember
+import androidx.compose.ui.ImageComposeScene
+import androidx.compose.ui.graphics.toArgb
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.onRoot
+import androidx.compose.ui.test.runDesktopComposeUiTest
+import androidx.compose.ui.unit.Density
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.LifecycleRegistry
+import androidx.lifecycle.ViewModelStore
+import androidx.lifecycle.ViewModelStoreOwner
+import androidx.lifecycle.compose.LocalLifecycleOwner
+import androidx.lifecycle.viewmodel.compose.LocalViewModelStoreOwner
+import __PACKAGE__.core.connectivity.NetworkMonitor
+// >>> cmp:feature room
+import __PACKAGE__.data.local.AppDatabase
+import __PACKAGE__.data.local.buildDatabase
+// <<< cmp:feature room
+import __PACKAGE__.di.appModules
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Theme
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import org.jetbrains.skia.EncodedImageFormat
+import org.koin.core.context.startKoin
+import org.koin.dsl.module
+import java.io.File
+import kotlin.system.exitProcess
+
+// Phone-shaped viewport, density 1 — px == dp in the dumped tree (matches the dev-client
+// window and keeps the inspector's a11y/touch-target math exact).
+internal const val WIDTH = 411
+internal const val HEIGHT = 891
+
+/**
+ * Headless preview harness — the project-wired tier-0 loop of the create-cmp inspector.
+ *
+ * Renders REAL screens from [previewRegistry] with no device, emulator, or window:
+ * for each screen it writes the inspector-contract semantics tree (`tree.json`, via
+ * `runDesktopComposeUiTest`) and a pixel preview (`screen.png`, via [ImageComposeScene])
+ * from the same composition sources at the same viewport, plus the declared design-system
+ * catalog (`design-system.json`) and a `manifest.json` for gallery tooling
+ * (qa/preview-gallery.mjs turns the output into a single self-contained index.html).
+ *
+ * Real DI, real theme, real data: Koin starts with the same modules as the app, and
+ * screens resolve their ViewModels through `koinViewModel()` exactly as in production.
+ *
+ * Invoked by the `:composeApp:renderScreens` Gradle task; parameters arrive as SYSTEM
+ * PROPERTIES (never `--args`, which Gradle's CLI parsing mangles):
+ *   -Pscreen=<id|all>   which registry entry to render        (default all)
+ *   -PpreviewOut=<dir>  output root                           (default build/previews)
+ *   -PpngScale=<n>      PNG density multiplier for sharpness  (default 2; tree stays density 1)
+ */
+fun main() {
+    val screenFilter = System.getProperty("screen")?.takeIf { it.isNotBlank() } ?: "all"
+    val outRoot = File(System.getProperty("out")?.takeIf { it.isNotBlank() } ?: "build/previews")
+    val pngScale = System.getProperty("pngScale")?.toFloatOrNull()?.takeIf { it > 0f } ?: 2f
+
+    initPreviewKoin()
+
+    val all = previewRegistry()
+    val selected = if (screenFilter == "all") all else all.filter { it.id == screenFilter }
+    if (selected.isEmpty()) {
+        System.err.println(
+            "Unknown screen '$screenFilter'. Available: ${all.joinToString(", ") { it.id }} (or 'all').",
+        )
+        exitProcess(2)
+    }
+
+    outRoot.mkdirs()
+    File(outRoot, "design-system.json").writeText(designSystemCatalog())
+
+    for (entry in selected) {
+        val dir = File(outRoot, entry.id).apply { mkdirs() }
+        renderTree(entry, File(dir, "tree.json"))
+        renderPng(entry, File(dir, "screen.png"), pngScale)
+        System.err.println("rendered ${entry.id} -> ${dir.absolutePath}")
+    }
+
+    File(outRoot, "manifest.json").writeText(manifestJson(selected, pngScale))
+    System.err.println("previews -> ${outRoot.absolutePath}")
+    // AWT/EDT and Koin threads are non-daemon; exit explicitly once outputs are on disk.
+    exitProcess(0)
+}
+
+/**
+ * Preview-harness DI — intentionally independent of the dev-client feature (which owns
+ * DesktopModule): the same platform bindings, started once for the render run.
+ */
+internal fun initPreviewKoin() {
+    startKoin {
+        modules(
+            module {
+                // >>> cmp:feature room
+                single<AppDatabase> { buildDatabase() }
+                // <<< cmp:feature room
+                single { NetworkMonitor(null) }
+            },
+            *appModules.toTypedArray(),
+        )
+    }
+}
+
+/**
+ * Provides what a bare offscreen composition lacks so production screens compose
+ * unmodified: a RESUMED [LifecycleOwner] (for `collectAsStateWithLifecycle`) and a fresh
+ * [ViewModelStoreOwner] per composition (so `koinViewModel()` resolves — and each render
+ * gets fresh ViewModels), then the app theme.
+ */
+@Composable
+internal fun PreviewRoot(content: @Composable () -> Unit) {
+    val owner = remember { PreviewOwner() }
+    CompositionLocalProvider(
+        LocalLifecycleOwner provides owner,
+        LocalViewModelStoreOwner provides owner,
+    ) {
+        __THEME_PREFIX__Theme(content)
+    }
+}
+
+internal class PreviewOwner : LifecycleOwner, ViewModelStoreOwner {
+    private val registry = LifecycleRegistry.createUnsafe(this).apply {
+        currentState = Lifecycle.State.RESUMED
+    }
+    override val lifecycle: Lifecycle get() = registry
+    override val viewModelStore = ViewModelStore()
+}
+
+/**
+ * Semantics tree at the phone viewport, density 1. ADAPTIVE settle: async data arrives in
+ * real time, so keep sampling until two consecutive dumps are identical (bounded) — static
+ * screens finish in ~300ms instead of paying the full window.
+ */
+@OptIn(ExperimentalTestApi::class)
+internal fun renderTree(entry: ScreenPreview, outFile: File) {
+    var json = ""
+    runDesktopComposeUiTest(width = WIDTH, height = HEIGHT) {
+        setContent { PreviewRoot { entry.content() } }
+        waitForIdle()
+        var prev: String? = null
+        var stable = 0
+        var iterations = 0
+        while (iterations < 8 && stable < 2) {
+            Thread.sleep(150)
+            waitForIdle()
+            val dump = PreviewSemanticsJson.dumpTree(onRoot(useUnmergedTree = true).fetchSemanticsNode())
+            if (dump == prev) stable++ else { stable = 0; prev = dump }
+            iterations++
+        }
+        json = prev ?: PreviewSemanticsJson.dumpTree(onRoot(useUnmergedTree = true).fetchSemanticsNode())
+    }
+    outFile.writeText(json)
+}
+
+/**
+ * Pixel twin of the tree: same content, same dp viewport, density [scale] for sharpness.
+ * Frames are re-rendered while invalidations arrive so async data reaches the pixels too.
+ */
+internal fun renderPng(entry: ScreenPreview, outFile: File, scale: Float) {
+    val scene = ImageComposeScene(
+        width = (WIDTH * scale).toInt(),
+        height = (HEIGHT * scale).toInt(),
+        density = Density(scale),
+    ) {
+        PreviewRoot { entry.content() }
+    }
+    try {
+        var elapsedNanos = 0L
+        var image = scene.render(elapsedNanos)
+        var quiet = 0
+        var iterations = 0
+        while (iterations < 12 && quiet < 2) {
+            Thread.sleep(100)
+            elapsedNanos += 100_000_000L
+            if (scene.hasInvalidations()) {
+                image = scene.render(elapsedNanos)
+                quiet = 0
+            } else {
+                quiet++
+            }
+            iterations++
+        }
+        val data = image.encodeToData(EncodedImageFormat.PNG)
+            ?: error("Skia failed to encode ${entry.id} as PNG")
+        outFile.writeBytes(data.bytes)
+    } finally {
+        scene.close()
+    }
+}
+
+/** The declared design-system catalog — generated FROM the theme objects, so it can't drift. */
+internal fun designSystemCatalog(): String {
+    val pretty = Json { prettyPrint = true }
+    fun hex(color: androidx.compose.ui.graphics.Color): JsonElement =
+        JsonPrimitive("#%06X".format(color.toArgb() and 0xFFFFFF))
+    fun dp(value: androidx.compose.ui.unit.Dp): JsonElement =
+        JsonPrimitive("${value.value.toInt()}dp")
+
+    val doc = buildJsonObject {
+        put("colors", buildJsonObject {
+            put("Primary", hex(__THEME_PREFIX__Colors.Primary))
+            put("OnPrimary", hex(__THEME_PREFIX__Colors.OnPrimary))
+            put("Accent", hex(__THEME_PREFIX__Colors.Accent))
+            put("OnAccent", hex(__THEME_PREFIX__Colors.OnAccent))
+            put("Secondary", hex(__THEME_PREFIX__Colors.Secondary))
+            put("Error", hex(__THEME_PREFIX__Colors.Error))
+            put("Success", hex(__THEME_PREFIX__Colors.Success))
+            put("Warning", hex(__THEME_PREFIX__Colors.Warning))
+            put("Info", hex(__THEME_PREFIX__Colors.Info))
+            put("Background", hex(__THEME_PREFIX__Colors.Background))
+            put("Surface", hex(__THEME_PREFIX__Colors.Surface))
+            put("SurfaceVariant", hex(__THEME_PREFIX__Colors.SurfaceVariant))
+            put("OnSurface", hex(__THEME_PREFIX__Colors.OnSurface))
+            put("OnSurfaceVariant", hex(__THEME_PREFIX__Colors.OnSurfaceVariant))
+            put("Outline", hex(__THEME_PREFIX__Colors.Outline))
+            put("OutlineVariant", hex(__THEME_PREFIX__Colors.OutlineVariant))
+            put("Divider", hex(__THEME_PREFIX__Colors.Divider))
+        })
+        put("dimens", buildJsonObject {
+            put("ElevationCard", dp(__THEME_PREFIX__Tokens.ElevationCard))
+            put("ElevationModal", dp(__THEME_PREFIX__Tokens.ElevationModal))
+            put("PaddingPage", dp(__THEME_PREFIX__Tokens.PaddingPage))
+            put("PaddingCard", dp(__THEME_PREFIX__Tokens.PaddingCard))
+            put("GapCard", dp(__THEME_PREFIX__Tokens.GapCard))
+            put("BottomNavHeight", dp(__THEME_PREFIX__Tokens.BottomNavHeight))
+            put("RadiusCard", dp(__THEME_PREFIX__Tokens.RadiusCard))
+            put("RadiusPill", dp(__THEME_PREFIX__Tokens.RadiusPill))
+            put("RadiusModal", dp(__THEME_PREFIX__Tokens.RadiusModal))
+            put("RadiusInput", dp(__THEME_PREFIX__Tokens.RadiusInput))
+        })
+    }
+    return pretty.encodeToString(JsonElement.serializer(), doc)
+}
+
+internal fun manifestJson(entries: List<ScreenPreview>, pngScale: Float): String {
+    val pretty = Json { prettyPrint = true }
+    val doc = buildJsonObject {
+        put("viewport", buildJsonObject {
+            put("width", JsonPrimitive(WIDTH))
+            put("height", JsonPrimitive(HEIGHT))
+            put("treeDensity", JsonPrimitive(1))
+            put("pngScale", JsonPrimitive(pngScale))
+        })
+        put("screens", buildJsonArray {
+            entries.forEach { entry ->
+                add(buildJsonObject {
+                    put("id", JsonPrimitive(entry.id))
+                    put("title", JsonPrimitive(entry.title))
+                    put("tree", JsonPrimitive("${entry.id}/tree.json"))
+                    put("png", JsonPrimitive("${entry.id}/screen.png"))
+                })
+            }
+        })
+    }
+    return pretty.encodeToString(JsonElement.serializer(), doc)
+}

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewRegistry.kt

@@ -0,0 +1,61 @@
+package __PACKAGE__.inspector
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import __PACKAGE__.presentation.components.BaseScreen
+import __PACKAGE__.presentation.home.DetailScreen
+import __PACKAGE__.presentation.home.HomeScreen
+import __PACKAGE__.presentation.navigation.AppShell
+import __PACKAGE__.presentation.navigation.appTabs
+import __PACKAGE__.presentation.profile.ProfileScreen
+
+/**
+ * One previewable screen: a stable [id] (the `-Pscreen=` selector and output directory
+ * name), a human [title] for the gallery, and the composable [content] exactly as the
+ * app hosts it.
+ *
+ * The `@Preview` analog for the create-cmp inspector: the registry makes "render screen
+ * X" a closed, enumerable operation. The scaffolder regenerates the tab entries from the
+ * configured `tabs`; when you add a screen by hand, add it here — the renderScreens
+ * harness, the gallery, and golden baselines pick it up by id.
+ *
+ * State variants (the Storybook "story" analog): a screen in a specific UI state is just
+ * another entry with a derived id — e.g. `ScreenPreview("home@empty", "Home — empty")`
+ * hosting the screen with that state forced (a state-first overload of the screen, or
+ * preview-only fakes behind its usual parameters). Every entry renders the same way
+ * (gallery card, `-Pscreen=` selector, golden baseline), so loading/empty/error states
+ * sit side by side with the default seeded state.
+ */
+data class ScreenPreview(
+    val id: String,
+    val title: String,
+    val content: @Composable () -> Unit,
+)
+
+/** Every registered screen, in gallery order. Ids must be unique and filesystem-safe. */
+fun previewRegistry(): List<ScreenPreview> = listOf(
+    ScreenPreview("shell", "App shell — bottom nav (first tab selected)") {
+        AppShell(
+            tabs = appTabs(
+                home = { HomeScreen(onItemClick = {}) },
+                profile = { ProfileScreen() },
+            ),
+        )
+    },
+    ScreenPreview("home", "Home tab") { TabHost { HomeScreen(onItemClick = {}) } },
+    ScreenPreview("profile", "Profile tab") { TabHost { ProfileScreen() } },
+    ScreenPreview("detail", "Detail (nav destination)") { DetailScreen(itemId = "1", onBack = {}) },
+)
+
+/**
+ * Hosts a single tab's content the way [AppShell] does — inside [BaseScreen] — minus the
+ * bottom bar, so a tab previews with the same insets/background it gets in the shell.
+ */
+@Composable
+private fun TabHost(content: @Composable () -> Unit) {
+    BaseScreen {
+        Box(Modifier.fillMaxSize()) { content() }
+    }
+}

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewSemanticsJson.kt

@@ -0,0 +1,83 @@
+package __PACKAGE__.inspector
+
+import androidx.compose.ui.semantics.SemanticsActions
+import androidx.compose.ui.semantics.SemanticsNode
+import androidx.compose.ui.semantics.SemanticsProperties
+import androidx.compose.ui.semantics.getOrNull
+import __PACKAGE__.presentation.theme.DesignTokenKey
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonArray
+import kotlinx.serialization.json.buildJsonObject
+import kotlin.math.roundToInt
+
+/**
+ * Walks a Compose [SemanticsNode] tree and serialises it to JSON matching the create-cmp
+ * inspector contract (schemaVersion 1, source "headless-jvm"). Every node carries pixel,
+ * root-relative `bounds` and a (possibly empty) `children` array; testTag / text /
+ * contentDescription / designToken are nullable; `role` / `clickable` / `disabled` are the
+ * additive interaction fields.
+ *
+ * This dumper reads THIS project's [DesignTokenKey], so the resolved design tokens the
+ * component kit self-reports (Modifier.designToken) appear in the dump — which is what
+ * makes the tree design-system-aware, not just geometry.
+ */
+object PreviewSemanticsJson {
+
+    private val prettyJson = Json { prettyPrint = true }
+
+    fun dumpTree(root: SemanticsNode): String {
+        val doc = buildJsonObject {
+            put("schemaVersion", JsonPrimitive(1))
+            put("source", JsonPrimitive("headless-jvm"))
+            put("root", nodeToJson(root))
+        }
+        return prettyJson.encodeToString(JsonElement.serializer(), doc)
+    }
+
+    private fun nodeToJson(node: SemanticsNode): JsonObject = buildJsonObject {
+        put("testTag", node.config.getOrNull(SemanticsProperties.TestTag).toJson())
+        put(
+            "text",
+            node.config.getOrNull(SemanticsProperties.Text)
+                ?.joinToString(" ") { it.text }?.takeIf { it.isNotEmpty() }.toJson(),
+        )
+        put(
+            "contentDescription",
+            node.config.getOrNull(SemanticsProperties.ContentDescription)
+                ?.joinToString(" ")?.takeIf { it.isNotEmpty() }.toJson(),
+        )
+        put("role", node.config.getOrNull(SemanticsProperties.Role)?.toString().toJson())
+        put("clickable", JsonPrimitive(node.config.contains(SemanticsActions.OnClick)))
+        put("disabled", JsonPrimitive(node.config.contains(SemanticsProperties.Disabled)))
+        put("bounds", node.boundsJson())
+        put("designToken", node.designTokenJson())
+        put("children", buildJsonArray { node.children.forEach { add(nodeToJson(it)) } })
+    }
+
+    private fun SemanticsNode.boundsJson(): JsonObject {
+        val rect = boundsInRoot
+        return buildJsonObject {
+            put("x", JsonPrimitive(rect.left.roundToInt()))
+            put("y", JsonPrimitive(rect.top.roundToInt()))
+            put("width", JsonPrimitive(rect.width.roundToInt()))
+            put("height", JsonPrimitive(rect.height.roundToInt()))
+        }
+    }
+
+    private fun SemanticsNode.designTokenJson(): JsonElement {
+        val info = config.getOrNull(DesignTokenKey) ?: return JsonNull
+        return buildJsonObject {
+            put("tokens", buildJsonArray { info.tokens.forEach { add(JsonPrimitive(it)) } })
+            put("resolved", buildJsonObject {
+                info.resolved.forEach { (k, v) -> put(k, JsonPrimitive(v)) }
+            })
+        }
+    }
+
+    private fun String?.toJson(): JsonElement =
+        if (this == null) JsonNull else JsonPrimitive(this)
+}

package/template/manifest.json

@@ -94,9 +94,11 @@
       "enabledByDefault": true,
       "paths": [
         "composeApp/src/androidDebug/kotlin/com/example/app/inspector",
-        "composeApp/src/androidRelease/kotlin/com/example/app/inspector"
+        "composeApp/src/androidRelease/kotlin/com/example/app/inspector",
+        "composeApp/src/desktopMain/kotlin/com/example/app/inspector",
+        "qa/preview-gallery.mjs"
       ],
-      "notes": "Live on-device inspector: debug-only loopback HTTP server on 127.0.0.1:9500 (GET /inspect/health|tree|design-system) serving the semantics tree + design-token catalog to the cmp-inspector MCP via `adb forward tcp:9500 tcp:9500`. The androidRelease dir holds only the no-op startInspector() twin — release builds contain no inspector code structurally. When off: delete both inspector dirs AND strip the `inspector` marker blocks in AppApplication.kt (import + startInspector() call) and composeApp/src/androidDebug/AndroidManifest.xml (INTERNET permission). Zero dependencies (java.net.ServerSocket + kotlinx-serialization from commonMain); no build-file markers needed."
+      "notes": "Two loops in one feature. (1) Live on-device inspector: debug-only loopback HTTP server on 127.0.0.1:9500 (GET /inspect/health|tree|design-system) serving the semantics tree + design-token catalog to the cmp-inspector MCP via `adb forward tcp:9500 tcp:9500`. The androidRelease dir holds only the no-op startInspector() twin — release builds contain no inspector code structurally. (2) Headless preview harness (tier 0): the desktopMain inspector dir (PreviewRegistry/PreviewHarness/PreviewSemanticsJson) + the :composeApp:renderScreens task render every registered screen to PNG + contract tree JSON with no device; qa/preview-gallery.mjs builds a self-contained index.html from the output (vendored pure-logic render libs live in qa/lib and stay when the feature is off — they are inert without the harness). The harness starts its OWN Koin (independent of the dev-client feature's DesktopModule) and its PreviewRegistry tab entries are regenerated from the configured `tabs` by the scaffolder (pipeline step b.3). When off: delete all three inspector dirs + qa/preview-gallery.mjs, strip the `inspector` marker blocks in AppApplication.kt (import + startInspector() call), composeApp/src/androidDebug/AndroidManifest.xml (INTERNET permission), and composeApp/build.gradle.kts (desktopMain compose.uiTest dep + the renderScreens task). On-device server: zero dependencies (java.net.ServerSocket + kotlinx-serialization from commonMain)."
     },
     "dev-client": {
       "enabledByDefault": true,

package/template/qa/lib/a11y.mjs

@@ -0,0 +1,104 @@
+// a11y.mjs — accessibility audit over the tree contract.
+// Pure logic only — no fs, no MCP imports; unit-testable.
+//
+// Rules (violations):
+//   touch-target-too-small — a clickable node whose width or height is below the
+//                            minimum touch target (default 48px; the harness dumps
+//                            at density 1 so px == dp there — pass a different
+//                            minTouchTargetPx for device-density trees).
+//   missing-label          — a clickable node with no text, no contentDescription,
+//                            and no descendant text: nothing for a screen reader.
+// Rules (warnings):
+//   empty-content-description — contentDescription === "" (redundant/empty; either
+//                               label it or drop the attribute).
+//
+// Trees produced before the role/clickable/disabled contract extension are handled
+// gracefully: nodes without `clickable` are simply skipped, never crashed on.
+
+import { walk } from "./tree.mjs";
+
+/**
+ * Audit a tree for accessibility faults.
+ *
+ * @param {object} tree  a full tree ({root}) or bare node.
+ * @param {{minTouchTargetPx?: number}} [opts]
+ * @returns {{
+ *   violations: Array<{path:string, testTag:string|null, rule:string, detail:string, bounds:object|null}>,
+ *   warnings:   Array<{path:string, testTag:string|null, rule:string, detail:string, bounds:object|null}>,
+ *   warningCount: number,
+ *   passCount: number
+ * }}  passCount = clickable nodes that passed every check.
+ */
+export function auditA11y(tree, opts = {}) {
+  const minTouchTargetPx =
+    typeof opts.minTouchTargetPx === "number" && opts.minTouchTargetPx > 0
+      ? opts.minTouchTargetPx
+      : 48;
+
+  const violations = [];
+  const warnings = [];
+  let passCount = 0;
+
+  for (const { node, path } of walk(tree)) {
+    const entryBase = {
+      path,
+      testTag: node.testTag ?? null,
+      bounds: node.bounds ?? null,
+    };
+
+    // Warn on redundant/empty contentDescription regardless of clickability.
+    if (node.contentDescription === "") {
+      warnings.push({
+        ...entryBase,
+        rule: "empty-content-description",
+        detail: 'contentDescription is an empty string ("") — either label the node or drop the attribute',
+      });
+    }
+
+    // Interactive checks only apply to nodes that self-report clickable:true.
+    // Old trees without the optional field are skipped gracefully.
+    if (node.clickable !== true) continue;
+
+    let violated = false;
+
+    const b = node.bounds;
+    if (
+      b &&
+      typeof b.width === "number" &&
+      typeof b.height === "number" &&
+      (b.width < minTouchTargetPx || b.height < minTouchTargetPx)
+    ) {
+      violations.push({
+        ...entryBase,
+        rule: "touch-target-too-small",
+        detail: `clickable node is ${b.width}x${b.height}px; minimum touch target is ${minTouchTargetPx}x${minTouchTargetPx}px`,
+      });
+      violated = true;
+    }
+
+    const hasOwnLabel =
+      (node.text != null && node.text !== "") ||
+      (node.contentDescription != null && node.contentDescription !== "");
+    if (!hasOwnLabel && !hasDescendantText(node)) {
+      violations.push({
+        ...entryBase,
+        rule: "missing-label",
+        detail: "clickable node has no text, no contentDescription, and no descendant text — invisible to screen readers",
+      });
+      violated = true;
+    }
+
+    if (!violated) passCount++;
+  }
+
+  return { violations, warnings, warningCount: warnings.length, passCount };
+}
+
+function hasDescendantText(node) {
+  for (const child of node.children || []) {
+    if (child.text != null && child.text !== "") return true;
+    if (child.contentDescription != null && child.contentDescription !== "") return true;
+    if (hasDescendantText(child)) return true;
+  }
+  return false;
+}