create-cmp-cli 0.4.0 → 0.6.0

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ArchitectureConformanceTest.kt

@@ -27,22 +27,47 @@ class ArchitectureConformanceTest {
     private fun imports(file: File): List<String> =
         file.readLines().filter { it.trimStart().startsWith("import ") }.map { it.trim() }
 
+    /**
+     * Source lines with comment lines stripped. Layer-boundary rules scan these for BOTH
+     * `import x.y.` statements AND fully-qualified inline references (`x.y.Type(...)`) —
+     * import-only matching leaves a one-edit evasion open: delete the import, qualify the
+     * name inline, and the gate goes green while the violation remains.
+     */
+    private fun nonCommentLines(file: File): List<String> =
+        file.readLines().filterNot {
+            val t = it.trimStart()
+            t.startsWith("//") || t.startsWith("*") || t.startsWith("/*")
+        }
+
+    private fun bannedReference(file: File, banned: List<String>): Boolean =
+        nonCommentLines(file).any { line -> banned.any { line.contains(it) } }
+
     private fun under(file: File, segment: String): Boolean =
         file.path.replace(File.separatorChar, '/').contains("/$segment/")
 
+    /**
+     * True when the file sits in a feature subpackage (presentation/<feature>/…) rather than
+     * at the presentation root (App.kt) — the scope for the composable-file rules.
+     */
+    private fun inPresentationFeatureDir(file: File): Boolean {
+        val rel = file.path.replace(File.separatorChar, '/').substringAfter("/presentation/", "")
+        return rel.isNotEmpty() && rel.contains('/')
+    }
+
     private fun violation(clause: String, rule: String, offenders: List<String>, fix: String): String =
         "[$clause] $rule\n  Offending: ${offenders.joinToString("\n             ")}\n  Fix: $fix"
 
     // SPEC: ARCH-01
     @Test
-    fun `ARCH-01 presentation never imports the data layer`() {
+    fun `ARCH-01 presentation never references the data layer`() {
         val offenders = sources(commonMain)
             .filter { under(it, "presentation") }
-            .filter { file -> imports(file).any { it.startsWith("import __PACKAGE__.data.") } }
+            .filter { bannedReference(it, listOf("__PACKAGE__.data.")) }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-01", "presentation depends on domain only — it never imports the data layer.",
+                "ARCH-01", "presentation depends on domain only — it never references the data layer " +
+                    "(neither imports nor fully-qualified inline names).",
                 offenders,
                 "depend on a domain interface (domain/repository) and let di/ wire the data implementation.",
             )
@@ -53,16 +78,17 @@ class ArchitectureConformanceTest {
     @Test
     fun `ARCH-02 domain is pure - no app layers, no frameworks`() {
         val banned = listOf(
-            "import __PACKAGE__.presentation.", "import __PACKAGE__.data.", "import __PACKAGE__.di.",
-            "import androidx.compose.", "import org.koin.",
+            "__PACKAGE__.presentation.", "__PACKAGE__.data.", "__PACKAGE__.di.",
+            "androidx.compose.", "org.koin.",
         )
         val offenders = sources(commonMain)
             .filter { under(it, "domain") }
-            .filter { file -> imports(file).any { imp -> banned.any { imp.startsWith(it) } } }
+            .filter { bannedReference(it, banned) }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-02", "domain imports nothing app-internal and no UI/DI frameworks.",
+                "ARCH-02", "domain references nothing app-internal and no UI/DI frameworks " +
+                    "(neither imports nor fully-qualified inline names).",
                 offenders,
                 "move framework-touching code out to presentation/data; domain stays pure Kotlin.",
             )
@@ -88,17 +114,23 @@ class ArchitectureConformanceTest {
 
     // SPEC: ARCH-04
     @Test
-    fun `ARCH-04 every Screen composable declares a testTag`() {
+    fun `ARCH-04 every feature composable file declares a testTag`() {
+        // Scoped by CONTENT (contains @Composable), not by *Screen.kt filename: real apps
+        // split features into Screen.kt (often ViewModel-only) and Content.kt (the UI).
+        // Filename scoping produced both false negatives (untagged FooContent.kt slid
+        // through) and false positives (VM-only FooScreen.kt was flagged) in the field.
         val offenders = sources(commonMain)
-            .filter { it.name != "Screen.kt" && it.name.endsWith("Screen.kt") }
-            .filterNot { under(it, "components") || under(it, "navigation") }
+            .filter { inPresentationFeatureDir(it) }
+            .filterNot { under(it, "components") || under(it, "navigation") || under(it, "theme") }
+            .filter { it.readText().contains("@Composable") }
             .filterNot { it.readText().contains("testTag") }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-04", "every screen is automation-reachable: *Screen files declare at least one testTag.",
+                "ARCH-04", "every feature UI file is automation-reachable: files containing a " +
+                    "@Composable declare at least one testTag.",
                 offenders,
-                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the screen's key nodes.",
+                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the file's key nodes.",
             )
         )
     }
@@ -120,6 +152,45 @@ class ArchitectureConformanceTest {
         )
     }
 
+    // SPEC: SHELL-05
+    @Test
+    fun `SHELL-05 every non-shell nav destination wraps its content in BaseScreen`() {
+        // SHELL-03 bans direct inset-API calls, but a destination that simply never handles
+        // insets at all (bare Column at the nav layer) passes that rule while rendering
+        // under the status bar. Tab screens are exempt — AppShell wraps them — so the rule
+        // targets exactly the destinations registered directly on the NavHost.
+        val navHost = sources(commonMain).firstOrNull { it.name == "AppNavHost.kt" } ?: return
+        val text = navHost.readText()
+        val screenCall = Regex("""([A-Z][A-Za-z0-9]*Screen)\s*\(""")
+        // A call with only a trailing lambda has no paren — `BaseScreen { … }` — so match both.
+        val baseScreenCall = Regex("""BaseScreen\s*[({]""")
+        val allSources = sources(commonMain)
+
+        val offenders = mutableListOf<String>()
+        val chunks = text.split("composable(").drop(1)
+        for (chunk in chunks) {
+            if (chunk.contains("AppShell(")) continue // shell destination: tabs inherit BaseScreen
+            for (m in screenCall.findAll(chunk)) {
+                val name = m.groupValues[1]
+                if (name == "BaseScreen") continue
+                val defining = allSources.firstOrNull { f ->
+                    Regex("""fun\s+$name\s*\(""").containsMatchIn(f.readText())
+                } ?: continue
+                if (!baseScreenCall.containsMatchIn(defining.readText())) {
+                    offenders.add("${defining.path} ($name is a NavHost destination without BaseScreen)")
+                }
+            }
+        }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "SHELL-05", "every screen registered directly on the NavHost composes inside " +
+                    "BaseScreen — otherwise it renders edge-to-edge with no inset handling.",
+                offenders.distinct(),
+                "wrap the destination's content in BaseScreen { … } (see DetailScreen).",
+            )
+        )
+    }
+
     // SPEC: SHELL-03
     @Test
     fun `SHELL-03 insets are owned by BaseScreen - screens never touch inset APIs`() {

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;
+}

package/template/qa/lib/render.mjs

@@ -0,0 +1,254 @@
+// render.mjs — deterministic SVG wireframe of a CMP inspector tree.
+//
+// The "structural twin" of a pixel preview: every node with a non-zero visual
+// footprint becomes a rect; token-annotated nodes are visually distinct and carry
+// a small chip with their resolved values ("radius 16 · pad 16"); clickable nodes
+// get a distinct outline; testTags render as small mono labels; text nodes show
+// their text. An optional a11y audit result overlays violations in a danger style.
+//
+// SVG is structured TEXT, not pixels — safe for model context, works for ANY
+// source (file / live / uiautomator). Output is fully deterministic: no dates,
+// no randomness; the same tree + opts always yields byte-identical SVG.
+//
+// Pure logic only — no fs, no MCP imports; the server wires file I/O around it.
+
+import { walk } from "./tree.mjs";
+
+const FIT_WIDTH = 740; // target drawing width when no explicit scale is given
+const MARGIN = 16;
+const LEGEND_H = 30;
+const FOOTER_H = 24;
+
+const STYLE = {
+  plain: { fill: "none", stroke: "#9CA3AF", strokeWidth: 1, dash: null },
+  tokenized: { fill: "rgba(0,185,107,0.10)", stroke: "#00B96B", strokeWidth: 1.5, dash: null },
+  clickableStroke: "#2563EB",
+  dangerStroke: "#DC2626",
+  chipFill: "#0A2540",
+  chipText: "#FFFFFF",
+  tagText: "#6B7280",
+  nodeText: "#1A1A1A",
+  footerText: "#6B7280",
+};
+
+/**
+ * Render a tree (full {root} document or bare node) as an SVG wireframe string.
+ *
+ * @param {object} tree
+ * @param {object} [opts]
+ * @param {object} [opts.a11y]     an auditA11y() result — its violations are overlaid
+ *                                 in the danger style (matched to nodes by path).
+ * @param {number} [opts.maxDepth] only draw nodes up to this depth (root = 0).
+ * @param {number} [opts.scale]    explicit px scale; default fits root width to ~740.
+ * @returns {string} the SVG document.
+ */
+export function renderTreeSvg(tree, opts = {}) {
+  const root = tree && tree.root ? tree.root : tree;
+  if (!root || typeof root !== "object") {
+    throw new Error("renderTreeSvg: tree has no root node.");
+  }
+  const schemaVersion = (tree && tree.schemaVersion) ?? 1;
+  const source = (tree && tree.source) ?? "unknown";
+
+  const rootW = boundsDim(root.bounds, "width") || 360;
+  const rootH = boundsDim(root.bounds, "height") || 640;
+  const scale = typeof opts.scale === "number" && opts.scale > 0 ? opts.scale : FIT_WIDTH / rootW;
+  const maxDepth =
+    typeof opts.maxDepth === "number" && opts.maxDepth >= 0 ? opts.maxDepth : Infinity;
+
+  // Violations by node path (danger overlay).
+  const violationsByPath = new Map();
+  if (opts.a11y && Array.isArray(opts.a11y.violations)) {
+    for (const v of opts.a11y.violations) {
+      if (!violationsByPath.has(v.path)) violationsByPath.set(v.path, []);
+      violationsByPath.get(v.path).push(v.rule);
+    }
+  }
+
+  const drawW = rootW * scale;
+  const drawH = rootH * scale;
+  const svgW = Math.ceil(drawW + MARGIN * 2);
+  const svgH = Math.ceil(LEGEND_H + drawH + FOOTER_H + MARGIN * 2);
+  const originX = MARGIN;
+  const originY = LEGEND_H + MARGIN / 2;
+
+  let nodeCount = 0;
+  const body = [];
+
+  for (const { node, path } of walk(root)) {
+    nodeCount++;
+    if (depthOf(path) > maxDepth) continue;
+    const b = node.bounds;
+    const w = boundsDim(b, "width");
+    const h = boundsDim(b, "height");
+    if (!(w > 0 && h > 0)) continue; // zero-footprint nodes have nothing to draw
+
+    const x = originX + (b.x || 0) * scale;
+    const y = originY + (b.y || 0) * scale;
+    const sw = w * scale;
+    const sh = h * scale;
+    const tokenized = node.designToken != null;
+    const clickable = node.clickable === true;
+    const rules = violationsByPath.get(path);
+
+    const base = tokenized ? STYLE.tokenized : STYLE.plain;
+    body.push(
+      `<rect x="${fmt(x)}" y="${fmt(y)}" width="${fmt(sw)}" height="${fmt(sh)}" ` +
+        `fill="${base.fill}" stroke="${base.stroke}" stroke-width="${base.strokeWidth}"` +
+        `${tokenized ? ` class="tokenized"` : ""} data-path="${esc(path)}"/>`
+    );
+    if (clickable) {
+      // Distinct clickable outline, drawn just inside the node rect.
+      body.push(
+        `<rect x="${fmt(x + 1.5)}" y="${fmt(y + 1.5)}" width="${fmt(Math.max(sw - 3, 1))}" ` +
+          `height="${fmt(Math.max(sh - 3, 1))}" fill="none" stroke="${STYLE.clickableStroke}" ` +
+          `stroke-width="2" stroke-dasharray="5 3" class="clickable"/>`
+      );
+    }
+    if (rules && rules.length > 0) {
+      // Danger overlay + rule label for a11y violations.
+      body.push(
+        `<rect x="${fmt(x - 2)}" y="${fmt(y - 2)}" width="${fmt(sw + 4)}" height="${fmt(sh + 4)}" ` +
+          `fill="rgba(220,38,38,0.08)" stroke="${STYLE.dangerStroke}" stroke-width="2" class="a11y-violation"/>`
+      );
+      body.push(
+        `<text x="${fmt(x)}" y="${fmt(y - 4)}" font-family="monospace" font-size="8" ` +
+          `fill="${STYLE.dangerStroke}" class="a11y-label">! ${esc([...rules].sort().join(", "))}</text>`
+      );
+    }
+    if (node.testTag) {
+      body.push(
+        `<text x="${fmt(x + 3)}" y="${fmt(y + 9)}" font-family="monospace" font-size="8" ` +
+          `fill="${STYLE.tagText}" class="test-tag">${esc(node.testTag)}</text>`
+      );
+    }
+    if (node.text) {
+      body.push(
+        `<text x="${fmt(x + 3)}" y="${fmt(y + sh / 2 + 3)}" font-family="sans-serif" font-size="10" ` +
+          `fill="${STYLE.nodeText}" class="node-text">${esc(truncate(node.text, 48))}</text>`
+      );
+    }
+    if (tokenized) {
+      const chip = tokenChip(node.designToken);
+      if (chip) {
+        const chipW = chip.length * 4.6 + 8;
+        const chipY = y + sh - 12;
+        body.push(
+          `<rect x="${fmt(x + 2)}" y="${fmt(chipY)}" width="${fmt(chipW)}" height="11" rx="5" ` +
+            `fill="${STYLE.chipFill}" opacity="0.85" class="token-chip"/>`
+        );
+        body.push(
+          `<text x="${fmt(x + 6)}" y="${fmt(chipY + 8.5)}" font-family="monospace" font-size="7.5" ` +
+            `fill="${STYLE.chipText}" class="token-chip-text">${esc(chip)}</text>`
+        );
+      }
+    }
+  }
+
+  const legend = legendRow(opts.a11y != null);
+  const footer =
+    `<text x="${MARGIN}" y="${svgH - 8}" font-family="monospace" font-size="10" ` +
+    `fill="${STYLE.footerText}" class="footer">${nodeCount} nodes · ${esc(source)} · schemaVersion ${schemaVersion}</text>`;
+
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${svgW}" height="${svgH}" viewBox="0 0 ${svgW} ${svgH}">`,
+    `<rect x="0" y="0" width="${svgW}" height="${svgH}" fill="#F7F9FC"/>`,
+    legend,
+    ...body,
+    footer,
+    `</svg>`,
+    ``,
+  ].join("\n");
+}
+
+// --- helpers ----------------------------------------------------------------
+
+// Legend row across the top: what each visual style means.
+function legendRow(withA11y) {
+  const items = [];
+  let x = MARGIN;
+  const y = 8;
+  const swatch = (fill, stroke, dash, label, cls) => {
+    const parts = [
+      `<rect x="${fmt(x)}" y="${y}" width="14" height="10" fill="${fill}" stroke="${stroke}" ` +
+        `stroke-width="1.5"${dash ? ` stroke-dasharray="${dash}"` : ""} class="legend-${cls}"/>`,
+      `<text x="${fmt(x + 18)}" y="${y + 9}" font-family="sans-serif" font-size="9" fill="#1A1A1A">${label}</text>`,
+    ];
+    x += 18 + label.length * 5.2 + 14;
+    items.push(...parts);
+  };
+  swatch("none", STYLE.plain.stroke, null, "node", "node");
+  swatch(STYLE.tokenized.fill, STYLE.tokenized.stroke, null, "tokenized", "tokenized");
+  swatch("none", STYLE.clickableStroke, "5 3", "clickable", "clickable");
+  if (withA11y) swatch("rgba(220,38,38,0.08)", STYLE.dangerStroke, null, "a11y violation", "a11y");
+  return `<g class="legend">${items.join("")}</g>`;
+}
+
+// "radius 16 · pad 16" — compact resolved-values chip, sorted keys for determinism.
+function tokenChip(dt) {
+  if (!dt || !dt.resolved || typeof dt.resolved !== "object") return null;
+  const keys = Object.keys(dt.resolved).sort();
+  if (keys.length === 0) return null;
+  const parts = keys.map((k) => {
+    const v = String(dt.resolved[k]).replace(/(dp|sp)$/i, "");
+    return `${abbrev(k)} ${v}`.trim();
+  });
+  return truncate(parts.join(" · "), 64);
+}
+
+const ABBREV = {
+  padding: "pad",
+  elevation: "elev",
+  fontSize: "font",
+  height: "h",
+  width: "w",
+  statusBarPadding: "statusBar",
+  navBarPadding: "navBar",
+};
+function abbrev(key) {
+  return ABBREV[key] ?? key;
+}
+
+function depthOf(path) {
+  return (path.match(/\.children\[/g) || []).length;
+}
+
+function boundsDim(b, key) {
+  return b && typeof b[key] === "number" ? b[key] : 0;
+}
+
+function fmt(n) {
+  // Fixed one-decimal formatting: deterministic and diff-friendly.
+  return (Math.round(n * 10) / 10).toString();
+}
+
+function truncate(s, max) {
+  const str = String(s);
+  return str.length <= max ? str : str.slice(0, max - 1) + "…";
+}
+
+function esc(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Count the nodes renderTreeSvg would draw as rects (non-zero footprint within
+ * maxDepth) plus the total node count — used by the tool result.
+ */
+export function countRenderable(tree, opts = {}) {
+  const root = tree && tree.root ? tree.root : tree;
+  const maxDepth =
+    typeof opts.maxDepth === "number" && opts.maxDepth >= 0 ? opts.maxDepth : Infinity;
+  let total = 0;
+  let drawn = 0;
+  for (const { node, path } of walk(root)) {
+    total++;
+    if (depthOf(path) > maxDepth) continue;
+    if (boundsDim(node.bounds, "width") > 0 && boundsDim(node.bounds, "height") > 0) drawn++;
+  }
+  return { total, drawn };
+}

package/template/qa/lib/tree.mjs

@@ -0,0 +1,108 @@
+// tree.mjs — pure helpers for loading and walking a CMP inspector tree.
+// No MCP imports here: everything is unit-testable in isolation.
+//
+// The JSON tree contract (schemaVersion 1):
+//   { schemaVersion, source, root: <Node> }
+//   Node = { testTag, text, contentDescription, bounds:{x,y,width,height},
+//            designToken: { tokens:string[], resolved:{[k]:string} } | null,
+//            children: Node[] }
+//
+// Additive optional fields (still schemaVersion 1 — absent on old trees, so every
+// consumer must treat them as optional):
+//   role:      string|null  — semantics Role (e.g. "Button", "Checkbox")
+//   clickable: boolean      — presence of the OnClick semantics action
+//   disabled:  boolean      — presence of the Disabled semantics property
+
+import { readFileSync } from "node:fs";
+
+/**
+ * Load a tree from a filesystem path, a JSON string, or an already-parsed object.
+ * Validates the minimal shape (schemaVersion + root) and throws a clear,
+ * caller-facing Error (never a raw fs/JSON stack) on failure.
+ *
+ * @param {string|object} pathOrObj
+ * @returns {object} the parsed tree ({ schemaVersion, source, root })
+ */
+export function loadTree(pathOrObj) {
+  if (pathOrObj == null) {
+    throw new Error("loadTree: no tree provided (path or object is null/undefined).");
+  }
+
+  let tree;
+  if (typeof pathOrObj === "object") {
+    tree = pathOrObj;
+  } else if (typeof pathOrObj === "string") {
+    const raw = readOrParse(pathOrObj);
+    tree = raw;
+  } else {
+    throw new Error(`loadTree: unsupported input type '${typeof pathOrObj}'.`);
+  }
+
+  if (!tree || typeof tree !== "object") {
+    throw new Error("loadTree: tree is not an object.");
+  }
+  if (!tree.root || typeof tree.root !== "object") {
+    throw new Error("loadTree: tree has no 'root' node (expected { schemaVersion, source, root }).");
+  }
+  return tree;
+}
+
+// If the string looks like a JSON document, parse it directly; otherwise treat
+// it as a filesystem path and read+parse. This lets callers pass either.
+function readOrParse(str) {
+  const trimmed = str.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch (err) {
+      throw new Error(`loadTree: input looked like JSON but failed to parse: ${err.message}`);
+    }
+  }
+  let contents;
+  try {
+    contents = readFileSync(str, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new Error(`loadTree: tree file not found: ${str}`);
+    }
+    throw new Error(`loadTree: could not read tree file '${str}': ${err.message}`);
+  }
+  try {
+    return JSON.parse(contents);
+  } catch (err) {
+    throw new Error(`loadTree: tree file '${str}' is not valid JSON: ${err.message}`);
+  }
+}
+
+/**
+ * Depth-first walk yielding every node with a stable, dotted path.
+ * Root's path is "root"; children are "root.children[0]", etc.
+ *
+ * @param {object} tree  a full tree ({root}) OR a bare node.
+ * @yields {{ node: object, path: string }}
+ */
+export function* walk(tree) {
+  const root = tree && tree.root ? tree.root : tree;
+  if (!root || typeof root !== "object") return;
+  yield* walkNode(root, "root");
+}
+
+function* walkNode(node, path) {
+  yield { node, path };
+  const children = Array.isArray(node.children) ? node.children : [];
+  for (let i = 0; i < children.length; i++) {
+    yield* walkNode(children[i], `${path}.children[${i}]`);
+  }
+}
+
+/**
+ * Find the first node with the given testTag. Returns { node, path } or null.
+ * @param {object} tree
+ * @param {string} tag
+ */
+export function findByTestTag(tree, tag) {
+  for (const entry of walk(tree)) {
+    if (entry.node.testTag === tag) return entry;
+  }
+  return null;
+}